devharness 0.9.8 → 0.9.9

package/build/session-endpoint.test.js

@@ -0,0 +1,202 @@
+/**
+ * Tests for the socket a CLI process calls tools through.
+ *
+ * The round-trip cases bind a real socket in a temp DEVHARNESS_DIR and connect
+ * to it, because the things worth asserting - that a ToolError comes back as a
+ * renderable response, that a half-written request does not reply early - are
+ * properties of the framing, not of a mocked handler.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { connect } from 'net';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { initializePaths } from './helpers/paths.js';
+import { startSessionEndpoint, listSessionRecords, getEndpointsDir, getEndpointAddress, getPresencePath, } from './session-endpoint.js';
+const posixOnly = process.platform === 'win32' ? it.skip : it;
+let dir;
+let previousDir;
+let endpoint = null;
+beforeEach(() => {
+    previousDir = process.env.DEVHARNESS_DIR;
+    dir = mkdtempSync(join(tmpdir(), 'devharness-endpoint-'));
+    process.env.DEVHARNESS_DIR = dir;
+    initializePaths();
+});
+afterEach(async () => {
+    if (endpoint) {
+        await endpoint.close();
+        endpoint = null;
+    }
+    if (previousDir === undefined)
+        delete process.env.DEVHARNESS_DIR;
+    else
+        process.env.DEVHARNESS_DIR = previousDir;
+    initializePaths();
+    rmSync(dir, { recursive: true, force: true });
+});
+/** One request over the socket, resolving with the parsed reply. */
+function callEndpoint(address, payload) {
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        const socket = connect(address);
+        socket.setEncoding('utf-8');
+        socket.on('connect', () => socket.write(JSON.stringify(payload) + '\n'));
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf('\n');
+            if (newline === -1)
+                return;
+            socket.destroy();
+            try {
+                resolve(JSON.parse(buffer.slice(0, newline)));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        socket.on('error', reject);
+    });
+}
+const IDENTITY = { pid: process.pid, ppid: process.ppid, cwd: '/repo' };
+// ---------------------------------------------------------------------------
+// addresses
+// ---------------------------------------------------------------------------
+describe('getEndpointAddress', () => {
+    posixOnly('puts the socket beside the presence record', () => {
+        expect(getEndpointAddress(1234)).toBe(join(getEndpointsDir(), '1234.sock'));
+        expect(getPresencePath(1234)).toBe(join(getEndpointsDir(), '1234.json'));
+    });
+    posixOnly('falls back to the temp directory when the path would exceed the sockaddr limit', () => {
+        process.env.DEVHARNESS_DIR = join(dir, 'x'.repeat(120));
+        initializePaths();
+        const address = getEndpointAddress(1234);
+        expect(address).not.toContain('x'.repeat(120));
+        expect(address).toContain('session-1234.sock');
+    });
+});
+// ---------------------------------------------------------------------------
+// round trip
+// ---------------------------------------------------------------------------
+describe('endpoint round trip', () => {
+    posixOnly('runs the named tool and returns its response', async () => {
+        const calls = [];
+        endpoint = await startSessionEndpoint({
+            executeToolCall: async (tool, args) => {
+                calls.push({ tool, args });
+                return { content: [{ type: 'text', text: 'ran it' }], _meta: { tool } };
+            },
+            identity: IDENTITY,
+        });
+        const reply = await callEndpoint(endpoint.address, { tool: 'config', args: { action: 'status' } });
+        expect(reply.ok).toBe(true);
+        expect(reply.response.content[0].text).toBe('ran it');
+        expect(calls).toEqual([{ tool: 'config', args: { action: 'status' } }]);
+    });
+    posixOnly('returns a ToolError\'s response, so an error renders like any other result', async () => {
+        const failure = { content: [{ type: 'text', text: 'nope' }], isError: true, _errorId: 'SOME_ERROR' };
+        endpoint = await startSessionEndpoint({
+            executeToolCall: async () => { throw Object.assign(new Error('nope'), { response: failure }); },
+            identity: IDENTITY,
+        });
+        const reply = await callEndpoint(endpoint.address, { tool: 'whatever', args: {} });
+        expect(reply.ok).toBe(true);
+        expect(reply.response).toEqual(failure);
+    });
+    posixOnly('reports a throw that carries no response as a failed call', async () => {
+        endpoint = await startSessionEndpoint({
+            executeToolCall: async () => { throw new Error('Unknown tool: nope'); },
+            identity: IDENTITY,
+        });
+        const reply = await callEndpoint(endpoint.address, { tool: 'nope', args: {} });
+        expect(reply.ok).toBe(false);
+        expect(reply.error).toBe('Unknown tool: nope');
+    });
+    posixOnly('rejects a request that is not JSON', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const reply = await new Promise((resolve, reject) => {
+            let buffer = '';
+            const socket = connect(endpoint.address);
+            socket.setEncoding('utf-8');
+            socket.on('connect', () => socket.write('not json\n'));
+            socket.on('data', (chunk) => {
+                buffer += chunk;
+                if (!buffer.includes('\n'))
+                    return;
+                socket.destroy();
+                resolve(JSON.parse(buffer.split('\n')[0]));
+            });
+            socket.on('error', reject);
+        });
+        expect(reply.ok).toBe(false);
+        expect(reply.error).toMatch(/single line of JSON/);
+    });
+    posixOnly('rejects a request with no tool name', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const reply = await callEndpoint(endpoint.address, { args: {} });
+        expect(reply.ok).toBe(false);
+        expect(reply.error).toMatch(/tool name/);
+    });
+    posixOnly('binds over a socket file left by a process that was killed', async () => {
+        mkdirSync(getEndpointsDir(), { recursive: true });
+        writeFileSync(getEndpointAddress(process.pid), '');
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({ content: [] }), identity: IDENTITY });
+        expect(endpoint).not.toBeNull();
+        const reply = await callEndpoint(endpoint.address, { tool: 'x', args: {} });
+        expect(reply.ok).toBe(true);
+    });
+    posixOnly('gives the socket and the record owner-only permissions', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({ content: [] }), identity: IDENTITY });
+        expect(statSync(endpoint.address).mode & 0o777).toBe(0o600);
+        expect(statSync(endpoint.presencePath).mode & 0o777).toBe(0o600);
+    });
+});
+// ---------------------------------------------------------------------------
+// presence records
+// ---------------------------------------------------------------------------
+describe('presence records', () => {
+    posixOnly('publishes this session and picks it up again', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const records = listSessionRecords();
+        expect(records).toHaveLength(1);
+        expect(records[0].pid).toBe(process.pid);
+        expect(records[0].address).toBe(endpoint.address);
+        expect(records[0].shortId).toBeUndefined();
+    });
+    posixOnly('carries the ids once refresh supplies them', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        await endpoint.refresh({ sessionId: 'full-uuid', shortId: 'abcd1234' });
+        expect(listSessionRecords()[0].shortId).toBe('abcd1234');
+        expect(listSessionRecords()[0].sessionId).toBe('full-uuid');
+    });
+    posixOnly('drops a record whose process is gone, and its socket with it', async () => {
+        mkdirSync(getEndpointsDir(), { recursive: true });
+        const deadPid = 2; // pid 2 is not a devharness session on any machine this runs on
+        const deadSocket = join(getEndpointsDir(), '999999.sock');
+        writeFileSync(deadSocket, '');
+        writeFileSync(join(getEndpointsDir(), '999999.json'), JSON.stringify({
+            pid: 999999, ppid: deadPid, cwd: '/gone', address: deadSocket, startedAt: 1,
+        }));
+        expect(listSessionRecords()).toEqual([]);
+        expect(existsSync(join(getEndpointsDir(), '999999.json'))).toBe(false);
+        expect(existsSync(deadSocket)).toBe(false);
+    });
+    posixOnly('ignores a file that is not one of ours', async () => {
+        mkdirSync(getEndpointsDir(), { recursive: true });
+        // The shape server-claims.ts writes - no address, so nothing to dial.
+        writeFileSync(join(getEndpointsDir(), '4242.json'), JSON.stringify({
+            supervisorPid: 4242, cwd: '/repo', childPid: 4243,
+        }));
+        expect(listSessionRecords()).toEqual([]);
+        expect(existsSync(join(getEndpointsDir(), '4242.json'))).toBe(true);
+    });
+    posixOnly('removes the record and the socket on close', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const { address, presencePath } = endpoint;
+        await endpoint.close();
+        endpoint = null;
+        expect(existsSync(address)).toBe(false);
+        expect(existsSync(presencePath)).toBe(false);
+    });
+});
+//# sourceMappingURL=session-endpoint.test.js.map

package/build/session-endpoint.test.js.map

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

package/build/session-events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One event stream per session.
+ *
+ * Every push event devharness produces - a guard block, an incoming message -
+ * appends one JSON line to `~/.devharness/events/<session>.jsonl`. One file
+ * means one watch: a session arms a single Monitor and receives every kind of
+ * event, including kinds added later, instead of one watch per feature.
+ *
+ * The plugin's SessionStart hook names this path to each session as it starts,
+ * which is what gets the watch armed. Nothing here verifies that a watch
+ * exists: a session with none simply receives nothing, the same as before the
+ * stream existed.
+ */
+export type EventKind = 'block' | 'message';
+export interface SessionEvent {
+    ts: string;
+    kind: EventKind;
+    [key: string]: unknown;
+}
+export declare function getEventsDir(): string;
+export declare function getEventStreamPath(sessionName: string): string;
+/**
+ * Append one event. Failures are logged and swallowed: the stream is a
+ * notification path, and losing a line must not fail the operation that
+ * produced it.
+ */
+export declare function appendEvent(sessionName: string, kind: EventKind, payload: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=session-events.d.ts.map

package/build/session-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../src/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/build/session-events.js

@@ -0,0 +1,38 @@
+/**
+ * One event stream per session.
+ *
+ * Every push event devharness produces - a guard block, an incoming message -
+ * appends one JSON line to `~/.devharness/events/<session>.jsonl`. One file
+ * means one watch: a session arms a single Monitor and receives every kind of
+ * event, including kinds added later, instead of one watch per feature.
+ *
+ * The plugin's SessionStart hook names this path to each session as it starts,
+ * which is what gets the watch armed. Nothing here verifies that a watch
+ * exists: a session with none simply receives nothing, the same as before the
+ * stream existed.
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { getOutputPath } from './helpers/paths.js';
+export function getEventsDir() {
+    return getOutputPath('events', { global: true });
+}
+export function getEventStreamPath(sessionName) {
+    return join(getEventsDir(), `${sessionName}.jsonl`);
+}
+/**
+ * Append one event. Failures are logged and swallowed: the stream is a
+ * notification path, and losing a line must not fail the operation that
+ * produced it.
+ */
+export async function appendEvent(sessionName, kind, payload) {
+    const event = { ts: new Date().toISOString(), kind, ...payload };
+    try {
+        await fs.mkdir(getEventsDir(), { recursive: true });
+        await fs.appendFile(getEventStreamPath(sessionName), JSON.stringify(event) + '\n');
+    }
+    catch (error) {
+        console.error(`[devharness] Failed to append ${kind} event: ${error}`);
+    }
+}
+//# sourceMappingURL=session-events.js.map

package/build/session-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.js","sourceRoot":"","sources":["../src/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD,MAAM,UAAU,YAAY;IAC1B,OAAO,aAAa,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,GAAG,WAAW,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,WAAmB,EACnB,IAAe,EACf,OAAgC;IAEhC,MAAM,KAAK,GAAiB,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;IAC/E,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,MAAM,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IACrF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,IAAI,WAAW,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC"}

package/build/session-events.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for the per-session event stream.
+ *
+ * The property worth pinning is that every kind lands in one file: a session
+ * arms one watch, and a kind added later arrives on it without a second one.
+ */
+export {};
+//# sourceMappingURL=session-events.test.d.ts.map

package/build/session-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.test.d.ts","sourceRoot":"","sources":["../src/session-events.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/build/session-events.test.js

@@ -0,0 +1,56 @@
+/**
+ * Tests for the per-session event stream.
+ *
+ * The property worth pinning is that every kind lands in one file: a session
+ * arms one watch, and a kind added later arrives on it without a second one.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { initializePaths } from './helpers/paths.js';
+import { appendEvent, getEventStreamPath, getEventsDir, } from './session-events.js';
+let dir;
+let previousDir;
+const SESSION = 'aaaaaaaa';
+function readStream() {
+    const path = getEventStreamPath(SESSION);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf-8')
+        .split('\n')
+        .filter(line => line.trim())
+        .map(line => JSON.parse(line));
+}
+beforeEach(() => {
+    previousDir = process.env.DEVHARNESS_DIR;
+    dir = mkdtempSync(join(tmpdir(), 'devharness-events-'));
+    process.env.DEVHARNESS_DIR = dir;
+    initializePaths();
+});
+afterEach(() => {
+    if (previousDir === undefined)
+        delete process.env.DEVHARNESS_DIR;
+    else
+        process.env.DEVHARNESS_DIR = previousDir;
+    initializePaths();
+    rmSync(dir, { recursive: true, force: true });
+});
+describe('appendEvent', () => {
+    it('writes one line per event, each stamped and kinded', async () => {
+        await appendEvent(SESSION, 'block', { guard: 'port', tool: 'navigate' });
+        await appendEvent(SESSION, 'message', { from: 'bbbbbbbb' });
+        const events = readStream();
+        expect(events.map(e => e.kind)).toEqual(['block', 'message']);
+        expect(events[0]).toMatchObject({ kind: 'block', guard: 'port', tool: 'navigate' });
+        expect(typeof events[0].ts).toBe('string');
+    });
+    it('puts every kind in the one file, so one watch covers them all', async () => {
+        await appendEvent(SESSION, 'block', {});
+        await appendEvent(SESSION, 'message', {});
+        await appendEvent(SESSION, 'block', {});
+        expect(getEventStreamPath(SESSION)).toBe(join(getEventsDir(), 'aaaaaaaa.jsonl'));
+        expect(readStream()).toHaveLength(3);
+    });
+});
+//# sourceMappingURL=session-events.test.js.map

package/build/session-events.test.js.map

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

package/build/session-identity.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Which Claude Code session this process serves.
+ *
+ * Claude Code exports CLAUDE_CODE_SESSION_ID into the environment it spawns
+ * the supervisor with, and the child inherits it. That value is present from
+ * the first instruction and unchanged when the supervisor replaces the child,
+ * so anything naming this session on disk - a mailbox filename, a presence
+ * record - keeps the same name across a rebuild.
+ *
+ * The session detector produces the same id, but only after a tool response
+ * carrying a `pid:` footer has been written into the session's .jsonl and
+ * matched. A session driven from the CLI writes no such footer, and a child
+ * restarted by a rebuild has not written one yet.
+ */
+/** The full session id from the environment, or undefined when this process
+ *  was not spawned by Claude Code. */
+export declare function getClaudeSessionId(): string | undefined;
+/** The first 8 characters of the session id - the form the dashboard and the
+ *  session detector both display. */
+export declare function getClaudeShortId(): string | undefined;
+/**
+ * The name this session is known by on disk - its mailbox filename, its event
+ * stream filename, its presence record.
+ *
+ * The hook's record comes first: it is the only source that follows the
+ * conversation through a `/clear`, which changes the id without restarting this
+ * process. The environment is next, correct from the first instruction and for
+ * as long as the conversation lasts. The detector covers a client that exports
+ * no session id. The pid form is last, and changes on every restart, which is
+ * why it is the fallback rather than the default.
+ */
+export declare function resolveSessionName(detectedShortId?: string): string;
+/**
+ * The Claude process this server belongs to.
+ *
+ * `CLAUDE_CODE_MESSAGING_SOCKET` carries that pid in its filename, and it is
+ * present in both the hook's environment and the server's, under `-p` and
+ * interactively. `CLAUDE_PID` carries it more directly and is absent from the
+ * server under `-p`, so the socket path is the derivation that works on both
+ * sides.
+ */
+export declare function getClientPid(): number | undefined;
+/** Where the plugin's SessionStart hook records the conversation a client is
+ *  currently on. */
+export declare function getClientsDir(): string;
+export declare function getClientRecordPath(clientPid: number): string;
+/**
+ * The conversation this client is on now, as last written by the hook.
+ *
+ * `CLAUDE_CODE_SESSION_ID` is read once when the process is spawned, and
+ * `/clear` gives the conversation a new id without restarting it. The hook runs
+ * on every start reason including `clear`, carrying the current id, so this
+ * file is the only source that tracks the change while the process lives.
+ */
+export declare function readCurrentSessionId(): string | undefined;
+//# sourceMappingURL=session-identity.d.ts.map

package/build/session-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-identity.d.ts","sourceRoot":"","sources":["../src/session-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH;sCACsC;AACtC,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAIvD;AAED;qCACqC;AACrC,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAKjD;AAED;oBACoB;AACpB,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAUzD"}

package/build/session-identity.js

@@ -0,0 +1,96 @@
+/**
+ * Which Claude Code session this process serves.
+ *
+ * Claude Code exports CLAUDE_CODE_SESSION_ID into the environment it spawns
+ * the supervisor with, and the child inherits it. That value is present from
+ * the first instruction and unchanged when the supervisor replaces the child,
+ * so anything naming this session on disk - a mailbox filename, a presence
+ * record - keeps the same name across a rebuild.
+ *
+ * The session detector produces the same id, but only after a tool response
+ * carrying a `pid:` footer has been written into the session's .jsonl and
+ * matched. A session driven from the CLI writes no such footer, and a child
+ * restarted by a rebuild has not written one yet.
+ */
+import { readFileSync } from 'fs';
+import { join, basename } from 'path';
+import { getOutputPath } from './helpers/paths.js';
+/** Ids become filenames; anything outside this set could escape the directory
+ *  holding them. */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** The full session id from the environment, or undefined when this process
+ *  was not spawned by Claude Code. */
+export function getClaudeSessionId() {
+    const value = process.env.CLAUDE_CODE_SESSION_ID;
+    if (!value || !SESSION_ID_PATTERN.test(value))
+        return undefined;
+    return value;
+}
+/** The first 8 characters of the session id - the form the dashboard and the
+ *  session detector both display. */
+export function getClaudeShortId() {
+    return getClaudeSessionId()?.slice(0, 8);
+}
+/**
+ * The name this session is known by on disk - its mailbox filename, its event
+ * stream filename, its presence record.
+ *
+ * The hook's record comes first: it is the only source that follows the
+ * conversation through a `/clear`, which changes the id without restarting this
+ * process. The environment is next, correct from the first instruction and for
+ * as long as the conversation lasts. The detector covers a client that exports
+ * no session id. The pid form is last, and changes on every restart, which is
+ * why it is the fallback rather than the default.
+ */
+export function resolveSessionName(detectedShortId) {
+    return readCurrentSessionId()?.slice(0, 8)
+        ?? getClaudeShortId()
+        ?? detectedShortId
+        ?? `pid-${process.pid}`;
+}
+/**
+ * The Claude process this server belongs to.
+ *
+ * `CLAUDE_CODE_MESSAGING_SOCKET` carries that pid in its filename, and it is
+ * present in both the hook's environment and the server's, under `-p` and
+ * interactively. `CLAUDE_PID` carries it more directly and is absent from the
+ * server under `-p`, so the socket path is the derivation that works on both
+ * sides.
+ */
+export function getClientPid() {
+    const socket = process.env.CLAUDE_CODE_MESSAGING_SOCKET;
+    if (!socket)
+        return undefined;
+    const pid = Number(basename(socket).replace(/\.sock$/, ''));
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+/** Where the plugin's SessionStart hook records the conversation a client is
+ *  currently on. */
+export function getClientsDir() {
+    return getOutputPath('clients', { global: true });
+}
+export function getClientRecordPath(clientPid) {
+    return join(getClientsDir(), `${clientPid}.json`);
+}
+/**
+ * The conversation this client is on now, as last written by the hook.
+ *
+ * `CLAUDE_CODE_SESSION_ID` is read once when the process is spawned, and
+ * `/clear` gives the conversation a new id without restarting it. The hook runs
+ * on every start reason including `clear`, carrying the current id, so this
+ * file is the only source that tracks the change while the process lives.
+ */
+export function readCurrentSessionId() {
+    const clientPid = getClientPid();
+    if (clientPid === undefined)
+        return undefined;
+    try {
+        const record = JSON.parse(readFileSync(getClientRecordPath(clientPid), 'utf-8'));
+        const id = record?.sessionId;
+        return typeof id === 'string' && SESSION_ID_PATTERN.test(id) ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=session-identity.js.map

package/build/session-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-identity.js","sourceRoot":"","sources":["../src/session-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;oBACoB;AACpB,MAAM,kBAAkB,GAAG,oCAAoC,CAAC;AAEhE;sCACsC;AACtC,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACjD,IAAI,CAAC,KAAK,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;qCACqC;AACrC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,kBAAkB,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,eAAwB;IACzD,OAAO,oBAAoB,EAAE,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;WACrC,gBAAgB,EAAE;WAClB,eAAe;WACf,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC;IACxD,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5D,CAAC;AAED;oBACoB;AACpB,MAAM,UAAU,aAAa;IAC3B,OAAO,aAAa,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,GAAG,SAAS,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACjF,MAAM,EAAE,GAAG,MAAM,EAAE,SAAS,CAAC;QAC7B,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/build/session-identity.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for reading the Claude Code session id out of the environment.
+ *
+ * The id becomes a filename, so a value that could traverse out of the
+ * directory holding mailboxes and presence records is rejected rather than
+ * sanitised - a sanitised name would silently address a different session.
+ */
+export {};
+//# sourceMappingURL=session-identity.test.d.ts.map

package/build/session-identity.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-identity.test.d.ts","sourceRoot":"","sources":["../src/session-identity.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}