praxis-agent 0.41.0 → 0.42.0

package/README.md

@@ -200,7 +200,8 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   imports, memory, skills, commands, agents, hooks, settings, MCP servers,
   plugins, and append-only `praxis.transcript` JSONL sessions under `~/.praxis`.
 - **Provider-neutral models** — native Anthropic Messages and OpenAI-compatible
-  streaming adapters with explicit capability checks and metering controls.
+  streaming adapters with explicit capability checks, metering controls, and
+  a bounded absolute deadline for every provider attempt.
 
 Detailed feature status and executable evidence live in the
 [parity matrix](https://github.com/Forest-Isle/Praxis/blob/main/docs/PARITY_MATRIX.md),

package/dist/cli-runtime.js

@@ -47,6 +47,7 @@ import { redactSensitiveText, sensitiveEnvironmentValues, } from './platform/sen
 import { AnthropicCompatibleProvider } from './providers/anthropic-compatible.js';
 import { createAnthropicPromptCachePolicyResolver } from './providers/anthropic-prompt-cache.js';
 import { FallbackModelProvider } from './providers/fallback-provider.js';
+import { DeadlineModelProvider } from './providers/deadline-provider.js';
 import { OpenAICompatibleProvider } from './providers/openai-compatible.js';
 import { parseContextEnvironment, parseProviderEnvironment, } from './providers/environment.js';
 import { ModelPricingRegistry, usageCostUsd } from './core/usage.js';
@@ -107,7 +108,7 @@ function createProviderForModel({ apiKey, environment, provider, context, contro
                 ? { contextWindowTokens: context.contextWindowTokens }
                 : {}),
         };
-        return provider.provider === 'anthropic'
+        const concrete = provider.provider === 'anthropic'
             ? new AnthropicCompatibleProvider({
                 ...providerOptions,
                 promptCaching: resolvePromptCachePolicy({
@@ -126,7 +127,9 @@ function createProviderForModel({ apiKey, environment, provider, context, contro
                 ...('anthropicVersion' in provider
                     ? { anthropicVersion: provider.anthropicVersion }
                     : {}),
-                ...('webSearch' in provider ? { webSearch: provider.webSearch } : {}),
+                ...('webSearch' in provider
+                    ? { webSearch: provider.webSearch }
+                    : {}),
             })
             : new OpenAICompatibleProvider({
                 ...providerOptions,
@@ -142,6 +145,10 @@ function createProviderForModel({ apiKey, environment, provider, context, contro
                         },
                     }),
             });
+        return new DeadlineModelProvider({
+            provider: concrete,
+            deadlineMs: provider.deadlineMs,
+        });
     };
 }
 const HELP = `Praxis — local-first general agent

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

@@ -0,0 +1,16 @@
+import { type ModelProvider, type ModelRequest, type ModelStreamEvent } from '../core/runtime.js';
+export declare const DEFAULT_PROVIDER_DEADLINE_MS = 90000;
+export interface DeadlineModelProviderOptions {
+    provider: ModelProvider;
+    deadlineMs?: number;
+}
+/** Bounds each streamed completion while preserving the wrapped provider's API. */
+export declare class DeadlineModelProvider implements ModelProvider {
+    private readonly provider;
+    private readonly deadlineMs;
+    readonly model?: string;
+    constructor(options: DeadlineModelProviderOptions);
+    get capabilities(): ModelProvider['capabilities'];
+    complete(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
+}
+//# sourceMappingURL=deadline-provider.d.ts.map

package/dist/providers/deadline-provider.js

@@ -0,0 +1,226 @@
+import { ModelProviderError, } from '../core/runtime.js';
+export const DEFAULT_PROVIDER_DEADLINE_MS = 90_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+function deferred() {
+    let resolve;
+    const promise = new Promise((promiseResolve) => {
+        resolve = promiseResolve;
+    });
+    return { promise, resolve };
+}
+/** Bounds each streamed completion while preserving the wrapped provider's API. */
+export class DeadlineModelProvider {
+    provider;
+    deadlineMs;
+    constructor(options) {
+        const deadlineMs = options.deadlineMs === undefined
+            ? DEFAULT_PROVIDER_DEADLINE_MS
+            : options.deadlineMs;
+        if (!Number.isFinite(deadlineMs) ||
+            !Number.isInteger(deadlineMs) ||
+            deadlineMs <= 0) {
+            throw new Error('Provider deadline must be a positive integer');
+        }
+        this.provider = options.provider;
+        this.deadlineMs = deadlineMs;
+        Object.defineProperty(this, 'model', {
+            configurable: false,
+            enumerable: true,
+            get: () => this.provider.model,
+        });
+    }
+    get capabilities() {
+        return this.provider.capabilities;
+    }
+    complete(request) {
+        let started = false;
+        let closed = false;
+        let interruption;
+        let controller;
+        let callerSignal;
+        let timer;
+        let deadlineStartedAt;
+        let underlying;
+        let cleanupStarted = false;
+        const interruptionDeferred = deferred();
+        const interruptionError = () => {
+            if (interruption?.kind === 'timeout') {
+                return new ModelProviderError('Provider request timed out', {
+                    kind: 'timeout',
+                    retryable: true,
+                    cause: interruption.cause,
+                });
+            }
+            return new ModelProviderError('Provider request cancelled', {
+                kind: 'cancelled',
+                retryable: false,
+                cause: interruption?.cause,
+            });
+        };
+        const bestEffortUnderlyingReturn = () => {
+            const iterator = underlying;
+            if (!iterator || cleanupStarted)
+                return;
+            cleanupStarted = true;
+            let returnMethod;
+            try {
+                returnMethod = iterator.return;
+            }
+            catch {
+                return;
+            }
+            if (!returnMethod)
+                return;
+            try {
+                const result = returnMethod.call(iterator);
+                if (result && typeof result.then === 'function') {
+                    void Promise.resolve(result).catch(() => undefined);
+                }
+            }
+            catch {
+                // Cleanup is best effort; preserve the original completion outcome.
+            }
+        };
+        const clearResources = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            callerSignal?.removeEventListener('abort', onCallerAbort);
+        };
+        const finish = (outcome) => {
+            if (interruption !== undefined)
+                return;
+            interruption = outcome;
+            closed = true;
+            interruptionDeferred.resolve(outcome);
+            controller?.abort(outcome.cause);
+            clearResources();
+            if (outcome.kind !== 'return')
+                bestEffortUnderlyingReturn();
+        };
+        const onCallerAbort = () => finish({ kind: 'cancelled', cause: callerSignal?.reason });
+        const timeoutCause = new Error('Provider request timed out');
+        timeoutCause.name = 'TimeoutError';
+        const scheduleDeadline = () => {
+            if (deadlineStartedAt === undefined || closed)
+                return;
+            const elapsedMs = Math.max(0, performance.now() - deadlineStartedAt);
+            const remainingMs = this.deadlineMs - elapsedMs;
+            if (remainingMs <= 0) {
+                finish({ kind: 'timeout', cause: timeoutCause });
+                return;
+            }
+            timer = setTimeout(scheduleDeadline, Math.min(remainingMs, MAX_TIMER_DELAY_MS));
+        };
+        const start = () => {
+            if (started || closed)
+                return;
+            started = true;
+            controller = new AbortController();
+            callerSignal = request.signal;
+            if (callerSignal?.aborted)
+                onCallerAbort();
+            else
+                callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+            if (interruption !== undefined)
+                return;
+            deadlineStartedAt = performance.now();
+            scheduleDeadline();
+            const iterable = this.provider.complete({
+                ...request,
+                signal: controller.signal,
+            });
+            underlying = iterable[Symbol.asyncIterator]();
+            if (interruption !== undefined)
+                bestEffortUnderlyingReturn();
+        };
+        const next = async () => {
+            try {
+                start();
+            }
+            catch (error) {
+                if (interruption !== undefined)
+                    throw interruptionError();
+                closed = true;
+                clearResources();
+                bestEffortUnderlyingReturn();
+                throw error;
+            }
+            if (interruption?.kind === 'return')
+                return { done: true, value: undefined };
+            if (interruption !== undefined)
+                throw interruptionError();
+            if (closed || !underlying)
+                return { done: true, value: undefined };
+            let nextPromise;
+            try {
+                const result = underlying.next();
+                nextPromise = Promise.resolve(result);
+            }
+            catch (error) {
+                if (interruption !== undefined)
+                    throw interruptionError();
+                closed = true;
+                clearResources();
+                bestEffortUnderlyingReturn();
+                throw error;
+            }
+            if (interruption !== undefined) {
+                void nextPromise.catch(() => undefined);
+                throw interruptionError();
+            }
+            const result = await Promise.race([
+                nextPromise.then((value) => ({ type: 'result', value }), (error) => ({ type: 'error', error })),
+                interruptionDeferred.promise.then((outcome) => ({
+                    type: 'interruption',
+                    outcome,
+                })),
+            ]);
+            const observedInterruption = interruption ??
+                (result.type === 'interruption' ? result.outcome : undefined);
+            if (observedInterruption !== undefined) {
+                if (result.type === 'result')
+                    void nextPromise.catch(() => undefined);
+                if (observedInterruption.kind === 'return')
+                    return { done: true, value: undefined };
+                throw interruptionError();
+            }
+            if (result.type === 'error') {
+                closed = true;
+                clearResources();
+                bestEffortUnderlyingReturn();
+                throw result.error;
+            }
+            if (result.type === 'interruption') {
+                if (result.outcome.kind === 'return')
+                    return { done: true, value: undefined };
+                throw interruptionError();
+            }
+            if (result.value.done) {
+                closed = true;
+                clearResources();
+            }
+            return result.value;
+        };
+        const returnFromConsumer = async () => {
+            if (!started) {
+                closed = true;
+                return { done: true, value: undefined };
+            }
+            if (!closed) {
+                finish({ kind: 'return', cause: undefined });
+                bestEffortUnderlyingReturn();
+            }
+            return { done: true, value: undefined };
+        };
+        const result = {
+            [Symbol.asyncIterator]() {
+                return result;
+            },
+            next,
+            return: returnFromConsumer,
+        };
+        return result;
+    }
+}
+//# sourceMappingURL=deadline-provider.js.map

package/dist/providers/environment.d.ts

@@ -1,6 +1,7 @@
 export interface ProviderEnvironment {
     provider: 'openai' | 'anthropic';
     baseUrl: string;
+    deadlineMs: number;
     maxOutputTokens?: number;
     anthropicVersion?: string;
     webSearch?: boolean;

package/dist/providers/environment.js

@@ -1,9 +1,20 @@
 import { createAnthropicPromptCachePolicyResolver } from './anthropic-prompt-cache.js';
+import { DEFAULT_PROVIDER_DEADLINE_MS } from './deadline-provider.js';
 export function parseProviderEnvironment(environment) {
     const provider = environment.PRAXIS_PROVIDER ?? 'openai';
     if (provider !== 'openai' && provider !== 'anthropic') {
         throw new Error('PRAXIS_PROVIDER must be openai or anthropic');
     }
+    const rawDeadlineMs = environment.PRAXIS_PROVIDER_DEADLINE_MS;
+    if (rawDeadlineMs !== undefined &&
+        (!/^\d+$/.test(rawDeadlineMs) ||
+            Number(rawDeadlineMs) <= 0 ||
+            !Number.isSafeInteger(Number(rawDeadlineMs)))) {
+        throw new Error('PRAXIS_PROVIDER_DEADLINE_MS must be a positive safe integer');
+    }
+    const deadlineMs = rawDeadlineMs === undefined
+        ? DEFAULT_PROVIDER_DEADLINE_MS
+        : Number(rawDeadlineMs);
     const maxOutputTokens = environment.PRAXIS_MAX_OUTPUT_TOKENS;
     if (maxOutputTokens !== undefined &&
         (!/^\d+$/.test(maxOutputTokens) ||
@@ -47,6 +58,7 @@ export function parseProviderEnvironment(environment) {
             (provider === 'anthropic'
                 ? 'https://api.anthropic.com/v1'
                 : 'https://api.openai.com/v1'),
+        deadlineMs,
         ...(maxOutputTokens === undefined
             ? {}
             : { maxOutputTokens: Number(maxOutputTokens) }),

package/dist/providers/fallback-provider.js

@@ -6,6 +6,38 @@ function retryable(error) {
         error.retryable &&
         modelProviderErrorKind(error) !== 'prompt_too_long');
 }
+function cancellationError(signal) {
+    return new ModelProviderError('Provider request cancelled', {
+        kind: 'cancelled',
+        retryable: false,
+        cause: signal.reason,
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw cancellationError(signal);
+}
+async function waitForRetry(delayMs, signal) {
+    throwIfAborted(signal);
+    if (delayMs <= 0)
+        return;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            result();
+        };
+        const onAbort = () => finish(() => reject(cancellationError(signal)));
+        const timer = setTimeout(() => finish(resolve), delayMs);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+    });
+}
 /** Routes each complete request through Claude's retry-then-fallback policy. */
 export class FallbackModelProvider {
     active;
@@ -30,6 +62,7 @@ export class FallbackModelProvider {
         let lastError;
         for (const provider of this.providers()) {
             for (let attempt = 0; attempt < MAX_ATTEMPTS_PER_MODEL; attempt += 1) {
+                throwIfAborted(request.signal);
                 this.active = provider;
                 const attemptStartedAt = performance.now();
                 try {
@@ -73,6 +106,7 @@ export class FallbackModelProvider {
                     return;
                 }
                 catch (error) {
+                    throwIfAborted(request.signal);
                     lastError = error;
                     if (!retryable(error))
                         throw error;
@@ -89,8 +123,7 @@ export class FallbackModelProvider {
                                 error: modelProviderErrorKind(error),
                             };
                         }
-                        if (delay > 0)
-                            await new Promise((resolve) => setTimeout(resolve, delay));
+                        await waitForRetry(delay, request.signal);
                     }
                 }
             }

package/package.json

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