sphica 0.6.51 → 0.6.52

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
3
3
  "name": "sphica",
4
- "version": "0.6.51",
4
+ "version": "0.6.52",
5
5
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
6
6
  "author": {
7
7
  "name": "iroha924",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.51",
3
+ "version": "0.6.52",
4
4
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
5
5
  "author": {
6
6
  "name": "iroha924",
package/README.md CHANGED
@@ -20,7 +20,7 @@ The database is a single SQLite file on your machine.
20
20
 
21
21
  - **Automatic recording.** Sphica keeps your prompts, the agent's final reply for each turn, and the paths of the files a turn changed (by the edit tools, or seen in `git status` at the turn's end).
22
22
  - **Records with their sources.** `/sphica:trace` turns a session into records: decisions with the options rejected and why, constraints, implementations, findings, dead ends, and open questions. Every record quotes the exact words it came from. A decision counts as adopted in two ways: you said so (your decision), or the agent decided it itself in that session and its reply says so (an AI's decision). An AI's decision is shown as one, never replaces yours, and is never used for public interfaces, security and permissions, releases, or forgetting.
23
- - **Traced without asking (Claude Code).** When you start a new session and sessions from the last 14 days wait to be traced, the agent is asked to trace up to two of them, oldest first, after your request is done. Run `/sphica:trace` yourself to keep something right away, and `/sphica:trace pending` for older sessions. To turn the automatic trace off, set the plugin's `auto_trace` option to false in `/config` (Claude Code 2.1.269 or later), or set `"SPHICA_AUTO_TRACE": "off"` under `env` in Claude Code's `settings.json`; recording and your own `/sphica:trace` keep working. Either one off keeps it off, so to turn it back on, clear both.
23
+ - **Traced without asking.** When you start a new session (an interactive one in Claude Code; one started from the terminal in Codex) and sessions from the last 14 days wait to be traced, the agent is asked to trace up to two of them, oldest first, after your request is done. Run `/sphica:trace` yourself to keep something right away, and `/sphica:trace pending` for older sessions. To turn the automatic trace off, set the plugin's `auto_trace` option to false in `/config` (Claude Code 2.1.269 or later), or set `"SPHICA_AUTO_TRACE": "off"` under `env` in Claude Code's `settings.json`; recording and your own `/sphica:trace` keep working. Either one off keeps it off, so to turn it back on, clear both. In Codex, set `SPHICA_AUTO_TRACE` to `off` in the environment Codex's background server starts with (see "What Sphica can't do yet" for when a value takes effect).
24
24
  - **Pull requests too.** `/sphica:harvest <number>` keeps a GitHub pull request (body, comments, reviews, review comments, commits, and up to five issues the body says it closes) and records what it decided. A reviewer's suggestion stays a proposal unless the owner or a maintainer adopted it; a merge alone adopts nothing.
25
25
  - **Evidence found later.** `/sphica:glean` adds evidence and corrections to existing records. It asks you for the source (an issue URL, the file and line, meeting notes) before saving; a claim without one is kept only as unsourced and never used as fact.
26
26
  - **Forget what should not have been kept.** `/sphica:forget` removes the messages, pull request items, or file excerpts you pick, with their search entries and the bytes left in the database file, after you confirm in a dialog (if another session is reading the database, it asks you to run it again to finish clearing the bytes). Records that cited them are judged again and leave active when nothing else supports them; a record's own text stays as it was.
@@ -96,7 +96,7 @@ sphica doctor
96
96
 
97
97
  Only sessions in repositories you register (projects) go into Sphica's database; run `sphica init` in each one.
98
98
 
99
- Work as usual. In Claude Code, a new session asks the agent to trace earlier sessions on its own. To keep something right away, or in Codex, run `/sphica:trace` (`$sphica:trace` in Codex).
99
+ Work as usual. A new session asks the agent to trace earlier sessions on its own (in Codex, a session started from the terminal). To keep something right away, run `/sphica:trace` (`$sphica:trace` in Codex).
100
100
  `/sphica:trace pending` lists earlier sessions not traced yet. To keep what a pull request decided, run `/sphica:harvest 123`.
101
101
  When you find evidence later ("the ops notes say…", "Kimura said the team agreed"), run `/sphica:glean` with what you found.
102
102
 
@@ -110,7 +110,7 @@ To bring back earlier decisions, ask the agent:
110
110
 
111
111
  Without being asked, Sphica adds a few past records to what the agent sees, each marked as a past record rather than an instruction:
112
112
 
113
- - At session start: the current work and project-wide constraints, and in Claude Code, when earlier sessions wait to be traced, a request to trace them after your request is done.
113
+ - At session start: the current work and project-wide constraints, and, when earlier sessions wait to be traced, a request to trace them after your request is done (in a new interactive Claude Code session, or a new Codex session started from the terminal).
114
114
  - On a prompt that names a recorded code symbol, file path, or option.
115
115
  - Before the agent reads or edits a file a decision applies to, and before a shell command that names such a file (naming it is not proof the command reads it). A read shows each record once per session.
116
116
  - After a shell command that changed the content of such a file, when the `shell_write_delivery` option is on (off by default): the decisions on it the agent has not seen in this conversation.
@@ -147,7 +147,9 @@ The agent searches with Sphica's `search` and opens full records with `read`. `s
147
147
  - In Codex, `$sphica:trace`, `$sphica:harvest`, and `$sphica:glean` can write only when Codex tells Sphica which directory the session is in. Current Codex does. When it does not, they write nothing and tell you why.
148
148
  - Showing a record does not make the agent follow it.
149
149
  - Whether the agent decided something itself is judged from what its reply says, so it can be wrong.
150
- - An AI's decision is adopted only when the trace runs in an interactive Claude Code session. In headless and SDK runs and in Codex it stays a candidate. The automatic trace also runs only in Claude Code; Codex tells you when sessions wait.
150
+ - An AI's decision is adopted only when the trace runs in an interactive session: Claude Code's terminal, or a Codex turn a person started in the session's own thread. For Codex, Sphica reads what Codex reports with each tool call; this was measured with Codex's terminal, and another Codex client that reports the same is treated alike. In headless and SDK runs, `codex exec`, and a Codex child thread it stays a candidate, and once a Codex child thread has called one of Sphica's record tools, no reply of that session is adopted.
151
+ - The automatic trace is a request the agent may skip. In Codex it goes only to new sessions started from the terminal; in other Codex clients and in `codex exec`, Codex tells you when sessions wait.
152
+ - In Codex, Sphica's settings are environment variables (`SPHICA_AUTO_TRACE`, `SPHICA_SHELL_WRITE_DELIVERY`; Codex plugins have no options page). In a session that runs through Codex's background server (the terminal does by default), Sphica's hooks see the environment that server started with, not the terminal you open later: a value you set afterwards takes effect the next time the server starts (`codex app-server daemon restart` starts it again; work running in Codex may be interrupted). `codex exec` does not use that server, so its hooks see the environment it was started from. A background server started from inside an agent's shell (for example `! codex` in Claude Code) keeps that agent's variables too: Sphica then takes every session that runs through it for that agent's child and records nothing until the server starts again.
151
153
  - When Sphica cannot tell which turn ran one of its record tools, every reply Claude Code's agent writes in that project from then on stays a candidate. If the hook only timed out, it keeps what it saw and the next recording sends it; from then on, replies of other turns can be adopted again (when the hook knew the turn), while the turn that ran the tool stays out. If the hook was turned off, the host sent no tool call id, or the call came before Sphica was installed, nothing can be sent later and the stop stays for good. Records already saved as candidates are not adopted afterwards. `sphica doctor` lists the calls behind a stop and since when. Your decisions are not affected.
152
154
  - The automatic trace uses your subscription's usage.
153
155
  - The agent never withdraws an AI's decision. When a later record contradicts it, the AI's decision is held back from being shown until you settle it, and so is the later record unless it is your decision.
package/dist/deliver.js CHANGED
@@ -4,6 +4,7 @@
4
4
  import fs9 from "node:fs";
5
5
  import os3 from "node:os";
6
6
  import path10 from "node:path";
7
+ import { fileURLToPath as fileURLToPath2 } from "node:url";
7
8
 
8
9
  // server/node_modules/kysely/dist/util/object-utils.js
9
10
  function isUndefined(obj) {
@@ -13820,7 +13821,37 @@ function rotateTrial(dir2, file) {
13820
13821
  } catch {}
13821
13822
  }
13822
13823
  var AUTO_TRACE_OFF = new Set(["off", "0", "false", "no"]);
13823
- var AUTO_TRACE = (n) => `- ${n} earlier session${n === 1 ? "" : "s"} of this project ${n === 1 ? "waits" : "wait"} to be traced. After the user's request is done, run the trace Skill on your own for the oldest (at most 2), as its "On your own" section says, without asking the user.`;
13824
+ var AUTO_TRACE = (n, skill) => `- ${n} earlier session${n === 1 ? "" : "s"} of this project ${n === 1 ? "waits" : "wait"} to be traced. After the user's request is done, ${skill ? `read \`${skill}\` and run it` : "run the trace Skill"} on your own for the oldest (at most 2), as its "On your own" section says, without asking the user.`;
13825
+ var SESSION_META_BYTES = 256 * 1024;
13826
+ function codexInteractive(input) {
13827
+ const file = input.transcript_path;
13828
+ if (!input.session_id || typeof file !== "string" || !path10.isAbsolute(file))
13829
+ return false;
13830
+ let fd;
13831
+ try {
13832
+ if (!fs9.lstatSync(file).isFile())
13833
+ return false;
13834
+ fd = fs9.openSync(file, "r");
13835
+ const buffer = Buffer.alloc(SESSION_META_BYTES);
13836
+ const read = fs9.readSync(fd, buffer, 0, SESSION_META_BYTES, 0);
13837
+ const end = buffer.subarray(0, read).indexOf(10);
13838
+ if (end < 0)
13839
+ return false;
13840
+ const line2 = JSON.parse(buffer.subarray(0, end).toString("utf8"));
13841
+ const payload = line2?.payload;
13842
+ return line2?.type === "session_meta" && payload?.id === input.session_id && payload.originator === "codex-tui" && payload.thread_source === "user";
13843
+ } catch {
13844
+ return false;
13845
+ } finally {
13846
+ if (fd !== undefined)
13847
+ fs9.closeSync(fd);
13848
+ }
13849
+ }
13850
+ var namable = (file) => Buffer.byteLength(file) <= 1000 && !/[\p{Cc}`]/u.test(file) ? file : null;
13851
+ function traceSkill(here2 = path10.dirname(fileURLToPath2(import.meta.url))) {
13852
+ const file = [path10.join(here2, ".."), path10.join(here2, "..", "..", "plugin")].map((root) => path10.join(root, "skills", "trace", "SKILL.md")).find((f) => fs9.existsSync(f));
13853
+ return file ? namable(file) : null;
13854
+ }
13824
13855
  async function waiting(db, projectId2, place) {
13825
13856
  if (!place.owner)
13826
13857
  return "";
@@ -13833,7 +13864,7 @@ async function waiting(db, projectId2, place) {
13833
13864
  return "";
13834
13865
  if (!markOnce("auto-trace", `${path10.resolve(place.file)}\x00${place.key}\x00${place.host}\x00${place.auto}`))
13835
13866
  return "";
13836
- return AUTO_TRACE(total);
13867
+ return AUTO_TRACE(total, place.skill);
13837
13868
  }
13838
13869
  const n = (await pendingCount(db, projectId2)).recent;
13839
13870
  if (!n)
@@ -14123,13 +14154,17 @@ async function deliver(input, host = "claude-code", file = dbFile()) {
14123
14154
  }
14124
14155
  const reader = db;
14125
14156
  const session = input.session_id;
14157
+ const asksToTrace = name === "SessionStart" && input.source === "startup" && ![process.env.CLAUDE_PLUGIN_OPTION_AUTO_TRACE, process.env.SPHICA_AUTO_TRACE].some((v) => AUTO_TRACE_OFF.has((v ?? "").trim().toLowerCase()));
14158
+ const skill = asksToTrace && host === "codex" && codexInteractive(input) ? traceSkill() : null;
14159
+ const newInteractive = asksToTrace && (host === "claude-code" ? process.env.CLAUDE_CODE_ENTRYPOINT === "cli" : skill !== null);
14126
14160
  const make = async () => event === "pre_edit" ? await beforeEdit(reader, pid, rels) : event === "pre_read" ? await beforeRead(reader, pid, rels, sessionId(pid, host, session), agentOf(input), shell ? "named" : "reading") : event === "prompt" ? await onPrompt(reader, pid, place.root, input.prompt ?? "") : call ? await beforeReview(reader, pid, place.root, call) : {
14127
14161
  ...await atStart(reader, pid, branchOf(place.root), {
14128
14162
  file,
14129
14163
  key: place.key,
14130
14164
  host,
14131
14165
  subagent: name === "SubagentStart",
14132
- auto: host === "claude-code" && name === "SessionStart" && input.source === "startup" && process.env.CLAUDE_CODE_ENTRYPOINT === "cli" && ![process.env.CLAUDE_PLUGIN_OPTION_AUTO_TRACE, process.env.SPHICA_AUTO_TRACE].some((v) => AUTO_TRACE_OFF.has((v ?? "").trim().toLowerCase())) ? session : null,
14166
+ auto: newInteractive ? session : null,
14167
+ ...skill ? { skill } : {},
14133
14168
  owner: name !== "SubagentStart" && isOwnerTurn(input, undefined, undefined, host === "codex" ? process.env.CODEX_THREAD_ID : undefined)
14134
14169
  }),
14135
14170
  reason: name === "SubagentStart" ? "subagent" : input.source && START_SOURCES.has(input.source) ? input.source : null
@@ -14178,10 +14213,13 @@ export {
14178
14213
  CONFIRM,
14179
14214
  CONFIRM_GOLD,
14180
14215
  anchoredRules,
14216
+ codexInteractive,
14181
14217
  deliver,
14182
14218
  deliverableIds,
14183
14219
  deliverablePaths,
14184
14220
  leadFor,
14221
+ namable,
14185
14222
  namedRecords,
14186
- recordLines
14223
+ recordLines,
14224
+ traceSkill
14187
14225
  };
@@ -34726,14 +34726,17 @@ var record3 = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ?
34726
34726
  function callerOf(meta3, env = process.env) {
34727
34727
  const codex = record3(record3(meta3)?.["x-codex-turn-metadata"]);
34728
34728
  if (codex) {
34729
+ const session2 = text(codex.session_id);
34730
+ const source = text(codex.thread_source);
34729
34731
  const trigger = text(codex.turn_trigger);
34732
+ const own2 = session2 !== null && session2 === text(codex.thread_id) && source === "user";
34730
34733
  return {
34731
34734
  host: "codex",
34732
- session: text(codex.session_id),
34733
- turn: text(codex.turn_id),
34735
+ session: session2,
34736
+ turn: own2 ? text(codex.turn_id) : null,
34734
34737
  toolUseId: null,
34735
- mode: trigger === "exec" ? "headless" : "unknown",
34736
- raw: trigger
34738
+ mode: trigger === "exec" ? "headless" : own2 && trigger === "user" ? "interactive" : "unknown",
34739
+ raw: own2 || trigger === null && source === null ? trigger : text(`${trigger ?? "none"}:${source ?? "none"}`)
34737
34740
  };
34738
34741
  }
34739
34742
  const toolUseId = text(record3(meta3)?.["claudecode/toolUseId"]);
@@ -51358,7 +51361,8 @@ async function projectOf(cwd, meta3) {
51358
51361
  }
51359
51362
  async function called(name, cwd, meta3) {
51360
51363
  const p = await projectOf(cwd, meta3);
51361
- return { p, call: await logCall(conn(), p.projectId, name, callerOf(meta3)) };
51364
+ const by = callerOf(meta3);
51365
+ return { p, by, call: await logCall(conn(), p.projectId, name, by) };
51362
51366
  }
51363
51367
  var tool = (fn) => fn().then((t) => reply(t), (e) => reply(e instanceof RecordRefused ? e.message : `Sphica: ${head(reason(e), 2000)}`, true));
51364
51368
  var server = new McpServer({ name: "sphica-record", version: versionAt(ROOT) ?? "unknown" }, {
@@ -51382,7 +51386,9 @@ server.registerTool("trace_pending", {
51382
51386
  inputSchema: exports_external.object({ auto: AUTO, cwd: CWD }).strict(),
51383
51387
  annotations: READ
51384
51388
  }, async (a, extra) => tool(async () => {
51385
- const { p, call } = await called("trace_pending", a.cwd, extra._meta);
51389
+ const { p, by, call } = await called("trace_pending", a.cwd, extra._meta);
51390
+ if (a.auto && by.host === "codex" && by.mode !== "interactive")
51391
+ return "Sphica did not see a person start this Codex turn in the session's own thread (a child thread, codex exec, or a client it does not know), so the automatic trace does nothing this time.";
51386
51392
  const skip = a.auto ? await callSession(conn(), call) : undefined;
51387
51393
  return pendingText(conn(), p.projectId, undefined, { auto: a.auto, skip });
51388
51394
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sphica",
3
- "version": "0.6.51",
3
+ "version": "0.6.52",
4
4
  "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -58,10 +58,11 @@ A session with nothing worth keeping is saved with `"units": []`: it is marked a
58
58
 
59
59
  ## On your own
60
60
 
61
- When Sphica's session-start notice in Claude Code says earlier sessions wait to be traced, run this after the user's request is done, without asking them. Codex does not start this Skill on its own yet: there it runs only when the user asks.
61
+ When Sphica's session-start notice says earlier sessions wait to be traced, run this after the user's request is done, without asking them. The notice comes in a new interactive Claude Code session, and in a new Codex session started from the terminal, where it names this file (Codex otherwise starts this Skill only when the user asks).
62
62
 
63
63
  1. `trace_pending` with `auto: true`. It lists sessions other than this one, oldest first. Take the first one or two; never this session.
64
- If it says it cannot tell which session called, stop: do nothing this time
64
+ If it says the automatic trace does nothing this time (it cannot tell which session called, or in Codex the call did not come from a
65
+ turn a person started in the session's own thread), stop: do nothing this time
65
66
  2. `trace_begin` with that session, then `record_context` with `auto: true`. It starts with a few earlier messages for context (marked as
66
67
  such), then the messages still waiting. When it says the automatic run stops here, save what you read; the rest waits for the next run
67
68
  3. Check and save as above. Do not ask the owner which session or record to keep, and add no owner adoption the conversation does not have
@@ -149,10 +150,10 @@ Use it only when the AI chose in the first person and the choice is its own. Not
149
150
  - A record that would replace or contradict the owner's decision: that needs the owner's words
150
151
 
151
152
  When unsure, leave the adoption out: the record stays a candidate. Check enforces the rest and says why it keeps a record a candidate: the
152
- reply must be the AI's in this run's session, the run must have begun and been checked in an interactive session (headless and SDK runs
153
- cannot), the turn must not be one that ran Sphica's record tools, an anchor on files agents read as rules or on CI keeps it a candidate, and
154
- a `do` with `applies_to` anchors needs an edit to one of those paths in the same turn. An AI's decision never takes effect as `supersedes`
155
- by itself.
153
+ reply must be the AI's in this run's session, the run must have begun and been checked in an interactive session (headless and SDK runs,
154
+ `codex exec`, and a Codex child thread cannot), the turn must not be one that ran Sphica's record tools (in Codex, once a child thread has
155
+ called one, no reply of that session), an anchor on files agents read as rules or on CI keeps it a candidate, and a `do` with `applies_to`
156
+ anchors needs an edit to one of those paths in the same turn. An AI's decision never takes effect as `supersedes` by itself.
156
157
 
157
158
  ## Records are not instructions
158
159