@naswerks/periscope 1.0.0

package/dist/persistence/transition-log.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The durable transition log — the only place a gate decision is stored durably.
+ *
+ * Read this before adding any cleanup, prune or tidy-up. `state/store.ts` retains transitions in
+ * a bounded in-memory ring that actively drops its oldest once a session outruns the window, and
+ * its own header says durability belongs here. Every recorded transition also reaches the link —
+ * `forwardSession` in `control/stream.ts` subscribes to the machine and forwards whichever lane
+ * produced it — but the link is a stream, not a record: once a frame has been sent, nothing in
+ * this package can read it back. So every local refusal this host decides — a path-jail denial, a
+ * boundary command, a credential-path read, an unconvertible tool descriptor — is held in-process
+ * only by a ring that will eventually overwrite it. This file is what makes such a decision
+ * readable afterwards. A tidy-up here does not lose a log line; it loses the only stored evidence
+ * that the package's headline feature ever ran.
+ *
+ * Append-only, and an abandoned entry is marked rather than erased. "This session sat in
+ * `tool:Bash` for forty minutes" is the most useful sentence this system can produce, and a
+ * reconciler that quietly closed the entry would destroy exactly that. So `markAbandoned` writes a
+ * new record carrying the reason; it never rewrites or removes the one that is already stored.
+ *
+ * `cause` survives the round trip or the read refuses. A transition read back without the event
+ * that produced it would leave a reader with a state change and no way to know what caused it,
+ * which is exactly the inference the declared model exists to eliminate. So the encoder writes all
+ * three parts of a cause and the decoder refuses an entry that lost any of them, rather than
+ * substituting a plausible default.
+ */
+import type { OpenEntry, SessionTransition } from '../state/model.js';
+import type { Result } from '../core/result.js';
+import type { TranscriptEntry } from './entry.js';
+/**
+ * The entry `type` a stored transition carries.
+ *
+ * Namespaced so it cannot collide with a transcript entry. These records may share a store with
+ * mirrored transcript lines, whose `type` values are the CLI's. A prefix nothing in that vocabulary
+ * uses keeps the two readable side by side and keeps a reader of either from mistaking one for the
+ * other.
+ */
+export declare const TRANSITION_ENTRY_TYPE = "periscope.transition";
+/** The entry `type` an abandonment mark carries. A record in its own right, never an edit. */
+export declare const ABANDONED_ENTRY_TYPE = "periscope.entry_abandoned";
+/** Encode one transition as a storable entry. Lossless for everything a reader branches on. */
+export declare function encodeTransition(transition: SessionTransition): TranscriptEntry;
+/**
+ * Read a stored transition back.
+ *
+ * A lost or unrecognised cause is a refusal. Both halves are checked independently — the same way
+ * the machine validates them — because a cause that survived as a shape but not as a declared value
+ * is a record a reader would branch on wrongly.
+ */
+export declare function decodeTransition(entry: TranscriptEntry): Result<SessionTransition>;
+/**
+ * A record that an open entry was abandoned.
+ *
+ * This is an append, not an edit, and that is the whole design. The entry it refers to stays
+ * exactly as it was written, with the time it opened and the cause that opened it. A reader
+ * assembling the two sees "opened at X, still open at Y, marked abandoned because Z" — which is the
+ * signal. Rewriting the original would leave "closed", which is the signal's opposite and is
+ * indistinguishable from an ordinary completion.
+ */
+export declare function markAbandoned(entry: OpenEntry, at: string, reason: string): TranscriptEntry;
+/** Every stored transition in an entry list, in stored order. Non-transition entries are ignored. */
+export declare function transitionsIn(entries: readonly TranscriptEntry[]): Result<SessionTransition[]>;
+/** Every abandonment mark in an entry list, by the entry id it refers to. */
+export declare function abandonmentsIn(entries: readonly TranscriptEntry[]): Map<string, TranscriptEntry>;
+/**
+ * A stable uuid for one transition, so a re-append is deduplicated rather than doubled.
+ *
+ * Derived, not minted. The adapter contract treats `uuid` as an idempotency key, and a mirror
+ * retries. A random id would make every retry a new row, so the same transition written twice must
+ * carry the same id — and a session's `seq` is dense from 1 per machine, which makes the pair
+ * unique without inventing anything.
+ */
+export declare function transitionUuid(transition: SessionTransition): string;
+//# sourceMappingURL=transition-log.d.ts.map

package/dist/persistence/transition-log.js

@@ -0,0 +1,133 @@
+import { isCauseEvent, isCauseKind } from '../state/model.js';
+import { ok, refuse } from '../core/result.js';
+/**
+ * The entry `type` a stored transition carries.
+ *
+ * Namespaced so it cannot collide with a transcript entry. These records may share a store with
+ * mirrored transcript lines, whose `type` values are the CLI's. A prefix nothing in that vocabulary
+ * uses keeps the two readable side by side and keeps a reader of either from mistaking one for the
+ * other.
+ */
+export const TRANSITION_ENTRY_TYPE = 'periscope.transition';
+/** The entry `type` an abandonment mark carries. A record in its own right, never an edit. */
+export const ABANDONED_ENTRY_TYPE = 'periscope.entry_abandoned';
+/** Encode one transition as a storable entry. Lossless for everything a reader branches on. */
+export function encodeTransition(transition) {
+    return {
+        type: TRANSITION_ENTRY_TYPE,
+        uuid: transitionUuid(transition),
+        timestamp: transition.at,
+        sessionId: transition.sessionId,
+        seq: transition.seq,
+        from: transition.from,
+        to: transition.to,
+        activity: transition.activity,
+        entryId: transition.entryId,
+        cause: { kind: transition.cause.kind, event: transition.cause.event, detail: transition.cause.detail },
+        where: transition.where,
+        correlationId: transition.correlationId,
+    };
+}
+/**
+ * Read a stored transition back.
+ *
+ * A lost or unrecognised cause is a refusal. Both halves are checked independently — the same way
+ * the machine validates them — because a cause that survived as a shape but not as a declared value
+ * is a record a reader would branch on wrongly.
+ */
+export function decodeTransition(entry) {
+    if (entry.type !== TRANSITION_ENTRY_TYPE) {
+        return refuse('transcript-entry-malformed', `not a transition entry: type ${entry.type}`);
+    }
+    const cause = entry['cause'];
+    if (cause === null || typeof cause !== 'object' || Array.isArray(cause)) {
+        return refuse('transcript-entry-malformed', 'the transition carries no cause');
+    }
+    const { kind, event, detail } = cause;
+    if (typeof kind !== 'string' || !isCauseKind(kind)) {
+        return refuse('transcript-entry-malformed', `the cause kind is not a declared kind: ${String(kind)}`);
+    }
+    if (typeof event !== 'string' || !isCauseEvent(event)) {
+        return refuse('transcript-entry-malformed', `the cause event is not a declared event: ${String(event)}`);
+    }
+    const seq = entry['seq'];
+    if (typeof seq !== 'number' || !Number.isFinite(seq)) {
+        return refuse('transcript-entry-malformed', 'the transition carries no seq');
+    }
+    const where = entry['where'];
+    if (where === null || typeof where !== 'object') {
+        return refuse('transcript-entry-malformed', 'the transition carries no where');
+    }
+    return ok({
+        sessionId: entry['sessionId'] ?? null,
+        seq,
+        at: typeof entry.timestamp === 'string' ? entry.timestamp : '',
+        from: entry['from'],
+        to: entry['to'],
+        activity: entry['activity'] ?? null,
+        entryId: entry['entryId'] ?? null,
+        cause: { kind, event, detail: typeof detail === 'string' ? detail : '' },
+        where: where,
+        correlationId: entry['correlationId'] ?? null,
+    });
+}
+/**
+ * A record that an open entry was abandoned.
+ *
+ * This is an append, not an edit, and that is the whole design. The entry it refers to stays
+ * exactly as it was written, with the time it opened and the cause that opened it. A reader
+ * assembling the two sees "opened at X, still open at Y, marked abandoned because Z" — which is the
+ * signal. Rewriting the original would leave "closed", which is the signal's opposite and is
+ * indistinguishable from an ordinary completion.
+ */
+export function markAbandoned(entry, at, reason) {
+    return {
+        type: ABANDONED_ENTRY_TYPE,
+        uuid: `abandoned:${entry.entryId}:${at}`,
+        timestamp: at,
+        entryId: entry.entryId,
+        activity: entry.activity,
+        lane: entry.lane,
+        openedAt: entry.openedAt,
+        agentId: entry.agentId,
+        reason,
+        cause: { kind: entry.cause.kind, event: entry.cause.event, detail: entry.cause.detail },
+    };
+}
+/** Every stored transition in an entry list, in stored order. Non-transition entries are ignored. */
+export function transitionsIn(entries) {
+    const found = [];
+    for (const entry of entries) {
+        if (entry.type !== TRANSITION_ENTRY_TYPE)
+            continue;
+        const decoded = decodeTransition(entry);
+        if (!decoded.ok)
+            return refuse(decoded.refusal.reason, decoded.refusal.detail);
+        found.push(decoded.value);
+    }
+    return ok(found);
+}
+/** Every abandonment mark in an entry list, by the entry id it refers to. */
+export function abandonmentsIn(entries) {
+    const marks = new Map();
+    for (const entry of entries) {
+        if (entry.type !== ABANDONED_ENTRY_TYPE)
+            continue;
+        const entryId = entry['entryId'];
+        if (typeof entryId === 'string')
+            marks.set(entryId, entry);
+    }
+    return marks;
+}
+/**
+ * A stable uuid for one transition, so a re-append is deduplicated rather than doubled.
+ *
+ * Derived, not minted. The adapter contract treats `uuid` as an idempotency key, and a mirror
+ * retries. A random id would make every retry a new row, so the same transition written twice must
+ * carry the same id — and a session's `seq` is dense from 1 per machine, which makes the pair
+ * unique without inventing anything.
+ */
+export function transitionUuid(transition) {
+    return `transition:${transition.sessionId ?? 'unidentified'}:${transition.correlationId ?? '-'}:${transition.seq}`;
+}
+//# sourceMappingURL=transition-log.js.map

package/dist/protocol.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The wire contract, on its own subpath — `@naswerks/periscope/protocol`.
+ *
+ * This is the only import path into the package that structurally cannot reach `src/host/`, so a
+ * controller written against it cannot transitively acquire `node:fs`, `node:child_process` or
+ * `node:os`, and does not pull the Agent SDK. That turns the package's blast-radius claim into
+ * something a consumer can verify at the package boundary instead of taking on trust from the
+ * package's own test suite. Pinned by src/pins/protocol-closure.test.ts.
+ *
+ * The condition that keeps it true: `exports` in package.json has exactly these two entries and no
+ * catch-all `"./*"`. A third subpath re-opens the boundary and is a decision, not a refactor.
+ */
+export type { AgentMessageUpdate, BulkDelivered, BulkFailed, BulkRequest, ControlFrame, ControlPayload, ControlPayloadKind, Frame, HostConfiguration, HostConfigure, HostConfigureEntry, HostConfigureResult, JsonObject, JsonValue, LinkAck, LinkBye, LinkHello, LinkPing, LinkPong, LinkWelcome, ProtocolRange, ReadRefusal, SessionCancel, SessionConfigure, SessionCursor, SessionDelta, SessionFrame, SessionList, SessionListEntry, SessionListResult, SessionNew, SessionNewEnv, SessionNewGate, SessionNewPlugin, SessionNewRequest, SessionPayload, SessionPayloadKind, SessionPrompt, SessionUpdate, SessionUpdateBody, StateTransitionUpdate, TranscriptFailed, TranscriptList, TranscriptListEntry, TranscriptListResult, TranscriptTail, TranscriptTailResult, WireRefusal, WireRefusalUpdate, RepositoryEntry, RepositoryList, RepositoryListResult, RepositoryRead, RepositoryReadResult, WorkspaceList, WorkspaceListEntry, WorkspaceListResult, WorkspaceRelease, WorkspaceReleaseBulk, WorkspaceReleaseBulkResult, WorkspaceReleaseEntry, WorkspaceReleaseEntryResult, WorkspaceReleaseFlags, WorkspaceReleaseResult, } from './control/frames.js';
+export type { ActivityKind, AgedEntry, CauseEvent, CauseKind, EntryLane, HookEventName, OpenEntry, SessionActivity, SessionSnapshot, SessionState, SessionTransition, TransitionCause, TransitionWhere, } from './state/model.js';
+export { ACTIVITY_KINDS, CAUSE_KINDS, HOOK_EVENTS, HOST_ACTIVITY_KINDS, SDK_ACTIVITY_KINDS, SESSION_STATES, formatActivity, isCauseEvent, isCauseKind, sameActivity, } from './state/model.js';
+export { DROPPABLE_KINDS, MAX_CONFIGURATION_VALUE_LENGTH, MAX_BULK_RELEASES, MAX_CONFIGURE_ENTRIES, MAX_FRAME_BYTES, MAX_REPOSITORY_ENTRIES, MAX_REPOSITORY_READ_BYTES, PROTOCOL_VERSION, PROTOCOL_VERSION_MIN, TRANSCRIPT_PAGE_SIZE, TRANSCRIPT_WHAT_PREFIX, WORKSPACE_PAGE_SIZE, agentMessageDelta, agentMessageUpdate, bulkDelivered, frameId, hostConfigure, hostConfigureResult, isControlFrame, isDroppable, isSessionFrame, readAgentMessage, readRefusal, readStateTransition, readWireRefusal, repositoryList, repositoryListResult, repositoryRead, repositoryReadResult, sessionList, sessionListResult, sessionNew, sessionNewRequest, stateTransitionUpdate, transcriptFailed, transcriptList, transcriptListResult, transcriptTail, transcriptTailResult, unsetHostConfiguration, wireRefusalUpdate, workspaceList, workspaceListResult, workspaceRelease, workspaceReleaseBulk, workspaceReleaseBulkResult, workspaceReleaseEntryResult, workspaceReleaseResult, } from './control/frames.js';
+export { decode, encode } from './control/codec.js';
+export type { InboundCheck } from './control/seq.js';
+export { SeqTracker } from './control/seq.js';
+export type { Refusal, RefusalReason } from './core/refusal.js';
+export { REFUSAL_REASONS, isRefusalReason } from './core/refusal.js';
+export type { Result } from './core/result.js';
+export type { Decider, Decision, DecisionReading, DecisionRequest } from './gate/decision.js';
+export { describeRaw, readDecision } from './gate/decision.js';
+export type { EscalationOptions, EscalationResponse, EscalationTransport } from './gate/escalate.js';
+export type { Authorization, ControllerCredential } from './control/credential.js';
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -0,0 +1,12 @@
+export { ACTIVITY_KINDS, CAUSE_KINDS, HOOK_EVENTS, HOST_ACTIVITY_KINDS, SDK_ACTIVITY_KINDS, SESSION_STATES, formatActivity, isCauseEvent, isCauseKind, sameActivity, } from './state/model.js';
+export { DROPPABLE_KINDS, MAX_CONFIGURATION_VALUE_LENGTH, MAX_BULK_RELEASES, MAX_CONFIGURE_ENTRIES, MAX_FRAME_BYTES, MAX_REPOSITORY_ENTRIES, MAX_REPOSITORY_READ_BYTES, PROTOCOL_VERSION, PROTOCOL_VERSION_MIN, TRANSCRIPT_PAGE_SIZE, TRANSCRIPT_WHAT_PREFIX, WORKSPACE_PAGE_SIZE, agentMessageDelta, agentMessageUpdate, bulkDelivered, frameId, hostConfigure, hostConfigureResult, isControlFrame, isDroppable, isSessionFrame, readAgentMessage, readRefusal, readStateTransition, readWireRefusal, repositoryList, repositoryListResult, repositoryRead, repositoryReadResult, sessionList, sessionListResult, sessionNew, sessionNewRequest, stateTransitionUpdate, transcriptFailed, transcriptList, transcriptListResult, transcriptTail, transcriptTailResult, unsetHostConfiguration, wireRefusalUpdate, workspaceList, workspaceListResult, workspaceRelease, workspaceReleaseBulk, workspaceReleaseBulkResult, workspaceReleaseEntryResult, workspaceReleaseResult, } from './control/frames.js';
+// `control/stream-routing.ts` is not exported here, deliberately. It is keyed off the SDK's own
+// message union, so it reaches `host/` and would drag the privileged module into this subpath's
+// closure — the one thing this file exists to prevent. What a wire consumer needs is already here:
+// `DROPPABLE_KINDS` and `isDroppable` say which payload kinds may be lost. The routing table is the
+// host's emission policy, and it ships from the main barrel.
+export { decode, encode } from './control/codec.js';
+export { SeqTracker } from './control/seq.js';
+export { REFUSAL_REASONS, isRefusalReason } from './core/refusal.js';
+export { describeRaw, readDecision } from './gate/decision.js';
+//# sourceMappingURL=protocol.js.map

package/dist/sessions/index.d.ts

@@ -0,0 +1,8 @@
+/** The agent session lifecycle and the registry of live sessions. */
+export type { EnvSource, SpawnEnvPolicy } from './spawn-env.js';
+export { DECLARED_EXACT_KEYS, DECLARED_PREFIXES, DECLARED_SUFFIXES, STRIPPED_HOST_SESSION_KEYS, composeSpawnEnv, isDeclaredSpawnEnvKey, redactProxyCredential, } from './spawn-env.js';
+export type { HostedSessionFacts, SessionDegrade, SessionDegradeListener, SessionEndCause, SessionEndListener, SessionEnded, SessionLifecycle, SessionListener, Unsubscribe, } from './session.js';
+export { SESSION_END_CAUSES, HostedSession } from './session.js';
+export type { SessionRegistryOptions, SessionRequest } from './registry.js';
+export { SessionRegistry } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sessions/index.js

@@ -0,0 +1,4 @@
+export { DECLARED_EXACT_KEYS, DECLARED_PREFIXES, DECLARED_SUFFIXES, STRIPPED_HOST_SESSION_KEYS, composeSpawnEnv, isDeclaredSpawnEnvKey, redactProxyCredential, } from './spawn-env.js';
+export { SESSION_END_CAUSES, HostedSession } from './session.js';
+export { SessionRegistry } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/sessions/registry.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The live sessions this host is running, and the only thing that starts or ends one.
+ *
+ * Instance state on a class, never module globals, and that is the whole reason this is a class
+ * at all. A module-level map would make the package a singleton for its process: two embedders in
+ * one host — a test beside a running host, two controllers, one library used twice — would share a
+ * session table and end each other's work. Every piece of per-session state here is a private
+ * field, and a test runs two registries side by side to prove they cannot see each other.
+ *
+ * The ownership model in one line: this object owns lifetime, everything else borrows a handle.
+ * `create` mints, `get` borrows, `stop`/`stopAll` end. A session removes itself from here the
+ * moment it ends, whichever way it ended, so "in the registry" and "alive" are the same fact rather
+ * than two that can drift.
+ */
+import type { AgentSystemPrompt, HookRegistrations, McpServerConfig, SdkPluginConfig, SessionStore, SessionStoreFlush, SettingSource, SpawnAgentProcess, ThinkingConfig, EffortLevel, PermissionMode } from '../host/agent-process.js';
+import type { WorkspaceTrust } from '../host/workspace-trust.js';
+import type { Clock } from '../core/time.js';
+import type { Result } from '../core/result.js';
+import type { SpawnEnvPolicy } from './spawn-env.js';
+import { HostedSession } from './session.js';
+/** What a caller asks for when starting a session. */
+export interface SessionRequest {
+    /** Absolute. Refused otherwise — a relative cwd means "relative to something you cannot see". */
+    readonly cwd: string;
+    /**
+     * Which on-disk settings tiers the agent may load. Defaults to none.
+     *
+     * Reading no settings files is the default because it is the only setting under which the host
+     * can state what an agent's permissions are. Loading the project tier also brings the trust
+     * problem back: its rules are silently void in a workspace nobody accepted. A caller that wants
+     * project instructions loaded must ask, and gets told what it costs.
+     */
+    readonly settingSources?: readonly SettingSource[];
+    readonly plugins?: readonly SdkPluginConfig[];
+    /** Hook callbacks for this session. Carried to the process untouched — see host/hooks.ts. */
+    readonly hooks?: HookRegistrations;
+    /** Extra allow/deny/literal declarations on top of the general spawn environment. */
+    readonly env?: SpawnEnvPolicy;
+    /** A session id to continue. The controller decides when; the host only carries it out. */
+    readonly resume?: string;
+    /** With `resume`, continue into a new id instead of extending the old session. */
+    readonly fork?: boolean;
+    /**
+     * Stream this session's turns as they compose. Defaults to on.
+     *
+     * On because the incremental lane is droppable by construction — a delta never enters the replay
+     * ring or the durable store, so what it costs under pressure is a repaint. Off, a turn can only
+     * be rendered after it is over, which is a different product.
+     */
+    readonly includePartialMessages?: boolean;
+    /**
+     * How much reasoning this session emits. Defaults to the SDK's own default (deltas fire, prose
+     * is empty), so summarized prose is something a caller asks for.
+     *
+     * Why the default is not "on when someone is watching": that rule cannot be written in this
+     * package. Whether a run is watched is a judgement about what the session is for, and this host
+     * has no fact that distinguishes one — inventing one would be a name earned by observation, which
+     * is the failure the declared model exists to end. The caller knows; the host offers the knob.
+     * The asymmetry in the defaults carries the intent instead: the cheap half is on, and the half
+     * that costs tokens on the wire and puts reasoning text into transcripts and mirrors is opt-in.
+     */
+    readonly thinking?: ThinkingConfig;
+    /** Forward a subagent's whole conversation rather than only its tool calls. Defaults to off. */
+    readonly forwardSubagentText?: boolean;
+    /**
+     * In-process MCP servers this session may call, by server name. Build them with `mcp/`.
+     *
+     * Every tool these add is decided by the same gate as `Bash` — `PreToolUse` is registered with
+     * no matcher, so coverage does not depend on the host recognising the tool. What the host's own
+     * gate does with them is a different question: see `gate/local.ts`, which matches on tool name and
+     * therefore has no opinion about an `mcp__…` tool unless the embedder names it in `ToolFamilies`.
+     */
+    readonly mcpServers?: Readonly<Record<string, McpServerConfig>>;
+    /**
+     * Ignore every MCP server this host did not declare. Defaults to true.
+     *
+     * On by default, and this is the one place a workspace's contents could otherwise decide what
+     * tools exist. Without it the agent also loads project `.mcp.json`, user settings, plugin MCP and
+     * on-disk agent frontmatter — so a repository the host checked out into a workspace can register
+     * its own servers, and a `WorkspaceProvider` that clones untrusted code becomes a tool-registration
+     * channel. The host provisions those directories programmatically, which is exactly the case where
+     * nobody reviewed what is in them.
+     *
+     * Turning it off is legitimate and costs something named. A consumer whose own repository
+     * declares the servers it wants needs this off, and forcing them to fork the package would be
+     * worse. But the cost is not only a wider tool surface: an in-process server cannot fail to
+     * connect, while the stdio and HTTP servers this re-admits can — and this package deliberately
+     * does not expose the SDK's `mcpServerStatus()` / `reconnectMcpServer()`, because reaching them
+     * means handing out the query object whose narrowing is a pinned security property. So with strict
+     * off, a failed server is neither detectable nor recoverable through this package. Strict on is
+     * what makes that absence harmless.
+     */
+    readonly strictMcpConfig?: boolean;
+    /**
+     * Mirror this session's transcript to a store. Defaults to none.
+     *
+     * The store receives every message the agent saw, so supplying one is an egress decision and it
+     * is deliberately the embedder's — this type is the local API, not the wire. Nothing arriving over
+     * the link can reach this field: a store is an object with methods and has no JSON form, so a
+     * controller cannot name a destination for a transcript even in principle. Pinned by
+     * pins/persistence-egress.test.ts.
+     *
+     * Local disk remains the primary record whatever is set here. The subprocess writes locally
+     * first and the mirror runs after that write succeeds, so a store can legitimately lag — and when
+     * a batch is dropped it stays behind, silently. See host/session-store.ts on reading that report.
+     */
+    readonly sessionStore?: SessionStore;
+    /** How eagerly the mirror flushes. Defaults to the SDK's batching. Ignored with no store. */
+    readonly sessionStoreFlush?: SessionStoreFlush;
+    /** Create the process yourself — a VM, a container, a remote machine. See agent-process.ts. */
+    readonly spawn?: SpawnAgentProcess;
+    /**
+     * Which model runs this session. Defaults to the CLI's own.
+     *
+     * Absent, not narrowed — this and `systemPrompt` were simply not composable before, so they fill
+     * a gap rather than widen the permission narrowing. See `AGENT_SELECTION_OPTION_KEYS`.
+     *
+     * Whether it took effect is provable: the agent reports `model` on its own `system/init`, so a
+     * caller reads it back off `HostedSession`'s facts rather than trusting the request.
+     */
+    readonly model?: string;
+    /**
+     * What the agent is told at the start. Defaults to the CLI's own preset.
+     *
+     * This one is not provable the same way. The init message carries no system prompt, so nothing
+     * the agent says back confirms it. Asking for it is a decision made blind, by construction.
+     */
+    readonly systemPrompt?: AgentSystemPrompt;
+    /** The effort level. Defaults to the SDK's own. */
+    readonly effort?: EffortLevel;
+    /** The permission mode. Defaults to the SDK's own. See `CLI_PARITY_OPTION_KEYS`. */
+    readonly permissionMode?: PermissionMode;
+}
+export interface SessionRegistryOptions {
+    /** The environment sessions are filtered from. The composition root passes `process.env`. */
+    readonly baseEnv: Readonly<Record<string, string | undefined>>;
+    /** Absolute path to the user's home, for the trust read. */
+    readonly homeDir: string;
+    readonly clock?: Clock;
+    /** How long the agent has to report itself before the start is called failed. */
+    readonly startTimeoutMs?: number;
+}
+export declare class SessionRegistry {
+    #private;
+    constructor(options: SessionRegistryOptions);
+    /** Every live session. A copy — a caller iterating this cannot be surprised by one ending. */
+    list(): HostedSession[];
+    get liveCount(): number;
+    /** Sessions that have started but not yet reported themselves. Separate because they have no id. */
+    get provisioningCount(): number;
+    get(sessionId: string): Result<HostedSession>;
+    /**
+     * Start a session. Returns as soon as the process exists — synchronously, and without an id.
+     *
+     * Why there is no id yet, and why this is not an oversight. The agent reports itself only once
+     * a turn has been queued; before that it emits nothing at all, for as long as you care to wait
+     * (observed: 45 seconds of silence with no turn, 2.5 seconds with one). So a `create` that
+     * waited for the id would deadlock against the `prompt` that causes it.
+     *
+     * The shape a caller wants is therefore: create, prompt, then `whenLive()` if it needs the id, the
+     * version receipt or the tool list. Until then the session is in `provisioning` — held by this
+     * registry, counted by `provisioningCount`, stopped by `stopAll`, but not yet reachable by id
+     * because there is no id to reach it by.
+     */
+    create(request: SessionRequest): Result<HostedSession>;
+    /**
+     * Start a session, send its first turn, and wait until it has reported itself.
+     *
+     * The ordinary shape, offered as one call because getting it wrong deadlocks: the turn must be
+     * queued before the wait, since it is what makes the agent initialize.
+     */
+    open(request: SessionRequest & {
+        readonly prompt: string;
+    }): Promise<Result<HostedSession>>;
+    /** End one session. Refuses an id this registry does not hold rather than succeeding quietly. */
+    stop(sessionId: string, detail?: string): Result<void>;
+    /**
+     * End everything this registry holds, including sessions still provisioning.
+     *
+     * Provisioning sessions are included deliberately: they hold a real process even though they have
+     * no id yet, and a shutdown that only walked the keyed map would leave those running.
+     */
+    stopAll(detail?: string): void;
+}
+export type { WorkspaceTrust };
+//# sourceMappingURL=registry.d.ts.map

package/dist/sessions/registry.js

@@ -0,0 +1,190 @@
+import { startAgentProcess } from '../host/agent-process.js';
+import { isUntrustedWorkspaceWarning, readWorkspaceTrust, trustConfigPath } from '../host/workspace-trust.js';
+import { systemClock } from '../core/time.js';
+import { ok, refuse } from '../core/result.js';
+import { requireAbsolute } from '../core/paths.js';
+import { composeSpawnEnv } from './spawn-env.js';
+import { HostedSession } from './session.js';
+/**
+ * 60 seconds. The process is a large native binary starting cold, and a loaded host has been
+ * observed holding a trivial invocation of it past ten. Too short turns a slow machine into a
+ * spurious outage; there is no upper bound that is too generous for a case that otherwise hangs.
+ */
+const DEFAULT_START_TIMEOUT_MS = 60_000;
+export class SessionRegistry {
+    #live = new Map();
+    #provisioning = new Set();
+    #baseEnv;
+    #homeDir;
+    #clock;
+    #startTimeoutMs;
+    #startProcess;
+    constructor(options) {
+        this.#baseEnv = options.baseEnv;
+        this.#homeDir = options.homeDir;
+        this.#clock = options.clock ?? systemClock;
+        this.#startTimeoutMs = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+        this.#startProcess = options.startProcess ?? startAgentProcess;
+    }
+    /** Every live session. A copy — a caller iterating this cannot be surprised by one ending. */
+    list() {
+        return [...this.#live.values()];
+    }
+    get liveCount() {
+        return this.#live.size;
+    }
+    /** Sessions that have started but not yet reported themselves. Separate because they have no id. */
+    get provisioningCount() {
+        return this.#provisioning.size;
+    }
+    get(sessionId) {
+        const session = this.#live.get(sessionId);
+        if (session === undefined) {
+            return refuse('session-unknown', `no live session ${sessionId} in this registry`);
+        }
+        return ok(session);
+    }
+    /**
+     * Start a session. Returns as soon as the process exists — synchronously, and without an id.
+     *
+     * Why there is no id yet, and why this is not an oversight. The agent reports itself only once
+     * a turn has been queued; before that it emits nothing at all, for as long as you care to wait
+     * (observed: 45 seconds of silence with no turn, 2.5 seconds with one). So a `create` that
+     * waited for the id would deadlock against the `prompt` that causes it.
+     *
+     * The shape a caller wants is therefore: create, prompt, then `whenLive()` if it needs the id, the
+     * version receipt or the tool list. Until then the session is in `provisioning` — held by this
+     * registry, counted by `provisioningCount`, stopped by `stopAll`, but not yet reachable by id
+     * because there is no id to reach it by.
+     */
+    create(request) {
+        const cwd = requireAbsolute(request.cwd);
+        if (!cwd.ok)
+            return refuse(cwd.refusal.reason, cwd.refusal.detail);
+        const settingSources = request.settingSources ?? [];
+        const trust = readWorkspaceTrust(trustConfigPath(this.#homeDir), cwd.value);
+        const session = new HostedSession(this.#startProcess({
+            cwd: cwd.value,
+            env: composeSpawnEnv(this.#baseEnv, request.env ?? {}),
+            settingSources,
+            plugins: request.plugins ?? null,
+            hooks: request.hooks ?? null,
+            resume: request.resume ?? null,
+            fork: request.fork ?? false,
+            // The two defaults that carry the streaming policy are these two lines. See SessionRequest
+            // for why the rule is stated as an asymmetry rather than as attendedness.
+            includePartialMessages: request.includePartialMessages ?? true,
+            thinking: request.thinking ?? null,
+            forwardSubagentText: request.forwardSubagentText ?? false,
+            mcpServers: request.mcpServers ?? null,
+            // The default is strict, and it is stated rather than left to the SDK. Omitting the key
+            // lets a provisioned workspace's own files register servers — see SessionRequest.
+            strictMcpConfig: request.strictMcpConfig ?? true,
+            // No default destination, and there must never be one: a host that mirrored somewhere by
+            // default would be sending transcripts off-box without anyone choosing to.
+            sessionStore: request.sessionStore ?? null,
+            sessionStoreFlush: request.sessionStoreFlush ?? null,
+            spawn: request.spawn ?? null,
+            // No default for either: naming a model here would make this package's own choice look like
+            // the CLI's, and the CLI's default is the one an operator can actually see and change.
+            model: request.model ?? null,
+            systemPrompt: request.systemPrompt ?? null,
+            effort: request.effort ?? null,
+            permissionMode: request.permissionMode ?? null,
+            // The untrusted-workspace condition is reported here and nowhere else in the SDK, so the
+            // callback is wired on every start rather than only when it is expected.
+            onStderr: (data) => {
+                if (isUntrustedWorkspaceWarning(data)) {
+                    session.degrade('workspace_untrusted', data.trim());
+                }
+            },
+        }), this.#clock, cwd.value, trust, (live) => this.#adopt(live), (finished) => this.#release(finished));
+        this.#provisioning.add(session);
+        // Stated before the first message, because a caller that asked for settings files in a
+        // workspace nobody trusted has already lost its rules by the time anything runs — and the only
+        // other notice is a line on stderr.
+        if (settingSources.length > 0 && trust !== 'trusted') {
+            session.degrade('workspace_untrusted', `settings sources ${settingSources.join(', ')} were requested but this workspace is ` +
+                `${trust}: permission rules from settings files will be ignored`);
+        }
+        return ok(session);
+    }
+    /**
+     * Start a session, send its first turn, and wait until it has reported itself.
+     *
+     * The ordinary shape, offered as one call because getting it wrong deadlocks: the turn must be
+     * queued before the wait, since it is what makes the agent initialize.
+     */
+    async open(request) {
+        const created = this.create(request);
+        if (!created.ok)
+            return created;
+        const sent = created.value.prompt(request.prompt);
+        if (!sent.ok) {
+            created.value.stop('the first turn could not be queued');
+            return refuse(sent.refusal.reason, sent.refusal.detail);
+        }
+        const live = await created.value.whenLive(this.#startTimeoutMs);
+        if (!live.ok)
+            return refuse(live.refusal.reason, live.refusal.detail);
+        return ok(created.value);
+    }
+    /** End one session. Refuses an id this registry does not hold rather than succeeding quietly. */
+    stop(sessionId, detail = 'stop requested') {
+        const session = this.#live.get(sessionId);
+        if (session === undefined) {
+            return refuse('session-unknown', `no live session ${sessionId} in this registry`);
+        }
+        session.stop(detail);
+        return ok(undefined);
+    }
+    /**
+     * End everything this registry holds, including sessions still provisioning.
+     *
+     * Provisioning sessions are included deliberately: they hold a real process even though they have
+     * no id yet, and a shutdown that only walked the keyed map would leave those running.
+     */
+    stopAll(detail = 'host shutting down') {
+        for (const session of [...this.#live.values(), ...this.#provisioning]) {
+            session.stop(detail);
+        }
+    }
+    /**
+     * The agent has named itself, so the session becomes reachable by that id and stops provisioning.
+     *
+     * An id already held is not overwritten, and the reason is an observed SDK property: a resume
+     * without `fork` keeps the same session id. So resuming a session this registry is already
+     * running produces two live handles claiming one key. Overwriting would make the older one
+     * untracked-but-alive — invisible to `list`, unreachable by `get`, missed by `stopAll`, still
+     * holding a process — and then its eventual end would evict the newer session's entry, so a live
+     * session would become unreachable because a different one finished. Both losses are silent, and
+     * both falsify this file's own rule that "in the registry" and "alive" are the same fact.
+     *
+     * The newcomer is refused rather than the incumbent evicted: the incumbent is the one already
+     * being observed, and a degrade names the collision on the session that is about to be dropped —
+     * whose caller is the one that can do something about it.
+     */
+    #adopt(session) {
+        const id = session.facts?.id;
+        if (id === undefined)
+            return;
+        this.#provisioning.delete(session);
+        const incumbent = this.#live.get(id);
+        if (incumbent !== undefined && incumbent !== session) {
+            session.degrade('session_id_collision', `the agent reported session id ${id}, which this registry already holds — a resume without ` +
+                `fork keeps the original id. This session stays unregistered; stop the one that holds the ` +
+                `id, or resume with fork so the agent mints a new one`);
+            session.stop(`session id ${id} is already held by a live session in this registry`);
+            return;
+        }
+        this.#live.set(id, session);
+    }
+    /** Only the holder of an id may release it — a colliding session must not evict the incumbent. */
+    #release(session) {
+        this.#provisioning.delete(session);
+        const id = session.facts?.id;
+        if (id !== undefined && this.#live.get(id) === session)
+            this.#live.delete(id);
+    }
+}
+//# sourceMappingURL=registry.js.map