praxis-agent 0.23.1 → 0.24.1

package/dist/application/session-service.d.ts

@@ -161,6 +161,7 @@ export interface RewindPoint {
     fileRestoreAvailable: boolean;
 }
 export declare function workflowTokenTarget(prompt: string): number | null;
+export type HookSessionEndReason = 'clear' | 'resume' | 'other';
 export declare class ClaudeSessionService {
     private readonly options;
     private readonly schema;
@@ -182,6 +183,7 @@ export declare class ClaudeSessionService {
     private activeCostSessionId;
     private closeCostSavePromise;
     private readonly sessionMemoryControllers;
+    private readonly hookLifecycle;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
     nextScheduledPrompt(signal?: AbortSignal): Promise<ScheduledPrompt | null>;
@@ -198,6 +200,7 @@ export declare class ClaudeSessionService {
     stopTask(sessionId: string, taskId: string): Promise<void>;
     private applyPermissionUpdates;
     close(): Promise<void>;
+    transitionHookSession(sessionId: string, reason: Exclude<HookSessionEndReason, 'other'>): Promise<void>;
     createHostedToolRegistry(sessionId: string): ToolRegistry;
     run(prompt: string, signal?: AbortSignal, sessionId?: string, name?: string, images?: readonly ModelImage[], documents?: readonly ModelDocument[]): Promise<SessionRunResult>;
     runShell(command: string, signal?: AbortSignal, sessionId?: string, name?: string): Promise<SessionRunResult>;

package/dist/application/session-service.js

@@ -319,6 +319,116 @@ function validSessionName(value) {
         ? name.toLocaleLowerCase()
         : null;
 }
+const SESSION_END_HOOK_TIMEOUT_MS = 15_000;
+class HookLifecycle {
+    hooks;
+    eventSink;
+    sessions = new Map();
+    pendingSource;
+    constructor(hooks, eventSink) {
+        this.hooks = hooks;
+        this.eventSink = eventSink;
+    }
+    async start(sessionId, input, fallbackSource, signal) {
+        let state = this.sessions.get(sessionId);
+        if (state?.started)
+            return undefined;
+        if (state?.starting)
+            return state.starting;
+        state = {
+            input,
+            started: false,
+            starting: undefined,
+            ending: undefined,
+        };
+        this.sessions.set(sessionId, state);
+        const source = this.pendingSource ?? fallbackSource;
+        this.pendingSource = undefined;
+        state.starting = this.hooks?.run({ ...input, hook_event_name: 'SessionStart', source }, source, signal);
+        try {
+            const outcome = await state.starting;
+            state.started = true;
+            return outcome;
+        }
+        catch (error) {
+            this.sessions.delete(sessionId);
+            throw error;
+        }
+        finally {
+            state.starting = undefined;
+        }
+    }
+    async refresh(sessionId, input, signal) {
+        const state = this.sessions.get(sessionId);
+        if (state)
+            state.input = input;
+        return this.hooks?.run({ ...input, hook_event_name: 'SessionStart', source: 'compact' }, 'compact', signal);
+    }
+    async transition(sessionId, reason) {
+        await this.end(sessionId, reason);
+        this.pendingSource = reason;
+    }
+    async end(sessionId, reason) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return;
+        if (state.starting)
+            await state.starting;
+        if (!state.started)
+            return;
+        if (state.ending)
+            return state.ending;
+        state.ending = this.runEnd(state.input, reason).finally(() => {
+            this.sessions.delete(sessionId);
+        });
+        await state.ending;
+    }
+    async close() {
+        await Promise.all([...this.sessions.keys()].map((sessionId) => this.end(sessionId, 'other')));
+    }
+    async runEnd(input, reason) {
+        if (!this.hooks)
+            return;
+        const controller = new AbortController();
+        let timer;
+        try {
+            const timeout = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`timed out after ${SESSION_END_HOOK_TIMEOUT_MS}ms`));
+                }, SESSION_END_HOOK_TIMEOUT_MS);
+            });
+            const outcome = await Promise.race([
+                this.hooks.run({ ...input, hook_event_name: 'SessionEnd', reason }, reason, controller.signal),
+                timeout,
+            ]);
+            for (const execution of outcome.executions) {
+                if (execution.exitCode === 0)
+                    continue;
+                const detail = execution.stderr.trim() ||
+                    execution.stdout.trim() ||
+                    `exit code ${execution.exitCode}`;
+                this.warn(detail);
+            }
+            if (outcome.blockedReason && outcome.executions.at(-1)?.exitCode === 0) {
+                this.warn(outcome.blockedReason);
+            }
+        }
+        catch (error) {
+            this.warn(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    warn(detail) {
+        this.eventSink?.({
+            type: 'warning',
+            message: `SessionEnd hook failed: ${detail}`,
+        });
+    }
+}
 export class ClaudeSessionService {
     options;
     schema;
@@ -340,9 +450,11 @@ export class ClaudeSessionService {
     activeCostSessionId;
     closeCostSavePromise;
     sessionMemoryControllers = new Map();
+    hookLifecycle;
     runtimeCwd;
     constructor(options) {
         this.options = options;
+        this.hookLifecycle = new HookLifecycle(options.hooks, options.eventSink);
         this.runtimeCwd = options.workspace?.cwd() ?? options.cwd;
         this.schema = selectClaudeSchemaAdapter(options.claudeVersion);
         this.scheduledPrompts =
@@ -481,6 +593,7 @@ export class ClaudeSessionService {
         }
     }
     async close() {
+        await this.hookLifecycle.close();
         this.scheduledPrompts?.close();
         await Promise.all([...this.hostedSubagents].map((executor) => executor.close()));
         await Promise.resolve();
@@ -494,6 +607,9 @@ export class ClaudeSessionService {
         this.mcpClosePromise ??= this.options.mcp?.close?.() ?? Promise.resolve();
         await this.mcpClosePromise;
     }
+    async transitionHookSession(sessionId, reason) {
+        await this.hookLifecycle.transition(sessionId, reason);
+    }
     createHostedToolRegistry(sessionId) {
         const baseTools = this.options.tools;
         if (!baseTools)
@@ -2243,17 +2359,11 @@ export class ClaudeSessionService {
                     }
                 },
             };
+            let turnCompleted = false;
             try {
-                if (this.options.hooks) {
-                    const outcome = await this.options.hooks.run({
-                        ...hookSession,
-                        hook_event_name: 'SessionStart',
-                        source: requireExisting ? 'resume' : 'startup',
-                    }, requireExisting ? 'resume' : 'startup', signal);
+                const outcome = await this.hookLifecycle.start(sessionId, hookSession, requireExisting ? 'resume' : 'startup', signal);
+                if (outcome) {
                     await recordHookOutcome(outcome, pendingRecoveryToolCallIds.size > 0);
-                    if (outcome.blockedReason) {
-                        throw new Error(`SessionStart hook error: ${outcome.blockedReason}`);
-                    }
                 }
                 const approveRecovery = this.options.approveRecovery;
                 const recoveryRequest = {
@@ -2620,15 +2730,9 @@ export class ClaudeSessionService {
                     // runtime-only context so the next request retains current
                     // instructions, plan state, session memory, and hook context.
                     if (this.options.hooks) {
-                        const outcome = await this.options.hooks.run({
-                            ...hookSession,
-                            hook_event_name: 'SessionStart',
-                            source: 'compact',
-                        }, 'compact', signal);
-                        await recordHookOutcome(outcome);
-                        if (outcome.blockedReason) {
-                            throw new Error(`SessionStart hook error: ${outcome.blockedReason}`);
-                        }
+                        const outcome = await this.hookLifecycle.refresh(sessionId, hookSession, signal);
+                        if (outcome)
+                            await recordHookOutcome(outcome);
                     }
                     await refreshRuntimeContext();
                     this.options.eventSink?.({
@@ -3057,6 +3161,7 @@ export class ClaudeSessionService {
                         });
                     }
                 }
+                turnCompleted = true;
                 return {
                     sessionId,
                     text: structuredCapture && structuredCapture.calls === 1
@@ -3074,35 +3179,8 @@ export class ClaudeSessionService {
                 };
             }
             finally {
-                try {
-                    const outcome = await this.options.hooks?.run({
-                        ...hookSession,
-                        hook_event_name: 'SessionEnd',
-                        reason: 'other',
-                    }, 'other');
-                    const failedExecutions = outcome?.executions.filter((execution) => execution.exitCode !== 0) ?? [];
-                    for (const execution of failedExecutions) {
-                        const detail = execution.stderr.trim() ||
-                            execution.stdout.trim() ||
-                            `exit code ${execution.exitCode}`;
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `SessionEnd hook failed: ${detail}`,
-                        });
-                    }
-                    if (outcome?.blockedReason &&
-                        outcome.executions.at(-1)?.exitCode === 0) {
-                        this.options.eventSink?.({
-                            type: 'warning',
-                            message: `SessionEnd hook failed: ${outcome.blockedReason}`,
-                        });
-                    }
-                }
-                catch (error) {
-                    this.options.eventSink?.({
-                        type: 'warning',
-                        message: `SessionEnd hook failed: ${error instanceof Error ? error.message : String(error)}`,
-                    });
+                if (!turnCompleted) {
+                    await this.hookLifecycle.end(sessionId, 'other');
                 }
             }
         });

package/dist/cli/interactive.d.ts

@@ -72,6 +72,7 @@ interface InteractiveSessionCommands {
         id: string;
         prompt: string;
     } | null>;
+    transitionHookSession?(sessionId: string, reason: 'clear' | 'resume'): Promise<void>;
     close?(): Promise<void>;
 }
 export interface InteractiveServiceFactory {

package/dist/cli/interactive.js

@@ -1294,6 +1294,8 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                     text: `API retry ${event.attempt}/${event.maxRetries} · ${event.error}`,
                 });
                 break;
+            case 'terminal':
+                break;
             case 'elicitation-complete':
                 append({
                     kind: 'notice',
@@ -3433,9 +3435,16 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
         if (selectingSession) {
             if (key.escape || value === '\u001B') {
                 if (pickerIncludesNewSessionRef.current && allowNewSession) {
-                    setSessionId(null);
-                    setPendingFork(false);
                     setSelectingSession(false);
+                    const previousSessionId = sessionIdRef.current;
+                    void (async () => {
+                        if (previousSessionId) {
+                            const commands = await service();
+                            await commands.transitionHookSession?.(previousSessionId, 'clear');
+                        }
+                        openSession(null);
+                        setPendingFork(false);
+                    })().catch(warn);
                 }
                 else if (allowNewSession) {
                     setSelectingSession(false);
@@ -3460,10 +3469,18 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 const selected = filterSessionChoices(currentPickerChoices, sessionSearchRef.current)[selectedIndexRef.current];
                 if (selected === undefined)
                     return;
-                openSession(selected?.sessionId ?? null);
-                if (!selected)
-                    setPendingFork(false);
                 setSelectingSession(false);
+                const nextSessionId = selected?.sessionId ?? null;
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId && previousSessionId !== nextSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, nextSessionId === null ? 'clear' : 'resume');
+                    }
+                    openSession(nextSessionId);
+                    if (!selected)
+                        setPendingFork(false);
+                })().catch(warn);
             }
             else if (key.backspace || key.delete) {
                 sessionSearchRef.current = sessionSearchRef.current.slice(0, -1);
@@ -5218,28 +5235,40 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 updateMenu({ kind: 'help', tabIndex: 0, selectedIndex: 0 });
             }
             else if (prompt === '/new') {
-                statusLineSessionId.current = randomUUID();
-                setSessionId(null);
-                setSessionColor(undefined);
-                setPendingFork(false);
-                append({ kind: 'notice', text: 'Started a new session.' });
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, 'clear');
+                    }
+                    statusLineSessionId.current = randomUUID();
+                    openSession(null);
+                    setPendingFork(false);
+                    append({ kind: 'notice', text: 'Started a new session.' });
+                })().catch(warn);
             }
             else if (prompt === '/clear') {
-                statusLineSessionId.current = randomUUID();
-                setSessionId(null);
-                setSessionColor(undefined);
-                setPendingFork(false);
-                setHistory([]);
-                setUsage(undefined);
-                setCostUsd(undefined);
-                streamingFrameRef.current?.resetText();
-                streamingFrameRef.current?.resetThinking();
-                streamingFrameRef.current?.flush();
-                setThinkingExpanded(false);
-                setStatus('ready');
-                inputHistoryRef.current = [];
-                inputHistoryIndexRef.current = null;
-                inputHistoryDraftRef.current = '';
+                const previousSessionId = sessionIdRef.current;
+                void (async () => {
+                    if (previousSessionId) {
+                        const commands = await service();
+                        await commands.transitionHookSession?.(previousSessionId, 'clear');
+                    }
+                    statusLineSessionId.current = randomUUID();
+                    openSession(null);
+                    setPendingFork(false);
+                    setHistory([]);
+                    setUsage(undefined);
+                    setCostUsd(undefined);
+                    streamingFrameRef.current?.resetText();
+                    streamingFrameRef.current?.resetThinking();
+                    streamingFrameRef.current?.flush();
+                    setThinkingExpanded(false);
+                    setStatus('ready');
+                    inputHistoryRef.current = [];
+                    inputHistoryIndexRef.current = null;
+                    inputHistoryDraftRef.current = '';
+                })().catch(warn);
             }
             else if (prompt === '/model') {
                 updateMenu({ kind: 'model', selectedIndex: 0 });

package/dist/cli/protocol.d.ts

@@ -247,6 +247,7 @@ export declare class StreamJsonOutput {
     private turnThinking;
     private turnCalls;
     private turnUsage;
+    private turnTerminalReason;
     private turnActive;
     private assistantFlushed;
     private contentStarted;

package/dist/cli/protocol.js

@@ -1666,6 +1666,7 @@ export class StreamJsonOutput {
     turnThinking = [];
     turnCalls = [];
     turnUsage = emptyUsage();
+    turnTerminalReason;
     turnActive = false;
     assistantFlushed = true;
     contentStarted = false;
@@ -1884,6 +1885,11 @@ export class StreamJsonOutput {
             this.turnUsage = event.usage;
             return;
         }
+        if (event.type === 'terminal') {
+            this.ensureTurn();
+            this.turnTerminalReason = event.reason;
+            return;
+        }
         if (event.type === 'permission-decision') {
             this.flushAssistant();
             return;
@@ -2111,6 +2117,7 @@ export class StreamJsonOutput {
         this.turnThinking = [];
         this.turnCalls = [];
         this.turnUsage = emptyUsage();
+        this.turnTerminalReason = undefined;
         this.turnActive = true;
         this.assistantFlushed = false;
         this.contentStarted = false;
@@ -2224,7 +2231,10 @@ export class StreamJsonOutput {
             event: {
                 type: 'message_delta',
                 delta: {
-                    stop_reason: this.turnCalls.length > 0 ? 'tool_use' : 'end_turn',
+                    stop_reason: this.turnTerminalReason === 'prompt_too_long'
+                        ? 'model_context_window_exceeded'
+                        : (this.turnTerminalReason ??
+                            (this.turnCalls.length > 0 ? 'tool_use' : 'end_turn')),
                     stop_sequence: null,
                 },
                 usage: { output_tokens: this.turnUsage.outputTokens },

package/dist/cli-runtime.js

@@ -1577,6 +1577,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             rename: (sessionId, name) => service.rename(sessionId, name),
             sessionNameSuggestion: (sessionId, signal) => service.sessionNameSuggestion(sessionId, signal),
             nextScheduledPrompt: (signal) => service.nextScheduledPrompt(signal),
+            transitionHookSession: (sessionId, reason) => service.transitionHookSession(sessionId, reason),
             close: async () => {
                 let failure;
                 try {

package/dist/core/runtime.d.ts

@@ -78,6 +78,7 @@ export interface ModelWebSearch {
     blockedDomains?: readonly string[];
     maxUses: number;
 }
+export type ModelTerminalReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'prompt_too_long';
 export type ModelStreamEvent = {
     type: 'text-delta';
     delta: string;
@@ -102,6 +103,9 @@ export type ModelStreamEvent = {
 } | {
     type: 'usage';
     usage: ModelUsage;
+} | {
+    type: 'terminal';
+    reason: ModelTerminalReason;
 } | {
     type: 'api-retry';
     attempt: number;
@@ -135,6 +139,8 @@ export interface ModelProviderCapabilities {
     };
     contextWindowTokens?: number;
     maxOutputTokens?: number;
+    /** The provider emits exactly one terminal event as its final stream event. */
+    terminalReasons?: boolean;
 }
 export interface ModelProvider {
     readonly capabilities: ModelProviderCapabilities;
@@ -170,6 +176,9 @@ export type RuntimeEvent = {
 } | {
     type: 'usage';
     usage: ModelUsage;
+} | {
+    type: 'terminal';
+    reason: ModelTerminalReason;
 } | {
     type: 'tool-call';
     call: ModelToolCall;
@@ -480,8 +489,10 @@ export declare class ModelProviderError extends Error {
     readonly retryable: boolean;
     readonly status?: number;
     readonly retryDelayMs?: number;
+    readonly kind?: ProviderErrorKind;
     constructor(message: string, options: {
         retryable: boolean;
+        kind?: ProviderErrorKind;
         status?: number;
         retryDelayMs?: number;
         cause?: unknown;
@@ -492,7 +503,7 @@ export declare class AgentRunCancelledError extends Error {
     constructor();
 }
 export type RuntimeEventSink = (event: RuntimeEvent) => void;
-export type ProviderErrorKind = 'authentication_failed' | 'billing_error' | 'rate_limit' | 'invalid_request' | 'server_error' | 'unknown' | 'max_output_tokens';
+export type ProviderErrorKind = 'authentication_failed' | 'billing_error' | 'rate_limit' | 'invalid_request' | 'server_error' | 'timeout' | 'overloaded' | 'api_error' | 'prompt_too_long' | 'transport_error' | 'cancelled' | 'unknown' | 'max_output_tokens';
 export declare function modelProviderErrorKind(error: ModelProviderError): ProviderErrorKind;
 export declare class AgentRuntime {
     private readonly provider;

package/dist/core/runtime.js

@@ -20,9 +20,12 @@ export class ModelProviderError extends Error {
     retryable;
     status;
     retryDelayMs;
+    kind;
     constructor(message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
         this.retryable = options.retryable;
+        if (options.kind !== undefined)
+            this.kind = options.kind;
         if (options.status !== undefined)
             this.status = options.status;
         if (options.retryDelayMs !== undefined)
@@ -37,6 +40,8 @@ export class AgentRunCancelledError extends Error {
 }
 const emptyUsage = () => ({ inputTokens: 0, outputTokens: 0 });
 export function modelProviderErrorKind(error) {
+    if (error.kind !== undefined)
+        return error.kind;
     if (error.status === 401 || error.status === 403)
         return 'authentication_failed';
     if (error.status === 402)
@@ -341,6 +346,7 @@ export class AgentRuntime {
                 let turnUsage = emptyUsage();
                 let streaming = false;
                 const toolCalls = [];
+                let terminalReason;
                 const apiStartedAt = request.collectMetrics ? performance.now() : 0;
                 let turnApiDurationMs = 0;
                 let turnApiDurationWithoutRetriesMs;
@@ -349,6 +355,9 @@ export class AgentRuntime {
                     for await (const event of this.provider.complete(providerRequest)) {
                         if (request.signal?.aborted)
                             return this.cancel();
+                        if (terminalReason !== undefined) {
+                            throw new ModelProviderError(`Provider emitted ${event.type} after terminal reason ${terminalReason}`, { retryable: false });
+                        }
                         if (event.type === 'api-retry') {
                             this.emit(event);
                             continue;
@@ -414,6 +423,10 @@ export class AgentRuntime {
                             toolCalls.push(event.call);
                             this.emit(event);
                         }
+                        else if (event.type === 'terminal') {
+                            terminalReason = event.reason;
+                            this.emit(event);
+                        }
                         else {
                             turnUsage = event.usage;
                             this.emit(event);
@@ -427,6 +440,18 @@ export class AgentRuntime {
                         unrecordedDurationApiMs = addApiDurationMetric(turnApiDurationMs, unrecordedDurationApiMs, 'durationApiMs');
                     }
                 }
+                if (this.provider.capabilities.terminalReasons === true &&
+                    terminalReason === undefined) {
+                    throw new ModelProviderError('Provider stream ended without a terminal reason', { retryable: true });
+                }
+                if (terminalReason === 'tool_use' && toolCalls.length === 0) {
+                    throw new ModelProviderError('Provider reported tool_use without a completed tool call', { retryable: false });
+                }
+                if (terminalReason !== undefined &&
+                    terminalReason !== 'tool_use' &&
+                    toolCalls.length > 0) {
+                    throw new ModelProviderError(`Provider reported ${terminalReason} with completed tool calls`, { retryable: false });
+                }
                 if (request.collectMetrics) {
                     const turnApiDurationWithoutRetriesMsResolved = turnApiDurationWithoutRetriesMs ?? turnApiDurationMs;
                     durationApiWithoutRetriesMs = addApiDurationMetric(turnApiDurationWithoutRetriesMsResolved, durationApiWithoutRetriesMs, 'durationApiWithoutRetriesMs');

package/dist/providers/anthropic-compatible.js

@@ -1,4 +1,5 @@
 import { ModelProviderError, } from '../core/runtime.js';
+import { transportFailureKind } from './provider-errors.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -61,6 +62,52 @@ function readErrorMessage(value, status) {
     }
     return `Provider request failed with HTTP ${status}`;
 }
+function isPromptTooLongError(type, message) {
+    return (['prompt_too_long', 'context_length_exceeded'].includes(type) ||
+        /prompt\s+(?:is\s+)?too long|context.{0,80}(?:exceed|too long)|maximum context length/iu.test(message));
+}
+function anthropicErrorKind(value, status) {
+    const error = isRecord(value) && isRecord(value.error) ? value.error : value;
+    const type = isRecord(error) && typeof error.type === 'string' ? error.type : '';
+    const message = isRecord(error) && typeof error.message === 'string' ? error.message : '';
+    if (isPromptTooLongError(type, message))
+        return 'prompt_too_long';
+    if (type === 'authentication_error' || status === 401 || status === 403)
+        return 'authentication_failed';
+    if (type === 'billing_error' || status === 402)
+        return 'billing_error';
+    if (type === 'rate_limit_error' || status === 429)
+        return 'rate_limit';
+    if (type === 'overloaded_error' || status === 529)
+        return 'overloaded';
+    if (type === 'api_error')
+        return 'api_error';
+    if (status === 408)
+        return 'timeout';
+    if (type === 'invalid_request_error')
+        return 'invalid_request';
+    if (status !== undefined && status >= 400 && status < 500)
+        return 'invalid_request';
+    if (status !== undefined && status >= 500)
+        return 'server_error';
+    return 'unknown';
+}
+function anthropicStopReason(value) {
+    if (value === 'end_turn' || value === 'stop_sequence' || value === 'refusal')
+        return 'end_turn';
+    if (value === 'tool_use')
+        return 'tool_use';
+    if (value === 'max_tokens')
+        return 'max_tokens';
+    if (value === 'model_context_window_exceeded')
+        return 'prompt_too_long';
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new ModelProviderError('Provider message delta is missing stop reason', {
+            retryable: false,
+        });
+    }
+    throw new ModelProviderError(`Provider returned unsupported stop reason ${value}`, { retryable: false });
+}
 function completedToolCall(state, index) {
     const pending = state.tools.get(index);
     if (!pending)
@@ -105,12 +152,14 @@ function parseSseEvent(data, state, maxToolArgumentsBytes, maxToolCallsPerRespon
         const message = typeof error.message === 'string'
             ? error.message
             : 'Provider stream returned an error';
+        const kind = anthropicErrorKind(error);
         const retryable = [
             'api_error',
-            'overloaded_error',
-            'rate_limit_error',
-        ].includes(String(error.type));
-        throw new ModelProviderError(message, { retryable });
+            'overloaded',
+            'rate_limit',
+            'timeout',
+        ].includes(kind);
+        throw new ModelProviderError(message, { kind, retryable });
     }
     if (value.type === 'message_start') {
         if (state.messageStarted || !isRecord(value.message)) {
@@ -344,6 +393,17 @@ function parseSseEvent(data, state, maxToolArgumentsBytes, maxToolCallsPerRespon
             throw new ModelProviderError('Provider returned an invalid message delta', { retryable: false });
         }
         state.messageDeltaSeen = true;
+        if (value.delta !== undefined && !isRecord(value.delta)) {
+            throw new ModelProviderError('Provider returned an invalid message delta', {
+                retryable: false,
+            });
+        }
+        if (isRecord(value.delta) && value.delta.stop_reason !== undefined) {
+            if (state.terminalReason !== undefined) {
+                throw new ModelProviderError('Provider returned multiple terminal stop reasons', { retryable: false });
+            }
+            state.terminalReason = anthropicStopReason(value.delta.stop_reason);
+        }
         if (typeof value.usage.output_tokens === 'number') {
             state.outputTokens = value.usage.output_tokens;
             state.usageSeen = true;
@@ -360,6 +420,11 @@ function parseSseEvent(data, state, maxToolArgumentsBytes, maxToolCallsPerRespon
         if (!state.messageDeltaSeen) {
             throw new ModelProviderError('Provider stopped before the terminal message delta', { retryable: false });
         }
+        if (state.terminalReason === undefined) {
+            throw new ModelProviderError('Provider message delta is missing stop reason', {
+                retryable: false,
+            });
+        }
         state.terminal = true;
         const events = [];
         if (state.usageSeen) {
@@ -381,6 +446,7 @@ function parseSseEvent(data, state, maxToolArgumentsBytes, maxToolCallsPerRespon
             });
             state.usageSeen = false;
         }
+        events.push({ type: 'terminal', reason: state.terminalReason });
         return events;
     }
     return [];
@@ -532,6 +598,7 @@ export class AnthropicCompatibleProvider {
                 ? {}
                 : { contextWindowTokens: options.contextWindowTokens }),
             maxOutputTokens: this.maxOutputTokens,
+            terminalReasons: true,
         };
         this.thinking = validateThinking(options.thinking);
         this.anthropicVersion = options.anthropicVersion ?? '2023-06-01';
@@ -618,10 +685,14 @@ export class AnthropicCompatibleProvider {
             response = await this.fetchImplementation(this.endpoint, requestInit);
         }
         catch (error) {
-            if (request.signal?.aborted)
-                throw error;
-            throw new ModelProviderError('Provider transport failed', {
-                retryable: true,
+            const kind = transportFailureKind(error, request.signal);
+            throw new ModelProviderError(kind === 'cancelled'
+                ? 'Provider request cancelled'
+                : kind === 'timeout'
+                    ? 'Provider request timed out'
+                    : 'Provider transport failed', {
+                kind,
+                retryable: kind === 'timeout' || kind === 'transport_error',
                 cause: error,
             });
         }
@@ -669,12 +740,14 @@ export class AnthropicCompatibleProvider {
                 payload = null;
             }
             throw new ModelProviderError(readErrorMessage(payload, response.status), {
+                kind: anthropicErrorKind(payload, response.status),
                 retryable: isRetryableStatus(response.status),
                 status: response.status,
             });
         }
         if (!response.body) {
             throw new ModelProviderError('Provider response has no body', {
+                kind: 'transport_error',
                 retryable: true,
             });
         }
@@ -734,11 +807,12 @@ export class AnthropicCompatibleProvider {
             }
         }
         catch (error) {
-            if (error instanceof ModelProviderError || request.signal?.aborted) {
+            if (error instanceof ModelProviderError)
                 throw error;
-            }
+            const kind = transportFailureKind(error, request.signal);
             throw new ModelProviderError('Provider stream failed', {
-                retryable: true,
+                kind,
+                retryable: kind === 'timeout' || kind === 'transport_error',
                 cause: error,
             });
         }

package/dist/providers/fallback-provider.js

@@ -35,7 +35,11 @@ export class FallbackModelProvider {
                     // cannot duplicate text/tool events when retried.
                     const events = [];
                     let attemptDurationMs;
+                    let terminalSeen = false;
                     for await (const event of provider.complete(request)) {
+                        if (terminalSeen) {
+                            throw new ModelProviderError(`Provider emitted ${event.type} after its terminal event`, { retryable: false });
+                        }
                         if (event.type === 'api-attempt-duration') {
                             // Consume the underlying attempt timing rather than replaying it
                             // so nested wrappers report a single retry-free duration.
@@ -51,8 +55,13 @@ export class FallbackModelProvider {
                             attemptDurationMs = durationMs;
                             continue;
                         }
+                        if (event.type === 'terminal')
+                            terminalSeen = true;
                         events.push(event);
                     }
+                    if (provider.capabilities.terminalReasons === true && !terminalSeen) {
+                        throw new ModelProviderError('Provider stream ended without a terminal reason', { retryable: true });
+                    }
                     yield {
                         type: 'api-attempt-duration',
                         durationMs: attemptDurationMs ??

package/dist/providers/openai-compatible.js

@@ -1,4 +1,5 @@
 import { ModelProviderError, } from '../core/runtime.js';
+import { transportFailureKind } from './provider-errors.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -13,6 +14,48 @@ function readErrorMessage(value, status) {
     }
     return `Provider request failed with HTTP ${status}`;
 }
+function openAiFinishReason(value) {
+    if (value === 'stop' || value === 'content_filter')
+        return 'end_turn';
+    if (value === 'tool_calls' || value === 'function_call')
+        return 'tool_use';
+    if (value === 'length')
+        return 'max_tokens';
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new ModelProviderError('Provider stream is missing finish reason', {
+            retryable: false,
+        });
+    }
+    throw new ModelProviderError(`Provider returned unsupported finish reason ${value}`, { retryable: false });
+}
+function openAiErrorKind(value, status) {
+    const error = isRecord(value) && isRecord(value.error) ? value.error : value;
+    const type = isRecord(error) && typeof error.type === 'string' ? error.type : '';
+    const code = isRecord(error) && typeof error.code === 'string' ? error.code : '';
+    const message = isRecord(error) && typeof error.message === 'string' ? error.message : '';
+    if (['context_length_exceeded', 'prompt_too_long'].includes(type) ||
+        ['context_length_exceeded', 'prompt_too_long'].includes(code) ||
+        /prompt\s+(?:is\s+)?too long|context.{0,80}(?:exceed|too long)|maximum context length/iu.test(message)) {
+        return 'prompt_too_long';
+    }
+    if (status === 401 || status === 403)
+        return 'authentication_failed';
+    if (status === 402)
+        return 'billing_error';
+    if (status === 408)
+        return 'timeout';
+    if (type === 'rate_limit_error' || status === 429)
+        return 'rate_limit';
+    if (type === 'overloaded_error' || status === 529)
+        return 'overloaded';
+    if (type === 'api_error' || type === 'server_error')
+        return 'api_error';
+    if (status !== undefined && status >= 400 && status < 500)
+        return 'invalid_request';
+    if (status !== undefined && status >= 500)
+        return 'server_error';
+    return 'unknown';
+}
 function completedToolCallEvents(pending) {
     const events = [...pending.calls.entries()]
         .sort(([left], [right]) => left - right)
@@ -42,9 +85,18 @@ function completedToolCallEvents(pending) {
 }
 function parseSseEvent(data, pendingTools, maxToolArgumentsBytes, maxToolCallsPerResponse, maxToolMetadataBytes) {
     if (data === '[DONE]') {
+        if (pendingTools.terminalReason === undefined) {
+            throw new ModelProviderError('Provider stream is missing finish reason', {
+                retryable: false,
+            });
+        }
         pendingTools.done = true;
         pendingTools.terminal = true;
-        return completedToolCallEvents(pendingTools);
+        pendingTools.terminalEmitted = true;
+        return [
+            ...completedToolCallEvents(pendingTools),
+            { type: 'terminal', reason: pendingTools.terminalReason },
+        ];
     }
     let value;
     try {
@@ -58,6 +110,16 @@ function parseSseEvent(data, pendingTools, maxToolArgumentsBytes, maxToolCallsPe
     }
     if (!isRecord(value))
         return [];
+    if (isRecord(value.error)) {
+        const kind = openAiErrorKind(value);
+        const message = typeof value.error.message === 'string'
+            ? value.error.message
+            : 'Provider stream returned an error';
+        throw new ModelProviderError(message, {
+            kind,
+            retryable: ['api_error', 'overloaded', 'rate_limit', 'timeout'].includes(kind),
+        });
+    }
     const events = [];
     const choices = value.choices;
     if (Array.isArray(choices)) {
@@ -106,7 +168,11 @@ function parseSseEvent(data, pendingTools, maxToolArgumentsBytes, maxToolCallsPe
         if (isRecord(first) &&
             first.finish_reason !== null &&
             first.finish_reason !== undefined) {
+            if (pendingTools.terminalReason !== undefined) {
+                throw new ModelProviderError('Provider returned multiple finish reasons', { retryable: false });
+            }
             pendingTools.terminal = true;
+            pendingTools.terminalReason = openAiFinishReason(first.finish_reason);
             if (pendingTools.calls.size > 0) {
                 events.push(...completedToolCallEvents(pendingTools));
             }
@@ -219,6 +285,7 @@ export class OpenAICompatibleProvider {
             tools: true,
             images: true,
             thinking: { modes: ['disabled'], maxTokens: false },
+            terminalReasons: true,
             ...(options.contextWindowTokens === undefined
                 ? {}
                 : { contextWindowTokens: options.contextWindowTokens }),
@@ -279,10 +346,14 @@ export class OpenAICompatibleProvider {
             response = await this.fetchImplementation(this.endpoint, requestInit);
         }
         catch (error) {
-            if (request.signal?.aborted)
-                throw error;
-            throw new ModelProviderError('Provider transport failed', {
-                retryable: true,
+            const kind = transportFailureKind(error, request.signal);
+            throw new ModelProviderError(kind === 'cancelled'
+                ? 'Provider request cancelled'
+                : kind === 'timeout'
+                    ? 'Provider request timed out'
+                    : 'Provider transport failed', {
+                kind,
+                retryable: kind === 'timeout' || kind === 'transport_error',
                 cause: error,
             });
         }
@@ -330,12 +401,14 @@ export class OpenAICompatibleProvider {
                 payload = null;
             }
             throw new ModelProviderError(readErrorMessage(payload, response.status), {
+                kind: openAiErrorKind(payload, response.status),
                 retryable: isRetryableStatus(response.status),
                 status: response.status,
             });
         }
         if (!response.body) {
             throw new ModelProviderError('Provider response has no body', {
+                kind: 'transport_error',
                 retryable: true,
             });
         }
@@ -347,6 +420,7 @@ export class OpenAICompatibleProvider {
             metadataBytes: 0,
             done: false,
             terminal: false,
+            terminalEmitted: false,
         };
         let streamEnded = false;
         try {
@@ -383,13 +457,23 @@ export class OpenAICompatibleProvider {
             if (!pendingTools.terminal) {
                 throw new ModelProviderError('Provider stream ended before a terminal event', { retryable: true });
             }
+            if (!pendingTools.terminalEmitted) {
+                if (pendingTools.terminalReason === undefined) {
+                    throw new ModelProviderError('Provider stream is missing finish reason', {
+                        retryable: false,
+                    });
+                }
+                pendingTools.terminalEmitted = true;
+                yield { type: 'terminal', reason: pendingTools.terminalReason };
+            }
         }
         catch (error) {
-            if (error instanceof ModelProviderError || request.signal?.aborted) {
+            if (error instanceof ModelProviderError)
                 throw error;
-            }
+            const kind = transportFailureKind(error, request.signal);
             throw new ModelProviderError('Provider stream failed', {
-                retryable: true,
+                kind,
+                retryable: kind === 'timeout' || kind === 'transport_error',
                 cause: error,
             });
         }

package/dist/providers/provider-errors.d.ts

@@ -0,0 +1,3 @@
+export type TransportFailureKind = 'cancelled' | 'timeout' | 'transport_error';
+export declare function transportFailureKind(error: unknown, signal?: AbortSignal): TransportFailureKind;
+//# sourceMappingURL=provider-errors.d.ts.map

package/dist/providers/provider-errors.js

@@ -0,0 +1,9 @@
+export function transportFailureKind(error, signal) {
+    const reason = signal?.reason;
+    if ((error instanceof Error && error.name === 'TimeoutError') ||
+        (reason instanceof Error && reason.name === 'TimeoutError')) {
+        return 'timeout';
+    }
+    return signal?.aborted ? 'cancelled' : 'transport_error';
+}
+//# sourceMappingURL=provider-errors.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",