@adecore/agents 0.21.1 → 0.21.2

package/dist/usage/scanner.js

@@ -1,12 +1,12 @@
 import { mkdir, open, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { errorText } from '../error-text.js';
 import { isNotFound, writeAtomic } from '../fs.js';
 import { decodeIndex, encodeIndex } from './index-file.js';
 import { foldByKey } from './record.js';
 import { claudeMightCarryUsage, parseClaudeLine } from './readers/claude.js';
 import { cloneCodexState, codexMightCarryUsage, createCodexState, parseCodexLine } from './readers/codex.js';
 import { usageRoots } from './roots.js';
-import { errorText } from '../error-text.js';
 /* What a file holds from `from` to its end, as it is at the read. */
 async function readFrom(path, from) {
     const handle = await open(path, 'r');
@@ -53,11 +53,11 @@ async function listJsonl(dir, out = []) {
  * read again next time. The Codex state is snapshotted before that tail for the same reason.
  */
 function parseChunk(text, provider, from, state) {
-    let records = [];
     const end = text.lastIndexOf('\n');
     const whole = end === -1 ? '' : text.slice(0, end);
     const tail = text.slice(end + 1);
     const read = (chunk, codex) => {
+        const records = [];
         for (const raw of chunk.split('\n')) {
             const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
             if (line === '') {
@@ -79,14 +79,12 @@ function parseChunk(text, provider, from, state) {
                 }
             }
         }
+        return records;
     };
     const codex = provider === 'codex' ? (state ?? createCodexState()) : null;
-    read(whole, codex);
+    const counted = read(whole, codex);
     const committed = codex === null ? null : cloneCodexState(codex);
-    const counted = records;
-    records = [];
-    read(tail, codex);
-    return { records: counted, tail: records, offset: from + (end === -1 ? 0 : Buffer.byteLength(whole, 'utf8') + 1), codex: committed };
+    return { records: counted, tail: read(tail, codex), offset: from + (end === -1 ? 0 : Buffer.byteLength(whole, 'utf8') + 1), codex: committed };
 }
 /*
  * The account a record of a root belongs to, as a record keeps it (absent for the default account):
@@ -113,8 +111,8 @@ function withAccount(records, accountOf) {
     });
 }
 /*
- * Read appended transcript bytes incrementally, but restart after rewrites or truncation. Preserve
- * totals for deleted transcripts because their usage still happened.
+ * Reads only what a transcript appended since the last scan, and starts a file over once it was
+ * rewritten or cut. A deleted transcript keeps its totals, since its usage still happened.
  */
 export class UsageScanner {
     home;

package/dist/usage/usage-service.d.ts

@@ -1,8 +1,8 @@
 import type { UsageAccount, UsageSummaryPayload, UsageSummaryResult } from '@adecore/agent-contracts';
 import type { AgentSink } from '../events.ts';
 import type { KnownProject } from './projects.ts';
-import { type UsageScannerOptions } from './scanner.ts';
 import type { UsageRootPath } from './roots.ts';
+import { type UsageScannerOptions } from './scanner.ts';
 export interface UsageServiceOptions {
     home: string;
     allowPriceFetch?: boolean;
@@ -31,5 +31,4 @@ export declare class UsageService {
     stop(): void;
     private rescan;
     private runScan;
-    private emit;
 }

package/dist/usage/usage-service.js

@@ -1,9 +1,9 @@
+import { ClientSinks } from '../client-sinks.js';
+import { errorText } from '../error-text.js';
 import { accountOfRecord, aggregate } from './aggregate.js';
 import { ExchangeRates } from './exchange.js';
 import { PriceBook } from './pricing.js';
 import { UsageScanner } from './scanner.js';
-import { errorText } from '../error-text.js';
-import { ClientSinks } from '../client-sinks.js';
 /* A scan this fresh answers the question the page is asking, so nothing is opened for it. */
 const SCAN_TTL_MS = 60_000;
 /* The accounts of the machine, and after them any a record names that the machine no longer has, under its id. */
@@ -121,10 +121,7 @@ export class UsageService {
         }
         this.report = report;
         if (report.changedFiles > 0) {
-            this.emit({ event: 'usage.changed', payload: { scannedAt: report.at } });
+            this.sinks.emit({ event: 'usage.changed', payload: { scannedAt: report.at } });
         }
     }
-    emit(event) {
-        this.sinks.emit(event);
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -20,8 +20,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.21.1",
-    "@adecore/intelligent-ui": "0.21.1",
+    "@adecore/agent-contracts": "0.21.2",
+    "@adecore/intelligent-ui": "0.21.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/async.ts

@@ -1,9 +1,6 @@
-/* The two waits the host does: a pause it can be woken from, and a deadline on somebody else's promise. */
-
 /*
- * Resolves after `ms`, or at once when the signal is raised. An abort ends the wait rather than
- * failing it: every caller here is a loop that checks the signal itself on the next turn, and a
- * rejection would only be caught and thrown away.
+ * Resolves after `ms`, or at once when the signal is raised. An abort resolves instead of rejecting:
+ * every caller is a loop that checks the signal itself on its next turn.
  */
 export function wait(ms: number, signal?: AbortSignal): Promise<void> {
     return new Promise((resolve) => {
@@ -19,10 +16,7 @@ export function wait(ms: number, signal?: AbortSignal): Promise<void> {
     });
 }
 
-/*
- * The promise, or `message` when it takes longer than `ms`. The timer is cleared either way, so a
- * call that answers at once does not hold the process for the rest of its deadline.
- */
+/* The timer is cleared either way, so a call that answers at once does not hold the process until its deadline. */
 export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error(message)), ms);

package/src/chat/chat-core.ts

@@ -27,7 +27,6 @@ import {
     type ModelSelection,
     type RuntimeMode
 } from '@adecore/agent-contracts';
-import { ChatUiQueries, type ChatUiHost } from './ui-queries.ts';
 import { ClientSinks } from '../client-sinks.ts';
 import { errorText } from '../error-text.ts';
 import type { AgentEvent, AgentSink } from '../events.ts';
@@ -38,6 +37,7 @@ import { SkillIndex } from '../skills.ts';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
 import { usageRoots } from '../usage/roots.ts';
 import type { AttachmentStore } from './attachment-store.ts';
+import { commandLabel, isBackgroundWork, runsInBackground, type BackgroundWork } from './background-work.ts';
 import type { BookmarkStore } from './bookmark-store.ts';
 import { ChatLog, COMPACT_ABOVE_BYTES } from './chat-log.ts';
 import type { SpawnChatProcess } from './chat-process.ts';
@@ -57,10 +57,10 @@ import type { CodexProcessSpec } from './codex-thread.ts';
 import type { CodexClientInfo } from './codex-transport.ts';
 import { ComposerPreferences } from './composer-preferences.ts';
 import { DeltaCoalescer } from './delta-coalescer.ts';
-import { readableAssistantText } from './readable-text.ts';
 import { ChatError } from './errors.ts';
-import { commandLabel, isBackgroundWork, runsInBackground, type BackgroundWork } from './background-work.ts';
+import { readableAssistantText } from './readable-text.ts';
 import { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
+import { ChatUiQueries, type ChatUiHost } from './ui-queries.ts';
 import type { VisualInput, VisualStore } from './visual-store.ts';
 
 /* A turn that was running when the host went down, and the attempt that would take it up again. */
@@ -72,12 +72,12 @@ export interface InterruptedRun {
 
 type BookmarkableItem = Extract<ChatItem, { kind: 'user' | 'assistant' }>;
 
-/* A message a person or the agent wrote in the chat's own thread; a subagent's words belong to its row. */
 function withoutHidden(info: ChatInfo): ChatInfo {
     const { hidden: _hidden, ...rest } = info;
     return rest;
 }
 
+/* A message a person or the agent wrote in the chat's own thread; a subagent's words belong to its row. */
 function isBookmarkable(item: ChatItem): item is BookmarkableItem {
     return item.kind === 'user' || (item.kind === 'assistant' && (item.parentToolUseId ?? null) === null);
 }

package/src/chat/chat-log.ts

@@ -48,8 +48,8 @@ export interface ChatLogState {
 }
 
 /*
- * Number and synchronously append each broadcast event so disk, memory and snapshot boundaries keep
- * one order. Recent lines stay in memory for immediate `since` attachment.
+ * Numbers every broadcast event and appends it synchronously, so disk, memory and snapshot boundaries
+ * keep one order. Recent lines stay in memory to answer an attach with `since` at once.
  */
 export class ChatLog {
     private readonly path: string | null;

package/src/chat/chat-store.ts

@@ -4,12 +4,12 @@ import { join } from 'node:path';
 import { ChatInfoSchema, ChatItemSchema, type ChatInfo, type ChatItem } from '@adecore/agent-contracts';
 import { z } from 'zod';
 import { isNotFound, writeAtomic, writeAtomicSync } from '../fs.ts';
-import { isBookmarkFileName } from './bookmark-store.ts';
+import { recordFileName } from '../record-directory.ts';
 import { migrateInlineAttachments, type AttachmentStore } from './attachment-store.ts';
+import { isBookmarkFileName } from './bookmark-store.ts';
 import { parseLog, type ChatLogLine } from './chat-log.ts';
 import { ChatThread } from './thread.ts';
 import { isVisualFileName } from './visual-store.ts';
-import { recordFileName } from '../record-directory.ts';
 
 // zod strips what it does not know inside the info and the items, so a file written by an older build
 // (with `interactionMode`, say) still parses and loses only the dropped field. A record without `seq`
@@ -30,7 +30,7 @@ const OWN_KEYS = new Set(['info', 'items', 'seq', 'resetSeq', 'preambles', 'uiAc
 /* What a host keeps in a chat's record beside the thread; it never reaches the wire. */
 export type ChatRecordExtras = Record<string, unknown>;
 
-function extrasOf(record: Record<string, unknown>): ChatRecordExtras {
+function withoutOwnKeys(record: Record<string, unknown>): ChatRecordExtras {
     return Object.fromEntries(Object.entries(record).filter(([key]) => !OWN_KEYS.has(key)));
 }
 
@@ -90,10 +90,6 @@ function liftUiAccess(record: unknown): unknown {
     return Object.keys(uiAccess).length === 0 ? record : { ...record, uiAccess };
 }
 
-function withoutOwnKeys(extras: ChatRecordExtras): ChatRecordExtras {
-    return Object.fromEntries(Object.entries(extras).filter(([key]) => !OWN_KEYS.has(key)));
-}
-
 export interface ChatStoreOptions {
     attachments?: AttachmentStore | null;
     // Files a host keeps beside a record under names that also end in .json (a chat's plans), which are no chats.
@@ -214,7 +210,7 @@ export class ChatStore {
             resetSeq,
             preambles: snapshot.preambles ?? [],
             uiAccess: snapshot.uiAccess ?? {},
-            extras: extrasOf(snapshot),
+            extras: withoutOwnKeys(snapshot),
             lines
         };
     }

package/src/chat/chat-title.ts

@@ -1,7 +1,7 @@
 import type { AgentKind } from '@adecore/agent-contracts';
-import { cleanTitle } from '../title-file.ts';
 import type { ProviderRegistry } from '../providers/registry.ts';
 import { runProcess } from '../run-process.ts';
+import { cleanTitle } from '../title-file.ts';
 
 // Enough of a conversation to name it; the rest of a long prompt or answer says nothing a title needs.
 const MAX_PROMPT_CHARS = 2000;
@@ -19,10 +19,7 @@ function cap(text: string, limit: number): string {
     return text.length <= limit ? text : `${text.slice(0, limit)}...`;
 }
 
-/*
- * What the CLI is asked. JSON again, as for a commit message: a model left to write freely opens
- * with a sentence, and that sentence would become the name of the node.
- */
+/* JSON, since a model left to write freely opens with a sentence, and that sentence would become the name. */
 export function buildTitlePrompt(prompt: string, answer: string): string {
     return [
         'Write a short title for the conversation below, as a person would name it in a list of chats.',
@@ -42,9 +39,8 @@ export function buildTitlePrompt(prompt: string, answer: string): string {
 }
 
 /*
- * The title out of what the CLI printed, or null. Strict on purpose, unlike a commit message: a run
- * that holds no `{"title": "..."}` object printed something other than a title, and a derived name
- * is better than a stray line of it.
+ * Strict on purpose: a run that holds no `{"title": "..."}` object printed something other than a
+ * title, and a derived name is better than a stray line of it.
  */
 export function parseTitle(output: string): string | null {
     const start = [...output.matchAll(/\{\s*"title"/g)].at(-1)?.index;

package/src/chat/claude-backend.ts

@@ -1,5 +1,5 @@
-import { errorText } from '../error-text.ts';
 import { randomUUID } from 'node:crypto';
+import { errorText } from '../error-text.ts';
 import { claudeArgs, claudeEnv, promptPrefix } from '../providers/claude.ts';
 import type { ApprovalDecision, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 import { ChatChild } from './chat-process.ts';
@@ -71,12 +71,10 @@ export class ClaudeBackend implements ChatBackend {
     }
 
     sendTurn(input: TurnInput): void {
-        // The prefix is what the CLI must see first (ultrathink), then the note about the links, then what was typed.
-        const prefix = `${promptPrefix(this.launch.selection)}${input.preamble === null ? '' : `${input.preamble}\n\n`}`;
         const promptId = input.promptId ?? randomUUID();
         this.active = true;
         this.protocol.beginPrompt(promptId);
-        this.write(buildUserMessage({ text: input.text, attachments: input.attachments, prefix, skills: input.skills, promptId }));
+        this.write(this.userMessage(input, promptId));
     }
 
     steerTurn(input: TurnInput): Promise<boolean> {
@@ -88,8 +86,7 @@ export class ClaudeBackend implements ChatBackend {
             this.steers.set(promptId, { resolve, reject });
             this.protocol.beginSteer(promptId);
             try {
-                const prefix = `${promptPrefix(this.launch.selection)}${input.preamble === null ? '' : `${input.preamble}\n\n`}`;
-                this.write(buildUserMessage({ text: input.text, attachments: input.attachments, prefix, skills: input.skills, promptId }));
+                this.write(this.userMessage(input, promptId));
             } catch (error) {
                 this.steers.delete(promptId);
                 reject(error instanceof Error ? error : new Error(errorText(error)));
@@ -147,6 +144,12 @@ export class ClaudeBackend implements ChatBackend {
         return child?.end() ?? Promise.resolve();
     }
 
+    private userMessage(input: TurnInput, promptId: string): Record<string, unknown> {
+        // What the CLI must see first (ultrathink), then the preamble, then what was typed.
+        const prefix = `${promptPrefix(this.launch.selection)}${input.preamble === null ? '' : `${input.preamble}\n\n`}`;
+        return buildUserMessage({ text: input.text, attachments: input.attachments, prefix, skills: input.skills, promptId });
+    }
+
     private async readLines(child: ChatChild): Promise<void> {
         const reader = child.process.stdout.getReader();
         const decoder = new TextDecoder();

package/src/chat/claude-title.ts

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { usageRoots } from '../usage/roots.ts';
 import { cleanTitle, readLines } from '../title-file.ts';
+import { usageRoots } from '../usage/roots.ts';
 
 interface Progress {
     offset: number;

package/src/chat/claude-transcript.ts

@@ -5,8 +5,8 @@ import type { ChatHistoryResult, ChatItem } from '@adecore/agent-contracts';
 import { readLines } from '../title-file.ts';
 import { ClaudeProtocol } from './claude-protocol.ts';
 import { readingThread, settledReading } from './subagent-projection.ts';
-import type { ChatThread } from './thread.ts';
 import type { ThreadProjector } from './projector.ts';
+import type { ChatThread } from './thread.ts';
 
 const CHUNK_BYTES = 4 * 1024 * 1024;
 

package/src/chat/codex-backend.ts

@@ -1,11 +1,11 @@
 import { accessSync, constants } from 'node:fs';
 import { attachmentImageMime, type ChatSkill } from '@adecore/agent-contracts';
+import { errorText } from '../error-text.ts';
 import { codexServiceTier, codexThreadOptions } from '../providers/codex.ts';
 import type { ApprovalDecision, BackendEvent, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
 import { CodexProtocol } from './codex-protocol.ts';
-import { attachmentNote } from './input.ts';
 import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo, type CodexFrame } from './codex-transport.ts';
-import { errorText } from '../error-text.ts';
+import { attachmentNote } from './input.ts';
 
 function textInput(text: string) {
     return [{ type: 'text', text, text_elements: [] }];
@@ -46,18 +46,15 @@ export interface CodexBackendOptions {
  */
 export class CodexBackend implements ChatBackend {
     readonly acknowledgesTurns = true;
-    private promptId: string | null = null;
     private readonly launch: BackendLaunch;
-    private imageWrites: Promise<void> | null = null;
     private readonly host: BackendHost;
     private readonly protocol: CodexProtocol;
     private readonly client: CodexClientInfo;
+    private promptId: string | null = null;
+    private imageWrites: Promise<void> | null = null;
     private transport: CodexTransport | null = null;
     private threadId = '';
-    /*
-     * Codex 0.154 ignores developer instructions on `thread/resume` (measured), so a thread started
-     * before anything was linked would never hear of its links; the first prompt of a resumed process says so instead.
-     */
+    // Codex 0.154 ignores developer instructions on `thread/resume` (measured), so the first prompt of a resumed process carries them.
     private contextPending: string | null = null;
     private imageInputSupported: boolean | null = null;
     /* A turn asked for that Codex has not named yet; `turn/interrupt` needs that name. */

package/src/chat/codex-protocol.ts

@@ -172,7 +172,7 @@ function elicitationInput(meta: Frame): Frame {
     return input;
 }
 
-// Every spent window must reset; one unknown reset keeps resuming a person's choice.
+// The latest reset of every spent window; one without a known reset leaves resuming to a person.
 function spentUntil(windows: readonly UsageWindow[]): number | null {
     const spent = windows.filter((window) => window.used >= 1);
     if (spent.length === 0 || spent.some((window) => window.resetsAt === null)) {

package/src/chat/codex-thread.ts

@@ -1,10 +1,10 @@
 import type { ChatItem } from '@adecore/agent-contracts';
+import { errorText } from '../error-text.ts';
 import type { SpawnChatProcess } from './chat-process.ts';
 import { CodexProtocol } from './codex-protocol.ts';
 import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo } from './codex-transport.ts';
 import { ChatError } from './errors.ts';
 import { readingThread, settledReading } from './subagent-projection.ts';
-import { errorText } from '../error-text.ts';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -116,14 +116,15 @@ async function nthTurnId(transport: CodexTransport, threadId: string, turns: num
     let seen = 0;
     let cursor: string | null = null;
     do {
-        const page = await transport.request('thread/turns/list', { threadId, limit: 100, sortDirection: 'asc', ...(cursor === null ? {} : { cursor }) });
-        const data = isRecord(page) && Array.isArray(page.data) ? page.data.filter(isRecord) : [];
-        for (const turn of data) {
+        const page = parseThreadItemsPage(
+            await transport.request('thread/turns/list', { threadId, limit: 100, sortDirection: 'asc', ...(cursor === null ? {} : { cursor }) })
+        );
+        for (const turn of page.entries) {
             if (++seen === turns) {
                 return typeof turn.id === 'string' ? turn.id : null;
             }
         }
-        cursor = isRecord(page) && typeof page.nextCursor === 'string' && page.nextCursor !== '' ? page.nextCursor : null;
+        cursor = page.nextCursor;
     } while (cursor !== null);
     return null;
 }

package/src/chat/composer-preferences.ts

@@ -15,9 +15,8 @@ interface Held {
 
 /*
  * What each connected client says a new chat starts with, for the chats the host starts with no
- * client mounting them. Held per socket like the approval switch: a machine never remembers a
- * person's pick after that person's client is gone, so with nobody connected a chat gets the
- * host's own defaults.
+ * client mounting them. Held per client only, so with nobody connected a chat gets the host's own
+ * defaults rather than the pick of a person who left.
  */
 export class ComposerPreferences {
     private readonly byClient = new Map<string, Held>();

package/src/chat/limit-resume.ts

@@ -5,13 +5,8 @@ export const LIMIT_RETRY_DELAYS_MS: readonly number[] = [60_000, 5 * 60_000, 15
 
 /* The last turn of a thread, when it stopped on a limit. */
 export function limitedTurn(items: readonly ChatItem[]): (ChatTurnItem & { limit: ChatTurnLimit }) | null {
-    for (let i = items.length - 1; i >= 0; i--) {
-        const item = items[i]!;
-        if (item.kind === 'turn') {
-            return item.state === 'error' && item.limit !== undefined ? (item as ChatTurnItem & { limit: ChatTurnLimit }) : null;
-        }
-    }
-    return null;
+    const last = items.findLast((item) => item.kind === 'turn');
+    return last?.kind === 'turn' && last.state === 'error' && last.limit !== undefined ? (last as ChatTurnItem & { limit: ChatTurnLimit }) : null;
 }
 
 /* How many turns in a row, up to and including this one, stopped on a limit: the tries a person did not step in between. */

package/src/chat/thread.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
 import { ChatError } from './errors.ts';
 import { requestSummaries } from './request-summary.ts';
-import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
 
 /*
  * The state of one chat as the client sees it. Every mutation answers the event that describes

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

@@ -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);
     }