@adecore/agents 0.23.0 → 0.24.0

package/dist/chat/codex-backend.js

@@ -1,16 +1,14 @@
+import { randomUUID } from 'node:crypto';
 import { accessSync, constants } from 'node:fs';
-import { attachmentImageMime } from '@adecore/agent-contracts';
+import { isRecord, attachmentImageMime } from '@adecore/agent-contracts';
 import { errorText } from '../error-text.js';
 import { codexServiceTier, codexThreadOptions } from '../providers/codex.js';
-import { CodexProtocol } from './codex-protocol.js';
+import { codexGoal, CodexProtocol } from './codex-protocol.js';
 import { CodexTransport, DEFAULT_CODEX_CLIENT } from './codex-transport.js';
 import { attachmentNote } from './input.js';
 function textInput(text) {
     return [{ type: 'text', text, text_elements: [] }];
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /* The enabled skills of a `skills/list` answer; Codex reports one entry per folder it was asked about. */
 export function parseSkillsList(result) {
     const data = isRecord(result) && Array.isArray(result.data) ? result.data : [];
@@ -29,6 +27,30 @@ export function parseSkillsList(result) {
     }
     return [...skills.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
+// The words Claude Code 2.1.296 takes for clearing a goal; Codex reads the same, so `/goal` means one thing in every chat.
+const CLEAR_WORDS = new Set(['clear', 'stop', 'off', 'reset', 'none', 'cancel']);
+/* A `/goal` message the way the CLIs read one: a bare `/goal` shows the goal, a control word acts on it, and anything else is a new objective. Null for any other message. */
+export function parseGoalCommand(text) {
+    const match = /^\/goal(?:\s+([\s\S]*))?$/.exec(text.trim());
+    if (!match) {
+        return null;
+    }
+    const argument = (match[1] ?? '').trim();
+    const word = argument.toLowerCase();
+    if (word === '') {
+        return { kind: 'show' };
+    }
+    if (CLEAR_WORDS.has(word)) {
+        return { kind: 'clear' };
+    }
+    if (word === 'pause' || word === 'resume') {
+        return { kind: word };
+    }
+    return { kind: 'set', objective: argument };
+}
+function goalLine(goal) {
+    return `Goal ${goal.status.replace('-', ' ')}: ${goal.objective}`;
+}
 /*
  * One `codex app-server` process on JSON-RPC over stdio. `start` handshakes (initialize, then
  * thread/start or thread/resume) before the first turn goes out, so every later request knows the
@@ -53,6 +75,8 @@ export class CodexBackend {
     turnUnnamed = false;
     /* A stop that came in while the turn was unnamed, sent once `turn/started` names it. */
     interruptOwed = false;
+    // The thread's goal as Codex last reported it, which a stop pauses first so Codex opens no turn after it.
+    goalNow = null;
     constructor(launch, host, options = {}) {
         this.launch = launch;
         this.host = host;
@@ -80,6 +104,19 @@ export class CodexBackend {
             onExit: (exitCode, stderr) => this.handleExit(transport, exitCode, stderr)
         });
         this.transport = transport;
+        try {
+            await this.handshake(transport);
+        }
+        catch (error) {
+            // A chat that failed to start drops this backend, so nothing else would end an app-server stuck in its handshake.
+            if (this.transport === transport) {
+                this.transport = null;
+                void transport.dispose();
+            }
+            throw error;
+        }
+    }
+    async handshake(transport) {
         await transport.request('initialize', { clientInfo: this.client, capabilities: { experimentalApi: true, requestAttestation: false } });
         transport.notify('initialized', {});
         const tier = codexServiceTier(this.launch.selection);
@@ -97,7 +134,10 @@ export class CodexBackend {
                 this.contextPending = this.launch.resumeNote;
             }
             catch (error) {
-                // The thread is gone from Codex's store; a fresh one keeps the chat usable.
+                // A refusal means the thread is gone from Codex's store and a fresh one keeps the chat usable; a silence or an exit says nothing about the thread.
+                if (!(error instanceof Error) || error.name !== 'CodexRpcError') {
+                    throw error;
+                }
                 this.emit({ type: 'note', level: 'warning', text: `Codex could not resume its thread (${errorText(error)}). Started a new one.` });
                 result = await transport.request('thread/start', { ...params, ...instructions });
             }
@@ -112,6 +152,17 @@ export class CodexBackend {
             }
             this.emit(event);
         }
+        await this.readGoal(transport).catch(() => {
+            // An app-server without goals, or with the feature turned off, has none to report.
+        });
+    }
+    async readGoal(transport) {
+        const result = await transport.request('thread/goal/get', { threadId: this.threadId });
+        const goal = codexGoal(isRecord(result) ? result.goal : null);
+        if (this.transport === transport) {
+            this.emit({ type: 'goal', goal });
+        }
+        return goal;
     }
     turnInput(input) {
         const images = input.attachments.filter((attachment) => attachmentImageMime(attachment) !== null);
@@ -142,18 +193,118 @@ export class CodexBackend {
         return [...textInput(parts.join('')), ...images.map((attachment) => ({ type: 'localImage', path: attachment.path }))];
     }
     sendTurn(input) {
+        const command = input.attachments.length === 0 ? parseGoalCommand(input.text) : null;
+        if (command !== null) {
+            void this.runGoalCommand(command, input);
+            return;
+        }
         const nativeInput = this.turnInput(input);
-        const effort = this.launch.selection.options.effort;
-        const tier = codexServiceTier(this.launch.selection);
         this.turnUnnamed = true;
         this.promptId = input.promptId ?? null;
-        this.request('turn/start', {
+        this.request('turn/start', this.turnStartParams(nativeInput), () => this.acceptPrompt(input.promptId));
+    }
+    turnStartParams(nativeInput) {
+        const effort = this.launch.selection.options.effort;
+        const tier = codexServiceTier(this.launch.selection);
+        return {
             threadId: this.threadId,
             input: nativeInput,
             model: this.launch.selection.model,
             ...(typeof effort === 'string' ? { effort } : {}),
             ...(tier === null ? {} : { serviceTier: tier })
-        }, () => this.acceptPrompt(input.promptId));
+        };
+    }
+    /*
+     * `/goal` through the app-server's goal calls, as Codex's own TUI does. A new objective or a resume
+     * starts the first goal turn itself, with this chat's settings, and only then makes the goal active:
+     * Codex opens every later turn on its own, and one it opened before this turn would take the old
+     * settings. Every other form settles at once with a reply, no turn of the model's.
+     */
+    async runGoalCommand(command, input) {
+        const transport = this.transport;
+        if (!transport) {
+            this.emit({ type: 'failed', message: 'thread/goal failed: Codex is not running' });
+            return;
+        }
+        const threadId = this.threadId;
+        const setGoal = async (params) => {
+            const result = await transport.request('thread/goal/set', { threadId, origin: 'user', ...params });
+            if (this.transport === transport) {
+                this.emit({ type: 'goal', goal: codexGoal(isRecord(result) ? result.goal : null) });
+            }
+        };
+        try {
+            const current = await this.readGoal(transport);
+            if (command.kind === 'show') {
+                this.reply(input.promptId, current === null ? 'No goal is set.' : goalLine(current));
+                return;
+            }
+            if (command.kind === 'clear') {
+                const result = await transport.request('thread/goal/clear', { threadId, origin: 'user' });
+                this.emit({ type: 'goal', goal: null });
+                this.reply(input.promptId, isRecord(result) && result.cleared === true ? 'Goal cleared.' : 'No goal to clear.');
+                return;
+            }
+            if (current === null && command.kind !== 'set') {
+                this.reply(input.promptId, 'No goal is set. Set one with /goal and the objective.');
+                return;
+            }
+            if (command.kind === 'pause') {
+                await setGoal({ status: 'paused' });
+                this.reply(input.promptId, 'Goal paused. /goal resume takes it up again.');
+                return;
+            }
+            if (command.kind === 'set') {
+                // A new objective starts over, its tokens and time included.
+                if (current !== null) {
+                    await transport.request('thread/goal/clear', { threadId, origin: 'user' });
+                }
+                await setGoal({ objective: command.objective, status: 'paused' });
+            }
+            const nativeInput = command.kind === 'set' ? this.turnInput({ ...input, text: command.objective }) : [];
+            this.turnUnnamed = true;
+            this.promptId = input.promptId ?? null;
+            await transport.request('turn/start', this.turnStartParams(nativeInput));
+            if (this.transport !== transport) {
+                return;
+            }
+            this.acceptPrompt(input.promptId);
+            await setGoal({ status: 'active' });
+        }
+        catch (error) {
+            if (this.transport === transport) {
+                this.emit({ type: 'failed', message: errorText(error) });
+            }
+        }
+    }
+    /* A turn that ends with what the host said, for a command no model answers. */
+    reply(promptId, text) {
+        if (promptId !== undefined) {
+            this.emit({ type: 'turn.accepted', promptId });
+        }
+        this.emit({ type: 'text.done', ref: `goal-${randomUUID()}`, text });
+        this.emit({ type: 'turn.done', ...(promptId === undefined ? {} : { promptId }), state: 'done', costUsd: 0 });
+    }
+    async goal(action) {
+        const transport = this.transport;
+        if (!transport) {
+            throw new Error('thread/goal failed: Codex is not running');
+        }
+        if (action === 'clear') {
+            await transport.request('thread/goal/clear', { threadId: this.threadId, origin: 'user' });
+            if (this.transport === transport) {
+                this.emit({ type: 'goal', goal: null });
+            }
+            return;
+        }
+        const result = await transport.request('thread/goal/set', {
+            threadId: this.threadId,
+            status: action === 'pause' ? 'paused' : 'active',
+            origin: 'user'
+        });
+        if (this.transport === transport) {
+            this.emit({ type: 'goal', goal: codexGoal(isRecord(result) ? result.goal : null) });
+        }
     }
     async steerTurn(input) {
         const transport = this.transport;
@@ -254,6 +405,10 @@ export class CodexBackend {
         if (!this.transport) {
             return;
         }
+        // As Codex's own TUI does: paused first, so no goal turn opens after the one this stops.
+        if (this.goalNow?.status === 'active') {
+            void this.transport.request('thread/goal/set', { threadId: this.threadId, status: 'paused', origin: 'user' }).catch(() => undefined);
+        }
         if (!turnId) {
             this.interruptOwed = this.turnUnnamed;
             // A child request can open a host turn after the root's native turn already ended.
@@ -385,6 +540,9 @@ export class CodexBackend {
         this.emit({ type: 'exit', exitCode, ...(stderr === null ? {} : { stderr }) });
     }
     emit(event) {
+        if (event.type === 'goal') {
+            this.goalNow = event.goal;
+        }
         // An older autonomous turn can finish while the next prompt still waits for its own turn/started.
         if ((event.type === 'turn.done' && (!this.turnUnnamed || event.promptId !== undefined)) || event.type === 'failed' || event.type === 'exit') {
             this.turnUnnamed = false;

package/dist/chat/codex-protocol.d.ts

@@ -1,3 +1,4 @@
+import type { ChatGoal } from '@adecore/agent-contracts';
 import type { ApprovalDecision, BackendEvent } from './backend.ts';
 import type { CodexFrame } from './codex-transport.ts';
 type CodexRpcId = number | string;
@@ -9,6 +10,7 @@ type CodexAnswer = {
     kind: 'steer';
     text: string;
 };
+export declare function codexGoal(raw: unknown): ChatGoal | null;
 export declare function unwrapCommand(command: string): string;
 export declare class CodexProtocol {
     private readonly generation;

package/dist/chat/codex-protocol.js

@@ -1,16 +1,44 @@
 import { generatedImage } from './generated-image.js';
+import { isRecord } from '@adecore/agent-contracts';
 import { readCodexLimits } from '../usage/limits/normalize.js';
 import { codexRuntimeMode } from '../providers/codex.js';
 import { cleanTitle } from '../title-file.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function str(value) {
     return typeof value === 'string' ? value : null;
 }
 function num(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
+const GOAL_STATUSES = {
+    active: 'active',
+    paused: 'paused',
+    blocked: 'blocked',
+    usageLimited: 'usage-limited',
+    budgetLimited: 'budget-limited',
+    complete: 'complete'
+};
+/* A `ThreadGoal` of the app-server (Codex 0.162.1) as a chat says it; null for a goal it cannot read, or none. */
+export function codexGoal(raw) {
+    if (!isRecord(raw)) {
+        return null;
+    }
+    const objective = str(raw.objective)?.trim() ?? '';
+    const status = GOAL_STATUSES[str(raw.status) ?? ''];
+    if (objective === '' || status === undefined) {
+        return null;
+    }
+    const count = (value) => (typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined);
+    const tokensUsed = count(raw.tokensUsed);
+    const tokenBudget = count(raw.tokenBudget);
+    const secondsUsed = count(raw.timeUsedSeconds);
+    return {
+        objective,
+        status,
+        ...(tokensUsed === undefined ? {} : { tokensUsed }),
+        ...(tokenBudget === undefined || tokenBudget === 0 ? {} : { tokenBudget }),
+        ...(secondsUsed === undefined ? {} : { secondsUsed })
+    };
+}
 // Codex wraps every command in a login shell; the person wants to read the command, not the wrapper.
 const SHELL_WRAPPER = /^(?:\/bin\/|\/usr\/bin\/)?(?:zsh|bash|sh) -lc (.*)$/s;
 export function unwrapCommand(command) {
@@ -234,6 +262,12 @@ export class CodexProtocol {
             case 'turn/completed':
                 this.handleTurnCompleted(params, events);
                 break;
+            case 'thread/goal/updated':
+                events.push({ type: 'goal', goal: codexGoal(params.goal) });
+                break;
+            case 'thread/goal/cleared':
+                events.push({ type: 'goal', goal: null });
+                break;
             case 'thread/closed':
                 this.withdrawOwner(threadId ?? this.ownThreadId, null, events);
                 break;

package/dist/chat/codex-thread.js

@@ -1,11 +1,9 @@
+import { isRecord } from '@adecore/agent-contracts';
 import { errorText } from '../error-text.js';
 import { CodexProtocol } from './codex-protocol.js';
 import { CodexTransport, DEFAULT_CODEX_CLIENT } from './codex-transport.js';
 import { ChatError } from './errors.js';
 import { readingThread, settledReading } from './subagent-projection.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /* One `thread/items/list` answer as far as a reader needs it: the entries newest first, and the cursor to older ones. */
 export function parseThreadItemsPage(result) {
     const data = isRecord(result) && Array.isArray(result.data) ? result.data.filter(isRecord) : [];

package/dist/chat/codex-transport.d.ts

@@ -21,6 +21,7 @@ export declare class CodexTransport {
     private readonly pending;
     private nextId;
     private closed;
+    private inputClosed;
     constructor(options: CodexTransportOptions);
     get pid(): number;
     get alive(): boolean;
@@ -33,10 +34,12 @@ export declare class CodexTransport {
     stop(): void;
     dispose(): Promise<void>;
     private write;
+    private broken;
     private failed;
     private readLine;
     private readLines;
     private handleLine;
     private handleExit;
+    private rejectPending;
 }
 export {};

package/dist/chat/codex-transport.js

@@ -1,5 +1,5 @@
 import { errorText } from '../error-text.js';
-import { ChatChild } from './chat-process.js';
+import { ChatChild, MAX_LINE_LENGTH, readStreamLines } from './chat-process.js';
 export const DEFAULT_CODEX_CLIENT = { name: 'agents', title: 'Agents', version: '0.1.0' };
 class CodexRpcError extends Error {
     code;
@@ -10,6 +10,8 @@ class CodexRpcError extends Error {
         this.code = typeof detail.code === 'number' ? detail.code : null;
     }
 }
+// The app-server answers every request it takes at once and does the work in notifications, so a silent one is stuck.
+const REQUEST_TIMEOUT_MS = 60_000;
 /*
  * One `codex app-server` process and the JSON-RPC framing on its stdio: newline-delimited JSON,
  * a request carries an id and gets a result or an error back under the same id, a notification
@@ -21,6 +23,8 @@ export class CodexTransport {
     pending = new Map();
     nextId = 1;
     closed = false;
+    // Set once stdin ended or broke; a write after an EPIPE only raises the next one.
+    inputClosed = false;
     constructor(options) {
         this.options = options;
         this.child = new ChatChild({
@@ -28,7 +32,7 @@ export class CodexTransport {
             cwd: options.cwd,
             env: options.env,
             ...(options.spawn ? { spawn: options.spawn } : {}),
-            onError: (error) => this.failed(error),
+            onError: (error) => this.broken(error),
             onExit: (exitCode, stderr) => this.handleExit(exitCode, stderr)
         });
         void this.readLines();
@@ -46,11 +50,17 @@ export class CodexTransport {
                 return;
             }
             const id = this.nextId++;
-            this.pending.set(id, { resolve, reject, method });
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`${method} failed: Codex did not answer in ${REQUEST_TIMEOUT_MS / 1000} seconds`));
+            }, REQUEST_TIMEOUT_MS);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, method, timer });
             try {
                 this.write({ id, method, params });
             }
             catch (error) {
+                clearTimeout(timer);
                 this.pending.delete(id);
                 reject(error);
             }
@@ -67,6 +77,7 @@ export class CodexTransport {
     }
     /* Closes stdin; the app-server ends on its own once it has nothing more to say. */
     end() {
+        this.inputClosed = true;
         try {
             this.child.process.stdin.end();
         }
@@ -85,18 +96,26 @@ export class CodexTransport {
         return this.child.end();
     }
     write(frame) {
-        if (this.closed) {
+        if (this.closed || this.inputClosed) {
             throw new Error('Codex stdin is closed');
         }
-        this.child.process.stdin.write(`${JSON.stringify(frame)}\n`);
-        this.child.process.stdin.flush();
+        try {
+            this.child.process.stdin.write(`${JSON.stringify(frame)}\n`);
+            this.child.process.stdin.flush();
+        }
+        catch (error) {
+            this.inputClosed = true;
+            throw error;
+        }
+    }
+    /* A pipe that failed takes no more writes; a frame a consumer choked on leaves it as it was. */
+    broken(error) {
+        this.inputClosed = true;
+        this.failed(error);
     }
     failed(error) {
         const failure = new Error(`Codex transport failed: ${errorText(error)}`);
-        for (const settle of this.pending.values()) {
-            settle.reject(failure);
-        }
-        this.pending.clear();
+        this.rejectPending(() => failure);
         try {
             this.options.onError?.(failure);
         }
@@ -113,35 +132,14 @@ export class CodexTransport {
         }
     }
     async readLines() {
-        const reader = this.child.process.stdout.getReader();
-        const decoder = new TextDecoder();
-        let buffered = '';
         try {
-            while (true) {
-                const { value, done } = await reader.read();
-                if (done) {
-                    break;
-                }
-                buffered += decoder.decode(value, { stream: true });
-                let newline = buffered.indexOf('\n');
-                while (newline >= 0) {
-                    this.readLine(buffered.slice(0, newline));
-                    buffered = buffered.slice(newline + 1);
-                    newline = buffered.indexOf('\n');
-                }
-            }
-            if (buffered.trim() !== '') {
-                this.readLine(buffered);
-            }
+            await readStreamLines(this.child.process.stdout, (line) => this.readLine(line), () => this.failed(new Error(`Codex wrote a frame of more than ${MAX_LINE_LENGTH / 1_000_000} million characters, which was dropped`)));
         }
         catch (error) {
             if (!this.closed) {
-                this.failed(error);
+                this.broken(error);
             }
         }
-        finally {
-            reader.releaseLock();
-        }
     }
     handleLine(line) {
         if (this.closed || line.trim() === '') {
@@ -167,6 +165,7 @@ export class CodexTransport {
             return;
         }
         this.pending.delete(message.id);
+        clearTimeout(settle.timer);
         if (message.error !== undefined) {
             settle.reject(new CodexRpcError(settle.method, message.error));
         }
@@ -179,10 +178,14 @@ export class CodexTransport {
             return;
         }
         this.closed = true;
+        this.rejectPending((method) => new Error(`${method} failed: Codex exited`));
+        this.options.onExit(exitCode, stderr);
+    }
+    rejectPending(reason) {
         for (const settle of this.pending.values()) {
-            settle.reject(new Error(`${settle.method} failed: Codex exited`));
+            clearTimeout(settle.timer);
+            settle.reject(reason(settle.method));
         }
         this.pending.clear();
-        this.options.onExit(exitCode, stderr);
     }
 }

package/dist/chat/context-breakdown.js

@@ -1,4 +1,4 @@
-import { attachmentImageMime } from '@adecore/agent-contracts';
+import { attachmentImageMime, HOST_TASK_ORIGIN } from '@adecore/agent-contracts';
 // A rough rate for prose and code alike; scaling to the CLI's own total absorbs the error.
 const CHARS_PER_TOKEN = 4;
 // What a model is charged for a picture at the size a CLI sends it, whatever its bytes on disk.
@@ -54,7 +54,7 @@ export function estimateContextBreakdown(items, contextTokens) {
             }
             case 'subagent':
                 // A row the host drew for work it delegated stands for that work; the call that made it is a tool row of its own.
-                if (item.origin !== 'ruimte') {
+                if (item.origin !== HOST_TASK_ORIGIN) {
                     toolOutput += textTokens(item.prompt ?? '') + textTokens(item.result ?? '');
                 }
                 break;

package/dist/chat/errors.d.ts

@@ -1,4 +1,4 @@
 import { CodedError } from '../coded-error.ts';
-export type ChatErrorCode = 'refused-query' | 'stale-ui-query' | 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'subagent-stale' | 'task-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
+export type ChatErrorCode = 'refused-query' | 'stale-ui-query' | 'history-expired' | 'chat-not-found' | 'chat-unreadable' | 'chat-busy' | 'request-not-found' | 'chat-unsupported' | 'invalid-attachments' | 'subagent-not-found' | 'subagent-stale' | 'task-not-found' | 'goal-not-found' | 'transcript-missing' | 'transcript-format' | 'fork-failed' | 'turn-not-found' | 'item-not-found' | 'bookmark-not-found' | 'too-many-bookmarks' | 'visual-invalid' | 'visual-too-large';
 export declare class ChatError<TCode extends string = ChatErrorCode> extends CodedError<TCode> {
 }

package/dist/chat/external-sessions.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { clipText } from '@adecore/agent-contracts';
+import { clipText, isRecord } from '@adecore/agent-contracts';
 import { isForkOrSubagent } from '../usage/readers/codex.js';
 import { claudeProjectSlug, spokenText } from './claude-transcript.js';
 const TITLE_LENGTH = 120;
@@ -18,7 +18,7 @@ function records(head) {
         }
         try {
             const parsed = JSON.parse(line);
-            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? [parsed] : [];
+            return isRecord(parsed) ? [parsed] : [];
         }
         catch {
             return [];