@skillstate/opencode 2.2.2 → 3.0.1

package/dist/plugin.d.ts

@@ -1,95 +1,237 @@
-import { mergePatch, resolveHostStateForCwd } from '@skillstate/core';
-import type { OpenCodeMessage, SkillStatePlugin } from './plugin-types.js';
-export * from './plugin-types.js';
 /**
- * Resolve the per-project state file for a session working directory
- * (`cwd` of the current opencode session) — the core single source of
- * truth (`resolveHostStateForCwd`): `<cwd>/.skillstate/skillstate.json`,
- * or the global bucket `<home>/.skillstate/global/skillstate.json` when
- * cwd equals home. A non-empty `agentId` scopes the file under
- * `<bucket>/agents/<agentId>/skillstate.json`. Pure path arithmetic via
- * `path.resolve`, no filesystem access.
+ * `@skillstate/opencode` — the OpenCode **v2** plugin.
+ *
+ * ── What this replaces ───────────────────────────────────────────────────
+ *
+ * The v1 integration rewrote the conversation on every model request. It
+ * kept the system messages and the last three non-system messages, dropped
+ * everything else from `output.messages`, and appended a synthetic
+ * `role: "user"` message containing the raw state JSON. The reported
+ * failure was that the agent stopped doing the user's task and started
+ * emitting state JSON instead.
+ *
+ * Both halves of that were destructive, and neither was a model quirk:
+ *
+ * 1. The injected message landed LAST, so for the model it was the current
+ *    instruction — it displaced the user's actual request.
+ * 2. `slice(-3)` deleted the task statement, the tool results and the
+ *    errors the agent had just been handed. It was reasoning about work it
+ *    could no longer see.
+ *
+ * The MCP server made it worse: `spec.get` returned a procedural spec whose
+ * default was `INTERCODE_CTF_SPEC`, whose instructions read "You are an
+ * autonomous CTF agent ... hidden flag somewhere on its filesystem". A
+ * model told to look for a flag looks for a flag. (Fixed: the default is now
+ * the neutral `GENERIC_PROCEDURE_SPEC`, and its instructions describe the
+ * storage format instead of prescribing a way of working.)
+ *
+ * ── 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:
+ *
+ * - **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
+ *   created by loading the plugin.
+ *
+ * ── Native tools AND the MCP server, on purpose ──────────────────────────
+ *
+ * This package does not replace `@skillstate/mcp`; it sits beside it.
+ *
+ * - The native tools ({@link registerTools}) are the fast path inside
+ *   opencode: a typed schema, structured output, no JSON-RPC round-trip and
+ *   no untyped text result.
+ * - The MCP server is the portable path. It is what every other
+ *   MCP-capable host reads, and the only way to reach this state from a
+ *   client that is not opencode.
+ *
+ * Both address the same `<project>/.skillstate/skillstate.json`, so they
+ * cannot disagree about what is saved. `skillstate init` registers both.
+ *
+ * The reason v1 needed the MCP server is gone: an opencode v1 plugin could
+ * not contribute first-class tools at all.
+ *
+ * Load it from `opencode.json(c)`:
+ *
+ * ```json
+ * { "plugins": ["@skillstate/opencode"] }
+ * ```
  */
-export { resolveHostStateForCwd as resolveStatePathForCwd };
-export { mergePatch };
-/** Options for {@link createSkillStatePlugin}. */
-export interface SkillStatePluginOptions {
-    /** Non-system messages kept in the prompt (default 3). */
-    maxHistoryMessages?: number;
-}
+import { Plugin } from '@opencode/plugin';
+/** Stable plugin id — scopes plugin storage and identifies it in `/api/plugin`. */
+export declare const PLUGIN_ID = "skillstate";
 /**
- * Read the state file. Missing or corrupt files yield `{}` (best-effort).
- * The on-disk envelope is `{ version: 1, state }` (migrations-compatible);
- * a bare object is tolerated and treated as the state itself. Thin fs
- * adapter over the core hook-runtime {@link readStateEnvelope}.
+ * 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 function readSkillState(statePath: string): Record<string, unknown>;
+export declare const CONTINUE_ACTION = "continue";
 /**
- * Persist the state file (best-effort: read-only environments are ignored).
- * Creates the parent directory when missing (the per-project resolver may
- * target a fresh `<cwd>/.skillstate/agents/<id>/`). Writes the
- * `{ version: 1, state }` envelope so `migrate()`/runtime resume read the
- * same file — via the core hook-runtime {@link saveStateEnvelope} — under
- * the cross-process sync lock {@link lockStateWrite} (2-3 parallel agent
- * processes never interleave state writes).
+ * 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 saveSkillState(statePath: string, state: Record<string, unknown>): void;
+export declare function recordEvent(path: string | undefined, type: string): void;
 /**
- * Atomic READ-MERGE-WRITE of one `state_patch` (paper ⊕: null deletes):
- * the whole critical section runs inside {@link lockStateWrite}, so two
- * concurrent writers apply BOTH patches instead of racing between the
- * read and the write. Best-effort: lock contention or unwritable state
- * files are swallowed — the tool flow never breaks.
+ * 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.
  */
-export declare function mergeSkillState(statePath: string, patch: Record<string, unknown>): Record<string, unknown>;
+/** Tool-result parts in the newest tool message, counted. */
+export declare function countToolResults(messages: ReadonlyArray<{
+    role: string;
+    content: unknown;
+}>): number;
 /**
- * Extract the `state_patch` object from an LLM response's fenced ```json
- * block; `null` when there is no block, it is malformed, or it carries no
- * object-shaped `state_patch`. Thin adapter over the core hook-runtime
- * {@link findFencedPatch} (the invalid/truncated outcomes collapse to
- * `null`, preserving the legacy boolean contract).
+ * 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 extractPatch(response: string): Record<string, unknown> | null;
+export declare function dumpPromptShape(path: string | undefined, messages: ReadonlyArray<{
+    role: string;
+    content: unknown;
+}>, state?: Record<string, unknown>): void;
 /**
- * Agent id for an opencode hook call.
- *
- * MAIN SESSION → `''` (the ROOT state file `<cwd>/.skillstate/skillstate.json`
- * — the SAME file the skillstate MCP tools and the CLI address, so the
- * injected state and `state.patch` can never disagree). A session
- * registered as a SUB-AGENT via the host event bus
- * (`session.created`/`updated` carry `info.parentID`) resolves to
- * `<parentPrefix>-<sessionPrefix>` — an isolated copy under `agents/` that
- * never last-writer-wins the main state; the main agent folds it back with
- * `agent.merge`. No session id at all → `''` (root: a single context).
+ * 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 pluginAgentId(input: {
-    sessionID?: unknown;
-}, messages?: OpenCodeMessage[]): string;
+export declare function dumpDrift(path: string | undefined, record: {
+    readonly scope: string;
+    readonly turns: number;
+    readonly notice: boolean;
+    readonly writes: number;
+}): void;
 /**
- * Widen an agent id for a registered sub-agent session:
- * `<parentPrefix>-<sessionPrefix>`. Plain sessions resolve to `''` (the
- * main/root scope — NOT their own agents/ copy).
+ * 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 scopedAgentId(agentId: string): string;
+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;
 /**
- * Record a session→parent edge from the host event stream. `sessionId`
- * with a non-empty `parentID` registers that session as a sub-agent of
- * `parentID`; an empty `parentID` (the main session being updated after
- * the fact) clears a stale registration. Exposed for tests.
+ * 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 registerSessionParent(sessionId: unknown, parentId: unknown): void;
-/** Test-only: forget every registered session→parent edge. */
-export declare function resetSessionParents(): void;
+export declare function maxStepsFromEnv(): number | undefined;
 /**
- * Build the OpenCode plugin function with the same behavior for every host
- * entry point (thin generated loaders, direct imports).
- *
- * State resolution is ALWAYS per-project: the state file path is computed
- * from the session cwd on EVERY hook call via
- * `resolveStatePathForCwd(process.cwd(), os.homedir(), agentId)` — each
- * project gets its own `<cwd>/.skillstate/`, each session (sub-agent) its
- * isolated `agents/<session>/` copy, and a session launched from `$HOME`
- * uses the global bucket.
+ * The plugin definition.
+ *
+ * `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;
+ * - 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
+ * OpenCode when the plugin unloads.
  */
-export declare function createSkillStatePlugin(options?: SkillStatePluginOptions): SkillStatePlugin;
+export declare const SkillStatePlugin: Plugin.Plugin;
+export default SkillStatePlugin;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAmCA,OAAO,EAGL,UAAU,EAGV,sBAAsB,EAEvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,eAAe,EAEf,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B,cAAc,mBAAmB,CAAC;AAElC;;;;;;;;GAQG;AACH,OAAO,EAAE,sBAAsB,IAAI,sBAAsB,EAAE,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAG7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EAC9B,QAAQ,CAAC,EAAE,eAAe,EAAE,GAC3B,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAUjF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAwG9F"}
+{"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"}