@imunitic/synapse 0.13.16 → 0.14.0

package/bin/synapse-setup.cjs

@@ -239,13 +239,9 @@ function configureClaude() {
   const rendered = renderHooksTemplate(path.join(PKG_ROOT, "harness", "claude", "hooks.json"), hookBin);
   settings.hooks = mergeHooksInto(settings.hooks, rendered);
 
-  // The npm-install counterpart to $CLAUDE_PLUGIN_ROOT -- conf.zig's own
-  // resolveConfPath and session_start.zig's synapse-claude.md/Index.md.template
-  // lookups both check this env var now that there's no plugin marketplace
-  // to set CLAUDE_PLUGIN_ROOT for them. Points at PKG_ROOT, the same
-  // relative shape CLAUDE_PLUGIN_ROOT used to point at plugins/synapse/ --
-  // synapse-claude.md, Index.md.template, and every *.conf.template sit
-  // directly under it.
+  // SYNAPSE_CONTENT_ROOT points at PKG_ROOT: the config resolution in
+  // Conf_Files and the session-start hook look up synapse-claude.md,
+  // Index.md.template and every *.conf.template directly under it.
   settings.env = settings.env || {};
   settings.env.SYNAPSE_CONTENT_ROOT = PKG_ROOT;
 

package/commands/synapse-rebuild-full.md

@@ -148,5 +148,5 @@ note live containing only the leftovers, trimmed of everything that did get merg
   only the wipe-with-preservation step before it and the note-merge step after it.
 - The wipe itself is `synapse graph-wipe` (via `synapse graph-wipe`), mirroring
   `synapse graph-clean` as the only other destructive tool in the system.
-- Resolves the namespace the same way `/synapse-init` and `/synapse-rebuild-diff` do -- one chain, in `core/identity.zig`
+- Resolves the namespace the same way `/synapse-init` and `/synapse-rebuild-diff` do -- one chain, in `Core.Identity`
   — never re-derives repo/branch/remote independently.

package/harness/codex/skills/synapse-rebuild-full/SKILL.md

@@ -146,4 +146,4 @@ note live containing only the leftovers, trimmed of everything that did get merg
 - The wipe itself is `synapse graph-wipe` (via `synapse graph-wipe`), mirroring
   `synapse graph-clean` as the only other destructive tool in the system.
 - Resolves the namespace the same way the synapse-init and synapse-rebuild-diff skills do -- one
-  chain, in `core/identity.zig` — never re-derives repo/branch/remote independently.
+  chain, in `Core.Identity` — never re-derives repo/branch/remote independently.

package/harness/opencode/plugin/synapse.js

@@ -2,35 +2,39 @@
 // Code's hooks.json already calls, translating OpenCode's plugin callbacks
 // into the same stdin JSON payload / stdout `hookSpecificOutput` shape the
 // binary already reads and writes. No engine change -- see
-// `src/apps/hook/main.zig`'s own doc comment for that contract.
+// `src/hooks/synapse-hooks-dispatch.ads`'s own doc comment for that contract.
 //
-// Session lifecycle isn't a named `Hooks` key in OpenCode's plugin API --
-// confirmed against the real `@opencode-ai/plugin`/`@opencode-ai/sdk` type
-// packages, not assumed from prose docs. `session.created` is delivered
-// only through the generic catch-all `event` hook as an `Event` union
-// member (`event.type === "session.created"`), so this plugin instead
-// piggybacks the equivalent one-per-session injection on `chat.message`,
-// gated on whether this session has already received it -- checked against
-// real session history (`client.session.messages`), not just in-memory
-// state, since each `opencode run` CLI invocation is its own short-lived
-// process and an in-memory Set alone re-injects on every `--continue` call.
+// Ported to the OpenCode v2 plugin API (2.0.x). The v2 loader rejects this
+// file's old shape outright at load time -- it requires a default export
+// carrying an `id` plus a `setup(ctx)` function, and it never runs a bare
+// named-export factory ("Plugin must export a default definition with an id
+// and an effect or setup function"). The v1 hook map is kept as `server()`
+// for OpenCode 1.18.29+ hosts, which read exactly that key off the default
+// export; the two implementations share all state and helpers below, and
+// only the wiring differs.
 //
-// `tool.execute.after`'s real tool names/args, live-verified against a real
-// edit: `write` (`args.filePath`, `args.content`) and `edit` (`args.filePath`,
-// `args.oldString`, `args.newString`) -- both share `filePath`, matching
-// Claude Code's `Write`/`Edit` sharing `tool_input.file_path`. Fired on
-// write/edit tools for `staleness` -- the vault's own version control
-// (`SYNAPSE_VAULT_INTEGRATIONS=git`) commits from inside `synapse`'s own CLI
-// (`vault-write`/`vault-patch`) itself now, needing no `PostToolUse`-style
-// hook here or on any other harness.
+// v1 `chat.message` -> v2 `ctx.session.hook("prompt", ...)`. The v2 prompt
+// hook runs once at prompt admission, before the durable inbox write, and an
+// edit to `event.prompt.text` becomes the canonical persisted user input --
+// so appending the synapse blocks there lands them where v1's synthetic parts
+// did: delivered to the model call answering this prompt, and persisted in
+// session history. That persistence is what makes the one-per-session gate
+// correct across separate `opencode run` invocations -- each CLI call is its
+// own short-lived process with an empty in-memory Set, so the gate re-checks
+// real session history (`ctx.session.context`), not just memory.
 //
-// `stop-nudge`'s Claude Code trigger (`Stop`, once per turn) maps to
-// `session.idle` -- live-verified as firing exactly once, after every tool
-// call and the final response for a turn. Its own `additionalContext` (the
-// periodic "worth capturing" nudge) has nowhere to land at that moment --
-// `session.idle` is a pure notification, no message `output` to push a part
-// onto the way `chat.message` has -- so it's queued and delivered as a
-// synthetic part on the *next* `chat.message` instead of dropped.
+// v1 `tool.execute.after` -> v2 `ctx.tool.hook("execute.after", ...)`, same
+// event fields under different names (`event.tool`, `event.input` instead of
+// `input.tool`, `input.args`).
+//
+// v1 `event` -> v2 `ctx.event.subscribe()`, filtered to `session.idle` --
+// live-verified in v1 as firing exactly once, after every tool call and the
+// final response for a turn. `stop-nudge`'s `additionalContext` (the periodic
+// "worth capturing" nudge) still has nowhere to land at that moment -- idle
+// is a pure notification -- so it stays queued and delivered as a block on
+// the *next* admitted prompt instead of dropped. Same for `staleness`
+// warnings: `tool.execute.after` is a post-hoc notification with no way to
+// reach the current turn, so its output queues the same way.
 //
 // `synapse-hook`'s own binary path isn't resolved here the usual way --
 // OpenCode plugins get no `${CLAUDE_PLUGIN_ROOT}`-equivalent "where am I
@@ -86,54 +90,85 @@ const injected = new Set()
 // correct across separate CLI invocations, not just within one, confirmed
 // live: without this check, a second `opencode run --continue` call
 // re-injected the full vault index every time.
-async function alreadyInjected(client, sessionID) {
+//
+// The Set claim happens synchronously *before* the awaited history read, so
+// two prompts admitted concurrently in one process cannot both pass the
+// check (v1 marked only after the await, leaving that race open).
+async function alreadyInjected(fetchHistory, sessionID) {
   if (injected.has(sessionID)) return true
+  injected.add(sessionID)
   try {
-    const res = await client.session.messages({ path: { id: sessionID } })
-    const history = res?.data ?? []
-    const found = history.some((m) => m.parts.some((p) => p.type === "text" && p.text.startsWith(SESSION_START_MARKER)))
-    if (found) injected.add(sessionID)
-    return found
+    const history = await fetchHistory(sessionID)
+    return history.some(messageHasMarker)
   } catch {
     return false
   }
 }
 
+// v1 messages carry text in `parts`; v2 session-context messages (user and
+// synthetic alike) carry it flat on `text`.
+function messageHasMarker(m) {
+  if (typeof m?.text === "string") return m.text.startsWith(SESSION_START_MARKER)
+  return (m?.parts ?? []).some((p) => p.type === "text" && p.text.startsWith(SESSION_START_MARKER))
+}
+
 const EDIT_TOOLS = new Set(["write", "edit"])
 
 // sessionID -> nudge text from a `stop-nudge` call that had nowhere to land
-// yet -- delivered on that session's next `chat.message`.
+// yet -- delivered on that session's next admitted prompt.
 const pendingNudge = new Map()
 
 // sessionID -> queued `staleness` output, same reason and same delivery as
-// `pendingNudge` above: `tool.execute.after` has no message `output` to push
-// a part onto, so a drift/grounding warning from it would otherwise be
+// `pendingNudge` above: `tool.execute.after` has no channel into the turn
+// that just ran, so a drift/grounding warning from it would otherwise be
 // silently discarded instead of just reaching the next turn late.
 const pendingStaleness = new Map()
 
+// Blocks delivered alongside a prompt, in v1's part order: session-start,
+// queued nudge, queued staleness, prompt-context.
+async function collectBlocks(sessionID, opts) {
+  const blocks = []
+
+  if (!(await opts.injected())) {
+    const ctx = runHook("session-start", { cwd: opts.directory })
+    if (ctx) blocks.push(`${SESSION_START_MARKER}\n${ctx}`)
+  }
+
+  const queuedNudge = pendingNudge.get(sessionID)
+  if (queuedNudge) {
+    pendingNudge.delete(sessionID)
+    blocks.push(`[SYNAPSE-STOP-NUDGE]\n${queuedNudge}`)
+  }
+
+  const queuedStaleness = pendingStaleness.get(sessionID)
+  if (queuedStaleness) {
+    pendingStaleness.delete(sessionID)
+    blocks.push(`[SYNAPSE-STALENESS]\n${queuedStaleness}`)
+  }
+
+  return blocks
+}
+
+// ---------------------------------------------------------------------------
+// v1 wiring (OpenCode 1.x): named factory plus `server()` on the default
+// export, per the v1->v2 migration guide's dual-entrypoint shape.
+// ---------------------------------------------------------------------------
+
 export const Synapse = async ({ directory, client }) => {
   return {
     "chat.message": async (input, output) => {
       const sessionID = input.sessionID
       const newParts = []
 
-      if (!(await alreadyInjected(client, sessionID))) {
-        injected.add(sessionID)
-        const ctx = runHook("session-start", { cwd: directory })
-        if (ctx) newParts.push(textPart(sessionID, output, `${SESSION_START_MARKER}\n${ctx}`))
-      }
-
-      const queuedNudge = pendingNudge.get(sessionID)
-      if (queuedNudge) {
-        pendingNudge.delete(sessionID)
-        newParts.push(textPart(sessionID, output, `[SYNAPSE-STOP-NUDGE]\n${queuedNudge}`))
-      }
-
-      const queuedStaleness = pendingStaleness.get(sessionID)
-      if (queuedStaleness) {
-        pendingStaleness.delete(sessionID)
-        newParts.push(textPart(sessionID, output, `[SYNAPSE-STALENESS]\n${queuedStaleness}`))
+      const history = async (id) => {
+        const res = await client.session.messages({ path: { id } })
+        return res?.data ?? []
       }
+      const blocks = await collectBlocks(sessionID, {
+        directory,
+        injected: () => alreadyInjected(history, sessionID),
+      })
+      for (const block of blocks) newParts.push(textPart(sessionID, output, block))
 
       const promptText = (output.parts || [])
         .filter((p) => p.type === "text")
@@ -158,9 +193,69 @@ export const Synapse = async ({ directory, client }) => {
 
     event: async ({ event }) => {
       if (event.type !== "session.idle") return
-      const sessionID = event.properties.sessionID
+      const sessionID = event.properties?.sessionID ?? event.data?.sessionID
       const text = runHook("stop-nudge", { session_id: sessionID })
-      if (text) pendingNudge.set(sessionID, text)
+      if (text && sessionID) pendingNudge.set(sessionID, text)
     },
   }
 }
+
+// ---------------------------------------------------------------------------
+// v2 wiring (OpenCode 2.x): registrations through the plugin context.
+// ---------------------------------------------------------------------------
+
+async function setup(ctx) {
+  const directory = ctx.location.directory
+
+  await ctx.session.hook("prompt", async (event) => {
+    const sessionID = event.sessionID
+
+    const history = async (id) => {
+      const res = await ctx.session.context({ sessionID: id })
+      return Array.isArray(res) ? res : res?.data ?? []
+    }
+    const blocks = await collectBlocks(sessionID, {
+      directory,
+      injected: () => alreadyInjected(history, sessionID),
+    })
+
+    const promptText = event.prompt?.text ?? ""
+    const nudge = runHook("prompt-context", { cwd: directory, prompt: promptText || "x" })
+    if (nudge) blocks.push(`[SYNAPSE-PROMPT-CONTEXT]\n${nudge}`)
+
+    if (blocks.length) {
+      event.prompt.text = promptText ? `${promptText}\n\n${blocks.join("\n\n")}` : blocks.join("\n\n")
+    }
+  })
+
+  await ctx.tool.hook("execute.after", async (event) => {
+    const filePath = event.input?.filePath
+    if (EDIT_TOOLS.has(event.tool) && filePath) {
+      const text = runHook("staleness", {
+        session_id: event.sessionID,
+        tool_input: { file_path: filePath },
+      })
+      if (text) pendingStaleness.set(event.sessionID, text)
+    }
+  })
+
+  const controller = new AbortController()
+  void (async () => {
+    for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+      if (event?.type !== "session.idle") continue
+      const sessionID = event.data?.sessionID ?? event.properties?.sessionID
+      if (!sessionID) continue
+      const text = runHook("stop-nudge", { session_id: sessionID })
+      if (text) pendingNudge.set(sessionID, text)
+    }
+  })().catch(() => {})
+
+  return () => controller.abort()
+}
+
+export default {
+  id: "synapse",
+  setup,
+  // v1 hook factory, read by OpenCode 1.18.29+ loaders; v2 hosts ignore it.
+  server: Synapse,
+}

package/lib/resolve-binaries.cjs

@@ -15,9 +15,9 @@ const path = require("path");
 const CLI_NAME = "synapse";
 const HOOK_NAME = "synapse-hook";
 
-// Matches process.platform/process.arch directly (not a Zig target triple)
+// Matches process.platform/process.arch directly (not a compiler target triple)
 // since that's what npm's own `os`/`cpu` fields select against -- the
-// release pipeline maps its Zig target names to this naming once, at
+// release pipeline maps its target names to this naming once, at
 // publish time, not here.
 function platformPackageName() {
   return `@imunitic/synapse-${process.platform}-${process.arch}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.13.16",
+  "version": "0.14.0",
   "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable markdown vault plus a per-repo code graph.",
   "repository": {
     "type": "git",
@@ -23,9 +23,9 @@
     "*.conf.template"
   ],
   "optionalDependencies": {
-    "@imunitic/synapse-darwin-arm64": "0.13.16",
-    "@imunitic/synapse-linux-x64": "0.13.16",
-    "@imunitic/synapse-linux-arm64": "0.13.16"
+    "@imunitic/synapse-darwin-arm64": "0.14.0",
+    "@imunitic/synapse-linux-x64": "0.14.0",
+    "@imunitic/synapse-linux-arm64": "0.14.0"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/skills/synapse-node-authoring/SKILL.md

@@ -44,7 +44,7 @@ conf file actually lives"): the first tier with a file at all wins, whether or n
 sets `SYNAPSE_AUTHOR_POOL` — a `synapse.conf` at `~/.claude/` is not consulted when one already
 exists at the XDG tier, even if the XDG one is silent on this key. Absent, empty, or malformed
 all fall through to `0`. **This is read by you, the orchestrating agent, directly — not by any
-Zig binary.** Nothing compiled dispatches subagents, so there is nothing for a `synapse` flag to
+compiled binary.** Nothing compiled dispatches subagents, so there is nothing for a `synapse` flag to
 feed. The conf file is the shared home for the setting; the reader is markdown, not code.
 
 `pool = 0` is not "a pool of zero workers" — go to §2. `pool >= 1` is a real worker pool — go
@@ -142,7 +142,7 @@ convention. State it here, every time, rather than assuming it travels for free.
 ### 3d. Verify on completion, retry once, then fall back
 
 When a completion notification arrives, read `b-NN.md` yourself — this is a check you read the
-file for, same as the section check next to it, not a shell one-liner (`core/query.zig` is this
+file for, same as the section check next to it, not a shell one-liner (`Core.Frontmatter` is this
 codebase's own tested, compiled frontmatter reader — a fresh hand-rolled `grep`/`sed`/`awk`
 pattern here would drift from it the same way the gap this section exists to close first
 happened). Confirm the file exists, opens with

package/skills/synapse-orientation/SKILL.md

@@ -406,9 +406,9 @@ discipline — never assume a patch worked from reading it:
 
 A per-file "this file depends on library L" edge narrows an ambiguous reference (a name defined in
 more than one node) to the candidate the referencing file actually declares a dependency on —
-`core/links.zig`'s own real signal for that case, read from `synapse-dependency-rules.conf`
+`Core.Links`' own real signal for that case, read from `synapse-dependency-rules.conf`
 (`SYNAPSE_DEPENDENCY_RULES_CONF` overrides the path), a second registry alongside
-`synapse-namespace-rules.conf` and reusing the exact same `core/namespace.Rule`/`Registry` shape
+`synapse-namespace-rules.conf` and reusing the exact same `Core.Namespace.Rule`/`Registry` shape
 unchanged — a rule per extension, `kind` `in-file` or `build-file`, ordered `prefix`/`terminator`,
 first match wins, no per-language branching in code. A separate file, not a second key on the same
 one: an extension can need both a namespace rule (what a file *is*) and a dependency rule (what a

package/synapse.conf.template

@@ -44,7 +44,7 @@ SYNAPSE_GRAMMARS_DIR="$HOME/.cache/synapse/grammars"
 # -- the safest choice and the only one that preserves cross-node authorial
 # memory. N>=1 fans out to a worker pool of that size instead, each node
 # written by an isolated subagent. Read directly by the orchestrating agent
-# when it runs /synapse-init, not by any Zig binary -- nothing compiled
+# when it runs /synapse-init, not by any compiled binary -- nothing compiled
 # dispatches subagents.
 #SYNAPSE_AUTHOR_POOL=0