@adecore/agents 0.23.1 → 0.24.0

package/dist/coordination/index.d.ts

@@ -0,0 +1,15 @@
+export { type OutboxEntryOf, OutboxStore, type OutboxWorkShape, type OutboxEntryFields, type OutboxStoreOptions } from '../outbox/outbox.ts';
+export { RETRY_DELAYS_MS, type OutboxClock, systemClock, type OutboxOutcome, type OutboxHandlers, OutboxWorker, type OutboxWorkerOptions } from '../outbox/outbox-worker.ts';
+export { restartBackgroundLimits, type RestartedOutbox } from '../tasks/background-limit.ts';
+export { EndChildrenWorkSchema, endChildren, type EndChildrenWork, type EndChildrenEntry, type EndChildrenOutbox, type EndChildrenDeps, type EndChildren } from '../tasks/end-children.ts';
+export { type TaskCoordinatorDeps, TaskCoordinator } from '../tasks/task-coordinator.ts';
+export { TaskStore, type TaskListener, type TaskEvent, type TaskSink } from '../tasks/task-store.ts';
+export { BackgroundLimitWorkSchema, WakeParentWorkSchema, GiveTaskWorkSchema, DeliverWaitingWorkSchema, type BackgroundLimitWork, type WakeParentWork, type GiveTaskWork, type DeliverWaitingWork, type TaskWork, type BackgroundLimitEntry, type AnyOutboxEntry, type TaskOutbox } from '../tasks/task-work.ts';
+export { type ChatRequests, chatRequests, WAITING_GRACE_MS, WaitingObserver, type WaitingRequest, type WaitingObserverDeps, type WaitingWords } from '../tasks/waiting-child.ts';
+export { RESULT_PREVIEW_BYTES, wakePrompt } from '../tasks/wake-parent.ts';
+export { type TaskVerbs, type TaskWords, wireTasks, type TaskChats, type TaskRecord, type TaskWiringDeps, type TaskWiring } from '../tasks/wiring.ts';
+export { DeliverMessageWorkSchema, deliverMessageHandler, type DeliverMessageWork, type DeliverMessageEntry, type DeliverMessageDeps } from '../messages/deliver-message.ts';
+export { type MessageWords, type ChatNoticeTargets, type ChatDelivery, chatNoticeTargets, deliverToChat, showNotices, type NoticeChat } from '../messages/deliver-notice.ts';
+export { NoticeNotes, unshownNotes } from '../messages/notice-notes.ts';
+export { MAX_NOTICES, NOTICE_MAX_AGE_MS, type Notice, NoticeStore } from '../messages/notice-store.ts';
+export { AgentLineageStore } from '../lineage.ts';

package/dist/coordination/index.js

@@ -0,0 +1,16 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { OutboxStore } from '../outbox/outbox.js';
+export { RETRY_DELAYS_MS, systemClock, OutboxWorker } from '../outbox/outbox-worker.js';
+export { restartBackgroundLimits } from '../tasks/background-limit.js';
+export { EndChildrenWorkSchema, endChildren } from '../tasks/end-children.js';
+export { TaskCoordinator } from '../tasks/task-coordinator.js';
+export { TaskStore } from '../tasks/task-store.js';
+export { BackgroundLimitWorkSchema, WakeParentWorkSchema, GiveTaskWorkSchema, DeliverWaitingWorkSchema } from '../tasks/task-work.js';
+export { chatRequests, WAITING_GRACE_MS, WaitingObserver } from '../tasks/waiting-child.js';
+export { RESULT_PREVIEW_BYTES, wakePrompt } from '../tasks/wake-parent.js';
+export { wireTasks } from '../tasks/wiring.js';
+export { DeliverMessageWorkSchema, deliverMessageHandler } from '../messages/deliver-message.js';
+export { chatNoticeTargets, deliverToChat, showNotices } from '../messages/deliver-notice.js';
+export { NoticeNotes, unshownNotes } from '../messages/notice-notes.js';
+export { MAX_NOTICES, NOTICE_MAX_AGE_MS, NoticeStore } from '../messages/notice-store.js';
+export { AgentLineageStore } from '../lineage.js';

package/dist/host/handlers.js

@@ -27,6 +27,10 @@ export function chatHandlers(chats, providers) {
             await chats.stopTask(payload.chatId, payload.taskId);
             return {};
         },
+        'chat.goal': async (payload) => {
+            await chats.goal(payload.chatId, payload.action);
+            return {};
+        },
         'chat.detach': (payload, clientId) => {
             chats.detach(payload.chatId, clientId);
             return {};
@@ -78,6 +82,10 @@ export function chatHandlers(chats, providers) {
             await chats.kill(payload.chatId);
             return {};
         },
+        'chat.restart': async (payload) => {
+            await chats.restart(payload.chatId);
+            return {};
+        },
         'chat.list': () => ({ chats: chats.list() })
     };
 }

package/dist/host/index.d.ts

@@ -0,0 +1,7 @@
+export { AgentHost, type AgentHostOptions } from './agent-host.ts';
+export { RUIMTE_SESSION_VARIABLES, cliEnvironment, type CliEnvironmentPolicy } from './environment.ts';
+export { type AgentHandler, type AgentHandlers, chatHandlers, accountHandlers, usageHandlers, type AgentRequestMap, type ChatRequestType } from './handlers.ts';
+export { memoryPortPair } from './memory-port.ts';
+export { type AgentWiring, wireAgents, type AgentWiringOptions } from './wiring.ts';
+export { ClientSinks } from '../client-sinks.ts';
+export type { AgentEvent, AgentEventMap, AgentSink } from '../events.ts';

package/dist/host/index.js

@@ -0,0 +1,7 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { AgentHost } from './agent-host.js';
+export { RUIMTE_SESSION_VARIABLES, cliEnvironment } from './environment.js';
+export { chatHandlers, accountHandlers, usageHandlers } from './handlers.js';
+export { memoryPortPair } from './memory-port.js';
+export { wireAgents } from './wiring.js';
+export { ClientSinks } from '../client-sinks.js';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { wait, withTimeout } from './async.ts';
+export { CodedError } from './coded-error.ts';
+export { describeError, setErrorStacks, errorText } from './error-text.ts';
+export { tempNameFor, writeAtomic, replaceSync, writeAtomicSync, isNotFound, fileExists, type WriteAtomicOptions } from './fs.ts';
+export { recordFileName, RecordDirectory, type RecordDirectoryOptions } from './record-directory.ts';
+export { runProcess, type ProcessResult, type RunProcessOptions } from './run-process.ts';
+export { Serializer, KeyedSerializer } from './serializer.ts';
+export { cleanTitle, readLines } from './title-file.ts';
+export { type DirectoryWatcher, type WatchSeams, supportsRecursive, SYSTEM_WATCH, type Settled, settled, PerClientWatches, type WatchDirectory, type Schedule } from './watch-seam.ts';

package/dist/index.js

@@ -0,0 +1,10 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { wait, withTimeout } from './async.js';
+export { CodedError } from './coded-error.js';
+export { describeError, setErrorStacks, errorText } from './error-text.js';
+export { tempNameFor, writeAtomic, replaceSync, writeAtomicSync, isNotFound, fileExists } from './fs.js';
+export { recordFileName, RecordDirectory } from './record-directory.js';
+export { runProcess } from './run-process.js';
+export { Serializer, KeyedSerializer } from './serializer.js';
+export { cleanTitle, readLines } from './title-file.js';
+export { supportsRecursive, SYSTEM_WATCH, settled, PerClientWatches } from './watch-seam.js';

package/dist/providers/accounts/status.js

@@ -1,3 +1,4 @@
+import { isRecord } from '@adecore/agent-contracts';
 import { withTimeout } from '../../async.js';
 import { CodexTransport } from '../../chat/codex-transport.js';
 import { runProcess } from '../../run-process.js';
@@ -6,9 +7,6 @@ const ASK_TIMEOUT_MS = 20_000;
 function text(value) {
     return typeof value === 'string' && value !== '' ? value : null;
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /* `claude auth status --json`, as Claude Code 2.1.282 prints it: `loggedIn`, `email`, `orgName`, `subscriptionType`. */
 export function readClaudeAuthStatus(output) {
     let status;

package/dist/providers/claude.js

@@ -85,6 +85,7 @@ export const CLAUDE_CAPABILITIES = {
     denyReason: true,
     allowAlways: true,
     asyncQuestions: false,
+    steer: true,
     compaction: 'prompt',
     reportsCost: true,
     /*
@@ -94,7 +95,8 @@ export const CLAUDE_CAPABILITIES = {
      */
     reportsContextWindow: false,
     reportsThinking: true,
-    slashCommands: true
+    slashCommands: true,
+    goals: 'command'
 };
 // Claude Code takes its flags before `--resume`, which takes the id.
 export const CLAUDE_RESUME_COMMAND = 'claude {flags} --resume {id}';

package/dist/providers/codex.js

@@ -42,11 +42,13 @@ export const CODEX_CAPABILITIES = {
     denyReason: false,
     allowAlways: true,
     asyncQuestions: true,
+    steer: true,
     compaction: 'native',
     reportsCost: false,
     reportsContextWindow: true,
     reportsThinking: true,
-    slashCommands: false
+    slashCommands: false,
+    goals: 'native'
 };
 // `codex resume` is a subcommand that reads `[OPTIONS] [SESSION_ID]`, so the flags go after it.
 export const CODEX_RESUME_COMMAND = 'codex resume {flags} {id}';

package/dist/providers/index.d.ts

@@ -0,0 +1,14 @@
+export { AccountError, type AccountLaunches, storedAccount, launchEnv } from './accounts/launch.ts';
+export { ProviderAccountsService, type ProviderAccountsOptions } from './accounts/service.ts';
+export type { ShadowHomeReport } from './accounts/shadow-home.ts';
+export type { AccountReading, AskAccount } from './accounts/status.ts';
+export { type AccountsHost, variablesProblem, keychainService, type SecretStore, type ReservedVariables } from './accounts/variables.ts';
+export { ModelCatalog, type ModelCatalogInput } from './catalog.ts';
+export { createClaudeProvider } from './claude-provider.ts';
+export { createCodexProvider } from './codex-provider.ts';
+export { type CodexRules, codexRulesText, codexRulesPathIn, defaultCodexHome, installCodexRules, type CodexRulesResult } from './codex-rules.ts';
+export { codexThreadOptions, codexServiceTier } from './codex.ts';
+export { type CliDetection, detectCli } from './detect.ts';
+export type { ChatProvider, ProviderHome } from './provider.ts';
+export { ProviderRegistry, type ProviderRegistryOptions } from './registry.ts';
+export { MODE_ORDER, narrowerMode, ceilingForOpening, modeFlag } from '../modes.ts';

package/dist/providers/index.js

@@ -0,0 +1,12 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { AccountError, storedAccount, launchEnv } from './accounts/launch.js';
+export { ProviderAccountsService } from './accounts/service.js';
+export { variablesProblem, keychainService } from './accounts/variables.js';
+export { ModelCatalog } from './catalog.js';
+export { createClaudeProvider } from './claude-provider.js';
+export { createCodexProvider } from './codex-provider.js';
+export { codexRulesText, codexRulesPathIn, defaultCodexHome, installCodexRules } from './codex-rules.js';
+export { codexThreadOptions, codexServiceTier } from './codex.js';
+export { detectCli } from './detect.js';
+export { ProviderRegistry } from './registry.js';
+export { MODE_ORDER, narrowerMode, ceilingForOpening, modeFlag } from '../modes.js';

package/dist/run-process.js

@@ -1,4 +1,9 @@
 import { spawn } from 'node:child_process';
+import { killProcessTree } from './chat/chat-process.js';
+// What a command and everything it started get between the SIGTERM and the SIGKILL.
+const KILL_GRACE_MS = 2000;
+// Stdout and stderr together; a short command that prints more is ended and fails instead of filling memory.
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
 /* One short command to its end, with what it printed. A command that cannot start rejects. */
 export function runProcess(command, options = {}) {
     return new Promise((resolve, reject) => {
@@ -10,29 +15,64 @@ export function runProcess(command, options = {}) {
         const child = spawn(executable, args, {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
             ...(options.env === undefined ? {} : { env: options.env }),
-            stdio: [options.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe']
+            stdio: [options.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+            // A group of its own, so ending the command also ends what it started; Windows ends the tree through `taskkill`.
+            detached: process.platform !== 'win32',
+            windowsHide: true
         });
         const stdout = [];
         const stderr = [];
-        child.stdout?.on('data', (chunk) => stdout.push(chunk));
-        child.stderr?.on('data', (chunk) => stderr.push(chunk));
-        const timer = options.timeoutMs === undefined
-            ? null
-            : setTimeout(() => {
-                child.kill('SIGTERM');
-                reject(new Error(options.timeoutMessage ?? `${executable} did not finish in time`));
-            }, options.timeoutMs);
-        child.on('error', (error) => {
+        let printed = 0;
+        let settled = false;
+        let timer = null;
+        const settle = () => {
+            if (settled) {
+                return false;
+            }
+            settled = true;
             if (timer !== null) {
                 clearTimeout(timer);
             }
-            reject(error);
+            return true;
+        };
+        const end = (message) => {
+            if (!settle()) {
+                return;
+            }
+            const pid = child.pid;
+            if (pid !== undefined) {
+                killProcessTree(pid, 'SIGTERM');
+                // Sent even when the command left in time: what it started may still ignore the SIGTERM.
+                setTimeout(() => killProcessTree(pid, 'SIGKILL'), KILL_GRACE_MS).unref?.();
+            }
+            reject(new Error(message));
+        };
+        const collect = (into) => (chunk) => {
+            if (settled) {
+                return;
+            }
+            printed += chunk.length;
+            if (printed > MAX_OUTPUT_BYTES) {
+                end(`${executable} printed more than ${MAX_OUTPUT_BYTES / 1024 / 1024} MB`);
+                return;
+            }
+            into.push(chunk);
+        };
+        child.stdout?.on('data', collect(stdout));
+        child.stderr?.on('data', collect(stderr));
+        if (options.timeoutMs !== undefined) {
+            const message = options.timeoutMessage ?? `${executable} did not finish in time`;
+            timer = setTimeout(() => end(message), options.timeoutMs);
+        }
+        child.on('error', (error) => {
+            if (settle()) {
+                reject(error);
+            }
         });
         child.on('close', (exitCode) => {
-            if (timer !== null) {
-                clearTimeout(timer);
+            if (settle()) {
+                resolve({ exitCode, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') });
             }
-            resolve({ exitCode, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') });
         });
         if (options.stdin !== undefined && child.stdin) {
             child.stdin.on('error', () => undefined);

package/dist/skills.d.ts

@@ -18,4 +18,5 @@ export declare class SkillIndex {
     private readonly cache;
     constructor(options?: SkillRootOptions);
     list(kind: AgentKind, cwd: string): Promise<ChatSkill[]>;
+    forget(kind: AgentKind, cwd: string): void;
 }

package/dist/skills.js

@@ -171,4 +171,8 @@ export class SkillIndex {
         this.cache.set(key, { at: Date.now(), skills });
         return skills;
     }
+    /* Drops the scan of one CLI in one folder, so the next look reads the disk again. */
+    forget(kind, cwd) {
+        this.cache.delete(`${kind}:${cwd}`);
+    }
 }

package/dist/tasks/task-coordinator.d.ts

@@ -12,6 +12,10 @@ export interface TaskCoordinatorDeps {
     alert(nodeId: string, title: string, body: string): void;
     retryAt?(chatId: string, turn: ChatTurnItem, items: readonly ChatItem[]): number | null;
     afterBackgroundWork(chatId: string): 'reports' | 'silent' | 'gone';
+    activeGoal?(chatId: string): {
+        objective: string;
+        running: boolean;
+    } | null;
     commandsOf(chatId: string): readonly ChatBackgroundTask[];
     limit: {
         owed(taskId: string): boolean;

package/dist/tasks/task-coordinator.js

@@ -33,6 +33,9 @@ function outlastedNote(commands) {
 function restartedNote(commands) {
     return `The machine restarted while this still ran in the background: ${commandList(commands)}.`;
 }
+function goalLostNote(objective) {
+    return `The agent stopped before its goal was met: ${objective}`;
+}
 /* What a settled turn of a child makes of its task. */
 export function resultOfTurn(turn, items, at) {
     if (turn.state === 'done') {
@@ -49,8 +52,9 @@ export function resultOfTurn(turn, items, at) {
 /*
  * Settles tasks from what children do and does nothing else: it writes the task store and owes wakes
  * in the outbox, never starts a turn, since it runs inside the broadcast of the child it heard. A chat
- * child settles when a turn ends with none of its own tasks still open or waiting to wake it and no work
- * of its CLI's still running in the background, or once the commands it runs there outlast their limit;
+ * child settles when a turn ends with none of its own tasks still open or waiting to wake it, no goal
+ * still active and no work of its CLI's still running in the background, or once the commands it runs
+ * there outlast their limit;
  * an agent that is not a chat, which the host tells it about, settles only on `done`, or fails when it
  * ends without one.
  */
@@ -185,6 +189,16 @@ export class TaskCoordinator {
             this.hold(task, paused);
             return;
         }
+        // A goal holds the task with no limit, and the parent sleeps on through the turns its CLI opens toward it.
+        const goal = turn.state === 'done' ? (this.deps.activeGoal?.(chatId) ?? null) : null;
+        if (goal?.running === true) {
+            return;
+        }
+        if (goal !== null) {
+            const { result } = resultOfTurn(turn, items, this.deps.now());
+            this.settle(task, 'failed', { ...result, text: `${result.text}\n\n${goalLostNote(goal.objective)}`, source: 'exit' });
+            return;
+        }
         // A turn a person stopped or that failed ends the task as it always did, whatever still runs beside it.
         if (turn.state === 'done' && this.heldInBackground(chatId, task, items)) {
             this.track(this.deps.tasks.holdBackground(task.id, {

package/dist/tasks/wiring.js

@@ -37,6 +37,11 @@ export function wireTasks(deps) {
             return reportsOnBackgroundWork(chat.info.provider) ? 'reports' : 'silent';
         },
         commandsOf: (chatId) => chats.get(chatId)?.info.background ?? [],
+        activeGoal: (chatId) => {
+            const chat = chats.get(chatId);
+            const goal = chat?.info.goal;
+            return chat && goal?.status === 'active' ? { objective: goal.objective, running: chat.running } : null;
+        },
         limit
     });
     deps.tasks.onChange((task) => {
@@ -68,7 +73,8 @@ export function wireTasks(deps) {
         }
         const stored = await chats.storedBackground(task.childId);
         const storedWork = stored.items.length > 0 || stored.commands.length > 0;
-        if (!deps.placed(task.childId) || (task.background === undefined && task.requiresTaskTurn !== true && !storedWork)) {
+        // A goal still active went down with the CLI, which its child's last turn settles on.
+        if (!deps.placed(task.childId) || (task.background === undefined && task.requiresTaskTurn !== true && !storedWork && !stored.goal)) {
             return;
         }
         if (task.background === undefined && stored.turnId !== null && storedWork) {

package/dist/{providers/accounts/test-accounts.d.ts → testing/accounts.d.ts}

@@ -1,6 +1,6 @@
 import type { ProviderAccountMap } from '@adecore/agent-contracts';
-import { ProviderAccountsService } from './service.ts';
-import type { SecretStore } from './variables.ts';
+import { ProviderAccountsService } from '../providers/accounts/service.ts';
+import type { SecretStore } from '../providers/accounts/variables.ts';
 export declare function memorySecrets(values?: Map<string, string>): SecretStore & {
     values: Map<string, string>;
 };

package/dist/{providers/accounts/test-accounts.js → testing/accounts.js}

@@ -1,6 +1,6 @@
-import { providerFor } from '../registry.js';
-import { ProviderAccountsService } from './service.js';
-import { accountsPath, writeAccounts } from './store.js';
+import { providerFor } from '../providers/registry.js';
+import { ProviderAccountsService } from '../providers/accounts/service.js';
+import { accountsPath, writeAccounts } from '../providers/accounts/store.js';
 /* A keychain in memory; `values` is what it holds, by key. */
 export function memorySecrets(values = new Map()) {
     return {

package/dist/testing/bin/fake-claude.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/testing/bin/fake-claude.js

@@ -0,0 +1,6 @@
+import { fakeClaude } from '../fake-claude.js';
+import { runOverStdio } from '../fake-cli.js';
+// Run as a script, it stands in for the Claude CLI behind real pipes; imported, it does nothing.
+if (import.meta.main) {
+    await runOverStdio(fakeClaude);
+}

package/dist/testing/bin/fake-codex.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/testing/bin/fake-codex.js

@@ -0,0 +1,6 @@
+import { fakeCodex } from '../fake-codex.js';
+import { runOverStdio } from '../fake-cli.js';
+// Run as a script, it stands in for `codex app-server` behind real pipes; imported, it does nothing.
+if (import.meta.main) {
+    await runOverStdio(fakeCodex);
+}

package/dist/{chat → testing}/fake-claude.d.ts

@@ -1,3 +1,3 @@
-import { type FakeCli, type FakeIo, type FakeProgram } from './fake-cli.ts';
+import type { FakeCli, FakeIo, FakeProgram } from './fake-cli.ts';
 export declare function fakeClaude(io: FakeIo): FakeProgram;
 export declare function claudeStoppingOnResume(sessionIds: ReadonlySet<string>, how: 'missing' | 'exit'): FakeCli;

package/dist/{chat → testing}/fake-claude.js

@@ -5,7 +5,6 @@
 import { spawn } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { runOverStdio } from './fake-cli.js';
 export function fakeClaude(io) {
     const args = io.argv;
     const resumeAt = args.indexOf('--resume');
@@ -1050,6 +1049,3 @@ export function claudeStoppingOnResume(sessionIds, how) {
         return { onLine: () => undefined };
     };
 }
-if (import.meta.main) {
-    await runOverStdio(fakeClaude);
-}

package/dist/{chat → testing}/fake-cli.d.ts

@@ -1,4 +1,4 @@
-import type { SpawnChatProcess } from './chat-process.ts';
+import type { SpawnChatProcess } from '../chat/chat-process.ts';
 export interface FakeIo {
     readonly argv: string[];
     readonly cwd: string;

package/dist/{chat → testing}/fake-codex.d.ts

@@ -1,4 +1,4 @@
-import { type FakeCli } from './fake-cli.ts';
+import type { FakeCli } from './fake-cli.ts';
 type Frame = Record<string, unknown>;
 export declare const FAKE_CHILD_STEPS = 250;
 export declare const fakeCodexForks: Frame[];

package/dist/{chat → testing}/fake-codex.js

@@ -1,8 +1,3 @@
-/*
- * Network-free `codex app-server` fake. Prompt commands exercise approvals, edits, questions,
- * interrupts, failures, names, subagents, pagination and forks through the real JSON-RPC shapes.
- */
-import { runOverStdio } from './fake-cli.js';
 // How many steps a spawned agent takes: more than a thread row keeps, so only its own thread has them all.
 export const FAKE_CHILD_STEPS = 250;
 // The threads of spawned agents, outside any one process: the real ones are on disk, so a process that never ran them reads them too.
@@ -93,6 +88,34 @@ export function fakeCodexWith(options) {
             });
             turnId = '';
         };
+        /*
+         * The thread's goal (Codex 0.162.1). An objective `steps:N` takes N turns: the first is the one the client
+         * starts, which ends when the test says later is, and Codex opens every next one itself while the goal
+         * is active, also later, and marks the goal complete in the last.
+         */
+        let goal = null;
+        let goalSteps = 0;
+        const goalChanged = () => {
+            notify('thread/goal/updated', { threadId, turnId: turnId === '' ? null : turnId, goal });
+        };
+        const goalStep = () => {
+            goalSteps += 1;
+            agentMessage(`goal step ${goalSteps}`);
+            const needed = Number(/steps:(\d+)/.exec(String(goal?.objective ?? ''))?.[1] ?? '1');
+            if (goal !== null) {
+                goal = { ...goal, tokensUsed: Number(goal.tokensUsed) + 100, status: goalSteps >= needed ? 'complete' : goal.status };
+                goalChanged();
+            }
+            turnCompleted('completed');
+            if (goal?.status === 'active') {
+                io.later(() => {
+                    if (goal?.status === 'active') {
+                        turnStarted();
+                        goalStep();
+                    }
+                });
+            }
+        };
         let pendingApproval = null;
         let pendingQuestion = null;
         let pendingSteer = false;
@@ -132,6 +155,10 @@ export function fakeCodexWith(options) {
             const user = item('userMessage', { clientId: null, content: [{ type: 'text', text, text_elements: [] }] });
             started(user);
             completed(user);
+            if (goal !== null && (text === goal.objective || text === '')) {
+                io.later(goalStep);
+                return;
+            }
             if (text === 'crash') {
                 io.exit(1);
                 return;
@@ -494,6 +521,44 @@ export function fakeCodexWith(options) {
                         turnCompleted('interrupted');
                     }
                     return;
+                case 'thread/goal/get':
+                    out({ id, result: { goal } });
+                    return;
+                case 'thread/goal/set': {
+                    const at = Math.floor(Date.now() / 1000);
+                    if (typeof params.objective === 'string') {
+                        goal = {
+                            threadId,
+                            objective: params.objective,
+                            status: 'active',
+                            tokenBudget: null,
+                            tokensUsed: 0,
+                            timeUsedSeconds: 0,
+                            createdAt: at,
+                            updatedAt: at
+                        };
+                        goalSteps = 0;
+                    }
+                    if (goal === null) {
+                        out({ id, error: { code: -32600, message: 'no goal to update' } });
+                        return;
+                    }
+                    if (typeof params.status === 'string') {
+                        goal = { ...goal, status: params.status, updatedAt: at };
+                    }
+                    out({ id, result: { goal } });
+                    goalChanged();
+                    return;
+                }
+                case 'thread/goal/clear': {
+                    const cleared = goal !== null;
+                    goal = null;
+                    out({ id, result: { cleared } });
+                    if (cleared) {
+                        notify('thread/goal/cleared', { threadId });
+                    }
+                    return;
+                }
                 case 'thread/compact/start':
                     out({ id, result: {} });
                     turnStarted();
@@ -530,6 +595,3 @@ export function fakeCodexWith(options) {
     };
 }
 export const fakeCodex = fakeCodexWith({});
-if (import.meta.main) {
-    await runOverStdio(fakeCodex);
-}

package/dist/testing/index.d.ts

@@ -0,0 +1,6 @@
+export { type FakeIo, type FakeProgram, type FakeCli, type StartedFake, type InProcessCli, inProcess, runOverStdio } from './fake-cli.ts';
+export { fakeClaude, claudeStoppingOnResume } from './fake-claude.ts';
+export { FAKE_CHILD_STEPS, fakeCodexForks, type FakeCodexOptions, fakeCodexWith, fakeCodex } from './fake-codex.ts';
+export { memorySecrets, testAccounts } from './accounts.ts';
+export { ManualClock } from './manual-clock.ts';
+export { FakeDirectoryWatcher, FakeWatch, EventLog } from './watch.ts';

package/dist/testing/index.js

@@ -0,0 +1,7 @@
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { inProcess, runOverStdio } from './fake-cli.js';
+export { fakeClaude, claudeStoppingOnResume } from './fake-claude.js';
+export { FAKE_CHILD_STEPS, fakeCodexForks, fakeCodexWith, fakeCodex } from './fake-codex.js';
+export { memorySecrets, testAccounts } from './accounts.js';
+export { ManualClock } from './manual-clock.js';
+export { FakeDirectoryWatcher, FakeWatch, EventLog } from './watch.js';

package/dist/{outbox → testing}/manual-clock.d.ts

@@ -1,4 +1,4 @@
-import type { OutboxClock } from './outbox-worker.ts';
+import type { OutboxClock } from '../outbox/outbox-worker.ts';
 export declare class ManualClock implements OutboxClock {
     private time;
     private timers;

package/dist/{watch-test-helpers.d.ts → testing/watch.d.ts}

@@ -1,4 +1,4 @@
-import type { DirectoryWatcher, WatchDirectory, WatchSeams } from './watch-seam.ts';
+import type { DirectoryWatcher, WatchDirectory, WatchSeams } from '../watch-seam.ts';
 export declare class FakeDirectoryWatcher implements DirectoryWatcher {
     readonly path: string;
     readonly recursive: boolean;

package/dist/usage/exchange.d.ts

@@ -6,11 +6,13 @@ export declare class ExchangeRates {
     private readonly home;
     private readonly allowFetch;
     private rate;
-    private loadedFromDisk;
+    private stored;
     private inFlight;
     constructor(home: string, allowFetch?: boolean);
     get current(): UsageRate | null;
-    ensure(): Promise<void>;
+    load(): Promise<void>;
+    ensure(): Promise<boolean>;
     private get file();
-    private refresh;
+    private readStored;
+    private fetchFresh;
 }