@skillstate/opencode 2.2.2 → 3.0.1

package/dist/state-store.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Project state persistence for the OpenCode v2 plugin.
+ *
+ * ONE store, THREE guarantees:
+ *
+ * 1. **Per-project addressing.** The state file is derived from the plugin
+ *    instance's location (`ctx.location.project.canonical`), never from
+ *    `process.cwd()`. The v1 plugin called `process.cwd()` on every hook;
+ *    in v2 a single OpenCode server serves many projects, so the process
+ *    cwd is simply the wrong answer. Two checkouts no longer share state.
+ *
+ * 2. **Per-session isolation.** A root session owns the shared project
+ *    file; a sub-agent session owns `agents/<scope>/skillstate.json` (see
+ *    `stateScopeFor`). Parallel sub-agents therefore never last-writer-win
+ *    over the main session's notes.
+ *
+ * 3. **Never lose a write.** Every mutation runs inside the core
+ *    cross-process lock ({@link withStateLock}) and lands via
+ *    {@link atomicWriteFile} (temp sibling → fsync → rename), so a crash
+ *    mid-write can never leave a truncated or interleaved state file. Reads
+ *    never throw: a missing or corrupt file reads as `{}`.
+ *
+ * The store is deliberately schema-free. It does not validate against a
+ * procedural spec: OpenCode sessions are free-form work, and forcing a
+ * fixed `goal`/`progress`/`next_steps` shape is what made the v1 prompt
+ * rewrite the user's actual task into a state machine.
+ */
+import type { StatePatch } from '@skillstate/core';
+/** A skillstate document: a plain JSON object. */
+export type StateDocument = Record<string, unknown>;
+/** Options for {@link ProjectStateStore}. */
+export interface ProjectStateStoreOptions {
+    /**
+     * The project directory the state file lives under. Prefer
+     * `ctx.location.project.canonical` — the canonical checkout, stable
+     * across worktrees.
+     */
+    directory: string;
+    /** Home directory, for the `$HOME` global bucket. Defaults to `os.homedir()`. */
+    home?: string;
+}
+/**
+ * The keys a patch actually changed, split by direction. Mirrors the
+ * `state.patch` MCP contract so behaviour is identical across hosts.
+ */
+export interface StateChanges {
+    readonly added: readonly string[];
+    readonly updated: readonly string[];
+    readonly deleted: readonly string[];
+}
+/** Top-level diff between two state documents. Pure. */
+export declare function diffDocuments(before: StateDocument, after: StateDocument): StateChanges;
+/**
+ * The state file for one session scope inside one project.
+ *
+ * `scope === ''` is the shared project file; any other scope is a
+ * sub-agent's isolated copy. Delegates to the core resolver (shared with
+ * the MCP server, the CLI and the other host adapters) so every host agrees
+ * on where a project's state lives.
+ */
+export declare function statePathFor(directory: string, scope: string, home?: string): string;
+/**
+ * Reads and merges the per-project state documents for a plugin instance.
+ *
+ * Stateless between calls apart from the filesystem, so it is safe to keep
+ * one instance per plugin and to construct it in tests without any global
+ * setup.
+ */
+export declare class ProjectStateStore {
+    private readonly directory;
+    private readonly home;
+    constructor(options: ProjectStateStoreOptions);
+    /** The project directory this store addresses. */
+    get projectDirectory(): string;
+    /** The absolute state file path for a scope (`''` = shared). */
+    pathFor(scope: string): string;
+    /**
+     * Whether a state file already exists for this scope. The plugin uses
+     * this to decide whether to inject the system hint at all — an untouched
+     * project must behave exactly like vanilla OpenCode.
+     */
+    exists(scope: string): boolean;
+    /**
+     * Read a scope's state. A missing, unreadable or corrupt file reads as
+     * `{}` — a best-effort read that never breaks the agent loop.
+     */
+    read(scope: string): StateDocument;
+    /**
+     * Apply a patch to a scope's state and persist it.
+     *
+     * The read, the merge and the write all happen inside the cross-process
+     * lock, so two sub-agents writing disjoint keys both survive — neither
+     * can clobber the other's write by reading a stale snapshot.
+     *
+     * Returns the merged document and the top-level change sets. A `null`
+     * value in the patch deletes that key (paper ⊕).
+     */
+    patch(scope: string, patch: StatePatch): Promise<{
+        state: StateDocument;
+        changes: StateChanges;
+    }>;
+    /**
+     * Fold a sub-agent's document into this scope's document.
+     *
+     * `keep` decides what happens when both sides set the same scalar:
+     * `'existing'` (default) keeps the receiving document's value, `'source'`
+     * takes the sub-agent's. Keys only present in the sub-agent are always
+     * taken, and `null` in either document is a deletion.
+     *
+     * The source document is left on disk — the merge is not destructive, so
+     * a sub-agent's notes remain inspectable after the fold.
+     */
+    merge(scope: string, sourceScope: string, keep?: 'existing' | 'source'): Promise<{
+        state: StateDocument;
+        changes: StateChanges;
+    }>;
+}
+/**
+ * Fold `source` into `target` under a conflict policy. Pure.
+ *
+ * Nested plain objects recurse. A `null` on either side is a deletion and
+ * wins outright — an explicit "remove this" is not a scalar conflict. Every
+ * other scalar conflict follows `keep`.
+ */
+export declare function mergeDocuments(target: StateDocument, source: StateDocument, keep: 'existing' | 'source'): StateDocument;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../src/state-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE/D,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,GACnB,YAAY,CAed;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAqB,GAC1B,MAAM,CAER;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B,YAAY,OAAO,EAAE,wBAAwB,EAG5C;IAED,kDAAkD;IAClD,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,gEAAgE;IAChE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7B;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM7B;IAED;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAQjC;IAED;;;;;;;;;OASG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC,CAY1D;IAED;;;;;;;;;;OAUG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,UAAU,GAAG,QAAqB,GACvC,OAAO,CAAC;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC,CAoB1D;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,UAAU,GAAG,QAAQ,GAC1B,aAAa,CAsBf"}

package/dist/state-store.js

@@ -0,0 +1,186 @@
+/**
+ * Project state persistence for the OpenCode v2 plugin.
+ *
+ * ONE store, THREE guarantees:
+ *
+ * 1. **Per-project addressing.** The state file is derived from the plugin
+ *    instance's location (`ctx.location.project.canonical`), never from
+ *    `process.cwd()`. The v1 plugin called `process.cwd()` on every hook;
+ *    in v2 a single OpenCode server serves many projects, so the process
+ *    cwd is simply the wrong answer. Two checkouts no longer share state.
+ *
+ * 2. **Per-session isolation.** A root session owns the shared project
+ *    file; a sub-agent session owns `agents/<scope>/skillstate.json` (see
+ *    `stateScopeFor`). Parallel sub-agents therefore never last-writer-win
+ *    over the main session's notes.
+ *
+ * 3. **Never lose a write.** Every mutation runs inside the core
+ *    cross-process lock ({@link withStateLock}) and lands via
+ *    {@link atomicWriteFile} (temp sibling → fsync → rename), so a crash
+ *    mid-write can never leave a truncated or interleaved state file. Reads
+ *    never throw: a missing or corrupt file reads as `{}`.
+ *
+ * The store is deliberately schema-free. It does not validate against a
+ * procedural spec: OpenCode sessions are free-form work, and forcing a
+ * fixed `goal`/`progress`/`next_steps` shape is what made the v1 prompt
+ * rewrite the user's actual task into a state machine.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { atomicWriteFile, isPlainObject, mergePatch, migrate, resolveHostStateForCwd, withStateLock, } from '@skillstate/core';
+/** Top-level diff between two state documents. Pure. */
+export function diffDocuments(before, after) {
+    const added = [];
+    const updated = [];
+    const deleted = [];
+    for (const key of Object.keys(after)) {
+        if (!(key in before)) {
+            added.push(key);
+        }
+        else if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) {
+            updated.push(key);
+        }
+    }
+    for (const key of Object.keys(before)) {
+        if (!(key in after))
+            deleted.push(key);
+    }
+    return { added, updated, deleted };
+}
+/**
+ * The state file for one session scope inside one project.
+ *
+ * `scope === ''` is the shared project file; any other scope is a
+ * sub-agent's isolated copy. Delegates to the core resolver (shared with
+ * the MCP server, the CLI and the other host adapters) so every host agrees
+ * on where a project's state lives.
+ */
+export function statePathFor(directory, scope, home = os.homedir()) {
+    return resolveHostStateForCwd(directory, home, scope);
+}
+/**
+ * Reads and merges the per-project state documents for a plugin instance.
+ *
+ * Stateless between calls apart from the filesystem, so it is safe to keep
+ * one instance per plugin and to construct it in tests without any global
+ * setup.
+ */
+export class ProjectStateStore {
+    directory;
+    home;
+    constructor(options) {
+        this.directory = path.resolve(options.directory);
+        this.home = options.home ?? os.homedir();
+    }
+    /** The project directory this store addresses. */
+    get projectDirectory() {
+        return this.directory;
+    }
+    /** The absolute state file path for a scope (`''` = shared). */
+    pathFor(scope) {
+        return statePathFor(this.directory, scope, this.home);
+    }
+    /**
+     * Whether a state file already exists for this scope. The plugin uses
+     * this to decide whether to inject the system hint at all — an untouched
+     * project must behave exactly like vanilla OpenCode.
+     */
+    exists(scope) {
+        try {
+            return fs.statSync(this.pathFor(scope)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read a scope's state. A missing, unreadable or corrupt file reads as
+     * `{}` — a best-effort read that never breaks the agent loop.
+     */
+    read(scope) {
+        const filePath = this.pathFor(scope);
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            return migrate(JSON.parse(raw)).state;
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Apply a patch to a scope's state and persist it.
+     *
+     * The read, the merge and the write all happen inside the cross-process
+     * lock, so two sub-agents writing disjoint keys both survive — neither
+     * can clobber the other's write by reading a stale snapshot.
+     *
+     * Returns the merged document and the top-level change sets. A `null`
+     * value in the patch deletes that key (paper ⊕).
+     */
+    async patch(scope, patch) {
+        const filePath = this.pathFor(scope);
+        const result = await withStateLock(filePath, async () => {
+            const before = this.read(scope);
+            const after = mergePatch(before, patch);
+            await atomicWriteFile(filePath, `${JSON.stringify({ version: 1, state: after }, null, 2)}\n`);
+            return { state: after, changes: diffDocuments(before, after) };
+        });
+        return result;
+    }
+    /**
+     * Fold a sub-agent's document into this scope's document.
+     *
+     * `keep` decides what happens when both sides set the same scalar:
+     * `'existing'` (default) keeps the receiving document's value, `'source'`
+     * takes the sub-agent's. Keys only present in the sub-agent are always
+     * taken, and `null` in either document is a deletion.
+     *
+     * The source document is left on disk — the merge is not destructive, so
+     * a sub-agent's notes remain inspectable after the fold.
+     */
+    async merge(scope, sourceScope, keep = 'existing') {
+        if (sourceScope === scope) {
+            throw new Error('skillstate_merge: a sub-agent cannot merge its own state');
+        }
+        const source = this.read(sourceScope);
+        if (Object.keys(source).length === 0) {
+            throw new Error(`skillstate_merge: no saved state for sub-agent "${sourceScope}" — nothing to merge`);
+        }
+        const filePath = this.pathFor(scope);
+        return withStateLock(filePath, async () => {
+            const before = this.read(scope);
+            const after = mergeDocuments(before, source, keep);
+            await atomicWriteFile(filePath, `${JSON.stringify({ version: 1, state: after }, null, 2)}\n`);
+            return { state: after, changes: diffDocuments(before, after) };
+        });
+    }
+}
+/**
+ * Fold `source` into `target` under a conflict policy. Pure.
+ *
+ * Nested plain objects recurse. A `null` on either side is a deletion and
+ * wins outright — an explicit "remove this" is not a scalar conflict. Every
+ * other scalar conflict follows `keep`.
+ */
+export function mergeDocuments(target, source, keep) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (value === null) {
+            delete result[key];
+            continue;
+        }
+        if (!(key in result)) {
+            result[key] = value;
+            continue;
+        }
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergeDocuments(result[key], value, keep);
+            continue;
+        }
+        if (keep === 'source')
+            result[key] = value;
+    }
+    return result;
+}
+//# sourceMappingURL=state-store.js.map

package/dist/state-store.js.map

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

package/dist/step-boundary.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The step boundary — §5.1's one observation per step, enforced in code.
+ *
+ * ── The divergence this fixes ─────────────────────────────────────────────
+ *
+ * The paper's Algorithm 1 alternates, once per step:
+ *
+ *     Aₜ ← Format(P, Σₜ, Oₜ);  resp ← llm(Aₜ);  Σₜ₊₁ ← Σₜ ⊕ ΔΣₜ;  Oₜ₊₁ ← execute(aₜ)
+ *
+ * One prompt, one patch, one action, one observation. The model is never
+ * given a loop of its own, so it has no opportunity to run twenty things
+ * inside one step, and the state cannot lag the work.
+ *
+ * This integration cannot own the model call or the tool execution — the
+ * OpenCode plugin API exposes neither, and that is a real limit rather than a
+ * design choice. What it can do is own the *boundary*, and that is the half
+ * that was missing. Delegating execution to the host's agent loop handed the
+ * model an unbounded inner loop, and it used it: 21 tool calls, 3 text
+ * blocks, one state patch written at the end from whatever observation was
+ * current. Two models, repeated runs. The state lagged the work, and a model
+ * whose running total lags cannot accumulate.
+ *
+ * The fix uses a capability that is present and unused: `SessionContext.tools`
+ * is handed to the `context` hook on *every* model request. So requests
+ * alternate. One may act — tools present, the host executes, the observation
+ * lands in Oₜ. The next is given no tools at all, and a model that has just
+ * acted and is asked again with nothing to call can only answer in text, which
+ * is exactly where `state_patch` lives.
+ *
+ * That is §5.1's alternation with the host standing in for both `llm` and
+ * `execute`. It is not a simulation of the loop: the host really runs the
+ * action, and the state really moves between steps.
+ *
+ * ── What it does not do ───────────────────────────────────────────────────
+ *
+ * It cannot make the model write a *good* patch, only make it answer. The
+ * merge, the validation and the retry-with-rollback are unchanged, and a
+ * patch that fails validation is still refused. This buys the paper's
+ * one-observation-per-step; it does not buy correctness of reasoning.
+ */
+export declare class StepBoundary {
+    #private;
+    /**
+     * Decide what a request may do, and remember the answer.
+     *
+     * Returns true when the model may act. A session starts in `act`, so the
+     * first request can do real work; every request after an action is a report.
+     */
+    mayAct(sessionID: string): boolean;
+    /**
+     * Record that an action ran, so the next request must report.
+     *
+     * Called when the host executed a tool on this session's behalf. There is
+     * no event that says "a tool finished" in a form the plugin can trust for
+     * this, so the boundary is advanced from the patch instead — see
+     * {@link reportRequired}. Kept as a separate method so the trigger can
+     * change without the cycle changing.
+     */
+    actionTaken(sessionID: string): void;
+    /**
+     * Whether this request must be answered with a state patch.
+     *
+     * The single question the context hook needs. It is also the whole point:
+     * the model gets one turn to act and one turn to account for it.
+     */
+    reportRequired(sessionID: string): boolean;
+    /**
+     * A patch was applied, so the next request may act again.
+     *
+     * Only an *applied* patch clears the phase. A rejected one leaves the model
+     * in `report`, which is what the retry-with-rollback in §6.3 needs: it is
+     * re-asked for the same step rather than being let off the hook to act
+     * before it has recorded anything.
+     */
+    patchApplied(sessionID: string): void;
+    /** Reset a session, on teardown or a fresh run. */
+    reset(sessionID: string): void;
+    /** Forget everything. A plugin unload must not leak a phase map. */
+    clear(): void;
+    /** How many sessions are mid-cycle, for diagnostics and tests. */
+    get size(): number;
+}
+/**
+ * Whether an action ends the procedure.
+ *
+ * Shared with the runtime so the two agree on what "finished" means. They
+ * answer the same question from the same string, and two copies of that would
+ * be two definitions to keep in step.
+ */
+export declare function isTerminalAction(action: string): boolean;
+//# sourceMappingURL=step-boundary.d.ts.map

package/dist/step-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-boundary.d.ts","sourceRoot":"","sources":["../src/step-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAQH,qBAAa,YAAY;;IAGvB;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEnC;IAED;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEzC;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEpC;IAED,mDAAmD;IACnD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE7B;IAED,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAEZ;IAED,kEAAkE;IAClE,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/step-boundary.js

@@ -0,0 +1,109 @@
+/**
+ * The step boundary — §5.1's one observation per step, enforced in code.
+ *
+ * ── The divergence this fixes ─────────────────────────────────────────────
+ *
+ * The paper's Algorithm 1 alternates, once per step:
+ *
+ *     Aₜ ← Format(P, Σₜ, Oₜ);  resp ← llm(Aₜ);  Σₜ₊₁ ← Σₜ ⊕ ΔΣₜ;  Oₜ₊₁ ← execute(aₜ)
+ *
+ * One prompt, one patch, one action, one observation. The model is never
+ * given a loop of its own, so it has no opportunity to run twenty things
+ * inside one step, and the state cannot lag the work.
+ *
+ * This integration cannot own the model call or the tool execution — the
+ * OpenCode plugin API exposes neither, and that is a real limit rather than a
+ * design choice. What it can do is own the *boundary*, and that is the half
+ * that was missing. Delegating execution to the host's agent loop handed the
+ * model an unbounded inner loop, and it used it: 21 tool calls, 3 text
+ * blocks, one state patch written at the end from whatever observation was
+ * current. Two models, repeated runs. The state lagged the work, and a model
+ * whose running total lags cannot accumulate.
+ *
+ * The fix uses a capability that is present and unused: `SessionContext.tools`
+ * is handed to the `context` hook on *every* model request. So requests
+ * alternate. One may act — tools present, the host executes, the observation
+ * lands in Oₜ. The next is given no tools at all, and a model that has just
+ * acted and is asked again with nothing to call can only answer in text, which
+ * is exactly where `state_patch` lives.
+ *
+ * That is §5.1's alternation with the host standing in for both `llm` and
+ * `execute`. It is not a simulation of the loop: the host really runs the
+ * action, and the state really moves between steps.
+ *
+ * ── What it does not do ───────────────────────────────────────────────────
+ *
+ * It cannot make the model write a *good* patch, only make it answer. The
+ * merge, the validation and the retry-with-rollback are unchanged, and a
+ * patch that fails validation is still refused. This buys the paper's
+ * one-observation-per-step; it does not buy correctness of reasoning.
+ */
+/** Actions that end the procedure rather than continuing it. */
+const TERMINAL = new Set(['done', 'complete', 'completed', 'finished', 'stop', 'end', '']);
+export class StepBoundary {
+    #phase = new Map();
+    /**
+     * Decide what a request may do, and remember the answer.
+     *
+     * Returns true when the model may act. A session starts in `act`, so the
+     * first request can do real work; every request after an action is a report.
+     */
+    mayAct(sessionID) {
+        return (this.#phase.get(sessionID) ?? 'act') === 'act';
+    }
+    /**
+     * Record that an action ran, so the next request must report.
+     *
+     * Called when the host executed a tool on this session's behalf. There is
+     * no event that says "a tool finished" in a form the plugin can trust for
+     * this, so the boundary is advanced from the patch instead — see
+     * {@link reportRequired}. Kept as a separate method so the trigger can
+     * change without the cycle changing.
+     */
+    actionTaken(sessionID) {
+        this.#phase.set(sessionID, 'report');
+    }
+    /**
+     * Whether this request must be answered with a state patch.
+     *
+     * The single question the context hook needs. It is also the whole point:
+     * the model gets one turn to act and one turn to account for it.
+     */
+    reportRequired(sessionID) {
+        return (this.#phase.get(sessionID) ?? 'act') === 'report';
+    }
+    /**
+     * A patch was applied, so the next request may act again.
+     *
+     * Only an *applied* patch clears the phase. A rejected one leaves the model
+     * in `report`, which is what the retry-with-rollback in §6.3 needs: it is
+     * re-asked for the same step rather than being let off the hook to act
+     * before it has recorded anything.
+     */
+    patchApplied(sessionID) {
+        this.#phase.set(sessionID, 'act');
+    }
+    /** Reset a session, on teardown or a fresh run. */
+    reset(sessionID) {
+        this.#phase.delete(sessionID);
+    }
+    /** Forget everything. A plugin unload must not leak a phase map. */
+    clear() {
+        this.#phase.clear();
+    }
+    /** How many sessions are mid-cycle, for diagnostics and tests. */
+    get size() {
+        return this.#phase.size;
+    }
+}
+/**
+ * Whether an action ends the procedure.
+ *
+ * Shared with the runtime so the two agree on what "finished" means. They
+ * answer the same question from the same string, and two copies of that would
+ * be two definitions to keep in step.
+ */
+export function isTerminalAction(action) {
+    return TERMINAL.has(action.trim().toLowerCase());
+}
+//# sourceMappingURL=step-boundary.js.map

package/dist/step-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-boundary.js","sourceRoot":"","sources":["../src/step-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,gEAAgE;AAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;AAE3F,MAAM,OAAO,YAAY;IACd,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IAE3C;;;;;OAKG;IACH,MAAM,CAAC,SAAiB;QACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC;IACzD,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,SAAiB;QAC3B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,SAAiB;QAC9B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,QAAQ,CAAC;IAC5D,CAAC;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,SAAiB;QAC5B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,oEAAoE;IACpE,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,kEAAkE;IAClE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACnD,CAAC"}

package/dist/system-hint.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The system-prompt fragment the plugin contributes to each model request.
+ *
+ * ── Why this module is so small and so careful ───────────────────────────
+ *
+ * The v1 integration rewrote the conversation on every turn: it truncated
+ * history to the last three messages and appended a synthetic `role: "user"`
+ * message whose body was the raw state JSON. The reported symptom was that
+ * the agent stopped doing what it was asked and started emitting state
+ * JSON instead. The cause was structural, not a model quirk:
+ *
+ * - The last `role: "user"` message is what the model treats as the current
+ *   instruction, so the state blob displaced the user's actual request.
+ * - Truncating history deleted the task statement, the tool results, and
+ *   the errors the agent had just been given — it could not reason about
+ *   work it could no longer see.
+ *
+ * The fix is a rule, enforced by `tests/opencode/context-integrity.test.ts`:
+ * **this plugin never mutates `event.messages`.** It contributes one
+ * additive, bounded fragment to `event.system`, states what the tools are
+ * for, and explicitly leaves the task alone.
+ *
+ * The wording below is a product requirement, not prose taste. It must
+ * describe the tools without instructing the model to change how it works.
+ * Imperative framing ("you must", "always", "respond with a JSON block")
+ * is what turns a persistence aid into a prompt override.
+ */
+/** Largest state JSON rendered into the hint before falling back to a key list. */
+export declare const MAX_INLINE_STATE_CHARS = 4000;
+/** The tool names the hint advertises — kept in sync with `tools.ts`. */
+export declare const ADVERTISED_TOOLS: readonly ['skillstate_read', 'skillstate_update', 'skillstate_merge'];
+/**
+ * Render a state document for inclusion in the system prompt.
+ *
+ * Small documents are inlined verbatim (the model sees what is already
+ * saved without a tool round-trip). Documents past
+ * {@link MAX_INLINE_STATE_CHARS} are summarized as a key list plus a count and
+ * a pointer to `skillstate_read` — an unbounded state file must not be able to
+ * grow the system prompt without limit.
+ *
+ * The reported count is in the SAME UNIT as the limit, and it is labelled with
+ * that unit's name. The first version reported `bytes` next to a limit expressed
+ * in characters, which is this project's whole recurring mistake in one line: a
+ * state of 4,003 Cyrillic characters is 3,003 over the limit and 7,993 bytes, so
+ * the model reading the summary was handed two numbers in two units and a limit
+ * in a third. §4.3 is explicit that sizes here are raw string CHARS.
+ */
+export declare function renderStateForHint(state: Record<string, unknown>): string;
+/**
+ * How many MODEL REQUESTS may pass with the state untouched before the drift
+ * notice fires.
+ *
+ * **"Requests", not "turns".** Measured on the weakest model in the
+ * catalogue: 20 file reads took 6 requests, 40 reads took 12, 70 reads took
+ * 27. The model batches tool calls, so a request is worth several file reads
+ * and a threshold described in "turns" is off by a factor of three. The
+ * number here is the unit the hook can actually count.
+ *
+ * 12 is chosen from the corpus rather than taste: the average run in the
+ * host's own store showed the model ~29,900 prompt tokens per request, so a
+ * dozen silent requests is roughly 350k tokens re-sent for a record that
+ * never moved. High enough that an agent reading five files in a row is not
+ * nagged.
+ */
+export declare const DRIFT_NOTICE_AFTER_TURNS = 12;
+/** Options for {@link buildStateHint}. */
+export interface StateHintOptions {
+    /** The state document this session has saved. */
+    state: Record<string, unknown>;
+    /** Project-relative state path, for the model's reference. */
+    statePath: string;
+    /**
+     * This session's scope, or `''` when it is a root session. A sub-agent
+     * hint names the merge step so the main session can fold its notes back.
+     */
+    scope?: string;
+    /**
+     * The fields a project `skill-spec.json` declares, when one is present.
+     *
+     * Notes mode does not ENFORCE a schema — §4.1 scopes the schema to a spec P,
+     * and notes mode has no P because it never formats an A.4 prompt. What it
+     * must not do is stay silent, and it was: a project shipped a schema, a model
+     * read it, ignored it, and wrote thirty files under a namespace it invented
+     * while the declared fields sat at their defaults. Nothing said so, and the
+     * state looked populated to a reader checking the wrong key.
+     *
+     * So the fields are stated, not enforced. A model that follows them writes
+     * the state where the spec says; one that does not has been told where the
+     * spec says, which is the difference between an override and an oversight.
+     */
+    declaredFields?: readonly string[];
+    /**
+     * True when the project is INITIALIZED — a state file exists for it.
+     *
+     * This is the whole difference between an optional side channel and a
+     * record, and the two must not be phrased the same way. Telling a model to
+     * "skip these tools when the work needs no memory" is correct advice for a
+     * scratch project and an invitation to walk away in a real one, where the
+     * user initialized skillstate precisely because the work does need it.
+     */
+    initialized?: boolean;
+    /**
+     * Turns taken since the state last changed. Set by the caller, which
+     * counts; see {@link DRIFT_NOTICE_AFTER_TURNS}.
+     */
+    turnsSinceWrite?: number;
+}
+/**
+ * The notice shown once when the state has not moved for a long stretch.
+ *
+ * This is feedback, not an instruction, and the distinction is the whole
+ * design. It states a measured fact — this many turns, no write — and
+ * nothing about what the model ought to do. That keeps the v1 failure
+ * impossible (nothing here can displace the user's task) while still
+ * telling a drifting agent that the user initialized this for a reason.
+ *
+ * It fires once per silence, not every turn: a notice that repeats forever
+ * is wallpaper, and after the second copy nobody reads it.
+ */
+export declare function driftNotice(turnsSinceWrite: number): string;
+/**
+ * Build the system-prompt fragment.
+ *
+ * Returns `''` for an empty document so an untouched project contributes
+ * nothing at all — the plugin is inert until the agent actually saves
+ * something, and an inert plugin is indistinguishable from no plugin.
+ */
+export declare function buildStateHint(options: StateHintOptions): string;
+//# sourceMappingURL=system-hint.d.ts.map

package/dist/system-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-hint.d.ts","sourceRoot":"","sources":["../src/system-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,YAC3B,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,CACV,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAczE;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAkDhE"}