Multiplayer agent harness for work.
Show concise tool purposes and skill names in web activity (#1568)
Regan Bell437829c008e7
diff --git a/docs/qa/tool-purpose/after.png b/docs/qa/tool-purpose/after.pngnew file mode 100644index 000000000..0772ec91bBinary files /dev/null and b/docs/qa/tool-purpose/after.png differdiff --git a/docs/qa/tool-purpose/before-skill.png b/docs/qa/tool-purpose/before-skill.pngnew file mode 100644index 000000000..f8630274bBinary files /dev/null and b/docs/qa/tool-purpose/before-skill.png differdiff --git a/plugins/web-ui/src/activity-presentation.ts b/plugins/web-ui/src/activity-presentation.tsindex d7293fb4f..6ee89da94 100644--- a/plugins/web-ui/src/activity-presentation.ts+++ b/plugins/web-ui/src/activity-presentation.ts@@ -33,7 +33,8 @@ export function activityDescription(if (tool === "read") return { category: "read", target: compactPath(call.path ?? result.path ?? "") };if (tool === "skill") {const name = call.name ?? result.name ?? "";- return { category: "read", target: `${name}/${compactPath(call.path ?? result.path ?? "SKILL.md")}` };+ const path = call.path ?? result.path ?? "SKILL.md";+ return { category: "read", target: path === "SKILL.md" ? name : `${name}/${compactPath(path)}` };}if (tool !== "execute") return { category: "other", target: "" };const command = call.command ?? "";@@ -81,7 +82,14 @@ export function activityLabel(row: ToolRowModel, status: WorkBlock["status"]): sconst result = (row.result?.payload ?? {}) as ToolPayload;const { category, target } = activityDescription(call, result);const state = toolRowKind(row, status);- if (category === "other" || state === "approval") return null;+ if (state === "approval") return null;+ const purpose = typeof call.purpose === "string" ? call.purpose.trim() : "";+ if (purpose) {+ if (state === "failed") return `${purpose} · Failed`;+ if (state === "attempted") return `${purpose} · Unconfirmed`;+ return purpose;+ }+ if (category === "other") return null;const verbs = {read: { ok: "Read", running: "Reading", failed: "Failed to read", attempted: "Tried reading" },search: {diff --git a/plugins/web-ui/src/chat.ts b/plugins/web-ui/src/chat.tsindex 029818af8..9d3e5079c 100644--- a/plugins/web-ui/src/chat.ts+++ b/plugins/web-ui/src/chat.ts@@ -2613,13 +2613,17 @@ export function createChatSurface(}function toolDetail(tool: string, call: ToolPayload, result: ToolPayload): string {+ if (typeof call.purpose === "string" && call.purpose.trim()) return call.purpose.trim();switch (toolCategory({ ...result, ...call, tool })) {case "execute":return call.command ? firstLine(call.command) : "";case "read":return call.path ?? result.path ?? "";- case "skill":- return `${call.name ?? result.name ?? ""}/${call.path ?? result.path ?? "SKILL.md"}`;+ case "skill": {+ const name = call.name ?? result.name ?? "";+ const path = call.path ?? result.path ?? "SKILL.md";+ return path === "SKILL.md" ? name : `${name}/${path}`;+ }case "write": {const path = call.path ?? result.path ?? "";const bytes = result.bytes ?? call.bytes;diff --git a/plugins/web-ui/src/timeline.ts b/plugins/web-ui/src/timeline.tsindex 15f993a70..e2c959ef5 100644--- a/plugins/web-ui/src/timeline.ts+++ b/plugins/web-ui/src/timeline.ts@@ -13,6 +13,7 @@ export interface ToolPayload {tool?: string;command?: string;+ purpose?: string;path?: string;bytes?: number;name?: string;diff --git a/plugins/web-ui/test/activity-presentation.test.ts b/plugins/web-ui/test/activity-presentation.test.tsindex 202a4c70f..b72f0ff44 100644--- a/plugins/web-ui/test/activity-presentation.test.ts+++ b/plugins/web-ui/test/activity-presentation.test.ts@@ -43,7 +43,11 @@ test("simple shell reads and searches get semantic labels, compound commands staassert.equal(activityLabel(row("rg --files src"), "complete"), "Searched for files in src");assert.deepEqual(activityDescription({ tool: "skill", name: "publish" }), {category: "read",- target: "publish/SKILL.md",+ target: "publish",+ });+ assert.deepEqual(activityDescription({ tool: "skills", action: "read", name: "admin", path: "SKILL.md" }), {+ category: "read",+ target: "admin",});assert.deepEqual(activityDescription({ tool: "skill", name: "publish", path: "templates/x.md" }), {category: "read",@@ -129,3 +133,21 @@ test("resolved approval history does not mark a group as needing action", () =>const blocked = row("npm test", { blocked: "needs_approval" });assert.equal(activityGroupSummary([{ kind: "tool", row: blocked }], "complete").attention, false);});++test("purpose takes precedence over commands while retaining failure and incomplete states", () => {+ const tool = row("cat /workspace/report.csv");+ tool.call!.payload = { ...(tool.call!.payload as ToolPayload), purpose: " Check the sales totals " };+ assert.equal(activityLabel(tool, "complete"), "Check the sales totals");+ tool.result = null;+ assert.equal(activityLabel(tool, "working"), "Check the sales totals");+ assert.equal(activityLabel(tool, "complete"), "Check the sales totals · Unconfirmed");+ tool.result = row("", { code: 1 }).result;+ assert.equal(activityLabel(tool, "complete"), "Check the sales totals · Failed");+ tool.result = row("", { blocked: "needs_approval" }).result;+ assert.equal(activityLabel(tool, "working"), null);+ tool.call!.payload = { tool: "sandbox", action: "start_process", purpose: "Start the preview server" };+ tool.result = null;+ assert.equal(activityLabel(tool, "working"), "Start the preview server");+ tool.call!.payload = { tool: "execute", command: "cat report.csv", purpose: " " };+ assert.equal(activityLabel(tool, "working"), "Reading report.csv");+});diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.tsindex 43e387af5..12b359f9d 100644--- a/src/harness/agent-tools.ts+++ b/src/harness/agent-tools.ts@@ -589,10 +589,8 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):),purpose: Type.String({description:- "One short sentence on what this command accomplishes and why you're running it now — " +- "the intent, not a restatement of the command. Required on every call: keep it terse for " +- "routine commands, but never skip it, because you can't tell in advance which command will " +- "trip human approval, and if one does this is the ONLY context the approver sees before deciding.",+ "A human-readable intent label, at most 4 words (e.g. 'Check Python version'). " ++ "Describe the purpose, not the code. Required on every call; shown in tool activity and approval requests.",}),timeout_seconds: Type.Optional(Type.Integer({@@ -660,6 +658,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):await recordCall(callId, {tool: "execute",command: params.command,+ purpose: params.purpose,...scopeNote,...(params.sandbox_id ? { sandbox_id: params.sandbox_id } : {}),});@@ -783,14 +782,14 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):const durable = params.durable;if (keyword === "scoped") {if ((scratchExec || ownerAuthExec) && durable === false) {- await recordCall(callId, { tool: "execute", command: params.command, scope, durable });+ await recordCall(callId, { tool: "execute", command: params.command, purpose: params.purpose, scope, durable });return invalidExecute(callId, { tool: "execute", invalid: "scoped_ephemeral" }, SCOPED_EPHEMERAL_ERROR);}return runExecute(callId, params, { scratch: false });}if (keyword === "scratch") {if (!scratchExec) {- await recordCall(callId, { tool: "execute", command: params.command, scope });+ await recordCall(callId, { tool: "execute", command: params.command, purpose: params.purpose, scope });return invalidExecute(callId,{ tool: "execute", invalid: "scratch_unavailable" },@@ -798,14 +797,14 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):);}if (durable === true) {- await recordCall(callId, { tool: "execute", command: params.command, scope, durable });+ await recordCall(callId, { tool: "execute", command: params.command, purpose: params.purpose, scope, durable });return invalidExecute(callId, { tool: "execute", invalid: "scratch_durable" }, SCRATCH_DURABLE_ERROR);}return runExecute(callId, params, { scratch: true });}if (keyword === "owner") {if (!ownerAuthExec) {- await recordCall(callId, { tool: "execute", command: params.command, scope });+ await recordCall(callId, { tool: "execute", command: params.command, purpose: params.purpose, scope });return invalidExecute(callId,{ tool: "execute", invalid: "owner_unavailable" },@@ -813,7 +812,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):);}if (durable === true) {- await recordCall(callId, { tool: "execute", command: params.command, scope, durable });+ await recordCall(callId, { tool: "execute", command: params.command, purpose: params.purpose, scope, durable });return invalidExecute(callId,{ tool: "execute", invalid: "owner_durable" },@@ -897,7 +896,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):),backend: Type.Optional(Type.String({ description: "create only: provider from list." })),name: Type.Optional(Type.String({ description: "create only: human-readable name." })),- purpose: Type.String({ description: "Briefly explain why this action is needed." }),+ purpose: Type.String({ description: "Human-readable purpose, at most 4 words (e.g. 'Check sandbox health')." }),}),async execute(callId, params) {const tc = ref.current;@@ -905,6 +904,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):await recordCall(callId, {tool: "sandbox",action: params.action,+ purpose: params.purpose,...(params.sandbox_id !== undefined ? { sandbox_id: params.sandbox_id } : {}),...(params.backend ? { backend: params.backend } : {}),...(params.name ? { name: params.name } : {}),@@ -1670,7 +1670,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):},),purpose: Type.Optional(- Type.String({ description: "Brief intent for a process operation that may require approval." }),+ Type.String({ description: "Human-readable purpose, at most 4 words (e.g. 'Start preview server')." }),),command: Type.Optional(Type.String({ description: "start only: the shell command to run in the background." })),process_id: Type.Optional(Type.String({ description: "poll/write/stop/watch only: the id start returned." })),@@ -1736,6 +1736,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):await recordCall(callId, {tool: "background",action: params.action,+ purpose: params.purpose,command: params.command,process_id: params.process_id,...(params.sandbox_id ? { sandbox_id: params.sandbox_id } : {}),@@ -2012,7 +2013,8 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):command: Type.Optional(executeBaseParams.command),purpose: Type.Optional(Type.String({- description: "Required for exec and management actions: briefly explain why. Optional for process actions.",+ description:+ "Human-readable intent label, at most 4 words (e.g. 'Check Python version'). Describe the purpose, not the code. Required for exec and management actions; optional for process actions.",}),),timeout_seconds: Type.Optional(@@ -2109,7 +2111,7 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):!Check(schema, params) ||((params as Record<string, unknown>).sandbox_id === null && action !== "set_default")) {- await recordCall(callId, { tool: "sandbox", action });+ await recordCall(callId, { tool: "sandbox", action, purpose: params.purpose });return recordResult(callId,{ tool: "sandbox", action, invalid: true },@@ -4025,6 +4027,7 @@ function withToolApprovalGate(await rec.recordCall(callId, {tool: tool.name,...(resourceAction ? { action: resourceAction } : {}),+ ...(isObj(params) && typeof params.purpose === "string" ? { purpose: params.purpose } : {}),blocked: "needs_approval",reason: STRICT_TOOL_APPROVAL_REASON,});diff --git a/test/agent-tools.test.ts b/test/agent-tools.test.tsindex 83ce30c84..4903ed575 100644--- a/test/agent-tools.test.ts+++ b/test/agent-tools.test.ts@@ -3542,3 +3542,26 @@ test("the retired credential tool is absent and execute accepts credential handl);assert.ok(tools.some((tool) => tool.name === "execute"));});++test("sandbox call traces preserve purpose across execution, management, processes, and invalid routes", async () => {+ const calls: Record<string, unknown>[] = [];+ const ref: ToolContextRef = {+ current: fakeToolContext(),+ scopeLabel: "personal:U1",+ emit: (event) => {+ if (event.type === "tool_call") calls.push(event.payload as Record<string, unknown>);+ },+ };+ const sandbox = createAgentTools(ref, { sandboxResources: true }).find((tool) => tool.name === "sandbox")!;+ for (const params of [+ { action: "exec", command: "pwd" },+ { action: "status" },+ { action: "start_process", command: "echo ready" },+ { action: "exec", command: "pwd", scope: "scratch" },+ { action: "exec" },+ ]) {+ await call(sandbox, { ...params, purpose: "Inspect the demo workspace" });+ }+ assert.equal(calls.length, 5);+ assert.ok(calls.every((entry) => entry.purpose === "Inspect the demo workspace"));+});