@theokit/sdk 4.19.1 → 4.19.3

package/dist/errors-gE8612p9.d.cts

@@ -0,0 +1,516 @@
+import { Q as RunOperation } from './run-DFM1H2jW.cjs';
+
+/**
+ * Public type contract for the Budget enforcement primitive
+ * (ADRs D375, D382-D387). The runtime facade lives in `budget.ts`.
+ *
+ * @public
+ */
+/**
+ * Scope of a budget — where the charge is attributed. v1 supports
+ * `process` (shared global) only; `agent` and `call` reserved for
+ * v0.2 multi-tenant scenarios.
+ */
+type BudgetScope = "agent" | "call" | "process";
+/**
+ * Time window for a budget limit (D382 — UTC calendar-aligned).
+ * - `1h` is relative (last 60 minutes).
+ * - `1d` / `1w` / `30d` / `365d` are aligned to UTC calendar
+ *   boundaries (UTC midnight / monday 00:00 UTC / 1st 00:00 UTC).
+ */
+type BudgetWindow = "1h" | "1d" | "1w" | "30d" | "365d";
+/**
+ * Enforcement mode (D383).
+ * - `audit`: log only, never throw, never block.
+ * - `warn`: callbacks fire at 80/95/100% thresholds; no throw.
+ * - `block`: preflightCheck throws `BudgetExceededError` BEFORE LLM call
+ *   when would-exceed.
+ */
+type BudgetMode = "audit" | "warn" | "block";
+/** A single limit; stacked in an array (D384, ANY exceeded blocks). */
+interface BudgetLimit {
+    readonly window: BudgetWindow;
+    readonly limitUsd: number;
+}
+/** Threshold event emitted at 80% and 95% in `warn` and `block` modes. */
+interface BudgetThresholdEvent {
+    readonly budgetName: string;
+    readonly window: BudgetWindow;
+    readonly threshold: 0.8 | 0.95;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+}
+/** Exceed event emitted at 100% across all modes. */
+interface BudgetExceedEvent {
+    readonly budgetName: string;
+    readonly window: BudgetWindow;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+    readonly mode: BudgetMode;
+}
+/** Options for `Budget.create`. */
+interface BudgetOptions {
+    /**
+     * Identifier. Must match grammar `^[a-z0-9][a-z0-9_-]*$` (EC-7);
+     * empty/invalid → `ConfigurationError({ code: "invalid_budget_name" })`.
+     */
+    readonly name: string;
+    readonly scope: BudgetScope;
+    /**
+     * Stacked limits — at least one is expected for `warn`/`block`. Empty
+     * array (EC-19) is allowed → registry-only tracking, callbacks never
+     * fire.
+     */
+    readonly limits: ReadonlyArray<BudgetLimit>;
+    /** Default `warn` (D383). */
+    readonly mode?: BudgetMode;
+    /** Fires at 80% and 95% of any limit. Caller throws are isolated (EC-8). */
+    readonly onThreshold?: (event: BudgetThresholdEvent) => void | Promise<void>;
+    /** Fires at 100%. Caller throws are isolated (EC-8). */
+    readonly onExceed?: (event: BudgetExceedEvent) => void | Promise<void>;
+}
+/** Returned by `Budget.create` and `Budget.get` — read-only view. */
+interface BudgetHandle {
+    readonly name: string;
+    readonly mode: BudgetMode;
+    readonly scope: BudgetScope;
+    readonly limits: ReadonlyArray<BudgetLimit>;
+    /** Snapshot spend for the given window. */
+    spentIn(window: BudgetWindow): number;
+    /** Remaining USD before the given window's limit is reached. */
+    remainingIn(window: BudgetWindow): number;
+}
+/** Per-window snapshot returned by `Budget.snapshot()`. */
+interface BudgetSnapshot {
+    readonly name: string;
+    readonly window: BudgetWindow;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+    readonly ratio: number;
+}
+
+/**
+ * Finite, machine-readable error codes for provider-originated errors
+ * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively
+ * — adding a new variant is an explicit decision + test coverage.
+ *
+ * @public
+ */
+type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" | "server_error" | "context_too_long" | "content_filtered" | "model_unavailable" | "network" | "quota_exceeded" | "unknown";
+/**
+ * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).
+ *
+ * Superset of {@link ErrorCode} extended with codes that do NOT originate
+ * from a provider HTTP response:
+ *
+ * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)
+ * - `tool_runtime_error` — custom tool handler threw inside dispatch
+ * - `aborted` — caller's `AbortSignal` fired (Phase 4)
+ * - `invalid_model` — model id rejected by provider (400 "model not found")
+ * - `safety_blocked` — provider safety filter blocked req or resp
+ * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary
+ *
+ * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while
+ * accepting any string for forward compatibility with constructor calls
+ * that pass arbitrary code values (legacy callers).
+ *
+ * @public
+ */
+/**
+ * T1.1 — closed literal union for `AgentRunError.code`. The previous
+ * `(string & {})` escape hatch let arbitrary strings slip into the type
+ * surface and defeated exhaustive `switch (code)` discrimination. This is
+ * the canonical closed form. `AgentRunErrorCode` is re-aliased below for
+ * source-level back-compat.
+ *
+ * Adding a new code: append the literal here AND audit every `switch (err.code)`
+ * in callers. Type-checker enforces the audit via the `default: assertNever(code)`
+ * convention.
+ *
+ * @public
+ */
+type KnownAgentRunErrorCode = ErrorCode | "quota_exceeded" | "tool_runtime_error" | "aborted" | "invalid_model" | "safety_blocked" | "provider_unreachable";
+/**
+ * Back-compat alias of {@link KnownAgentRunErrorCode}. Pre-T1.1 callers that
+ * imported `AgentRunErrorCode` keep working; new code SHOULD prefer
+ * `KnownAgentRunErrorCode` to make the closed-union intent explicit.
+ *
+ * @public
+ */
+type AgentRunErrorCode = KnownAgentRunErrorCode;
+/**
+ * Structured context for errors that originated from a provider HTTP
+ * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),
+ * surface actionable diagnostics (`provider`, `endpoint`), and inspect the
+ * raw response body when needed (`raw`, capped at ~2KB by the mapper).
+ *
+ * @public
+ */
+interface ErrorMetadata {
+    /** Provider canonical name (e.g., `"anthropic"`, `"openai"`, `"openrouter"`, `"gemini"`). */
+    provider: string;
+    /** HTTP endpoint that failed (e.g., `"/v1/messages"`, `"/v1/chat/completions"`). */
+    endpoint: string;
+    /** Machine-readable error code (finite enum). */
+    code: ErrorCode;
+    /** HTTP status code if applicable. */
+    statusCode?: number;
+    /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */
+    retryAfter?: number;
+    /** Raw response body for debugging (truncated to ~2KB by the mapper). */
+    raw?: unknown;
+}
+/**
+ * Base class for all errors thrown by `@theokit/sdk`.
+ *
+ * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`
+ * are populated for server-originated errors when available. `metadata`
+ * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when
+ * the error originated from a provider HTTP call.
+ *
+ * @public
+ */
+declare class TheokitAgentError extends Error {
+    readonly name: string;
+    readonly isRetryable: boolean;
+    readonly code?: string;
+    readonly protoErrorCode?: string;
+    readonly metadata?: ErrorMetadata;
+    constructor(message: string, options?: {
+        isRetryable?: boolean;
+        code?: string;
+        protoErrorCode?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Invalid API key, not logged in, insufficient permissions.
+ *
+ * @public
+ */
+declare class AuthenticationError extends TheokitAgentError {
+    readonly name: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Too many requests or usage limits exceeded.
+ *
+ * @public
+ */
+declare class RateLimitError extends TheokitAgentError {
+    readonly name: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Invalid model, bad request parameters, malformed options.
+ *
+ * @public
+ */
+declare class ConfigurationError extends TheokitAgentError {
+    readonly name: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Thrown when creating a cloud agent for a repo whose SCM provider is not
+ * connected. Use `helpUrl` to point the user at the right reconnect flow.
+ *
+ * @public
+ */
+declare class IntegrationNotConnectedError extends ConfigurationError {
+    readonly name: string;
+    readonly provider: string;
+    readonly helpUrl: string;
+    constructor(message: string, options: {
+        provider: string;
+        helpUrl: string;
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Service unavailable, timeout, transport-level failure.
+ *
+ * @public
+ */
+declare class NetworkError extends TheokitAgentError {
+    readonly name: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Catch-all for unclassified server or runtime errors.
+ *
+ * @public
+ */
+declare class UnknownAgentError extends TheokitAgentError {
+    readonly name: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when
+ * the option `{ throwOnError: true }` is set and the run terminates with
+ * `status: 'error'`. Carries the structured `RunResult.error` fields so
+ * callers can `catch` once and branch on `code` / `provider` instead of
+ * unwrapping the run.
+ *
+ * Extends {@link TheokitAgentError} per ADR D65 — no new hierarchy.
+ *
+ * @example
+ *   try {
+ *     await Agent.prompt(msg, { apiKey, model, throwOnError: true });
+ *   } catch (err) {
+ *     if (err instanceof AgentRunError && err.code === 'auth_failed') {
+ *       // bad key
+ *     }
+ *   }
+ *
+ * @public
+ */
+declare class AgentRunError extends TheokitAgentError {
+    readonly name: string;
+    readonly provider?: string;
+    readonly raw?: string;
+    /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */
+    readonly requestId?: string;
+    /** SDK conversation id this error was raised inside. */
+    readonly conversationId?: string;
+    constructor(message: string, options: {
+        code: AgentRunErrorCode;
+        provider?: string;
+        raw?: string;
+        requestId?: string;
+        conversationId?: string;
+        retriable?: boolean;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+    /**
+     * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as
+     * `retriable` to match the handoff contract. Future v2 will deprecate
+     * `isRetryable` in favor of this.
+     */
+    get retriable(): boolean;
+    /**
+     * D312: provider's `Retry-After` header in **milliseconds**. Mappers store
+     * the header value (seconds) in `metadata.retryAfter`; this getter
+     * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.
+     *
+     * Returns `undefined` when no hint was provided. `0` is a legitimate value
+     * — use `=== undefined` check rather than truthy check.
+     */
+    get retryAfterMs(): number | undefined;
+    /**
+     * D313 + T1.5: alias for `metadata.raw`. Provider response body for
+     * debugging. T1.5 wraps the value in `redactSecrets` at the getter
+     * boundary so secret-shaped substrings (`sk-...`, Bearer JWTs, etc.) are
+     * stripped before reaching the caller. Available but NEVER serialized
+     * into `.message` (anti-leak invariant).
+     */
+    get providerError(): unknown;
+    /**
+     * T1.5 — sanitized JSON form. `metadata.raw` is OMITTED by default; opt
+     * in via `THEOKIT_DEBUG_RAW_ERRORS=1` to surface the (redacted) raw
+     * payload for diagnostics. Every other field stays accessible.
+     *
+     * The single env-var gate is read each call so operators can toggle at
+     * runtime without restarting the process.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Is this error transient (worth retrying)?
+ *
+ * Returns the SDK's own retryability verdict: every {@link TheokitAgentError}
+ * subclass computes `isRetryable` at construction (rate-limit / network /
+ * credential-pool-exhausted are retryable; auth / configuration / unsupported
+ * are not), so this predicate is a single source of truth rather than a
+ * re-derivation. Non-SDK errors return `false` conservatively — wrap a foreign
+ * error in the appropriate SDK error first if you want it considered transient.
+ * It never inspects `err.message`.
+ *
+ * @example
+ *   try {
+ *     await agent.send(message, { throwOnError: true });
+ *   } catch (err) {
+ *     if (isTransientError(err)) return retryWithBackoff();
+ *     throw err;
+ *   }
+ *
+ * @public
+ */
+declare function isTransientError(err: unknown): boolean;
+/**
+ * Thrown when a {@link Run} or agent operation is not available on the current
+ * runtime. Check first with `run.supports(operation)`.
+ *
+ * Extends {@link TheokitAgentError} (so error-catching code that branches on
+ * `instanceof TheokitAgentError` continues to work) but is never retryable —
+ * an unsupported operation will not become supported on retry.
+ *
+ * @public
+ */
+declare class UnsupportedRunOperationError extends TheokitAgentError {
+    readonly name: string;
+    readonly operation: RunOperation;
+    constructor(message: string, operation: RunOperation, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when every credential in a per-provider pool is in cooldown
+ * and no healthy key is available (ADR D133). The caller's
+ * {@link import("./internal/llm/fallback-client.js").FallbackLlmClient}
+ * catches this and tries the next provider in the fallback chain.
+ *
+ * `metadata.nextRetryAt` (epoch ms) tells callers when the soonest
+ * pool entry resumes — useful for manual retry scheduling.
+ *
+ * @public
+ */
+declare class CredentialPoolExhaustedError extends TheokitAgentError {
+    readonly name: string;
+    readonly provider: string;
+    readonly nextRetryAt: number | undefined;
+    constructor(message: string, options: {
+        provider: string;
+        nextRetryAt?: number;
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Finite error codes specific to memory adapter operations (ADR D141).
+ *
+ * @public
+ */
+type MemoryAdapterErrorCode = "auth_failed" | "rate_limited" | "not_found" | "network" | "invalid_input" | "unknown";
+/**
+ * Error raised by `@theokit-memory-*` adapters. Carries `adapterId`
+ * so callers can branch on which provider failed (ADR D141).
+ *
+ * @public
+ */
+declare class MemoryAdapterError extends TheokitAgentError {
+    readonly name: string;
+    readonly adapterId: string;
+    constructor(message: string, options: {
+        adapterId: string;
+        code: MemoryAdapterErrorCode;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+/**
+ * Thrown when a user-supplied task ID violates the grammar
+ * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter
+ * prefix (`wf-` / `b-` / `cron-`, EC-5).
+ *
+ * @public
+ */
+declare class InvalidTaskIdError extends TheokitAgentError {
+    readonly name: string;
+    readonly taskId: string;
+    constructor(message: string, taskId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `Task.subscribe(id)` is called for a task that has been
+ * evicted, never submitted, or evicted after retention (D373).
+ *
+ * @public
+ */
+declare class TaskNotFoundError extends TheokitAgentError {
+    readonly name: string;
+    readonly taskId: string;
+    constructor(taskId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
+ * task observability is deferred until Theo PaaS GA.
+ *
+ * @public
+ */
+declare class UnsupportedTaskOperationError extends TheokitAgentError {
+    readonly name: string;
+    readonly operation: string;
+    constructor(operation: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by `Budget` enforcement (ADR D386) when a `mode: "block"`
+ * budget would be exceeded by the upcoming LLM call. Caller pega
+ * tipado para retry-after-window-reset or surface to the user.
+ *
+ * @public
+ */
+declare class BudgetExceededError extends TheokitAgentError {
+    readonly name: string;
+    readonly budgetName: string;
+    readonly window: BudgetWindow;
+    readonly spentUsd: number;
+    readonly limitUsd: number;
+    readonly mode: BudgetMode;
+    constructor(args: {
+        budgetName: string;
+        window: BudgetWindow;
+        spentUsd: number;
+        limitUsd: number;
+        mode: BudgetMode;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud
+ * budget surface waits for Theo PaaS GA.
+ *
+ * @public
+ */
+/**
+ * T1.6 — Thrown when a consumer calls `agent.send()` or any method
+ * on an agent that has already been `dispose()`d. Pre-T1.6 this was
+ * a generic `new Error("Agent has been disposed")` — consumers
+ * couldn't catch it without string-matching the message.
+ *
+ * @public
+ */
+declare class AgentDisposedError extends TheokitAgentError {
+    readonly name: string;
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+declare class UnsupportedBudgetOperationError extends TheokitAgentError {
+    readonly name: string;
+    readonly operation: string;
+    constructor(operation: string, options?: {
+        cause?: unknown;
+    });
+}
+
+export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, type ErrorMetadata as E, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, TheokitAgentError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, type ErrorCode as m, InvalidTaskIdError as n, type MemoryAdapterErrorCode as o, TaskNotFoundError as p, UnsupportedBudgetOperationError as q, UnsupportedRunOperationError as r, UnsupportedTaskOperationError as s, isTransientError as t, CredentialPoolExhaustedError as u };

package/dist/errors.d.cts

@@ -0,0 +1,3 @@
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, g as BudgetExceededError, C as ConfigurationError, u as CredentialPoolExhaustedError, m as ErrorCode, E as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, K as KnownAgentRunErrorCode, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, T as TheokitAgentError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-gE8612p9.cjs';
+import './run-DFM1H2jW.cjs';
+import 'zod';

package/dist/eval.cjs

@@ -860,7 +860,8 @@ function safePathJoin(base, ...parts) {
   }
   const baseResolved = path.resolve(base);
   const target = path.resolve(base, ...parts);
-  if (target !== baseResolved && !target.startsWith(baseResolved + path.sep)) {
+  const prefix = baseResolved.endsWith(path.sep) ? baseResolved : baseResolved + path.sep;
+  if (target !== baseResolved && !target.startsWith(prefix)) {
     throw new PathTraversalError(parts.join("/"), target);
   }
   return target;
@@ -6005,7 +6006,9 @@ function isCompactSummary(content) {
 function plainText(content) {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return void 0;
-  const texts = content.filter((p) => p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string").map((p) => p.text);
+  const texts = content.filter(
+    (p) => p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string"
+  ).map((p) => p.text);
   return texts.length > 0 ? texts.join("\n") : void 0;
 }
 async function compactSessionTranscript(opts) {
@@ -6126,8 +6129,10 @@ async function autoCompactIfNeeded(opts) {
     return true;
   } catch (cause) {
     const msg = cause instanceof Error ? cause.message : String(cause);
-    process.stderr.write(`[theokit-sdk] auto-compaction failed (left transcript untouched): ${msg}
-`);
+    process.stderr.write(
+      `[theokit-sdk] auto-compaction failed (left transcript untouched): ${msg}
+`
+    );
     return false;
   }
 }
@@ -6137,11 +6142,11 @@ var init_compact_session = __esm({
     init_compaction();
     init_router();
     init_real_local_run_provider();
+    init_session_transcript();
     init_providers();
     init_compression_model_registry();
     init_compression_summarizer();
     init_agent_session();
-    init_session_transcript();
     COMPACT_SUMMARY_MARKER = "[[theokit:compact-summary]]";
     COMPACT_USER_MESSAGE_MAX_TOKENS = 2e4;
     autoCompactAttempts = (() => {
@@ -6246,10 +6251,17 @@ var init_context = __esm({
   }
 });
 
+// src/goal-loop.ts
+var GOAL_CONTINUATION_MARKER;
+var init_goal_loop = __esm({
+  "src/goal-loop.ts"() {
+    GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+  }
+});
+
 // src/internal/runtime/lifecycle/run-until.ts
 var run_until_exports = {};
 __export(run_until_exports, {
-  GOAL_CONTINUATION_MARKER: () => GOAL_CONTINUATION_MARKER,
   composeContinuation: () => composeContinuation,
   runUntilImpl: () => runUntilImpl
 });
@@ -6414,10 +6426,9 @@ ${goal}
 ${lastResponse.slice(-1e3)}`
   ].join("\n");
 }
-var GOAL_CONTINUATION_MARKER;
 var init_run_until = __esm({
   "src/internal/runtime/lifecycle/run-until.ts"() {
-    GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+    init_goal_loop();
   }
 });