feat!: align hot-path session memory with context-mode (#2)

## Summary
- re-center the branch on an MCP-first `session_*` runtime, with
in-process bounded execution, file processing, local indexing/search,
and per-root-session corpus storage on Redis/FalkorDB
- keep session continuity and long-term memory split correctly: plugin
hooks own canonical root-session resolution, event capture,
`<session_memory>` injection, and native-tool enforcement, while
Graphiti stays asynchronous and off the hot path
- harden runtime lifecycle and session-state behavior with shared
teardown, temporary-root to canonical-root migration, bounded
artifact/corpus overflow handling, and follow-up docs/config cleanup

## Key Changes
- register an in-process `session_*` MCP surface from the plugin
runtime: `session_execute`, `session_execute_file`,
`session_batch_execute`, `session_index`, `session_search`,
`session_fetch_and_index`, `session_stats`, and `session_doctor`
- add the local session corpus layer for normalized indexing, bounded
search/snippet retrieval, fetched-content ingestion, artifact storage,
and per-root-session stats in Redis/FalkorDB
- route large or risky work toward the MCP-first path via
`tool.execute.before` / `tool.execute.after`, including native-tool
guidance, argument rewriting, denial paths, and routing outcome metadata
- preserve shared session state across parent/child and
temporary/canonical root transitions by wiring runtime-state migration
through `SessionManager`, the session MCP runtime, and corpus storage
- retain the Redis-backed short-term memory + async Graphiti model:
hot-path injection remains local/cache-backed, while Graphiti drain and
cache refresh stay background-only
- refresh README/plans/tests to describe the MCP-first architecture,
local-first injection semantics, Graphiti-optional behavior, and current
validation surface
- update release workflow behavior in `.github/workflows/publish.yml`
and `.github/scripts/version.ts` so publish gating, skip behavior, and
tag/release creation stay consistent and idempotent even when npm
publish is skipped

## Testing
- add and expand focused Deno coverage for the MCP runtime, corpus,
routing, runtime teardown, session migration, and hook integration paths
- covered suites now include `src/services/session-mcp-runtime.test.ts`,
`src/services/session-corpus.test.ts`,
`src/services/tool-routing.test.ts`,
`src/services/tool-guidance-cache.test.ts`,
`src/services/tool-routing-outcome-cache.test.ts`,
`src/handlers/tool-before.test.ts`, `src/handlers/tool-after.test.ts`,
`src/session.test.ts`, and related index/handler/service tests
- release/versioning coverage includes `.github/scripts/version.test.ts`

## Notes
- this PR is no longer just the original Redis hot-tier rewrite; it now
reflects the follow-up MCP-first replacement work and the later
hardening passes on runtime lifecycle, corpus behavior, root-session
migration, and release workflow handling
- current docs intentionally describe hooks as enforcement/continuity
plumbing, not the primary execution surface; the primary path is the
in-process `session_*` MCP runtime

Author: vicary

.github/scripts/version.test.ts

@@ -10,6 +10,8 @@
  *   COMMIT_SHA         - override for GITHUB_SHA (e.g. PR head SHA)
  */
 
+import { parse as parseJsonc } from "jsr:@std/jsonc@^1.0.2";
+
 /** Semantic version bump type. */
 export type Bump = "major" | "minor" | "patch" | "none";
 
@@ -18,16 +20,108 @@ export type VersionResult =
   | { skip: true }
   | { skip: false; version: string; tag: "latest" | "canary" };
 
+export interface VersionCliDeps {
+  cmd: (...command: string[]) => Promise<string>;
+  readTextFile: (filePath: string) => Promise<string>;
+  envGet: (name: string) => string | undefined;
+  appendFile: (filePath: string, text: string) => void;
+  log: (message: string) => void;
+  now: () => Date;
+}
+
+export interface CommandOutputResult {
+  stdout: Uint8Array;
+  stderr: Uint8Array;
+  success: boolean;
+  code: number;
+}
+
+export function parseCommandOutput(
+  command: string[],
+  result: CommandOutputResult,
+): string {
+  const stdoutText = new TextDecoder().decode(result.stdout).trim();
+  const stderrText = new TextDecoder().decode(result.stderr).trim();
+
+  if (!result.success) {
+    const stderrSuffix = stderrText ? `: ${stderrText}` : "";
+    throw new Error(
+      `Command failed with exit code ${result.code} (${
+        command.join(" ")
+      })${stderrSuffix}`,
+    );
+  }
+
+  return stdoutText;
+}
+
+export async function runCommand(...command: string[]): Promise<string> {
+  const proc = new Deno.Command(command[0], {
+    args: command.slice(1),
+    stdout: "piped",
+    stderr: "piped",
+  });
+  return parseCommandOutput(command, await proc.output());
+}
+
+function parsePackageManifest(text: string, filePath: string): unknown {
+  if (filePath.endsWith(".jsonc")) {
+    return parseJsonc(text);
+  }
+
+  return JSON.parse(text);
+}
+
+function getPackageNameFromManifest(manifest: unknown): string | undefined {
+  if (
+    manifest &&
+    typeof manifest === "object" &&
+    "name" in manifest &&
+    typeof manifest.name === "string"
+  ) {
+    return manifest.name;
+  }
+
+  return undefined;
+}
+
+const defaultVersionCliDeps: VersionCliDeps = {
+  cmd: (...command: string[]) => runCommand(...command),
+  readTextFile: (filePath) => Deno.readTextFile(filePath),
+  envGet: (name) => Deno.env.get(name),
+  appendFile: (filePath, text) => {
+    Deno.writeTextFileSync(filePath, text, { append: true });
+  },
+  log: (message) => console.log(message),
+  now: () => new Date(),
+};
+
+/**
+ * Returns true when any commit body contains a semantic-release style breaking
+ * change footer/header such as `BREAKING CHANGE: details`.
+ */
+export function hasBreakingChangeBody(bodies: string[]): boolean {
+  return bodies.some((body) => /^BREAKING CHANGE:/im.test(body));
+}
+
 /**
- * Analyze conventional commit subjects and return the highest bump type.
+ * Analyze conventional commits and return the highest bump type.
+ *
+ * Supported formats:
+ * - `feat: add feature` -> minor
+ * - `fix: resolve bug` / `perf: speed up path` -> patch
+ * - `feat!: breaking api change` / `fix!: breaking bugfix` -> major
+ * - `BREAKING CHANGE: explanation` in a commit body -> major
+ * - `Release-As: x.y.z` is handled separately as an exact override
  *
- * Rules:
- * - `BREAKING CHANGE` in body or `type!:` → major
- * - `feat:` → minor
- * - `fix:` / `perf:` → patch
- * - Anything else → none
+ * In `0.x`, a major bump resolves to the next minor version.
  */
-export function analyzeCommits(subjects: string[]): Bump {
+export function analyzeCommits(
+  subjects: string[],
+  bodies: string[] = [],
+): Bump {
+  if (hasBreakingChangeBody(bodies)) return "major";
+
   let bump: Bump = "none";
 
   for (const msg of subjects) {
@@ -111,6 +205,17 @@ export function hasNonTestChanges(changedFiles: string[]): boolean {
   return changedFiles.some((file) => file && !file.endsWith(".test.ts"));
 }
 
+/** Parse newline-separated changed-file output into a stable unique list. */
+export function parseChangedFiles(output: string): string[] {
+  return [
+    ...new Set(
+      output.split("\n").map((line) => line.trim()).filter(
+        Boolean,
+      ),
+    ),
+  ];
+}
+
 /**
  * Calculate the next version given all inputs.
  *
@@ -121,7 +226,7 @@ export function calculateVersion(opts: {
   currentVersion: string;
   /** Conventional commit subjects since last release. */
   subjects: string[];
-  /** Commit bodies (for Release-As detection). */
+  /** Commit bodies (for Release-As and BREAKING CHANGE detection). */
   bodies: string[];
   /** Whether this is a "push" (release) or "pull_request" (canary). */
   eventName: "push" | "pull_request";
@@ -151,8 +256,8 @@ export function calculateVersion(opts: {
     return { skip: false, version, tag } as const;
   }
 
-  // Analyze commits
-  let bump = analyzeCommits(opts.subjects);
+  // Analyze commits using subjects plus semantic-release style body footers.
+  let bump = analyzeCommits(opts.subjects, opts.bodies);
 
   // When no git tags, default to patch bump from npm baseline
   if (opts.noGitTags && bump === "none") {
@@ -185,45 +290,40 @@ export function calculateVersion(opts: {
 // CLI entry point
 // ---------------------------------------------------------------------------
 
-async function run(args: string[]): Promise<void> {
-  const cmd = async (...command: string[]): Promise<string> => {
-    const proc = new Deno.Command(command[0], {
-      args: command.slice(1),
-      stdout: "piped",
-      stderr: "piped",
-    });
-    const { stdout } = await proc.output();
-    return new TextDecoder().decode(stdout).trim();
-  };
-
+export async function run(
+  args: string[],
+  deps: VersionCliDeps = defaultVersionCliDeps,
+): Promise<void> {
+  const { cmd, readTextFile, envGet, appendFile, log, now } = deps;
   const output = (key: string, value: string): void => {
-    const ghOutput = Deno.env.get("GITHUB_OUTPUT");
+    const ghOutput = envGet("GITHUB_OUTPUT");
     if (ghOutput) {
-      Deno.writeTextFileSync(ghOutput, `${key}=${value}\n`, { append: true });
+      appendFile(ghOutput, `${key}=${value}\n`);
     }
-    console.log(`${key}=${value}`);
+    log(`${key}=${value}`);
   };
 
   // Read package name from deno.json or package.json
   let packageName = "unknown";
   for (const file of ["deno.json", "deno.jsonc", "package.json"]) {
     try {
-      const text = await Deno.readTextFile(file);
-      const json = JSON.parse(text);
-      if (json.name) {
-        packageName = json.name;
+      const text = await readTextFile(file);
+      const manifest = parsePackageManifest(text, file);
+      const manifestPackageName = getPackageNameFromManifest(manifest);
+      if (manifestPackageName) {
+        packageName = manifestPackageName;
         break;
       }
     } catch {
       continue;
     }
   }
 
-  const eventName = (Deno.env.get("GITHUB_EVENT_NAME") ?? args[0] ?? "push") as
+  const eventName = (envGet("GITHUB_EVENT_NAME") ?? args[0] ?? "push") as
     | "push"
     | "pull_request";
-  const commitSha = Deno.env.get("COMMIT_SHA") ??
-    Deno.env.get("GITHUB_SHA") ??
+  const commitSha = envGet("COMMIT_SHA") ??
+    envGet("GITHUB_SHA") ??
     args[1] ??
     await cmd("git", "rev-parse", "HEAD");
 
@@ -250,8 +350,9 @@ async function run(args: string[]): Promise<void> {
     currentVersion = npmVersion || "0.0.0";
     subjects = (await cmd("git", "log", "--format=%s")).split("\n");
     bodies = (await cmd("git", "log", "--format=%b")).split("\n");
-    changedFiles = (await cmd("git", "ls-tree", "-r", "--name-only", "HEAD"))
-      .split("\n");
+    changedFiles = parseChangedFiles(
+      await cmd("git", "log", "--format=", "--name-only"),
+    );
     noGitTags = true;
   } else {
     currentVersion = latestTag.replace(/^v/, "");
@@ -267,16 +368,18 @@ async function run(args: string[]): Promise<void> {
       `${latestTag}..HEAD`,
       "--format=%b",
     )).split("\n");
-    changedFiles = (await cmd(
-      "git",
-      "diff",
-      "--name-only",
-      `${latestTag}..HEAD`,
-    )).split("\n");
+    changedFiles = parseChangedFiles(
+      await cmd(
+        "git",
+        "diff",
+        "--name-only",
+        `${latestTag}..HEAD`,
+      ),
+    );
     noGitTags = false;
   }
 
-  const timestamp = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  const timestamp = now().toISOString().replace(/[-:T]/g, "").slice(0, 14);
 
   const result = calculateVersion({
     currentVersion,
@@ -291,13 +394,13 @@ async function run(args: string[]): Promise<void> {
 
   if (result.skip) {
     output("skip", "true");
-    console.log(
+    log(
       `No release-triggering commits since ${latestTag || "initial"}, skipping`,
     );
   } else {
     output("version", result.version);
     output("tag", result.tag);
-    console.log(
+    log(
       `${
         result.tag === "canary" ? "Canary" : "Release"
       } version: ${result.version}`,

.github/scripts/version.ts

@@ -42,27 +42,42 @@ jobs:
         with:
           node-version: 24
 
-      - name: Check if version exists
+      - name: Check if version exists on npm
         if: steps.version.outputs.skip != 'true'
-        id: check
+        id: npm
         run: |
           if npm view "opencode-graphiti@${{ steps.version.outputs.version }}" version 2>/dev/null; then
-            echo "skip=true" >> "$GITHUB_OUTPUT"
-            echo "Version ${{ steps.version.outputs.version }} already exists, skipping"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+            echo "Version ${{ steps.version.outputs.version }} already exists on npm, skipping publish"
           else
-            echo "skip=false" >> "$GITHUB_OUTPUT"
+            echo "publish=true" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Publish
-        if: steps.version.outputs.skip != 'true' && steps.check.outputs.skip != 'true'
+        if: steps.version.outputs.skip != 'true' && steps.npm.outputs.publish == 'true'
         working-directory: dist
         run: npm publish --provenance --access public --tag ${{ steps.version.outputs.tag }}
 
       - name: Tag and Release
-        if: github.event_name == 'push' && steps.version.outputs.skip != 'true' && steps.check.outputs.skip != 'true'
+        if: github.event_name == 'push' && steps.version.outputs.skip != 'true'
         run: |
-          git tag "v${{ steps.version.outputs.version }}"
-          git push origin "v${{ steps.version.outputs.version }}"
-          gh release create "v${{ steps.version.outputs.version }}" --generate-notes
+          set -euo pipefail
+          tag="v${{ steps.version.outputs.version }}"
+
+          if git show-ref --verify --quiet "refs/tags/$tag"; then
+            echo "Tag $tag already exists locally"
+          elif git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null 2>&1; then
+            git fetch --tags origin
+            echo "Tag $tag already exists on origin"
+          else
+            git tag "$tag"
+            git push origin "$tag"
+          fi
+
+          if gh release view "$tag" >/dev/null 2>&1; then
+            echo "Release $tag already exists"
+          else
+            gh release create "$tag" --generate-notes
+          fi
         env:
           GH_TOKEN: ${{ github.token }}

.github/workflows/publish.yml

@@ -1,5 +1,7 @@
 .opencode/
+.swarm/
 
 dist/
 
 node_modules/
+.worktrees/