@skillstate/opencode 2.0.0

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/dist/index.js.map

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

package/dist/opencode-adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @non-paper adapter — no adapters exist in arXiv 2608.26263v3.
+ *
+ * Bridges the skillstate runtime into OpenCode via:
+ * - Prompts formatted with the skillstate XML-style skill envelope
+ *   (delegates to PromptTransformer.formatForOpenCode).
+ * - A generated SKILL.md so OpenCode discovers the skill and follows the
+ *   state-based execution process.
+ * - A generated plugin that hooks `experimental.chat.messages.transform` for
+ *   real O(1) history trimming: old messages are dropped, only the last N
+ *   non-system messages plus injected state are sent to the LLM.
+ * - `experimental.session.compacting` injects state into compaction context.
+ * - `tool.execute.after` persists state updates from LLM responses.
+ */
+import type { SkillState, StatePatch, ProceduralSpec, Observation, PlatformAdapter } from '@skillstate/core';
+import type { StatePathRef } from '@skillstate/core';
+/**
+ * OpenCode platform adapter (@non-paper; see module doc).
+ */
+export declare class OpenCodeAdapter implements PlatformAdapter {
+    readonly name = "opencode";
+    private transformer;
+    /**
+     * Produce a prompt string carrying the current state and skill
+     * instructions, directing the LLM to reason and then emit a JSON block
+     * with `state_patch` and `action`.
+     */
+    injectState(state: SkillState, spec: ProceduralSpec): string;
+    /**
+     * Extract the state_patch from an LLM response containing a fenced JSON block.
+     */
+    extractPatch(response: string): StatePatch | null;
+    /**
+     * Extract the action string from an LLM response containing a fenced JSON block.
+     */
+    extractAction(response: string): string | null;
+    /**
+     * Format the full prompt (instructions + state + observation).
+     *
+     * @non-paper — adapter convenience (delegates to the transformer).
+     * Paper-exact callers use `PromptTransformer.formatPaper` (Appendix A.4).
+     */
+    formatPrompt(state: SkillState, observation: Observation, spec: ProceduralSpec): string;
+    /**
+     * Generate a SKILL.md suitable for OpenCode's skill system.
+     *
+     * The frontmatter carries the skill name/description plus an
+     * execution_context block pointing at the persisted state file; the body
+     * describes the state-based execution process. History is discarded by
+     * the plugin's `messages.transform` hook — the LLM sees only the state.
+     */
+    generateSkillMd(spec: ProceduralSpec, statePath?: string): string;
+    /**
+     * Generate an OpenCode plugin with real O(1) prompt economy.
+     *
+     * 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.
+     */
+    generatePluginCode(statePath: string, options?: {
+        maxHistoryMessages?: number;
+    }): 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;
+    /**
+     * @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.
+     */
+    savePluginCode(target: string | StatePathRef, statePath: string | StatePathRef, options?: {
+        maxHistoryMessages?: number;
+    }): Promise<string>;
+    /**
+     * Describe the schema fields for inclusion in prompts.
+     */
+    private describeSchema;
+}
+//# sourceMappingURL=opencode-adapter.d.ts.map

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

@@ -0,0 +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"}

package/dist/opencode-adapter.js

@@ -0,0 +1,263 @@
+import { PromptTransformer } from '@skillstate/core';
+import { atomicWriteFile, resolveStatePath, } from '@skillstate/core';
+/**
+ * OpenCode platform adapter (@non-paper; see module doc).
+ */
+export class OpenCodeAdapter {
+    name = 'opencode';
+    transformer = new PromptTransformer({ platform: 'opencode' });
+    /**
+     * Produce a prompt string carrying the current state and skill
+     * instructions, directing the LLM to reason and then emit a JSON block
+     * with `state_patch` and `action`.
+     */
+    injectState(state, spec) {
+        const stateJson = JSON.stringify(state);
+        const schemaDesc = this.describeSchema(spec.schema);
+        return `<skill name="${spec.id}">
+<instructions>${spec.instructions}</instructions>
+${schemaDesc}
+<state>
+${stateJson}
+</state>
+</skill>
+
+Respond with step-by-step reasoning followed by a JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
+
+\`\`\`json
+{
+  "state_patch": { "key": "new_value", "obsolete_key": null },
+  "action": "your_action_here"
+}
+\`\`\`
+
+In \`state_patch\`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.`;
+    }
+    /**
+     * Extract the state_patch from an LLM response containing a fenced JSON block.
+     */
+    extractPatch(response) {
+        return this.transformer.extractStatePatch(response);
+    }
+    /**
+     * Extract the action string from an LLM response containing a fenced JSON block.
+     */
+    extractAction(response) {
+        return this.transformer.extractAction(response);
+    }
+    /**
+     * Format the full prompt (instructions + state + observation).
+     *
+     * @non-paper — adapter convenience (delegates to the transformer).
+     * Paper-exact callers use `PromptTransformer.formatPaper` (Appendix A.4).
+     */
+    formatPrompt(state, observation, spec) {
+        return this.transformer.formatForOpenCode(spec, state, observation);
+    }
+    /**
+     * Generate a SKILL.md suitable for OpenCode's skill system.
+     *
+     * The frontmatter carries the skill name/description plus an
+     * execution_context block pointing at the persisted state file; the body
+     * describes the state-based execution process. History is discarded by
+     * the plugin's `messages.transform` hook — the LLM sees only the state.
+     */
+    generateSkillMd(spec, statePath) {
+        const resolvedStatePath = statePath ?? './.skillstate.json';
+        return `---
+name: ${JSON.stringify(spec.name)}
+description: ${JSON.stringify(spec.instructions)}
+version: ${spec.version}
+execution_context:
+  state_path: ${resolvedStatePath}
+  format: json
+---
+
+# ${spec.name}
+
+${spec.instructions}
+
+## Execution Context
+
+Your execution state is persisted at \`${resolvedStatePath}\`. Read it at the
+start of every step to recover where you are — never rely on conversation
+history to carry state between steps. History is automatically trimmed by the
+plugin; only the current state and the latest observation matter.
+
+## Process
+
+1. Read the current state from the state file.
+2. Observe the result of your last action.
+3. Reason about what to do next, given the state and the observation.
+4. Respond with a JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:
+
+\`\`\`json
+{
+  "state_patch": { "key": "new_value", "obsolete_key": null },
+  "action": "next_action_name"
+}
+\`\`\`
+
+- In \`state_patch\`, set keys to null to delete them. Only include fields you
+  want to change. Omit fields to leave them unchanged.
+- \`action\` names what you will do next (e.g. "continue", "done").
+- Reasoning is discarded after execution — put anything you need to persist
+  into \`state_patch\`.`;
+    }
+    generatePluginCode(statePathOrRef, options) {
+        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.
+// Real O(1) prompt economy via experimental.chat.messages.transform:
+// trims history to last ${maxHistory} non-system messages + injected state.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { Plugin } from "@opencode-ai/plugin";
+
+const STATE_PATH = ${sp};
+const MAX_HISTORY = ${maxHistory};
+
+function readSkillState(): Record<string, unknown> {
+  try {
+    if (existsSync(STATE_PATH)) {
+      return JSON.parse(readFileSync(STATE_PATH, "utf-8"));
+    }
+  } catch {
+    // Corrupt or unreadable state file — fall back to empty state.
+  }
+  return {};
+}
+
+function saveSkillState(state: Record<string, unknown>): void {
+  try {
+    writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+  } catch {
+    // Best-effort: read-only environments or permission issues.
+  }
+}
+
+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) {
+      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 {
+      result[key] = patch[key];
+    }
+  }
+  return result;
+}
+
+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;
+    }
+  } catch {
+    // Malformed JSON — ignore.
+  }
+  return null;
+}
+
+export const SkillStatePlugin: Plugin = async ({ project, client, $ }) => {
+  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) => {
+      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 stateMessage = {
+        role: "user",
+        content: "Current skill state (JSON): " + JSON.stringify(state),
+      };
+
+      output.messages = [...systemMessages, ...trimmed, stateMessage];
+      return output;
+    },
+
+    // ── 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();
+      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 ?? "";
+      if (typeof response === "string") {
+        const patch = extractPatch(response);
+        if (patch) {
+          const current = readSkillState();
+          const merged = mergePatch(current, patch);
+          saveSkillState(merged);
+        }
+      }
+      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

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

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@skillstate/opencode",
+  "version": "2.0.0",
+  "description": "OpenCode platform adapter for the skillstate runtime.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@skillstate/core": "^2.0.0"
+  }
+}