feat(desktop): Implement loops ➿ (#3411)

Author: charlesvien

packages/agent/src/adapters/claude/claude-agent.finish.test.ts

@@ -0,0 +1,121 @@
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PostHogAPIConfig } from "../../types";
+
+vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+  query: vi.fn(),
+}));
+
+const mocks = vi.hoisted(() => ({
+  updateTaskRun: vi.fn(),
+  constructedConfigs: [] as unknown[],
+}));
+
+vi.mock("../../posthog-api", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../posthog-api")>();
+  class FakePostHogAPIClient {
+    updateTaskRun = mocks.updateTaskRun;
+    constructor(config: unknown) {
+      mocks.constructedConfigs.push(config);
+    }
+  }
+  return { ...actual, PostHogAPIClient: FakePostHogAPIClient };
+});
+
+const { ClaudeAcpAgent } = await import("./claude-agent");
+
+const API_CONFIG: PostHogAPIConfig = {
+  apiUrl: "https://us.posthog.com",
+  getApiKey: () => "key",
+  projectId: 1,
+};
+
+type RequestFinish = (
+  status: "completed" | "failed",
+  message?: string,
+) => Promise<void>;
+
+function buildRequestFinish(
+  posthogApiConfig: PostHogAPIConfig | undefined,
+  taskId: string | undefined,
+  taskRunId: string | undefined,
+): RequestFinish | undefined {
+  const client = {
+    sessionUpdate: vi.fn().mockResolvedValue(undefined),
+  } as unknown as AgentSideConnection;
+  const agent = new ClaudeAcpAgent(client, { posthogApiConfig });
+  return (
+    agent as unknown as {
+      buildRequestFinish(
+        taskId: string | undefined,
+        taskRunId: string | undefined,
+      ): RequestFinish | undefined;
+    }
+  ).buildRequestFinish(taskId, taskRunId);
+}
+
+describe("ClaudeAcpAgent.buildRequestFinish", () => {
+  beforeEach(() => {
+    mocks.updateTaskRun.mockReset().mockResolvedValue({});
+    mocks.constructedConfigs.length = 0;
+  });
+
+  it.each([
+    {
+      name: "no posthogApiConfig",
+      config: undefined,
+      taskId: "task-1",
+      taskRunId: "run-1",
+    },
+    {
+      name: "no taskId",
+      config: API_CONFIG,
+      taskId: undefined,
+      taskRunId: "run-1",
+    },
+    {
+      name: "no taskRunId",
+      config: API_CONFIG,
+      taskId: "task-1",
+      taskRunId: undefined,
+    },
+  ])("is unavailable with $name", ({ config, taskId, taskRunId }) => {
+    expect(buildRequestFinish(config, taskId, taskRunId)).toBeUndefined();
+  });
+
+  it("marks the run completed without an error_message", async () => {
+    const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");
+    await requestFinish?.("completed");
+
+    expect(mocks.constructedConfigs).toEqual([API_CONFIG]);
+    expect(mocks.updateTaskRun).toHaveBeenCalledWith("task-1", "run-1", {
+      status: "completed",
+    });
+  });
+
+  it("marks the run failed with the message as error_message", async () => {
+    const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");
+    await requestFinish?.("failed", "blocked on missing credentials");
+
+    expect(mocks.updateTaskRun).toHaveBeenCalledWith("task-1", "run-1", {
+      status: "failed",
+      error_message: "blocked on missing credentials",
+    });
+  });
+
+  it("omits error_message on a failed finish without a message", async () => {
+    const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");
+    await requestFinish?.("failed");
+
+    expect(mocks.updateTaskRun).toHaveBeenCalledWith("task-1", "run-1", {
+      status: "failed",
+    });
+  });
+
+  it("rethrows when the API update fails", async () => {
+    mocks.updateTaskRun.mockRejectedValue(new Error("api down"));
+    const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");
+
+    await expect(requestFinish?.("completed")).rejects.toThrow("api down");
+  });
+});

packages/agent/src/adapters/claude/claude-agent.ts

@@ -57,6 +57,7 @@ import {
   type Enrichment,
   type FileEnrichmentDeps,
 } from "../../enrichment/file-enricher";
+import { PostHogAPIClient } from "../../posthog-api";
 import { resolvePostHogExecPermissionRegex } from "../../posthog-exec-permission";
 import {
   classifyPostHogExecCall,
@@ -75,7 +76,7 @@ import { resolveGithubToken } from "../../utils/github-token";
 import { Logger } from "../../utils/logger";
 import { Pushable } from "../../utils/streams";
 import { BaseAcpAgent } from "../base-acp-agent";
-import { LOCAL_TOOLS_MCP_NAME } from "../local-tools";
+import { LOCAL_TOOLS_MCP_NAME, type LocalToolCtx } from "../local-tools";
 import { resolveSpokenNarration, resolveTaskId } from "../session-meta";
 import {
   buildBreakdown,
@@ -1881,6 +1882,30 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     }
   }
 
+  // Backs the `finish` local tool: marks the task run terminal so the Temporal
+  // workflow tears the sandbox down. Only wired when we have both the run
+  // identifiers and a PostHog API config, i.e. a real cloud run.
+  private buildRequestFinish(
+    taskId: string | undefined,
+    taskRunId: string | undefined,
+  ): LocalToolCtx["requestFinish"] {
+    const config = this.options?.posthogApiConfig;
+    if (!config || !taskId || !taskRunId) {
+      return undefined;
+    }
+    return async (status, message) => {
+      try {
+        await new PostHogAPIClient(config).updateTaskRun(taskId, taskRunId, {
+          status,
+          ...(status === "failed" && message ? { error_message: message } : {}),
+        });
+      } catch (error) {
+        this.logger.error("finish tool failed to mark run terminal", error);
+        throw error;
+      }
+    };
+  }
+
   private async createSession(
     params: {
       cwd: string;
@@ -1939,6 +1964,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     const baseBranch = meta?.baseBranch;
     const environment = meta?.environment;
     const spokenNarration = resolveSpokenNarration(meta);
+    const requestFinish = this.buildRequestFinish(taskId, meta?.taskRunId);
     const buildInProcessMcpServers = (): Record<
       string,
       McpSdkServerConfigWithInstance
@@ -1950,8 +1976,13 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
           taskId,
           taskRunId: meta?.taskRunId,
           baseBranch,
+          requestFinish,
+        },
+        {
+          environment,
+          spokenNarration,
+          background: meta?.mode === "background",
         },
-        { environment, spokenNarration },
       );
       return server ? { [LOCAL_TOOLS_MCP_NAME]: server } : {};
     };

packages/agent/src/adapters/claude/types.ts

@@ -11,6 +11,7 @@ import type {
   SDKUserMessage,
 } from "@anthropic-ai/claude-agent-sdk";
 import type { PostHogProductId } from "../../posthog-products";
+import type { AgentMode } from "../../types";
 import type { Pushable } from "../../utils/streams";
 import type { BaseSession } from "../base-acp-agent";
 import type { ContextBreakdownBaseline } from "./context-breakdown";
@@ -181,6 +182,12 @@ export type NewSessionMeta = {
   taskRunId?: string;
   taskId?: string;
   environment?: "local" | "cloud";
+  /**
+   * Run mode. "background" means unattended (loops, durable ingest) — no human
+   * drives the turns, so the agent may end its own run via the `finish` tool.
+   * "interactive" runs are driven turn-by-turn and are ended by the human.
+   */
+  mode?: AgentMode;
   disableBuiltInTools?: boolean;
   systemPrompt?: unknown;
   sessionId?: string;

packages/agent/src/adapters/local-tools/index.ts

@@ -1,5 +1,6 @@
 import type { LocalTool, LocalToolCtx, LocalToolGateMeta } from "./registry";
 import { cloneRepoTool } from "./tools/clone-repo";
+import { finishTool } from "./tools/finish";
 import { listReposTool } from "./tools/list-repos";
 import { signedCommitTool } from "./tools/signed-commit";
 import { signedMergeTool } from "./tools/signed-merge";
@@ -23,6 +24,7 @@ export const LOCAL_TOOLS: LocalTool[] = [
   listReposTool,
   cloneRepoTool,
   speakTool,
+  finishTool,
 ];
 
 /** Tools whose gate passes for the given context — the set to actually expose. */

packages/agent/src/adapters/local-tools/registry.ts

@@ -21,6 +21,16 @@ export interface LocalToolCtx {
    * back to origin/HEAD detection when unset.
    */
   baseBranch?: string;
+  /**
+   * Marks this run terminal and lets the workflow tear the sandbox down. Set by
+   * the adapter for cloud runs that own a sandbox; absent for local sessions.
+   * Powers the `finish` tool so an unattended run ends the moment the agent
+   * decides it's done, instead of idling until a timeout.
+   */
+  requestFinish?: (
+    status: "completed" | "failed",
+    message?: string,
+  ) => Promise<void>;
 }
 
 /** Minimal session-meta shape needed to gate tools (e.g. cloud-only). */
@@ -30,6 +40,12 @@ export interface LocalToolGateMeta {
   channelMode?: boolean;
   /** Spoken narration is on for this session: enables the speak tool. */
   spokenNarration?: boolean;
+  /**
+   * Unattended run (no human driving turns): enables the `finish` tool so the
+   * agent can end its own run. False/undefined for interactive runs, which a
+   * human ends.
+   */
+  background?: boolean;
 }
 
 /**

packages/agent/src/adapters/local-tools/tools/finish.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from "vitest";
+import { enabledLocalTools } from "../index";
+import type { LocalToolCtx, LocalToolGateMeta } from "../registry";
+import { FINISH_TOOL_NAME, finishSchema, finishTool } from "./finish";
+
+describe("finish tool", () => {
+  const requestFinish = async (): Promise<void> => {};
+
+  it.each([
+    {
+      name: "background cloud run with requestFinish",
+      ctx: { cwd: "/repo", requestFinish },
+      meta: { environment: "cloud", background: true },
+      expected: true,
+    },
+    {
+      name: "background cloud run without requestFinish",
+      ctx: { cwd: "/repo" },
+      meta: { environment: "cloud", background: true },
+      expected: false,
+    },
+    {
+      name: "interactive cloud run (background unset)",
+      ctx: { cwd: "/repo", requestFinish },
+      meta: { environment: "cloud" },
+      expected: false,
+    },
+    {
+      name: "interactive cloud run (background false)",
+      ctx: { cwd: "/repo", requestFinish },
+      meta: { environment: "cloud", background: false },
+      expected: false,
+    },
+    {
+      name: "background local run",
+      ctx: { cwd: "/repo", requestFinish },
+      meta: { environment: "local", background: true },
+      expected: false,
+    },
+    {
+      name: "no gate meta",
+      ctx: { cwd: "/repo", requestFinish },
+      meta: undefined,
+      expected: false,
+    },
+  ] as {
+    name: string;
+    ctx: LocalToolCtx;
+    meta: LocalToolGateMeta | undefined;
+    expected: boolean;
+  }[])("is exposed only for $name → $expected", ({ ctx, meta, expected }) => {
+    const tools = enabledLocalTools(ctx, meta);
+    expect(tools.some((t) => t.name === FINISH_TOOL_NAME)).toBe(expected);
+  });
+
+  it("stays visible without ToolSearch (alwaysLoad)", () => {
+    expect(finishTool.alwaysLoad).toBe(true);
+  });
+
+  it("defaults status to completed", () => {
+    expect(finishSchema.status.parse(undefined)).toBe("completed");
+  });
+
+  it("rejects an unknown status", () => {
+    expect(finishSchema.status.safeParse("aborted").success).toBe(false);
+  });
+
+  it("marks the run terminal via requestFinish", async () => {
+    const spy = vi.fn(async () => {});
+    const result = await finishTool.handler(
+      { cwd: "/repo", requestFinish: spy },
+      { status: "failed", reason: "ran out of quota" },
+    );
+    expect(spy).toHaveBeenCalledWith("failed", "ran out of quota");
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("errors when requestFinish is unavailable", async () => {
+    const result = await finishTool.handler(
+      { cwd: "/repo" },
+      { status: "completed" },
+    );
+    expect(result.isError).toBe(true);
+  });
+});