:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(tasks): send the agent's report with the finish tool (#126478)
Harley Alexander422d2a64ded0
diff --git a/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts b/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.tsindex 5b493934fa42..a4f3d1d28373 100644--- a/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts+++ b/packages/agent/packages/agent/src/adapters/claude/claude-agent.finish.test.ts@@ -33,6 +33,7 @@ const API_CONFIG: PostHogAPIConfig = {type RequestFinish = (status: "completed" | "failed",message?: string,+ report?: string,) => Promise<void>;function buildRequestFinish(@@ -93,6 +94,16 @@ describe("ClaudeAcpAgent.buildRequestFinish", () => {});});+ it("saves the report as the run's final message", async () => {+ const requestFinish = buildRequestFinish(API_CONFIG, "task-1", "run-1");+ await requestFinish?.("completed", undefined, "Opened 2 draft PRs");++ expect(mocks.updateTaskRun).toHaveBeenCalledWith("task-1", "run-1", {+ status: "completed",+ output: { final_message: "Opened 2 draft PRs" },+ });+ });+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");diff --git a/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts b/packages/agent/packages/agent/src/adapters/claude/claude-agent.tsindex 3b135e60f068..4193c630acc9 100644--- a/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts+++ b/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts@@ -53,7 +53,9 @@ import {type FileEnrichmentDeps,} from "@posthog/harness/extensions/enrichment";import {+ buildFinishRunUpdate,isCloudRun,+ isFinishReportRequired,LOCAL_TOOLS_MCP_NAME,type LocalToolCtx,resolveGithubToken,@@ -3082,13 +3084,13 @@ export class ClaudeAcpAgent extends BaseAcpAgent {if (!config || !taskId || !taskRunId) {return undefined;}- return async (status, message) => {+ return async (status, message, report) => {try {- await new PostHogAPIClient(config).updateTaskRun(taskId, taskRunId, {- status,- ...(status === "failed" && message ? { error_message: message } : {}),- ...(status === "failed" ? { error_type: "agent_declined" } : {}),- });+ await new PostHogAPIClient(config).updateTaskRun(+ taskId,+ taskRunId,+ buildFinishRunUpdate(status, message, report),+ );} catch (error) {this.logger.error("finish tool failed to mark run terminal", error);throw error;@@ -3191,6 +3193,10 @@ export class ClaudeAcpAgent extends BaseAcpAgent {taskRunId: meta?.taskRunId,baseBranch,requestFinish,+ finishReportRequired: isFinishReportRequired({+ taskOriginProduct,+ endRunWhenDone,+ }),},{environment,diff --git a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.tsindex 3a577b2cf711..b01b25085211 100644--- a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts+++ b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp-server.ts@@ -42,6 +42,7 @@ let parsed: {taskRunId?: string;token?: string;baseBranch?: string;+ finishReportRequired?: boolean;};try {parsed = JSON.parse(Buffer.from(ctxEnv, "base64").toString("utf-8"));@@ -59,6 +60,7 @@ const ctx: LocalToolCtx = {taskId: parsed.taskId,taskRunId: parsed.taskRunId,baseBranch: parsed.baseBranch,+ finishReportRequired: parsed.finishReportRequired,};const enabledNames = (process.env.POSTHOG_LOCAL_TOOLS_ENABLED ?? "")diff --git a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.tsindex a48fd8cedc3a..3c8a6a3db6f8 100644--- a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts+++ b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.test.ts@@ -62,6 +62,8 @@ describe("buildLocalToolsServer", () => {taskId: "task-1",taskRunId: "run-1",baseBranch: "master",+ taskOriginProduct: "workflow",+ endRunWhenDone: true,},);@@ -96,6 +98,7 @@ describe("buildLocalToolsServer", () => {expect(ctx.taskId).toBe("task-1");expect(ctx.taskRunId).toBe("run-1");expect(ctx.baseBranch).toBe("master");+ expect(ctx.finishReportRequired).toBe(true);});it("returns a server but omits token env vars when no token is present", () => {diff --git a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.tsindex 70afcfd64142..876dd59828bc 100644--- a/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts+++ b/packages/agent/packages/agent/src/adapters/codex-app-server/local-tools-mcp.ts@@ -9,6 +9,7 @@ import type { McpServerStdio } from "@agentclientprotocol/sdk";import { ghTokenEnv } from "@posthog/git/signed-commit";import {enabledLocalTools,+ isFinishReportRequired,LOCAL_TOOLS_MCP_NAME,type LocalToolCtx,type LocalToolGateMeta,@@ -83,6 +84,7 @@ export function buildLocalToolsServer(taskId: resolveTaskId(meta),taskRunId: meta?.taskRunId,baseBranch: meta?.baseBranch,+ finishReportRequired: isFinishReportRequired(meta),};const names = enabledLocalTools(toolCtx, meta).map((tool) => tool.name);if (isTaskRunSandbox(process.env)) names.push(MEMORY_KILL_HOOK_TOOL_NAME);diff --git a/packages/agent/packages/harness/src/extensions/local-tools/index.ts b/packages/agent/packages/harness/src/extensions/local-tools/index.tsindex 2ce7560546d2..ec530182d097 100644--- a/packages/agent/packages/harness/src/extensions/local-tools/index.ts+++ b/packages/agent/packages/harness/src/extensions/local-tools/index.ts@@ -38,7 +38,11 @@ export {type SignedCommitToolResult,} from "./signed-commit-shared";export { TaskToolsApiClient, TaskToolsApiError } from "./task-tools-client";-export { FINISH_TOOL_NAME } from "./tools/finish";+export {+ buildFinishRunUpdate,+ FINISH_TOOL_NAME,+ isFinishReportRequired,+} from "./tools/finish";export { GH_STACK_QUALIFIED_TOOL_NAME } from "./tools/gh-stack";export { SHOW_ACTIONS_TOOL_NAME } from "./tools/show-actions";export { SPEAK_TOOL_NAME } from "./tools/speak";diff --git a/packages/agent/packages/harness/src/extensions/local-tools/registry.ts b/packages/agent/packages/harness/src/extensions/local-tools/registry.tsindex dde09ad3efbb..e339fcf2b085 100644--- a/packages/agent/packages/harness/src/extensions/local-tools/registry.ts+++ b/packages/agent/packages/harness/src/extensions/local-tools/registry.ts@@ -30,7 +30,13 @@ export interface LocalToolCtx {requestFinish?: (status: "completed" | "failed",message?: string,+ report?: string,) => Promise<void>;+ /**+ * A later workflow step reads this run's final message, so `finish` refuses to+ * end the run without a report. Set from `isFinishReportRequired(meta)`.+ */+ finishReportRequired?: boolean;}/** Minimal session-meta shape needed to gate tools (e.g. cloud-only). */diff --git a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.tsindex a74fce385aa1..825e1e445be2 100644--- a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts+++ b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.test.ts@@ -9,7 +9,13 @@ vi.mock("../signed-commit-artefacts", async (importOriginal) => ({import { enabledLocalTools } from "../index";import type { LocalToolCtx, LocalToolGateMeta } from "../registry";-import { FINISH_TOOL_NAME, finishSchema, finishTool } from "./finish";+import {+ buildFinishRunUpdate,+ FINISH_REPORT_MAX_CHARS,+ FINISH_TOOL_NAME,+ finishSchema,+ finishTool,+} from "./finish";describe("finish tool", () => {const requestFinish = async (): Promise<void> => {};@@ -174,9 +180,17 @@ describe("finish tool", () => {const spy = vi.fn(async () => {});const result = await finishTool.handler({ cwd: "/repo", requestFinish: spy },- { status: "failed", reason: "ran out of quota" },+ {+ status: "failed",+ reason: "ran out of quota",+ report: "Partial report",+ },+ );+ expect(spy).toHaveBeenCalledWith(+ "failed",+ "ran out of quota",+ "Partial report",);- expect(spy).toHaveBeenCalledWith("failed", "ran out of quota");expect(result.isError).toBeUndefined();});@@ -199,6 +213,57 @@ describe("finish tool", () => {expect(result.isError).toBeUndefined();});+ it.each(["", " "])(+ "keeps a report-required run open when the report is %j",+ async (report) => {+ const spy = vi.fn(async () => {});+ const result = await finishTool.handler(+ { cwd: "/repo", requestFinish: spy, finishReportRequired: true },+ { status: "completed", report },+ );+ expect(spy).not.toHaveBeenCalled();+ expect(result.isError).toBe(true);+ },+ );++ const rejectOnce = (status: number) =>+ vi+ .fn<NonNullable<LocalToolCtx["requestFinish"]>>()+ .mockRejectedValueOnce(Object.assign(new Error("rejected"), { status }))+ .mockResolvedValue(undefined);++ it.each([400, 403])(+ "ends the run without the report when the backend rejects it (%i)",+ async (status) => {+ const spy = rejectOnce(status);+ const result = await finishTool.handler(+ { cwd: "/repo", requestFinish: spy },+ { status: "completed", report: "Full report" },+ );+ expect(result.isError).toBeUndefined();+ expect(spy).toHaveBeenLastCalledWith("completed", undefined);+ },+ );++ it("keeps the report when the finish fails for another reason", async () => {+ const spy = rejectOnce(500);+ await expect(+ finishTool.handler(+ { cwd: "/repo", requestFinish: spy },+ { status: "completed", report: "Full report" },+ ),+ ).rejects.toThrow("rejected");+ expect(spy).toHaveBeenCalledTimes(1);+ });++ it("cuts a long report without splitting a surrogate pair", () => {+ const report = `${"a".repeat(FINISH_REPORT_MAX_CHARS - 1)}😀😀`;+ const finalMessage = buildFinishRunUpdate("completed", undefined, report)+ .output?.final_message as string;+ expect(finalMessage).toBe(`${"a".repeat(FINISH_REPORT_MAX_CHARS - 1)}😀`);+ expect(finalMessage.isWellFormed()).toBe(true);+ });+it("errors when requestFinish is unavailable", async () => {const result = await finishTool.handler({ cwd: "/repo" },diff --git a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.tsindex a9fd597c93c3..594fda80fb0b 100644--- a/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts+++ b/packages/agent/packages/harness/src/extensions/local-tools/tools/finish.ts@@ -2,12 +2,14 @@ import { z } from "zod";import {defineLocalTool,type LocalToolCtx,+ type LocalToolGateMeta,type LocalToolResult,} from "../registry";import {createSandboxPosthogClient,withReportDeadline,} from "../signed-commit-artefacts";+import type { TaskRunUpdate } from "../task-tools-client";export const FINISH_TOOL_NAME = "finish";@@ -28,8 +30,60 @@ export const finishSchema = {"Short note on why you're stopping — recorded on the run. Required-in- " +"spirit for 'failed': say what blocked you so a human can pick it up.",),+ report: z+ .string()+ .optional()+ .describe(+ "Your final report: the full answer your instructions asked for. " ++ "Workflow steps after this run read it, so put the complete report " ++ "here, not a pointer to an earlier message.",+ ),};+// Kept equal to FINAL_MESSAGE_MAX_CHARS in products/tasks/backend/constants.py.+export const FINISH_REPORT_MAX_CHARS = 20_000;++/** The task run PATCH that the `finish` tool sends. */+export function buildFinishRunUpdate(+ status: "completed" | "failed",+ message?: string,+ report?: string,+): TaskRunUpdate {+ return {+ status,+ ...(status === "failed" && message ? { error_message: message } : {}),+ ...(status === "failed" ? { error_type: "agent_declined" } : {}),+ // The relay saves the final message only when the turn ends, and `finish`+ // ends the run before that, so the report travels with the status change.+ ...(report+ ? {+ output: {+ // Cut by code point: a split surrogate pair makes Postgres reject the JSONB write.+ final_message: Array.from(report)+ .slice(0, FINISH_REPORT_MAX_CHARS)+ .join(""),+ },+ }+ : {}),+ };+}++/** A workflow run that opts into `finish` hands its report to the next step. */+export function isFinishReportRequired(+ meta: LocalToolGateMeta | undefined,+): boolean {+ return (+ meta?.taskOriginProduct === "workflow" && meta?.endRunWhenDone === true+ );+}++// A backend without finish-report support rejects the `output` field: 400 from+// the run serializer, 403 for a scout trial token.+function isReportRejected(error: unknown): boolean {+ const status = (error as { status?: unknown } | null)?.status;+ return status === 400 || status === 403;+}+const FINISH_TOOL_DESCRIPTION ="End this run and release the sandbox. This is an unattended background run: " +"nothing else will stop it promptly, so calling `finish` is how the machine " +@@ -38,7 +92,8 @@ const FINISH_TOOL_DESCRIPTION ="or checks you were waiting on have settled, and you've delivered whatever " +"your instructions asked for (or deliberately skipped delivery per those " +"instructions). Do NOT call it while you're still working or still waiting on " +- "something to finish. After it returns, stop — the run is over.";+ "something to finish. Pass your final report in `report`. After it returns, " ++ "stop — the run is over.";/*** Lets the model end its own background run. The handler calls back into the@@ -64,19 +119,13 @@ function resolveRequestFinish(if (!client) {return undefined;}- return async (status, message) => {+ return async (status, message, report) => {await withReportDeadline((signal) =>client.updateTaskRun(taskId,taskRunId,- {- status,- ...(status === "failed" && message- ? { error_message: message }- : {}),- ...(status === "failed" ? { error_type: "agent_declined" } : {}),- },+ buildFinishRunUpdate(status, message, report),signal,),"run finish",@@ -120,7 +169,34 @@ export const finishTool = defineLocalTool({isError: true,};}- await requestFinish(args.status, args.reason);+ if (ctx.finishReportRequired && !args.report?.trim()) {+ return {+ content: [+ {+ type: "text",+ text: "The run is still open. A workflow step reads this run's report, so call `finish` again with your full final report in `report`.",+ },+ ],+ isError: true,+ };+ }+ try {+ await requestFinish(args.status, args.reason, args.report);+ } catch (error) {+ if (!args.report || !isReportRejected(error)) {+ throw error;+ }+ // Ending the run without its report beats leaving it active until the idle timeout.+ await requestFinish(args.status, args.reason);+ return {+ content: [+ {+ type: "text",+ text: `Run marked ${args.status}, but the backend did not accept the report. Stop here.`,+ },+ ],+ };+ }return {content: [{