@skillstate/core 0.0.1 → 2.0.1

package/dist/instrumentation.js

@@ -0,0 +1,41 @@
+/**
+ * @non-paper — OPTIONAL instrumentation helpers, NOT part of the paper.
+ *
+ * Nothing in this module appears in arXiv 2608.26263v3. The paper's §4.3
+ * methodology measures prompts in raw string chars (Average Prompt Size =
+ * mean char length per call, Total Token Cost = cumulative burn) and reports
+ * no tokenizer heuristic and no dollar pricing. Import from here only when
+ * you explicitly want a rough, clearly-labelled estimate outside the
+ * paper-exact baseline in `./token-tracker.js`.
+ */
+/**
+ * @non-paper legacy heuristic: 1 token ≈ 4 chars, rounded up.
+ *
+ * Kept for backward compatibility of ad-hoc estimates only. Do NOT use it
+ * for paper §4.3 metrics — those are measured in chars (see `TokenTracker`).
+ * Empty text costs zero.
+ */
+export class CharDiv4Counter {
+    count(text) {
+        if (text.length === 0) {
+            return 0;
+        }
+        return Math.ceil(text.length / 4);
+    }
+}
+/**
+ * @non-paper estimated dollar savings of state prompts vs the conversation
+ * baseline, from measured char counts (e.g. `TokenTracker.compareWithBaseline`).
+ *
+ * This is a back-of-the-envelope estimate, NOT a paper metric: the paper
+ * reports no pricing. `usdPerMillionChars` defaults to 3 (a placeholder
+ * rate, not a paper figure). Returns 0 when there is nothing to save.
+ */
+export function estimateCostSavings(conversationChars, stateChars, usdPerMillionChars = 3) {
+    const saved = conversationChars - stateChars;
+    if (saved <= 0) {
+        return 0;
+    }
+    return (saved * usdPerMillionChars) / 1_000_000;
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,IAAY;QAChB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,CAAC;QACX,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,iBAAyB,EACzB,UAAkB,EAClB,kBAAkB,GAAG,CAAC;IAEtB,MAAM,KAAK,GAAG,iBAAiB,GAAG,UAAU,CAAC;IAC7C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,KAAK,GAAG,kBAAkB,CAAC,GAAG,SAAS,CAAC;AAClD,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,34 @@
+/** @non-paper log severity. */
+export type LogLevel = 'info' | 'warn' | 'error';
+/** @non-paper structured fields attached to a log line. */
+export interface LogFields {
+    [key: string]: unknown;
+}
+/** @non-paper minimal structured logger consumed by the runtime. */
+export interface Logger {
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+/** @non-paper options for {@link JsonLogger}. All optional. */
+export interface JsonLoggerOptions {
+    /** Line sink (default: `console.log`). One JSON object per call. */
+    sink?: (line: string) => void;
+    /** Millis source for `ts` (default: `Date.now`). */
+    now?: () => number;
+}
+/**
+ * @non-paper JSON-line `Logger`. The ENTRY is built first, then the whole
+ * serialized line is scrubbed — secrets hiding inside `fields` are caught
+ * exactly like secrets in the message.
+ */
+export declare class JsonLogger implements Logger {
+    private readonly sink;
+    private readonly now;
+    constructor(options?: JsonLoggerOptions);
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    private write;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAcA,+BAA+B;AAC/B,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAClD;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,YAAY,OAAO,CAAC,EAAE,iBAAiB,EAGtC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9C;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9C;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE/C;IAED,OAAO,CAAC,KAAK;CAId"}

package/dist/logger.js

@@ -0,0 +1,40 @@
+/**
+ * @non-paper JSON-line logger with secret scrubbing.
+ *
+ * The paper logs nothing. This module adds an OPTIONAL, additive logging
+ * seam: the runtime calls it ONLY when a caller passes `logger?` (unset =
+ * silent, paper-exact). Every line is a single JSON object
+ * `{ level, msg, ts, ...fields }` passed through `redactSecrets`, so
+ * credential-shaped spans (tokens, keys, PEM blocks) can never leak via
+ * logs even when prompts/observations carry them.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+import { redactSecrets } from './redaction.js';
+/**
+ * @non-paper JSON-line `Logger`. The ENTRY is built first, then the whole
+ * serialized line is scrubbed — secrets hiding inside `fields` are caught
+ * exactly like secrets in the message.
+ */
+export class JsonLogger {
+    sink;
+    now;
+    constructor(options) {
+        this.sink = options?.sink ?? ((line) => console.log(line));
+        this.now = options?.now ?? (() => Date.now());
+    }
+    info(message, fields) {
+        this.write('info', message, fields);
+    }
+    warn(message, fields) {
+        this.write('warn', message, fields);
+    }
+    error(message, fields) {
+        this.write('error', message, fields);
+    }
+    write(level, message, fields) {
+        const entry = { level, msg: message, ts: this.now(), ...(fields ?? {}) };
+        this.sink(redactSecrets(JSON.stringify(entry)));
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAyB/C;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACJ,IAAI,CAAyB;IAC7B,GAAG,CAAe;IAEnC,YAAY,OAA2B;QACrC,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,IAAY,EAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,MAAkB;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,MAAkB;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,MAAkB;QACvC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAEO,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,MAAkB;QAChE,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QACzE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/migrations.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @non-paper versioned-state envelope + 0→1 migration.
+ *
+ * The paper has no persistence format; anything written to disk before this
+ * @non-paper layer is a BARE `SkillState` object (no envelope) — that is
+ * "version 0". The versioned envelope is `{ version: 1, state }`.
+ * `migrate` accepts unknown persisted JSON and returns a `VersionedState`:
+ *
+ * - `{ version: 1, state }` → returned as-is (deep-copied, never aliased);
+ * - `{ version: 0, state }` → re-enveloped as version 1;
+ * - a bare state object (no `version` key) → wrapped losslessly as v1;
+ * - anything else (null, arrays, primitives, wrong versions, non-object
+ *   `state`) → throws; fail closed rather than running on garbage.
+ *
+ * Pure function, zero dependencies, Node >= 20, ESM.
+ */
+import type { SkillState } from './types.js';
+/** Current @non-paper persistence envelope version. */
+export declare const CURRENT_STATE_VERSION: 1;
+/**
+ * @non-paper versioned envelope around a paper-exact `SkillState`.
+ * The inner `state` keeps full paper semantics (⊕ merge, null-deletion);
+ * the envelope only versions the BYTES on disk.
+ */
+export interface VersionedState {
+    version: 1;
+    state: SkillState;
+}
+/**
+ * Normalize unknown persisted JSON into a `VersionedState` (0→1).
+ * Never aliases its input: the returned `state` is always a deep copy.
+ * Throws on anything that is not recognizably a state.
+ */
+export declare function migrate(raw: unknown): VersionedState;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAapD"}

package/dist/migrations.js

@@ -0,0 +1,26 @@
+import { clone } from './clock.js';
+/** Current @non-paper persistence envelope version. */
+export const CURRENT_STATE_VERSION = 1;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Normalize unknown persisted JSON into a `VersionedState` (0→1).
+ * Never aliases its input: the returned `state` is always a deep copy.
+ * Throws on anything that is not recognizably a state.
+ */
+export function migrate(raw) {
+    if (isRecord(raw)) {
+        if (raw.version === CURRENT_STATE_VERSION && isRecord(raw.state)) {
+            return { version: 1, state: clone(raw.state) };
+        }
+        if (raw.version === 0 && isRecord(raw.state)) {
+            return { version: 1, state: clone(raw.state) };
+        }
+        if (!('version' in raw)) {
+            return { version: 1, state: clone(raw) };
+        }
+    }
+    throw new Error('Unrecognized state format: cannot migrate to version 1');
+}
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,uDAAuD;AACvD,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAU,CAAC;AAYhD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,GAAY;IAClC,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClB,IAAI,GAAG,CAAC,OAAO,KAAK,qBAAqB,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACjE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAmB,CAAC,EAAE,CAAC;QAC/D,CAAC;QACD,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAmB,CAAC,EAAE,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAiB,CAAC,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;AAC5E,CAAC"}

package/dist/prompt-transformer.d.ts

@@ -0,0 +1,106 @@
+import type { ProceduralSpec, SkillState, Observation, StatePatch, StateSchema } from './types.js';
+export interface PromptTransformerOptions {
+    platform?: 'claude' | 'opencode' | 'generic';
+}
+/**
+ * Reason a parseResponse call failed.
+ *
+ * @non-paper — implementation-internal codes. These are NOT the paper's
+ * §5.7 taxonomy: §5.7 reports log-analysis categories from the Gemma-4-31B
+ * T=100 runs (68% Premature Overwrite/Deletion, 20% Schema/Type Coercion,
+ * 12% JSON Syntax), not parser result codes.
+ */
+export type ParseFailureReason = 'no_block' | 'malformed_json' | 'missing_state_patch' | 'missing_action';
+/**
+ * Typed result of parsing an LLM response into a state patch + action.
+ */
+export type ParseResponseResult = {
+    ok: true;
+    patch: StatePatch;
+    action: string;
+} | {
+    ok: false;
+    reason: ParseFailureReason;
+    detail?: string;
+};
+/**
+ * Transforms skill state, observations, and specs into formatted prompts
+ * for LLM consumption, and parses structured responses back.
+ *
+ * Only {@link PromptTransformer.formatPaper} is paper-exact (Appendix A.4).
+ * Every other formatter here is an implementation convenience for the
+ * platform adapters — the paper defines no per-platform prompt templates.
+ */
+export declare class PromptTransformer {
+    private platform;
+    constructor(options?: PromptTransformerOptions);
+    /**
+     * Format the full prompt. Delegates to platform-specific formatter.
+     *
+     * @non-paper — adapter convenience. Paper-exact callers must use
+     * {@link PromptTransformer.formatPaper}.
+     */
+    formatPrompt(spec: ProceduralSpec, state: SkillState, observation: Observation, platform?: 'claude' | 'opencode' | 'generic'): string;
+    /**
+     * Claude-specific prompt format: markdown with system prompt section,
+     * state section, observation section, instruction for reasoning + JSON.
+     *
+     * @non-paper — adapter convenience; the paper defines no Claude template.
+     */
+    formatForClaude(spec: ProceduralSpec, state: SkillState, observation: Observation): string;
+    /**
+     * OpenCode-specific prompt format adapted for the opencode skill system.
+     *
+     * @non-paper — adapter convenience; the paper defines no OpenCode template.
+     */
+    formatForOpenCode(spec: ProceduralSpec, state: SkillState, observation: Observation): string;
+    /**
+     * Paper-exact prompt format — byte-verbatim Appendix A.4.
+     *
+     * The template is reproduced exactly as printed in the paper (blank lines
+     * and indentation preserved): instructions start after a blank line, the
+     * state is fenced as ```json with compact JSON (`JSON.stringify(state)` —
+     * the paper's `json.dumps(state, separators=(',', ':'))`), and the response
+     * directive carries the two-key JSON contract verbatim. No schema
+     * description and no platform padding is added on top of A.4.
+     */
+    formatPaper(spec: ProceduralSpec, state: SkillState, observation: Observation): string;
+    /**
+     * Generic prompt format (no platform prefix).
+     *
+     * @non-paper — adapter convenience; the paper-exact template is
+     * {@link PromptTransformer.formatPaper} (Appendix A.4).
+     */
+    private formatGeneric;
+    /**
+     * Extract the state_patch from an LLM response containing a fenced JSON block.
+     */
+    extractStatePatch(response: string): StatePatch | null;
+    /**
+     * Extract the action string from an LLM response containing a fenced JSON block.
+     */
+    extractAction(response: string): string | null;
+    /**
+     * Parse an LLM response into a typed result: either a valid
+     * { patch, action } pair or a structured failure with a reason.
+     *
+     * Malformed outputs can never corrupt Σt: callers (runtime §7
+     * rollback-retry, adapter hook scripts) must reject `ok: false` results
+     * without touching state (paper Limitations).
+     */
+    parseResponse(response: string): ParseResponseResult;
+    /**
+     * Serialize state as JSON. When a schema is provided, only keys present
+     * in the schema are serialized (schema-aware filtering — unknown keys,
+     * including any stray 'reasoning' key, are dropped). Without a schema,
+     * all keys are serialized as-is.
+     */
+    serializeState(state: SkillState, options?: {
+        pretty?: boolean;
+    }, schema?: StateSchema): string;
+    /**
+     * Describe the schema fields for inclusion in prompts.
+     */
+    private describeSchema;
+}
+//# sourceMappingURL=prompt-transformer.d.ts.map

package/dist/prompt-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-transformer.d.ts","sourceRoot":"","sources":["../src/prompt-transformer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAMN;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAoC;IAEpD,YAAY,OAAO,CAAC,EAAE,wBAAwB,EAE7C;IAED;;;;;OAKG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,EACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAC3C,MAAM,CASR;IAED;;;;;OAKG;IACH,eAAe,CACb,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAmCR;IAED;;;;OAIG;IACH,iBAAiB,CACf,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAyBR;IAED;;;;;;;;;OASG;IACH,WAAW,CACT,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,GACvB,MAAM,CAmBR;IAED;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAqCrB;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGrD;IAED;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG7C;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA2CnD;IAMD;;;;;OAKG;IACH,cAAc,CACZ,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,MAAM,CAcR;IAED;;OAEG;IACH,OAAO,CAAC,cAAc;CAMvB"}

package/dist/prompt-transformer.js

@@ -0,0 +1,265 @@
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Transforms skill state, observations, and specs into formatted prompts
+ * for LLM consumption, and parses structured responses back.
+ *
+ * Only {@link PromptTransformer.formatPaper} is paper-exact (Appendix A.4).
+ * Every other formatter here is an implementation convenience for the
+ * platform adapters — the paper defines no per-platform prompt templates.
+ */
+export class PromptTransformer {
+    platform;
+    constructor(options) {
+        this.platform = options?.platform ?? 'generic';
+    }
+    /**
+     * Format the full prompt. Delegates to platform-specific formatter.
+     *
+     * @non-paper — adapter convenience. Paper-exact callers must use
+     * {@link PromptTransformer.formatPaper}.
+     */
+    formatPrompt(spec, state, observation, platform) {
+        const p = platform ?? this.platform;
+        if (p === 'claude') {
+            return this.formatForClaude(spec, state, observation);
+        }
+        if (p === 'opencode') {
+            return this.formatForOpenCode(spec, state, observation);
+        }
+        return this.formatGeneric(spec, state, observation);
+    }
+    /**
+     * Claude-specific prompt format: markdown with system prompt section,
+     * state section, observation section, instruction for reasoning + JSON.
+     *
+     * @non-paper — adapter convenience; the paper defines no Claude template.
+     */
+    formatForClaude(spec, state, observation) {
+        const stateJson = this.serializeState(state, undefined, spec.schema);
+        const schemaDesc = this.describeSchema(spec.schema);
+        return `# System
+
+You are ${spec.name}. ${spec.instructions}
+
+${schemaDesc}
+
+# Current State
+
+\`\`\`json
+${stateJson}
+\`\`\`
+
+# Observation
+
+${observation.content}
+
+# Instructions
+
+Based on the observation and your current state, provide your response with:
+
+1. Step-by-step reasoning (will be discarded after execution)
+2. A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
+
+\`\`\`json
+{
+  "state_patch": { "key": "new_value", "obsolete_key": null },
+  "action": "your_action_here"
+}
+\`\`\`
+
+In \`state_patch\`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.`;
+    }
+    /**
+     * OpenCode-specific prompt format adapted for the opencode skill system.
+     *
+     * @non-paper — adapter convenience; the paper defines no OpenCode template.
+     */
+    formatForOpenCode(spec, state, observation) {
+        const stateJson = this.serializeState(state, undefined, spec.schema);
+        const schemaDesc = this.describeSchema(spec.schema);
+        return `<skill name="${spec.id}">
+<instructions>${spec.instructions}</instructions>
+${schemaDesc}
+<state>
+${stateJson}
+</state>
+<observation>
+${observation.content}
+</observation>
+</skill>
+
+Respond with step-by-step reasoning followed by a JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
+
+\`\`\`json
+{
+  "state_patch": { "key": "new_value", "obsolete_key": null },
+  "action": "action_name"
+}
+\`\`\`
+
+In \`state_patch\`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.`;
+    }
+    /**
+     * Paper-exact prompt format — byte-verbatim Appendix A.4.
+     *
+     * The template is reproduced exactly as printed in the paper (blank lines
+     * and indentation preserved): instructions start after a blank line, the
+     * state is fenced as ```json with compact JSON (`JSON.stringify(state)` —
+     * the paper's `json.dumps(state, separators=(',', ':'))`), and the response
+     * directive carries the two-key JSON contract verbatim. No schema
+     * description and no platform padding is added on top of A.4.
+     */
+    formatPaper(spec, state, observation) {
+        const stateJson = JSON.stringify(state);
+        return `Instructions:
+
+${spec.instructions}
+
+Skill Execution State:
+
+\`\`\`json
+${stateJson}
+\`\`\`
+Latest Observation: ${observation.content}
+
+Provide your response with:
+
+1. Step-by-step reasoning (will be discarded after execution)
+
+2. A JSON block fenced with json ...  containing both your State Patch and your Action. The JSON block MUST have exactly these two keys: { "state_patch": { <dict: your state updates, set keys to null to delete> }, "action": "<string: the exact command you want to execute>" }`;
+    }
+    /**
+     * Generic prompt format (no platform prefix).
+     *
+     * @non-paper — adapter convenience; the paper-exact template is
+     * {@link PromptTransformer.formatPaper} (Appendix A.4).
+     */
+    formatGeneric(spec, state, observation) {
+        const stateJson = this.serializeState(state, undefined, spec.schema);
+        const schemaDesc = this.describeSchema(spec.schema);
+        return `${spec.instructions}
+
+${schemaDesc}
+
+## Current State
+
+${stateJson}
+
+## Observation
+
+${observation.content}
+
+## Required Output
+
+Provide your response with:
+
+1. Step-by-step reasoning (will be discarded after execution)
+2. A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
+
+\`\`\`json
+{
+  "state_patch": { "key": "value", "obsolete_key": null },
+  "action": "action_name"
+}
+\`\`\`
+
+In \`state_patch\`, set keys to null to delete them.`;
+    }
+    /**
+     * Extract the state_patch from an LLM response containing a fenced JSON block.
+     */
+    extractStatePatch(response) {
+        const result = this.parseResponse(response);
+        return result.ok ? result.patch : null;
+    }
+    /**
+     * Extract the action string from an LLM response containing a fenced JSON block.
+     */
+    extractAction(response) {
+        const result = this.parseResponse(response);
+        return result.ok ? result.action : null;
+    }
+    /**
+     * Parse an LLM response into a typed result: either a valid
+     * { patch, action } pair or a structured failure with a reason.
+     *
+     * Malformed outputs can never corrupt Σt: callers (runtime §7
+     * rollback-retry, adapter hook scripts) must reject `ok: false` results
+     * without touching state (paper Limitations).
+     */
+    parseResponse(response) {
+        // Prefer a closed ```json fence.
+        //
+        // @non-paper extension: fall back to an unterminated fence (common
+        // with truncated LLM output) and attempt to parse the rest. The paper
+        // specifies only the fenced JSON block; lenient recovery is ours.
+        const closed = response.match(/```json[ \t]*\n?([\s\S]*?)\n?[ \t]*```/);
+        const opened = closed ? null : response.match(/```json[ \t]*\n?([\s\S]*)$/);
+        const block = closed ? closed[1] : opened ? opened[1] : null;
+        if (block === null) {
+            return { ok: false, reason: 'no_block' };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(block);
+        }
+        catch (error) {
+            // String(error) renders "SyntaxError: <message>" — includes the
+            // parse error message from JSON.parse.
+            return {
+                ok: false,
+                reason: 'malformed_json',
+                detail: String(error),
+            };
+        }
+        if (!isPlainObject(parsed)) {
+            // A fenced block containing a bare primitive or null has no
+            // state_patch object in it.
+            return { ok: false, reason: 'missing_state_patch' };
+        }
+        const { state_patch: statePatch, action } = parsed;
+        if (!isPlainObject(statePatch)) {
+            return { ok: false, reason: 'missing_state_patch' };
+        }
+        if (typeof action !== 'string') {
+            return { ok: false, reason: 'missing_action' };
+        }
+        return { ok: true, patch: statePatch, action };
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internal helpers                                                   */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Serialize state as JSON. When a schema is provided, only keys present
+     * in the schema are serialized (schema-aware filtering — unknown keys,
+     * including any stray 'reasoning' key, are dropped). Without a schema,
+     * all keys are serialized as-is.
+     */
+    serializeState(state, options, schema) {
+        let toSerialize = state;
+        if (schema) {
+            toSerialize = {};
+            for (const key of Object.keys(state)) {
+                if (key in schema) {
+                    toSerialize[key] = state[key];
+                }
+            }
+        }
+        if (options?.pretty) {
+            return JSON.stringify(toSerialize, null, 2);
+        }
+        return JSON.stringify(toSerialize);
+    }
+    /**
+     * Describe the schema fields for inclusion in prompts.
+     */
+    describeSchema(schema) {
+        const fields = Object.entries(schema)
+            .map(([name, field]) => `- ${name} (${field.type}): ${field.description ?? 'no description'}`)
+            .join('\n');
+        return `## Schema\n${fields}`;
+    }
+}
+//# sourceMappingURL=prompt-transformer.js.map

package/dist/prompt-transformer.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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.
+ */
+/** Legacy LLM function: prompt in, raw response text out. Kept verbatim. */
+export type LLMFnLike = (prompt: string) => Promise<string>;
+/** @non-paper per-call options threaded into `LLMProvider.call`. */
+export interface LLMCallOptions {
+    /** AbortSignal for the in-flight call (runtime forwards its `signal?`). */
+    signal?: AbortSignal;
+}
+/**
+ * @non-paper usage reported by the provider, in raw string CHARS (§4.3).
+ * Both fields are optional: missing values fall back to measuring the
+ * corresponding string, exactly the legacy `LLMFn` behavior.
+ */
+export interface LLMUsage {
+    /** Raw chars of the prompt as sent (overrides `prompt.length`). */
+    promptChars?: number;
+    /** Raw chars of the completion text (overrides `text.length`). */
+    completionChars?: number;
+}
+/** @non-paper provider result: raw text plus optional char usage. */
+export interface LLMResult {
+    text: string;
+    usage?: LLMUsage;
+}
+/**
+ * @non-paper LLM provider. `call` resolves the raw response text and,
+ * when known, its char sizes — so metered hosts are not measured twice.
+ */
+export interface LLMProvider {
+    call(prompt: string, opts?: LLMCallOptions): Promise<LLMResult>;
+}
+/**
+ * @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 declare function isLLMProvider(value: unknown): value is LLMProvider;
+/**
+ * @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 declare function fromLLMFn(fn: LLMFnLike): LLMProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5D,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAKlE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,WAAW,CASpD"}