feat: add Agent Runs API and related models, activities, and tests

Author: Saurabhkmr98

env.example

@@ -22,3 +22,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

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,48 @@
+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}/`);
+  }
+
+  /**
+   * Resume an agent run
+   * @param workspaceSlug - The workspace slug
+   * @param runId - The agent run ID
+   * @returns The resumed agent run
+   */
+  async resume(workspaceSlug: string, runId: string): Promise<AgentRun> {
+    return this.post<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,115 @@
+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";

tests/unit/agent-runs/activities.test.ts

@@ -0,0 +1,120 @@
+import { PlaneClient } from "../../../src/client/plane-client";
+import { AgentRun, AgentRunActivity } from "../../../src/models";
+import { config } from "../constants";
+import { createTestClient } from "../../helpers/test-utils";
+import { describeIf as describe } from "../../helpers/conditional-tests";
+
+describe(!!(config.workspaceSlug && config.agentSlug), "Agent Run Activities API Tests", () => {
+  let client: PlaneClient;
+  let workspaceSlug: string;
+  let agentSlug: string;
+  let projectId: string;
+  let agentRun: AgentRun;
+  let activity: AgentRunActivity;
+
+  beforeAll(async () => {
+    client = createTestClient();
+    workspaceSlug = config.workspaceSlug;
+    agentSlug = config.agentSlug;
+    projectId = config.projectId;
+
+    // Create an agent run for testing activities
+    agentRun = await client.agentRuns.create(workspaceSlug, {
+      agent_slug: agentSlug,
+      project: projectId,
+    });
+  });
+
+  it("should create an agent run activity", async () => {
+    activity = await client.agentRuns.activities.create(workspaceSlug, agentRun.id, {
+      content: {
+        type: "thought",
+        body: "Test thought activity",
+      },
+      type: "thought",
+      project: projectId,
+    });
+
+    expect(activity).toBeDefined();
+    expect(activity.id).toBeDefined();
+    expect(activity.type).toBe("thought");
+    expect(activity.agent_run).toBe(agentRun.id);
+  });
+
+  it("should list agent run activities", async () => {
+    const activitiesResponse = await client.agentRuns.activities.list(workspaceSlug, agentRun.id);
+
+    expect(activitiesResponse).toBeDefined();
+    expect(Array.isArray(activitiesResponse.results)).toBe(true);
+    expect(activitiesResponse.results.length).toBeGreaterThan(0);
+
+    const foundActivity = activitiesResponse.results.find((a) => a.id === activity.id);
+    expect(foundActivity).toBeDefined();
+  });
+
+  it("should retrieve an agent run activity", async () => {
+    const retrievedActivity = await client.agentRuns.activities.retrieve(
+      workspaceSlug,
+      agentRun.id,
+      activity.id
+    );
+
+    expect(retrievedActivity).toBeDefined();
+    expect(retrievedActivity.id).toBe(activity.id);
+    expect(retrievedActivity.type).toBe("thought");
+  });
+
+  it("should create an action type activity", async () => {
+    const actionActivity = await client.agentRuns.activities.create(workspaceSlug, agentRun.id, {
+      content: {
+        type: "action",
+        action: "create_comment",
+        parameters: {
+          comment: "Test comment from agent",
+        },
+      },
+      type: "action",
+      project: projectId,
+    });
+
+    expect(actionActivity).toBeDefined();
+    expect(actionActivity.id).toBeDefined();
+    expect(actionActivity.type).toBe("action");
+  });
+
+  it("should create a response type activity", async () => {
+    const responseActivity = await client.agentRuns.activities.create(workspaceSlug, agentRun.id, {
+      content: {
+        type: "response",
+        body: "This is a response from the agent",
+      },
+      type: "response",
+      project: projectId,
+    });
+
+    expect(responseActivity).toBeDefined();
+    expect(responseActivity.id).toBeDefined();
+    expect(responseActivity.type).toBe("response");
+  });
+
+  it("should create an elicitation type activity", async () => {
+    const elicitationActivity = await client.agentRuns.activities.create(workspaceSlug, agentRun.id, {
+      content: {
+        type: "elicitation",
+        body: "What would you like me to do next?",
+      },
+      type: "elicitation",
+      signal: "select",
+      signal_metadata: {
+        options: ["option1", "option2"],
+      },
+      project: projectId,
+    });
+
+    expect(elicitationActivity).toBeDefined();
+    expect(elicitationActivity.id).toBeDefined();
+    expect(elicitationActivity.type).toBe("elicitation");
+    expect(elicitationActivity.signal).toBe("select");
+  });
+});
+