Skip to content

Commit 854ca6d

Browse files
mchwangclaude
andauthored
F: run plan suggestions through lane D in planning's own worker (#117, part 2) (#120)
* wip: parameterize leftover ledger by worker naming * wip: AgentWorker hosts Ask or planning jobs * F: run plan suggestions through lane D in planning's own worker (#117, part 2) - AgentWorker (was QuestionWorker) and question-worker.ts serve one feature each; LeftoverLedger, worker roots, locks and recovery wording take a WorkerNaming. Ask's names and messages are unchanged (ASK_NAMING). - Planning gets its own worker, TMPDIR root, ledger, lock and per-database owner token (planning_owner), so its recovery never touches Ask's or the runner's agents. - PlanningAgent (runner/planning.ts) runs each request at the snapshot head of the review repository, with the Settings vendor; Codex is refused (#93). - E3's suggestion timer and the request share one ten-minute budget. - The server awaits PlanningDeps.describe before a start; web/planning.ts reads the issue from GitHub with a bound and is on for any non-demo review with a github block. - Real-Docker planning test in the agent-isolation workflow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * F: address independent review on planning wiring (#117) - A suggestion start replays its recorded outcome before reading GitHub, and reads nothing for a start that would be refused (no planning, shutdown, stale revision or snapshot). A GitHub failure is a 502, not recorded; a shutdown during the read is a 503. - Shutdown gives planning requests Ask's 20 s grace after E3 aborts them, then closes planning's worker, which abandons one stuck in lane D's setup. - Docs: a crashed process's container runs until Claude exits or the next planning request's recovery removes it (no host-side deadline is left). - Tests: E3 budget wiring, deadline lower bound, replay without GitHub, 502, 503, shutdown bound, reverse isolation, worker-side refusal of another feature's job, and a leak check in the real-Docker planning test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 1b826bb commit 854ca6d

19 files changed

Lines changed: 781 additions & 140 deletions

‎.github/workflows/agent-isolation.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ on:
88
- 'test/agent-*.test.ts'
99
- 'runner/question-*.ts'
1010
- 'runner/questions.ts'
11+
- 'runner/planning*.ts'
1112
- 'runner/workspace.ts'
1213
- 'runner/runner-repository.ts'
1314
- 'runner/execution.ts'
@@ -24,6 +25,7 @@ on:
2425
- 'test/agent-*.test.ts'
2526
- 'runner/question-*.ts'
2627
- 'runner/questions.ts'
28+
- 'runner/planning*.ts'
2729
- 'runner/workspace.ts'
2830
- 'runner/runner-repository.ts'
2931
- 'runner/execution.ts'
@@ -49,4 +51,4 @@ jobs:
4951
- run: npm ci --ignore-scripts
5052
- run: npm run typecheck
5153
# The Docker suites share one image tag and daemon, so run test files one at a time.
52-
- run: npx vitest run --no-file-parallelism test/agent-contract.test.ts test/agent-clone.test.ts test/agent-container.test.ts test/agent-network.test.ts test/agent-policy.test.ts test/agent-proxy.test.ts test/agent-adapter.test.ts test/agent-supervisor.test.ts test/agent-output.test.ts test/agent-gate.test.ts test/agent-question.test.ts test/runner-workspace.test.ts
54+
- run: npx vitest run --no-file-parallelism test/agent-contract.test.ts test/agent-clone.test.ts test/agent-container.test.ts test/agent-network.test.ts test/agent-policy.test.ts test/agent-proxy.test.ts test/agent-adapter.test.ts test/agent-supervisor.test.ts test/agent-output.test.ts test/agent-gate.test.ts test/agent-question.test.ts test/agent-planning.test.ts test/runner-workspace.test.ts

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,6 @@ jobs:
1818
- run: npm run typecheck
1919
# The Docker agent suites run one file at a time in the Agent isolation workflow; running them here
2020
# would put them in parallel against the same image tag and daemon.
21-
- run: npm test -- --exclude test/agent-container.test.ts --exclude test/agent-network.test.ts --exclude test/agent-adapter.test.ts --exclude test/agent-supervisor.test.ts --exclude test/agent-gate.test.ts --exclude test/agent-question.test.ts --exclude test/runner-workspace.test.ts
21+
- run: npm test -- --exclude test/agent-container.test.ts --exclude test/agent-network.test.ts --exclude test/agent-adapter.test.ts --exclude test/agent-supervisor.test.ts --exclude test/agent-gate.test.ts --exclude test/agent-question.test.ts --exclude test/agent-planning.test.ts --exclude test/runner-workspace.test.ts
2222
- run: npx playwright install --with-deps chromium
2323
- run: npm run test:browser

‎docs/architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ Dependencies point downward only. `core/` imports nothing that does input or out
160160
| Part | Main files | Owns | State |
161161
|---|---|---|---|
162162
| Command line | `web/cli.ts` | Parses `--demo` or `--config`, takes the single-runner lock, starts the server, releases the lock on Ctrl+C. | In use |
163-
| HTTP server | `web/server.ts` | Binds `127.0.0.1` only. Checks the token, Host and Origin. Bounded JSON bodies. Routes `/api/review`, `/api/action`, `/api/questions`, `/api/merge`, `/api/issues`, `/api/settings`, plus `/api/runner` and `/api/plan/*` when a runner or planning provider is supplied. Ordered shutdown. | In use; `/api/runner` and `/api/plan/*` not connected |
163+
| HTTP server | `web/server.ts` | Binds `127.0.0.1` only. Checks the token, Host and Origin. Bounded JSON bodies. Routes `/api/review`, `/api/action`, `/api/questions`, `/api/merge`, `/api/issues`, `/api/settings`, plus `/api/runner` and `/api/plan/*` when a runner or planning provider is supplied. Ordered shutdown. | In use; `/api/plan/suggestions` runs Claude through lane D for a review with a `github` block (#117) |
164164
| Browser screen | `web/public/*` | Review screen and Issues screen. Plain JavaScript with IBM Plex fonts served locally. Sends item and segment IDs and a state token, never fingerprints or ownership. | Yes |
165165
| Review service | `runner/review.ts` | Builds the review view: reads history, links it to the plan, computes approval states and merge blockers. Applies review commands through the store. | Yes |
166166
| Ask | `runner/questions.ts`, `runner/question-*.ts` | Answers a question about one plan item with a read-only agent. Runs lane D's synchronous setup in a worker thread so the server stays responsive. Tracks leftover containers. | Yes |

‎docs/implementation/planning-acceptance.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -72,14 +72,15 @@ The provider and Ask share one container runner, `runReadOnlyAgent` in
7272
limits, credential rule, output check and wording as a `ReadOnlyFeature` (`ASK_FEATURE`, `PLANNING_FEATURE`). Ask's wording
7373
and cleanup error are unchanged (#117 part 1).
7474

75-
Left for #117 part 2: the provider's image build, clone and storage calls are
76-
synchronous, so a server must run it off its request thread, as Ask does. That
77-
worker should also set TMPDIR to a planning root, as Ask's does, so the input and
78-
auth staging that lane D leaves when it gives up on cleanup is covered. E3's
79-
default 120-second suggestion timeout is shorter than the provider's ten-minute
80-
budget. Startup recovery does not yet remove planning's Docker resources after a
81-
crash, because they are not attempt allocations in the Store. The recording
82-
script prints its runner label if it leaves any.
75+
#117 part 2 wires the provider into the server. Each request runs in planning's
76+
own worker thread (`runner/planning.ts`, `AgentWorker` with `PLANNING_NAMING`),
77+
whose TMPDIR is a planning root recorded in a ledger beside the review database,
78+
so lane D's leftover input and auth staging is covered. Its Docker objects carry
79+
the database's planning owner, apart from Ask's and the runner's, and the first
80+
request of a process removes what earlier sessions left by that owner only. E3's
81+
suggestion timer and the request share one ten-minute budget. The recording
82+
script still runs the provider in its own process and prints its runner label if
83+
it leaves anything.
8384

8485
F/G still own live API and UI integration. The Store now guarantees revision/snapshot
8586
binding and pending-only settlement across processes, and E3 requires the caller's

‎docs/implementation/runner-lifecycle.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -354,10 +354,10 @@ F1 owns the production planning endpoints that G4 needs. They wrap E3's coordina
354354
| `POST /api/plan/import` | `Store.importRevision` | expected revision |
355355
| `POST /api/plan/suggestions` | E3 coordinator start (`beginSuggestions`) | expected revision and snapshot |
356356
| `GET /api/plan/suggestions/:id` | `Store.getSuggestions` | reads only the request row |
357-
| `POST /api/plan/suggestions/:id/cancel` | `pending`: `handle.cancel(reason)` on the `SuggestionHandle` that `SuggestionCoordinator.start()` returned. E3's coordinator has no cancel-by-ID method, so F keeps a map from request ID to handle, adds each handle when it starts the request, and removes it only after the handle's outcome settles. If the request is `pending` but F holds no handle (for example after a restart), F calls `Store.cancelSuggestions`. It is safe to do so because startup recovery has already stopped the crashed process's provider. A live planning provider runs only through D (G4 after D5), in a container labelled with this database's runner owner, and D's `recoverLeftovers` (startup step 2) stops it before admission opens. Until D5 there is no live planning provider at all ("Planning agent not available yet"). If a planning provider ever runs outside D, this endpoint must refuse such a request instead, until startup has reconciled it. `ready`: `Store.cancelSuggestions` (dismiss), because no invocation is running. | request is `pending` or `ready`, as `Store.cancelSuggestions` already allows |
357+
| `POST /api/plan/suggestions/:id/cancel` | `pending`: `handle.cancel(reason)` on the `SuggestionHandle` that `SuggestionCoordinator.start()` returned. E3's coordinator has no cancel-by-ID method, so F keeps a map from request ID to handle, adds each handle when it starts the request, and removes it only after the handle's outcome settles. If the request is `pending` but F holds no handle (for example after a restart), F calls `Store.cancelSuggestions`. It is safe to do so because a crashed process's planning container has no route back to the Store: its output went to that process's worker, which ended with it. A live planning provider runs only through D (#117), in planning's own worker, in containers labelled with this database's planning owner (not the runner's or Ask's). Like Ask's, those containers are removed by D's `recoverLeftovers` for that owner before the first planning request of the next process, not at startup; until then a stray container can keep running read-only (its deadline is enforced from the host, which is gone) until Claude exits or that recovery removes it, and its output is discarded. If a planning provider ever runs outside D, or could report into the Store from another process, this endpoint must refuse such a request instead, until it has been reconciled. `ready`: `Store.cancelSuggestions` (dismiss), because no invocation is running. | request is `pending` or `ready`, as `Store.cancelSuggestions` already allows |
358358
| `POST /api/plan/suggestions/:id/apply` | `Store.applySuggestion` | request `ready` and bound to the current revision and snapshot |
359359

360-
Live planning invocation waits for D5. Until then, the server returns "Planning agent not available yet" instead of using a fake provider.
360+
Live planning runs for a non-demo review with a `github` block (#117): `web/planning.ts` reads the issue from GitHub before each start, and `runner/planning.ts` runs the request in planning's worker. E3's suggestion timer and the request share one ten-minute budget (`PLANNING_BUDGET_MS`). At shutdown E3 aborts every request; one that has not settled within 20 seconds (`PLANNING_SHUTDOWN_GRACE_MS`, as Ask) is ended by abandoning planning's worker. A start replays its recorded outcome before reading GitHub; a GitHub failure is a 502 and is not recorded. Without a `github` block, or in a demo, the server returns "Planning agent not available yet".
361361

362362
## Feedback-event contract (for lane J)
363363

‎runner/planning-provider.ts‎

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import type { InvocationInput, InvocationResult, StopReason } from '../agents/co
55
import type { TaskStorageLimits } from '../agents/container/storage.ts';
66
import type { AuthorProvider, AuthorRequest } from '../core/planning-author.ts';
77
import { allocations, exceedsStorage, RetainedStorage, runReadOnlyAgent, sameContext, type ContainerDependencies, type LeftoverPolicy, type Provider,
8-
type ReadOnlyFeature, type RepositorySize } from './question-container.ts';
8+
type ReadOnlyFeature, type ReadOnlyRun, type RepositorySize } from './question-container.ts';
99

1010
/** Ask's lane D dependencies, less startup recovery, which the runner owns for planning. */
1111
export type PlanningDependencies = Omit<ContainerDependencies, 'recover'>;
@@ -63,7 +63,12 @@ export function removePlanningRoot(root: string): void {
6363
export const PLANNING_STORAGE: TaskStorageLimits = Object.freeze({
6464
workBytes: 512 * 1024 * 1024, workInodes: 131_072, metadataBytes: 512 * 1024 * 1024, metadataInodes: 131_072,
6565
});
66-
const DEFAULT_TIMEOUT_MS = 10 * 60_000;
66+
/**
67+
* The whole budget of one planning request, setup included (#117). Lane D caps the invocation itself at ten minutes,
68+
* and E3's suggestion timer uses this same budget, so the request settles inside it.
69+
*/
70+
export const PLANNING_BUDGET_MS = 10 * 60_000;
71+
const DEFAULT_TIMEOUT_MS = PLANNING_BUDGET_MS;
6772

6873
/** Codex reads files only through its shell, and planning runs no process, so Codex cannot plan (#75, #93). */
6974
export const CODEX_PLANNING_REFUSED = 'Codex cannot write plans yet: it can read the code only by running commands, '
@@ -110,6 +115,22 @@ export const PLANNING_FEATURE: ReadOnlyFeature = Object.freeze({
110115
: new AggregateError(failures, 'Planning container cleanup did not settle.'),
111116
});
112117

118+
/** Where a planning request reads the code: the review's repository at the snapshot's head. */
119+
export interface PlanningSource {
120+
readonly vendor: Provider;
121+
readonly repository: string;
122+
readonly head: string;
123+
readonly snapshotId: string;
124+
}
125+
/** One planning request as a read-only run, without its owner, which the process running it supplies. */
126+
export function planningRun(request: AuthorRequest, source: PlanningSource, deadline: number): Omit<ReadOnlyRun, 'runnerOwner'> {
127+
if (request.phase !== 'planning' || request.access !== 'read-only') throw new Error('Planning requests must be read-only.');
128+
return { provider: source.vendor, repository: source.repository, head: source.head, attemptId: request.requestId,
129+
taskId: `planning-${request.requestId}`, deadline, prompt: request.prompt, schemaText: request.schemaText,
130+
context: { snapshotId: source.snapshotId, planId: request.identity.planId, planRevision: request.revision,
131+
assignmentId: `${request.mode}-${request.issue}`, referencedCodeHash: source.head, stateVersion: 0 } };
132+
}
133+
113134
/**
114135
* E2's provider over lane D: each request runs in a fresh container on a read-only copy of `head`, in the "planning"
115136
* phase (read, list and search only; no commands) with vendor-only egress. The request's schema is the only file in
@@ -129,11 +150,8 @@ export function createPlanningProvider(options: PlanningProviderOptions): Planni
129150
return { async invoke(request: AuthorRequest, signal: AbortSignal): Promise<string> {
130151
if (request.phase !== 'planning' || request.access !== 'read-only') throw new Error('Planning requests must be read-only.');
131152
signal.throwIfAborted();
132-
return runReadOnlyAgent(PLANNING_FEATURE, { provider: vendor, repository: options.repository, head: options.head,
133-
runnerOwner: options.runnerOwner, attemptId: request.requestId, taskId: `planning-${request.requestId}`,
134-
deadline: Date.now() + timeoutMs, prompt: request.prompt, schemaText: request.schemaText,
135-
context: { snapshotId: options.snapshotId, planId: request.identity.planId, planRevision: request.revision,
136-
assignmentId: `${request.mode}-${request.issue}`, referencedCodeHash: options.head, stateVersion: 0 } },
153+
return runReadOnlyAgent(PLANNING_FEATURE, { ...planningRun(request, { vendor, repository: options.repository,
154+
head: options.head, snapshotId: options.snapshotId }, Date.now() + timeoutMs), runnerOwner: options.runnerOwner },
137155
deps, signal, image, retained);
138156
} };
139157
}

‎runner/planning.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import type { AuthorProvider, AuthorRequest } from '../core/planning-author.ts';
2+
import { AgentWorker } from './question-agent.ts';
3+
import { LeftoverLedger, PLANNING_NAMING } from './question-leftovers.ts';
4+
import { PLANNING_BUDGET_MS, planningRun } from './planning-provider.ts';
5+
import type { ReviewService } from './review.ts';
6+
7+
// Leave the worker time to cancel the container and release storage before E3's own timer fires (as Ask does).
8+
const SETTLE_MARGIN_MS = 5_000;
9+
export const NO_PLANNING_AGENT = 'Choose an agent in Settings, then retry.';
10+
11+
/**
12+
* The production planning provider (#117): every request runs in planning's own worker thread, so lane D's synchronous
13+
* setup never blocks the server. The worker's TMPDIR is a planning root recorded in a ledger beside the review
14+
* database, and every Docker object it creates carries the database's planning owner. The first request of a process
15+
* removes what earlier sessions left, by that owner only, so Ask's and the runner's agents are never touched.
16+
*
17+
* The code is the review's repository at the current snapshot's head; E3 discards a reply whose snapshot or revision
18+
* changed meanwhile. The vendor is the one chosen in Settings for Ask; Codex is refused (#93).
19+
*/
20+
export class PlanningAgent implements AuthorProvider {
21+
readonly #service: ReviewService;
22+
readonly #worker: AgentWorker;
23+
constructor(service: ReviewService, options: { url?: URL; env?: Readonly<Record<string, string | undefined>>;
24+
ledger?: LeftoverLedger; abandonAfterDeadlineMs?: number; terminateWaitMs?: number; releaseTimeoutMs?: number } = {}) {
25+
this.#service = service;
26+
// Beside the review database's canonical path, so a restart of the same review finds what an earlier session left.
27+
const ledger = options.ledger ?? LeftoverLedger.forDatabase(service.config.database, PLANNING_NAMING);
28+
this.#worker = new AgentWorker(options.url, ledger, { naming: PLANNING_NAMING, env: options.env,
29+
abandonAfterDeadlineMs: options.abandonAfterDeadlineMs, terminateWaitMs: options.terminateWaitMs,
30+
releaseTimeoutMs: options.releaseTimeoutMs,
31+
runnerOwner: () => service.store.planningOwnerToken(ledger.identity!) });
32+
}
33+
async invoke(request: AuthorRequest, signal: AbortSignal): Promise<string> {
34+
signal.throwIfAborted();
35+
const store = this.#service.store, vendor = store.questionProvider();
36+
if (!vendor) throw new Error(NO_PLANNING_AGENT);
37+
const snapshot = store.getSnapshot(request.identity);
38+
const run = planningRun(request, { vendor, repository: this.#service.reviewRepository().path, head: snapshot.head,
39+
snapshotId: snapshot.id }, Date.now() + PLANNING_BUDGET_MS - SETTLE_MARGIN_MS);
40+
return this.#worker.plan(run, signal);
41+
}
42+
/** Call only after every request has settled (E3's close). Releases what the worker still owns, then stops it. */
43+
close(): Promise<void> { return this.#worker.close(); }
44+
}

0 commit comments

Comments
 (0)