@adecore/agents 0.21.0 → 0.21.2

package/src/chat/ui-queries.ts

@@ -7,10 +7,9 @@ import type {
     ChatInfo,
     ChatUiChoicePayload,
     ChatUiQueryPayload,
-    ChatUiQueryReading,
-    ChatUiQueryState
+    ChatUiQueryReading
 } from '@adecore/agent-contracts';
-import { copyUiValue, UiBudget, type UiValue } from '@adecore/intelligent-ui';
+import { copyUiValue, UI_HOST_LIMITS, UiBudget, uiMayReferenceHost, type UiValue } from '@adecore/intelligent-ui';
 import { UiLinkResolutionSchema, uiLinkTargets, type UiLinkTarget } from '@adecore/intelligent-ui/links';
 import { uiQueryArguments, uiQueryFallback } from '@adecore/intelligent-ui/query';
 import type { UiBlock } from '@adecore/intelligent-ui/compiler';
@@ -36,17 +35,42 @@ interface CachedReading {
     reading: ChatUiQueryReading;
 }
 
+/*
+ * A failure a client can say in its own words: `reason` is a code that stays the same across versions,
+ * the message is the fallback for a client that does not know the code.
+ */
+class UiQueryError extends ChatError<string> {
+    readonly reason: string;
+
+    constructor(code: string, reason: string, message: string) {
+        super(code, message);
+        this.reason = reason;
+    }
+}
+
+/*
+ * What a host's `authorize`, `read` or `link` throws to say why with a code: `code` reaches the reading's
+ * `code` and should stay the same across versions, `reason` is the plain sentence a client shows without it.
+ */
+export class ChatUiRefusal extends UiQueryError {
+    constructor(code: string, reason: string) {
+        super('refused-query', code, reason);
+    }
+}
+
 const MAX_QUERY_BYTES = 64 * 1024;
 const MAX_SNAPSHOT_BYTES = 128 * 1024;
-const MAX_QUERIES = 8;
-const REFRESH_MS = 10_000;
 const READ_TIMEOUT_MS = 8_000;
+// A changed input reads at once, but a query never reads more often than this across its inputs.
+const INPUT_READ_MS = 250;
 
 export class ChatUiQueries {
     readonly schemas: Record<string, z.ZodType>;
-    private readonly captures = new Map<string, Promise<ChatUiQueryState>>();
+    private readonly captures = new Map<string, Promise<unknown>>();
     private readonly freezing = new Set<string>();
     private readonly cache = new Map<string, CachedReading>();
+    // The read id of the newest reading per cache key, which a remount or a second client is answered with.
+    private readonly latest = new Map<string, string>();
     private readonly reading = new Map<string, Promise<ChatUiQueryReading>>();
     private readonly attempts = new Map<string, number>();
     private readonly active = new Map<string, number>();
@@ -60,14 +84,16 @@ export class ChatUiQueries {
     }
 
     observe(session: ChatSession, item: ChatAssistantItem, final: boolean): void {
-        if (!item.text.includes('@Query') && !/<(?:File|Diff|Commit|Node)\b/.test(item.text) && !item.ui?.some((block) => Object.keys(block.queries).length)) {
+        const key = `${session.id}:${item.id}`;
+        // Once a capture started, every delta of a streaming reply would scan its whole text again for nothing.
+        const captured = this.captures.has(key) || item.uiQueries?.authorChatId === session.id;
+        if (!captured && !uiMayReferenceHost(item.text) && !item.ui?.some((block) => Object.keys(block.queries).length)) {
             return;
         }
         const capture = this.access(session, item);
         if (!final || !item.ui?.length) {
             return;
         }
-        const key = `${session.id}:${item.id}`;
         if (this.freezing.has(key)) {
             return;
         }
@@ -84,7 +110,7 @@ export class ChatUiQueries {
                     }
                     const readings: Record<string, ChatUiQueryReading> = Object.create(null);
                     const values: Record<string, unknown> = Object.create(null);
-                    for (const name of Object.keys(block.queries).slice(0, MAX_QUERIES)) {
+                    for (const name of Object.keys(block.queries).slice(0, UI_HOST_LIMITS.queries)) {
                         const reading = await this.query(session, {
                             chatId: session.id,
                             itemId: item.id,
@@ -101,11 +127,11 @@ export class ChatUiQueries {
                     if (this.host.link) {
                         const targets = uiLinkTargets(block, {}, values);
                         const access = await this.access(session, current);
-                        for (const [id, target] of Object.entries(targets).slice(0, 64)) {
+                        for (const [id, target] of Object.entries(targets).slice(0, UI_HOST_LIMITS.links)) {
                             try {
-                                links[id] = this.linkReading(await this.host.link(session.info, access.access, target));
+                                links[id] = this.linkReading(await this.host.link(session.info, access, target));
                             } catch (error) {
-                                links[id] = { state: 'plain', reason: this.reason(error) };
+                                links[id] = { state: 'plain', ...this.failure(error) };
                             }
                         }
                     }
@@ -131,10 +157,12 @@ export class ChatUiQueries {
                         frozen.readings = Object.fromEntries(
                             Object.keys(readings).map((name) => [
                                 name,
-                                { state: 'failed', readAt: Date.now(), reason: 'The frozen query values are too large.' }
+                                { state: 'failed', readAt: Date.now(), code: 'snapshot-too-large', reason: 'The frozen query values are too large.' }
                             ])
                         );
-                        frozen.links = Object.fromEntries(Object.keys(links).map((id) => [id, { state: 'plain', reason: 'This link must be checked again.' }]));
+                        frozen.links = Object.fromEntries(
+                            Object.keys(links).map((id) => [id, { state: 'plain', code: 'link-unchecked', reason: 'This link must be checked again.' }])
+                        );
                         frozen.fallback = `${block.fallback.slice(0, 2048)}\nSources: ${names}\nThe frozen query values are too large.`;
                     }
                     if (Buffer.byteLength(JSON.stringify(blocks)) > MAX_SNAPSHOT_BYTES) {
@@ -147,17 +175,19 @@ export class ChatUiQueries {
             .finally(() => this.freezing.delete(key));
     }
 
-    private access(session: ChatSession, item: ChatAssistantItem): Promise<ChatUiQueryState> {
+    /* The writer's access for a reply, captured once; null where it was denied or is unavailable. */
+    private access(session: ChatSession, item: ChatAssistantItem): Promise<unknown> {
         const key = `${session.id}:${item.id}`;
         const existing = this.captures.get(key);
         if (existing) {
             return existing;
         }
         if (item.uiQueries?.authorChatId === session.id) {
-            return Promise.resolve(item.uiQueries);
+            return Promise.resolve(session.uiAccess(item.id) ?? null);
         }
         // A pending capture is persisted as denied, so a restart cannot widen the writer's rights.
-        session.updateUiQueries(item.id, { authorChatId: session.id, access: null, blocks: {} });
+        session.setUiAccess(item.id, null);
+        session.updateUiQueries(item.id, { authorChatId: session.id, blocks: {} });
         const captured = this.host
             .capture(session.info)
             .then((access) => {
@@ -165,11 +195,10 @@ export class ChatUiQueries {
                 if (Buffer.byteLength(JSON.stringify(captured)) > 32 * 1024) {
                     throw new Error('The UI access snapshot is too large.');
                 }
-                const state: ChatUiQueryState = { authorChatId: session.id, access: captured, blocks: {} };
-                session.updateUiQueries(item.id, state);
-                return state;
+                session.setUiAccess(item.id, captured);
+                return captured as unknown;
             })
-            .catch(() => ({ authorChatId: session.id, access: null, blocks: {} }))
+            .catch(() => null)
             .finally(() => this.captures.delete(key));
         this.captures.set(key, captured);
         return captured;
@@ -183,19 +212,19 @@ export class ChatUiQueries {
         const block =
             item?.kind === 'assistant' && !item.streaming && !item.parentToolUseId ? item.ui?.find((entry) => entry.id === payload.blockId) : undefined;
         if (item?.kind !== 'assistant' || !block?.complete || block.revision !== payload.revision) {
-            throw new ChatError('stale-ui-block', 'This completed UI block is no longer available.');
+            throw new UiQueryError('stale-ui-block', 'block-stale', 'This completed UI block is no longer available.');
         }
         return { item, block };
     }
 
     private stored(session: ChatSession, payload: ChatUiQueryPayload): { item: ChatAssistantItem; block: UiBlock; source: ChatUiSource } {
         const { item, block } = this.storedBlock(session, payload);
-        if (!Object.hasOwn(block.queries, payload.query) || Object.keys(block.queries).length > MAX_QUERIES) {
-            throw new ChatError('refused-query', 'This block does not declare an allowed query.');
+        if (!Object.hasOwn(block.queries, payload.query) || Object.keys(block.queries).length > UI_HOST_LIMITS.queries) {
+            throw new UiQueryError('refused-query', 'query-undeclared', 'This block does not declare an allowed query.');
         }
         const name = block.queries[payload.query].source;
         if (!Object.hasOwn(this.host.sources, name)) {
-            throw new ChatError('refused-query', 'This query source is not registered.');
+            throw new UiQueryError('refused-query', 'source-unregistered', 'This query source is not registered.');
         }
         return { item, block, source: this.host.sources[name] };
     }
@@ -210,18 +239,17 @@ export class ChatUiQueries {
             ({ source, block, item } = this.stored(session, payload));
             args = uiQueryArguments(block, payload.query, payload.values);
             args = source.args.parse(args) as Record<string, UiValue>;
-            const access = await this.access(session, item);
-            if (access.access === null) {
-                throw new ChatError('refused-query', 'The writer’s original access is unavailable.');
+            authorAccess = await this.access(session, item);
+            if (authorAccess === null) {
+                throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
             }
-            authorAccess = access.access;
             await source.authorize(session.info, authorAccess, args);
         } catch (error) {
-            return { state: 'refused', readAt: Date.now(), reason: this.reason(error) };
+            return { state: 'refused', readAt: Date.now(), ...this.failure(error) };
         }
         const key = JSON.stringify([session.id, item.id, block.id, block.revision, payload.query, args]);
-        const cached = [...this.cache.values()].find((entry) => entry.key === key);
-        if (cached && Date.now() - cached.reading.readAt < REFRESH_MS) {
+        const cached = this.cache.get(this.latest.get(key) ?? '');
+        if (cached && Date.now() - cached.reading.readAt < UI_HOST_LIMITS.refreshMilliseconds) {
             return cached.reading;
         }
         const pending = this.reading.get(key);
@@ -229,14 +257,19 @@ export class ChatUiQueries {
             return pending;
         }
         const identity = JSON.stringify([session.id, item.id, block.id, block.revision, payload.query]);
-        if (Date.now() - (this.attempts.get(identity) ?? 0) < REFRESH_MS) {
-            return { state: 'failed', readAt: Date.now(), reason: 'This query may refresh once every ten seconds.' };
+        const now = Date.now();
+        if (
+            now - (this.attempts.get(key) ?? -Infinity) < UI_HOST_LIMITS.refreshMilliseconds ||
+            now - (this.attempts.get(identity) ?? -Infinity) < INPUT_READ_MS
+        ) {
+            return { state: 'failed', readAt: now, code: 'refresh-limit', reason: 'This query may refresh once every ten seconds.' };
         }
         if ((this.active.get(session.id) ?? 0) >= 2 || this.totalActive >= 16) {
-            return { state: 'failed', readAt: Date.now(), reason: 'Too many UI queries are being read.' };
+            return { state: 'failed', readAt: now, code: 'busy', reason: 'Too many UI queries are being read.' };
         }
-        this.attempts.set(identity, Date.now());
-        while (this.attempts.size > 128) {
+        this.attempts.set(key, now);
+        this.attempts.set(identity, now);
+        while (this.attempts.size > 256) {
             this.attempts.delete(this.attempts.keys().next().value!);
         }
         this.active.set(session.id, (this.active.get(session.id) ?? 0) + 1);
@@ -247,21 +280,26 @@ export class ChatUiQueries {
         timeout.unref?.();
         const read = Promise.race([
             work,
-            new Promise<never>((_, reject) => controller.signal.addEventListener('abort', () => reject(new Error('The UI query timed out.')), { once: true }))
+            new Promise<never>((_, reject) =>
+                controller.signal.addEventListener('abort', () => reject(new UiQueryError('refused-query', 'timed-out', 'The UI query timed out.')), {
+                    once: true
+                })
+            )
         ])
             .then((result): ChatUiQueryReading => {
                 const value = copyUiValue(source.result.parse(result), new UiBudget());
                 if (Buffer.byteLength(JSON.stringify(value)) > MAX_QUERY_BYTES) {
-                    throw new Error('The UI query result is too large.');
+                    throw new UiQueryError('refused-query', 'result-too-large', 'The UI query result is too large.');
                 }
                 const reading: ChatUiQueryReading = { state: 'fresh', value, readId: randomUUID(), readAt: Date.now() };
                 this.cache.set(reading.readId!, { key, chatId: session.id, reading });
+                this.latest.set(key, reading.readId!);
                 while (this.cache.size > 128) {
-                    this.cache.delete(this.cache.keys().next().value!);
+                    this.evict(this.cache.keys().next().value!);
                 }
                 return reading;
             })
-            .catch((error): ChatUiQueryReading => ({ state: 'failed', readAt: Date.now(), reason: this.reason(error) }))
+            .catch((error): ChatUiQueryReading => ({ state: 'failed', readAt: Date.now(), ...this.failure(error) }))
             .finally(() => {
                 clearTimeout(timeout);
                 this.reading.delete(key);
@@ -282,32 +320,41 @@ export class ChatUiQueries {
         return read;
     }
 
+    /* The issued value of every query the block declares, each checked against the read id the person saw. */
     async choiceValues(session: ChatSession, payload: ChatUiChoicePayload | ChatUiLinkPayload): Promise<Record<string, unknown>> {
         const item = session.thread.get(payload.itemId);
         const block = item?.kind === 'assistant' ? item.ui?.find((entry) => entry.id === payload.blockId) : undefined;
         if (!block || item?.kind !== 'assistant' || ('choiceId' in payload && item.uiAnswers?.[block.id]?.revision === payload.revision)) {
             return {};
         }
+        const names = Object.keys(block.queries);
         const values: Record<string, unknown> = Object.create(null);
-        for (const name of Object.keys(payload.reads ?? {})) {
-            const identity = { ...payload, query: name };
-            const { source } = this.stored(session, identity);
+        if (names.length === 0) {
+            return values;
+        }
+        const access = await this.access(session, item);
+        if (access === null) {
+            throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
+        }
+        for (const name of names) {
+            const { source } = this.stored(session, { ...payload, query: name });
             const args = source.args.parse(uiQueryArguments(block, name, payload.values)) as Record<string, UiValue>;
-            const access = await this.access(session, item);
-            await source.authorize(session.info, access.access, args);
+            await source.authorize(session.info, access, args);
+            const readId = payload.reads !== undefined && Object.hasOwn(payload.reads, name) ? payload.reads[name] : undefined;
             const key = JSON.stringify([session.id, item.id, block.id, block.revision, name, args]);
-            const readId = payload.reads![name];
-            const cached = this.cache.get(readId);
+            const cached = readId === undefined ? undefined : this.cache.get(readId);
             const frozen = item.uiQueries?.blocks[block.id];
             const snapshot = frozen?.revision === block.revision ? frozen?.readings[name] : undefined;
             const reading =
-                cached?.key === key
-                    ? cached.reading
-                    : snapshot?.readId === readId && JSON.stringify(args) === JSON.stringify(source.args.parse(uiQueryArguments(block, name)))
-                      ? snapshot
-                      : undefined;
+                readId === undefined
+                    ? undefined
+                    : cached?.key === key
+                      ? cached.reading
+                      : snapshot?.readId === readId && JSON.stringify(args) === JSON.stringify(source.args.parse(uiQueryArguments(block, name)))
+                        ? snapshot
+                        : undefined;
             if (!reading || reading.state !== 'fresh') {
-                throw new ChatError('stale-ui-query', 'Refresh this query before sending its choice.');
+                throw new UiQueryError('stale-ui-query', 'stale-read', 'Refresh this query before sending its choice.');
             }
             values[name] = reading.value;
         }
@@ -317,35 +364,43 @@ export class ChatUiQueries {
     async link(session: ChatSession, payload: ChatUiLinkPayload): Promise<ChatUiLinkReading> {
         try {
             if (!this.host.link) {
-                throw new ChatError('refused-query', 'This host does not provide UI links.');
+                throw new UiQueryError('refused-query', 'links-unsupported', 'This host does not provide UI links.');
             }
             const { item, block } = this.storedBlock(session, payload);
             if (!item.uiQueries) {
-                throw new ChatError('refused-query', 'The writer’s original access is unavailable.');
+                throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
             }
             const access = await this.access(session, item);
-            if (access.access === null) {
-                throw new ChatError('refused-query', 'The writer’s original access is unavailable.');
+            if (access === null) {
+                throw new UiQueryError('refused-query', 'access-unavailable', 'The writer’s original access is unavailable.');
             }
             const queries = await this.choiceValues(session, payload);
             const target = uiLinkTargets(block, payload.values, queries)[payload.nodeId];
             if (!target) {
-                throw new ChatError('refused-query', 'This visible node is not a supported link.');
+                throw new UiQueryError('refused-query', 'link-unsupported', 'This visible node is not a supported link.');
             }
-            return this.linkReading(await this.host.link(session.info, access.access, target));
+            return this.linkReading(await this.host.link(session.info, access, target));
         } catch (error) {
-            return { state: 'plain', reason: this.reason(error) };
+            return { state: 'plain', ...this.failure(error) };
         }
     }
 
     forget(chatId: string): void {
         for (const [id, cached] of this.cache) {
             if (cached.chatId === chatId) {
-                this.cache.delete(id);
+                this.evict(id);
             }
         }
     }
 
+    private evict(readId: string): void {
+        const cached = this.cache.get(readId);
+        this.cache.delete(readId);
+        if (cached && this.latest.get(cached.key) === readId) {
+            this.latest.delete(cached.key);
+        }
+    }
+
     private linkReading(value: unknown): ChatUiLinkReading {
         const reading = UiLinkResolutionSchema.parse(copyUiValue(value, new UiBudget()));
         if (reading.state === 'chip' && !reading.target) {
@@ -354,7 +409,8 @@ export class ChatUiQueries {
         return reading;
     }
 
-    private reason(error: unknown): string {
-        return (error instanceof Error ? error.message : 'This query could not be read.').slice(0, 240);
+    private failure(error: unknown): { reason: string; code?: string } {
+        const reason = (error instanceof Error ? error.message : 'This query could not be read.').slice(0, 240);
+        return error instanceof UiQueryError ? { reason, code: error.reason } : { reason };
     }
 }

package/src/chat/visual-store.ts

@@ -113,6 +113,13 @@ function tooLarge(bytes: number): never {
     );
 }
 
+function refuseOversized(html: string): void {
+    const bytes = Buffer.byteLength(html, 'utf8');
+    if (bytes > VISUAL_LIMITS.bytes) {
+        tooLarge(bytes);
+    }
+}
+
 /*
  * The visuals of every chat. The list of a chat is one file beside its record under `<home>/chats`;
  * each page is a file in the chat's attachment folder, `<id>.html`, so whatever serves an attachment
@@ -164,9 +171,7 @@ export class VisualStore {
         if (html.trim() === '') {
             refuse('visual-invalid', 'The page is empty; pass one self-contained HTML document');
         }
-        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
-            tooLarge(Buffer.byteLength(html, 'utf8'));
-        }
+        refuseOversized(html);
         return this.writeWorkspaceFile(chatId, name, html);
     }
 
@@ -178,9 +183,7 @@ export class VisualStore {
     async publish(chatId: string, input: VisualInput): Promise<ChatVisual> {
         const { title, html, maxHeight, layout, heights } = checked(input);
         // Before the bootstrap is added, so a page far too large is never copied first.
-        if (Buffer.byteLength(html, 'utf8') > VISUAL_LIMITS.bytes) {
-            tooLarge(Buffer.byteLength(html, 'utf8'));
-        }
+        refuseOversized(html);
         const page = Buffer.from(injectVisualBootstrap(html), 'utf8');
         if (page.byteLength > VISUAL_LIMITS.bytes) {
             tooLarge(page.byteLength);

package/src/chat/wake-chat.ts

@@ -2,7 +2,10 @@ import type { ChatItem } from '@adecore/agent-contracts';
 import type { ChatCore } from './chat-core.ts';
 import type { ChatSession } from './chat-session.ts';
 
-/* A chat the host may open a turn in, as the outbox handlers see it: what its thread holds, and the one call that opens one, false while a turn or an owed resume is in the way. */
+/*
+ * A chat the host may open a turn in, as the outbox handlers see it. `wake` answers false while a
+ * turn or an owed resume is in the way.
+ */
 export interface WakeChat {
     items(): ChatItem[];
     persist?(): Promise<void>;

package/src/context/refusal.ts

@@ -1,8 +1,7 @@
 /*
  * How every no reads: `refused`, the code a script branches on and the sentence a model reads, and
- * under it a line per thing the actor can do instead. One row per line, and a line is a row of
- * tab-separated fields of its own, so only a newline is taken out of it: that would split the row in
- * two, and everything under the first row is read as advice.
+ * under it a line per thing the actor can do instead. A line keeps its tabs but loses its newlines,
+ * since everything under the first row is read as advice.
  */
 
 /* A field that goes into a tab-separated line; a tab or a newline in a title would split the row. */
@@ -24,10 +23,7 @@ export function refusalBody(code: string, message: string, lines: readonly strin
     return [`refused\t${first}`, ...rest].join('\n');
 }
 
-/*
- * The same without the word that names it, for a host that adds the prefix in its CLI:
- * The context CLI puts the prefix on, so a CLI of an older build still prints one refusal.
- */
+/* Without the `refused` prefix, for a host whose CLI adds it, so a CLI of an older build still prints one refusal. */
 export function refusalRows(code: string, message: string, lines: readonly string[] = []): string {
     return rows(code, message, lines).join('\n');
 }

package/src/context/verb.ts

@@ -382,11 +382,7 @@ export function requiredField(needs: string): z.ZodString {
     return z.string({ error: needs }).min(1, needs);
 }
 
-/*
- * What a refusal lists, or one line saying the set is empty. A refusal that promises the groups of a
- * canvas and then prints nothing reads as a daemon that lost them, where the truth is that there are
- * none, which is a different thing to do something about.
- */
+/* A refusal that promises a list and prints nothing reads as a host that lost it, where there is none. */
 export function orNote(lines: string[], note: string): string[] {
     return lines.length === 0 ? [`note\t${note}`] : lines;
 }

package/src/host/agent-host.ts

@@ -24,8 +24,8 @@ function isAgentRequest(type: string): type is AgentRequestType {
 
 /*
  * The chats of an app that has no daemon: it answers the agent requests over any `FramePort` and
- * sends the agent events back on it, frames checked on arrival. One port is one client. Closing the host writes every thread and ends every CLI; a chat
- * goes on at the next start through its CLI's own session.
+ * sends the agent events back on it, frames checked on arrival. One port is one client. A chat
+ * closed with the host goes on at the next start through its CLI's own session.
  */
 export class AgentHost<Core extends ChatCore = ChatCore> {
     readonly chats: Core;

package/src/host/handlers.ts

@@ -66,7 +66,7 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
                 { delivery: payload.delivery, mentions: payload.mentions, skills: payload.skills, chats: payload.chats },
                 payload.attachments
             ),
-        'chat.uiChoice': (payload) => chats.choose(payload),
+        'chat.uiChoice': (payload, clientId) => chats.choose(payload, clientId),
         'ui.link': (payload, clientId) => chats.linkUi(payload, clientId),
         'ui.query': (payload, clientId) => chats.queryUi(payload, clientId),
         'chat.unqueue': (payload) => ({ message: chats.unqueue(payload.chatId, payload.messageId) }),
@@ -116,7 +116,6 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
     };
 }
 
-/* The accounts are the person's settings of this host. */
 export function accountHandlers(accounts: ProviderAccountsService): { [T in AccountRequestType]: AgentHandler<T> } {
     return {
         'accounts.list': () => accounts.snapshot(),

package/src/host/wiring.ts

@@ -9,12 +9,12 @@ import { VisualStore } from '../chat/visual-store.ts';
 import type { ClaudeBackendOptions } from '../chat/claude-backend.ts';
 import { ClaudeTitleReader } from '../chat/claude-title.ts';
 import { DEFAULT_CODEX_CLIENT, type CodexClientInfo } from '../chat/codex-transport.ts';
+import { errorText } from '../error-text.ts';
 import type { AgentEvent } from '../events.ts';
 import { definedEnv } from '../providers/accounts/launch.ts';
 import { ProviderAccountsService } from '../providers/accounts/service.ts';
 import type { AccountsHost } from '../providers/accounts/variables.ts';
 import { createClaudeProvider } from '../providers/claude-provider.ts';
-import { errorText } from '../error-text.ts';
 import { createCodexProvider } from '../providers/codex-provider.ts';
 import { codexRulesPathIn, defaultCodexHome, installCodexRules, type CodexRules } from '../providers/codex-rules.ts';
 import { ProviderRegistry, type ProviderRegistryOptions } from '../providers/registry.ts';

package/src/lineage.ts

@@ -30,8 +30,8 @@ function openedByAgent(entry: Lineage): boolean {
 }
 
 /*
- * Lineage lives in `lineage` under the host's data folder, outside the agent-writable project, so agents
- * cannot reset their own depth. Persisting it also prevents a restart of the host from resetting recursion limits.
+ * Lives under the host's data folder, outside the agent-writable project, so an agent cannot reset its
+ * own depth; on disk, so a restart of the host does not reset it either.
  */
 export class AgentLineageStore {
     readonly dir: string;
@@ -140,7 +140,6 @@ export class AgentLineageStore {
         return entry?.relation === 'fork' ? entry.openedBy : null;
     }
 
-    /* The forks made from a chat. */
     forksOf(nodeId: string): string[] {
         return [...this.opened.all()].filter((entry) => entry.relation === 'fork' && entry.openedBy === nodeId).map((entry) => entry.nodeId);
     }

package/src/messages/deliver-message.ts

@@ -24,13 +24,11 @@ export interface DeliverMessageDeps {
 }
 
 /*
- * Opens the turn a message earns a chat. The messages themselves are not carried here: they wait in
- * the notice store and the turn's preamble takes them (`NoticeNotes`), the same channel a person's
- * own prompt reads them through, so one message is heard once whichever of the two opens the turn.
+ * Opens the turn a message earns a chat. The messages wait in the notice store and the turn's preamble
+ * takes them (`NoticeNotes`), as a person's own prompt does, so a message is heard once either way.
  *
- * One attempt, never `wait`. A chat that turned out to be in a turn reads the message in front of its
- * next one, which is what a message to a busy chat has always done; holding the entry instead would
- * make the host start turns nobody asked for long after the news was worth anything.
+ * One attempt, never `wait`: a chat already in a turn reads the message in front of its next one, and
+ * holding the entry would start turns nobody asked for long after the news mattered.
  */
 export function deliverMessageHandler(deps: DeliverMessageDeps) {
     return async (entry: DeliverMessageEntry): Promise<OutboxOutcome> => {
@@ -46,11 +44,8 @@ export function deliverMessageHandler(deps: DeliverMessageDeps) {
         if (chat === null) {
             return;
         }
-        /*
-         * No note of its own, and the preamble stays off the thread. A person read the message as it
-         * landed (`showNotices`), so anything the turn adds about it only says the same thing again;
-         * the label on the turn already names who it came from.
-         */
+        // No note and no preamble on the thread: a person read the message as it landed (`showNotices`),
+        // and the label on the turn names who it came from.
         chat.wake({
             text: deps.words.prompt(waiting.length),
             label: deps.words.label(waiting),

package/src/messages/deliver-notice.ts

@@ -33,11 +33,10 @@ export interface ChatDelivery {
 }
 
 /*
- * Whether the turn a chat is running was itself opened by a message. This is the whole of the stop:
- * two agents that read each other would otherwise wake each other for as long as they kept writing,
- * and nothing about that started with a person. It rides on the turn, so it survives a restart.
+ * Whether the turn a chat is running was itself opened by a message, which stops two agents that
+ * read each other from waking each other forever. It rides on the turn, so it survives a restart.
  * Between turns the last one counts, since work it left running (a background subagent) may still
- * write, and a turn the CLI opened by itself goes on with the step of the turn before it.
+ * write, and a turn the CLI opened by itself takes the step of the turn before it.
  */
 export function turnFromMessage(items: readonly ChatItem[], activeTurnId: string | null): boolean {
     const from = activeTurnId === null ? items.findLastIndex((item) => item.kind === 'turn') : items.findIndex((item) => item.id === activeTurnId);
@@ -76,10 +75,9 @@ export function chatNoticeTargets(chats: Pick<ChatCore, 'get' | 'hasStored'>): C
 
 /*
  * One message on its way to a chat, and whether the chat owes a turn on it. A chat between turns gets
- * one, the way a settled task gives one: a person watching two agents cannot tell a message from an
- * assignment, and a message nobody starts a turn for sits there until someone happens to prompt that
- * chat. One step deep, so the turn a message opened wakes nobody with a message of its own. A node the
- * host runs something else in, such as a terminal, is the host's to deliver to before this.
+ * one, as for a settled task, or the message sits there until someone happens to prompt that chat.
+ * One step deep: the turn a message opened wakes nobody with a message of its own. A node that runs
+ * something else, such as a terminal, is the host's to deliver to before this.
  */
 export async function deliverToChat(store: Pick<NoticeStore, 'put'>, targets: ChatNoticeTargets, notice: Omit<Notice, 'createdAt'>): Promise<ChatDelivery> {
     const waiting = await store.put(notice);
@@ -105,10 +103,8 @@ export interface NoticeChat {
 }
 
 /*
- * What a chat has to show a person, in its thread, the moment a message lands and not when the model
- * gets round to it: without this a message left for a busy node is a file on disk and nothing else.
- * An id no chat holds shows nothing and marks nothing, so the chat that opens on that id later still
- * has all of it.
+ * Shows a person the message in the chat's thread the moment it lands, not when the model gets round
+ * to it. An id no chat holds shows and marks nothing, so a chat that opens on it later still has all of it.
  */
 export async function showNotices(store: Pick<NoticeStore, 'show'>, chat: NoticeChat, words: Pick<MessageWords, 'shown'>, targetId: string): Promise<void> {
     if (!(await chat.has(targetId))) {

package/src/messages/notice-store.ts

@@ -7,10 +7,8 @@ import { RecordDirectory } from '../record-directory.ts';
 export const MAX_NOTICES = 10;
 
 /*
- * A message nobody picked up in this long is dropped rather than delivered. It is news about work
- * happening now ("the build is green"), and a model reading it six hours late would act on
- * something that has moved on. The cap alone would not do it: one message in a queue of one waits
- * for ever.
+ * A message is news about work happening now ("the build is green"), and a model reading it six hours
+ * late would act on something that moved on. The cap alone would leave a queue of one waiting forever.
  */
 export const NOTICE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
 
@@ -131,7 +129,7 @@ export class NoticeStore {
         return this.now() - notice.createdAt < NOTICE_MAX_AGE_MS;
     }
 
-    /* The queue of one node, emptied here and on disk both; an empty one leaves no file behind. */
+    /* In memory and on disk both; an empty queue leaves no file behind. */
     private async persist(targetId: string, queue: Notice[]): Promise<void> {
         if (queue.length === 0) {
             await this.queues.remove(targetId);