@sporhq/spor 0.18.1 → 0.18.2

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "spor",
   "displayName": "Spor Context Compiler",
   "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "author": {
     "name": "losthammer"
   }

package/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "spor",
+  "version": "0.18.2",
+  "description": "Maintains a typed, versioned knowledge graph and compiles compact briefings from it: session-start injection, per-prompt relevance digests, capture at discovery, end-of-session distillation, decision queue.",
+  "author": {
+    "name": "Spor",
+    "url": "https://github.com/sporhq/spor"
+  },
+  "homepage": "https://sporhq.io",
+  "repository": "https://github.com/sporhq/spor",
+  "license": "Apache-2.0",
+  "keywords": [
+    "knowledge-graph",
+    "context",
+    "memory",
+    "agents",
+    "spor",
+    "provenance"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Spor Context Compiler",
+    "shortDescription": "Graph-backed briefings, captures, and queue triage for Codex.",
+    "longDescription": "Spor keeps durable project context in a typed knowledge graph, then helps Codex brief tasks, capture follow-up work, correct stale context, and work the decision queue.",
+    "developerName": "Spor",
+    "category": "Productivity",
+    "capabilities": [
+      "Knowledge graph",
+      "Task briefings",
+      "Queue triage"
+    ],
+    "websiteURL": "https://sporhq.io",
+    "defaultPrompt": [
+      "Brief this Spor task before I start work.",
+      "Capture this follow-up in the graph.",
+      "Show me what is next in the Spor queue."
+    ],
+    "brandColor": "#3B82F6"
+  }
+}

package/adapters/codex/README.md

@@ -7,7 +7,18 @@ is just a manifest over `bin/spor-hook.js`.
 ## Install
 
 1. Clone this repo somewhere stable, e.g. `~/tools/spor`.
-2. Resolve the path placeholder and install the manifest:
+2. Install the Codex plugin, hook manifest, and backfill custom agent:
+
+   ```sh
+   ~/tools/spor/bin/spor install codex
+   ```
+
+   This registers this checkout as the `spor` Codex marketplace, runs
+   `codex plugin add spor@spor`, resolves the hook path placeholder, and keeps
+   the custom agent sourced from `agents/backfill.md`.
+
+3. Manual hook-only install, if you are debugging the adapter without the Codex
+   plugin:
 
    ```sh
    SPOR_ROOT=~/tools/spor
@@ -18,7 +29,8 @@ is just a manifest over `bin/spor-hook.js`.
    (Or merge into an existing `~/.codex/hooks.json` / `[hooks]` table in
    `~/.codex/config.toml`. Per-repo installs go in `<repo>/.codex/hooks.json`.)
 
-3. Add the backfill custom agent:
+4. Add the backfill custom agent manually, only if you skipped
+   `spor install codex`:
 
    ```sh
    mkdir -p ~/.codex/agents
@@ -31,27 +43,20 @@ is just a manifest over `bin/spor-hook.js`.
    } > ~/.codex/agents/spor-backfill.toml
    ```
 
-   `spor install codex` performs both steps automatically and keeps the custom
-   agent sourced from `agents/backfill.md`.
-
-4. Approve the hooks in Codex's `/hooks` trust prompt on first run.
-5. Environment (the same variables on every host):
+5. Approve the hooks in Codex's `/hooks` trust prompt on first run.
+6. Environment (the same variables on every host):
 
    ```sh
    export SPOR_SERVER=https://spor.example.com   # remote mode
    export SPOR_TOKEN=spor_pat_...
-   # Distiller backend — Codex hosts usually won't have the claude CLI.
-   # Contract: prompt on stdin, response on stdout.
-   export SPOR_DISTILL_CMD='codex exec -'
-   # Capture-nudge backend — same contract, but it runs synchronously in the
-   # tool loop, so prefer a fast model. SPOR_NUDGE=0 disables it.
-   export SPOR_NUDGE_CMD='codex exec -'
+   # Capture-nudge defaults to `codex exec --model gpt-5.4-mini -`; distill
+   # defaults to `codex exec -`. Set SPOR_NUDGE_CMD / SPOR_DISTILL_CMD only to
+   # override those defaults; SPOR_NUDGE=0 disables the nudge.
    ```
 
-   (Legacy `SUBSTRATE_*` names are still read.) Without `SPOR_DISTILL_CMD` /
-   `SPOR_NUDGE_CMD` both default to `claude -p --model haiku`, which is fine if
-   the claude CLI is installed. See [adapters/README.md](../README.md) for the
-   nudge bounds (`SPOR_NUDGE_MAX`, `SPOR_NUDGE_TIMEOUT`).
+   (Legacy `SUBSTRATE_*` names are still read.) See
+   [adapters/README.md](../README.md) for the nudge bounds (`SPOR_NUDGE_MAX`,
+   `SPOR_NUDGE_TIMEOUT`).
 
 ## Event mapping
 

package/bin/spor-hook.js

@@ -153,7 +153,7 @@ async function main() {
   // `enabled:false` / `mode:off` makes every hook a no-op (exit 0, no output)
   // so an unrelated side project doesn't pollute the shared graph neighborhood;
   // default-enabled, so a repo without config is byte-identical to before.
-  const cfg = u.useConfig({ cwd: payload.cwd || process.cwd() });
+  const cfg = u.useConfig({ cwd: payload.cwd || process.cwd(), host });
   if (cfg.warnings.length) {
     try {
       const log = u.makeLogger(path.join(u.graphHome(), "journal", "remote.log"), "config: ");

package/bin/spor.js

@@ -4870,7 +4870,7 @@ function cmdLink(cfg, { positionals }) {
 const HOSTS = {
   claude: { kind: "claude", label: "Claude Code" },
   codex: {
-    kind: "hooks",
+    kind: "codex",
     label: "Codex CLI",
     src: ["adapters", "codex", "hooks.json"],
     user: [".codex", "hooks.json"],
@@ -4907,6 +4907,12 @@ function claudeCmd() {
   return process.env.SPOR_CLAUDE_CMD || "claude";
 }
 
+// The Codex CLI binary, overridable for tests. Codex owns plugin install state,
+// so all plugin shell-outs route through this seam instead of writing its cache.
+function codexCmd() {
+  return process.env.SPOR_CODEX_CMD || "codex";
+}
+
 function spawnPortableSync(cmd, args, opts = {}) {
   if (process.platform !== "win32" || opts.shell) return spawnSync(cmd, args, opts);
   const resolved = u.whichSync(cmd) || cmd;
@@ -5264,6 +5270,37 @@ function installClaude(scope, dryRun) {
   return 0;
 }
 
+// Codex CLI: install the repo as a Codex plugin via its marketplace commands,
+// then keep the hook manifest + backfill custom agent installed. The plugin
+// manifest intentionally does not carry hooks (Codex plugin validation rejects
+// that field), so both halves matter.
+function installCodex(scope, dryRun) {
+  const cmd = codexCmd();
+  const mpArgs = ["plugin", "marketplace", "add", ROOT];
+  const pluginArgs = ["plugin", "add", "spor@spor"];
+  if (dryRun) {
+    out(`would run: ${cmd} ${mpArgs.join(" ")}`);
+    out(`would run: ${cmd} ${pluginArgs.join(" ")}`);
+    return installHookHost(HOSTS.codex, scope, true);
+  }
+  if (cmd === "codex" && !hasCmd("codex")) {
+    err("codex CLI not on PATH — install Codex, then re-run 'spor install codex'.");
+    return 1;
+  }
+  const mp = spawnPortableSync(cmd, mpArgs, { encoding: "utf8" });
+  if (mp.status !== 0 && !/already|exists|known/i.test((mp.stderr || "") + (mp.stdout || ""))) {
+    err(`codex plugin marketplace add failed: ${(mp.stderr || mp.stdout || "").trim() || "unknown error"}`);
+    return 1;
+  }
+  const plugin = spawnPortableSync(cmd, pluginArgs, { stdio: "inherit" });
+  if (plugin.status !== 0) {
+    err(`codex plugin add failed (exit ${plugin.status == null ? "?" : plugin.status})`);
+    return 1;
+  }
+  out("installed spor@spor into Codex.");
+  return installHookHost(HOSTS.codex, scope, false);
+}
+
 // JSON-hook hosts (codex/cursor/copilot/gemini): render + merge into the target.
 function installHookHost(spec, scope, dryRun) {
   const target = targetPath(spec, scope);
@@ -5366,6 +5403,7 @@ async function cmdInstall(cfg, { values, positionals: pos }) {
     const spec = HOSTS[host];
     let r;
     if (spec.kind === "claude") r = installClaude(scope, dryRun);
+    else if (spec.kind === "codex") r = installCodex(scope, dryRun);
     else if (spec.kind === "plugin") r = installPluginHost(spec, scope, dryRun);
     else r = installHookHost(spec, scope, dryRun);
     if (r !== 0) rc = r;
@@ -5386,10 +5424,12 @@ async function cmdInstall(cfg, { values, positionals: pos }) {
 // (issue-spor-upgrade-no-plugin-refresh) An npm bump updates the package on disk
 // but NOT what an agent already loaded: Claude Code runs its OWN cached copy of
 // the plugin, so it keeps running stale skills/hooks until 'plugin update' swaps
-// the copy. The hook hosts (codex/cursor/copilot/gemini/opencode) reference the
-// package by absolute path, so they only go stale if the checkout MOVED — for
-// which re-running the idempotent install refreshes the path. This verb does
-// both in one step and tells the user to restart the session.
+// the copy. Codex also caches an installed plugin copy, while its hooks still
+// reference this checkout by absolute path. Re-running the idempotent install
+// refreshes Codex's marketplace/plugin cache and rewrites the hook path. The
+// other hook hosts reference the package by absolute path, so they only go stale
+// if the checkout MOVED. This verb does both in one step and tells the user to
+// restart the session.
 
 // Refresh Claude Code's loaded plugin (marketplace add to register/repoint the
 // source, then the shared marketplace+plugin update). Returns 0/1.
@@ -5466,6 +5506,7 @@ async function cmdUpgrade(cfg, { values, positionals: pos }) {
   for (const host of hosts) {
     let r;
     if (host === "claude") r = upgradeClaude(scope, dryRun);
+    else if (host === "codex") r = installCodex(scope, dryRun);
     else {
       // Re-running install refreshes the absolute __SPOR_ROOT__ path (a no-op
       // when the path is unchanged; repairs a moved checkout when it is not).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporhq/spor",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "Spor — a shared memory substrate for teams and agents. Decisions, their reasons, and the traces they leave. Knowledge-graph context compiler: session-start briefings, per-prompt digests, capture at discovery, end-of-session distillation, decision queue.",
   "license": "Apache-2.0",
   "author": "Anthony Allen",
@@ -27,6 +27,7 @@
   },
   "files": [
     ".claude-plugin/",
+    ".codex-plugin/",
     "lib/",
     "bin/",
     "scripts/engines/",

package/scripts/engines/distill.js

@@ -252,7 +252,7 @@ async function distill(input) {
   // runs async on SessionEnd, so it tolerates more than the nudge, but a wedged
   // CLI should still not hang the SessionEnd hook indefinitely).
   const timeoutMs = u.cfgNum("distill.timeoutMs", "DISTILL_TIMEOUT", 120000);
-  const distillCmd = u.cfgStr("distill.cmd", "DISTILL_CMD");
+  const distillCmd = u.cfgStr("distill.cmd", "DISTILL_CMD") || u.hostDefaultBackendCmd("distill");
   if (distillCmd) {
     backend = `cmd:${distillCmd}`;
     response = u.runBackendCmd(distillCmd, prompt, { timeoutMs });

package/scripts/engines/post-tool.js

@@ -181,7 +181,7 @@ async function nudge({ input, graph, slug, session, file, remote }) {
   // PostToolUse budget (nudge.timeoutMs / SPOR_NUDGE_TIMEOUT, default 30s — room
   // for a ~17s claude -p haiku cold boot, well under the host's 60s).
   const timeoutMs = u.cfgNum("nudge.timeoutMs", "NUDGE_TIMEOUT", 30000);
-  const nudgeCmd = u.cfgStr("nudge.cmd", "NUDGE_CMD");
+  const nudgeCmd = u.cfgStr("nudge.cmd", "NUDGE_CMD") || u.hostDefaultBackendCmd("nudge");
   if (nudgeCmd) {
     backend = `cmd:${nudgeCmd}`;
     response = u.runBackendCmd(nudgeCmd, prompt, { timeoutMs });

package/scripts/engines/util.js

@@ -11,6 +11,7 @@ const crypto = require("crypto");
 const { execFileSync, spawnSync, spawn } = require("child_process");
 
 const ROOT = path.resolve(__dirname, "..", "..");
+const CODEX_NUDGE_MODEL = "gpt-5.4-mini";
 
 const home = require(path.join(ROOT, "lib", "shell", "home.js"));
 // The harness vocabulary the capability probe emits — owned by the pure matcher
@@ -25,7 +26,9 @@ const { HARNESS_BINARIES, SPOR_MCP_NAME } = require(path.join(ROOT, "lib", "kern
 // falls back to the exact env dual-read it replaced, so those paths stay
 // byte-identical (norm-cc-byte-identical-refactor).
 let _config = null;
+let _host = null;
 function useConfig(opts) {
+  _host = opts && opts.host ? opts.host : null;
   _config = require(path.join(ROOT, "lib", "config.js")).loadConfig(opts);
   return _config;
 }
@@ -35,6 +38,7 @@ function useConfig(opts) {
 // (serverBase/bearer/graphHome) honors a file-config or --org tenant instead of
 // silently falling back to raw env.
 function setConfig(cfg) {
+  _host = null;
   _config = cfg;
   return cfg;
 }
@@ -42,6 +46,7 @@ function config() {
   return _config;
 }
 function clearConfig() {
+  _host = null;
   _config = null; // test hook
 }
 // Config-aware string read: the active cascade value, else env dual-read.
@@ -61,6 +66,12 @@ function cfgNum(keyPath, envName, fallback) {
   return Number.isFinite(n) ? n : fallback;
 }
 
+function hostDefaultBackendCmd(kind) {
+  if (_host === "codex" && kind === "nudge") return `codex exec --model ${CODEX_NUDGE_MODEL} -`;
+  if (_host === "codex" && kind === "distill") return "codex exec -";
+  return undefined;
+}
+
 function graphHome() {
   return _config ? _config.graphHome() : home.graphHome();
 }
@@ -1068,6 +1079,7 @@ module.exports = {
   clearConfig,
   cfgStr,
   cfgNum,
+  hostDefaultBackendCmd,
   jqNow,
   isoMs,
   isoSeconds,

package/skills/spor/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: spor
-description: The operating manual for Spor — a knowledge-graph tool your training does not cover. Load it before any Spor graph operation so you use the right CLI syntax, node and edge format, MCP tools, and REST API instead of rediscovering them: querying or searching the graph, reading or writing nodes, adding edges, capturing or deferring work, running spor CLI commands or Spor MCP tools, working in local vs remote mode, or defining a new node/edge type or schema. It also routes you to the right /spor action skill (defer, brief, next, correct, ask, backfill) for a specific operation, and explains the node/edge mental model when you need it. For FIRST-TIME setup — installing, creating an identity, joining a team graph, or "spor isn't doing anything" — use /spor:onboard instead. When unsure how to operate Spor, consult this before guessing.
+description: >
+  The operating manual for Spor — a knowledge-graph tool your training does not
+  cover. Load it before any Spor graph operation so you use the right CLI
+  syntax, node and edge format, MCP tools, and REST API instead of rediscovering
+  them: querying or searching the graph, reading or writing nodes, adding edges,
+  capturing or deferring work, running spor CLI commands or Spor MCP tools,
+  working in local vs remote mode, or defining a new node/edge type or schema.
+  It also routes you to the right /spor action skill (defer, brief, next,
+  correct, ask, backfill) for a specific operation, and explains the node/edge
+  mental model when you need it. For FIRST-TIME setup — installing, creating an
+  identity, joining a team graph, or "spor isn't doing anything" — use
+  /spor:onboard instead. When unsure how to operate Spor, consult this before
+  guessing.
 ---
 
 # Operate Spor