Skip to content

Commit a032034

Browse files
authored
Merge pull request #908 from taras/agent/issue-907-core-comment-cleanup
Simplify project comments and enforce banned words
2 parents 9c4f4f9 + 6ebcceb commit a032034

378 files changed

Lines changed: 2166 additions & 3067 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.oxlint-prose.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"ignorePatterns": [
3+
"**/node_modules/**",
4+
"site/_fresh/**",
5+
"site/vendor/**",
6+
"site/*.timestamp-*.mjs"
7+
],
8+
"categories": { "correctness": "off" },
9+
"jsPlugins": [{ "name": "local", "specifier": "./scripts/oxlint-plugin.js" }],
10+
"rules": { "local/no-banned-jsdoc-words": "error" }
11+
}

‎.oxlintrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
"rules": {
1616
"eslint/curly": "error",
17+
"local/no-banned-jsdoc-words": "error",
1718
"local/no-module-scoped-registry": "error",
1819
"local/no-section-divider-comments": "error",
1920
"local/no-sync-filesystem": "error",

‎AGENTS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,12 @@ the corpus or enabling in-shard concurrency is not an answer to a miss.
503503
alternatives, defensive qualifications, and exhaustive detail that does not
504504
help a reader understand or use the design.
505505

506+
### Banned words
507+
508+
Avoid words in the canonical [banned-words list](scripts/banned-words.js) when
509+
writing architecture prose or JSDoc. Choose wording for the specific meaning;
510+
keep literal code references intact. `deno task lint` enforces the list.
511+
506512
### Component descriptions
507513

508514
Write a component description for an author deciding what to type. Lead with an

‎architecture.md‎

Lines changed: 86 additions & 85 deletions
Large diffs are not rendered by default.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@
7575
"test:node": "tsx scripts/runtime-tests.ts node",
7676
"test:bun": "bun scripts/runtime-tests.ts bun",
7777
"test:deno": "deno task test",
78-
"lint": "oxlint -c .oxlintrc.json --ignore-pattern 'scripts/tests/fixtures/**' --ignore-pattern '**/npm/**' --ignore-pattern 'packages/workflow/vendor/cloudflare-computer-dofs/**' --ignore-pattern 'packages/acp/vendor/acpx/**' --ignore-pattern 'packages/cli/src/repl/vendor/freedom/**' packages scripts && oxfmt --check packages scripts && pnpm run lint:dead-code",
78+
"lint": "oxlint -c .oxlintrc.json --ignore-pattern 'scripts/tests/fixtures/**' --ignore-pattern '**/npm/**' --ignore-pattern 'packages/workflow/vendor/cloudflare-computer-dofs/**' --ignore-pattern 'packages/acp/vendor/acpx/**' --ignore-pattern 'packages/cli/src/repl/vendor/freedom/**' packages scripts && oxlint -c .oxlint-prose.json site smoke-test && node scripts/lint-architecture.js && oxfmt --check packages scripts && pnpm run lint:dead-code",
7979
"lint:dead-code": "knip --config knip.json --no-progress --no-config-hints --include files,exports,types",
8080
"fmt": "oxfmt --write packages scripts"
8181
},

‎packages/acp/src/adapter-snapshots.ts‎

Lines changed: 47 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,27 @@
11
/**
2-
* The ACP adapters a workflow run executes, and how they reach the disk
3-
* (`packages/acp/vendor/adapters/PROVENANCE.md`).
4-
*
5-
* A workflow Prompt needs an adapter that names the turn it just completed, on
6-
* `_meta`. No published adapter does yet, so this repository carries one npm
7-
* tarball per provider — packed from an exact patched upstream commit by that
8-
* project's own build — and runs those instead of whatever `npx` would resolve.
9-
*
10-
* ## Why the bytes travel in the module graph
11-
*
12-
* A tarball on disk is unreachable from a compiled binary and from the npm
13-
* artifact. The same bytes are therefore carried as a generated module, which
14-
* every distribution inlines identically, and this module writes them out. One
15-
* mechanism, so "the source tree, the npm package and the binary all run the
16-
* same adapter" is a fact rather than three arrangements that happen to agree.
17-
*
18-
* ## Content-addressed, so identity is the location
19-
*
20-
* A snapshot materializes under its own SHA-256. Two runs asking for the same
21-
* adapter name the same directory, a changed snapshot names a different one,
22-
* and nothing has to decide whether an existing directory is current — the
23-
* question does not arise.
24-
*
25-
* ## Identity is not the launch path
26-
*
27-
* Two different things are needed, and conflating them was a defect: an adapter
28-
* has a **stable identity** — its provider, package, version and snapshot
29-
* digest — and a **host-local launch path** under whatever root this machine
30-
* materialized into.
31-
*
32-
* Only the identity is durable. It is what a retained Agent session records and
33-
* what a sealed artifact carries, so two machines running the same snapshot
34-
* agree, and a run exported from one is readable on the other. The path appears
35-
* nowhere durable: it names a directory that exists on one host, and putting it
36-
* in an artifact would make where a file happened to live a compatibility term.
37-
*
38-
* The launch path is quoted, because a root containing a space is an ordinary
39-
* thing on a developer's machine and an unquoted command would split there.
40-
*
41-
* ## Published atomically, verified before use
42-
*
43-
* Materialization happens in a private temporary directory and is published by
44-
* one rename. A concurrent run either wins that rename or finds the directory
45-
* already there — both then verify before using it, so nobody executes a tree
46-
* another process is still filling.
47-
*
48-
* Replacing an *abandoned* tree is the one step that cannot be done by rename
49-
* alone, because a rename will not overwrite a non-empty directory. Removing it
50-
* first is a decision that goes stale: another attempt may publish a valid tree
51-
* between the observation and the removal, and deleting that would pull the
52-
* files out from under an adapter already running. So recovery is serialized on
53-
* an exclusive claim, and the holder re-checks under it before removing
54-
* anything.
55-
*
56-
* The claim is a ticket: the directory `claims/<n>`, taken by renaming a
57-
* prepared directory onto that name, which only one attempt can win and which
58-
* is never handed out a second time.
59-
*
60-
* Two properties come from that, and the claim needs both. Because numbers are
61-
* never reissued, finishing a dead holder's ticket can only ever act on the
62-
* exact ticket that was inspected. Because they are taken in ascending order,
63-
* an attempt arriving later cannot obtain a lower number, so it cannot come to
64-
* precede a holder that has already been elected.
65-
*
66-
* The holder is the lowest ticket still outstanding. Releasing is marking one
67-
* finished, and a process killed mid-recovery leaves a ticket whose owner a
68-
* later attempt reads as dead and finishes on its behalf.
69-
*
70-
* ## It refuses; it never falls back
71-
*
72-
* A digest that does not match, an extraction that fails, a dependency install
73-
* that fails, a missing entry file: each raises. Running the published adapter
74-
* instead would be running one that emits no token, which is the state this
75-
* exists to leave — silently, and after the run had already been told it was
76-
* continuing an exact conversation.
2+
* Materialize the patched ACP adapters that report completed-turn `_meta`
3+
* (`packages/acp/vendor/adapters/PROVENANCE.md`). Their npm tarballs come from
4+
* exact patched upstream commits and travel as a generated module so source, npm
5+
* and compiled distributions execute identical bytes.
6+
*
7+
* A snapshot materializes under its SHA-256. Durable identity is provider, package,
8+
* version and digest; the quoted host-local launch path is never retained in a
9+
* session or sealed artifact.
10+
*
11+
* Stage privately, publish by one rename and verify the published tree before
12+
* use, including when another attempt won. Recovery of an abandoned non-empty
13+
* tree requires exclusive ownership of recovery and a fresh check before
14+
* removal, otherwise a stale observation could delete another process's newly
15+
* published valid adapter.
16+
*
17+
* Recovery tickets are prepared directories atomically renamed to `claims/<n>`.
18+
* Tickets increase monotonically and are never reused: late arrivals cannot
19+
* precede an elected holder, and finishing a dead holder cannot affect a later
20+
* ticket. The lowest unfinished ticket owns recovery; release marks it
21+
* finished, and a later attempt may finish a dead owner's ticket.
22+
*
23+
* Digest, extraction, installation or missing-entry failures raise. Falling back
24+
* to a published adapter would lose the turn identity continuation depends on.
7725
*/
7826

7927
import { ensureDir, exists, readTextFile, rm, writeTextFile } from "@effectionx/fs";
@@ -120,10 +68,10 @@ const RECOVERY_ATTEMPTS = 400;
12068
const OWNER = "owner";
12169
const DONE = "done";
12270

123-
/** A ceiling on ticket numbers, so a pathological claims directory cannot spin. */
71+
/** A ceiling on ticket numbers, so a pathological recovery-ticket directory cannot spin. */
12472
const MAX_TICKETS = 10_000;
12573

126-
/** Who holds a recovery claim, so a later attempt can tell live from dead. */
74+
/** Who holds a recovery ticket, so a later attempt can tell live from dead. */
12775
interface RecoveryOwner {
12876
readonly pid: number;
12977
readonly host: string;
@@ -150,7 +98,7 @@ function parseOwner(raw: string): RecoveryOwner | undefined {
15098
* Signal 0 asks without delivering anything. `EPERM` means it exists and
15199
* belongs to somebody else, which is still alive; only `ESRCH` means gone. An
152100
* answer this cannot interpret is treated as alive, so an unreadable state
153-
* never becomes a reason to take somebody's claim.
101+
* never becomes a reason to take somebody's recovery ownership.
154102
*/
155103
function alive(pid: number): boolean {
156104
try {
@@ -431,10 +379,10 @@ export function createEmbeddedAdapters(
431379
* on. An attempt arriving later cannot obtain a number below one already
432380
* taken, so it cannot come to sit ahead of a holder.
433381
*
434-
* Ordering names by time could not offer that. Two claims made in the same
435-
* millisecond were separated only by the random part of their names, and a
436-
* clock adjustment could hand a later arrival an earlier name — either way an
437-
* elected holder could be preceded after the fact.
382+
* Ordering names by time could not offer that. Two recovery tickets issued in
383+
* the same millisecond were separated only by the random part of their names,
384+
* and a clock adjustment could hand a later arrival an earlier name — either
385+
* way an elected holder could be preceded after the fact.
438386
*/
439387
function* takeTicket(claims: string): Operation<number> {
440388
yield* ensureDir(claims);
@@ -465,15 +413,15 @@ export function createEmbeddedAdapters(
465413
}
466414

467415
/**
468-
* Whether this attempt now holds the claim.
416+
* Whether this attempt now owns recovery.
469417
*
470418
* The holder is the lowest ticket still outstanding, so every number below
471-
* this attempt's own is examined in order: a finished ticket is passed over, a
472-
* ticket whose owner is a dead process on this host is finished here, and a
419+
* this attempt's own is examined in order: a finished ticket is passed over,
420+
* a ticket whose owner is a dead process on this host is finished here, and a
473421
* live owner, an owner on another machine, or a record that cannot be read
474422
* each stop the election where it stands. The last one says so, because
475423
* refusing to act on what it cannot read is the only safe reading of somebody
476-
* else's claim.
424+
* else's recovery ticket.
477425
*
478426
* Finishing a dead holder's ticket is safe for the reason the election is:
479427
* the number is never reissued, so this can only ever act on the exact ticket
@@ -518,17 +466,18 @@ export function createEmbeddedAdapters(
518466
}
519467

520468
/**
521-
* Replace an abandoned tree at the target, holding an exclusive claim.
469+
* Replace an abandoned tree at the target, under exclusive ownership of
470+
* recovery.
522471
*
523-
* Reached only when the rename failed and what is there does not verify. The
524-
* claim makes "check, then remove" one decision instead of two: without it, a
525-
* second attempt could publish a valid tree in the gap and this one would
526-
* delete it, taking the files out from under an adapter that had already
527-
* resolved and might already be running.
472+
* Reached only when the rename failed and what is there does not verify.
473+
* Exclusive recovery ownership makes "check, then remove" one decision
474+
* instead of two: without it, a second attempt could publish a valid tree in
475+
* the gap and this one would delete it, taking the files out from under an
476+
* adapter that had already resolved and might already be running.
528477
*
529-
* An attempt that does not hold the claim never removes anything. It waits
530-
* and answers from what the holder published — including when the wait ends
531-
* with this attempt elected, because a holder finishes its ticket only after
478+
* An attempt that does not own recovery never removes anything. It waits and
479+
* answers from what the holder published — including when the wait ends with
480+
* this attempt elected, because a holder finishes its ticket only after
532481
* publishing.
533482
*/
534483
function* recover(
@@ -690,9 +639,9 @@ export function createEmbeddedAdapters(
690639
*
691640
* A closed registry was the wrong shape for the same reason. It made "this
692641
* build has no Codex snapshot problem to solve for Gemini" into "this build
693-
* refuses Gemini", which is a much larger claim than the one being made, and it
694-
* would have changed the retained identity of agents the checkpoint work has
695-
* nothing to say about.
642+
* refuses Gemini", which is a much broader restriction than the one being made,
643+
* and it would have changed the retained identity of agents the checkpoint work
644+
* has nothing to say about.
696645
*
697646
* The overlay is *qualified*: an embedded provider never falls through. A
698647
* snapshot that cannot be verified or materialized refuses the agent, and does

‎packages/acp/src/checkpoint.ts‎

Lines changed: 8 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,14 @@
11
/**
2-
* Which provider turn a completed Prompt was, as this package reads it.
2+
* Read a completed Prompt's opaque provider turn identity from `_meta`.
33
*
4-
* ACP carries per-response metadata under `_meta`, and an adapter that knows
5-
* how to name its own turns puts that name there. The runtime carries the whole
6-
* value across untouched and recognizes nothing in it, because which keys mean
7-
* something is this package's decision rather than a transport's.
4+
* Recognized identities are `_meta.codex.turnId` (App Server turn id) and
5+
* `_meta.claudeCode.assistantMessageUuid` (assistant message uuid). The runtime
6+
* passes metadata through; this package discards every other field.
87
*
9-
* Two namespaces mean something here, one per adapter, and each is the
10-
* adapter's own:
11-
*
12-
* | Adapter | Where it says it | What that is |
13-
* | --- | --- | --- |
14-
* | Codex | `_meta.codex.turnId` | the App Server turn id |
15-
* | Claude | `_meta.claudeCode.assistantMessageUuid` | the assistant message uuid |
16-
*
17-
* Everything else in `_meta` is discarded. Quota, failure detail and whatever
18-
* else an adapter reports are that adapter's business; nothing here reads them,
19-
* and nothing here treats an unfamiliar key as a checkpoint because it happens
20-
* to look like one.
21-
*
22-
* The value is opaque. It is compared, never interpreted: this does not check
23-
* it against a UUID grammar, does not shorten or normalize it, and does not
24-
* reconstruct one from anything else. Transcript text repeats, another turn's
25-
* token is a different turn, a provider's current head is a later point in the
26-
* conversation, and prompt or journal position is order rather than identity —
27-
* so a completion that names no turn simply names none.
28-
*
29-
* Ambiguity is refused for the same reason. Two adapters both claiming one turn
30-
* is two answers to which conversation this was, and there is no rule for
31-
* choosing between them, so such a completion carries no checkpoint at all.
8+
* Exactly one recognized non-empty string yields a checkpoint. Missing or
9+
* ambiguous identities yield none; transcript text, current session head and
10+
* journal position never substitute for one. Values are compared unchanged,
11+
* without UUID validation or normalization.
3212
*/
3313

3414
import type { AgentPromptCheckpoint } from "@executablemd/core";

‎packages/acp/src/native-launch.ts‎

Lines changed: 10 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,17 @@
22
* Native launcher adapters (specs/native-agent-session-launch-spec.md
33
* §Provider-native identity).
44
*
5-
* An adapter knows one thing a document must never state: the argv that makes
6-
* a particular coding-agent CLI resume one exact provider-native session.
7-
* `claude --resume <id>` and `codex resume <id>` are adapter implementation
8-
* details, not authored values, and neither an executable path nor a session
9-
* id ever appears in a document.
5+
* Adapters own native resume argv; executable paths and provider-native session
6+
* ids are never document inputs. Command knowledge alone grants no launch:
7+
* `provider-returned` adapters must prove ACP and the native UI reach the same
8+
* conversation; `client-allocated` adapters must prove native creation uses the
9+
* allocated identity, applies private instructions to the first user turn without
10+
* a bootstrap, and later resumes that conversation.
1011
*
11-
* Knowing the command shape is not the same as being launch-capable.
12-
* Advertisement is separate, and what an adapter has to prove depends on who
13-
* names its sessions. An adapter the provider names proves that the session
14-
* ACP created is the session the native UI resumes; an adapter that names its
15-
* own sessions creates one directly, so what it proves instead is that the
16-
* native process makes that exact conversation, that the private instruction
17-
* layer governs its first user turn without a bootstrap, and that a later
18-
* invocation resumes the same identity rather than making a second one.
19-
* Until an adapter has proven its own contract against the installed CLI,
20-
* `<Session.Launch>` refuses that agent before anything of the session moves —
21-
* before a provider-returned adapter's ACP session is released, and before a
22-
* client-allocated one allocates an identity or writes a private file. That is
23-
* the failure the contract asks for rather than a hopeful spawn.
24-
*
25-
* Adapters differ along two structural axes, and both are discriminated rather
26-
* than inferred. The first is who chooses the provider-native session identity:
27-
* a `provider-returned` adapter can only resume a session something else
28-
* created and named, while a `client-allocated` adapter names the session first
29-
* and hands that name to the native process, which is what lets a launch
30-
* construct a conversation instead of merely reattaching to one. The second is
31-
* whether the adapter pins the build behind its executable, and it is
32-
* independent of the first: a name means one conversation only beside the build
33-
* that issued or accepted it, whichever side chose the name.
12+
* Until that contract is proven against the installed CLI, launch refuses before
13+
* ACP detach, client identity allocation or private-file creation. Build pinning
14+
* is an independent discriminator: either construction route may bind a session
15+
* to the exact executable build that issued or accepted its identity.
3416
*/
3517

3618
import { randomUUID } from "node:crypto";

0 commit comments

Comments
 (0)