@adecore/agents 0.23.1 → 0.24.1

package/src/chat/codex-backend.ts

@@ -1,9 +1,10 @@
+import { randomUUID } from 'node:crypto';
 import { accessSync, constants } from 'node:fs';
-import { attachmentImageMime, type ChatSkill } from '@adecore/agent-contracts';
+import { isRecord, attachmentImageMime, type ChatGoal, type ChatGoalAction, 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 { codexGoal, CodexProtocol } from './codex-protocol.ts';
 import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo, type CodexFrame } from './codex-transport.ts';
 import { attachmentNote } from './input.ts';
 
@@ -11,10 +12,6 @@ function textInput(text: string) {
     return [{ type: 'text', text, text_elements: [] }];
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    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: unknown): ChatSkill[] {
     const data = isRecord(result) && Array.isArray(result.data) ? result.data : [];
@@ -34,6 +31,35 @@ export function parseSkillsList(result: unknown): ChatSkill[] {
     return [...skills.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 
+export type GoalCommand = { kind: 'show' } | { kind: 'clear' } | { kind: 'pause' } | { kind: 'resume' } | { kind: 'set'; objective: string };
+
+// 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: string): GoalCommand | null {
+    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: ChatGoal): string {
+    return `Goal ${goal.status.replace('-', ' ')}: ${goal.objective}`;
+}
+
 export interface CodexBackendOptions {
     client?: CodexClientInfo;
 }
@@ -62,6 +88,8 @@ export class CodexBackend implements ChatBackend {
     private turnUnnamed = false;
     /* A stop that came in while the turn was unnamed, sent once `turn/started` names it. */
     private interruptOwed = false;
+    // The thread's goal as Codex last reported it, which a stop pauses first so Codex opens no turn after it.
+    private goalNow: ChatGoal | null = null;
 
     constructor(launch: BackendLaunch, host: BackendHost, options: CodexBackendOptions = {}) {
         this.launch = launch;
@@ -93,6 +121,19 @@ export class CodexBackend implements ChatBackend {
             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;
+        }
+    }
+
+    private async handshake(transport: CodexTransport): Promise<void> {
         await transport.request('initialize', { clientInfo: this.client, capabilities: { experimentalApi: true, requestAttestation: false } });
         transport.notify('initialized', {});
         const tier = codexServiceTier(this.launch.selection);
@@ -109,7 +150,10 @@ export class CodexBackend implements ChatBackend {
                 result = await transport.request('thread/resume', { threadId: this.launch.resume, excludeTurns: true, ...params });
                 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 });
             }
@@ -123,6 +167,18 @@ export class CodexBackend implements ChatBackend {
             }
             this.emit(event);
         }
+        await this.readGoal(transport).catch(() => {
+            // An app-server without goals, or with the feature turned off, has none to report.
+        });
+    }
+
+    private async readGoal(transport: CodexTransport): Promise<ChatGoal | null> {
+        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;
     }
 
     private turnInput(input: TurnInput): unknown[] {
@@ -154,22 +210,121 @@ export class CodexBackend implements ChatBackend {
     }
 
     sendTurn(input: TurnInput): void {
+        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',
-            {
-                threadId: this.threadId,
-                input: nativeInput,
-                model: this.launch.selection.model,
-                ...(typeof effort === 'string' ? { effort } : {}),
-                ...(tier === null ? {} : { serviceTier: tier })
-            },
-            () => this.acceptPrompt(input.promptId)
-        );
+        this.request('turn/start', this.turnStartParams(nativeInput), () => this.acceptPrompt(input.promptId));
+    }
+
+    private turnStartParams(nativeInput: unknown[]): Record<string, unknown> {
+        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 })
+        };
+    }
+
+    /*
+     * `/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.
+     */
+    private async runGoalCommand(command: GoalCommand, input: TurnInput): Promise<void> {
+        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: Record<string, unknown>): Promise<void> => {
+            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. */
+    private reply(promptId: string | undefined, text: string): void {
+        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: ChatGoalAction): Promise<void> {
+        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: TurnInput): Promise<boolean> {
@@ -277,6 +432,10 @@ export class CodexBackend implements ChatBackend {
         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.
@@ -418,6 +577,9 @@ export class CodexBackend implements ChatBackend {
     }
 
     private emit(event: BackendEvent): void {
+        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/src/chat/codex-protocol.ts

@@ -1,5 +1,6 @@
 import { generatedImage } from './generated-image.ts';
-import type { ChatFileChange, ChatQuestion, ChatTurnLimit, UsageWindow } from '@adecore/agent-contracts';
+import type { ChatFileChange, ChatGoal, ChatGoalStatus, ChatQuestion, ChatTurnLimit, UsageWindow } from '@adecore/agent-contracts';
+import { isRecord } from '@adecore/agent-contracts';
 import { readCodexLimits } from '../usage/limits/normalize.ts';
 import { codexRuntimeMode } from '../providers/codex.ts';
 import type { ApprovalDecision, BackendEvent } from './backend.ts';
@@ -13,10 +14,6 @@ type CodexAnswer = { kind: 'respond'; rpcId: CodexRpcId; result: unknown } | { k
 
 type Frame = Record<string, unknown>;
 
-function isRecord(value: unknown): value is Frame {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function str(value: unknown): string | null {
     return typeof value === 'string' ? value : null;
 }
@@ -25,6 +22,38 @@ function num(value: unknown): number {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
 
+const GOAL_STATUSES: Record<string, ChatGoalStatus> = {
+    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: unknown): ChatGoal | null {
+    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: unknown): number | undefined => (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;
 
@@ -280,6 +309,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/src/chat/codex-thread.ts

@@ -1,4 +1,5 @@
 import type { ChatItem } from '@adecore/agent-contracts';
+import { isRecord } from '@adecore/agent-contracts';
 import { errorText } from '../error-text.ts';
 import type { SpawnChatProcess } from './chat-process.ts';
 import { CodexProtocol } from './codex-protocol.ts';
@@ -6,10 +7,6 @@ import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo } from './co
 import { ChatError } from './errors.ts';
 import { readingThread, settledReading } from './subagent-projection.ts';
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 export interface ThreadItemsParams {
     threadId: string;
     cursor?: string;

package/src/chat/codex-transport.ts

@@ -1,5 +1,5 @@
 import { errorText } from '../error-text.ts';
-import { ChatChild, type SpawnChatProcess } from './chat-process.ts';
+import { ChatChild, MAX_LINE_LENGTH, readStreamLines, type SpawnChatProcess } from './chat-process.ts';
 
 export type CodexFrame = Record<string, unknown>;
 
@@ -35,7 +35,10 @@ class CodexRpcError extends Error {
     }
 }
 
-type Settle = { resolve(value: unknown): void; reject(reason: Error): void; method: string };
+type Settle = { resolve(value: unknown): void; reject(reason: Error): void; method: string; timer: ReturnType<typeof setTimeout> };
+
+// 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,
@@ -48,6 +51,8 @@ export class CodexTransport {
     private readonly pending = new Map<number, Settle>();
     private nextId = 1;
     private closed = false;
+    // Set once stdin ended or broke; a write after an EPIPE only raises the next one.
+    private inputClosed = false;
 
     constructor(options: CodexTransportOptions) {
         this.options = options;
@@ -56,7 +61,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();
@@ -77,10 +82,16 @@ 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);
             }
@@ -101,6 +112,7 @@ export class CodexTransport {
 
     /* Closes stdin; the app-server ends on its own once it has nothing more to say. */
     end(): void {
+        this.inputClosed = true;
         try {
             this.child.process.stdin.end();
         } catch {
@@ -122,19 +134,27 @@ export class CodexTransport {
     }
 
     private write(frame: CodexFrame): void {
-        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. */
+    private broken(error: unknown): void {
+        this.inputClosed = true;
+        this.failed(error);
     }
 
     private failed(error: unknown): void {
         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);
         } catch (reportError) {
@@ -151,32 +171,16 @@ export class CodexTransport {
     }
 
     private async readLines(): Promise<void> {
-        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();
         }
     }
 
@@ -203,6 +207,7 @@ export class CodexTransport {
             return;
         }
         this.pending.delete(message.id as number);
+        clearTimeout(settle.timer);
         if (message.error !== undefined) {
             settle.reject(new CodexRpcError(settle.method, message.error));
         } else {
@@ -215,10 +220,15 @@ export class CodexTransport {
             return;
         }
         this.closed = true;
+        this.rejectPending((method) => new Error(`${method} failed: Codex exited`));
+        this.options.onExit(exitCode, stderr);
+    }
+
+    private rejectPending(reason: (method: string) => Error): void {
         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/src/chat/context-breakdown.ts

@@ -1,4 +1,4 @@
-import { attachmentImageMime, type ChatContextBreakdown, type ChatItem } from '@adecore/agent-contracts';
+import { attachmentImageMime, HOST_TASK_ORIGIN, type ChatContextBreakdown, type ChatItem } 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;
@@ -60,7 +60,7 @@ export function estimateContextBreakdown(items: readonly ChatItem[], contextToke
             }
             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/src/chat/errors.ts

@@ -15,6 +15,7 @@ export type ChatErrorCode =
     // The sub-agent was started by a CLI process that has ended, so no process here can stop it.
     | 'subagent-stale'
     | 'task-not-found'
+    | 'goal-not-found'
     // What reading or forking a CLI's own conversation is refused with.
     | 'transcript-missing'
     | 'transcript-format'

package/src/chat/external-sessions.ts

@@ -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.ts';
 import { claudeProjectSlug, spokenText } from './claude-transcript.ts';
 
@@ -40,7 +40,7 @@ function records(head: string): Array<Record<string, unknown>> {
         }
         try {
             const parsed: unknown = JSON.parse(line);
-            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? [parsed as Record<string, unknown>] : [];
+            return isRecord(parsed) ? [parsed] : [];
         } catch {
             return [];
         }