@naswerks/periscope 1.0.0

package/dist/state/machine.js

@@ -0,0 +1,237 @@
+import { ok, refuse } from '../core/result.js';
+import { isCauseEvent, isCauseKind } from './model.js';
+/**
+ * The state a machine holds before anything has been recorded.
+ *
+ * A machine is constructed at the moment a process is asked for, and the first record is the
+ * `spawning` one. Until then `from` has to be something, and `spawning` is the honest answer: the
+ * caller has already decided to start a session.
+ */
+const INITIAL_STATE = 'spawning';
+export class SessionStateMachine {
+    /** Only until the first record. After that `where` is derived like everything else. */
+    #initialWhere;
+    #clock;
+    #ticker;
+    #correlationId;
+    #entries = new Map();
+    #listeners = new Set();
+    #rejectionListeners = new Set();
+    /** The last recorded transition. The only mutable state, assigned in exactly one place. */
+    #current = null;
+    #seq = 0;
+    #rejectedCount = 0;
+    constructor(options) {
+        this.#initialWhere = options.where;
+        this.#clock = options.clock;
+        this.#ticker = options.ticker;
+        this.#correlationId = options.correlationId ?? null;
+    }
+    /** Derived from the last transition. There is no field to set. */
+    get state() {
+        return this.#current?.to ?? INITIAL_STATE;
+    }
+    /** Derived from the open-entry set. There is no field to set. */
+    get activity() {
+        return foregroundActivity(this.#entries);
+    }
+    /** Null until the agent reports itself; carried forward after. There is no field to set. */
+    get sessionId() {
+        return this.#current?.sessionId ?? null;
+    }
+    get correlationId() {
+        return this.#correlationId;
+    }
+    /** Derived from the last transition. There is no field to set. */
+    get where() {
+        return this.#current?.where ?? this.#initialWhere;
+    }
+    get transitionCount() {
+        return this.#seq;
+    }
+    /** How many transitions were refused for an unnameable cause. Never silently zero. */
+    get rejectedCount() {
+        return this.#rejectedCount;
+    }
+    /** Every entry that has not exited, with the number a human wants: how long it has been open. */
+    openEntries() {
+        const now = this.#ticker();
+        return [...this.#entries.values()].map((entry) => ({
+            ...entry,
+            ageMs: Math.max(0, now - Date.parse(entry.openedAt)),
+        }));
+    }
+    onTransition(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    onRejected(listener) {
+        this.#rejectionListeners.add(listener);
+        return () => this.#rejectionListeners.delete(listener);
+    }
+    /**
+     * Record a transition. The only way a session's state changes.
+     *
+     * The only thing this branches on is whether the cause can be named. Nothing about which
+     * session this is, how it was created, or whether anyone is listening is reachable from here —
+     * see this file's header. `#commit` below is straight-line by construction.
+     */
+    record(request) {
+        const named = nameable(request.cause);
+        if (named !== null)
+            return this.#reject(named, request);
+        return ok(this.#commit(request));
+    }
+    /** What this host can say about this session. Raw material for a controller — not a roster. */
+    snapshot() {
+        return {
+            sessionId: this.sessionId,
+            correlationId: this.#correlationId,
+            state: this.state,
+            activity: this.activity,
+            where: this.where,
+            openEntries: this.openEntries(),
+            lastTransitionAt: this.#current?.at ?? null,
+            transitionCount: this.#seq,
+        };
+    }
+    // -------------------------------------------------------------------------
+    /**
+     * The single mutation point. Straight-line: every call that reaches here records.
+     *
+     * Do not add a guard to this method. A condition here is a session whose state changed without
+     * saying so, which is the defect this whole module exists to prevent.
+     */
+    #commit(request) {
+        const carried = carryForward(request, this.#current, this.#initialWhere, this.#clock);
+        const entryId = applyEntryOp(this.#entries, carried.entry, carried.at, request.cause);
+        this.#seq += 1;
+        const transition = {
+            sessionId: carried.sessionId,
+            seq: this.#seq,
+            at: carried.at,
+            from: carried.from,
+            to: request.to,
+            activity: foregroundActivity(this.#entries),
+            entryId,
+            cause: request.cause,
+            where: carried.where,
+            correlationId: this.#correlationId,
+        };
+        this.#current = transition;
+        for (const listener of this.#listeners)
+            listener(transition);
+        return transition;
+    }
+    #reject(detail, attempted) {
+        this.#rejectedCount += 1;
+        const refusal = { reason: 'transition-cause-unnamed', detail };
+        const rejected = { refusal, at: this.#clock(), attempted };
+        for (const listener of this.#rejectionListeners)
+            listener(rejected);
+        return refuse('transition-cause-unnamed', detail);
+    }
+}
+/**
+ * The four values a transition inherits from the one before it, resolved in one place.
+ *
+ * They are lifted out of `#commit` deliberately. Each is a defaulting expression — "use what was
+ * given, else what the last transition carried" — and a defaulting expression is still a branch in
+ * the shape of one. Keeping them here leaves the commit path with no conditional of any kind, so
+ * "the record cannot be skipped" is a claim a reader can check by looking rather than by trusting.
+ */
+function carryForward(request, current, initialWhere, clock) {
+    return {
+        at: request.at ?? clock(),
+        from: current?.to ?? INITIAL_STATE,
+        sessionId: request.sessionId ?? current?.sessionId ?? null,
+        where: request.where ?? current?.where ?? initialWhere,
+        entry: request.entry ?? null,
+    };
+}
+/**
+ * Null when the cause is nameable, otherwise why it is not.
+ *
+ * The compiler already closes `CauseEvent`, so this only fires for a value that never met the
+ * compiler — a cause rebuilt from a decoded frame, or a caller in plain JavaScript.
+ */
+function nameable(cause) {
+    if (cause === undefined || cause === null)
+        return 'a transition carried no cause at all';
+    if (!isCauseKind(cause.kind))
+        return `cause.kind "${String(cause.kind)}" is not a declared cause kind`;
+    if (typeof cause.event !== 'string' || cause.event.length === 0)
+        return 'cause.event is empty';
+    if (!isCauseEvent(cause.event))
+        return `cause.event "${String(cause.event)}" is not a declared cause event`;
+    return null;
+}
+/**
+ * What holds the session right now: the most recently opened foreground entry.
+ *
+ * Background entries are excluded by construction — that is the whole point of the lane. Abandoned
+ * entries are excluded too: they are still recorded and still ageing, but a session is not blocked
+ * on work that has been marked as never coming back.
+ *
+ * Most-recent rather than oldest, because `activity` answers "what is it doing now". "What has it
+ * been stuck on longest" is a different question, and `openEntries()` with its ages answers it
+ * without this field having to mean two things.
+ */
+function foregroundActivity(entries) {
+    let held = null;
+    for (const entry of entries.values()) {
+        if (entry.lane !== 'foreground')
+            continue;
+        if (entry.abandonedAt !== null)
+            continue;
+        held = entry;
+    }
+    return held?.activity ?? null;
+}
+/** Applies one entry operation and returns the entry it touched, or null. Pure over the map. */
+function applyEntryOp(entries, op, at, cause) {
+    if (op === null)
+        return null;
+    if (op.op === 'open') {
+        // Re-opening the same entry keeps the original openedAt. Two sources can report the same
+        // condition (the compaction hook and the status message both say "compacting"), and taking the
+        // later timestamp would silently reset the age — which is the one number an unpaired entry
+        // exists to carry. The transition still records either way; only the clock is protected.
+        const existing = entries.get(op.entryId);
+        const sameThing = existing !== undefined && existing.activity.kind === op.activity.kind;
+        entries.set(op.entryId, {
+            entryId: op.entryId,
+            activity: op.activity,
+            lane: 'foreground',
+            openedAt: sameThing ? existing.openedAt : at,
+            backgroundedAt: null,
+            abandonedAt: null,
+            abandonReason: null,
+            cause,
+            agentId: op.agentId ?? null,
+        });
+        return op.entryId;
+    }
+    if (op.op === 'close') {
+        entries.delete(op.entryId);
+        return op.entryId;
+    }
+    if (op.op === 'background') {
+        const open = entries.get(op.entryId);
+        // A background report for an entry this host never saw open is not an error and not a state
+        // change: the transition still records, naming the id, and the entry set is simply unchanged.
+        if (open === undefined)
+            return op.entryId;
+        entries.set(op.entryId, { ...open, lane: 'background', backgroundedAt: at });
+        return op.entryId;
+    }
+    // abandon-open: mark, never erase. An entry that never exited is the most useful thing this
+    // model can report, and a cleanup that deleted it would destroy exactly that signal.
+    for (const [entryId, entry] of entries) {
+        if (entry.abandonedAt !== null)
+            continue;
+        entries.set(entryId, { ...entry, abandonedAt: at, abandonReason: op.reason });
+    }
+    return null;
+}
+//# sourceMappingURL=machine.js.map

package/dist/state/model.d.ts

@@ -0,0 +1,233 @@
+/**
+ * The declared state model — what a session is at a moment, and what caused it to become that.
+ *
+ * This is the one model. There is no second status word anywhere in this package: a layer that
+ * finds itself wanting one has found a state missing from here, not a column of its own. A single
+ * word such as `running` that covers responding, tool-calling, waiting on a permission decision,
+ * compacting, and finished-and-waiting-for-input answers nobody's question, and every reader
+ * downstream of it ends up inferring.
+ *
+ * Two fields, never one composed string, and structured all the way down.
+ * `state` is the coarse lifecycle; `activity` is what a working session is blocked on right now. A
+ * composed string cannot be queried or aggregated without parsing it back apart, and "show me every
+ * session waiting on a permission decision" is the question this model is built to answer. The same
+ * argument applies one level in, which is why `activity` is `{kind, name}` rather than `tool:Bash`:
+ * `formatActivity` exists for display, and the structure is the truth.
+ *
+ * The vocabulary is the SDK's wherever the SDK has a word. `requesting` and `compacting` are
+ * `SDKStatus` verbatim; `permission`, `tool`, `subagent` are the SDK's nouns. Where the SDK is
+ * silent this package is the author, and the table below says which is which — the same separation
+ * `core/vocab.ts` draws between SDK_NOUNS and HOST_NOUNS, for the same reason.
+ *
+ * Nothing here imports the SDK or a runtime, so the model ships on `periscope/protocol` and a
+ * controller can read a transition without acquiring a package that can spawn a process.
+ */
+import type { RefusalReason } from '../core/refusal.js';
+export declare const SESSION_STATES: readonly ["spawning", "ready", "working", "idle", "errored", "interrupted", "ended"];
+export type SessionState = (typeof SESSION_STATES)[number];
+/**
+ * Where each activity kind's name comes from. Two are the SDK's own words; four extend it.
+ *
+ * `requesting` and `compacting` are `SDKStatus` verbatim — two values and a null. The SDK has no
+ * word for the other four situations, so this package names them, and this table is where that is
+ * recorded rather than left for a reader to guess.
+ */
+export declare const ACTIVITY_KINDS: readonly ["requesting", "compacting", "tool", "subagent", "permission", "elicitation"];
+export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
+/** Which activity kinds this package named itself, kept visible the way HOST_NOUNS is. */
+export declare const HOST_ACTIVITY_KINDS: readonly ActivityKind[];
+/** SDK: `SDKStatus`'s two non-null values, adopted verbatim. */
+export declare const SDK_ACTIVITY_KINDS: readonly ActivityKind[];
+export interface SessionActivity {
+    readonly kind: ActivityKind;
+    /** The tool, subagent type or server this is about. Null where the kind carries no name. */
+    readonly name: string | null;
+}
+/** The display form — `tool:Bash`, `requesting`. For logs and humans; never parsed back. */
+export declare function formatActivity(activity: SessionActivity | null): string;
+export declare function sameActivity(left: SessionActivity | null, right: SessionActivity | null): boolean;
+/**
+ * Where a transition came from. A transition that cannot name its cause is not recorded.
+ *
+ * `refusal` is the sixth and it is load-bearing: a permission denial is a hook event, but a
+ * permission-path outage has no hook at all, and with five kinds the difference would have to ride
+ * `detail` — free text a reader greps instead of a fact code branches on. Conflating an outage with
+ * a deliberate "no" is the most expensive confusion a controller can make, so the two differ in
+ * `kind` and in `event`, twice over, neither of them prose.
+ */
+export declare const CAUSE_KINDS: readonly ["hook", "sdk-message", "control", "timeout", "process", "refusal"];
+export type CauseKind = (typeof CAUSE_KINDS)[number];
+/**
+ * The SDK's hook events, mirrored as values so they can be validated at runtime.
+ *
+ * Kept in step by two checks, because a list copied out of a type rots silently: `coverage.ts`
+ * declares its table `satisfies Record<HookEvent, …>` so a new SDK event breaks the build, and
+ * `pins/hook-coverage.test.ts` parses the union straight out of the shipped `sdk.d.ts` and fails
+ * when this list disagrees with it.
+ */
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "DirectoryAdded", "MessageDisplay"];
+export type HookEventName = (typeof HOOK_EVENTS)[number];
+/**
+ * The SDK message discriminators this model names as causes — `type` for the plain kinds,
+ * `type/subtype` for the `system` family. Only the ones that can move a session appear here;
+ * `coverage.ts` accounts for all 39 members of the union, wired or declined.
+ */
+export declare const MESSAGE_EVENTS: readonly ["system/init", "system/status", "system/session_state_changed", "system/compact_boundary", "system/task_started", "system/task_updated", "system/task_notification", "system/permission_denied", "system/elicitation_complete", "system/worker_shutting_down", "assistant", "result"];
+export type MessageEventName = (typeof MESSAGE_EVENTS)[number];
+/**
+ * Calls the host makes on itself or is asked to make. Not SDK events — decisions.
+ *
+ * `kind` and `event` are validated independently and never as a pair. `machine.ts`'s `nameable()`
+ * checks that the kind is a declared kind and that the event is a declared event, in two separate
+ * guards — so `{kind:'hook', event:'permission_denied'}` passes while being incoherent. Pairing a
+ * cause with the right kind is the author's job, not the machine's.
+ *
+ * `permission_denied` sits here rather than in HOOK_EVENTS because a gate's deny is a call the host
+ * makes on itself: it is decided by this package, not reported to it. The SDK's `PermissionDenied`
+ * hook is a different thing that belongs to the SDK's own prompt path and does not fire for a
+ * hook-authored deny — measured — so naming it here would put an event in the trace that never
+ * happened, and would make a reader grepping traces conclude the hook fires.
+ */
+export declare const CONTROL_EVENTS: readonly ["create_requested", "prompt_submitted", "interrupt_requested", "stop_requested", "permission_denied"];
+export type ControlEventName = (typeof CONTROL_EVENTS)[number];
+/**
+ * The agent process's own lifecycle, as causes.
+ *
+ * These subsume `SESSION_END_CAUSES` deliberately. `sessions/session.ts` states four end causes
+ * local to the handle, and its own comment says the layer owning the declared state model maps them
+ * onto its causes. This is that layer, and this is that mapping — one cause vocabulary, not two.
+ * `state/reconciliation.test.ts` asserts the containment so it cannot drift.
+ */
+export declare const PROCESS_EVENTS: readonly ["process_started", "stop_requested", "process_ended", "process_failed", "start_timed_out"];
+export type ProcessEventName = (typeof PROCESS_EVENTS)[number];
+export declare const TIMEOUT_EVENTS: readonly ["start_timed_out", "hook_timed_out"];
+export type TimeoutEventName = (typeof TIMEOUT_EVENTS)[number];
+/**
+ * The gate's expiry, named once.
+ *
+ * One concept with two spellings — `hook_timed_out` on the transition, and `hook-timed-out` as
+ * the prefix of the deny reason handed to the model — looks exactly like a declared refusal reason
+ * (its sibling branch really is one) while resolving to nothing, so a reader who looks it up finds
+ * no such name. `satisfies` ties it to the closed vocabulary above, so the two cannot drift apart
+ * without breaking the build.
+ */
+export declare const HOOK_TIMEOUT_EVENT = "hook_timed_out";
+/**
+ * Every name a cause may carry. Closed, so a transition that cannot name its cause does not
+ * compile — the strongest available form of "cause is not nullable".
+ */
+export type CauseEvent = HookEventName | MessageEventName | ControlEventName | ProcessEventName | TimeoutEventName | RefusalReason;
+/** The runtime half. A frame decoded from the wire was never seen by the compiler. */
+export declare function isCauseEvent(value: string): value is CauseEvent;
+export declare function isCauseKind(value: string): value is CauseKind;
+export interface TransitionCause {
+    readonly kind: CauseKind;
+    /** The literal hook, message or control event that fired. Never free text. */
+    readonly event: CauseEvent;
+    /** For a human reading a log. Never branched on — that is what `kind` and `event` are for. */
+    readonly detail: string;
+}
+/**
+ * Which session, which worktree, which branch — so the trace answers "where" without a transcript.
+ *
+ * A null `worktree` or `branch` is a named outcome: `unknownReason` says which of the ordinary
+ * situations produced it (not a repository, detached HEAD, unreadable HEAD). An empty string would
+ * make "not in a repository" and "in a repository whose HEAD could not be read" the same value.
+ */
+export interface TransitionWhere {
+    readonly cwd: string;
+    readonly worktree: string | null;
+    readonly branch: string | null;
+    readonly unknownReason: string | null;
+}
+/**
+ * One recorded transition. The shape follows `control/link-state.ts`'s `LinkTransition` on purpose
+ * — `{from, to, cause, at, detail}` with a required cause is this package's established shape for a
+ * state machine, and two shapes for one idea is how vocabularies drift apart.
+ */
+export interface SessionTransition {
+    /**
+     * The agent's own session id — null until it has reported itself, and never null again after.
+     *
+     * The host does not mint one. An agent emits nothing until a turn is queued, so there is a
+     * real window with a live process and no id, and inventing a name for it would be exactly the
+     * "coin a word by observation" failure this package is written against. A controller that needs
+     * to correlate its request with the session it became supplies `correlationId`.
+     */
+    readonly sessionId: string | null;
+    /** Dense from 1, per session-machine. A gap is detectable by arithmetic alone. */
+    readonly seq: number;
+    readonly at: string;
+    readonly from: SessionState;
+    readonly to: SessionState;
+    /** What the session is blocked on after this transition. Null when nothing holds it. */
+    readonly activity: SessionActivity | null;
+    /** The open entry this transition opened, closed or backgrounded. Null when it touched none. */
+    readonly entryId: string | null;
+    readonly cause: TransitionCause;
+    readonly where: TransitionWhere;
+    /**
+     * Opaque, controller-supplied, and never interpreted here.
+     *
+     * It exists so a controller can tie a session back to whatever it means on its side. The host
+     * does not parse it, branch on it, or derive anything from it — the moment it did, this package
+     * would know something about one product's conventions and stop being general.
+     */
+    readonly correlationId: string | null;
+}
+/**
+ * Foreground work holds the session; background work does not.
+ *
+ * A backgrounded task produces an entry that never exits while the turn moves on — without this
+ * split, a session that starts a long build reads as blocked on it forever. The move happens at the
+ * moment the SDK reports the task backgrounded, with that as the cause; never on a timer and never
+ * by inference. A backgrounded entry is not a finished one: it stays open, it keeps ageing, and it
+ * still gets an exit.
+ */
+export type EntryLane = 'foreground' | 'background';
+export interface OpenEntry {
+    /** The SDK's own id for the thing — `tool_use_id`, `agent_id`, `task_id`. Never minted here. */
+    readonly entryId: string;
+    readonly activity: SessionActivity;
+    readonly lane: EntryLane;
+    readonly openedAt: string;
+    /** When it stopped holding the session. Null while it still does. */
+    readonly backgroundedAt: string | null;
+    /**
+     * When cleanup marked it abandoned. Cleanup may mark; it may never erase.
+     *
+     * A session sitting in one tool call for forty minutes is the most useful thing this model can
+     * report, and a reconciler that quietly closes the entry destroys exactly that signal. So an
+     * unpaired entry is surfaced with its age and a reason, and the fact that it happened survives.
+     */
+    readonly abandonedAt: string | null;
+    readonly abandonReason: string | null;
+    /** Why it opened. Carried so an entry read weeks later still says what started it. */
+    readonly cause: TransitionCause;
+    /** Set when the entry belongs to a subagent rather than the main thread. */
+    readonly agentId: string | null;
+}
+/** An open entry with the number a human actually wants. */
+export interface AgedEntry extends OpenEntry {
+    readonly ageMs: number;
+}
+/**
+ * One session, as this host sees it.
+ *
+ * This is not a roster and must not grow into one. A roster spans every session everywhere, and
+ * sessions live on different hosts — an agent runs where its host runs, so no single host can
+ * produce one. This enumerates the sessions this host holds, which is the raw material a controller
+ * aggregates into a roster on its side. If this grows a filter, a search or a notion of what a
+ * session means, the boundary has been crossed.
+ */
+export interface SessionSnapshot {
+    readonly sessionId: string | null;
+    readonly correlationId: string | null;
+    readonly state: SessionState;
+    readonly activity: SessionActivity | null;
+    readonly where: TransitionWhere;
+    readonly openEntries: readonly AgedEntry[];
+    readonly lastTransitionAt: string | null;
+    readonly transitionCount: number;
+}
+//# sourceMappingURL=model.d.ts.map