praxis-agent 0.23.1 → 0.24.0

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',

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/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.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",