Multiplayer agent harness for work.
Let a person resume a paused goal (#2116)
Regan Bell9a42ce209f57
diff --git a/src/api/app-sessions.ts b/src/api/app-sessions.tsindex e15761aec..903ca60c5 100644--- a/src/api/app-sessions.ts+++ b/src/api/app-sessions.ts@@ -466,7 +466,7 @@ export function createSessionMethods(goals.set(s.id, {objective: goal.objective,activeMs: goal.activeMs ?? 0,- ...(runningSince ? { runningSince: Math.max(runningSince, goal.createdAt) } : {}),+ ...(runningSince ? { runningSince: Math.max(runningSince, goal.activeSince ?? goal.createdAt) } : {}),...(goal.floor ? { floor: { ...goal.floor } } : {}),});}diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.tsindex f28673b5f..203c9564c 100644--- a/src/core/orchestrator.ts+++ b/src/core/orchestrator.ts@@ -2855,6 +2855,7 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {...(deps.config ? { config: deps.config } : {}),...(deps.control && controlClaims ? { control: deps.control, controlClaims } : {}),...(deps.webhookPublicUrl ? { webhookPublicUrl: deps.webhookPublicUrl } : {}),+ ...(humanTurn && !external ? { humanTurn: true } : {}),...(surfaceToolDeps ? { surface: surfaceToolDeps } : {}),...(!external &&deps.sessionSyscalls &&diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.tsindex 8c955d71e..8136b8894 100644--- a/src/harness/agent-tools.ts+++ b/src/harness/agent-tools.ts@@ -4094,12 +4094,14 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):"required work remains. Do not mark a goal complete merely because its budget is nearly exhausted or because " +"you are stopping work. An independent fresh-context verifier reads only the objective, your note, and any " +"workspace files you name in `files` (the harness reads them for it — name deliverables, never paste them into the note), and " +- "decides; if it rejects, the goal stays active and its reasons come back to you. You cannot block, pause, or " +- "resume a goal; only the user stops it.",+ "decides; if it rejects, the goal stays active and its reasons come back to you. You cannot block or pause a goal; " ++ 'only the user stops it. A paused goal resumes (status "resume") only when the person in this turn explicitly asks ' ++ "to resume it; never resume one on your own initiative. Resume keeps the objective, floor and cap.",parameters: Type.Object({- status: Type.Literal("complete"),+ status: Type.Union([Type.Literal("complete"), Type.Literal("resume")]),note: Type.String({- description: "The concrete evidence (commands, output, results, links) that proves the objective is achieved.",+ description:+ "complete: the concrete evidence (commands, output, results, links) that proves the objective is achieved. resume: quote the user's request to resume.",}),files: Type.Optional(Type.Array(Type.String(), {@@ -4109,19 +4111,53 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):),}),async execute(callId, params) {- const p = params as { note: string; files?: string[] };+ const p = params as { status?: "complete" | "resume"; note: string; files?: string[] };+ const status = p.status === "resume" ? "resume" : "complete";await recordCall(callId, {tool: "goal",action: "update",- status: "complete",+ status,...(p.note ? { note: p.note } : {}),});const goal = ref.goal;+ if (status === "resume") {+ if (goal?.status !== "paused") {+ return recordCoreAuthoredResult(+ callId,+ { tool: "goal", action: "update", error: "not_paused" },+ text(goal?.status === "active" ? "The goal is already active." : "No paused goal to resume."),+ true,+ );+ }+ // Only a person's own message can lift a pause the person put there;+ // crons, webhooks, ambient and delegated wakes cannot.+ if (ref.current?.humanTurn !== true) {+ return recordCoreAuthoredResult(+ callId,+ { tool: "goal", action: "update", error: "human_required" },+ text(+ "Only the user can resume a paused goal, by asking in their own message; this run was not started by one. The goal stays paused.",+ ),+ true,+ );+ }+ goal.status = "active";+ goal.updatedAt = goal.activeSince = Date.now();+ return recordCoreAuthoredResult(+ callId,+ { tool: "goal", action: "update", goal },+ text("The goal is active again and enforced as before. Continue working toward it."),+ );+ }if (goal?.status !== "active") {return recordCoreAuthoredResult(callId,{ tool: "goal", action: "update", error: "no_active_goal" },- text(goal?.status === "paused" ? "The goal is paused by the user." : "No active goal to complete."),+ text(+ goal?.status === "paused"+ ? "The goal is paused by the user. Only the user can resume it, by asking to."+ : "No active goal to complete.",+ ),true,);}diff --git a/src/harness/goal.ts b/src/harness/goal.tsindex bb0757179..c4dac4636 100644--- a/src/harness/goal.ts+++ b/src/harness/goal.ts@@ -13,8 +13,10 @@* floor works the same way (matching Codex/Claude Code goal features):* completing or stopping under an unmet floor is answered with a* keep-going prompt, never a hard tool rejection.- * - Only a human pressing stop in the UI stops a goal (it pauses). The- * agent cannot block, pause, resume, or complete it: it may only REQUEST+ * - Only a human pressing stop in the UI stops a goal (it pauses), and only+ * a person's own message can resume it (goal update "resume" is refused on+ * cron, webhook, ambient and delegated turns). The agent cannot block,+ * pause, or complete it on its own: it may only REQUEST* completion with evidence, and a fresh-context verifier (the harness's* judge model, which never saw the work) decides. A rejection's reasons* become the next continuation prompt. The harness never waives a goal.@@ -39,6 +41,8 @@ export interface GoalRecord {updatedAt: number;/** Time spent actually running turns on this goal, banked at each turn end. */activeMs?: number;+ /** When the user last resumed the goal; time before it (while paused) never counts. */+ activeSince?: number;completionNote?: string;/** Reasons the verifier gave for rejecting the last completion request. */verifierFeedback?: string;@@ -160,7 +164,8 @@ export function goalPausedNote(goal: GoalRecord): string {return (`[goal] This session has a PAUSED goal (paused when a turn was stopped or by request):\n` +`<objective>\n${escapeTags(goal.objective)}\n</objective>\n` +- `Do not pursue it and do not treat it as enforced.`+ `Do not pursue it and do not treat it as enforced. If the user's message explicitly asks to resume it, ` ++ `call goal action update with status "resume"; never resume it on your own initiative.`);}@@ -211,12 +216,14 @@ export function reviveGoalRecord(goal: GoalRecord): GoalRecord {const floor = sanitizeFloor(goal.floor);const capTokens = positiveInteger(goal.capTokens);const activeMs = finitePositive(goal.activeMs);- const { floor: _floor, capTokens: _capTokens, activeMs: _activeMs, ...rest } = goal;+ const activeSince = finitePositive(goal.activeSince);+ const { floor: _floor, capTokens: _capTokens, activeMs: _activeMs, activeSince: _activeSince, ...rest } = goal;return {...rest,objective: String(goal.objective ?? ""),tokensUsed: Math.floor(finitePositive(goal.tokensUsed) ?? 0),...(activeMs ? { activeMs } : {}),+ ...(activeSince ? { activeSince } : {}),...(capTokens ? { capTokens } : {}),...(floor ? { floor } : {}),};@@ -266,9 +273,16 @@ function goalFloorApplies(goal: GoalRecord): boolean {return goal.floor !== undefined && goal.status === "active";}-/** Active time on the goal: banked turns plus the running turn (counted from when the goal existed). */+function goalClockStart(goal: GoalRecord, turnStartedAt: number): number {+ return Math.max(turnStartedAt, goal.activeSince ?? goal.createdAt);+}++/** Active time on the goal: banked turns plus the running turn (counted since the goal was created or last resumed). A paused goal accrues nothing. */export function goalActiveMs(goal: GoalRecord, turnStartedAt: number | undefined, now = Date.now()): number {- const running = turnStartedAt === undefined ? 0 : Math.max(0, now - Math.max(turnStartedAt, goal.createdAt));+ const running =+ turnStartedAt === undefined || goal.status === "paused"+ ? 0+ : Math.max(0, now - goalClockStart(goal, turnStartedAt));return (goal.activeMs ?? 0) + running;}@@ -325,7 +339,7 @@ export function createFloorCapPolicy(opts: {function goalFloorEndsAt(goal: GoalRecord, turnStartedAt: number): number | undefined {const f = goal.floor;if (f?.minMs === undefined || Object.keys(f).length !== 1) return undefined;- return Math.max(turnStartedAt, goal.createdAt) + f.minMs - (goal.activeMs ?? 0);+ return goalClockStart(goal, turnStartedAt) + f.minMs - (goal.activeMs ?? 0);}export function goalFloorUnmet(goal: GoalRecord, meter: GrindMeter, now = Date.now()): boolean {diff --git a/src/harness/harness-router.ts b/src/harness/harness-router.tsindex 0a828b8ce..7ab883a01 100644--- a/src/harness/harness-router.ts+++ b/src/harness/harness-router.ts@@ -60,7 +60,7 @@ async function runTurnEnforcingGoal(meter.turns += result.modelCalls ?? 1;const tokens = inputTokens(result);meter.tokens += tokens;- goal.tokensUsed += tokens;+ if (goal.status !== "paused") goal.tokensUsed += tokens;};account();const remainingWallMs = () =>@@ -96,11 +96,11 @@ async function runTurnEnforcingGoal(return blocked() ? "halted" : "ok";},});+ bankGoalTurn(goal, startedAt);if (result.stopped && (result.stoppedByUser || !input.cancel?.aborted) && goal.status === "active") {goal.status = "paused";goal.updatedAt = Date.now();}- bankGoalTurn(goal, startedAt);await dispatched.emit({ type: "system", payload: goalSnapshotPayload(goal), scopeLabel: input.scopeLabel });return result;}diff --git a/src/harness/pi-harness.ts b/src/harness/pi-harness.tsindex 9bbed274a..9ec2c6016 100644--- a/src/harness/pi-harness.ts+++ b/src/harness/pi-harness.ts@@ -2450,11 +2450,11 @@ export function createPiHarness(opts?: PiHarnessOptions): Harness {if (entry.ref.goal) {const g = entry.ref.goal;+ bankGoalTurn(g, grindMeter.startedAt);if (userAborted && g.status === "active") {g.status = "paused";g.updatedAt = Date.now();}- bankGoalTurn(g, grindMeter.startedAt);const goalEntry = await turn.emit({type: "system",payload: goalSnapshotPayload(g),diff --git a/src/tools/primitives.ts b/src/tools/primitives.tsindex 1537945da..309139f34 100644--- a/src/tools/primitives.ts+++ b/src/tools/primitives.ts@@ -201,6 +201,8 @@ export interface ToolContext extends SurfaceToolDeps {runtime?(request: RuntimeRequest, signal?: AbortSignal): Promise<RuntimeResult>;attach: AttachFiles;sessionSyscalls?: SessionSyscalls;+ /** True when a person's own message started this turn (not a cron, webhook, ambient or delegated wake). */+ humanTurn?: boolean;commandCredentialHandles?: readonly string[];registerLogin?(service: string,@@ -521,6 +523,7 @@ export interface ToolContextDeps {surface?: SurfaceToolDeps;attach?: AttachFiles;sessionSyscalls?: SessionSyscalls;+ humanTurn?: boolean;}export function createToolContext(deps: ToolContextDeps): ToolContext {@@ -1190,6 +1193,7 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {);},+ ...(deps.humanTurn ? { humanTurn: true } : {}),...(deps.sessionSyscalls? {sessionSyscalls: {diff --git a/test/goal-tools.test.ts b/test/goal-tools.test.tsindex ae6a827a2..910e67d9e 100644--- a/test/goal-tools.test.ts+++ b/test/goal-tools.test.ts@@ -2,7 +2,14 @@ import test from "node:test";import assert from "node:assert/strict";import { createAgentTools, type ToolContextRef } from "../src/harness/agent-tools.ts";import { createGrindMeter } from "../src/harness/grind.ts";-import { goalContinuationPrompt, rehydrateOpenGoal } from "../src/harness/goal.ts";+import {+ bankGoalTurn,+ goalContinuationPrompt,+ goalFloorUnmet,+ goalPausedNote,+ goalSnapshotPayload,+ rehydrateOpenGoal,+} from "../src/harness/goal.ts";import type { ScopeId } from "../src/types.ts";function toolbox(screenToolResult?: ToolContextRef["screenToolResult"]) {@@ -105,7 +112,7 @@ for (const status of ["blocked", "paused", "active"]) {});}-test("agent cannot close or resume a user-paused goal", async () => {+test("agent cannot close a user-paused goal or replace it", async () => {const { ref, create, update } = toolbox();await create.execute("c1", { objective: "long haul" });ref.goal!.status = "paused";@@ -207,6 +214,94 @@ test("get frames free text as data and escapes tag characters in it", async () =assert.doesNotMatch(read.replace(/^<goal>$|^<\/goal>$/gm, ""), /<\/?goal>/);});+test("resume is refused on turns no person started, and the goal stays paused", async () => {+ const { ref, create, update } = toolbox();+ await create.execute("c1", { objective: "long haul", floor: { minMs: 60_000 } });+ ref.goal!.status = "paused";+ const before = structuredClone(ref.goal);+ for (const current of [null, {}, { humanTurn: false }]) {+ ref.current = current as never;+ const result = await update.execute("u1", { status: "resume", note: "resume it" });+ assert.match(textOf(result as never), /Only the user can resume/);+ assert.deepEqual(ref.goal, before);+ }+});++test("a person's own request resumes a paused goal with its objective, floor and banked time intact", async () => {+ const { ref, create, update } = toolbox();+ const entries: Array<{ type: string; payload: unknown }> = [];+ ref.emit = async (entry) => {+ entries.push(structuredClone(entry));+ };+ await create.execute("c1", { objective: "long haul", floor: { minMs: 60_000 }, token_cap: 500 });+ ref.goal!.status = "paused";+ ref.goal!.activeMs = 1234;+ ref.current = { humanTurn: true } as never;+ const result = await update.execute("u1", { status: "resume", note: "user: please resume the goal" });+ assert.match(textOf(result as never), /active again/);+ assert.equal(ref.goal?.status, "active");+ assert.deepEqual(ref.goal?.floor, { minMs: 60_000 });+ assert.equal(ref.goal?.capTokens, 500);+ assert.equal(ref.goal?.activeMs, 1234);+ assert.equal(rehydrateOpenGoal(entries)?.status, "active");+ const floored = await update.execute("u2", { status: "complete", note: "done" });+ assert.match(textOf(floored as never), /work floor is not met/);+});++test("stop, then a later human turn resumes from the persisted pause and completes", async () => {+ const history: Array<{ type: string; payload: unknown }> = [];+ const first = toolbox();+ first.ref.emit = async (entry) => {+ history.push(structuredClone(entry));+ };+ await first.create.execute("c1", { objective: "ship it" });+ first.ref.goal!.status = "paused"; // what the harness does on a user stop+ history.push({ type: "system", payload: goalSnapshotPayload(first.ref.goal!) });++ const next = toolbox();+ next.ref.emit = first.ref.emit;+ next.ref.goal = rehydrateOpenGoal(history);+ assert.equal(next.ref.goal?.status, "paused");+ assert.match(+ goalPausedNote(next.ref.goal!),+ /explicitly asks to resume[\s\S]*never resume it on your own initiative/,+ );+ next.ref.current = { humanTurn: true } as never;+ await next.update.execute("u1", { status: "resume", note: "user: resume the goal" });+ assert.equal(rehydrateOpenGoal(history)?.status, "active");+ await next.update.execute("u2", { status: "complete", note: "verified" });+ assert.equal(next.ref.goal?.status, "complete");+ assert.equal(rehydrateOpenGoal(history), null);+});++test("time spent while paused never counts toward the floor after a resume", async () => {+ const { ref, create, update } = toolbox();+ const minute = 60_000;+ await create.execute("c1", { objective: "long haul", floor: { minMs: 30 * minute } });+ const t0 = ref.goal!.createdAt;+ bankGoalTurn(ref.goal!, t0, t0 + 5 * minute); // the stopped turn still counts+ ref.goal!.status = "paused";+ for (let i = 0; i < 3; i++) bankGoalTurn(ref.goal!, t0 + (10 + i * 10) * minute, t0 + (20 + i * 10) * minute);+ assert.equal(ref.goal!.activeMs, 5 * minute);+ ref.current = { humanTurn: true } as never;+ await update.execute("u1", { status: "resume", note: "user: resume" });+ const meter = { ...createGrindMeter(), startedAt: t0 };+ assert.equal(goalFloorUnmet(ref.goal!, meter, ref.goal!.activeSince! + minute), true);+ assert.equal(goalFloorUnmet(ref.goal!, meter, ref.goal!.activeSince! + 26 * minute), false);+});++test("resume only applies to a paused goal", async () => {+ const { ref, create, update } = toolbox();+ ref.current = { humanTurn: true } as never;+ assert.match(textOf((await update.execute("u0", { status: "resume", note: "x" })) as never), /No paused goal/);+ await create.execute("c1", { objective: "obj" });+ assert.match(textOf((await update.execute("u1", { status: "resume", note: "x" })) as never), /already active/);+ await update.execute("u2", { status: "complete", note: "verified" });+ assert.equal(ref.goal?.status, "complete");+ await update.execute("u3", { status: "resume", note: "x" });+ assert.equal(ref.goal?.status, "complete");+});+test("goal mutation receipts are durable before returning and rehydrate without an end-of-turn snapshot", async () => {const { ref, create, update } = toolbox();const entries: Array<{ type: string; payload: unknown }> = [];@@ -232,7 +327,7 @@ test("agent cannot pause a goal or bypass its work floor", async () => {assert.deepEqual(ref.goal, before);});-test("goal update schema offers only complete", () => {+test("goal update schema offers only complete and resume", () => {const { tools } = toolbox();const goal = tools.find((tool) => tool.name === "goal")!;assert.doesNotMatch(JSON.stringify(goal.parameters), /"paused"|"blocked"|"active"/);