@naswerks/periscope 1.0.0

package/dist/host/git-facts.js

@@ -0,0 +1,106 @@
+/**
+ * Which worktree and which branch a directory sits in: the "where" half of every transition.
+ *
+ * Why this is read at all: a trace whose location is a bare path answers "where" with something
+ * a reader still has to go and look up. Worktree and branch are what makes a transition legible on
+ * its own, which is the whole bar the state model is held to.
+ *
+ * It reads; it never provisions. No `git` subprocess, no writes, no repository creation, just
+ * two small file reads. Creating and managing worktrees is a different job and stays one.
+ *
+ * `.git` is often a file, not a directory, and that is the trap this file exists around.
+ * In a linked worktree, `.git` is a text file holding `gitdir: <path>` and pointing at a directory
+ * under the main repository's `.git/worktrees/`. A walk-up that looks for a `.git` directory finds
+ * nothing there and reports "not a repository", which is wrong, silently, in exactly the
+ * environment agents are most often given.
+ *
+ * Every failure is a named null, never an exception and never an empty string. Three ordinary
+ * situations produce no branch: the directory is not in a repository at all (normal — a plain
+ * working directory is a legitimate place to run), HEAD is detached (there IS no branch name), or
+ * HEAD is unreadable. An empty string would make all three indistinguishable from each other and
+ * from a branch literally named "".
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+/** How far up to walk. A repository root further than this from cwd is not a case worth serving. */
+const MAX_DEPTH = 64;
+/**
+ * The `where` for a directory. Never throws — the caller stamps this onto every transition, so a
+ * throw here would take out the state record along with the fact it was decorating.
+ */
+export function readWhere(cwd) {
+    const located = locateGit(cwd);
+    if (located === null) {
+        return { cwd, worktree: null, branch: null, unknownReason: 'not inside a git repository' };
+    }
+    const head = readHead(located.gitDir);
+    return {
+        cwd,
+        worktree: located.worktree,
+        branch: head.branch,
+        unknownReason: head.reason,
+    };
+}
+/** Walk up from `start` for a `.git` entry, accepting both the directory and the pointer-file form. */
+function locateGit(start) {
+    let current = resolve(start);
+    for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+        const marker = join(current, '.git');
+        const kind = entryKind(marker);
+        if (kind === 'dir')
+            return { worktree: current, gitDir: marker };
+        if (kind === 'file') {
+            const pointed = readGitDirPointer(marker, current);
+            // A `.git` file that does not parse is still a `.git` file: this IS the worktree root, and
+            // saying so with an unreadable HEAD beats walking past it and reporting "not a repository".
+            return { worktree: current, gitDir: pointed ?? marker };
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}
+function entryKind(path) {
+    try {
+        const stats = statSync(path);
+        return stats.isDirectory() ? 'dir' : 'file';
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** `gitdir: <path>` out of a linked worktree's `.git` file. Relative paths resolve against it. */
+function readGitDirPointer(marker, worktree) {
+    try {
+        const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(marker, 'utf8'));
+        const target = pointer?.[1]?.trim();
+        if (target === undefined || target.length === 0)
+            return null;
+        return isAbsolute(target) ? target : resolve(worktree, target);
+    }
+    catch {
+        return null;
+    }
+}
+/** The branch, or which of the ordinary situations means there is not one. */
+function readHead(gitDir) {
+    let raw;
+    try {
+        raw = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
+    }
+    catch {
+        return { branch: null, reason: 'HEAD could not be read' };
+    }
+    const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(raw);
+    if (ref?.[1] !== undefined)
+        return { branch: ref[1].trim(), reason: null };
+    // A bare object id is a detached HEAD: there genuinely is no branch, which is different from
+    // failing to find one, and a reader deciding whether a run is on the branch it should be needs
+    // to be able to tell those apart.
+    if (/^[0-9a-f]{40}$/i.test(raw))
+        return { branch: null, reason: 'HEAD is detached' };
+    return { branch: null, reason: `HEAD is in an unrecognised form: ${raw.slice(0, 40)}` };
+}
+//# sourceMappingURL=git-facts.js.map

package/dist/host/hooks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Turns the coverage table into the `options.hooks` object the SDK actually takes.
+ *
+ * Registration is derived from the table, not written beside it. The list of events registered
+ * here is the list `coverage.ts` marks `wired`, so the table cannot claim an event is wired while
+ * the wiring quietly lacks it. A table that can disagree with the code is a document that will.
+ *
+ * Every handler is wrapped, because a throwing hook is fail-open. A hook that throws is treated
+ * by the CLI as absent rather than as a refusal (observed behaviour, not an assumption). For an
+ * observer that would mean a lost transition and nothing else, which is precisely the silent loss
+ * this model exists to prevent, so the wrapper is here and not left to the caller.
+ *
+ * This handler never decides anything. It returns an empty output on every path, including the
+ * failure path. `HookCallbackMatcher.hooks` is an array and the SDK runs every entry, so a
+ * permission-decision handler registers on the same event alongside this one; neither has to know
+ * about the other, and observation cannot accidentally become authorization.
+ */
+import type { HookRegistrations } from './agent-process.js';
+import type { SessionObserver } from '../state/observer.js';
+/** Told about a handler that threw, so a fail-open hook is never a silent one. */
+export type HookFailureListener = (failure: {
+    event: string;
+    error: unknown;
+}) => void;
+export interface ObservationHookOptions {
+    readonly observer: SessionObserver;
+    readonly onHandlerFailure?: HookFailureListener;
+}
+/** Every event the table marks `wired`, in the SDK's own order. */
+export declare function wiredHookEvents(): readonly string[];
+/**
+ * The `hooks` object for a session, registering exactly the wired events.
+ *
+ * No matcher is set: a matcher filters by tool name, and this observes every tool. The absence is
+ * deliberate rather than an omission.
+ */
+export declare function observationHooks(options: ObservationHookOptions): HookRegistrations;
+/**
+ * Combine independent hook registrations, concatenating the matchers per event.
+ *
+ * This is the seam that keeps observation and authorization apart. A permission decision and a
+ * state record answer different questions, have different consumers and fail differently, and the
+ * failure this package is built against is exactly what happens when they share a guard: the
+ * control concern wins, and the observability loss is silent. Two matchers on one event, merged
+ * here, means neither can suppress the other because neither knows the other exists.
+ *
+ * "Earlier arguments run first" is true of dispatch and false of completion. Handlers on one
+ * event have their synchronous prologues run in array order, and are then awaited concurrently
+ * (observed behaviour, not an assumption). So a handler may rely on an earlier one having started
+ * and must never rely on it having finished: anything order-dependent belongs before the first
+ * `await`. (The
+ * gate's permission entry opens from its hold timer, not in its prologue, so it depends on no
+ * registration order; it registers second by convention.)
+ */
+export declare function mergeHooks(...registrations: readonly HookRegistrations[]): HookRegistrations;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/host/hooks.js

@@ -0,0 +1,75 @@
+import { HOOK_COVERAGE } from '../state/coverage.js';
+import { HOOK_EVENTS } from '../state/model.js';
+/** Every event the table marks `wired`, in the SDK's own order. */
+export function wiredHookEvents() {
+    return HOOK_EVENTS.filter((event) => HOOK_COVERAGE[event].handling === 'wired');
+}
+/**
+ * The `hooks` object for a session, registering exactly the wired events.
+ *
+ * No matcher is set: a matcher filters by tool name, and this observes every tool. The absence is
+ * deliberate rather than an omission.
+ */
+export function observationHooks(options) {
+    const handler = (input) => {
+        try {
+            // The results are not read here. A transition the machine refuses is reported on
+            // `machine.onRejected` and counted in `rejectedCount`, the one channel every refused record
+            // takes whatever lane produced it; reporting it again from this handler would count one
+            // refusal twice. The observer builds a request only for an event it names, so an event this
+            // package does not know records nothing rather than producing a refusal to route.
+            options.observer.observeHook(input);
+        }
+        catch (error) {
+            // A throw here would make the CLI treat the hook as absent, which is the fail-open hole. It
+            // is caught, reported, and never rethrown; losing one observation loudly beats losing the
+            // handler entirely and silently. The listener is guarded too: a reporter that throws must
+            // not reopen the hole it exists to report.
+            try {
+                options.onHandlerFailure?.({ event: input.hook_event_name, error });
+            }
+            catch {
+                // Nothing further can be reported; the handler still answers.
+            }
+        }
+        return Promise.resolve({});
+    };
+    // One matcher object per event. A shared instance would let a `timeout` or `matcher` set on one
+    // event's entry apply to every event.
+    const registrations = {};
+    for (const event of HOOK_EVENTS) {
+        if (HOOK_COVERAGE[event].handling !== 'wired')
+            continue;
+        const matcher = { hooks: [handler] };
+        registrations[event] = [matcher];
+    }
+    return registrations;
+}
+/**
+ * Combine independent hook registrations, concatenating the matchers per event.
+ *
+ * This is the seam that keeps observation and authorization apart. A permission decision and a
+ * state record answer different questions, have different consumers and fail differently, and the
+ * failure this package is built against is exactly what happens when they share a guard: the
+ * control concern wins, and the observability loss is silent. Two matchers on one event, merged
+ * here, means neither can suppress the other because neither knows the other exists.
+ *
+ * "Earlier arguments run first" is true of dispatch and false of completion. Handlers on one
+ * event have their synchronous prologues run in array order, and are then awaited concurrently
+ * (observed behaviour, not an assumption). So a handler may rely on an earlier one having started
+ * and must never rely on it having finished: anything order-dependent belongs before the first
+ * `await`. (The
+ * gate's permission entry opens from its hold timer, not in its prologue, so it depends on no
+ * registration order; it registers second by convention.)
+ */
+export function mergeHooks(...registrations) {
+    const merged = {};
+    for (const registration of registrations) {
+        for (const [event, matchers] of Object.entries(registration)) {
+            const key = event;
+            merged[key] = [...(merged[key] ?? []), ...(matchers ?? [])];
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/host/host.d.ts

@@ -0,0 +1,356 @@
+/**
+ * The composer: the file that makes the parts a host.
+ *
+ * Why this file exists: every part of this package is built and proven through its own seam, and
+ * something has to join them. Without this file a session created through the registry runs with
+ * `hooks: null` (no gate, no observation) and the link decodes `session_new`, `session_prompt`,
+ * `session_cancel` and `bulk_request` with nothing consuming them, so the host cannot be told to
+ * do anything at all.
+ *
+ * Two things live here and the split is the testability.
+ *   `composeSession` is the per-session assembly (machine, observer, gate, forwarding) and it
+ *   takes everything as arguments, so it can be checked without a socket or a process.
+ *   `PeriscopeHost` owns the link and the registry and turns inbound payloads into calls on it.
+ *
+ * It lives in `src/host/` for the ordinary reason: it wires the real path resolver, the real bulk
+ * POST and the real MCP server, all of which are confined here. It imports no `node:` builtin of
+ * its own; the boundary is satisfied by construction rather than by permission.
+ *
+ * The order of assembly is load-bearing and it is not obvious. Forwarding is attached before the
+ * first transition is recorded, because the forwarder subscribes to the machine: attach it after
+ * and the `spawning` record (the one that carries where the session is and that it exists at all)
+ * is emitted to nobody. It is the first frame a controller ever sees for a session, so losing it
+ * costs the session's whole opening.
+ */
+import type { Clock, Ticker } from '../core/time.js';
+import type { Refusal } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import type { ControllerCredential } from '../control/credential.js';
+import type { BackoffOptions } from '../control/backoff.js';
+import type { LinkHandlers } from '../control/link.js';
+import type { LinkTransition } from '../control/link-state.js';
+import type { HostConfiguration, HostConfigureEntry } from '../control/frames.js';
+import type { FrameSink } from '../control/stream.js';
+import type { Decider } from '../gate/decision.js';
+import type { LocalGate } from '../gate/local.js';
+import type { ToolFamilies } from '../gate/local.js';
+import type { GateOutcome } from '../gate/outcome.js';
+import type { McpServerOptions } from '../mcp/server.js';
+import type { SessionRequest } from '../sessions/registry.js';
+import { SessionRegistry } from '../sessions/registry.js';
+import type { HostedSession, SessionDegrade, Unsubscribe } from '../sessions/session.js';
+import { SessionStateMachine } from '../state/machine.js';
+import type { SessionTransition, TransitionWhere } from '../state/model.js';
+import { SessionObserver } from '../state/observer.js';
+import type { WorkspaceProvider } from '../workspace/provider.js';
+/** How long the gate waits, when it reports a call as held, and whether its allow takes effect. */
+export interface GateTimings {
+    readonly decisionTimeoutMs?: number;
+    readonly holdAfterMs?: number;
+    readonly matcherTimeoutSeconds?: number;
+    /**
+     * Make the gate's allow effective.
+     *
+     * Defaults to false, and leaving it there gives a gate that cannot say yes. Without it
+     * this gate is a veto: it can refuse a call and cannot let one through. Observed on a real
+     * session: the gate allowed a `Write`, the tool did not run, and the model was told "Claude
+     * requested permissions to write to ..., but you haven't granted it yet", in a host with no user
+     * to grant anything. `PeriscopeHost` sets it to `true` for exactly this reason; an embedder
+     * calling `composeSession` by hand does not.
+     *
+     * The first allow that does not take effect raises a `gate-cannot-grant` degrade (see
+     * `permissionHooks`), so an embedder who left it off is told by a named outcome rather than by
+     * a comment.
+     *
+     * Setting it with `settingSources` non-empty is refused (`permission-grant-shadows-settings`).
+     * Per the SDK's documented evaluation order a hook allow does not skip operator deny or ask
+     * rules (it skips permission mode, allow rules and `canUseTool`), so the exposure is narrower
+     * than a bypass. See `composeSession` for what the refusal does and does not cover.
+     */
+    readonly grantOnAllow?: boolean;
+}
+export interface ComposeSessionOptions {
+    readonly registry: SessionRegistry;
+    /** The controller's handle: the frame routing key, not the agent's id. See frames.ts. */
+    readonly sessionKey: string;
+    /** Where the session runs. Absolute; the registry refuses anything else. */
+    readonly cwd: string;
+    readonly sink: FrameSink;
+    /** Who answers a permission escalation. Usually `escalatingDecider`. */
+    readonly decide: Decider;
+    /**
+     * The host's own gate, consulted before the decider.
+     *
+     * Optional in the type, supplied by default by `PeriscopeHost`. Absent means a path escape or a
+     * credential read waits `decisionTimeoutMs` for an unreachable controller and is reported as an
+     * outage, instead of being refused locally by name; see `gate/local.ts`. Composing without one
+     * is a decision, so it stays possible and is never the default.
+     */
+    readonly localGate?: LocalGate;
+    readonly gate?: GateTimings;
+    /** Read once, at composition. Carried by every transition until the agent moves itself. */
+    readonly where?: TransitionWhere;
+    /** Opaque and never interpreted here. The controller's own meaning handle. */
+    readonly correlationId?: string | null;
+    /** Everything else the session takes — MCP servers, a store, plugins, resume. */
+    readonly request?: Omit<SessionRequest, 'cwd' | 'hooks'>;
+    readonly clock?: Clock;
+    readonly ticker?: Ticker;
+    /** Every refusal the sink returned, every transition the machine would not record. */
+    readonly onRefusal?: (refused: Refusal) => void;
+    /**
+     * Told about every gate outcome, in addition to the machine record, never instead of it.
+     *
+     * The record is what reaches the wire and it is not optional; this is for an embedder that also
+     * wants to count, meter or log outcomes locally.
+     */
+    readonly onOutcome?: (outcome: GateOutcome) => void;
+    /** A hook handler that threw. The CLI treats a throwing hook as absent, so it is never silent. */
+    readonly onHookFailure?: (failure: {
+        event: string;
+        error: unknown;
+    }) => void;
+}
+/** One composed session: the handle, its machine, and how to take the wiring back down. */
+export interface ComposedSession {
+    readonly sessionKey: string;
+    readonly session: HostedSession;
+    readonly machine: SessionStateMachine;
+    readonly observer: SessionObserver;
+    /** Stops forwarding. Idempotent. Does not end the session; the registry owns lifetime. */
+    readonly detach: Unsubscribe;
+}
+/**
+ * Assemble one session: machine, observer, gate and forwarding, then start it.
+ *
+ * This is the wiring every consumer needs, written down where it can be used.
+ */
+export declare function composeSession(options: ComposeSessionOptions): Result<ComposedSession>;
+/** Turns the opaque `what` of a bulk request into a file this host will POST. */
+export type BulkResolver = (what: string, sessionKey: string) => Result<string>;
+/**
+ * The link surface a host uses. `ControllerLink` satisfies it.
+ *
+ * It is structural so the host's own rules can be checked without a socket: that an unknown
+ * handle is refused rather than dropped, that two `session_new` for one handle do not silently
+ * replace each other, that a failed delivery still sends a receipt, that a finished session is
+ * released in an order which keeps its last frames. It is not a way to test the transport: a
+ * substitute proves the substitute, and everything this package claims about reconnect, replay and
+ * `seq` is proven against the real link in `control/`.
+ */
+export interface HostLink extends FrameSink {
+    start(): void;
+    stop(detail?: string): void;
+    forgetSession(sessionId: string): void;
+    /** The version the controller chose at the last accepted handshake; optional because a test link negotiates nothing. */
+    readonly negotiatedVersion?: number | null;
+    /** Replace what the next `link_hello` declares; optional because a test link declares nothing. */
+    announce?(capabilities: readonly string[], configuration: HostConfiguration, pendingRestart: readonly string[]): void;
+}
+/**
+ * What a reconfigure produced: the pieces the host swaps in place of the ones it was composed with.
+ * `undefined` members mean the same as an omitted option at composition (no provider, no root).
+ */
+export interface HostReconfigured {
+    readonly workspaces: WorkspaceProvider | undefined;
+    readonly transcriptsRoot: string | undefined;
+    readonly bulk: BulkResolver | undefined;
+    readonly linkCapabilities: readonly string[];
+    readonly configuration: HostConfiguration;
+    readonly overriddenByEnvironment: readonly string[];
+    /** The keys written but not in effect until the next start. */
+    readonly pendingRestart: readonly string[];
+}
+/**
+ * The configuration seam a `host_configure` ask runs through. The composition root supplies it,
+ * because writing the config file and rebuilding a provider both read the environment, which is
+ * that file's job alone. `hostBusy` is true while any session is live or opening; the seam refuses
+ * a roots change by name in that state rather than writing a file the running host cannot honour.
+ */
+export type HostReconfigurer = (entries: readonly HostConfigureEntry[], hostBusy: boolean) => Result<HostReconfigured>;
+export interface PeriscopeHostOptions {
+    readonly controllerUrl: string;
+    readonly hostId: string;
+    /**
+     * The identity this host presents outbound, on the link's upgrade and on every bulk POST
+     * (resolved per delivery; a refusing credential posts headerless, and the receiver's refusal
+     * comes back as `bulk-delivery-failed`). Omitted means every outbound surface is anonymous.
+     */
+    readonly credential?: ControllerCredential;
+    readonly backoff?: BackoffOptions;
+    /**
+     * The default link's clocks: the heartbeat's interval and timeout, and how long a dial may sit
+     * without an open before it is abandoned and retried. Ignored when `link` supplies the link.
+     */
+    readonly linkTimings?: {
+        readonly heartbeatIntervalMs?: number;
+        readonly heartbeatTimeoutMs?: number;
+        readonly connectTimeoutMs?: number;
+    };
+    /** Who answers a permission escalation. Required: a host with no decider gates nothing. */
+    readonly decide: Decider;
+    /**
+     * Absolute paths the agent may never read or write, whatever its workspace.
+     *
+     * `host/paths.ts`'s `credentialPaths(env)` computes the default set; the composition root passes
+     * it in, because reading the environment is that file's job and only that file's.
+     */
+    readonly protectedPaths: readonly string[];
+    /**
+     * Which tool names the local gate treats as path writes, path reads and shell commands.
+     *
+     * Defaults to the SDK's own tools (`DEFAULT_TOOL_FAMILIES`). An MCP tool the embedder registers
+     * arrives as `mcp__{server}__{tool}`, matches nothing, and escalates with no local opinion; naming
+     * it here gives it the same local treatment as the built-in it resembles. Data, never guessed:
+     * the host cannot know which of an embedder's tools are dangerous.
+     */
+    readonly toolFamilies?: ToolFamilies;
+    /**
+     * Where sessions run. With a provider the controller's `cwd` is advisory: the provider decides,
+     * and the session's `spawning` transition carries the directory it actually got, so the
+     * controller learns where its session is rather than assuming.
+     */
+    readonly workspaces?: WorkspaceProvider;
+    /**
+     * The key an unkeyed `session_new` provisions at, when it should not be the session key
+     * (protocol v5).
+     *
+     * A default for an absence, never an override: resolution is exactly
+     * `opening.workspaceKey ?? defaultWorkspaceKey ?? sessionKey`, so a controller that names a key
+     * never has this consulted and no precedence question exists. It is what lets a library user
+     * with no controller at all get a shared tree: every unkeyed session lands in one workspace.
+     * The composition root screens the configured value at startup (same union screen as a wire
+     * key); the per-frame validation below still covers an embedder that passes one here directly.
+     */
+    readonly defaultWorkspaceKey?: string;
+    /**
+     * In-process tools this host offers every session. See the note on registration below.
+     *
+     * `identity` is not the embedder's to supply: it must be read at CALL time and only this host
+     * knows which session is calling, so it is filled in here and omitted from the type rather than
+     * accepted and ignored.
+     */
+    readonly tools?: Omit<McpServerOptions, 'identity'>;
+    readonly bulk?: BulkResolver;
+    /**
+     * Where the agent CLI's transcripts live (`~/.claude/projects`), for the discovery door.
+     *
+     * The composition root derives it (`claudeProjectsRoot(env)` in `host/claude-transcripts.ts`),
+     * because reading the environment is that layer's job. Absent means the door answers every
+     * `transcript_list` / `transcript_tail` with a named failure rather than guessing a root;
+     * `session_list` needs no filesystem and always answers.
+     */
+    readonly transcriptsRoot?: string;
+    readonly gate?: GateTimings;
+    /**
+     * Capability markers this host declares in its `link_hello`, beside the built-in `bulk-post`,
+     * never replacing it.
+     *
+     * The workspace mode rides here: the composition root computes
+     * `workspaceCapabilitiesOf(config)` (`bin/workspaces.ts`) because only it knows which provider
+     * it chose; the mode is deliberately erased from `WorkspaceProvider` itself. Markers are values
+     * in an existing open string list, so declaring a new one is not a protocol change and bumps no
+     * version; a controller that does not know a marker ignores it by construction. Values a marker
+     * cannot carry (which repository root, which scheme text) are a payload-member conversation, a
+     * version bump, and deliberately not smuggled in here.
+     */
+    readonly linkCapabilities?: readonly string[];
+    /**
+     * The values behind those markers: which roots, which scheme, which transcripts root,
+     * which controller. The composition root computes `hostConfigurationOf(config, ...)` beside the
+     * markers, from the same reading, so the two cannot disagree. Omitted, the hello reports every
+     * value as null.
+     */
+    readonly configuration?: HostConfiguration;
+    /** The wire-settable keys the environment sets, reported on a configure answer. */
+    readonly overriddenByEnvironment?: readonly string[];
+    /** The keys the file names differently from what this process dialled; empty at a fresh start. */
+    readonly pendingRestart?: readonly string[];
+    /** How a `host_configure` ask is applied. Omitted, every such ask refuses `config-write-failed`. */
+    readonly reconfigure?: HostReconfigurer;
+    readonly registry?: SessionRegistry;
+    /** How the link is built. Defaults to the real `ControllerLink`. See `HostLink`. */
+    readonly link?: (handlers: LinkHandlers) => HostLink;
+    /** The environment sessions are filtered from, when this builds its own registry. */
+    readonly baseEnv?: Readonly<Record<string, string | undefined>>;
+    readonly homeDir?: string;
+    readonly clock?: Clock;
+    readonly ticker?: Ticker;
+    /** Every named thing that happened. A host with no reporter is a host nobody can debug. */
+    readonly report?: (event: HostEvent) => void;
+}
+/** What a host reports. Data rather than log lines, so an embedder decides the format. */
+export type HostEvent = {
+    readonly kind: 'link';
+    readonly transition: LinkTransition;
+} | {
+    readonly kind: 'refusal';
+    readonly refusal: Refusal;
+    readonly sessionKey: string | null;
+} | {
+    readonly kind: 'gap';
+    readonly sessionKey: string;
+    readonly expected: number;
+    readonly received: number;
+} | {
+    readonly kind: 'session-opened';
+    readonly sessionKey: string;
+    readonly cwd: string;
+} | {
+    readonly kind: 'session-closed';
+    readonly sessionKey: string;
+} | {
+    readonly kind: 'prompt-held';
+    readonly sessionKey: string;
+    readonly held: number;
+} | {
+    readonly kind: 'prompt-delivered';
+    readonly sessionKey: string;
+    readonly delivered: number;
+} | {
+    readonly kind: 'prompt-withdrawn';
+    readonly sessionKey: string;
+    readonly withdrawn: number;
+} | {
+    readonly kind: 'transition';
+    readonly sessionKey: string;
+    readonly transition: SessionTransition;
+}
+/**
+ * A named condition that changed what is true of a session without ending it.
+ *
+ * Every degrade the sessions layer raises arrives here. The registry names its conditions (an
+ * untrusted workspace whose settings rules are silently void, an id collision whose own detail
+ * says how to resolve it) into a listener set, and a listener set with no subscribers would
+ * mean the one message that answers the operator's question is raised and never received. The
+ * subscription in `#compose` is the audience; a pin in `host.test.ts` holds every kind to it.
+ */
+ | {
+    readonly kind: 'degrade';
+    readonly sessionKey: string;
+    readonly degrade: SessionDegrade;
+};
+/**
+ * A host: one outbound link, one registry, and the dispatcher between them.
+ *
+ * It interprets exactly the payload kinds its `#dispatch` switch names and refuses the rest by
+ * name: the session commands (`session_new`, `session_prompt`, `session_cancel`,
+ * `session_configure`), `bulk_request`, and the host-scoped asks (the discovery, workspace,
+ * configure and repository asks). Derive the count from the switch below; never carry it from
+ * prose. Anything else arriving inbound is
+ * either a frame this host produces (an update, a delta, a receipt) or a kind a newer controller
+ * invented, and both are reported rather than ignored; a command that vanishes reads to the
+ * controller as a host that hung.
+ */
+export declare class PeriscopeHost {
+    #private;
+    constructor(options: PeriscopeHostOptions);
+    get link(): HostLink;
+    get registry(): SessionRegistry;
+    /** The composed session behind a controller handle, or a refusal naming the handle. */
+    session(sessionKey: string): Result<ComposedSession>;
+    start(): void;
+    /** Ends every session first, then the link — so the end transitions still have somewhere to go. */
+    stop(detail?: string): void;
+}
+//# sourceMappingURL=host.d.ts.map