@naswerks/periscope 1.0.0

package/dist/host/paths.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The real resolver.
+ *
+ * It is cwd-relative for a relative input, and that is exactly why the gate checks
+ * `isAbsolutePath` on the RESULT rather than trusting it. `node:path`'s `resolve` will happily turn
+ * `../../etc/passwd` into an absolute path against wherever this process happens to be — which is a
+ * different directory from the session's workspace. The jail's containment check is what catches
+ * that, and it catches it because the resolution happened first.
+ *
+ * It also handles what the textual resolver cannot: Windows drive-relative paths (`C:foo` means
+ * "foo relative to the current directory ON DRIVE C", not `C:\foo`), UNC roots, and mixed separators.
+ * Those are the shapes a hand-rolled normalizer gets subtly wrong, and each one is a way out of a
+ * jail built on string comparison.
+ */
+export declare function nodePathResolver(candidate: string): string;
+/**
+ * Where this host keeps its own credential material.
+ *
+ * This function is the single source, and that is the whole design. Both the path the host
+ * writes its token cache to and the set of paths the gate refuses derive from this one call, so
+ * they cannot disagree. The alternative (computing the cache path in one module and listing a
+ * protected path in another) is two facts that must be kept equal by hand, and nothing goes red
+ * when they drift apart: the cache tests still pass, the gate tests still pass, and the credential
+ * is simply unprotected.
+ *
+ * Why not just put the cache under `~/.claude`, which is already protected? Because that is the
+ * agent CLI's directory, and inheriting protection by squatting in somebody else's namespace is
+ * coincidence, not design. It would break the moment either side reorganised, and the breakage
+ * would be silent in exactly the same way.
+ *
+ * `PERISCOPE_CONFIG_DIR` overrides it, so an operator who keeps credentials on a separate volume
+ * gets the protection at the new location automatically rather than having to know to say so twice.
+ */
+export declare function periscopeCredentialDir(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The file the host's token cache lives in.
+ *
+ * Null when there is nowhere to put it — no home directory and no configured location. A caller
+ * that gets null has no cache, which is a refusable state and never a reason to fall back to a
+ * world-readable temp file.
+ */
+export declare function tokenCachePath(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The file this machine's paired credential lives in — beside the token cache, deliberately: the
+ * gate's protected set names the DIRECTORY, so living here is what protects it. Null when there is
+ * nowhere to put it, same contract as the cache.
+ */
+export declare function pairedCredentialPath(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Where credential material lives, as absolute paths.
+ *
+ * This exists because file permissions are not a boundary here. The agent runs as the same OS
+ * user as the host, so a 0600 token file is readable by the agent exactly as it is by the host. No
+ * mode, no owner and no ACL separates them. The gate refusing these paths is the only local
+ * control there is, and its refusal covers the declared tool families and shell commands naming a
+ * path literally; a call outside that scope (built-in `Grep`/`Glob`, an expansion form, a symlink)
+ * escalates to the controller instead, which offline means an outage refusal rather than a by-name
+ * one. Without this list "the agent holds no credential" is true only in the narrowest sense: it
+ * holds none of its own, and can read the host's.
+ *
+ * The set is returned, not applied. The embedder receives it, may add to it, and hands it to the
+ * gate at construction. A policy the caller cannot read back is a policy the caller cannot audit.
+ *
+ * Ambient cloud credentials are included deliberately. They are not this package's credentials,
+ * but they are reachable by the same user through the same tools, and a host that guards only its
+ * own secrets while the agent reads the machine's has guarded the cheaper half.
+ *
+ * `env` is passed in rather than read from the process so this is testable and so an embedder
+ * composing several sessions can state a different environment for each.
+ */
+export declare function credentialPaths(env?: NodeJS.ProcessEnv, options?: {
+    readonly agentHome?: string | null;
+}): string[];
+/**
+ * `join` without importing it: these are all one-level appends and the resolver normalizes after.
+ * The separator follows the base, so a Windows home spelled `C:\Users\x` prints as one
+ * (`C:\Users\x\.periscope`) rather than as a mix the operator has to read twice.
+ */
+export declare function join(base: string, ...segments: string[]): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/host/paths.js

@@ -0,0 +1,165 @@
+/**
+ * The two impure inputs the host's own gate needs: a real path resolver, and the set of absolute
+ * paths that hold credential material.
+ *
+ * Why it lives here: `core/paths.ts` resolves textually and never consults the filesystem, by
+ * contract, because the core must run anywhere — and its own header says a caller enforcing a real
+ * jail supplies a real resolver. Reading a home directory is reading the machine, and `src/host/` is
+ * where the boundary pin says that belongs. The gate takes both of these as INJECTED values, so the
+ * policy stays testable with a resolver that throws and a protected set nobody has to have on disk.
+ */
+import { homedir } from 'node:os';
+import { isAbsolute, resolve as resolvePath } from 'node:path';
+/**
+ * The real resolver.
+ *
+ * It is cwd-relative for a relative input, and that is exactly why the gate checks
+ * `isAbsolutePath` on the RESULT rather than trusting it. `node:path`'s `resolve` will happily turn
+ * `../../etc/passwd` into an absolute path against wherever this process happens to be — which is a
+ * different directory from the session's workspace. The jail's containment check is what catches
+ * that, and it catches it because the resolution happened first.
+ *
+ * It also handles what the textual resolver cannot: Windows drive-relative paths (`C:foo` means
+ * "foo relative to the current directory ON DRIVE C", not `C:\foo`), UNC roots, and mixed separators.
+ * Those are the shapes a hand-rolled normalizer gets subtly wrong, and each one is a way out of a
+ * jail built on string comparison.
+ */
+export function nodePathResolver(candidate) {
+    const resolved = resolvePath(candidate);
+    // `resolve` is total, but a caller reading this wants to know the post-condition is checked rather
+    // than assumed — an unrooted result would make every containment answer meaningless.
+    if (!isAbsolute(resolved))
+        throw new Error(`resolving ${candidate} produced a non-absolute path: ${resolved}`);
+    return resolved;
+}
+/**
+ * Where this host keeps its own credential material.
+ *
+ * This function is the single source, and that is the whole design. Both the path the host
+ * writes its token cache to and the set of paths the gate refuses derive from this one call, so
+ * they cannot disagree. The alternative (computing the cache path in one module and listing a
+ * protected path in another) is two facts that must be kept equal by hand, and nothing goes red
+ * when they drift apart: the cache tests still pass, the gate tests still pass, and the credential
+ * is simply unprotected.
+ *
+ * Why not just put the cache under `~/.claude`, which is already protected? Because that is the
+ * agent CLI's directory, and inheriting protection by squatting in somebody else's namespace is
+ * coincidence, not design. It would break the moment either side reorganised, and the breakage
+ * would be silent in exactly the same way.
+ *
+ * `PERISCOPE_CONFIG_DIR` overrides it, so an operator who keeps credentials on a separate volume
+ * gets the protection at the new location automatically rather than having to know to say so twice.
+ */
+export function periscopeCredentialDir(env = process.env) {
+    const configured = env['PERISCOPE_CONFIG_DIR'];
+    if (typeof configured === 'string' && configured.trim() !== '')
+        return configured.trim();
+    const home = env['USERPROFILE'] ?? env['HOME'] ?? safeHomedir();
+    if (home === null || home === '')
+        return null;
+    return join(home, '.periscope');
+}
+/**
+ * The file the host's token cache lives in.
+ *
+ * Null when there is nowhere to put it — no home directory and no configured location. A caller
+ * that gets null has no cache, which is a refusable state and never a reason to fall back to a
+ * world-readable temp file.
+ */
+export function tokenCachePath(env = process.env) {
+    const dir = periscopeCredentialDir(env);
+    return dir === null ? null : join(dir, 'token-cache.json');
+}
+/**
+ * The file this machine's paired credential lives in — beside the token cache, deliberately: the
+ * gate's protected set names the DIRECTORY, so living here is what protects it. Null when there is
+ * nowhere to put it, same contract as the cache.
+ */
+export function pairedCredentialPath(env = process.env) {
+    const dir = periscopeCredentialDir(env);
+    return dir === null ? null : join(dir, 'paired-credential.json');
+}
+/**
+ * Where credential material lives, as absolute paths.
+ *
+ * This exists because file permissions are not a boundary here. The agent runs as the same OS
+ * user as the host, so a 0600 token file is readable by the agent exactly as it is by the host. No
+ * mode, no owner and no ACL separates them. The gate refusing these paths is the only local
+ * control there is, and its refusal covers the declared tool families and shell commands naming a
+ * path literally; a call outside that scope (built-in `Grep`/`Glob`, an expansion form, a symlink)
+ * escalates to the controller instead, which offline means an outage refusal rather than a by-name
+ * one. Without this list "the agent holds no credential" is true only in the narrowest sense: it
+ * holds none of its own, and can read the host's.
+ *
+ * The set is returned, not applied. The embedder receives it, may add to it, and hands it to the
+ * gate at construction. A policy the caller cannot read back is a policy the caller cannot audit.
+ *
+ * Ambient cloud credentials are included deliberately. They are not this package's credentials,
+ * but they are reachable by the same user through the same tools, and a host that guards only its
+ * own secrets while the agent reads the machine's has guarded the cheaper half.
+ *
+ * `env` is passed in rather than read from the process so this is testable and so an embedder
+ * composing several sessions can state a different environment for each.
+ */
+export function credentialPaths(env = process.env, options = {}) {
+    const home = env['USERPROFILE'] ?? env['HOME'] ?? safeHomedir();
+    const paths = [];
+    // The host's own credential directory, first, and derived rather than spelled out. The
+    // directory is named rather than the file, so anything the host later keeps beside the token
+    // cache is protected by having been put there, not by somebody remembering to add a line.
+    //
+    // Removing these two lines takes tests red across three lanes at once (read, write and shell)
+    // because all three read this one list. That is the point of deriving it here rather than
+    // restating the path where the cache is written.
+    const own = periscopeCredentialDir(env);
+    if (own !== null)
+        paths.push(own);
+    if (home !== null && home !== '') {
+        // The agent CLI's own token cache and its per-project state file. `.claude.json` is a FILE and
+        // `.claude` a DIRECTORY; both are named because the containment check treats a protected path as
+        // protected along with everything beneath it, and a file simply has nothing beneath it.
+        paths.push(join(home, '.claude'));
+        paths.push(join(home, '.claude.json'));
+        // Ambient cloud credentials reachable by the same user.
+        paths.push(join(home, '.aws'));
+        paths.push(join(home, '.config', 'gcloud'));
+        paths.push(join(home, '.azure'));
+        // SSH keys: not a token cache, but the same class — material that authenticates this user.
+        paths.push(join(home, '.ssh'));
+    }
+    // An explicitly configured credential location wins over the derived ones and is added as well.
+    const configured = env['CLAUDE_CONFIG_DIR'];
+    if (typeof configured === 'string' && configured.trim() !== '')
+        paths.push(configured);
+    // The effective agent home, when it is not the default under the home directory: the agent CLI
+    // keeps its token cache and per-project state there, so protecting only `~/.claude` would leave a
+    // host configured with `PERISCOPE_AGENT_HOME` guarding the wrong directory. The composition root
+    // passes the value it resolved (environment or config file); the environment key alone is read
+    // here for a caller that has nothing else.
+    const agentHome = options.agentHome ?? env['PERISCOPE_AGENT_HOME'] ?? null;
+    if (typeof agentHome === 'string' && agentHome.trim() !== '' && !paths.includes(agentHome)) {
+        paths.push(agentHome);
+    }
+    return paths;
+}
+/**
+ * `join` without importing it: these are all one-level appends and the resolver normalizes after.
+ * The separator follows the base, so a Windows home spelled `C:\Users\x` prints as one
+ * (`C:\Users\x\.periscope`) rather than as a mix the operator has to read twice.
+ */
+export function join(base, ...segments) {
+    const trimmed = base.replace(/[\\/]+$/, '');
+    const separator = trimmed.includes('\\') && !trimmed.includes('/') ? '\\' : '/';
+    return [trimmed, ...segments].join(separator);
+}
+/** `homedir()` throws on a system with no resolvable home; a missing home is not a reason to fail. */
+function safeHomedir() {
+    try {
+        const home = homedir();
+        return home === '' ? null : home;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/host/repository-read.d.ts

@@ -0,0 +1,33 @@
+import type { RepositoryEntry } from '../control/frames.js';
+import type { Result } from '../core/result.js';
+/** How many bytes of a file's head are checked for a NUL byte before it is served as text. */
+export declare const BINARY_PROBE_BYTES: number;
+/** One directory's children, names only, sorted; `truncated` when the cap stopped the listing. */
+export interface RepositoryListing {
+    readonly entries: readonly RepositoryEntry[];
+    readonly truncated: boolean;
+}
+/** One file's head as text, with the whole size so a caller can see what `truncated` left behind. */
+export interface RepositoryText {
+    readonly text: string;
+    readonly sizeBytes: number;
+    readonly truncated: boolean;
+}
+/**
+ * The lexical half of the jail: join `relative` under `root`, resolve, and refuse anything that
+ * resolves outside. `''` is the root itself. Pure over the resolver; the physical half needs the
+ * filesystem and lives in the two readers.
+ */
+export declare function resolveRepositoryPath(root: string, relative: string): Result<string>;
+/**
+ * List one directory under the root: files and directories by name, sorted, at most `cap` of
+ * them. Anything that is neither (a link, a socket) is left out rather than followed.
+ */
+export declare function listRepositoryDirectory(root: string, relative: string, cap?: number, protectedPaths?: readonly string[]): Promise<Result<RepositoryListing>>;
+/**
+ * Read the head of one text file under the root: at most `maxBytes` (capped at the wire's bound),
+ * cut back to a UTF-8 boundary so the text never ends mid-character. Binary is refused by the NUL
+ * probe; a directory or an absent path is refused by name.
+ */
+export declare function readRepositoryFile(root: string, relative: string, maxBytes?: number, protectedPaths?: readonly string[]): Promise<Result<RepositoryText>>;
+//# sourceMappingURL=repository-read.d.ts.map

package/dist/host/repository-read.js

@@ -0,0 +1,201 @@
+/**
+ * The repository read: a controller listing one directory or reading one text file of the
+ * operator's checkout through this host, jailed to the repository root.
+ *
+ * The posture is the discovery door's, over a different root. The transcripts door reads the agent
+ * CLI's own directory; this reads the repository the host provisions workspaces from, so a
+ * controller can show a checkout's shape and the text of a file in it without a session, a clone or
+ * a bulk lane. Read-only is a property here too: the filesystem surface is `createReadStream`,
+ * `readdir`, `stat` and `realpath`, and `src/pins/transcript-readonly.test.ts` holds this module's
+ * closure to that allowlist beside the transcripts door.
+ *
+ * The jail, for every controller-supplied path:
+ *   1. a NUL byte in the text is refused before anything is resolved (it would end the path early
+ *      for the filesystem and late for the check);
+ *   2. resolve-then-containment, lexically: the path is joined under the root, resolved by the real
+ *      resolver, and must stay inside the root, so `..` and an absolute path cannot leave it;
+ *   3. resolve-then-containment, physically: the real path (links followed) must stay inside the
+ *      root's real path, so a link planted inside the checkout cannot point the read outside it;
+ *   4. the protected set: a path at or beneath one of the host's protected paths (the credential
+ *      directories the gate keeps from the agent) is refused whatever the root is, on the lexical
+ *      resolution and again on the real path.
+ * A jail violation refuses `repository-path-escape`; a protected path refuses
+ * `credential-path-denied`. A path that is inside the root but is not what was asked for (a file
+ * where a directory was asked, nothing at all) refuses `repository-read-failed`; absence is a
+ * refusal here, not a value, because the ask named one thing and it is not there.
+ *
+ * Bounded twice: a listing carries at most `MAX_REPOSITORY_ENTRIES` names and says when it stopped;
+ * a read carries at most `maxBytes` (itself capped at `MAX_REPOSITORY_READ_BYTES`), cut on a UTF-8
+ * boundary, and says the file's whole size. A file with a NUL byte in its first
+ * `BINARY_PROBE_BYTES` is refused as binary: the answer is a string and a string cannot carry it.
+ */
+import { createReadStream } from 'node:fs';
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { MAX_REPOSITORY_ENTRIES, MAX_REPOSITORY_READ_BYTES } from '../control/frames.js';
+import { isContainedBy, normalizePath } from '../core/paths.js';
+import { ok, refuse } from '../core/result.js';
+import { nodePathResolver } from './paths.js';
+/** How many bytes of a file's head are checked for a NUL byte before it is served as text. */
+export const BINARY_PROBE_BYTES = 8 * 1024;
+/**
+ * The lexical half of the jail: join `relative` under `root`, resolve, and refuse anything that
+ * resolves outside. `''` is the root itself. Pure over the resolver; the physical half needs the
+ * filesystem and lives in the two readers.
+ */
+export function resolveRepositoryPath(root, relative) {
+    if (relative.includes('\0')) {
+        return refuse('repository-path-escape', 'the path holds a NUL byte, refused before it is resolved');
+    }
+    const resolvedRoot = normalizePath(nodePathResolver(root));
+    const candidate = normalizePath(nodePathResolver(`${resolvedRoot}/${relative}`));
+    if (!isContainedBy(candidate, resolvedRoot)) {
+        return refuse('repository-path-escape', 'the path resolves outside the repository root, refused by the containment layer');
+    }
+    return ok(candidate);
+}
+/** The physical half: the real path of both, links followed, and the same containment rule. */
+async function containedRealPath(root, candidate) {
+    let realRoot;
+    try {
+        realRoot = normalizePath(await realpath(root));
+    }
+    catch (error) {
+        return refuse('repository-read-failed', `the repository root could not be resolved: ${describe(error)}`);
+    }
+    let real;
+    try {
+        real = normalizePath(await realpath(candidate));
+    }
+    catch (error) {
+        return refuse('repository-read-failed', `nothing is at that path: ${describe(error)}`);
+    }
+    if (!isContainedBy(real, realRoot)) {
+        return refuse('repository-path-escape', 'the path leads outside the repository root through a link, refused by the containment layer');
+    }
+    return ok(real);
+}
+/**
+ * The protected set applies to this door as it applies to the agent: a path at or beneath one of
+ * the host's protected paths is refused whatever the repository root is, checked on the lexical
+ * resolution and again on the real path, so neither a root pointed at the credential directory nor
+ * a link into it serves credential material to a controller.
+ */
+function protectedPathRefusal(resolved, protectedPaths) {
+    for (const candidate of protectedPaths) {
+        if (isContainedBy(resolved, candidate)) {
+            return refuse('credential-path-denied', `the path is at or beneath ${candidate}, which holds credential material; the repository doors honour the same protected set as the gate`);
+        }
+    }
+    return ok(null);
+}
+/** The jail and the protected set together; the real path of the target on success. */
+async function admittedRealPath(root, relative, protectedPaths) {
+    const resolved = resolveRepositoryPath(root, relative);
+    if (!resolved.ok)
+        return resolved;
+    const lexical = protectedPathRefusal(resolved.value, protectedPaths);
+    if (!lexical.ok)
+        return lexical;
+    const real = await containedRealPath(root, resolved.value);
+    if (!real.ok)
+        return real;
+    // The real path is compared against the protected set's real paths, not its spellings: a
+    // component `realpath` rewrites (a short name, a linked directory) would otherwise make the
+    // resolved target and the protected directory disagree about a prefix that names one place. A
+    // protected path that does not exist is compared as spelled; absence protects nothing.
+    const realProtected = await Promise.all(protectedPaths.map(async (candidate) => {
+        try {
+            return normalizePath(await realpath(candidate));
+        }
+        catch {
+            return candidate;
+        }
+    }));
+    const physical = protectedPathRefusal(real.value, realProtected);
+    if (!physical.ok)
+        return physical;
+    return real;
+}
+/**
+ * List one directory under the root: files and directories by name, sorted, at most `cap` of
+ * them. Anything that is neither (a link, a socket) is left out rather than followed.
+ */
+export async function listRepositoryDirectory(root, relative, cap = MAX_REPOSITORY_ENTRIES, protectedPaths = []) {
+    const real = await admittedRealPath(root, relative, protectedPaths);
+    if (!real.ok)
+        return real;
+    let children;
+    try {
+        children = await readdir(real.value, { withFileTypes: true });
+    }
+    catch (error) {
+        return refuse('repository-read-failed', `the path could not be listed as a directory: ${describe(error)}`);
+    }
+    const named = children
+        .filter((child) => child.isDirectory() || child.isFile())
+        .map((child) => ({ name: child.name, directory: child.isDirectory() }))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const limit = Math.max(1, cap);
+    const entries = [];
+    for (const child of named.slice(0, limit)) {
+        try {
+            const stats = await stat(`${real.value}/${child.name}`);
+            entries.push({
+                name: child.name,
+                directory: child.directory,
+                sizeBytes: child.directory ? 0 : stats.size,
+                mtimeMs: Math.floor(stats.mtimeMs),
+            });
+        }
+        catch {
+            // Removed between readdir and stat: the listing describes what exists, not what did.
+        }
+    }
+    return ok({ entries, truncated: named.length > limit });
+}
+/**
+ * Read the head of one text file under the root: at most `maxBytes` (capped at the wire's bound),
+ * cut back to a UTF-8 boundary so the text never ends mid-character. Binary is refused by the NUL
+ * probe; a directory or an absent path is refused by name.
+ */
+export async function readRepositoryFile(root, relative, maxBytes = MAX_REPOSITORY_READ_BYTES, protectedPaths = []) {
+    const real = await admittedRealPath(root, relative, protectedPaths);
+    if (!real.ok)
+        return real;
+    let stats;
+    try {
+        stats = await stat(real.value);
+    }
+    catch (error) {
+        return refuse('repository-read-failed', `the file could not be read: ${describe(error)}`);
+    }
+    if (!stats.isFile())
+        return refuse('repository-read-failed', 'the path is not a file');
+    const wanted = Math.min(Math.max(1, Math.floor(maxBytes)), MAX_REPOSITORY_READ_BYTES);
+    const probe = Math.max(wanted, BINARY_PROBE_BYTES);
+    const chunks = [];
+    try {
+        if (stats.size > 0) {
+            for await (const chunk of createReadStream(real.value, { start: 0, end: probe - 1 })) {
+                chunks.push(chunk);
+            }
+        }
+    }
+    catch (error) {
+        return refuse('repository-read-failed', `the file could not be read: ${describe(error)}`);
+    }
+    const head = Buffer.concat(chunks);
+    if (head.subarray(0, BINARY_PROBE_BYTES).includes(0)) {
+        return refuse('repository-read-failed', 'the file holds a NUL byte in its head and is not served as text');
+    }
+    let cut = Math.min(head.length, wanted);
+    // A continuation byte at the cut means a character straddles it: step back to its first byte.
+    while (cut > 0 && cut < head.length && (head[cut] & 0xc0) === 0x80)
+        cut -= 1;
+    const text = head.subarray(0, cut).toString('utf8');
+    return ok({ text, sizeBytes: stats.size, truncated: cut < stats.size });
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=repository-read.js.map

package/dist/host/session-store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The store adapter seam: where this package's transcript store becomes the SDK's `SessionStore`.
+ *
+ * It lives in `src/host/` because it names `@anthropic-ai/claude-agent-sdk`, which is confined here
+ * exactly like `node:fs` is. Everything above works in the package's own vocabulary; the bridge is
+ * a field-for-field copy in one file, so a shape change on either side is a compile error here
+ * rather than a silent mismatch anywhere else.
+ *
+ * The adapter is an interface this package implements, not an API it calls, and that is why
+ * standing on an `@alpha` surface is acceptable here. If the shape moves, `satisfies` stops
+ * holding and the build breaks, loudly, before anything ships. An alpha surface that is called
+ * fails the other way: it keeps compiling and behaves differently in production. The version is
+ * pinned exactly, and pins/sdk-confinement.test.ts asserts that the pin has no range.
+ *
+ * The SDK's errors are exceptions and this package's are refusals, so the bridge converts. The
+ * adapter contract says a rejection is retried and a timeout is not, which means throwing is how an
+ * adapter reports a failure it wants retried; returning normally would tell the SDK the batch
+ * landed. So a refusal from the store is re-thrown here deliberately: it is the only way to refuse
+ * in the adapter's own vocabulary, and swallowing it would silently accept data loss.
+ */
+import type { SDKMessage, SessionKey, SessionStore, SessionStoreEntry } from '@anthropic-ai/claude-agent-sdk';
+import type { TranscriptKey } from '../persistence/key.js';
+import type { MirrorDrop } from '../persistence/mirror.js';
+import type { TranscriptStore } from '../persistence/store.js';
+export type { SessionKey, SessionStore, SessionStoreEntry };
+/** The SDK's key, in this package's vocabulary. A copy: the two types may not meet above this file. */
+export declare function toTranscriptKey(key: SessionKey): TranscriptKey;
+/** This package's key, as the SDK's. */
+export declare function toSessionKey(key: TranscriptKey): SessionKey;
+/**
+ * Present a `TranscriptStore` to the SDK as a `SessionStore`.
+ *
+ * `listSessionSummaries` is not implemented, deliberately; see persistence/store.ts for the three
+ * reasons. The adapter contract marks it optional and states the fallback in as many words, so its
+ * absence is a supported posture rather than a missing feature.
+ */
+export declare function asSessionStore(store: TranscriptStore): SessionStore;
+/**
+ * A dropped mirror batch, lifted off the message stream: the one failure that is otherwise
+ * indistinguishable from nothing having happened.
+ *
+ * The store simply ends up with fewer entries than local disk: no error at the read, no gap anything
+ * can compute, and the durable copy silently behind local truth. The SDK reports it as a system
+ * message and this is what turns that into a named degrade a caller must handle. A host that only
+ * forwarded the message lane would drop it on the floor.
+ *
+ * The message does not carry the lost entries or how many attempts ran, so those are what this
+ * host knows rather than what it was told: attempts come from the contract's own stated policy, and
+ * the uuids are empty unless a caller correlates the batch itself. Reporting an attempt count the
+ * message did not carry would be inventing detail, so the kind is what decides it.
+ */
+export declare function readMirrorDrop(message: SDKMessage): MirrorDrop | null;
+//# sourceMappingURL=session-store.d.ts.map

package/dist/host/session-store.js

@@ -0,0 +1,100 @@
+/** The SDK's key, in this package's vocabulary. A copy: the two types may not meet above this file. */
+export function toTranscriptKey(key) {
+    return key.subpath === undefined
+        ? { projectKey: key.projectKey, sessionId: key.sessionId }
+        : { projectKey: key.projectKey, sessionId: key.sessionId, subpath: key.subpath };
+}
+/** This package's key, as the SDK's. */
+export function toSessionKey(key) {
+    return key.subpath === undefined
+        ? { projectKey: key.projectKey, sessionId: key.sessionId }
+        : { projectKey: key.projectKey, sessionId: key.sessionId, subpath: key.subpath };
+}
+/**
+ * Present a `TranscriptStore` to the SDK as a `SessionStore`.
+ *
+ * `listSessionSummaries` is not implemented, deliberately; see persistence/store.ts for the three
+ * reasons. The adapter contract marks it optional and states the fallback in as many words, so its
+ * absence is a supported posture rather than a missing feature.
+ */
+export function asSessionStore(store) {
+    const adapter = {
+        async append(key, entries) {
+            const result = await store.append(toTranscriptKey(key), entries);
+            if (!result.ok) {
+                // Thrown, not swallowed: a normal return tells the SDK the batch is durable. See the header.
+                throw new Error(`${result.refusal.reason}: ${result.refusal.detail}`);
+            }
+        },
+        async load(key) {
+            const result = await store.load(toTranscriptKey(key));
+            if (!result.ok)
+                throw new Error(`${result.refusal.reason}: ${result.refusal.detail}`);
+            return result.value === null ? null : result.value;
+        },
+    };
+    if (store.listSessions !== undefined) {
+        adapter.listSessions = async (projectKey) => {
+            const result = await store.listSessions?.(projectKey);
+            if (result === undefined || !result.ok) {
+                throw new Error(result === undefined ? 'listSessions is unavailable' : result.refusal.detail);
+            }
+            return result.value.map((one) => ({ sessionId: one.sessionId, mtime: one.mtime }));
+        };
+    }
+    if (store.delete !== undefined) {
+        adapter.delete = async (key) => {
+            const result = await store.delete?.(toTranscriptKey(key));
+            if (result !== undefined && !result.ok)
+                throw new Error(result.refusal.detail);
+        };
+    }
+    if (store.listSubkeys !== undefined) {
+        adapter.listSubkeys = async (key) => {
+            const result = await store.listSubkeys?.({ projectKey: key.projectKey, sessionId: key.sessionId });
+            if (result === undefined || !result.ok) {
+                throw new Error(result === undefined ? 'listSubkeys is unavailable' : result.refusal.detail);
+            }
+            return result.value;
+        };
+    }
+    return adapter;
+}
+/**
+ * A dropped mirror batch, lifted off the message stream: the one failure that is otherwise
+ * indistinguishable from nothing having happened.
+ *
+ * The store simply ends up with fewer entries than local disk: no error at the read, no gap anything
+ * can compute, and the durable copy silently behind local truth. The SDK reports it as a system
+ * message and this is what turns that into a named degrade a caller must handle. A host that only
+ * forwarded the message lane would drop it on the floor.
+ *
+ * The message does not carry the lost entries or how many attempts ran, so those are what this
+ * host knows rather than what it was told: attempts come from the contract's own stated policy, and
+ * the uuids are empty unless a caller correlates the batch itself. Reporting an attempt count the
+ * message did not carry would be inventing detail, so the kind is what decides it.
+ */
+export function readMirrorDrop(message) {
+    if (message.type !== 'system' || message.subtype !== 'mirror_error')
+        return null;
+    const kind = looksLikeTimeout(message.error) ? 'timed-out' : 'rejected';
+    return {
+        key: toTranscriptKey(message.key),
+        kind,
+        attempts: kind === 'timed-out' ? 1 : 3,
+        error: message.error,
+        entryUuids: [],
+    };
+}
+/**
+ * Whether the store's error text describes a timeout.
+ *
+ * A text match, and said out loud because it is the weak part. The message carries the failure as
+ * a string with no discriminant, so the two drop paths (retried three times, versus not retried at
+ * all) cannot be told apart structurally. Guessing wrong misreports the attempt count and nothing
+ * else; the drop itself is reported either way, which is the property that matters.
+ */
+function looksLikeTimeout(error) {
+    return /timed?[\s-]?out|timeout|etimedout/i.test(error);
+}
+//# sourceMappingURL=session-store.js.map