@naswerks/periscope 1.0.0

package/dist/mcp/schema.js

@@ -0,0 +1,175 @@
+/**
+ * JSON-Schema to Zod raw shape, because that is the shape the SDK's `tool()` actually takes.
+ *
+ * Why a conversion exists at all. `SdkMcpToolDefinition<Schema extends AnyZodRawShape>` is generic
+ * over a Zod raw shape — a plain record of Zod types, not a schema object and not JSON Schema. A
+ * design in which descriptors carry `inputSchema: JsonSchema` and the host does
+ * `validate(input, d.inputSchema)` does not compile against the shipped types. A controller in
+ * another language cannot express Zod shapes, so the conversion happens here and the descriptor
+ * contract stays JSON.
+ *
+ * An unconvertible construct is refused. Never widened, never `z.any()`, never skipped.
+ * This is the most consequential line in the directory. A converter that met something it did not
+ * recognise and fell back to a permissive schema would register the tool successfully and validate
+ * nothing — so "a malformed call is rejected before it reaches the controller" would be silently
+ * false for exactly the tools nobody looked at, while every test stayed green and the tool appeared
+ * to work. That is a false green in the highest-consequence direction: the failure is invisible
+ * precisely where the checking was supposed to be. Refusing happens at registration, before any
+ * session exists, and names the construct that could not be converted.
+ *
+ * The subset is deliberately small — what a controller emits for a tool's arguments. Growing it is
+ * a normal change; growing it by accident is what the refusal prevents.
+ */
+import { z } from 'zod';
+import { ok, refuse } from '../core/result.js';
+import { SUPPORTED_SCHEMA_TYPES } from './descriptor.js';
+/**
+ * Convert a tool's input schema into a raw shape.
+ *
+ * An object with no properties converts to an empty shape rather than being refused — a tool that
+ * takes no arguments is ordinary, and refusing it would force every caller to invent a parameter.
+ */
+export function toRawShape(schema, at = 'inputSchema') {
+    if (!isRecordLike(schema)) {
+        return refuse('mcp-schema-unsupported', `${at} is not an object`);
+    }
+    if (schema.type !== undefined && schema.type !== 'object') {
+        // A tool's arguments are always a named set. A top-level array or string has no property names
+        // to become a shape's keys, so there is nothing to convert it into.
+        return refuse('mcp-schema-unsupported', `${at} must be an object schema, not ${String(schema.type)} — a tool's arguments are always named`);
+    }
+    const properties = schema.properties ?? {};
+    if (!isRecordLike(properties)) {
+        return refuse('mcp-schema-unsupported', `${at}.properties is not an object`);
+    }
+    const required = new Set(schema.required ?? []);
+    for (const name of required) {
+        if (!(name in properties)) {
+            // A required property with no definition would silently vanish from the shape, so a call
+            // omitting it would pass — the schema says it is mandatory and nothing would enforce that.
+            return refuse('mcp-schema-unsupported', `${at}.required names "${name}", which has no entry in properties`);
+        }
+    }
+    const shape = {};
+    for (const [name, node] of Object.entries(properties)) {
+        const converted = toZod(node, `${at}.properties.${name}`);
+        if (!converted.ok)
+            return refuse(converted.refusal.reason, converted.refusal.detail);
+        // Optional is the default, exactly as JSON Schema says: a property is required only when
+        // `required` names it. Getting this backwards would make every argument mandatory and every
+        // legitimate call fail.
+        shape[name] = required.has(name) ? converted.value : converted.value.optional();
+    }
+    return ok(shape);
+}
+/** Convert one node. Recursive for `array` and `object`. */
+export function toZod(node, at) {
+    if (!isRecordLike(node)) {
+        return refuse('mcp-schema-unsupported', `${at} is not a schema object`);
+    }
+    const base = baseType(node, at);
+    if (!base.ok)
+        return base;
+    let schema = base.value;
+    if (node.nullable === true)
+        schema = schema.nullable();
+    if (typeof node.description === 'string' && node.description !== '') {
+        // Carried because the model reads it. A converted schema that dropped descriptions would produce
+        // tools whose arguments are undocumented to the only reader that matters.
+        schema = schema.describe(node.description);
+    }
+    return ok(schema);
+}
+function baseType(node, at) {
+    // `enum` wins over `type`: a closed set of literals is a stronger statement than the type of its
+    // members, and an emitter that sends both means the enum.
+    if (node.enum !== undefined)
+        return fromEnum(node.enum, at);
+    if (node.type === undefined) {
+        // A typeless node is refused, and this is the case a fallback would swallow. In
+        // JSON Schema, no `type` means "anything" — so converting it to a permissive schema is the
+        // literally correct reading and also the one that turns validation off for that property
+        // without saying so.
+        return refuse('mcp-schema-unsupported', `${at} declares no type, which would accept any value — state a type or an enum rather than validating nothing`);
+    }
+    switch (node.type) {
+        case 'string':
+            return ok(z.string());
+        case 'boolean':
+            return ok(z.boolean());
+        case 'number':
+            return ok(z.number());
+        case 'integer':
+            return ok(z.number().int());
+        case 'array':
+            return fromArray(node, at);
+        case 'object':
+            return fromObject(node, at);
+        default:
+            return refuse('mcp-schema-unsupported', `${at} has type "${String(node.type)}", which this host cannot convert — supported: ${SUPPORTED_SCHEMA_TYPES.join(', ')}`);
+    }
+}
+function fromArray(node, at) {
+    if (node.items === undefined) {
+        // An array with no `items` accepts a list of anything, which is the same hole as a typeless
+        // property one level down.
+        return refuse('mcp-schema-unsupported', `${at} is an array with no items schema, so its elements would not be validated at all`);
+    }
+    const items = toZod(node.items, `${at}.items`);
+    if (!items.ok)
+        return items;
+    return ok(z.array(items.value));
+}
+function fromObject(node, at) {
+    const properties = node.properties ?? {};
+    if (!isRecordLike(properties)) {
+        return refuse('mcp-schema-unsupported', `${at}.properties is not an object`);
+    }
+    if (Object.keys(properties).length === 0) {
+        return refuse('mcp-schema-unsupported', `${at} is an object with no properties, so any object would satisfy it`);
+    }
+    const required = new Set(node.required ?? []);
+    const shape = {};
+    for (const [name, child] of Object.entries(properties)) {
+        const converted = toZod(child, `${at}.properties.${name}`);
+        if (!converted.ok)
+            return converted;
+        shape[name] = required.has(name) ? converted.value : converted.value.optional();
+    }
+    return ok(z.object(shape));
+}
+function fromEnum(values, at) {
+    if (!Array.isArray(values) || values.length === 0) {
+        return refuse('mcp-schema-unsupported', `${at}.enum is empty, so no value could satisfy it`);
+    }
+    const literals = [];
+    for (const value of values) {
+        if (typeof value !== 'string' &&
+            typeof value !== 'number' &&
+            typeof value !== 'boolean' &&
+            value !== null) {
+            return refuse('mcp-schema-unsupported', `${at}.enum carries a non-primitive value (${JSON.stringify(value)}); only strings, numbers, booleans and null convert`);
+        }
+        literals.push(value === null ? z.null() : z.literal(value));
+    }
+    const [first, second, ...rest] = literals;
+    if (first === undefined) {
+        return refuse('mcp-schema-unsupported', `${at}.enum is empty`);
+    }
+    // A one-value enum is a literal; a union needs at least two members.
+    if (second === undefined)
+        return ok(first);
+    return ok(z.union([first, second, ...rest]));
+}
+/**
+ * A plain object, checked at runtime without narrowing the compile-time type.
+ *
+ * It returns `boolean`, not a type predicate, on purpose. These values arrive typed as schema
+ * nodes but come off the wire, so the check has to run — and a predicate would re-narrow an already
+ * precise type down to `Record<string, unknown>`, turning every child node into `unknown` and
+ * forcing casts back to the type the caller already had.
+ */
+function isRecordLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=schema.js.map

package/dist/mcp/server.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Descriptors in, tool plans out — the whole registration path, with no SDK anywhere in it.
+ *
+ * Why this file stops short of the SDK. Only `src/host/` names `@anthropic-ai/claude-agent-sdk`,
+ * pinned by pins/sdk-confinement.test.ts, so that one directory answers "what can start a process
+ * here?". Building an in-process MCP server is not a spawn — but the rule is about the specifier,
+ * not about which of the package's functions happen to be dangerous, and weakening it for a safe
+ * call is how the boundary stops meaning anything. So the decisions live here and
+ * `host/mcp-server.ts` turns a plan into an actual server. Exactly the split the path jail uses
+ * (`gate/jail.ts` pure, `host/paths.ts` real) and the workspace providers use.
+ *
+ * The payoff is the same one it always is: the generic pin can fingerprint a plan and compare two
+ * registrations without an SDK object anywhere near the test.
+ *
+ * The host never learns what a tool means. Every tool takes one path: validate the descriptor,
+ * convert the schema it was handed, check a call's arguments against that schema, attach session
+ * identity, forward to the invoker, return the answer. There is no branch on a tool's name anywhere
+ * — pinned by pins/mcp-generic.test.ts, which plans the same descriptors under permuted names and
+ * requires the results to be identical.
+ *
+ * No `MCP_TIMEOUT` knob, deliberately. A 30-second connect window lost under a spawn storm, and a
+ * CLI that never reconnects a failed stdio server, are process-transport failures. An in-process
+ * server never connects, so it cannot lose a race and has nothing to reconnect. Porting the knob
+ * anyway would document a failure mode this design does not have.
+ */
+import type { JsonObject } from '../control/frames.js';
+import type { Result } from '../core/result.js';
+import type { ToolDescriptor } from './descriptor.js';
+import type { ZodRawShape } from './schema.js';
+/** Which session a call came from. Read at call time — see `identity` below. */
+export interface ToolCallIdentity {
+    /**
+     * The agent's own session id, or null before it has reported one.
+     *
+     * Null is reachable and is not an error. An agent does not report itself until its first turn
+     * has been queued, so a server composed at session start genuinely has no id yet. An invoker
+     * receiving null knows the call arrived before the agent named itself, which is information —
+     * inventing a placeholder id would destroy it.
+     */
+    readonly sessionId: string | null;
+}
+/** One forwarded call, in the invoker's terms. */
+export interface ToolCall {
+    readonly serverName: string;
+    readonly toolName: string;
+    /** Already validated against the tool's own schema. */
+    readonly arguments: JsonObject;
+    readonly identity: ToolCallIdentity;
+}
+/** What the invoker answers with. */
+export interface ToolResponse {
+    readonly text: string;
+    /** Reported to the model as an error result. Defaults to false. */
+    readonly isError?: boolean;
+}
+/** How a validated call reaches the embedder's invoker, the only thing that knows what a tool does. */
+export type ToolInvoker = (call: ToolCall) => Promise<ToolResponse>;
+/**
+ * A tool result in the shape MCP expects. Structural, so this file needs no SDK type.
+ *
+ * `content` is mutable, against this package's habit, because the SDK's own result type declares a
+ * mutable array and a `readonly` one is not assignable to it. Stated rather than left as a puzzle:
+ * the alternative is a cast at the seam, which would hide any future divergence in that shape.
+ */
+export interface ToolResult {
+    readonly content: {
+        type: 'text';
+        text: string;
+    }[];
+    readonly isError?: boolean;
+}
+/**
+ * One tool, ready to be handed to the SDK.
+ *
+ * Everything about a tool that this package decides. `host/mcp-server.ts` adds nothing but the
+ * SDK call — which is what makes a plan a complete and checkable statement of the registration.
+ */
+export interface ToolPlan {
+    readonly name: string;
+    readonly description: string;
+    readonly shape: ZodRawShape;
+    readonly handler: (args: unknown) => Promise<ToolResult>;
+}
+export interface McpServerOptions {
+    /** The server's name. Tools reach the model as `mcp__{name}__{tool}`. */
+    readonly name: string;
+    readonly version?: string;
+    readonly descriptors: readonly ToolDescriptor[];
+    readonly invoke: ToolInvoker;
+    /**
+     * Session identity, read at call time rather than captured at composition time.
+     *
+     * A function, not a value, and the reason is a measured SDK property. The server has to exist
+     * before `query()` is called, and the agent does not report its session id until its first turn
+     * has been queued — so a value captured here would be null forever, on every call, for the whole
+     * session. Reading it lazily is the only shape that can ever carry a real id.
+     */
+    readonly identity: () => ToolCallIdentity;
+}
+/**
+ * Turn descriptors into plans.
+ *
+ * Refuses rather than throwing: this runs before any session exists, and an embedder that supplied an
+ * unusable descriptor needs to be told which one and why.
+ */
+export declare function planTools(options: McpServerOptions): Result<ToolPlan[]>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.js

@@ -0,0 +1,66 @@
+import { ok, refuse } from '../core/result.js';
+import { isUsableToolName } from './descriptor.js';
+import { toRawShape } from './schema.js';
+/**
+ * Turn descriptors into plans.
+ *
+ * Refuses rather than throwing: this runs before any session exists, and an embedder that supplied an
+ * unusable descriptor needs to be told which one and why.
+ */
+export function planTools(options) {
+    if (!isUsableToolName(options.name)) {
+        return refuse('mcp-descriptor-invalid', `"${options.name}" is not a usable server name — letters, digits, hyphen and single underscores only`);
+    }
+    const seen = new Set();
+    const plans = [];
+    for (const descriptor of options.descriptors) {
+        const invalid = rejectDescriptor(descriptor, seen);
+        if (invalid !== null)
+            return invalid;
+        seen.add(descriptor.name);
+        const shape = toRawShape(descriptor.inputSchema, `${descriptor.name}.inputSchema`);
+        if (!shape.ok)
+            return refuse(shape.refusal.reason, shape.refusal.detail);
+        // The handler closes over the tool's name as data. It reads nothing else about the tool and
+        // branches on nothing — every tool in every server runs this identical body.
+        const toolName = descriptor.name;
+        const handler = async (args) => {
+            const response = await options.invoke({
+                serverName: options.name,
+                toolName,
+                arguments: asJsonObject(args),
+                identity: options.identity(),
+            });
+            return {
+                content: [{ type: 'text', text: response.text }],
+                ...(response.isError === true ? { isError: true } : {}),
+            };
+        };
+        plans.push({ name: descriptor.name, description: descriptor.description, shape: shape.value, handler });
+    }
+    return ok(plans);
+}
+function rejectDescriptor(descriptor, seen) {
+    if (typeof descriptor?.name !== 'string' || !isUsableToolName(descriptor.name)) {
+        return refuse('mcp-descriptor-invalid', `"${String(descriptor?.name)}" is not a usable tool name — letters, digits, hyphen and single underscores only`);
+    }
+    if (typeof descriptor.description !== 'string' || descriptor.description.trim() === '') {
+        // The description is the only thing that tells the model what the tool is for. A tool without
+        // one is registered, callable, and never called — which looks like a broken tool, not a bad
+        // descriptor.
+        return refuse('mcp-descriptor-invalid', `tool "${descriptor.name}" has no description`);
+    }
+    if (seen.has(descriptor.name)) {
+        // Two tools with one name: the second silently shadows the first, so an embedder would see
+        // calls it expected to reach one tool arrive at another.
+        return refuse('mcp-descriptor-invalid', `tool "${descriptor.name}" is described twice in one server`);
+    }
+    return null;
+}
+/** The SDK hands the handler its parsed arguments; this narrows them for the wire. */
+function asJsonObject(args) {
+    if (typeof args !== 'object' || args === null || Array.isArray(args))
+        return {};
+    return args;
+}
+//# sourceMappingURL=server.js.map

package/dist/persistence/entry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * One stored line, and the codec that turns a transcript into lines and back.
+ *
+ * Entries are pass-through blobs and this file keeps them that way. The concrete entry shape is
+ * the on-disk transcript format — a large union the CLI owns and the SDK deliberately does not
+ * export, exposing only a structural supertype: a string `type`, usually a `uuid`, usually a
+ * `timestamp`, and opaque JSON for the rest. So nothing here parses an entry into a richer model.
+ * Round-tripping through JSON is the only invariant the adapter contract requires, and it is
+ * therefore the one this file pins.
+ *
+ * A line that will not round-trip is named, never skipped. Skipping is how a transcript loses
+ * entries nobody counted — the reader sees a shorter list and no reason to doubt it, which is the
+ * exact silent-loss shape a receipt read must not sit on top of.
+ */
+import type { Result } from '../core/result.js';
+/** One transcript line. Structurally the adapter contract's entry, under this package's own name. */
+export interface TranscriptEntry {
+    readonly type: string;
+    /** Most entries carry one. Titles, tags and mode markers do not — see `mirror.ts` on dedup. */
+    readonly uuid?: string;
+    readonly timestamp?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * The discriminators that mark an entry as produced by compaction rather than by a turn.
+ *
+ * This list is why a receipt cannot report a false positive, and it is the defence whose failure
+ * direction is opposite to the other two. Compaction replaces earlier turns with a summary, and a
+ * summary is fed back into the conversation as ordinary-looking content. A receipt asking only "is
+ * there a user entry after my anchor?" would match the summary and report a delivery that never
+ * happened — the controller then believes text landed that the agent never saw.
+ *
+ * Kept as data, because the entry union is CLI-internal and this is a structural read of it. If
+ * the format grows another marker, one constant changes and every reader that matters is already
+ * looking at it. `subtype` is the SDK's own word: `SDKCompactBoundaryMessage` carries
+ * `subtype: 'compact_boundary'` alongside its `compact_metadata`.
+ */
+export declare const COMPACTION_SUBTYPES: readonly string[];
+/** Entry `type` values that exist only because a compaction ran. */
+export declare const COMPACTION_TYPES: readonly string[];
+/** The key the boundary's own metadata rides on, named once. */
+export declare const COMPACT_METADATA_KEY = "compact_metadata";
+/**
+ * Whether this entry is the compaction boundary itself — the marker that says a compaction ran here.
+ *
+ * Three independent tells, because the boundary is the one entry a receipt read must never miss:
+ * the SDK's own subtype, the entry type, and the presence of the metadata block the boundary is the
+ * only thing that carries.
+ */
+export declare function isCompactBoundary(entry: TranscriptEntry): boolean;
+/**
+ * Whether this entry exists because a compaction ran — the boundary, or the summary it produced.
+ *
+ * Broader than `isCompactBoundary` on purpose: the boundary is what a reader counts, and this is
+ * what a reader must not mistake for a turn.
+ */
+export declare function isCompactionProduced(entry: TranscriptEntry): boolean;
+/** Whether this entry is a user turn — the thing a delivery receipt is looking for. */
+export declare function isUserEntry(entry: TranscriptEntry): boolean;
+/** One entry as one JSONL line. No trailing newline — the writer joins. */
+export declare function encodeEntry(entry: TranscriptEntry): string;
+/** One JSONL line back to an entry, or a named refusal. */
+export declare function decodeEntry(line: string): Result<TranscriptEntry>;
+/** A whole transcript as JSONL text. */
+export declare function encodeTranscript(entries: readonly TranscriptEntry[]): string;
+/**
+ * JSONL text back to entries.
+ *
+ * Blank lines are skipped because a trailing newline is ordinary and produces one; a line with
+ * content that will not decode is refused, and the refusal names which line so the file can be
+ * looked at. Those are different situations and only one of them is a problem.
+ */
+export declare function decodeTranscript(text: string): Result<TranscriptEntry[]>;
+//# sourceMappingURL=entry.d.ts.map

package/dist/persistence/entry.js

@@ -0,0 +1,105 @@
+import { ok, refuse } from '../core/result.js';
+/**
+ * The discriminators that mark an entry as produced by compaction rather than by a turn.
+ *
+ * This list is why a receipt cannot report a false positive, and it is the defence whose failure
+ * direction is opposite to the other two. Compaction replaces earlier turns with a summary, and a
+ * summary is fed back into the conversation as ordinary-looking content. A receipt asking only "is
+ * there a user entry after my anchor?" would match the summary and report a delivery that never
+ * happened — the controller then believes text landed that the agent never saw.
+ *
+ * Kept as data, because the entry union is CLI-internal and this is a structural read of it. If
+ * the format grows another marker, one constant changes and every reader that matters is already
+ * looking at it. `subtype` is the SDK's own word: `SDKCompactBoundaryMessage` carries
+ * `subtype: 'compact_boundary'` alongside its `compact_metadata`.
+ */
+export const COMPACTION_SUBTYPES = ['compact_boundary'];
+/** Entry `type` values that exist only because a compaction ran. */
+export const COMPACTION_TYPES = ['summary', 'compact_boundary'];
+/** The key the boundary's own metadata rides on, named once. */
+export const COMPACT_METADATA_KEY = 'compact_metadata';
+/**
+ * Whether this entry is the compaction boundary itself — the marker that says a compaction ran here.
+ *
+ * Three independent tells, because the boundary is the one entry a receipt read must never miss:
+ * the SDK's own subtype, the entry type, and the presence of the metadata block the boundary is the
+ * only thing that carries.
+ */
+export function isCompactBoundary(entry) {
+    const subtype = entry['subtype'];
+    if (typeof subtype === 'string' && COMPACTION_SUBTYPES.includes(subtype))
+        return true;
+    if (entry.type === 'compact_boundary')
+        return true;
+    return Object.prototype.hasOwnProperty.call(entry, COMPACT_METADATA_KEY);
+}
+/**
+ * Whether this entry exists because a compaction ran — the boundary, or the summary it produced.
+ *
+ * Broader than `isCompactBoundary` on purpose: the boundary is what a reader counts, and this is
+ * what a reader must not mistake for a turn.
+ */
+export function isCompactionProduced(entry) {
+    if (isCompactBoundary(entry))
+        return true;
+    if (COMPACTION_TYPES.includes(entry.type))
+        return true;
+    return entry['isCompactSummary'] === true;
+}
+/** Whether this entry is a user turn — the thing a delivery receipt is looking for. */
+export function isUserEntry(entry) {
+    return entry.type === 'user';
+}
+/** One entry as one JSONL line. No trailing newline — the writer joins. */
+export function encodeEntry(entry) {
+    return JSON.stringify(entry);
+}
+/** One JSONL line back to an entry, or a named refusal. */
+export function decodeEntry(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return refuse('transcript-entry-malformed', `line is not JSON: ${preview(line)}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return refuse('transcript-entry-malformed', `line is not a JSON object: ${preview(line)}`);
+    }
+    const record = parsed;
+    if (typeof record['type'] !== 'string') {
+        return refuse('transcript-entry-malformed', `entry has no string "type" discriminant: ${preview(line)}`);
+    }
+    return ok(record);
+}
+/** A whole transcript as JSONL text. */
+export function encodeTranscript(entries) {
+    return entries.map(encodeEntry).join('\n');
+}
+/**
+ * JSONL text back to entries.
+ *
+ * Blank lines are skipped because a trailing newline is ordinary and produces one; a line with
+ * content that will not decode is refused, and the refusal names which line so the file can be
+ * looked at. Those are different situations and only one of them is a problem.
+ */
+export function decodeTranscript(text) {
+    const entries = [];
+    const lines = text.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = (lines[index] ?? '').trim();
+        if (line.length === 0)
+            continue;
+        const decoded = decodeEntry(line);
+        if (!decoded.ok) {
+            return refuse(decoded.refusal.reason, `line ${index + 1}: ${decoded.refusal.detail}`);
+        }
+        entries.push(decoded.value);
+    }
+    return ok(entries);
+}
+function preview(line) {
+    const trimmed = line.trim();
+    return trimmed.length <= 80 ? trimmed : `${trimmed.slice(0, 80)}…`;
+}
+//# sourceMappingURL=entry.js.map

package/dist/persistence/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Transcript durability, the receipt read path, and the durable transition log.
+ *
+ * The one rule a consumer must not get wrong: a receipt, an audit, or any "what actually
+ * happened?" question is answered from raw stored entries — `store.load(key)` or the local JSONL —
+ * and never from the SDK's conversation reader, which returns the post-compaction view. "What would
+ * the agent see?" is the other question and the other read. `receipt.ts` carries the reasoning.
+ */
+export type { TranscriptKey } from './key.js';
+export { sameTranscript, transcriptKey, transcriptToken } from './key.js';
+export type { TranscriptEntry } from './entry.js';
+export { COMPACTION_SUBTYPES, COMPACTION_TYPES, COMPACT_METADATA_KEY, decodeEntry, decodeTranscript, encodeEntry, encodeTranscript, isCompactBoundary, isCompactionProduced, isUserEntry, } from './entry.js';
+export type { ReceiptOutcome, ReceiptQuery } from './receipt.js';
+export { baselineAnchor, compactionCount, resolveReceipt } from './receipt.js';
+export { ABANDONED_ENTRY_TYPE, TRANSITION_ENTRY_TYPE, abandonmentsIn, decodeTransition, encodeTransition, markAbandoned, transitionUuid, transitionsIn, } from './transition-log.js';
+export type { RetentionPlan, RetentionPolicy } from './retention.js';
+export { entryTimeMs, markOutlivesSubject, planRetention } from './retention.js';
+export type { DedupedBatch, MirrorDrop, MirrorFailureKind } from './mirror.js';
+export { MIRROR_ATTEMPTS, dedupeBatch, describeMirrorDrop, uuidsIn } from './mirror.js';
+export type { JsonlStoreOptions, StoreEffects, StoredSession, TranscriptStore } from './store.js';
+export { createJsonlStore } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/persistence/index.js

@@ -0,0 +1,8 @@
+export { sameTranscript, transcriptKey, transcriptToken } from './key.js';
+export { COMPACTION_SUBTYPES, COMPACTION_TYPES, COMPACT_METADATA_KEY, decodeEntry, decodeTranscript, encodeEntry, encodeTranscript, isCompactBoundary, isCompactionProduced, isUserEntry, } from './entry.js';
+export { baselineAnchor, compactionCount, resolveReceipt } from './receipt.js';
+export { ABANDONED_ENTRY_TYPE, TRANSITION_ENTRY_TYPE, abandonmentsIn, decodeTransition, encodeTransition, markAbandoned, transitionUuid, transitionsIn, } from './transition-log.js';
+export { entryTimeMs, markOutlivesSubject, planRetention } from './retention.js';
+export { MIRROR_ATTEMPTS, dedupeBatch, describeMirrorDrop, uuidsIn } from './mirror.js';
+export { createJsonlStore } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/persistence/key.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which transcript — the address of one session's stored entries.
+ *
+ * This is this package's own type, not the SDK's, and the duplication is deliberate. The store
+ * adapter's key is an SDK type, and `src/host/` is the only directory allowed to name the SDK
+ * (pinned by pins/sdk-confinement.test.ts). Everything worth testing about a key — what is refused,
+ * how a subagent's transcript is addressed, how one becomes a storage path — is pure logic, so it
+ * lives here and `host/session-store.ts` bridges the two shapes. The same split the workspace
+ * providers and the path jail already use.
+ *
+ * The three fields are structurally the adapter contract's, and that is the point: bridging is a
+ * field-for-field copy with nothing to get wrong, and a shape change on either side is a compile
+ * error in one file rather than a silent mismatch.
+ */
+import type { Result } from '../core/result.js';
+/**
+ * One transcript, addressed.
+ *
+ * `subpath` absent and `subpath` empty are different things, and conflating them reads the wrong
+ * transcript. Absent means the session's main transcript; a subagent's is addressed by a subpath
+ * that mirrors the on-disk directory. An empty string is neither — the adapter contract calls it
+ * invalid and says to omit the field — so an empty one is refused rather than normalised away. A
+ * normaliser here would answer a question about a subagent with the main transcript's contents,
+ * which is a wrong answer wearing a right answer's shape.
+ */
+export interface TranscriptKey {
+    /** The caller's scope — a tenant, a project. Never derived here; the embedder decides. */
+    readonly projectKey: string;
+    readonly sessionId: string;
+    /** Absent = the main transcript. Present = a subagent's. Opaque: never parsed. */
+    readonly subpath?: string;
+}
+/** Build a key, or say which part was unusable. */
+export declare function transcriptKey(projectKey: string, sessionId: string, subpath?: string): Result<TranscriptKey>;
+/** Whether two keys address the same transcript. */
+export declare function sameTranscript(left: TranscriptKey, right: TranscriptKey): boolean;
+/**
+ * A stable, comparable string for one key. For map keys and log lines — never parsed back.
+ *
+ * It is not a filesystem path and must not be used as one. A projectKey is caller-supplied and can
+ * carry anything, including separators; turning that into a path is how a key climbs out of its
+ * directory. `host/transcript-fs.ts` derives real paths through the same jail every other host-side
+ * path goes through, and this exists only so two keys can be compared or logged as one token.
+ */
+export declare function transcriptToken(key: TranscriptKey): string;
+//# sourceMappingURL=key.d.ts.map

package/dist/persistence/key.js

@@ -0,0 +1,33 @@
+import { ok, refuse } from '../core/result.js';
+/** Build a key, or say which part was unusable. */
+export function transcriptKey(projectKey, sessionId, subpath) {
+    if (projectKey.length === 0) {
+        return refuse('transcript-key-invalid', 'projectKey is empty');
+    }
+    if (sessionId.length === 0) {
+        return refuse('transcript-key-invalid', 'sessionId is empty');
+    }
+    if (subpath !== undefined && subpath.length === 0) {
+        return refuse('transcript-key-invalid', 'subpath is present and empty — omit the field for the main transcript');
+    }
+    return ok(subpath === undefined ? { projectKey, sessionId } : { projectKey, sessionId, subpath });
+}
+/** Whether two keys address the same transcript. */
+export function sameTranscript(left, right) {
+    return (left.projectKey === right.projectKey &&
+        left.sessionId === right.sessionId &&
+        (left.subpath ?? null) === (right.subpath ?? null));
+}
+/**
+ * A stable, comparable string for one key. For map keys and log lines — never parsed back.
+ *
+ * It is not a filesystem path and must not be used as one. A projectKey is caller-supplied and can
+ * carry anything, including separators; turning that into a path is how a key climbs out of its
+ * directory. `host/transcript-fs.ts` derives real paths through the same jail every other host-side
+ * path goes through, and this exists only so two keys can be compared or logged as one token.
+ */
+export function transcriptToken(key) {
+    const main = `${encodeURIComponent(key.projectKey)}/${encodeURIComponent(key.sessionId)}`;
+    return key.subpath === undefined ? main : `${main}/${encodeURIComponent(key.subpath)}`;
+}
+//# sourceMappingURL=key.js.map