@skillstate/core 0.0.1 → 2.0.0

package/dist/provider.js

@@ -0,0 +1,46 @@
+/**
+ * @non-paper LLM provider seam (Wave 4 DX).
+ *
+ * The paper core calls a bare `LLMFn` (`prompt => response text`) and
+ * measures raw string chars itself (§4.3). This module adds an OPTIONAL,
+ * additive provider interface for hosts that already report usage:
+ *
+ * - `LLMProvider.call(prompt, opts?)` resolves `{ text, usage? }` where
+ *   `usage.promptChars` / `usage.completionChars` are RAW STRING CHARS
+ *   (§4.3) reported by the caller — never tokenizer output;
+ * - `fromLLMFn(fn)` wraps a legacy `LLMFn` into an `LLMProvider`
+ *   (backwards compatibility; `LLMFn` itself is NOT removed);
+ * - `isLLMProvider(v)` distinguishes `LLMFn | LLMProvider` at runtime
+ *   (function = legacy fn, object with a `call` function = provider).
+ *
+ * The runtime accepts `llm: LLMFn | LLMProvider`: with a provider it
+ * prefers `usage` over measuring strings, otherwise it measures exactly
+ * as before. Zero dependencies, Node >= 20, ESM.
+ */
+/**
+ * @non-paper runtime guard: an object with a callable `call` is a
+ * provider; anything else passed as `llm` is treated as a legacy `LLMFn`.
+ */
+export function isLLMProvider(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    return typeof value.call === 'function';
+}
+/**
+ * @non-paper backwards-compatibility adapter: wrap a legacy `LLMFn`
+ * into an `LLMProvider`. The wrapper honors an already-aborted `signal`
+ * (rejects with `signal.reason`) and otherwise delegates verbatim —
+ * no usage is synthesized, so the runtime measures strings as before.
+ */
+export function fromLLMFn(fn) {
+    return {
+        async call(prompt, opts) {
+            if (opts?.signal?.aborted === true) {
+                throw opts.signal.reason;
+            }
+            return { text: await fn(prompt) };
+        },
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqCH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,OAAQ,KAA4B,CAAC,IAAI,KAAK,UAAU,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,EAAa;IACrC,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,IAAqB;YAC9C,IAAI,IAAI,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;gBACnC,MAAO,IAAI,CAAC,MAAsB,CAAC,MAAM,CAAC;YAC5C,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/redaction.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @non-paper secret redaction for logs, prompts, and persisted reports.
+ *
+ * The paper core never sees credentials, but the @non-paper adapters and
+ * trackers shuttle raw LLM text through logs and state files. `redactSecrets`
+ * is a fail-closed scrubber: anything shaped like a credential is replaced
+ * with `[REDACTED]` before the text leaves the process boundary.
+ *
+ * Covered shapes:
+ * - AWS access keys (`AKIA` + 16 uppercase alphanumerics);
+ * - GitHub tokens (`ghp_` + alphanumerics);
+ * - OpenAI-style keys (`sk-` + alphanumerics/dashes/underscores);
+ * - `Bearer <token>` authorisation headers (scheme is kept, token scrubbed);
+ * - PEM private-key blocks (`-----BEGIN … PRIVATE KEY-----` … `-----END …`).
+ *
+ * Pure string function, zero dependencies, Node >= 20, ESM.
+ */
+/** Replacement marker for anything shaped like a secret. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Replace every credential-shaped span in `text` with `[REDACTED]`
+ * (`Bearer <token>` keeps the scheme: `Bearer [REDACTED]`). Pure: the
+ * input string is never mutated.
+ */
+export declare function redactSecrets(text: string): string;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,eAAe,CAAC;AASrC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlD"}

package/dist/redaction.js

@@ -0,0 +1,38 @@
+/**
+ * @non-paper secret redaction for logs, prompts, and persisted reports.
+ *
+ * The paper core never sees credentials, but the @non-paper adapters and
+ * trackers shuttle raw LLM text through logs and state files. `redactSecrets`
+ * is a fail-closed scrubber: anything shaped like a credential is replaced
+ * with `[REDACTED]` before the text leaves the process boundary.
+ *
+ * Covered shapes:
+ * - AWS access keys (`AKIA` + 16 uppercase alphanumerics);
+ * - GitHub tokens (`ghp_` + alphanumerics);
+ * - OpenAI-style keys (`sk-` + alphanumerics/dashes/underscores);
+ * - `Bearer <token>` authorisation headers (scheme is kept, token scrubbed);
+ * - PEM private-key blocks (`-----BEGIN … PRIVATE KEY-----` … `-----END …`).
+ *
+ * Pure string function, zero dependencies, Node >= 20, ESM.
+ */
+/** Replacement marker for anything shaped like a secret. */
+export const REDACTED = '[REDACTED]';
+const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g;
+const AWS_ACCESS_KEY = /\bAKIA[0-9A-Z]{16}\b/g;
+const GITHUB_TOKEN = /\bghp_[A-Za-z0-9_]+/g;
+const OPENAI_KEY = /\bsk-[A-Za-z0-9_-]+/g;
+const BEARER_TOKEN = /\bBearer\s+[A-Za-z0-9\-._~+/=]{8,}/g;
+/**
+ * Replace every credential-shaped span in `text` with `[REDACTED]`
+ * (`Bearer <token>` keeps the scheme: `Bearer [REDACTED]`). Pure: the
+ * input string is never mutated.
+ */
+export function redactSecrets(text) {
+    return text
+        .replace(PRIVATE_KEY_BLOCK, REDACTED)
+        .replace(AWS_ACCESS_KEY, REDACTED)
+        .replace(GITHUB_TOKEN, REDACTED)
+        .replace(OPENAI_KEY, REDACTED)
+        .replace(BEARER_TOKEN, 'Bearer [REDACTED]');
+}
+//# sourceMappingURL=redaction.js.map

package/dist/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAErC,MAAM,iBAAiB,GACrB,mFAAmF,CAAC;AACtF,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAC/C,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAC5C,MAAM,UAAU,GAAG,sBAAsB,CAAC;AAC1C,MAAM,YAAY,GAAG,qCAAqC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI;SACR,OAAO,CAAC,iBAAiB,EAAE,QAAQ,CAAC;SACpC,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC;SACjC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC;SAC/B,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC;SAC7B,OAAO,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;AAChD,CAAC"}

package/dist/resilience.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @non-paper resilience helpers — timeouts, retries with backoff+jitter,
+ * and a circuit breaker for flaky LLM / executor calls.
+ *
+ * Nothing here changes paper semantics: these wrap the TRANSPORT (how long
+ * we wait, how often we re-issue a failed call), never the Algorithm 1
+ * prompt format, the ⊕ merge, or the §7 validation-retry cycle. All of it
+ * is opt-in — the runtime only uses these when the caller passes the
+ * @non-paper `timeoutMs` / `signal` / `retry` options.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+/** Rejection reason for {@link withTimeout} when the deadline fires. */
+export declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+/** Rejection reason for {@link CircuitBreaker.exec} while the circuit is open. */
+export declare class CircuitOpenError extends Error {
+    constructor();
+}
+/**
+ * Race `promise` against a deadline (and, optionally, an AbortSignal).
+ *
+ * - Resolves/rejects with whatever `promise` settles to when it wins.
+ * - Rejects with {@link TimeoutError} when `ms` elapses first.
+ * - Rejects with `signal.reason` when `signal` is already aborted or aborts
+ *   mid-flight. The timer is always cleared on settle so no handle leaks.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, signal?: AbortSignal): Promise<T>;
+/** Options for {@link withRetry}. */
+export interface RetryOptions {
+    /** Retries AFTER the first attempt (total attempts = 1 + maxRetries). */
+    maxRetries: number;
+    /** Base backoff in ms; attempt n waits `baseMs * 2^n` (+ jitter). */
+    baseMs: number;
+    /** When true, add `Math.random() * backoff` on top of the backoff. */
+    jitter?: boolean;
+}
+/**
+ * Re-issue a rejected `fn` up to `maxRetries` times with exponential
+ * backoff (`baseMs * 2^attempt`) and optional jitter. Resolves with the
+ * first success; rethrows the last error when attempts are exhausted.
+ * A `maxRetries` of 0 means a single attempt (no waiting).
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+/** Observable circuit state. */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+/** Options for {@link CircuitBreaker}. */
+export interface CircuitBreakerOptions {
+    /** Consecutive failures that trip the circuit from closed to open. */
+    failureThreshold: number;
+    /** Ms an open circuit waits before letting one trial call through. */
+    resetTimeoutMs: number;
+}
+/**
+ * Minimal circuit breaker (@non-paper transport guard).
+ *
+ * - `closed`: calls pass through; consecutive failures are counted and
+ *   reset by any success. `failureThreshold` consecutive failures open it.
+ * - `open`: calls are rejected immediately with {@link CircuitOpenError}
+ *   without invoking `fn`. After `resetTimeoutMs` the next observed state
+ *   (and the next `exec`) becomes `half-open`.
+ * - `half-open`: a single trial call goes through. Success closes the
+ *   circuit (counters reset); failure re-opens it (timeout restarts).
+ */
+export declare class CircuitBreaker {
+    private readonly options;
+    private failures;
+    private opened;
+    private halfOpen;
+    private openedAt;
+    constructor(options: CircuitBreakerOptions);
+    /** Current state; lazily transitions open → half-open after the timeout. */
+    get state(): CircuitState;
+    /**
+     * Run `fn` through the circuit. Rejects with {@link CircuitOpenError}
+     * while open; otherwise runs `fn` and records success/failure.
+     */
+    exec<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+}
+//# sourceMappingURL=resilience.d.ts.map

package/dist/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wEAAwE;AACxE,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,EAAE,EAAE,MAAM,EAGrB;CACF;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,cAGC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CA4BZ;AAED,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAQD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAK;IAErB,YAA6B,OAAO,EAAE,qBAAqB,EAAI;IAE/D,4EAA4E;IAC5E,IAAI,KAAK,IAAI,YAAY,CAexB;IAED;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAa9C;IAED,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,SAAS;CAYlB"}

package/dist/resilience.js

@@ -0,0 +1,171 @@
+/**
+ * @non-paper resilience helpers — timeouts, retries with backoff+jitter,
+ * and a circuit breaker for flaky LLM / executor calls.
+ *
+ * Nothing here changes paper semantics: these wrap the TRANSPORT (how long
+ * we wait, how often we re-issue a failed call), never the Algorithm 1
+ * prompt format, the ⊕ merge, or the §7 validation-retry cycle. All of it
+ * is opt-in — the runtime only uses these when the caller passes the
+ * @non-paper `timeoutMs` / `signal` / `retry` options.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+/** Rejection reason for {@link withTimeout} when the deadline fires. */
+export class TimeoutError extends Error {
+    constructor(ms) {
+        super(`Timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+/** Rejection reason for {@link CircuitBreaker.exec} while the circuit is open. */
+export class CircuitOpenError extends Error {
+    constructor() {
+        super('Circuit breaker is open');
+        this.name = 'CircuitOpenError';
+    }
+}
+/**
+ * Race `promise` against a deadline (and, optionally, an AbortSignal).
+ *
+ * - Resolves/rejects with whatever `promise` settles to when it wins.
+ * - Rejects with {@link TimeoutError} when `ms` elapses first.
+ * - Rejects with `signal.reason` when `signal` is already aborted or aborts
+ *   mid-flight. The timer is always cleared on settle so no handle leaks.
+ */
+export function withTimeout(promise, ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            reject(new TimeoutError(ms));
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Re-issue a rejected `fn` up to `maxRetries` times with exponential
+ * backoff (`baseMs * 2^attempt`) and optional jitter. Resolves with the
+ * first success; rethrows the last error when attempts are exhausted.
+ * A `maxRetries` of 0 means a single attempt (no waiting).
+ */
+export async function withRetry(fn, options) {
+    let lastError = null;
+    const attempts = options.maxRetries + 1;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= options.maxRetries) {
+                break;
+            }
+            const backoff = options.baseMs * 2 ** attempt;
+            const delay = options.jitter === true ? backoff + Math.random() * backoff : backoff;
+            if (delay > 0) {
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Minimal circuit breaker (@non-paper transport guard).
+ *
+ * - `closed`: calls pass through; consecutive failures are counted and
+ *   reset by any success. `failureThreshold` consecutive failures open it.
+ * - `open`: calls are rejected immediately with {@link CircuitOpenError}
+ *   without invoking `fn`. After `resetTimeoutMs` the next observed state
+ *   (and the next `exec`) becomes `half-open`.
+ * - `half-open`: a single trial call goes through. Success closes the
+ *   circuit (counters reset); failure re-opens it (timeout restarts).
+ */
+export class CircuitBreaker {
+    options;
+    failures = 0;
+    opened = false;
+    halfOpen = false;
+    openedAt = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Current state; lazily transitions open → half-open after the timeout. */
+    get state() {
+        if (this.opened &&
+            !this.halfOpen &&
+            Date.now() - this.openedAt >= this.options.resetTimeoutMs) {
+            this.halfOpen = true;
+        }
+        if (this.halfOpen) {
+            return 'half-open';
+        }
+        if (this.opened) {
+            return 'open';
+        }
+        return 'closed';
+    }
+    /**
+     * Run `fn` through the circuit. Rejects with {@link CircuitOpenError}
+     * while open; otherwise runs `fn` and records success/failure.
+     */
+    async exec(fn) {
+        const current = this.state;
+        if (current === 'open') {
+            throw new CircuitOpenError();
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    onSuccess() {
+        if (this.halfOpen) {
+            this.opened = false;
+            this.halfOpen = false;
+            this.failures = 0;
+        }
+        else {
+            this.failures = 0;
+        }
+    }
+    onFailure() {
+        if (this.halfOpen) {
+            this.halfOpen = false;
+            this.openedAt = Date.now();
+        }
+        else {
+            this.failures += 1;
+            if (this.failures >= this.options.failureThreshold) {
+                this.opened = true;
+                this.openedAt = Date.now();
+            }
+        }
+    }
+}
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.js","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,223 @@
+import type { ProceduralSpec, SkillState, Observation, StatePatch } from './types.js';
+import type { RetryOptions } from './resilience.js';
+import type { TokenTracker } from './token-tracker.js';
+import type { Clock } from './clock.js';
+import type { RuntimeEventEmitter } from './events.js';
+import type { Logger } from './logger.js';
+import type { LLMProvider } from './provider.js';
+/** LLM function: prompt in, response out. */
+export interface LLMFn {
+    (prompt: string): Promise<string>;
+}
+/** Action executor: runs the chosen action against the environment. */
+export interface ActionExecutor {
+    (action: string, state: SkillState): Promise<Observation>;
+}
+/**
+ * Options for constructing a SkillStateRuntime.
+ *
+ * Paper-exact Algorithm 1 (§3.2) takes no size caps, no history budget, and
+ * no token estimator: the prompt is At = (P, Σt, Ot) and nothing else.
+ */
+export interface RuntimeOptions {
+    spec: ProceduralSpec;
+    initialState?: SkillState;
+    /**
+     * Paper-exact `LLMFn` or the @non-paper `LLMProvider` seam (Wave 4 DX).
+     * A function is called verbatim and measured in raw chars; a provider's
+     * `usage` (raw chars, §4.3) is preferred over measuring when present.
+     */
+    llm: LLMFn | LLMProvider;
+    execute: ActionExecutor;
+    tracker?: TokenTracker;
+    /**
+     * Retries after the first failed attempt (§7 rollback-retry).
+     * Default 2 (max attempts = 3).
+     */
+    maxValidationRetries?: number;
+    /**
+     * @non-paper resilience (additive, opt-in). Per-call deadline in ms for
+     * the `llm`/`execute` transport calls. Unset = paper-exact direct calls
+     * with no timeout layer at all.
+     */
+    timeoutMs?: number;
+    /**
+     * @non-paper resilience (additive, opt-in). AbortSignal threaded through
+     * the `llm`/`execute` calls: an aborted signal rejects the in-flight call
+     * with `signal.reason`. Unset = no abort handling.
+     */
+    signal?: AbortSignal;
+    /**
+     * @non-paper resilience (additive, opt-in). Transient transport-error
+     * retries for `llm`/`execute` (thrown errors re-issued with backoff).
+     * Orthogonal to `maxValidationRetries` (§7), which re-prompts on
+     * invalid CONTENT. Unset = a single transport attempt.
+     */
+    retry?: RetryOptions;
+    /**
+     * @non-paper observability (additive, opt-in). Timestamps come from
+     * `clock.now()` instead of `Date.now()`. Unset = paper-exact `Date.now()`
+     * behavior; even an explicit `SystemClock` changes nothing observable.
+     */
+    clock?: Clock;
+    /**
+     * @non-paper observability (additive, opt-in). Receives
+     * `step:start`/`step:end`/`step:error` (and `budget:exceeded` from
+     * `run()`). Unset = nothing is emitted, zero overhead.
+     */
+    events?: RuntimeEventEmitter;
+    /**
+     * @non-paper observability (additive, opt-in). `info` per completed
+     * step, `warn` on invalidated/budget-exceeded steps, `error` on
+     * transport throws. Unset = silent.
+     */
+    logger?: Logger;
+    /**
+     * @non-paper char budget (additive, opt-in). Default cap for `run()`;
+     * a per-call `RunOptions` value wins when both are set. Alias pair:
+     * `tokenBudget`/`charsBudget` are interchangeable (chars, per §4.3 —
+     * the "token" name is kept for caller convenience only).
+     */
+    tokenBudget?: CharsBudget;
+    /** @non-paper alias of `tokenBudget` (additive, opt-in). */
+    charsBudget?: CharsBudget;
+}
+/**
+ * @non-paper char budget (chars, per paper §4.3 — never tokenizer output).
+ * Trips when cumulative prompt+response chars EXCEED `maxChars` (`>`).
+ * Unset `maxChars` = no cap.
+ */
+export interface CharsBudget {
+    maxChars?: number;
+}
+/** @non-paper alias of {@link CharsBudget} (naming convenience only). */
+export type TokenBudget = CharsBudget;
+/**
+ * @non-paper per-`run()` budget overrides. Precedence (first defined wins):
+ * `maxChars` → `tokenBudget` → `charsBudget` → constructor
+ * `tokenBudget` → constructor `charsBudget`. All optional, all additive.
+ */
+export interface RunOptions {
+    tokenBudget?: CharsBudget;
+    charsBudget?: CharsBudget;
+    maxChars?: number;
+}
+/**
+ * @non-paper rejection reason when `run()` trips a char budget. Carries
+ * the committed prefix (`partialResults`, WITHOUT the exceeding step —
+ * the trip rolls its state and tracker entry back) so callers can resume
+ * or report deterministically.
+ */
+export declare class BudgetExceededError extends Error {
+    readonly maxChars: number;
+    readonly totalChars: number;
+    readonly partialResults: StepResult[];
+    constructor(maxChars: number, totalChars: number, partialResults: StepResult[]);
+}
+/** Result of a single Algorithm 1 step. */
+export interface StepResult {
+    step: number;
+    observation: Observation;
+    reasoning: string;
+    statePatch: StatePatch;
+    action: string;
+    newObservation: Observation;
+    newState: SkillState;
+    validationAttempts: number;
+    invalidated: boolean;
+    /**
+     * @non-paper measured sizes for this step (raw string CHARS, §4.3):
+     * `promptChars` is |At| (base prompt only — retry feedback is transport,
+     * never part of At), `responseChars` accumulates every attempt's raw
+     * response. Additive: paper consumers ignore them.
+     */
+    promptChars: number;
+    responseChars: number;
+}
+/**
+ * Algorithm 1 runtime (paper §3.2) with the §7 rollback-retry cycle.
+ *
+ * Each step: format the paper-exact prompt At = (P, Σt, Ot), call the LLM,
+ * parse the response (Rt, ΔΣt, at), validate ΔΣt against the schema, merge
+ * it (Σt+1 = Σt ⊕ ΔΣt), and execute the action. The model never receives
+ * previous observations, actions, or reasoning (§3). Failed attempts
+ * re-prompt with corrective feedback; after exhausting retries the step
+ * fails deterministically — the state is left untouched and the action
+ * becomes `__invalid_patch__`.
+ *
+ * Reasoning is returned but never stored, and merged states are fresh
+ * objects, so a rejected patch can never leak into state (rollback is free).
+ */
+export declare class SkillStateRuntime {
+    private readonly spec;
+    private readonly llm;
+    private readonly execute;
+    private readonly tracker;
+    private readonly maxValidationRetries;
+    private readonly timeoutMs;
+    private readonly signal;
+    private readonly retry;
+    private readonly clock;
+    private readonly events;
+    private readonly logger;
+    private readonly tokenBudget;
+    private readonly charsBudget;
+    private readonly transformer;
+    private currentState;
+    private stepCounter;
+    constructor(options: RuntimeOptions);
+    /** Current state Σt (read-only copy). */
+    get state(): SkillState;
+    /**
+     * @non-paper resilience wrapper (additive, opt-in).
+     *
+     * Paper path: no `timeoutMs`/`signal`/`retry` options — `fn` is invoked
+     * directly, byte-for-byte the paper behavior (no timer, no extra attempt).
+     * Resilience path: the call is threaded through `withTimeout` (deadline
+     * and/or abort) and, when `retry` is set, transient throws are re-issued
+     * via `withRetry`. Validation-retry (§7) semantics above this are
+     * unchanged: a TRANSPORT throw still propagates out of `step` exactly as
+     * a throwing `llm`/`execute` did before.
+     */
+    private invokeResilient;
+    /**
+     * @non-paper LLM dispatch (Wave 4 DX, additive).
+     *
+     * Paper path: `llm` is a legacy `LLMFn` — called verbatim with the
+     * prompt, exactly as before. Provider path: `llm.call(prompt, opts?)`
+     * is used instead, forwarding the runtime `signal?` so aborts reach
+     * the provider; both paths stay inside `invokeResilient`, so the
+     * `timeoutMs`/`signal`/`retry` transport semantics are identical.
+     */
+    private invokeLLM;
+    /**
+     * @non-paper timestamp source: injected `clock` or `Date.now()`.
+     * The default path is exactly the paper core's `Date.now()`.
+     */
+    private now;
+    /** @non-paper: first defined budget cap wins (run-level beats ctor-level). */
+    private resolveMaxChars;
+    /** @non-paper: tracker total when tracked, local tally otherwise. */
+    private currentTotalChars;
+    /**
+     * Execute one Algorithm 1 step for observation Ot.
+     *
+     * Paper-exact Algorithm 1 + §7 rollback-retry; the @non-paper
+     * `events`/`logger` options only OBSERVE (emitted payloads never feed
+     * back into prompts, merges, or validation).
+     */
+    step(observation: Observation): Promise<StepResult>;
+    /**
+     * Run steps until isDone(result) is true or maxSteps is reached. Each
+     * step's input observation is the previous step's newObservation.
+     *
+     * @non-paper `runOpts`/constructor budgets cap cumulative CHARS
+     * (prompt+response, §4.3). On trip the exceeding step is rolled back —
+     * runtime state restored, its tracker entry truncated — and
+     * `BudgetExceededError` (with the committed prefix) is thrown alongside
+     * a `budget:exceeded` event. No budget = the paper-exact loop above,
+     * untouched.
+     */
+    run(first: Observation, isDone: (r: StepResult) => boolean, maxSteps?: number, runOpts?: RunOptions): Promise<StepResult[]>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACX,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,eAAe,CAAC;AAE3D,6CAA6C;AAC7C,MAAM,WAAW,KAAK;IACpB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3D;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,cAAc,CAAC;IACrB,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;;OAIG;IACH,GAAG,EAAE,KAAK,GAAG,WAAW,CAAC;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,UAAU,EAAE,CAAC;IAEtC,YACE,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,UAAU,EAAE,EAO7B;CACF;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,WAAW,CAAC;IAC5B,QAAQ,EAAE,UAAU,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAwCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,WAAW,CAAK;IAExB,YAAY,OAAO,EAAE,cAAc,EAkBlC;IAED,yCAAyC;IACzC,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IAyBvB;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAWjB;;;OAGG;IACH,OAAO,CAAC,GAAG;IAIX,8EAA8E;IAC9E,OAAO,CAAC,eAAe;IAUvB,qEAAqE;IACrE,OAAO,CAAC,iBAAiB;IAIzB;;;;;;OAMG;IACG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAuIxD;IAED;;;;;;;;;;OAUG;IACG,GAAG,CACP,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAClC,QAAQ,GAAE,MAA0B,EACpC,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,UAAU,EAAE,CAAC,CA8DvB;CACF"}