@skillstate/opencode 2.0.2 → 2.0.4

package/README.md

@@ -6,8 +6,8 @@
 
 [![npm version](https://img.shields.io/npm/v/@skillstate/opencode)](https://www.npmjs.com/package/@skillstate/opencode)
 [![node](https://img.shields.io/node/v/@skillstate/opencode)](https://www.npmjs.com/package/@skillstate/opencode)
-[![Tests](https://img.shields.io/badge/tests-755%20passing-brightgreen)](https://github.com/vitalykuzyaev/skillstate)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
+[![Tests](https://img.shields.io/badge/tests-755%20passing-brightgreen)](https://github.com/vitkuz573/skillstate)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/vitkuz573/skillstate/blob/main/LICENSE)
 
 </div>
 
@@ -60,18 +60,85 @@ const saved = await adapter.savePluginCode(
 );
 ```
 
+## Install into OpenCode (host)
+
+Tested end-to-end against OpenCode ≥ 1.17 (`@opencode-ai/plugin` 1.15.x
+hook contracts). Four steps:
+
+**1. Generate the plugin file** (one-off, or wire into a build script):
+
+```ts
+// scripts/gen-plugin.mjs  (run with: node scripts/gen-plugin.mjs)
+import { OpenCodeAdapter } from '@skillstate/opencode';
+import { writeFileSync } from 'node:fs';
+
+const adapter = new OpenCodeAdapter();
+const statePath = '/abs/path/to/.skillstate.json';
+const code = adapter.generatePluginCode(statePath, { maxHistoryMessages: 3 });
+writeFileSync('/abs/path/to/skillstate.plugin.ts', code);
+```
+
+Put the generated `skillstate.plugin.ts` anywhere stable (absolute path is
+safest), e.g. `<project>/.opencode-runtime/skillstate.plugin.ts`.
+
+**2. Create the initial state file** (`statePath` from step 1), matching your
+spec schema, e.g. for `INTERCODE_CTF_SPEC`:
+
+```json
+{
+  "discovered_flags": [],
+  "tested_hypotheses": [],
+  "active_files": [],
+  "working_dir": "/abs/work/dir",
+  "cmd_summary": "initialized"
+}
+```
+
+**3. Register the plugin in `opencode.jsonc`** — add a `file://` entry to the
+`plugin` array (local paths are resolved by OpenCode and imported directly;
+TypeScript is supported because plugins load under Bun):
+
+```jsonc
+{
+  "plugin": [
+    "@ai-sdk/anthropic",
+    "file:///abs/path/to/skillstate.plugin.ts"
+  ]
+}
+```
+
+**4. Install the SKILL.md** — write `adapter.generateSkillMd(spec, statePath)`
+to `~/.config/opencode/skills/skillstate/SKILL.md` (global) or
+`.opencode/skills/skillstate/SKILL.md` (project). Keep the frontmatter fields
+`name` (must match the folder name) and a one-line `description`; the
+generated frontmatter may need a manual trim to those two fields.
+
+Verify with `opencode debug config` (plugin entry shows under `plugin`) and
+`opencode debug skill` (your skill is listed). Hook notes for OpenCode ≥ 1.17:
+`messages.transform` receives `{ info: Message, parts: Part[] }` entries and
+must mutate `output.messages` **in place**; the plugin injects state as a
+synthetic `{ info, parts }` message.
+
 ## API / Exports
 
-Root path `@skillstate/opencode` exports one thing: `OpenCodeAdapter`.
+Root path `@skillstate/opencode` exports the adapter and the static plugin:
 
 - `new OpenCodeAdapter()` — implements `PlatformAdapter` (`name = 'opencode'`).
 - `generateSkillMd(spec, statePath?): string` — a `SKILL.md` body with
   frontmatter and a state-based process description.
-- `generatePluginCode(statePath, options?): string` — an OpenCode plugin
-  (`options.maxHistoryMessages`, default 3). Hooks:
+- `generatePluginCode(statePath, options?): string` — a thin plugin loader by
+  default (`import { createSkillStatePlugin } from '@skillstate/opencode'` with
+  the state path baked in; `options.maxHistoryMessages`, default 3).
+  `options.standalone: true` inlines the full self-contained plugin — escape
+  hatch for environments without npm resolution of this package. Hooks:
   `experimental.chat.messages.transform` (real history trimming),
   `experimental.session.compacting` (inject state into compaction context),
   `tool.execute.after` (persist `state_patch` to disk).
+- `createSkillStatePlugin({ statePath, maxHistoryMessages? })` — the static
+  plugin factory (single source of truth for the hook logic); re-exported from
+  `@skillstate/opencode/plugin` as well.
+- `readSkillState` / `saveSkillState` / `mergePatch` / `extractPatch` — the
+  plugin's state helpers, shared by the static plugin.
 - `savePluginCode(target, statePath, options?): Promise<string>` — writes the
   plugin atomically and returns the destination.
 - `injectState(state, spec): string` / `formatPrompt(state, observation, spec): string`.
@@ -86,8 +153,12 @@ Both `generatePluginCode`/`savePluginCode` accept a raw path (legacy) or a
   `experimental.chat.messages.transform`, so the plugin drops old messages
   instead of just hiding them — only the last N non-system messages plus an
   injected state message reach the LLM.
-- The generated plugin is a self-contained ESM/TS module; it reads and writes
-  the state file directly and applies the paper ⊕ null-deletion merge.
+- The default generated plugin is a **thin loader**: it imports
+  `createSkillStatePlugin` from `@skillstate/opencode` (one source of truth)
+  and bakes in the state path. The `{ standalone: true }` template is a
+  self-contained ESM/TS escape hatch for environments without npm resolution;
+  hook logic lives only in `src/plugin.ts` — regenerate rather than editing
+  generated files.
 - Depends on [`@skillstate/core`](../core) for `PromptTransformer`,
   `atomicWriteFile`, and `resolveStatePath`.
 

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './opencode-adapter.js';
+export * from './plugin.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 // @skillstate/opencode — OpenCode platform adapter.
 export * from './opencode-adapter.js';
+export * from './plugin.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC"}

package/dist/opencode-adapter.d.ts

@@ -14,6 +14,16 @@
  */
 import type { SkillState, StatePatch, ProceduralSpec, Observation, PlatformAdapter } from '@skillstate/core';
 import type { StatePathRef } from '@skillstate/core';
+/** Options for {@link OpenCodeAdapter.generatePluginCode}. */
+export interface GeneratePluginOptions {
+    /** Non-system messages kept by the plugin (default 3). */
+    maxHistoryMessages?: number;
+    /**
+     * Inline the full plugin instead of the thin loader — escape hatch for
+     * environments without npm resolution of `@skillstate/opencode`.
+     */
+    standalone?: boolean;
+}
 /**
  * OpenCode platform adapter (@non-paper; see module doc).
  */
@@ -51,27 +61,30 @@ export declare class OpenCodeAdapter implements PlatformAdapter {
      */
     generateSkillMd(spec: ProceduralSpec, statePath?: string): string;
     /**
-     * Generate an OpenCode plugin with real O(1) prompt economy.
+     * Generate an OpenCode plugin file.
+     *
+     * Default (thin) mode: a loader that imports the STATIC plugin
+     * (`createSkillStatePlugin` from `@skillstate/opencode`) — the single
+     * source of truth for hook logic. `statePath`/`maxHistoryMessages` are
+     * baked into the loader call.
+     *
+     * `{ standalone: true }` inlines the full plugin (self-contained template,
+     * escape hatch for environments without npm resolution of
+     * `@skillstate/opencode`).
      *
-     * Hooks:
-     * - `experimental.chat.messages.transform`: trims history to the last
-     *   `maxHistoryMessages` non-system messages, injects a synthetic state
-     *   message — real O(1) prompt footprint.
-     * - `experimental.session.compacting`: injects state into the compaction
-     *   context so the summary preserves it.
-     * - `tool.execute.after`: persists state updates from LLM responses.
+     * Hooks (see `src/plugin.ts`): `experimental.chat.messages.transform`
+     * (real O(1) history trimming, `{ info, parts }` entries, in-place
+     * mutation), `experimental.session.compacting` (state into compaction
+     * context), `tool.execute.after` (persist `state_patch` from
+     * `output.output`).
      */
-    generatePluginCode(statePath: string, options?: {
-        maxHistoryMessages?: number;
-    }): string;
+    generatePluginCode(statePath: string, options?: GeneratePluginOptions): string;
     /**
      * @non-paper additive overload: accept a `{ root, name }` ref confined
      * via `resolveStatePath` — `..` escapes throw instead of embedding an
      * unsafe path into the generated plugin.
      */
-    generatePluginCode(stateRef: StatePathRef, options?: {
-        maxHistoryMessages?: number;
-    }): string;
+    generatePluginCode(stateRef: StatePathRef, options?: GeneratePluginOptions): string;
     /**
      * @non-paper additive helper: generate the plugin and persist it via
      * `atomicWriteFile` (tmp + fsync + rename). Both the destination and the
@@ -79,9 +92,7 @@ export declare class OpenCodeAdapter implements PlatformAdapter {
      * `{ root, name }` refs confined by `resolveStatePath`. Returns the
      * absolute destination path.
      */
-    savePluginCode(target: string | StatePathRef, statePath: string | StatePathRef, options?: {
-        maxHistoryMessages?: number;
-    }): Promise<string>;
+    savePluginCode(target: string | StatePathRef, statePath: string | StatePathRef, options?: GeneratePluginOptions): Promise<string>;
     /**
      * Describe the schema fields for inclusion in prompts.
      */

package/dist/opencode-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-adapter.d.ts","sourceRoot":"","sources":["../src/opencode-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,WAAW,EACX,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;GAEG;AACH,qBAAa,eAAgB,YAAW,eAAe;IACrD,QAAQ,CAAC,IAAI,cAAc;IAE3B,OAAO,CAAC,WAAW,CAAmD;IAEtE;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAsB3D;IAED;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEhD;IAED;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7C;IAED;;;;;OAKG;IACH,YAAY,CACV,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,cAAc,GACnB,MAAM,CAER;IAED;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CA0ChE;IAED;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IACzF;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IAoI9F;;;;;;OAMG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,SAAS,EAAE,MAAM,GAAG,YAAY,EAChC,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,GACxC,OAAO,CAAC,MAAM,CAAC,CAYjB;IAMD;;OAEG;IACH,OAAO,CAAC,cAAc;CASvB"}
+{"version":3,"file":"opencode-adapter.d.ts","sourceRoot":"","sources":["../src/opencode-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,WAAW,EACX,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,eAAgB,YAAW,eAAe;IACrD,QAAQ,CAAC,IAAI,cAAc;IAE3B,OAAO,CAAC,WAAW,CAAmD;IAEtE;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAsB3D;IAED;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEhD;IAED;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7C;IAED;;;;;OAKG;IACH,YAAY,CACV,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,cAAc,GACnB,MAAM,CAER;IAED;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CA0ChE;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IAC/E;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IA4BpF;;;;;;OAMG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,SAAS,EAAE,MAAM,GAAG,YAAY,EAChC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAYjB;IAMD;;OAEG;IACH,OAAO,CAAC,cAAc;CASvB"}

package/dist/opencode-adapter.js

@@ -108,9 +108,63 @@ plugin; only the current state and the latest observation matter.
         const statePath = typeof statePathOrRef === 'string'
             ? statePathOrRef
             : resolveStatePath(statePathOrRef.root, statePathOrRef.name);
-        const sp = JSON.stringify(statePath);
         const maxHistory = options?.maxHistoryMessages ?? 3;
-        return `// OpenCode plugin generated by skillstate.
+        if (options?.standalone) {
+            return standalonePluginCode(statePath, maxHistory);
+        }
+        const sp = JSON.stringify(statePath);
+        return `// OpenCode plugin (thin loader) generated by skillstate.
+// Hook logic lives in the static plugin — the single source of truth —
+// shipped in the @skillstate/opencode package.
+import { createSkillStatePlugin } from '@skillstate/opencode';
+
+export default createSkillStatePlugin({
+  statePath: ${sp},
+  maxHistoryMessages: ${maxHistory},
+});
+`;
+    }
+    /**
+     * @non-paper additive helper: generate the plugin and persist it via
+     * `atomicWriteFile` (tmp + fsync + rename). Both the destination and the
+     * embedded state path accept raw strings (legacy behavior) or
+     * `{ root, name }` refs confined by `resolveStatePath`. Returns the
+     * absolute destination path.
+     */
+    async savePluginCode(target, statePath, options) {
+        const dest = typeof target === 'string'
+            ? target
+            : resolveStatePath(target.root, target.name);
+        const resolvedState = typeof statePath === 'string'
+            ? statePath
+            : resolveStatePath(statePath.root, statePath.name);
+        const plugin = this.generatePluginCode(resolvedState, options);
+        await atomicWriteFile(dest, plugin);
+        return dest;
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internal helpers                                                   */
+    /* ------------------------------------------------------------------ */
+    /**
+     * 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}`;
+    }
+}
+/**
+ * Standalone (escape-hatch) plugin template — a self-contained inline copy of
+ * `src/plugin.ts` for environments without npm resolution of
+ * `@skillstate/opencode`. Escape hatch only: `src/plugin.ts` remains the
+ * single source of truth; regenerate rather than editing generated files.
+ */
+function standalonePluginCode(statePath, maxHistory) {
+    const sp = JSON.stringify(statePath);
+    return `// OpenCode plugin (standalone escape hatch) generated by skillstate.
+// Self-contained copy of createSkillStatePlugin from @skillstate/opencode.
 // Real O(1) prompt economy via experimental.chat.messages.transform:
 // trims history to last ${maxHistory} non-system messages + injected state.
 
@@ -139,20 +193,20 @@ function saveSkillState(state: Record<string, unknown>): void {
   }
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function mergePatch(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown> {
   const result = { ...base };
   for (const key of Object.keys(patch)) {
-    if (patch[key] === null) {
+    const value = patch[key];
+    if (value === null) {
       delete result[key];
-    } else if (
-      typeof patch[key] === "object" && patch[key] !== null &&
-      !Array.isArray(patch[key]) &&
-      typeof result[key] === "object" && result[key] !== null &&
-      !Array.isArray(result[key])
-    ) {
-      result[key] = mergePatch(result[key] as Record<string, unknown>, patch[key] as Record<string, unknown>);
+    } else if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = mergePatch(result[key] as Record<string, unknown>, value);
     } else {
-      result[key] = patch[key];
+      result[key] = value;
     }
   }
   return result;
@@ -162,9 +216,9 @@ function extractPatch(response: string): Record<string, unknown> | null {
   const match = response.match(/\`\`\`json\\s*\\n?([\\s\\S]*?)\\n?\\s*\`\`\`/);
   if (!match) return null;
   try {
-    const parsed = JSON.parse(match[1]);
-    if (parsed.state_patch && typeof parsed.state_patch === "object" && !Array.isArray(parsed.state_patch)) {
-      return parsed.state_patch;
+    const parsed: unknown = JSON.parse(match[1]);
+    if (isPlainObject(parsed) && isPlainObject(parsed["state_patch"])) {
+      return parsed["state_patch"];
     }
   } catch {
     // Malformed JSON — ignore.
@@ -172,92 +226,76 @@ function extractPatch(response: string): Record<string, unknown> | null {
   return null;
 }
 
-export const SkillStatePlugin: Plugin = async ({ project, client, $ }) => {
+const SkillStatePlugin: Plugin = async () => {
   return {
     // ── O(1) history trimming ──────────────────────────────────────────
     // Filters messages BEFORE each LLM call: keeps all system messages
     // plus the last ${maxHistory} non-system messages, then injects a
-    // synthetic user message with the current state. This is real O(1):
-    // old messages are DROPPED from the prompt, not just hidden.
-    "experimental.chat.messages.transform": async (input, output) => {
+    // synthetic state element. Old messages are DROPPED from the prompt,
+    // not just hidden.
+    "experimental.chat.messages.transform": async (_input, output) => {
       const state = readSkillState();
-      const messages = output.messages ?? [];
-      const systemMessages = messages.filter((m) => m.role === "system");
-      const nonSystem = messages.filter((m) => m.role !== "system");
-      const trimmed = nonSystem.slice(-MAX_HISTORY);
+      const messages = output.messages;
+      const systemMessages = messages.filter((m) => m.info.role === "system");
+      const trimmed = messages
+        .filter((m) => m.info.role !== "system")
+        .slice(-MAX_HISTORY);
 
       const stateMessage = {
-        role: "user",
-        content: "Current skill state (JSON): " + JSON.stringify(state),
+        info: {
+          id: "skillstate-state-inject",
+          sessionID: "skillstate",
+          role: "user",
+          time: { created: 0 },
+          agent: "skillstate",
+          model: { providerID: "skillstate", modelID: "skillstate" },
+        },
+        parts: [
+          {
+            id: "skillstate-state-inject-text",
+            sessionID: "skillstate",
+            messageID: "skillstate-state-inject",
+            type: "text",
+            synthetic: true,
+            text: "Current skill state (JSON): " + JSON.stringify(state),
+          },
+        ],
       };
 
-      output.messages = [...systemMessages, ...trimmed, stateMessage];
-      return output;
+      // The pipeline holds the original array reference — mutate in place.
+      const kept = [...systemMessages, ...trimmed, stateMessage];
+      messages.length = 0;
+      messages.push(...kept);
     },
 
     // ── Compaction context injection ───────────────────────────────────
     // Before compaction, inject the current state into the context so the
     // compaction summary preserves state even after history is compressed.
-    "experimental.session.compacting": async (input, output) => {
+    "experimental.session.compacting": async (_input, output) => {
       const state = readSkillState();
       const stateContext = "Skillstate: " + JSON.stringify(state);
       if (!Array.isArray(output.context)) {
         output.context = [];
       }
       output.context.push(stateContext);
-      return output;
     },
 
     // ── State persistence from LLM responses ───────────────────────────
-    // After tool execution, extract state_patch from the assistant's last
-    // response, merge it, and save to disk.
-    "tool.execute.after": async (input, output) => {
-      const response = output?.result ?? "";
+    // After tool execution, extract state_patch from the tool response
+    // (output.output), merge it, and save to disk.
+    "tool.execute.after": async (_input, output) => {
+      const response = output.output ?? "";
       if (typeof response === "string") {
         const patch = extractPatch(response);
         if (patch) {
-          const current = readSkillState();
-          const merged = mergePatch(current, patch);
-          saveSkillState(merged);
+          saveSkillState(STATE_PATH, mergePatch(readSkillState(), patch));
         }
       }
-      return output;
     },
   };
 };
 
 export default SkillStatePlugin;
 `;
-    }
-    /**
-     * @non-paper additive helper: generate the plugin and persist it via
-     * `atomicWriteFile` (tmp + fsync + rename). Both the destination and the
-     * embedded state path accept raw strings (legacy behavior) or
-     * `{ root, name }` refs confined by `resolveStatePath`. Returns the
-     * absolute destination path.
-     */
-    async savePluginCode(target, statePath, options) {
-        const dest = typeof target === 'string'
-            ? target
-            : resolveStatePath(target.root, target.name);
-        const resolvedState = typeof statePath === 'string'
-            ? statePath
-            : resolveStatePath(statePath.root, statePath.name);
-        const plugin = this.generatePluginCode(resolvedState, options);
-        await atomicWriteFile(dest, plugin);
-        return dest;
-    }
-    /* ------------------------------------------------------------------ */
-    /*  Internal helpers                                                   */
-    /* ------------------------------------------------------------------ */
-    /**
-     * 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=opencode-adapter.js.map

package/dist/opencode-adapter.js.map

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

package/dist/plugin-types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal local types for OpenCode plugin hooks — the `@opencode-ai/plugin`
+ * shape, verified against opencode 1.17 (PluginInput/Hooks). Declared locally
+ * to keep `@skillstate/opencode` zero-dep; the host supplies the real types
+ * at runtime.
+ */
+/** Message roles seen by `experimental.chat.messages.transform`. */
+export type OpenCodeMessageRole = 'user' | 'assistant' | 'system';
+/**
+ * Message envelope: the transform pipeline hands each message as
+ * `{ info, parts }` — the role lives on `info.role`.
+ */
+export interface OpenCodeMessage {
+    info: {
+        role: OpenCodeMessageRole | string;
+        [key: string]: unknown;
+    };
+    parts: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+}
+/** Output payload of `experimental.chat.messages.transform`. */
+export interface MessagesTransformOutput {
+    /** Mutated IN PLACE — the pipeline keeps the original array reference. */
+    messages: OpenCodeMessage[];
+}
+/** Output payload of `experimental.session.compacting`. */
+export interface SessionCompactingOutput {
+    context: string[];
+    prompt?: string;
+}
+/** Output payload of `tool.execute.after`. */
+export interface ToolExecuteAfterOutput {
+    title?: string;
+    /** The tool's string response (state_patch extraction source). */
+    output: unknown;
+    metadata?: unknown;
+}
+/** OpenCode hooks used by the skillstate plugin. */
+export interface SkillStateHooks {
+    'experimental.chat.messages.transform'?: (input: Record<string, never>, output: MessagesTransformOutput) => Promise<void>;
+    'experimental.session.compacting'?: (input: {
+        sessionID: string;
+    }, output: SessionCompactingOutput) => Promise<void>;
+    'tool.execute.after'?: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+        args: unknown;
+    }, output: ToolExecuteAfterOutput) => Promise<void>;
+}
+/**
+ * OpenCode plugin: an async factory receiving the host input and returning
+ * the hooks object (`Plugin` from `@opencode-ai/plugin`).
+ */
+export type SkillStatePlugin = (input: {
+    project?: unknown;
+    client?: unknown;
+    $?: unknown;
+    [key: string]: unknown;
+}) => Promise<SkillStateHooks>;
+//# sourceMappingURL=plugin-types.d.ts.map

package/dist/plugin-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.d.ts","sourceRoot":"","sources":["../src/plugin-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACrE,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;CACvE;AAED,gEAAgE;AAChE,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,sCAAsC,CAAC,EAAE,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC5B,MAAM,EAAE,uBAAuB,KAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,iCAAiC,CAAC,EAAE,CAClC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EAC5B,MAAM,EAAE,uBAAuB,KAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,EACzE,MAAM,EAAE,sBAAsB,KAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,CAAC,EAAE,OAAO,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC"}

package/dist/plugin-types.js

@@ -0,0 +1,8 @@
+/**
+ * Minimal local types for OpenCode plugin hooks — the `@opencode-ai/plugin`
+ * shape, verified against opencode 1.17 (PluginInput/Hooks). Declared locally
+ * to keep `@skillstate/opencode` zero-dep; the host supplies the real types
+ * at runtime.
+ */
+export {};
+//# sourceMappingURL=plugin-types.js.map

package/dist/plugin-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.js","sourceRoot":"","sources":["../src/plugin-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/plugin.d.ts

@@ -0,0 +1,38 @@
+import type { SkillStatePlugin } from './plugin-types.js';
+export * from './plugin-types.js';
+/** Options for {@link createSkillStatePlugin}. */
+export interface SkillStatePluginOptions {
+    /** Absolute path of the persisted state file. */
+    statePath: string;
+    /** Non-system messages kept in the prompt (default 3). */
+    maxHistoryMessages?: number;
+}
+/**
+ * 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.
+ */
+export declare function readSkillState(statePath: string): Record<string, unknown>;
+/**
+ * Persist the state file (best-effort: read-only environments are ignored).
+ * Writes the `{ version: 1, state }` envelope so `migrate()`/runtime resume
+ * read the same file.
+ */
+export declare function saveSkillState(statePath: string, state: Record<string, unknown>): void;
+/**
+ * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
+ * recursively, everything else replaces.
+ */
+export declare function mergePatch(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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`.
+ */
+export declare function extractPatch(response: string): Record<string, unknown> | null;
+/**
+ * Build the OpenCode plugin function with the same behavior for every host
+ * entry point (thin generated loaders, direct imports).
+ */
+export declare function createSkillStatePlugin(options: SkillStatePluginOptions): SkillStatePlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B,cAAc,mBAAmB,CAAC;AAElC,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAOD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMtF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAY7E;AAKD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CA+EzF"}

package/dist/plugin.js

@@ -0,0 +1,179 @@
+/**
+ * Static OpenCode plugin — the SINGLE SOURCE OF TRUTH for the skillstate
+ * host integration. `OpenCodeAdapter.generatePluginCode` (thin mode, the
+ * default) emits a loader that imports `createSkillStatePlugin` from this
+ * module; the standalone template is only an escape hatch for environments
+ * without npm resolution of `@skillstate/opencode`.
+ *
+ * Hooks (opencode 1.17 contract, verified on host):
+ * - `experimental.chat.messages.transform` — entries are `{ info, parts }`
+ *   envelopes (role on `info.role`); the pipeline keeps the ORIGINAL array
+ *   reference, so trimming mutates in place; the state is injected as a
+ *   synthetic `{ info, parts }` element. Real O(1) prompt footprint.
+ * - `experimental.session.compacting` — pushes the state into
+ *   `output.context` so the compaction summary preserves it.
+ * - `tool.execute.after` — the tool response is `output.output`; a fenced
+ *   ```json `state_patch` block is merged (paper ⊕: null deletes) and saved.
+ */
+import * as fs from 'node:fs';
+export * from './plugin-types.js';
+/** True for plain (non-null, non-array) objects. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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.
+ */
+export function readSkillState(statePath) {
+    try {
+        if (fs.existsSync(statePath)) {
+            const parsed = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                'state' in parsed &&
+                typeof parsed['state'] === 'object' &&
+                parsed['state'] !== null) {
+                return parsed['state'];
+            }
+            if (typeof parsed === 'object' && parsed !== null) {
+                return parsed;
+            }
+        }
+    }
+    catch {
+        // Corrupt or unreadable state file — fall back to empty state.
+    }
+    return {};
+}
+/**
+ * Persist the state file (best-effort: read-only environments are ignored).
+ * Writes the `{ version: 1, state }` envelope so `migrate()`/runtime resume
+ * read the same file.
+ */
+export function saveSkillState(statePath, state) {
+    try {
+        fs.writeFileSync(statePath, `${JSON.stringify({ version: 1, state }, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort: read-only environments or permission issues.
+    }
+}
+/**
+ * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
+ * recursively, everything else replaces.
+ */
+export function mergePatch(base, patch) {
+    const result = { ...base };
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === null) {
+            delete result[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergePatch(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * 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`.
+ */
+export function extractPatch(response) {
+    const match = response.match(/```json\s*\n?([\s\S]*?)\n?\s*```/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (isPlainObject(parsed) && isPlainObject(parsed['state_patch'])) {
+            return parsed['state_patch'];
+        }
+    }
+    catch {
+        // Malformed JSON — ignore.
+    }
+    return null;
+}
+/** Synthetic message ids for the injected state carrier. */
+const STATE_MESSAGE_ID = 'skillstate-state-inject';
+/**
+ * Build the OpenCode plugin function with the same behavior for every host
+ * entry point (thin generated loaders, direct imports).
+ */
+export function createSkillStatePlugin(options) {
+    const statePath = options.statePath;
+    const maxHistory = options.maxHistoryMessages ?? 3;
+    return async () => {
+        return {
+            // ── O(1) history trimming ──────────────────────────────────────────
+            // Filters messages BEFORE each LLM call: keeps all system messages
+            // plus the last `maxHistory` non-system messages, then injects a
+            // synthetic state element. Old messages are DROPPED from the prompt,
+            // not just hidden.
+            'experimental.chat.messages.transform': async (_input, output) => {
+                const state = readSkillState(statePath);
+                const messages = output.messages;
+                const systemMessages = messages.filter((m) => m.info.role === 'system');
+                const trimmed = messages
+                    .filter((m) => m.info.role !== 'system')
+                    .slice(-maxHistory);
+                // Synthetic state carrier — a `{ info, parts }` envelope whose text
+                // part carries the current state JSON.
+                const stateMessage = {
+                    info: {
+                        id: STATE_MESSAGE_ID,
+                        sessionID: 'skillstate',
+                        role: 'user',
+                        time: { created: 0 },
+                        agent: 'skillstate',
+                        model: { providerID: 'skillstate', modelID: 'skillstate' },
+                    },
+                    parts: [
+                        {
+                            id: `${STATE_MESSAGE_ID}-text`,
+                            sessionID: 'skillstate',
+                            messageID: STATE_MESSAGE_ID,
+                            type: 'text',
+                            synthetic: true,
+                            text: `Current skill state (JSON): ${JSON.stringify(state)}`,
+                        },
+                    ],
+                };
+                // The pipeline holds the original array reference — mutate in place
+                // (reassigning `output.messages` would not reach the LLM call).
+                const kept = [...systemMessages, ...trimmed, stateMessage];
+                messages.length = 0;
+                messages.push(...kept);
+            },
+            // ── Compaction context injection ───────────────────────────────────
+            // Before compaction, inject the current state into the context so the
+            // compaction summary preserves state even after history is compressed.
+            'experimental.session.compacting': async (_input, output) => {
+                const state = readSkillState(statePath);
+                if (!Array.isArray(output.context)) {
+                    output.context = [];
+                }
+                output.context.push(`Skillstate: ${JSON.stringify(state)}`);
+            },
+            // ── State persistence from LLM responses ───────────────────────────
+            // After tool execution, extract state_patch from the tool response
+            // (output.output), merge it, and save to disk.
+            'tool.execute.after': async (_input, output) => {
+                const response = output.output ?? '';
+                if (typeof response !== 'string')
+                    return;
+                const patch = extractPatch(response);
+                if (patch) {
+                    saveSkillState(statePath, mergePatch(readSkillState(statePath), patch));
+                }
+            },
+        };
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAO9B,cAAc,mBAAmB,CAAC;AAUlC,oDAAoD;AACpD,SAAS,aAAa,CAAC,KAAc;IACnC,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,cAAc,CAAC,SAAiB;IAC9C,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAY,CAAC;YAC1E,IACE,OAAO,MAAM,KAAK,QAAQ;gBAC1B,MAAM,KAAK,IAAI;gBACf,OAAO,IAAI,MAAM;gBACjB,OAAQ,MAAkC,CAAC,OAAO,CAAC,KAAK,QAAQ;gBAC/D,MAAkC,CAAC,OAAO,CAAC,KAAK,IAAI,EACrD,CAAC;gBACD,OAAQ,MAAkC,CAAC,OAAO,CAA4B,CAAC;YACjF,CAAC;YACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBAClD,OAAO,MAAiC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,KAA8B;IAC9E,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,IAA6B,EAC7B,KAA8B;IAE9B,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;aAAM,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC9D,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAA4B,EAAE,KAAK,CAAC,CAAC;QAC1E,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACjE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC,CAAC;QACvD,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;YAClE,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,4DAA4D;AAC5D,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAEnD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,UAAU,GAAG,OAAO,CAAC,kBAAkB,IAAI,CAAC,CAAC;IAEnD,OAAO,KAAK,IAAI,EAAE;QAChB,OAAO;YACL,sEAAsE;YACtE,mEAAmE;YACnE,iEAAiE;YACjE,qEAAqE;YACrE,mBAAmB;YACnB,sCAAsC,EAAE,KAAK,EAC3C,MAAM,EACN,MAAM,EACS,EAAE;gBACjB,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;gBACxC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;gBACjC,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;gBACxE,MAAM,OAAO,GAAG,QAAQ;qBACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;qBACvC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;gBAEtB,oEAAoE;gBACpE,uCAAuC;gBACvC,MAAM,YAAY,GAAoB;oBACpC,IAAI,EAAE;wBACJ,EAAE,EAAE,gBAAgB;wBACpB,SAAS,EAAE,YAAY;wBACvB,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE;wBACpB,KAAK,EAAE,YAAY;wBACnB,KAAK,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE;qBAC3D;oBACD,KAAK,EAAE;wBACL;4BACE,EAAE,EAAE,GAAG,gBAAgB,OAAO;4BAC9B,SAAS,EAAE,YAAY;4BACvB,SAAS,EAAE,gBAAgB;4BAC3B,IAAI,EAAE,MAAM;4BACZ,SAAS,EAAE,IAAI;4BACf,IAAI,EAAE,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;yBAC7D;qBACF;iBACF,CAAC;gBAEF,oEAAoE;gBACpE,gEAAgE;gBAChE,MAAM,IAAI,GAAG,CAAC,GAAG,cAAc,EAAE,GAAG,OAAO,EAAE,YAAY,CAAC,CAAC;gBAC3D,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;gBACpB,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YACzB,CAAC;YAED,sEAAsE;YACtE,sEAAsE;YACtE,uEAAuE;YACvE,iCAAiC,EAAE,KAAK,EACtC,MAAM,EACN,MAAM,EACS,EAAE;gBACjB,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;gBACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;oBACnC,MAAM,CAAC,OAAO,GAAG,EAAE,CAAC;gBACtB,CAAC;gBACD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC9D,CAAC;YAED,sEAAsE;YACtE,mEAAmE;YACnE,+CAA+C;YAC/C,oBAAoB,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAiB,EAAE;gBAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;gBACrC,IAAI,OAAO,QAAQ,KAAK,QAAQ;oBAAE,OAAO;gBACzC,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACrC,IAAI,KAAK,EAAE,CAAC;oBACV,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;gBAC1E,CAAC;YACH,CAAC;SACwB,CAAC;IAC9B,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillstate/opencode",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "OpenCode platform adapter for the skillstate runtime.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [