Skip to content

armgit / qm

Public Imported from GitHub
0

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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"/);