@naswerks/periscope 1.0.0

package/dist/host/agent-process.js

@@ -0,0 +1,382 @@
+/**
+ * The agent SDK seam: the only module in this package that starts an agent process, and the one
+ * that re-exports the SDK's types for every layer above.
+ *
+ * It is not the only file that names `@anthropic-ai/claude-agent-sdk`. Three others in
+ * `src/host/` do (the MCP server builder, the store adapter and the telemetry reader), because
+ * each bridges one SDK shape and none of them spawns anything. The rule the pin enforces is the
+ * directory, not this file; what remains unique here is `query()`.
+ *
+ * It lives in `src/host/` because calling `query()` spawns a real CLI subprocess. The boundary this
+ * directory holds is stated as "nothing outside `src/host/` touches the filesystem, spawns a
+ * process, or reads the machine", and a package import that spawns is exactly as privileged as
+ * `node:child_process` even though no lint rule would have noticed. Pinned by
+ * src/pins/sdk-confinement.test.ts.
+ *
+ * Everything above this file works in the package's own vocabulary and never imports the SDK, so
+ * "what starts a process, and with what?" has one answer. The SDK types the layer above genuinely
+ * needs are re-exported here rather than imported there; a type-only import would still name the
+ * specifier, and one place naming it is the whole point.
+ *
+ * `windowsHide` is not a knob this package has, and it does not need to be. Node's default is
+ * `false` (the widespread "true since Node 15" belief is wrong), and where no ancestor process owns
+ * a console there is none to inherit, so every un-hidden spawn allocates a real visible window. It
+ * is absent from the SDK's `Options`, but the SDK's own `spawnLocalProcess` passes
+ * `windowsHide: true`, so the default path is correct. The trap is `spawnClaudeCodeProcess`: a
+ * custom spawn function replaces that path entirely, and one written without `windowsHide`
+ * reintroduces a flashing window on every spawn.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { AsyncQueue } from '../core/async-queue.js';
+/** The discriminator of one message, in the same form `MessageDiscriminator` names. */
+export function discriminatorOf(message) {
+    return message.type === 'system' ? `system/${message.subtype}` : message.type;
+}
+/**
+ * Every key `Options` is composed from, as data.
+ *
+ * This is the permission-config pin's subject, and it is why that pin is a compile error rather
+ * than a grep. The SDK's `Options` carries nine lanes that alter permission outcomes:
+ * `permissionMode`, `settings`, `managedSettings`, `toolAliases`, `permissionPromptToolName`,
+ * `allowedTools`, `disallowedTools`, `canUseTool`, and the `permissions` block a settings object can
+ * carry. Eight of them (`SHADOWING_LANES`) are unreachable, because a caller can only supply the
+ * keys below and `startAgentProcess` composes `Options` from exactly these; `permissionMode` is the
+ * one opened by name, in `CLI_PARITY_OPTION_KEYS`. Adding a composable option breaks this
+ * declaration, and the pin fails at build time instead of when someone remembers to look.
+ *
+ * The composable set is declared as several lists, each with its own reason, because the moment two
+ * different justifications share one constant, neither can be checked:
+ *
+ * - `STREAMING_OPTION_KEYS` select what the process emits, never what it may do. A widening for
+ *   visibility is not a weakening for permission.
+ * - `TOOL_SURFACE_OPTION_KEYS` change which tools exist. Read that list's note for why it is
+ *   nonetheless safe.
+ * - `PERSISTENCE_OPTION_KEYS` decide where the transcript goes: the egress lane. Its safety
+ *   argument is structural and is pinned rather than stated.
+ * - `AGENT_SELECTION_OPTION_KEYS` choose which agent runs and what it is told at the start.
+ * - `CLI_PARITY_OPTION_KEYS` expose what the CLI itself exposes, including the one shadowing lane
+ *   that is a posture rather than a rule file.
+ *
+ * The distinction that decides whether a widening is a weakening: `model` and `systemPrompt` were
+ * absent, not narrowed. They were never among the composable keys, so opening them filled a gap.
+ * The eight lanes in `SHADOWING_LANES` are a deliberate security narrowing and stay closed, and the
+ * pin still asserts each one by name. A gap filled and a narrowing widened are different acts and
+ * this file tells them apart.
+ *
+ * `toolAliases` is the one worth naming: it redirects tool names after the model emits them, so a
+ * gate matching on `tool_name` would see the alias source while the target executed. A silent
+ * mismatch, and unreachable here by construction.
+ */
+export const AGENT_PROCESS_REQUEST_KEYS = {
+    cwd: true,
+    env: true,
+    settingSources: true,
+    plugins: true,
+    hooks: true,
+    resume: true,
+    fork: true,
+    onStderr: true,
+    spawn: true,
+    includePartialMessages: true,
+    thinking: true,
+    forwardSubagentText: true,
+    mcpServers: true,
+    strictMcpConfig: true,
+    sessionStore: true,
+    sessionStoreFlush: true,
+    model: true,
+    systemPrompt: true,
+    effort: true,
+    permissionMode: true,
+};
+/**
+ * The eight closed lanes, as data: the subject both permission pins are about.
+ *
+ * The defect this guards against: the lanes were once written out twice, once per pin, and the two
+ * copies disagreed. The scan pin listed `permissionPrompt`, which does not exist in `sdk.d.ts` at
+ * all, and omitted `permissions`, which does. So the "two mechanisms, one invariant" argument (a
+ * type cannot see a module that reaches past the composer, a scan cannot see a type) was being made
+ * by two lists guarding different sets, with the real option covered by only one of them.
+ *
+ * One declaration now, derived by both, and every name checked against the shipped types.
+ */
+export const SHADOWING_LANES = [
+    // `permissionMode` was deliberately removed from this list (CLI parity); see
+    // `CLI_PARITY_OPTION_KEYS`. It is the one lane that is a posture the operator chooses in the open,
+    // not a rule file or a pre-answer; the eight below are the latter and stay closed.
+    'settings',
+    'managedSettings',
+    'toolAliases',
+    'permissionPromptToolName',
+    'allowedTools',
+    'disallowedTools',
+    'canUseTool',
+    'permissions',
+];
+/**
+ * The keys that widened the composable set for visibility, kept as data so the reason is checkable
+ * rather than remembered.
+ *
+ * One reason covers all three: each selects what the process emits. None appears in any permission
+ * evaluation path, so none can change whether a tool runs, only how much of the run is visible.
+ * That is why widening the set here does not weaken the boundary above.
+ *
+ * The pin asserts every member is composable and is none of the eight shadowing lanes, so a later
+ * addition cannot join this list by assertion alone.
+ */
+export const STREAMING_OPTION_KEYS = [
+    'includePartialMessages',
+    'thinking',
+    'forwardSubagentText',
+];
+/**
+ * The keys that change which tools exist: a different class from the streaming three, kept
+ * separate so the two reasons cannot be confused for one.
+ *
+ * These are not data keys. `mcpServers` introduces tools, and `PreToolUse` fires for MCP tools and
+ * inside subagents (observed, not assumed). So this widening enlarges the surface the gate must
+ * cover, and the streaming keys' reason ("it only selects what is emitted") is false of it.
+ *
+ * Nor are they shadowing lanes. The closed lanes share one property: they can answer a permission
+ * before the gate does. These answer nothing. What makes them safe is structural: `permissionHooks`
+ * registers `PreToolUse` with no `matcher`, so a tool this host has never heard of reaches exactly
+ * the same handler as `Bash`. Coverage is by construction rather than by enumeration, which is why a
+ * tool set the host cannot predict is still a tool set the host decides about.
+ *
+ * If a `matcher` were ever introduced, this classification stops being true, and these two keys
+ * become the first way to add a tool nothing decides about. That sentence is the whole reason this
+ * list exists as data instead of as a decision somebody made once.
+ *
+ * `strictMcpConfig` belongs here because it acts on the same surface, but it moves the opposite
+ * way: it only ever removes servers the host did not declare. It is the safe direction of the same
+ * lane, and grouping them keeps that visible.
+ */
+export const TOOL_SURFACE_OPTION_KEYS = [
+    'mcpServers',
+    'strictMcpConfig',
+];
+/**
+ * The keys that decide where a transcript goes: a third class again, and the reason is not the
+ * other two lists' reason.
+ *
+ * These are a confidentiality and egress surface. The streaming keys widen what this host observes
+ * about its own session. The tool-surface keys widen what the agent may do, and are covered because
+ * the gate has no matcher. These do neither: they hand a live object every message the agent saw,
+ * and a store is by definition somewhere else. Filing them under "it only selects what is emitted"
+ * would put a false sentence inside the constant whose entire job is to make the reason checkable.
+ *
+ * Nor are they shadowing lanes. The closed lanes share one property: they can answer a permission
+ * before the gate does. A store answers nothing and is never consulted about whether a tool runs.
+ *
+ * What makes them safe is that a destination cannot be named from off-box, and it is structural
+ * rather than enforced: `SessionStore` is an object with methods, so it has no JSON representation
+ * and cannot arrive over the link. The only code that can supply one is the code that composes this
+ * host. That is the same shape of argument as the gate's no-matcher coverage (a property of what
+ * the type is, not of a check somebody remembered to write) and it is pinned by
+ * pins/persistence-egress.test.ts.
+ *
+ * If a store ever becomes constructible from data (a URL, a connection string, a descriptor the
+ * host resolves into a client), this classification stops being true, and these become the first
+ * way a transcript can be sent somewhere the operator did not choose. That sentence is why this list
+ * is data instead of a decision somebody made once.
+ */
+export const PERSISTENCE_OPTION_KEYS = [
+    'sessionStore',
+    'sessionStoreFlush',
+];
+/**
+ * The keys that choose which agent runs and what it is told at the start: a fourth class, and its
+ * reason is not any of the other three's.
+ *
+ * These were absent, not narrowed, and that is the whole classification. `model` and
+ * `systemPrompt` were simply not in this type, so nothing was ever protecting them; there was no
+ * decision to reverse, only a capability nobody had wired. The eight `SHADOWING_LANES` are the
+ * opposite case: each was considered and closed. Opening a gap and re-opening a closed lane look
+ * identical in a diff, and this list is how they stop looking identical.
+ *
+ * Neither appears in any permission evaluation path. They do not pre-answer a call, do not
+ * redirect a tool name, do not load a rule file and are never consulted about whether a tool runs,
+ * which is exactly the property the closed lanes share and these do not. What they change is which
+ * weights answer and what standing instructions those weights start with.
+ *
+ * The cost, because a widening with no stated cost is a widening nobody checked: a controller that
+ * can set a system prompt can give the agent standing instructions this host will never see the
+ * effect of, since the SDK's init message does not report one. The gate still decides every tool
+ * call, so the boundary is unmoved, but "the host can state what this agent was told" is not a
+ * property this package has; `AgentInitFacts` is where that can be verified.
+ *
+ * The pin asserts every member is composable and is none of the eight, exactly as the other lists
+ * do.
+ */
+export const AGENT_SELECTION_OPTION_KEYS = [
+    'model',
+    'systemPrompt',
+];
+/**
+ * The CLI-parity keys, and the list that re-opens a closed lane on purpose. `effort` was absent (a
+ * gap, like `model`). `permissionMode` was once a shadowing lane, considered and closed, and it is
+ * opened here by name, with the reason:
+ *
+ *   a session through this host must expose what `claude` exposes, and bypass is a common default
+ *   for an operator. The gate never depended on the mode: `PreToolUse` fires under every mode, so
+ *   the boundary set is still held under `bypassPermissions`. What the mode changes is the CLI's
+ *   own prompt flow, which this host's gate already answers.
+ *
+ * The other eight stay closed: they are rule files and pre-answers, which is a different thing from a
+ * posture chosen in the open. Pinned by `pins/permission-config.test.ts`.
+ */
+export const CLI_PARITY_OPTION_KEYS = [
+    'effort',
+    'permissionMode',
+];
+/**
+ * The init message's facts, or null for every other message.
+ *
+ * Reading it here rather than above the seam keeps the SDK's message union on this side; the layer
+ * above branches on a plain record.
+ */
+export function readInitFacts(message) {
+    if (message.type !== 'system' || message.subtype !== 'init')
+        return null;
+    return {
+        sessionId: message.session_id,
+        cliVersion: message.claude_code_version,
+        cwd: message.cwd,
+        model: message.model,
+        permissionMode: message.permissionMode,
+        apiKeySource: message.apiKeySource,
+        tools: message.tools,
+        skills: message.skills,
+        // Guarded for the same reason as `mcp_servers` below: `plugins` is declared required and read
+        // with `.map(…)`, the identical shape, the identical runtime-wins argument, the identical
+        // `TypeError`. Every member of this class is guarded, not only the one observed failing.
+        plugins: (message.plugins ?? []).map((plugin) => ({
+            name: plugin.name,
+            path: plugin.path,
+            version: plugin.version ?? null,
+        })),
+        capabilities: message.capabilities ?? [],
+        // Guarded though the type says required. `mcp_servers` is declared non-optional on the init
+        // message, so `message.mcp_servers.map(…)` typechecks, and this package's rule is that the
+        // runtime wins over the types. An init message without the field would throw a TypeError inside
+        // `readInitFacts`, and the pump's own catch would convert the throw into `process_failed`: the
+        // session ends, and the reader's bug is reported as the agent process dying. `capabilities` one
+        // line up is guarded for the same reason, and it at least has `?` in the type as a warning.
+        //
+        // The cost of an unguarded read is misattribution, not silence. This read has exactly one
+        // caller, `HostedSession.#pump`, which calls it before and outside the per-listener try/catch,
+        // so nothing swallows it: the enclosing catch finishes the session as `process_failed`, closes
+        // the process, releases the registry entry, refuses every `whenLive` waiter and puts a
+        // transition to `ended` on the wire. `state/observer.ts` contains no catch at all, so no
+        // observer wrapper can eat the throw.
+        mcpServers: (message.mcp_servers ?? []).map((server) => ({ name: server.name, status: server.status })),
+    };
+}
+/**
+ * The message stream, and ONLY the message stream.
+ *
+ * `return` and `throw` are delegated, not just `next`. `for await…of` calls `iterator.return()`
+ * when the loop leaves early — a `break`, a `return`, or a throw inside the body — and that call is
+ * what lets the underlying query release the subprocess. A wrapper implementing only `next` would
+ * swallow it, leaking a session per abandoned loop with no error, no log and nothing null: exactly
+ * the silent-loss shape this package is built against. Pinned by agent-process.test.ts.
+ *
+ * Exported for that pin. It is not part of the package's public surface.
+ */
+export function messagesOf(source) {
+    return {
+        next: (...args) => source.next(...args),
+        return: (value) => source.return(value),
+        throw: (error) => source.throw(error),
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}
+/** Start an agent process. The subprocess exists when this returns. */
+export function startAgentProcess(request) {
+    const input = new AsyncQueue();
+    const options = {
+        cwd: request.cwd,
+        env: request.env,
+        settingSources: [...request.settingSources],
+        includePartialMessages: request.includePartialMessages,
+        forwardSubagentText: request.forwardSubagentText,
+        ...(request.thinking === null ? {} : { thinking: request.thinking }),
+        ...(request.mcpServers === null ? {} : { mcpServers: { ...request.mcpServers } }),
+        ...(request.strictMcpConfig === null ? {} : { strictMcpConfig: request.strictMcpConfig }),
+        // `persistSession` is deliberately never composed: the mirror runs after the local write, so a
+        // store cannot be combined with local persistence off. Leaving the SDK's default in place is
+        // what makes that combination unbuildable here rather than merely undocumented.
+        ...(request.sessionStore === null ? {} : { sessionStore: request.sessionStore }),
+        ...(request.sessionStoreFlush === null ? {} : { sessionStoreFlush: request.sessionStoreFlush }),
+        ...(request.plugins === null ? {} : { plugins: [...request.plugins] }),
+        ...(request.hooks === null ? {} : { hooks: request.hooks }),
+        ...(request.resume === null ? {} : { resume: request.resume, forkSession: request.fork }),
+        ...(request.onStderr === null ? {} : { stderr: request.onStderr }),
+        ...(request.spawn === null ? {} : { spawnClaudeCodeProcess: request.spawn }),
+        // Omitted rather than passed as null when unset, like every other optional above: the SDK reads
+        // an absent key as "use the default" and a present-but-null one as a value it must interpret.
+        ...(request.model === null ? {} : { model: request.model }),
+        ...(request.systemPrompt === null ? {} : { systemPrompt: request.systemPrompt }),
+        ...(request.effort === null ? {} : { effort: request.effort }),
+        ...(request.permissionMode === null ? {} : { permissionMode: request.permissionMode }),
+    };
+    const running = query({ prompt: input, options });
+    let closed = false;
+    return {
+        messages: messagesOf(running),
+        prompt(text) {
+            if (closed)
+                return false;
+            // `session_id` and `uuid` are optional on this type and deliberately left off: the agent
+            // stamps its own. Sending an empty string would be a PRESENT id that is blank, which is a
+            // different and worse thing than an absent one.
+            const message = {
+                type: 'user',
+                message: { role: 'user', content: [{ type: 'text', text }] },
+                parent_tool_use_id: null,
+            };
+            input.push(message);
+            return true;
+        },
+        async interrupt() {
+            if (closed)
+                return;
+            // The SDK's receipt names which queued messages survived the interrupt. Not surfaced here:
+            // acting on it needs the turn model, which belongs to the layer that owns turns.
+            await running.interrupt();
+        },
+        async setModel(model) {
+            if (closed)
+                return;
+            // `undefined`, never null: the SDK reads undefined as "the default" and null as a model named null.
+            await running.setModel(model ?? undefined);
+        },
+        async setPermissionMode(mode) {
+            if (closed)
+                return;
+            await running.setPermissionMode(mode);
+        },
+        async setThinking(thinking) {
+            if (closed)
+                return;
+            // The SDK's LIVE setter is the token cap, and on current models it is on/off: 0 = disabled,
+            // null = the default (adaptive). A fixed budget is REJECTED by Opus 5 / Sonnet 5 / Fable, so an
+            // `enabled` ask maps to adaptive rather than to a 400. The DISPLAY rides along: `summarized` when
+            // asked, because the models' default (`omitted`) streams thinking blocks with empty text — the
+            // "no thinking" an operator sees while paying for it.
+            const cap = thinking.type === 'disabled' ? 0 : null;
+            const display = thinking.type === 'disabled' ? undefined : thinking.display;
+            await running.setMaxThinkingTokens(cap, display);
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            input.end();
+            running.close();
+        },
+    };
+}
+//# sourceMappingURL=agent-process.js.map

package/dist/host/bulk-post.d.ts

@@ -0,0 +1,44 @@
+import type { Result } from '../core/result.js';
+export interface BulkPostRequest {
+    readonly deliveryId: string;
+    readonly postUrl: string;
+    /**
+     * The only origin this delivery may reach. Required, with no default, and that is the mechanism
+     * rather than a style.
+     *
+     * `postUrl` is chosen by the peer and arrives verbatim on the wire; this is the value that says
+     * which peer the host actually works for. An optional field defaulting to "no binding" would let
+     * every present and future caller inherit a fail-open nobody picked. Required, the compiler
+     * forces each caller to name the origin it trusts.
+     *
+     * Compute it with {@link bulkOriginFor}, which is the only thing that knows how to turn the
+     * host's configured `ws(s)://` controller URL into the `http(s)://` origin a POST lands on.
+     */
+    readonly allowedOrigin: string;
+    /** Absolute. A relative path means "relative to a cwd the controller cannot see". */
+    readonly filePath: string;
+    readonly fromOffset: number;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * The host's ONE controller origin, derived from the link URL it already dials.
+ *
+ * Derived, never separately configured. The host dials `controllerUrl` and trusts whatever
+ * answers it; the bulk POST goes to the same deployment over plain HTTP. Reading a second setting
+ * would create a way for the two to disagree, and a host whose "trusted origin" is configured apart
+ * from the one it actually talks to is a host that can be pointed at two peers at once.
+ */
+export declare function bulkOriginFor(controllerUrl: string): Result<string>;
+export interface BulkPostReceipt {
+    readonly deliveryId: string;
+    readonly byteCount: number;
+    /**
+     * The file's stat at the moment the delivery was read (size total, mtime as floored epoch ms).
+     * Carried so a transcript puller can detect the CLI rewriting the file under it — a byte-offset
+     * resume across a rewrite is invalid, and only the deliverer's own stat can say.
+     */
+    readonly sizeBytes: number;
+    readonly mtimeMs: number;
+}
+export declare function postBulk(request: BulkPostRequest): Promise<Result<BulkPostReceipt>>;
+//# sourceMappingURL=bulk-post.d.ts.map

package/dist/host/bulk-post.js

@@ -0,0 +1,114 @@
+/**
+ * The host half of the bulk lane: bytes leave over an outbound HTTP POST, never over the link.
+ *
+ * The link carries a locator and gets back a receipt; the content travels here. That inversion is
+ * what keeps a megabyte transcript off a socket that also carries the transitions telling you what
+ * a session is doing — a single large frame would otherwise stall every session sharing the link.
+ *
+ * The read is streamed. Buffering a whole transcript to send it would block the event loop for
+ * every other session this host is serving, which is the same failure in a different costume.
+ */
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { ok, refuse } from '../core/result.js';
+import { requireAbsolute } from '../core/paths.js';
+/**
+ * The host's ONE controller origin, derived from the link URL it already dials.
+ *
+ * Derived, never separately configured. The host dials `controllerUrl` and trusts whatever
+ * answers it; the bulk POST goes to the same deployment over plain HTTP. Reading a second setting
+ * would create a way for the two to disagree, and a host whose "trusted origin" is configured apart
+ * from the one it actually talks to is a host that can be pointed at two peers at once.
+ */
+export function bulkOriginFor(controllerUrl) {
+    let parsed;
+    try {
+        parsed = new URL(controllerUrl);
+    }
+    catch {
+        return refuse('bulk-target-invalid', `the configured controller URL is not a URL: ${controllerUrl}`);
+    }
+    // The link speaks WebSocket and the bulk lane speaks HTTP against the SAME deployment, so the
+    // scheme is mapped rather than compared: `wss://host:8443/periscope/link` and
+    // `https://host:8443/periscope/bulk/<id>` are one controller, and `URL.origin` alone would call
+    // them different peers.
+    const scheme = parsed.protocol === 'ws:' ? 'http:' : parsed.protocol === 'wss:' ? 'https:' : parsed.protocol;
+    if (scheme !== 'http:' && scheme !== 'https:') {
+        return refuse('bulk-target-invalid', `a controller URL cannot carry scheme ${parsed.protocol}`);
+    }
+    return ok(`${scheme}//${parsed.host}`);
+}
+export async function postBulk(request) {
+    const absolute = requireAbsolute(request.filePath);
+    if (!absolute.ok)
+        return { ok: false, refusal: absolute.refusal };
+    let target;
+    try {
+        target = new URL(request.postUrl);
+    }
+    catch {
+        return refuse('bulk-target-invalid', `not a URL: ${request.postUrl}`);
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+        return refuse('bulk-target-invalid', `unsupported scheme: ${target.protocol}`);
+    }
+    // The destination is the peer's choice; whether it is reached is not.
+    //
+    // The caller attaches this host's durable, non-expiring paired credential to the request (see
+    // `host.ts`'s `#deliver`). With a credential riding along, a peer-named `postUrl` is an
+    // exfiltration surface: any code path that can compose a `BulkRequest` could name
+    // `http://attacker.example/x` and receive the operator's transcript and the device credential
+    // that outlives the discovery of the theft.
+    //
+    // Checked after the scheme, on purpose. A garbled URL should still say it is garbled; this reason
+    // is reserved for a target that is well-formed and simply is not this host's controller.
+    if (target.origin !== request.allowedOrigin) {
+        return refuse('bulk-target-not-controller', `refusing to deliver to ${target.origin}: this host posts bulk content only to its own ` +
+            `controller at ${request.allowedOrigin}. The destination rides the wire, so a peer that ` +
+            `names another origin is asking for the transcript AND this host's durable credential`);
+    }
+    try {
+        const stats = await stat(absolute.value);
+        const start = Math.min(Math.max(0, request.fromOffset), stats.size);
+        const byteCount = stats.size - start;
+        // Bounded to the bytes the header promised. `content-length` is declared from the stat above,
+        // but the stream was opened after it: reading a live transcript (the headline use case) lets
+        // the CLI append between the two, so an unbounded stream drains past the declared length and
+        // the delivery dies as `bulk-delivery-failed`, a name that blames the delivery for a file that
+        // simply moved. The end offset is inclusive, hence the -1.
+        //
+        // The zero-byte arm is not `end: start - 1`: `end` must be a non-negative integer, so an
+        // empty delivery at offset 0 would throw rather than send nothing. An empty stream is the
+        // honest encoding of "the header promised no bytes".
+        const stream = byteCount > 0
+            ? createReadStream(absolute.value, { start, end: start + byteCount - 1 })
+            : Readable.from([]);
+        const response = await fetch(target, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/octet-stream',
+                'content-length': String(byteCount),
+                'x-delivery-id': request.deliveryId,
+                ...request.headers,
+            },
+            body: Readable.toWeb(stream),
+            // Required by undici whenever the body is a stream: the request body is still being sent
+            // while the response is read. Without it the fetch rejects before a byte moves.
+            duplex: 'half',
+        });
+        if (!response.ok) {
+            return refuse('bulk-delivery-failed', `controller answered ${response.status} ${response.statusText} for delivery ${request.deliveryId}`);
+        }
+        return ok({
+            deliveryId: request.deliveryId,
+            byteCount,
+            sizeBytes: stats.size,
+            mtimeMs: Math.floor(stats.mtimeMs),
+        });
+    }
+    catch (error) {
+        return refuse('bulk-delivery-failed', `delivery ${request.deliveryId} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=bulk-post.js.map

package/dist/host/claude-transcripts.d.ts

@@ -0,0 +1,84 @@
+import type { Result } from '../core/result.js';
+/**
+ * The strict name allowlist — drive/path characters only. `'.'` and `'..'` PASS this regex, which
+ * is exactly why the dot-name reject below is its own layer rather than a tightening of this one.
+ */
+export declare const NAME_ALLOWLIST: RegExp;
+/**
+ * The agent's home when nothing configures one: the folder the agent CLI keeps its state in, under
+ * the user's home directory. Null when there is no home to derive it from — a refusable state,
+ * never a fallback: inventing one would turn "this machine has no home directory" into a silent
+ * empty listing that reads as a fresh machine.
+ */
+export declare function defaultAgentHome(env?: NodeJS.ProcessEnv): string | null;
+/** Where the agent CLI keeps transcripts under its home: derived, never configured on its own. */
+export declare function transcriptsRootUnder(agentHome: string): string;
+/** The transcripts root under the default agent home, or null when there is no home. */
+export declare function claudeProjectsRoot(env?: NodeJS.ProcessEnv): string | null;
+/** One transcript on disk. `mtimeMs` is a floored integer so equality against a stamp holds. */
+export interface DiscoveredTranscript {
+    readonly projectSlug: string;
+    readonly sessionId: string;
+    readonly sizeBytes: number;
+    readonly mtimeMs: number;
+    /**
+     * The working directory the CLI recorded on its entries, read off the file's own head, never
+     * decoded from the slug (the flattening is not invertible). The resume handle's other half: the
+     * CLI keeps transcripts per cwd, so a resume that does not run there finds nothing. Null when the
+     * head carries none.
+     */
+    readonly cwd: string | null;
+}
+export interface TranscriptPage {
+    readonly entries: readonly DiscoveredTranscript[];
+    readonly totalCount: number;
+    /** Ask again from here for the next page; null when this page ends the listing. */
+    readonly nextIndex: number | null;
+}
+/** What a tail probe answers. `absent` true means the transcript does not exist — a real negative. */
+export interface TranscriptTailAnswer {
+    readonly absent: boolean;
+    readonly found: boolean;
+    readonly newOffset: number;
+    readonly sizeBytes: number | null;
+    readonly mtimeMs: number | null;
+}
+/**
+ * THE JAIL. Resolve `{root}/{projectSlug}/{sessionId}.jsonl` with all three layers applied to both
+ * caller-supplied names. The one path-shaping function in this module — list, tail and the bulk
+ * resolver all come through here, so there is no second door to keep honest.
+ */
+export declare function resolveTranscriptPath(root: string, projectSlug: string, sessionId: string): Result<string>;
+/**
+ * Enumerate every session transcript: direct-child `*.jsonl` per slug directory (nested files are
+ * the CLI's subagent transcripts and are not part of this listing). Newest first by mtime, paged.
+ * A missing root is a fresh machine and answers an empty listing, never an error; a file deleted
+ * between readdir and stat is skipped for the same reason.
+ */
+export declare function listTranscripts(root: string, page?: {
+    fromIndex?: number;
+    pageSize?: number;
+}): Promise<TranscriptPage>;
+/**
+ * Probe one transcript from `fromOffset` for a user entry matching `needle` (null = any user-text
+ * entry). Jail violations refuse; an absent file answers `{absent: true}`; a read that FAILS is a
+ * refusal (`transcript-read-failed`), never a false negative — to the asker "no new entry" and
+ * "could not look" must not be the same answer.
+ */
+export declare function tailTranscript(root: string, projectSlug: string, sessionId: string, probe?: {
+    fromOffset?: number;
+    needle?: string | null;
+}): Promise<Result<TranscriptTailAnswer>>;
+/**
+ * The bulk-lane resolver for transcript reads: `claude-transcript:{slug}/{sessionId}` to a jailed
+ * absolute path. A locator outside the namespace is refused as an invalid bulk target so an
+ * embedder composing several resolvers can tell "not mine" from "mine and malformed".
+ */
+export declare function claudeTranscriptResolver(root: string): (what: string, sessionKey: string) => Result<string>;
+/**
+ * One line: does it count as a matching user entry? Unparseable or foreign lines are skipped,
+ * never thrown — a truncated LAST line is the normal state of a file being appended to. A
+ * tool-result-only user line has no text block and so never matches.
+ */
+export declare function isMatchingUserEntry(line: string, needle: string | null): boolean;
+//# sourceMappingURL=claude-transcripts.d.ts.map