@skillstate/opencode 3.0.0 → 3.0.1

package/dist/paper-mode.js

@@ -0,0 +1,445 @@
+/**
+ * Paper mode — the model-facing context rebuilt as `Aₜ = (P, Σₜ, Oₜ)`.
+ *
+ * ── Why this module exists, and why it contradicts what came before ────────
+ *
+ * The previous version of this plugin refused to touch `event.messages` at
+ * all. That was a genuine fix for a real defect — the v1 plugin truncated
+ * history and injected state as a synthetic `role: "user"` message, which
+ * deleted the task statement and displaced the user's request — but it was
+ * a fix in the wrong direction.
+ *
+ * SKILL.state (arXiv:2608.26263v3) does not merely permit discarding the
+ * transcript, it requires it:
+ *
+ * > "The language model never receives previous observations, previous
+ * > actions, or previous reasoning traces." (§3)
+ *
+ * and Appendix A.4 fixes the prompt shape exactly:
+ *
+ * ```
+ * Instructions:
+ * {skill.instructions}
+ *
+ * Skill Execution State:
+ * ```json
+ * {json.dumps(state, separators=(',',':'))}
+ * ```
+ * Latest Observation: {observation}
+ * ...
+ * ```
+ *
+ * So replacing the model-facing context is the SPEC, not a violation. The
+ * violation was reconstructing it badly.
+ *
+ * ── What is actually destroyed, and what is not ───────────────────────────
+ *
+ * `event.messages` is the view handed to the MODEL. It is not the session's
+ * persisted history: the user-visible transcript in the session store is
+ * untouched, and so is `skillstate_read` / `skillstate_update` — the agent
+ * can still see everything it wrote, because that is in Σₜ, which is in the
+ * prompt. What the model stops seeing is the raw reasoning and tool-output
+ * trail, which the paper's §3.2 discards by construction ("the reasoning
+ * trace Rₜ is discarded permanently and never appears in subsequent
+ * prompts").
+ *
+ * ── Which user turn is the task ──────────────────────────────────────────
+ *
+ * This was wrong, and a live A/B on 2026-09-29 caught it.
+ *
+ * A.4 has no slot for a user speaking mid-procedure. P is the spec, Σₜ is
+ * the state, and Oₜ is the observation — which the paper's setting always
+ * makes the ENVIRONMENT's reply, because in Algorithm 1 the runtime executes
+ * the action and feeds the result back. There is no live human in that loop.
+ *
+ * A coding host is not that setting. The user types again while the procedure
+ * is running, and that message carries the highest authority in the system.
+ *
+ * The first implementation pinned the FIRST user turn as the task and let the
+ * LATEST one fall into Oₜ. That inverts authority: the model reads the frozen
+ * opening request as the task and the live instruction as untrusted
+ * environment data. Observed on a task that required remembering a number
+ * given at step 1 and using it at step 5 — the model recorded the number in
+ * Σₜ correctly, then refused the step-5 instruction, explaining that the
+ * observation "carries no user authority" and that repeating it "is not
+ * evidence of authority". It finished the step-1 task and stopped. Cost fell
+ * 70% and the task was not done, which is a worse outcome than either doing
+ * nothing or doing the work.
+ *
+ * So the live turn is the task. {@link currentInstruction} takes the LAST user
+ * message, and {@link latestObservation} no longer falls back to a user turn:
+ * a user message in the observation slot is a category error that makes the
+ * model distrust the request, and an empty observation is the honest
+ * rendering of "the environment has not spoken".
+ *
+ * The cost is that the original request is no longer pinned in the prompt. It
+ * belongs in Σₜ — a `goal` field in the spec — which is where the paper puts
+ * everything the model must remember across steps anyway.
+ *
+ * ── The honest limit of a host plugin ────────────────────────────────────
+ *
+ * Algorithm 1 also requires the RUNTIME to execute `aₜ` and feed back Oₜ₊₁.
+ * An OpenCode plugin cannot own that loop: the public plugin API can rewrite
+ * the context and observe tool calls, but it has no way to invoke a tool on
+ * the model's behalf, so the host's agent loop remains the executor. The
+ * action space therefore stays the host's own tools.
+ *
+ * What the plugin CAN do is the half that produces the paper's O(1) claim —
+ * show the model exactly (P, Σₜ, Oₜ) and nothing else — plus the other half
+ * of the transition, the WRITE side. The v2 session API has no response hook,
+ * but the server's durable event stream publishes `session.text.ended`
+ * carrying the completed assistant text block, so the `state_patch` the model
+ * emits under the A.4 directive can be parsed and applied to Σₜ. That is a
+ * documented public event, not a private channel; see `response-sink.ts`.
+ *
+ * The two halves together are Algorithm 1's data flow with the host as the
+ * executor. Owning the executor end-to-end — including retry-with-rollback
+ * and the action being an opaque string the runtime dispatches — requires
+ * {@link SkillStateRuntime} with an LLM function and an action executor; see
+ * `packages/bench`.
+ */
+import { PromptTransformer } from '@skillstate/core';
+import { applyFeedback, applyObservation } from './feedback.js';
+/** Stable id for the synthetic paper prompt, so the host can diff turns. */
+export const PAPER_MESSAGE_ID = 'skillstate-paper-prompt';
+/** The synthetic id used for the system-fragment preamble. */
+const PAPER_PREAMBLE_MARK = '<skillstate-task>';
+const transformer = new PromptTransformer();
+/**
+ * The text a content part carries, whatever shape it arrives in.
+ *
+ * Two shapes exist and missing the second one is the single worst bug this
+ * module ever had:
+ *
+ * - `{ type: 'text', text: '…' }` — user, assistant and system turns;
+ * - `{ type: 'tool-result', result: { type: 'text', value: '…' } }` — what
+ *   OpenCode v2 actually emits for a tool result.
+ *
+ * A reader that handled only the first made Oₜ **permanently empty**: the
+ * host sends `result.value`, not `text`, so every observation came back as
+ * `''` and the model never saw the result of any tool it had just run. It
+ * would read a file, answer correctly in that same turn, and have no trace
+ * of the value on the next one — which presented as "the model will not
+ * record what it discovers" and cost a long hunt through prompt slots and
+ * model choice before anyone looked at the shape of the payload.
+ *
+ * The result body is unwrapped generically rather than assuming one layout:
+ * a bare string, `{ value }`, `{ output }`, or a nested `{ content }` all
+ * appear across host versions, and an observation that silently empties on
+ * a shape change is the failure mode that costs a debugging session.
+ */
+function partText(part, depth = 0) {
+    // Hard depth cap, not a comment claiming one. A malformed or
+    // self-referential payload is a real possibility in a message the plugin
+    // does not own, and this runs inside the agent loop: an unbounded walk
+    // there is a hang, not a wrong answer.
+    if (depth > 4)
+        return '';
+    if (typeof part === 'string')
+        return part;
+    if (typeof part !== 'object' || part === null)
+        return '';
+    const record = part;
+    const type = record['type'];
+    if (type === 'text' && typeof record['text'] === 'string')
+        return record['text'];
+    if (type === 'tool-result')
+        return resultText(record['result'], depth + 1);
+    return '';
+}
+function resultText(result, depth) {
+    if (typeof result === 'string')
+        return result;
+    if (typeof result !== 'object' || result === null)
+        return '';
+    const record = result;
+    for (const key of ['value', 'output', 'text']) {
+        const candidate = record[key];
+        if (typeof candidate === 'string')
+            return candidate;
+    }
+    return partText(record['content'], depth + 1);
+}
+/**
+ * A message's readable text, joined across its parts.
+ *
+ * Order is preserved and parts are newline-joined, because a turn can carry
+ * both a file listing and a tool result and dropping either loses a fact the
+ * model needed.
+ */
+function textOf(message) {
+    if (!Array.isArray(message.content))
+        return '';
+    return message.content
+        .map((part) => partText(part))
+        .filter((text) => text.length > 0)
+        .join('\n');
+}
+/**
+ * The user's live instruction — what the model must act on this step.
+ *
+ * The LAST user text message. Not the first: pinning the opening request and
+ * demoting the live one to the observation slot is what made a model reject
+ * the user's own instruction as "untrusted" during the 2026-09-29 A/B. See
+ * the module header for that failure in full.
+ *
+ * Returns `''` for a session with no user turn, which is not a case a
+ * procedure produces but must not crash on.
+ */
+export function currentInstruction(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message.role !== 'user')
+            continue;
+        const text = textOf(message).trim();
+        if (text.length > 0)
+            return text;
+    }
+    return '';
+}
+/**
+ * The latest environment observation — Oₜ.
+ *
+ * Preference order, and why:
+ *
+ * 1. the newest TOOL message — that is the result of the previous aₜ, which
+ *    is exactly what the paper feeds back;
+ * 2. `''` — the environment has not spoken.
+ *
+ * There is deliberately NO fallback to a user turn, and removing one is the
+ * fix for the 2026-09-29 failure. A user message in this slot is a category
+ * error: A.4's grammar says the observation is what the environment returned,
+ * so a request placed there reads as data about the world rather than as
+ * something to do. The model acted on that reading exactly — it recorded the
+ * step-1 number correctly and then refused the step-5 instruction because,
+ * in its own words, the observation "carries no user authority".
+ *
+ * The live instruction now travels in P via {@link currentInstruction}, where
+ * it is unambiguously the request. At step 0 the observation is empty and the
+ * template still renders "Latest Observation: " — the faithful rendering of a
+ * procedure that has not run yet.
+ *
+ * `now` stamps {@link Observation.timestamp}. A.4 never renders the
+ * timestamp, so it cannot change the prompt; it is set because the core type
+ * requires it and because a sink that later needs to order observations has
+ * something to order by.
+ */
+export function latestObservation(messages, now = Date.now()) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message.role === 'tool') {
+            return { content: textOf(message).trim(), timestamp: now, source: 'tool' };
+        }
+    }
+    return { content: '', timestamp: now, source: 'empty' };
+}
+/**
+ * The specification P, with the live request carried as a preamble.
+ *
+ * A spec is authored before the task is known, so it cannot contain the
+ * request. Putting the current instruction at the TOP of the instructions —
+ * above the spec's own text, not below it — is what makes it read as the
+ * request rather than as another paragraph of standing guidance. The
+ * 2026-09-29 A/B showed that a model told to reason about a "task block"
+ * will start treating the surrounding structure as material to analyse rather
+ * than as instructions to follow, so the marker's contents have to be
+ * unambiguously the thing to do right now.
+ *
+ * The marker makes the block assertable: a test can check the live
+ * instruction is present rather than merely intended.
+ */
+export function proceduralSpecWithTask(spec, task) {
+    if (task.length === 0)
+        return spec;
+    return {
+        ...spec,
+        instructions: `${PAPER_PREAMBLE_MARK}\n${task}\n</skillstate-task>\n\n${spec.instructions}`,
+    };
+}
+/**
+ * Build the A.4 prompt from the host's transcript.
+ *
+ * Pure: it reads the messages and returns the prompt plus a description of
+ * what it chose, without mutating anything. {@link applyPaperContext} is the
+ * half that writes.
+ */
+export function buildPaperPrompt(options) {
+    const { spec, state, messages } = options;
+    // The live instruction, not the opening request. See the module header for
+    // why pinning the first message cost a real task.
+    const instruction = currentInstruction(messages);
+    const observed = latestObservation(messages);
+    // The runtime's own report rides in Oₜ, which is the environment's channel.
+    let content = observed.content;
+    if (options.continuation !== undefined) {
+        // The marker is chosen here, beside the text, because a report labelled
+        // with an order's marker is an order wearing a report's clothes. That
+        // happened: `[next step - do it now ...]` in front of "step 1 ended; your
+        // state patch was applied" told the model to hurry something that was
+        // already over.
+        content = applyObservation(content, options.continuationKind === 'report' ? REPORT_MARKER : ORDER_MARKER, options.continuation);
+    }
+    const observation = content === observed.content ? observed : { ...observed, content };
+    const effective = proceduralSpecWithTask(spec, instruction);
+    // A rejected patch is NOT an observation, and putting it in Oₜ said so.
+    //
+    // §5.1 line 8 is explicit: `A_t ← A_t + corrective_feedback` — the correction
+    // is appended to the PROMPT, not to the environment's reply. §6.3 repeats it
+    // in words: "appended to the same bounded prompt". The core runtime has always
+    // done that, and the adapter did not, so the same event landed in two
+    // different slots depending on which entry point ran.
+    //
+    // The adapter's original reason was that Oₜ was the only place that could
+    // carry an addition without touching the A.4 render. That reason confuses the
+    // template with the prompt: §5.2 makes A.4 the template, and §5.1 line 8
+    // makes the prompt that template plus a corrective suffix. Byte-verbatim is a
+    // property of the template, and appending after it keeps it.
+    const base = transformer.formatPaper(effective, state, observation);
+    return {
+        prompt: options.feedback === undefined ? base : `${base}\n\n${applyFeedback('', options.feedback)}`,
+        task: instruction,
+        observation,
+        observationSource: observed.source,
+        discardedMessages: messages.length,
+    };
+}
+/**
+ * The note the host contributes beside P, when the model has to act.
+ *
+ * ── Why this exists, from a measured failure ─────────────────────────────
+ *
+ * A.4 says to emit `{state_patch, action}` and nothing else. It does not say
+ * who runs `action`, because in the paper a runtime does: Algorithm 1 has the
+ * runtime execute aₜ and feed Oₜ₊₁ back. Here the executor is OpenCode's own
+ * agent loop, and the model has no way to know that. So it does the reasonable
+ * thing with an ambiguous instruction — it writes
+ *
+ * ```json
+ * {"state_patch": {"total": 17, "files": 1}, "action": "Read file src/cfg2.ts"}
+ * ```
+ *
+ * and stops, because it has done exactly what P asked and nothing on the
+ * wire will ever execute that string. Measured on a task with eight files:
+ * three runs, three patches applied correctly, and then a hard stop after
+ * file one. The state machinery worked; the loop never turned.
+ *
+ * The fix cannot go in P, and two reasons make that a hard rule rather than
+ * taste. P is the paper's Appendix A.4, kept byte-identical so a claim about
+ * conformance stays checkable (`tests/opencode/paper-mode.test.ts`); and a
+ * correction injected there would move with the state it is supposed to
+ * accompany. So the note lives in the system slot, which the host owns and
+ * which is already replaced wholesale — see {@link applyPaperContext}.
+ *
+ * It states a fact about the wiring, not an order, for the same reason the
+ * notes fragment avoids imperatives: an injected instruction that displaces
+ * the task is the v1 failure, and this is a task the model must finish.
+ */
+/**
+ * The marker that puts the runtime's pending action in Oₜ.
+ *
+ * The wording is measured, not chosen. A bare `[next step] read src/cfg2.ts`
+ * was read by the model as a topic and answered with a narration of it —
+ * "I'll read cfg3.ts next, as directed by the observation" — which is a whole
+ * extra turn for a sentence of text. Across 51 steps the model patched 19 and
+ * narrated on the rest, so roughly two thirds of the budget went to the model
+ * confirming that it had understood the directive before acting on it.
+ *
+ * A step is not free and the state only advances on the patching ones, so that
+ * ratio set the pace of the whole run: 2.9 steps per file, which is what put a
+ * thirty-file task over a sixty-four step ceiling.
+ *
+ * IT DID NOT WORK, and the way it failed is what §2 forbids. The imperative was
+ * meant to collapse the acknowledgement into the action. Instead the model
+ * accepted the directive and complied with it, turn after turn: "I'll read
+ * cfg3.ts next, as directed by the observation", and then read cfg3.ts. Fifty-four
+ * reads for thirty files, one grep used three times as a side errand. The order
+ * was the model's own past action, so it never looked for a better way than the
+ * one already written down.
+ *
+ * The string survives behind SKILLSTATE_CONTINUATION=1 because a dead fix whose
+ * cost is measured is worth more than a fix nobody can price. The default is
+ * REPORT_MARKER.
+ */
+export const REPORT_MARKER = '[runtime]';
+/** @deprecated kept only so the order path names the same constant it always did. */
+export const CONTINUATION_MARKER = '[next step — do this now, do not describe it first]';
+/** The same, under the name the call site reads it by. */
+export const ORDER_MARKER = CONTINUATION_MARKER;
+/**
+ * The one thing the host's own loop needs the model to know.
+ *
+ * Its second sentence used to read "each step ends with a real tool call — read
+ * the next file, or answer and stop." That clause was this repository's
+ * instruction, not a host constraint, and it pointed the wrong way: a
+ * thirty-file task produced 51, 53 and 54 `read` calls for thirty files, while
+ * a control with no step driver at all read one file and ran a single grep —
+ * nine calls for the same work.
+ *
+ * Worth being precise about how much this was worth, because the first version
+ * of this comment claimed the note CAUSED those counts and that is not
+ * supported. The transcripts show the model batching anyway — up to nine
+ * consecutive `read` calls inside a single turn. So the note was pushing the
+ * wrong way and was not obeyed literally. It is one defect, and removing it is
+ * right on its own terms; it is not the whole of the 43% of calls that are
+ * re-reads.
+ *
+ * The host does not limit a turn to one tool call. What limits it is eq. 1: the
+ * prompt is (P, Σₜ, Oₜ) and there is ONE Oₜ, so a turn that makes several calls
+ * keeps only the last result and the model must re-read the rest. That is not
+ * a guess — a turn that batched nine reads produced a model that said "the last
+ * observation re-read cfg8.ts" and then went and read cfg8 again, and the
+ * thirty-file run reached 103 reads for 29 files.
+ *
+ * So the note says the truth the model needs: one call per step, because the
+ * second one would be lost. An earlier version of this comment went the other
+ * way and told the model it could make as many calls as it liked. That was
+ * written before the single-observation consequence was understood, and it
+ * invited exactly the data loss the paper's own equation makes unavoidable.
+ */
+export const HOST_ACTION_NOTE = [
+    'The `action` field is a label, not a command: nothing executes it.',
+    'A step ends when you call a tool, so end each step with a real tool call —',
+    'or answer and stop. Emitting a state_patch on its own ends the run, however',
+    'correct the patch was. One tool call per step: this prompt shows you only the',
+    'LAST result, so a second call in the same step would leave you unable to',
+    'remember the first, and you would have to read it again.',
+].join(' ');
+/**
+ * Replace the model-facing context with exactly (P, Σₜ, Oₜ).
+ *
+ * Two edits, and both are required:
+ *
+ * - the A.4 prompt becomes the ONLY message, so no reasoning, action or tool
+ *   output from earlier steps survives into this dispatch;
+ * - the host's own system prompt is KEPT. An earlier version replaced it
+ *   wholesale, on the reasoning that P is the entire instruction surface and
+ *   the default prompt tells the model to prefer parallel tool calls, which
+ *   is incoherent with a single-step state machine. Measured: that reasoning
+ *   was wrong about a consequence, because the default system prompt is also
+ *   what carries the host's tool-use discipline. Replacing it with one
+ *   sentence produced a model that emitted a correct patch and then never
+ *   called a tool again — the run ended after the first file, three times
+ *   running, on two models. The "parallel calls" worry is real but costs
+ *   less than a dead loop; the trade is measured, not assumed.
+ *
+ * `systemPrefix` is where a host that cannot be the runtime says so; see
+ * {@link HOST_ACTION_NOTE}. It is optional because a deployment where
+ * something else does own the executor has no such gap to describe.
+ *
+ * The array is mutated in place: the host keeps the original reference.
+ */
+export function applyPaperContext(event, built, systemPrefix) {
+    const message = {
+        id: PAPER_MESSAGE_ID,
+        role: 'user',
+        content: [{ type: 'text', text: built.prompt }],
+        metadata: {},
+    };
+    event.messages.length = 0;
+    event.messages.push(message);
+    if (event.system !== undefined && systemPrefix !== undefined) {
+        event.system.push({ type: 'text', text: systemPrefix });
+    }
+    return message;
+}
+//# sourceMappingURL=paper-mode.js.map

package/dist/paper-mode.js.map

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

package/dist/plugin.d.ts

@@ -27,14 +27,33 @@
  *
  * ── The v2 design ────────────────────────────────────────────────────────
  *
+ * Two modes, each enforced by a test. They are different contracts with the
+ * model, not variants of one behaviour:
+ *
+ * - **`notes` (default).** Contribute one additive, bounded fragment to
+ *   `event.system` and leave the transcript alone. The agent sees its own
+ *   history the way the host intends, and the saved notes ride alongside it.
+ *   This is the mode that fixed the v1 failure, and it is the default for
+ *   exactly that reason.
+ * - **`paper` (opt-in).** Replace the model-facing context with
+ *   Aₜ = (P, Σₜ, Oₜ) — the paper's Appendix A.4 prompt, byte-verbatim — and
+ *   apply the `state_patch` the model emits in response. This is the paper's
+ *   specification, and it is a real behavioural change: the model stops
+ *   seeing its transcript, because §3.2 discards the reasoning trace by
+ *   construction. Select it with `mode: "paper"` in the project's
+ *   `skillstate.json` or `SKILLSTATE_MODE=paper`; see `mode.ts`.
+ *
+ * The default is `notes` and must stay that way: a default that discards the
+ * user's task is the v1 bug under a new name.
+ *
  * Three rules, each enforced by a test:
  *
- * - **Never mutate `event.messages`.** The plugin contributes one additive
- *   fragment to `event.system` and leaves the transcript alone. See
- *   `tests/opencode/context-integrity.test.ts`.
- * - **Never inject behavioural instructions.** The system fragment
- *   describes what the notes are and when to use them; it contains no
- *   "you must", no "always", and no output format. See
+ * - **Notes mode never mutates `event.messages`.** The plugin contributes
+ *   one additive fragment to `event.system` and leaves the transcript alone.
+ *   See `tests/opencode/context-integrity.test.ts`.
+ * - **Never inject behavioural instructions in notes mode.** The system
+ *   fragment describes what the notes are and when to use them; it contains
+ *   no "you must", no "always", and no output format. See
  *   `system-hint.ts`.
  * - **Inert until used.** A project with no state file gets no system
  *   fragment at all and behaves exactly like vanilla OpenCode. No files are
@@ -66,17 +85,148 @@
 import { Plugin } from '@opencode/plugin';
 /** Stable plugin id — scopes plugin storage and identifies it in `/api/plugin`. */
 export declare const PLUGIN_ID = "skillstate";
+/**
+ * The action carried forward when a turn produced no usable patch.
+ *
+ * NOT `__invalid_patch__`, though the paper names that sentinel at §5.1 line
+ * 9. It is a return value there — what the step function hands back to signal
+ * that Σ is unchanged — and forwarding it into the prompt as the next action
+ * is meaningless to a model: it is a name, not a request. The retry instruction
+ * the model actually needs already rides in Oₜ through the feedback queue, so
+ * this only has to say "keep going", and the queue says why.
+ */
+export declare const CONTINUE_ACTION = "continue";
+/**
+ * Record every event type the plugin actually receives.
+ *
+ * @non-paper diagnostics, same file. The advance is triggered by one event
+ * type and one, and a trigger that never fires is indistinguishable from one
+ * that is wired wrong — so the arrival counts have to be visible. Cheap, and
+ * it would have saved guessing.
+ */
+export declare function recordEvent(path: string | undefined, type: string): void;
+/**
+ * Whether the host has just executed a tool for this request.
+ *
+ * A tool result in the transcript is the observable edge of "an action ran".
+ * There is no event that says so in a shape this plugin can trust — and an
+ * event the host does not wait for is what caused the read-after-write race
+ * fixed in `response-sink.ts`, so the transcript is the more reliable of the
+ * two here as well as the more available one.
+ */
+/** Tool-result parts in the newest tool message, counted. */
+export declare function countToolResults(messages: ReadonlyArray<{
+    role: string;
+    content: unknown;
+}>): number;
+/**
+ * Append what the host actually handed us to a file, for diagnosis.
+ *
+ * @non-paper diagnostics. Enabled by `SKILLSTATE_DEBUG_PROMPT=<path>`.
+ *
+ * This exists because of a bug that was invisible from the inside for a
+ * long time. The model would run a tool, get the answer, and never record
+ * it — which looks exactly like a model refusing to cooperate, and sent the
+ * search through prompt slots, model choice and spec wording. The cause was
+ * the SHAPE: OpenCode v2 delivers a tool result as
+ * `{ type: 'tool-result', result: { value } }`, so a reader that only knew
+ * `{ type: 'text', text }` made Oₜ permanently empty without ever throwing.
+ *
+ * The dump records the part types alongside the extracted text, so that
+ * class of failure is visible on sight: a `tool-result` in the list next to
+ * an empty `observation` says the reader, not the model, is at fault.
+ *
+ * Append-only so a session's turns accumulate in order, and every failure
+ * is swallowed — diagnostics must never break the agent loop.
+ */
+export declare function dumpPromptShape(path: string | undefined, messages: ReadonlyArray<{
+    role: string;
+    content: unknown;
+}>, state?: Record<string, unknown>): void;
+/**
+ * One line per turn of the anti-drift diagnostic.
+ *
+ * The drift notice has a claim attached to it — "the model drifts, the notice
+ * brings it back" — and neither half can be checked from inside the process.
+ * A notice in a prompt is not an observation of a model: the fragment may be
+ * built correctly and the model may ignore it, and the two look identical
+ * from the code's side. Worse, both look identical from the *outside* too,
+ * which is what made the earlier `tool-result` bug so expensive to find.
+ *
+ * So each line carries the evidence that distinguishes them:
+ *
+ * - `notice` — was the drift sentence in the fragment that went out this turn;
+ * - `writes` — how many times the state file had changed when it went out, so
+ *   a notice that repeats forever is visible as a flat counter;
+ * - `fragments` — how many turns had passed without a change.
+ *
+ * That is enough to say "the notice fired and the state moved afterwards" or
+ * "the notice fired and nothing happened", which is the only claim worth
+ * making about it.
+ *
+ * @non-paper diagnostics. Enabled by `SKILLSTATE_DEBUG_DRIFT=<path>`.
+ * Separate from {@link dumpPromptShape} because it answers a different
+ * question: that one asks what the host sent, this one asks what the model
+ * did about what we sent.
+ */
+export declare function dumpDrift(path: string | undefined, record: {
+    readonly scope: string;
+    readonly turns: number;
+    readonly notice: boolean;
+    readonly writes: number;
+}): void;
+/**
+ * One line per step, for the run that answered correctly while its state
+ * under-reported the work. Enabled by `SKILLSTATE_DEBUG_STEPS=<path>`.
+ *
+ * The 30-file measurement produced the most confusing result in this project's
+ * history: paper mode answered correctly, its state ended 25/30, and the
+ * control's ended 30/30 complete. Twenty-five patches were emitted and all
+ * twenty-five landed, so no patch was lost — the model read every file and
+ * declined to patch the last five, while the loop kept driving it. From the
+ * outside that is indistinguishable from the loop stopping, from the model
+ * silently abandoning the protocol, and from the ceiling being hit.
+ *
+ * So this prints the thing that tells those apart: at every step, whether a
+ * patch was applied, what the state looked like, and whether the driver asked
+ * again. Every previous wrong guess in this file came from reasoning about the
+ * loop instead of watching it.
+ */
+export declare function dumpStepTrace(path: string | undefined, record: {
+    readonly sessionID: string;
+    readonly step: number;
+    readonly attempt: number;
+    readonly applied: boolean;
+    readonly done: number;
+    readonly total: number | null;
+    readonly drove: boolean;
+    readonly note: string;
+}): void;
+/**
+ * The step ceiling, or `undefined` to keep the default.
+ *
+ * A malformed value is ignored rather than thrown on or silently clamped: a
+ * typo in an environment variable should leave the ceiling where the code says
+ * it is, not quietly become some other number that then gets measured.
+ */
+export declare function maxStepsFromEnv(): number | undefined;
 /**
  * The plugin definition.
  *
- * `setup` wires three things and returns a cleanup function:
+ * `setup` wires the session registry, the project state store, the native
+ * tools, the mode resolver and the one `context` hook, then returns a cleanup
+ * function.
  *
  * - a {@link SessionRegistry}, fed by the server event stream, so a
  *   sub-agent session is recognised and given its own state file;
  * - a {@link ProjectStateStore} rooted at the plugin's own project
  *   location, so two checkouts served by one OpenCode server never share
  *   state;
- * - native tools plus a single additive `context` hook.
+ * - a {@link SpecResolver} for paper mode's P, so a project that ships its
+ *   own `skill-spec.json` gets its own procedure;
+ * - a {@link PaperStateSink}, in paper mode only, which applies the
+ *   `state_patch` the model emits;
+ * - native tools plus a single `context` hook whose body depends on the mode.
  *
  * The event subscription is the only resource the plugin owns, so the
  * returned cleanup aborts it. Hook and tool registrations are disposed by

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAO1C,mFAAmF;AACnF,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,eAyD3B,CAAC;eAEY,gBAAgB"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAkB1C,mFAAmF;AACnF,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,aAAa,CAAC;AAqJ1C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOxE;AAED;;;;;;;;GAQG;AACH,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,MAAM,CAUpG;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,EAC3D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CA4BN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5G,IAAI,CAON;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,EAAE;IACN,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACA,IAAI,CAON;AAED;;;;;;GAMG;AAEH,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAQpD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,gBAAgB,eAgf3B,CAAC;eAEY,gBAAgB"}