[SILO-713] feat: add Agent Runs API and related models, activities, and tests (#22)

Author: Saurabhkmr98

env.example

@@ -8,6 +8,9 @@ PLANE_BASE_URL=your-plane-base-url
 # Workspace configuration
 TEST_WORKSPACE_SLUG=your-workspace-slug
 
+# Agent configuration
+TEST_AGENT_SLUG=your-installed-agent-slug
+
 # Project and user IDs
 TEST_PROJECT_ID=your-project-id
 TEST_USER_ID=your-user-id
@@ -22,3 +25,6 @@ TEST_WORK_ITEM_TYPE_ID=your-work-item-type-id
 
 # Custom property IDs
 TEST_CUSTOM_TEXT_PROPERTY_ID=your-custom-text-property-id
+
+# Agent configuration
+TEST_AGENT_SLUG=your-agent-slug

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makeplane/plane-node-sdk",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Node SDK for Plane",
   "author": "Plane <[email protected]>",
   "repository": {

src/api/AgentRuns/Activities.ts

@@ -0,0 +1,55 @@
+import { BaseResource } from "../BaseResource";
+import { Configuration } from "../../Configuration";
+import { AgentRunActivity, CreateAgentRunActivityRequest } from "../../models/AgentRun";
+import { PaginatedResponse } from "../../models/common";
+
+/**
+ * Agent Run Activities API resource
+ * Handles all agent run activity operations
+ */
+export class Activities extends BaseResource {
+  constructor(config: Configuration) {
+    super(config);
+  }
+
+  /**
+   * List activities for an agent run
+   * @param workspaceSlug - The workspace slug
+   * @param runId - The agent run ID
+   * @param params - Optional query parameters for pagination
+   * @returns Paginated list of agent run activities
+   */
+  async list(
+    workspaceSlug: string,
+    runId: string,
+    params?: { per_page?: number; cursor?: string }
+  ): Promise<PaginatedResponse<AgentRunActivity>> {
+    return this.get<PaginatedResponse<AgentRunActivity>>(
+      `/workspaces/${workspaceSlug}/runs/${runId}/activities/`,
+      params
+    );
+  }
+
+  /**
+   * Retrieve a specific agent run activity by ID
+   * @param workspaceSlug - The workspace slug
+   * @param runId - The agent run ID
+   * @param activityId - The activity ID
+   * @returns The agent run activity
+   */
+  async retrieve(workspaceSlug: string, runId: string, activityId: string): Promise<AgentRunActivity> {
+    return this.get<AgentRunActivity>(`/workspaces/${workspaceSlug}/runs/${runId}/activities/${activityId}/`);
+  }
+
+  /**
+   * Create a new agent run activity
+   * @param workspaceSlug - The workspace slug
+   * @param runId - The agent run ID
+   * @param data - The activity data to create
+   * @returns The created agent run activity
+   */
+  async create(workspaceSlug: string, runId: string, data: CreateAgentRunActivityRequest): Promise<AgentRunActivity> {
+    return this.post<AgentRunActivity>(`/workspaces/${workspaceSlug}/runs/${runId}/activities/`, data);
+  }
+}
+

src/api/AgentRuns/index.ts

@@ -0,0 +1,38 @@
+import { BaseResource } from "../BaseResource";
+import { Configuration } from "../../Configuration";
+import { AgentRun, CreateAgentRunRequest } from "../../models/AgentRun";
+import { Activities } from "./Activities";
+
+/**
+ * Agent Runs API resource
+ * Handles all agent run operations
+ */
+export class AgentRuns extends BaseResource {
+  public activities: Activities;
+
+  constructor(config: Configuration) {
+    super(config);
+    this.activities = new Activities(config);
+  }
+
+  /**
+   * Create a new agent run
+   * @param workspaceSlug - The workspace slug
+   * @param data - The agent run data to create
+   * @returns The created agent run
+   */
+  async create(workspaceSlug: string, data: CreateAgentRunRequest): Promise<AgentRun> {
+    return this.post<AgentRun>(`/workspaces/${workspaceSlug}/runs/`, data);
+  }
+
+  /**
+   * Retrieve an agent run by ID
+   * @param workspaceSlug - The workspace slug
+   * @param runId - The agent run ID
+   * @returns The agent run
+   */
+  async retrieve(workspaceSlug: string, runId: string): Promise<AgentRun> {
+    return this.get<AgentRun>(`/workspaces/${workspaceSlug}/runs/${runId}/`);
+  }
+}
+

src/client/plane-client.ts

@@ -18,6 +18,7 @@ import { Intake } from "../api/Intake";
 import { Stickies } from "../api/Stickies";
 import { Teamspaces } from "../api/Teamspaces";
 import { Initiatives } from "../api/Initiatives";
+import { AgentRuns } from "../api/AgentRuns";
 
 /**
  * Main Plane Client class
@@ -44,6 +45,7 @@ export class PlaneClient {
   public stickies: Stickies;
   public teamspaces: Teamspaces;
   public initiatives: Initiatives;
+  public agentRuns: AgentRuns;
 
   constructor(config: { baseUrl?: string; apiKey?: string; accessToken?: string; enableLogging?: boolean }) {
     this.config = new Configuration({
@@ -76,5 +78,6 @@ export class PlaneClient {
     this.stickies = new Stickies(this.config);
     this.teamspaces = new Teamspaces(this.config);
     this.initiatives = new Initiatives(this.config);
+    this.agentRuns = new AgentRuns(this.config);
   }
 }

src/index.ts

@@ -27,6 +27,7 @@ export { Intake } from "./api/Intake";
 export { Stickies } from "./api/Stickies";
 export { Teamspaces } from "./api/Teamspaces";
 export { Initiatives } from "./api/Initiatives";
+export { AgentRuns } from "./api/AgentRuns";
 
 // Sub-resources
 export { Relations as WorkItemRelations } from "./api/WorkItems/Relations";
@@ -43,6 +44,7 @@ export { Members as TeamspaceMembers } from "./api/Teamspaces/Members";
 export { Labels as InitiativeLabels } from "./api/Initiatives/Labels";
 export { Projects as InitiativeProjects } from "./api/Initiatives/Projects";
 export { Epics as InitiativeEpics } from "./api/Initiatives/Epics";
+export { Activities as AgentRunActivities } from "./api/AgentRuns/Activities";
 
 // Models
 export * from "./models";

src/models/AgentRun.ts

@@ -0,0 +1,114 @@
+import { BaseModel } from "./common";
+
+/**
+ * Agent run status enum
+ */
+export type AgentRunStatus =
+  | "created"
+  | "in_progress"
+  | "awaiting"
+  | "completed"
+  | "stopping"
+  | "stopped"
+  | "failed"
+  | "stale";
+
+/**
+ * Agent run type enum
+ */
+export type AgentRunType = "comment_thread";
+
+/**
+ * Agent run activity signal enum
+ */
+export type AgentRunActivitySignal = "auth_request" | "continue" | "select" | "stop";
+
+/**
+ * Agent run activity type enum
+ */
+export type AgentRunActivityType = "action" | "elicitation" | "error" | "prompt" | "response" | "thought";
+
+/**
+ * Agent Run interface
+ */
+export interface AgentRun extends BaseModel {
+  agent_user: string;
+  comment?: string;
+  source_comment?: string;
+  creator: string;
+  stopped_at?: string;
+  stopped_by?: string;
+  started_at: string;
+  ended_at?: string;
+  external_link?: string;
+  issue?: string;
+  workspace: string;
+  project?: string;
+  status: AgentRunStatus;
+  error_metadata?: Record<string, any>;
+  type: AgentRunType;
+}
+
+/**
+ * Create agent run request interface
+ */
+export interface CreateAgentRunRequest {
+  agent_slug: string;
+  issue?: string;
+  project?: string;
+  comment?: string;
+  source_comment?: string;
+  external_link?: string;
+  type?: AgentRunType;
+}
+
+/**
+ * Agent run activity content for action type
+ */
+export interface AgentRunActivityActionContent {
+  type: "action";
+  action: string;
+  parameters: Record<string, string>;
+}
+
+/**
+ * Agent run activity content for other types
+ */
+export interface AgentRunActivityTextContent {
+  type: Exclude<AgentRunActivityType, "action">;
+  body: string;
+}
+
+/**
+ * Agent run activity content
+ */
+export type AgentRunActivityContent = AgentRunActivityActionContent | AgentRunActivityTextContent;
+
+/**
+ * Agent Run Activity interface
+ */
+export interface AgentRunActivity extends BaseModel {
+  agent_run: string;
+  content: AgentRunActivityContent;
+  content_metadata?: Record<string, any>;
+  ephemeral: boolean;
+  signal: AgentRunActivitySignal;
+  signal_metadata?: Record<string, any>;
+  comment?: string;
+  actor?: string;
+  type: AgentRunActivityType;
+  project?: string;
+  workspace: string;
+}
+
+/**
+ * Create agent run activity request interface
+ */
+export interface CreateAgentRunActivityRequest {
+  content: AgentRunActivityContent;
+  content_metadata?: Record<string, any>;
+  signal?: AgentRunActivitySignal;
+  signal_metadata?: Record<string, any>;
+  type: Exclude<AgentRunActivityType, "prompt">;
+  project?: string;
+}

src/models/index.ts

@@ -14,3 +14,4 @@ export * from "./Sticky";
 export * from "./Teamspace";
 export * from "./InitiativeLabel";
 export * from "./Initiative";
+export * from "./AgentRun";