@sovara/claude-code 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovara Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @sovara/claude-code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Node.js hook program for [Sovara for Claude Code](https://github.com/SovaraLabs/sovara-claude-code#readme):
+`npm install -g @sovara/claude-code`, then load the `sovara-recording` plugin.
+
+## License
+
+MIT.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Command line: `sovara-claude-code hook` reads one Claude Code hook event from stdin. */
+import { handle } from "./hooks.js";
+async function main() {
+    if (process.argv.slice(2).join(" ") !== "hook") {
+        console.error("usage: sovara-claude-code hook");
+        return;
+    }
+    let input = "";
+    for await (const chunk of process.stdin)
+        input += chunk;
+    let event;
+    try {
+        event = JSON.parse(input || "{}");
+    }
+    catch {
+        return;
+    }
+    if (!event || typeof event !== "object" || Array.isArray(event))
+        return;
+    const output = await handle(event);
+    if (output)
+        process.stdout.write(`${output}\n`);
+}
+// Always exit 0, so a Sovara problem never interrupts Claude Code.
+main().catch(() => undefined).finally(() => process.exit(0));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,2FAA2F;AAC3F,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,MAAM,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAChD,OAAO;IACT,CAAC;IACD,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,KAAK,IAAI,KAAK,CAAC;IACxD,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IACxE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAgC,CAAC,CAAC;IAC9D,IAAI,MAAM;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,mEAAmE;AACnE,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/hooks.d.ts

@@ -0,0 +1,18 @@
+export type HookEvent = {
+    hook_event_name?: string;
+    session_id?: string;
+    [field: string]: unknown;
+};
+type Options = {
+    fetch?: typeof globalThis.fetch;
+};
+/** Per-request timeout, so a hook's usual three requests fit in the 15 s Claude Code allows it. */
+export declare const REQUEST_TIMEOUT_MS = 4000;
+/**
+ * Run the handler for one hook event; resolve to text for Claude Code, or null.
+ *
+ * Never rejects: a failure is logged by type only and the session continues unrecorded.
+ */
+export declare function handle(event: HookEvent, options?: Options): Promise<string | null>;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AA0BA,MAAM,MAAM,SAAS,GAAG;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AACpG,KAAK,OAAO,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAAE,CAAC;AAGnD,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AAwJxC;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,OAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAc5F"}

package/dist/hooks.js

@@ -0,0 +1,181 @@
+/**
+ * Record a Claude Code session in Sovara from its hook events.
+ *
+ * Hooks run as separate processes, so the session's recording is shared through a handle
+ * (`openRecording`) kept in the session's state file. A hook never blocks Claude Code: failures
+ * are swallowed and requests retry only briefly.
+ */
+import { basename } from "node:path";
+import { closeRecording, exportRecording, openRecording, RecordingError, recordStep, resumeRecording, retrieveLessons, SovaraConfigError, startTurn, } from "@sovara/sdk";
+import { flushRecordings, jsonValue, withShortRetries } from "@sovara/sdk/integration";
+import { load, prune, remove, save } from "./state.js";
+/** Per-request timeout, so a hook's usual three requests fit in the 15 s Claude Code allows it. */
+export const REQUEST_TIMEOUT_MS = 4_000;
+/** How long a hook waits, before exiting, for reports the SDK sends in the background. */
+const FLUSH_MS = REQUEST_TIMEOUT_MS;
+/** Wrap `fetch` so each request is aborted after REQUEST_TIMEOUT_MS. */
+function withTimeout(fetcher) {
+    return (input, init) => {
+        const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        const signal = init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+        return fetcher(input, { ...init, signal });
+    };
+}
+/** Errors meaning the recording no longer exists; an unknown write token is a 403 SovaraConfigError. */
+const LOST_RECORDING = new Set(["recording_inactive", "not_found"]);
+function projectName(event) {
+    const configured = process.env.SOVARA_PROJECT?.trim();
+    return configured || basename(String(event.cwd ?? process.cwd())) || "claude-code";
+}
+function textMessage(role, text) {
+    return { role, content: [{ type: "text", text }] };
+}
+/** Open a recording of the session's trace; the same session always gets the same trace. */
+function open(event, options) {
+    return openRecording({
+        projectName: projectName(event),
+        name: "Claude Code session",
+        traceId: `claude-code:${event.session_id}`,
+        fetch: options.fetch,
+    });
+}
+async function sessionStart(event, options) {
+    prune();
+    if (load(event.session_id) !== null)
+        return null;
+    save(event.session_id, { session: await open(event, options), turn: null, prompt: null });
+    return null;
+}
+function beginTurn(session, prompt, options) {
+    return resumeRecording(session, async () => {
+        await startTurn(prompt);
+        return exportRecording();
+    }, { fetch: options.fetch });
+}
+function lessonsFor(handle, prompt, options) {
+    // Retrieved, not applied: Claude Code does not show what reaches the model.
+    return resumeRecording(handle, () => retrieveLessons(prompt), { fetch: options.fetch });
+}
+async function userPromptSubmit(event, options) {
+    let state = load(event.session_id);
+    if (state === null) {
+        // SessionStart could not open the recording; the trace key is stable, so open it now.
+        state = { session: await open(event, options), turn: null, prompt: null };
+        save(event.session_id, state);
+    }
+    const prompt = String(event.prompt ?? "");
+    let turn;
+    try {
+        turn = await beginTurn(state.session, prompt, options);
+    }
+    catch (error) {
+        // Only a recording the exec server lost (e.g. after a restart) is reopened; a passing
+        // failure must not open a second recording of the session.
+        const lost = (error instanceof SovaraConfigError && error.status === 403)
+            || (error instanceof RecordingError && LOST_RECORDING.has(error.code));
+        if (!lost)
+            throw error;
+        state = { ...state, session: await open(event, options) };
+        turn = await beginTurn(state.session, prompt, options);
+    }
+    // Saved before retrieving lessons, so later steps join this turn even if retrieval fails.
+    save(event.session_id, { ...state, turn, prompt });
+    let lessons = null;
+    if (prompt) {
+        try {
+            lessons = await lessonsFor(turn ?? state.session, prompt, options);
+        }
+        catch (error) {
+            if (!(error instanceof RecordingError))
+                throw error;
+        }
+    }
+    if (!lessons)
+        return null;
+    return JSON.stringify({
+        hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: lessons.text },
+    });
+}
+async function record(state, call, outcome, options) {
+    await resumeRecording(state.turn ?? state.session, () => recordStep(call, outcome), { fetch: options.fetch });
+}
+function toolCall(event) {
+    const args = jsonValue(event.tool_input);
+    return {
+        kind: "tool",
+        name: String(event.tool_name ?? "tool"),
+        arguments: (args && typeof args === "object" && !Array.isArray(args) ? args : { input: args }),
+        call_id: String(event.tool_use_id ?? "").trim() || null,
+        metadata: { source: "claude-code" },
+    };
+}
+async function postToolUse(event, options) {
+    const state = load(event.session_id);
+    if (state)
+        await record(state, toolCall(event), { status: "success", output: jsonValue(event.tool_response) }, options);
+    return null;
+}
+async function postToolUseFailure(event, options) {
+    const state = load(event.session_id);
+    const outcome = { status: "error", error: { type: "ToolError", message: String(event.error ?? "") } };
+    if (state)
+        await record(state, toolCall(event), outcome, options);
+    return null;
+}
+async function stop(event, options) {
+    const state = load(event.session_id);
+    const reply = String(event.last_assistant_message ?? "");
+    if (!state || !reply || event.stop_hook_active)
+        return null;
+    const call = {
+        kind: "llm",
+        provider: "anthropic",
+        input: { format: "conversation", messages: state.prompt ? [textMessage("user", state.prompt)] : [] },
+        metadata: { source: "claude-code" },
+    };
+    await record(state, call, { status: "success", output: { message: textMessage("assistant", reply) } }, options);
+    return null;
+}
+async function sessionEnd(event, options) {
+    const state = load(event.session_id);
+    if (!state)
+        return null;
+    try {
+        await closeRecording(state.session, { fetch: options.fetch });
+    }
+    finally {
+        remove(event.session_id);
+    }
+    return null;
+}
+const HANDLERS = {
+    SessionStart: sessionStart,
+    UserPromptSubmit: userPromptSubmit,
+    PostToolUse: postToolUse,
+    PostToolUseFailure: postToolUseFailure,
+    Stop: stop,
+    SessionEnd: sessionEnd,
+};
+/**
+ * Run the handler for one hook event; resolve to text for Claude Code, or null.
+ *
+ * Never rejects: a failure is logged by type only and the session continues unrecorded.
+ */
+export async function handle(event, options = {}) {
+    const handler = HANDLERS[String(event.hook_event_name)];
+    if (!handler || !event.session_id)
+        return null;
+    try {
+        const timed = { ...options, fetch: withTimeout(options.fetch ?? globalThis.fetch) };
+        const output = await withShortRetries(() => handler(event, timed));
+        // The hook process exits right after; let reports queued in the background finish.
+        await flushRecordings(FLUSH_MS);
+        return output;
+    }
+    catch (error) {
+        const type = error instanceof Error ? error.name : typeof error;
+        console.error(`[sovara] Claude Code hook failed event=${String(event.hook_event_name)} error_type=${type}`);
+        return null;
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Record Claude Code sessions in Sovara and add relevant lessons to each prompt.
+ *
+ * Claude Code runs `sovara-claude-code hook` for each hook event (see the `sovara-recording`
+ * plugin). `handle(event)` is the same entry point for tests.
+ */
+export { handle, type HookEvent } from "./hooks.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Record Claude Code sessions in Sovara and add relevant lessons to each prompt.
+ *
+ * Claude Code runs `sovara-claude-code hook` for each hook event (see the `sovara-recording`
+ * plugin). `handle(event)` is the same entry point for tests.
+ */
+export { handle } from "./hooks.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAkB,MAAM,YAAY,CAAC"}

package/dist/state.d.ts

@@ -0,0 +1,12 @@
+export type SessionState = {
+    session: string;
+    turn: string | null;
+    prompt: string | null;
+};
+export declare function stateDir(): string;
+export declare function load(sessionId: string): SessionState | null;
+export declare function save(sessionId: string, state: SessionState): void;
+export declare function remove(sessionId: string): void;
+/** Delete state files of sessions that ended without SessionEnd. */
+export declare function prune(): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAMF,wBAAgB,QAAQ,IAAI,MAAM,CAGjC;AAOD,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAO3D;AAED,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAWjE;AAED,wBAAgB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,oEAAoE;AACpE,wBAAgB,KAAK,IAAI,IAAI,CAiB5B"}

package/dist/state.js

@@ -0,0 +1,73 @@
+/**
+ * Per-session state shared by the hook processes of one Claude Code session.
+ *
+ * Each session has one JSON file holding its recording handles, which carry a write token: the
+ * file is private (0600), written atomically, and never logged. The format is shared with the
+ * Python integration (`sovara-claude-code`).
+ */
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+/** A session whose SessionEnd never ran (a crash) is forgotten after this long. */
+const STALE_AFTER_MS = 7 * 24 * 3600 * 1000;
+const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;
+export function stateDir() {
+    const pluginData = process.env.CLAUDE_PLUGIN_DATA?.trim();
+    return pluginData || join(homedir(), ".sovara", "claude-code");
+}
+function statePath(sessionId) {
+    if (!SAFE_ID.test(sessionId))
+        throw new Error("Unsupported Claude Code session ID.");
+    return join(stateDir(), `${sessionId}.json`);
+}
+export function load(sessionId) {
+    try {
+        return JSON.parse(readFileSync(statePath(sessionId), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function save(sessionId, state) {
+    const path = statePath(sessionId);
+    mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+    const tmp = join(stateDir(), `.tmp-${randomUUID()}`);
+    try {
+        writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+export function remove(sessionId) {
+    rmSync(statePath(sessionId), { force: true });
+}
+/** Delete state files of sessions that ended without SessionEnd. */
+export function prune() {
+    const cutoff = Date.now() - STALE_AFTER_MS;
+    let names;
+    try {
+        names = readdirSync(stateDir());
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const path = join(stateDir(), name);
+            if (statSync(path).mtimeMs < cutoff)
+                rmSync(path, { force: true });
+        }
+        catch {
+            continue;
+        }
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@sovara/claude-code",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Record Claude Code sessions in Sovara and add relevant lessons to each prompt",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SovaraLabs/sovara-claude-code.git",
+    "directory": "typescript"
+  },
+  "homepage": "https://github.com/SovaraLabs/sovara-claude-code#readme",
+  "keywords": ["sovara", "claude-code", "observability"],
+  "bin": {
+    "sovara-claude-code": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=24.22.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@sovara/sdk": ">=0.10.0 <0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.1"
+  }
+}