@skillstate/opencode 2.2.2 → 3.0.0

package/dist/plugin.d.ts

@@ -1,95 +1,87 @@
-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.
- */
-export { resolveHostStateForCwd as resolveStatePathForCwd };
-export { mergePatch };
-/** Options for {@link createSkillStatePlugin}. */
-export interface SkillStatePluginOptions {
-    /** 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. Thin fs
- * adapter over the core hook-runtime {@link readStateEnvelope}.
- */
-export declare function readSkillState(statePath: string): Record<string, unknown>;
-/**
- * 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).
- */
-export declare function saveSkillState(statePath: string, state: Record<string, unknown>): 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.
- */
-export declare function mergeSkillState(statePath: string, 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`. Thin adapter over the core hook-runtime
- * {@link findFencedPatch} (the invalid/truncated outcomes collapse to
- * `null`, preserving the legacy boolean contract).
- */
-export declare function extractPatch(response: string): Record<string, unknown> | null;
-/**
- * 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).
- */
-export declare function pluginAgentId(input: {
-    sessionID?: unknown;
-}, messages?: OpenCodeMessage[]): string;
-/**
- * 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).
- */
-export declare function scopedAgentId(agentId: string): string;
-/**
- * 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.
+ * `@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 ────────────────────────────────────────────────────────
+ *
+ * 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
+ *   `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 declare function registerSessionParent(sessionId: unknown, parentId: unknown): void;
-/** Test-only: forget every registered session→parent edge. */
-export declare function resetSessionParents(): void;
+import { Plugin } from '@opencode/plugin';
+/** Stable plugin id — scopes plugin storage and identifies it in `/api/plugin`. */
+export declare const PLUGIN_ID = "skillstate";
 /**
- * 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 three things and 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.
+ *
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/plugin.js

@@ -1,279 +1,147 @@
 /**
- * Static OpenCode plugin — the SINGLE SOURCE OF TRUTH for the skillstate
- * host integration. `OpenCodeAdapter.generatePluginCode` emits a thin loader
- * that imports `createSkillStatePlugin` from this module; the per-project
- * state resolution lives in `@skillstate/core`
- * (`resolveHostStateForCwd`, re-exported here) and the hook logic
- * (envelope read/write, ⊕ merge, patch extraction) in the core
- * hook-runtime — this module only adapts it to the OpenCode hooks.
+ * `@skillstate/opencode` — the OpenCode **v2** plugin.
  *
- * 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.
+ * ── What this replaces ───────────────────────────────────────────────────
  *
- * AGENT-SCOPED STATE: the opencode hook inputs carry the session id
- * (`input.sessionID`; message envelopes carry `info.sessionID`). The MAIN
- * session resolves to 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. SUB-AGENT sessions (registered from the host event bus —
- * `session.created`/`session.updated` carry `info.parentID`) resolve to
- * isolated `agents/<parentPrefix>-<sessionPrefix>/` copies and never
- * last-writer-win the main state; the main agent folds them back with
- * `agent.merge`. Writes go through the core cross-process sync lock
- * (`lockStateWrite`) so a state file is never interleaved between
- * processes.
+ * 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 ────────────────────────────────────────────────────────
+ *
+ * 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
+ *   `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"] }
+ * ```
  */
-import * as fs from 'node:fs';
-import * as os from 'node:os';
+import { Plugin } from '@opencode/plugin';
 import * as path from 'node:path';
-import { findFencedPatch, lockStateWrite, mergePatch, readStateEnvelope, resolveAgentIdFromSession, resolveHostStateForCwd, saveStateEnvelope, } from '@skillstate/core';
-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.
- */
-export { resolveHostStateForCwd as resolveStatePathForCwd };
-export { mergePatch };
-/**
- * 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}.
- */
-export function readSkillState(statePath) {
-    return readStateEnvelope(statePath, (p) => fs.readFileSync(p, 'utf-8'));
-}
-/**
- * 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).
- */
-export function saveSkillState(statePath, state) {
-    try {
-        fs.mkdirSync(path.dirname(statePath), { recursive: true });
-        lockStateWrite(statePath, fs, () => saveStateEnvelope(statePath, state, (p, data) => fs.writeFileSync(p, data)));
-    }
-    catch {
-        // Best-effort: read-only environments or permission issues.
-    }
-}
+import { SessionRegistry, stateScopeFor } from './session-registry.js';
+import { ProjectStateStore } from './state-store.js';
+import { buildStateHint } from './system-hint.js';
+import { registerTools } from './tools.js';
+/** Stable plugin id — scopes plugin storage and identifies it in `/api/plugin`. */
+export const PLUGIN_ID = 'skillstate';
 /**
- * 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.
- */
-export function mergeSkillState(statePath, patch) {
-    try {
-        fs.mkdirSync(path.dirname(statePath), { recursive: true });
-        let merged = {};
-        lockStateWrite(statePath, fs, () => {
-            merged = mergePatch(readSkillState(statePath), patch);
-            saveStateEnvelope(statePath, merged, (p, data) => fs.writeFileSync(p, data));
-        });
-        return merged;
-    }
-    catch {
-        return readSkillState(statePath);
-    }
-}
-/**
- * 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).
- */
-export function extractPatch(response) {
-    const result = findFencedPatch(response);
-    return 'patch' in result ? result.patch : null;
-}
-/**
- * Agent id for an opencode hook call.
+ * The plugin definition.
  *
- * 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).
- */
-export function pluginAgentId(input, messages) {
-    const direct = resolveAgentIdFromSession(input?.sessionID);
-    const sessionPrefix = direct.length > 0
-        ? direct
-        : resolveAgentIdFromSession((messages ?? []).find((m) => typeof m.info?.sessionID === 'string' &&
-            m.info.sessionID.length > 0 &&
-            m.info.sessionID !== 'skillstate')?.info.sessionID);
-    if (sessionPrefix.length === 0)
-        return '';
-    return scopedAgentId(sessionPrefix);
-}
-/**
- * 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).
- */
-export function scopedAgentId(agentId) {
-    const parent = SUB_AGENT_PARENTS.get(agentId);
-    return parent === undefined ? '' : `${parent}-${agentId}`;
-}
-/**
- * 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.
- */
-export function registerSessionParent(sessionId, parentId) {
-    if (typeof sessionId !== 'string' || sessionId.length === 0)
-        return;
-    const session = resolveAgentIdFromSession(sessionId);
-    if (session.length === 0)
-        return;
-    const parent = resolveAgentIdFromSession(parentId);
-    if (parent.length === 0 || parent === session) {
-        SUB_AGENT_PARENTS.delete(session);
-        return;
-    }
-    SUB_AGENT_PARENTS.set(session, parent);
-}
-/** Test-only: forget every registered session→parent edge. */
-export function resetSessionParents() {
-    SUB_AGENT_PARENTS.clear();
-}
-/** Synthetic message ids for the injected state carrier. */
-const STATE_MESSAGE_ID = 'skillstate-state-inject';
-/**
- * The session ids known to be SUB-AGENT sessions, keyed by session id →
- * parent session id. Populated from the `event` hook
- * (`session.created`/`session.updated` carry `info.parentID`); consulted
- * when resolving an agent id so a sub-agent's state lands in the SAME
- * agents/<parent>/<session-8>/ scope as its hook-session (the task tool
- * spawns sessions whose ids never appear as sub-agent prefixes — without
- * this map a sub-agent would silently write the MAIN state).
- */
-const SUB_AGENT_PARENTS = new Map();
-/**
- * Build the OpenCode plugin function with the same behavior for every host
- * entry point (thin generated loaders, direct imports).
+ * `setup` wires three things and returns a cleanup function:
  *
- * 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.
+ * - 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.
+ *
+ * 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 function createSkillStatePlugin(options = {}) {
-    const resolvePath = (agentId) => resolveHostStateForCwd(process.cwd(), os.homedir(), agentId);
-    const maxHistory = options.maxHistoryMessages ?? 3;
-    return async () => {
-        return {
-            // ── Session registry ──────────────────────────────────────────────
-            // The host event bus carries full Session objects on
-            // session.created/updated — including `parentID`. Registering here
-            // is what makes sub-agent scoping work: a Task sub-agent's session
-            // (parentID set) resolves to agents/<parent>-<session>/ BEFORE its
-            // first hook fires, so it never touches the parent's state file.
-            event: async ({ event }) => {
-                const payload = event;
-                if (payload === null ||
-                    typeof payload !== 'object' ||
-                    payload['type'] !== 'session.created' && payload['type'] !== 'session.updated') {
-                    return;
-                }
-                const info = payload['properties']?.['info'];
-                if (info === null || typeof info !== 'object')
-                    return;
-                const record = info;
-                registerSessionParent(record['id'], record['parentID']);
-            },
-            // ── 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 agentId = pluginAgentId(input, output.messages);
-                const state = readSkillState(resolvePath(agentId));
-                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 agentId = pluginAgentId(input);
-                const state = readSkillState(resolvePath(agentId));
-                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), and atomically merge it into the session-scoped
-            // state (read + merge + write all inside the cross-process lock).
-            'tool.execute.after': async (input, output) => {
-                const response = output.output ?? '';
-                if (typeof response !== 'string')
-                    return;
-                const agentId = pluginAgentId(input);
-                const patch = extractPatch(response);
-                if (patch) {
-                    mergeSkillState(resolvePath(agentId), patch);
+export const SkillStatePlugin = Plugin.define({
+    id: PLUGIN_ID,
+    async setup(ctx) {
+        const sessions = new SessionRegistry();
+        const scopeFor = (sessionID) => stateScopeFor(sessions, sessionID);
+        // `ctx.location.project.canonical` is the canonical checkout, stable
+        // across worktrees and symlinks. The v1 plugin used `process.cwd()`,
+        // which in v2 is the server's cwd, not the session's project.
+        const store = new ProjectStateStore({
+            directory: ctx.location.project.canonical,
+        });
+        await ctx.tool.transform((editor) => {
+            registerTools(editor, { store, sessions, scopeFor });
+        });
+        // ── Session tree ────────────────────────────────────────────────────
+        // Sub-agent sessions are created by OpenCode itself, so the parent edge
+        // arrives on the event stream. Until one is seen a session is treated as
+        // a root session, which is the correct default for single-session use.
+        const controller = new AbortController();
+        void (async () => {
+            try {
+                for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+                    sessions.ingestEvent(event);
                 }
-            },
+            }
+            catch {
+                // The stream ends when the plugin unloads or the server goes away.
+                // Session scoping degrades to "everyone shares the project file",
+                // which is safe; it must never surface as an unhandled rejection.
+            }
+        })();
+        // ── System fragment ─────────────────────────────────────────────────
+        // Registered on the agent loop only. `compaction`, `generate` and
+        // `title` are separate hooks in v2 and are deliberately left alone:
+        // after a compaction the next agent-loop request re-adds the fragment,
+        // so state survives without this plugin ever touching the transcript or
+        // the summariser's input.
+        await ctx.session.hook('context', (event) => {
+            const scope = scopeFor(event.sessionID);
+            if (!store.exists(scope))
+                return;
+            const state = store.read(scope);
+            const hint = buildStateHint({
+                state,
+                statePath: path.relative(store.projectDirectory, store.pathFor(scope)),
+                scope,
+            });
+            if (hint.length === 0)
+                return;
+            event.system.push({ type: 'text', text: hint });
+        });
+        return () => {
+            controller.abort();
         };
-    };
-}
+    },
+});
+export default SkillStatePlugin;
 //# sourceMappingURL=plugin.js.map