Skip to content

armgit / qm

Public Imported from GitHub
0

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.png
new file mode 100644
index 000000000..0772ec91b
Binary files /dev/null and b/docs/qa/tool-purpose/after.png differ
diff --git a/docs/qa/tool-purpose/before-skill.png b/docs/qa/tool-purpose/before-skill.png
new file mode 100644
index 000000000..f8630274b
Binary files /dev/null and b/docs/qa/tool-purpose/before-skill.png differ
diff --git a/plugins/web-ui/src/activity-presentation.ts b/plugins/web-ui/src/activity-presentation.ts
index 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"]): s
const 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.ts
index 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.ts
index 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.ts
index 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 sta
assert.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.ts
index 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.ts
index 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"));
+});