@naswerks/periscope 1.0.0 → 1.0.1

package/src/control/stream.ts

@@ -0,0 +1,149 @@
+/**
+ * Forwarding: one session's live output becomes frames on the outbound link.
+ *
+ * This module subscribes; it does not read the stream itself. `HostedSession` already reads the
+ * agent's stream once and fans it out, because the SDK hands back a single-consumer iterator and
+ * two readers would each silently see half of it. If a second read loop ever appears in this
+ * package, one of the two consumers is losing messages and nobody is being told.
+ *
+ * A throw here is deliberately not caught. The pump already contains a subscriber that throws,
+ * reports it as `subscriber_failed` (its own kind, so a forwarder's bug cannot impersonate the
+ * process dying) and keeps reading. Catching here would name the same failure twice and leave that
+ * mechanism with nothing to catch. Ordinary failure is not a throw anyway: `send` returns a
+ * refusal, which is reported through `onRefusal` and is the caller's pressure signal.
+ *
+ * Transitions are taken from the machine, not from the message handler's return value, and that
+ * is what puts the gate on the wire. Messages are only one of three things that move a session: the
+ * hook lane records tool entries, and the gate records denials, outages, expiries and holds
+ * directly. Forwarding only what `observeMessage` returns would carry the message lane and nothing
+ * else, so every refusal this package exists to produce (the offline boundary refusal, the
+ * credential-path denial, an unreachable controller) would be visible on-box and invisible to the
+ * controller that needs it. Subscribing where they are all recorded is the only place that sees
+ * all three. The naive version of this double-emits: adding the subscription while still forwarding
+ * `observeMessage`'s results sends every message-caused transition twice, which a consumer counting
+ * state changes reads as the session having done each thing twice. The results are still read here
+ * for their refusals, which the machine never sees, and never re-emitted.
+ *
+ * The message comes before the transition it caused, always. A transition is the settled
+ * conclusion of a message, so a consumer must never see a state change that refers to a message it
+ * has not been given; it would have to render a session that "started a tool" with no tool call in
+ * hand. Ordering survives the subscription because `record` fans out to its listeners
+ * synchronously: the message is emitted, then `observeMessage` records, then the listener emits.
+ * Every payload then goes through the link's one queue, so arrival order is delivery order.
+ * A hook- or gate-caused transition has no message, and that is not a violation of the rule
+ * above; it is a fact about where it came from. A consumer must not assume every transition is
+ * preceded by the message that explains it; `cause.kind` says which lane produced it.
+ *
+ * Which lane a message rides is not decided here. `stream-routing.ts` declares it per
+ * discriminator, `satisfies Record<MessageDiscriminator, …>` against the SDK's own union. This file
+ * reads the table; it holds no judgement of its own about what matters.
+ */
+import type { SDKMessage } from '../host/agent-process.js';
+import type { HostedSession, SessionEnded, Unsubscribe } from '../sessions/session.js';
+import type { SessionObserver } from '../state/observer.js';
+import type { SessionTransition } from '../state/model.js';
+import type { Refusal } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import type { JsonObject, SessionPayload } from './frames.js';
+import { agentMessageDelta, agentMessageUpdate, stateTransitionUpdate } from './frames.js';
+import { laneFor } from './stream-routing.js';
+
+/**
+ * Where frames go. Structural rather than `ControllerLink` so the forwarder can be exercised with
+ * no socket — and so this module pulls no WebSocket dependency into a path that does not need one.
+ */
+export interface FrameSink {
+  send(sessionId: string, payload: SessionPayload): Result<void>;
+}
+
+export interface ForwardSessionOptions {
+  /**
+   * The frame's routing key: the controller's handle for this session, not the agent's own id.
+   *
+   * See `SessionFrame` in frames.ts for the three ids and why they are not interchangeable. The
+   * short version: a session's first transitions are recorded before the agent has named itself,
+   * and a session that dies in start-up never names itself at all, so keying frames by the agent's
+   * id would make exactly the frames that explain a failure unsendable.
+   */
+  readonly sessionKey: string;
+  readonly session: HostedSession;
+  /** The session's own observer. Already attached to its machine; this does not create one. */
+  readonly observer: SessionObserver;
+  readonly sink: FrameSink;
+  /**
+   * Every refusal the sink returned, and every transition the machine would not record.
+   *
+   * Wired by callers that want to know; a refusal that nobody listens to is still a refusal and is
+   * never a silent success — `send` has already declined by the time this is called.
+   */
+  readonly onRefusal?: (refusal: Refusal) => void;
+}
+
+/**
+ * Start forwarding. Returns the unsubscribe, which is idempotent.
+ *
+ * The end transition is emitted from the session's own end listener rather than from the message
+ * stream, because a session can end without its stream ending (a start timeout, a stop request)
+ * and a trace whose last row is whatever happened to arrive last is not a trace of an ending.
+ */
+export function forwardSession(options: ForwardSessionOptions): Unsubscribe {
+  const { sessionKey, session, observer, sink } = options;
+
+  const refused = (refusal: Refusal): void => options.onRefusal?.(refusal);
+
+  const emit = (payload: SessionPayload): void => {
+    const sent = sink.send(sessionKey, payload);
+    if (!sent.ok) refused(sent.refusal);
+  };
+
+  // Every transition this session records, whichever lane produced it. See this file's header.
+  const dropTransitions = observer.machine.onTransition((transition) =>
+    emit(stateTransitionUpdate(transition)),
+  );
+
+  /**
+   * A transition the machine refused is not on the wire and never will be, so this is the only
+   * place it can be named. The recorded ones are already gone out through the subscription above,
+   * which is why nothing here emits.
+   */
+  const reportRejected = (recorded: readonly Result<SessionTransition>[]): void => {
+    for (const result of recorded) if (!result.ok) refused(result.refusal);
+  };
+
+  const dropMessages = session.onMessage((message: SDKMessage) => {
+    // The message first, then what it caused. See this file's header.
+    forwardMessage(message, emit);
+    reportRejected(observer.observeMessage(message));
+  });
+
+  const dropEnd = session.onEnd((ended: SessionEnded) => {
+    reportRejected([observer.ended({ kind: 'process', event: ended.cause, detail: ended.detail })]);
+    dropMessages();
+  });
+
+  return () => {
+    dropMessages();
+    dropEnd();
+    dropTransitions();
+  };
+}
+
+/**
+ * One message onto its declared lane, or nowhere.
+ *
+ * A large message is refused, not truncated, and it will happen: a tool result carrying a big
+ * file exceeds the frame limit, `send` declines with `frame-too-large`, and the refusal names the
+ * bulk lane. That is the "commands only, never payloads" rule doing its job rather than a defect,
+ * but a consumer will see a turn whose largest tool result never arrived, so the refusal has to
+ * reach someone. It does, through `onRefusal`.
+ */
+function forwardMessage(message: SDKMessage, emit: (payload: SessionPayload) => void): void {
+  const lane = laneFor(message);
+  if (lane === 'declined') return;
+
+  // Cast rather than copy: the message arrived as JSON and the codec is where bytes and types meet,
+  // so re-validating it here would be a second wire edge. A message that genuinely cannot serialize
+  // is refused by `encode` under its own name and reaches `onRefusal` like any other refusal.
+  const body = message as unknown as JsonObject;
+  emit(lane === 'delta' ? agentMessageDelta(body) : agentMessageUpdate(body));
+}

package/src/core/async-queue.ts

@@ -0,0 +1,63 @@
+/**
+ * A single-consumer async queue: push values in, iterate them out, close when there are no more.
+ *
+ * It exists because a session's input has to be an `AsyncIterable` before the first turn is known —
+ * the agent process is started with a stream it will read from later, and the control surface
+ * (interrupt, model change, permission mode) is only available to a session driven that way. A
+ * plain string prompt would ship a session that cannot be interrupted.
+ *
+ * Pure and generic on purpose: nothing here knows what a message is, so it is testable without a
+ * process and reusable by anything else that needs the same shape.
+ */
+export class AsyncQueue<T> implements AsyncIterable<T> {
+  readonly #items: T[] = [];
+  readonly #waiting: ((result: IteratorResult<T>) => void)[] = [];
+  #ended = false;
+
+  /** Hand a value to the consumer, or hold it until one asks. Ignored after `end()`. */
+  push(item: T): void {
+    if (this.#ended) return;
+    const waiter = this.#waiting.shift();
+    if (waiter !== undefined) {
+      waiter({ value: item, done: false });
+      return;
+    }
+    this.#items.push(item);
+  }
+
+  /**
+   * No more values. Idempotent, and it releases every waiting consumer rather than leaving them
+   * hanging — an iterator that never returns is indistinguishable from a session that never ends.
+   */
+  end(): void {
+    if (this.#ended) return;
+    this.#ended = true;
+    while (this.#waiting.length > 0) {
+      this.#waiting.shift()?.({ value: undefined, done: true });
+    }
+  }
+
+  /** Values pushed but not yet taken. */
+  get depth(): number {
+    return this.#items.length;
+  }
+
+  get ended(): boolean {
+    return this.#ended;
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: (): Promise<IteratorResult<T>> => {
+        const item = this.#items.shift();
+        if (item !== undefined) return Promise.resolve({ value: item, done: false });
+        if (this.#ended) return Promise.resolve({ value: undefined, done: true });
+        return new Promise<IteratorResult<T>>((resolve) => this.#waiting.push(resolve));
+      },
+      return: (): Promise<IteratorResult<T>> => {
+        this.end();
+        return Promise.resolve({ value: undefined, done: true });
+      },
+    };
+  }
+}

package/src/core/failure.ts

@@ -0,0 +1,61 @@
+/**
+ * Describing a thrown failure so the reader learns the cause, not the wrapper.
+ *
+ * Node's `fetch` throws `TypeError: fetch failed` and puts the reason on `error.cause`; a WebSocket
+ * carries a `code` such as `DEPTH_ZERO_SELF_SIGNED_CERT`. A message that stops at the wrapper reads
+ * "could not be reached" for a controller that answered the TCP dial and refused nothing but its own
+ * certificate. So the nested causes are walked, the innermost code is named, and a certificate refusal
+ * carries the remedy, because it is the failure a local controller meets first.
+ */
+
+/** The `code` a Node error carries when TLS refused the peer's certificate. */
+const CERTIFICATE_CODES = /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|CERTIFICATE/;
+
+/** The innermost error under nested `cause` members, and the codes met on the way down. */
+function unwrap(error: unknown): { readonly leaf: unknown; readonly codes: string[] } {
+  const codes: string[] = [];
+  let current: unknown = error;
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (
+      typeof current === 'object' &&
+      current !== null &&
+      typeof (current as { code?: unknown }).code === 'string'
+    ) {
+      codes.push((current as { code: string }).code);
+    }
+    const next =
+      typeof current === 'object' && current !== null ? (current as { cause?: unknown }).cause : undefined;
+    if (next === undefined || next === null) break;
+    current = next;
+  }
+  return { leaf: current, codes };
+}
+
+/** Is this failure TLS refusing the peer's certificate? Read off every `code` met on the way down. */
+export function isCertificateRefusal(error: unknown): boolean {
+  return unwrap(error).codes.some((code) => CERTIFICATE_CODES.test(code));
+}
+
+/**
+ * The failure in one line: the innermost message, prefixed by the innermost code when there is one.
+ * `fetch failed` becomes `DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate`.
+ */
+export function describeFailure(error: unknown): string {
+  const { leaf, codes } = unwrap(error);
+  const message = leaf instanceof Error ? leaf.message : typeof leaf === 'string' ? leaf : String(leaf);
+  const code = codes.at(-1);
+  return code === undefined || message.includes(code) ? message : `${code}: ${message}`;
+}
+
+/**
+ * What to do about a certificate refusal, in the operator's words. Stated once, here, so the pair
+ * verb, the decision transport and the link say the same thing.
+ */
+export function certificateRemedy(where: string): string {
+  return (
+    `Node does not trust the certificate ${where} presents. For a controller on a development ` +
+    `certificate, export that certificate as PEM and point Node at it: set NODE_EXTRA_CA_CERTS to the ` +
+    `file's path, then run this command again in a new terminal. Disabling verification ` +
+    `(NODE_TLS_REJECT_UNAUTHORIZED=0) also works and trusts every certificate; prefer the file.`
+  );
+}

package/src/core/index.ts

@@ -0,0 +1,22 @@
+/**
+ * The pure core: no `node:` imports, no packages, no I/O.
+ *
+ * Pinned by src/pins/core-purity.test.ts. The point is that anything here runs anywhere — in the
+ * host, in a controller, in a browser — so the contract types can be shared without dragging a
+ * runtime along with them.
+ */
+export type { Refusal, RefusalReason } from './refusal.js';
+export { REFUSAL_REASONS, isRefusalReason, refusal } from './refusal.js';
+
+export type { Result } from './result.js';
+export { isOk, ok, refuse, valueOr } from './result.js';
+
+export type { HostNoun, SdkNoun } from './vocab.js';
+export { HOST_NOUNS, SDK_NOUNS, isDeclaredNoun, nounOf } from './vocab.js';
+
+export { isAbsolutePath, isContainedBy, normalizePath, requireAbsolute } from './paths.js';
+
+export { MAX_WORKSPACE_ID_LENGTH } from './workspace-id.js';
+
+export type { Clock, Ticker } from './time.js';
+export { fixedClock, fixedTicker, systemClock, systemTicker } from './time.js';

package/src/core/keyed-turns.ts

@@ -0,0 +1,47 @@
+/**
+ * A per-key serial executor: work submitted under one key runs one piece at a time, in arrival
+ * order; work under different keys interleaves freely.
+ *
+ * It exists because the host's workspace verbs are fire-and-forget concurrent (`#dispatch` never
+ * awaits a handler) while the work they do takes seconds and is mutually destructive on one key:
+ * a `git worktree add` and a `git worktree remove --force` each take many seconds, and the
+ * reachable interleavings are real — a provision landing inside a removal, a removal landing inside
+ * a close's release. Serializing per key closes every one of those windows without making
+ * unrelated workspaces wait on each other.
+ *
+ * Pure and generic on purpose: nothing here knows what a workspace is, so it is testable without
+ * a provider and reusable by anything else that needs the same shape.
+ */
+export class KeyedTurns {
+  /** The tail of each key's queue — the promise the next submission must wait behind. */
+  readonly #tails = new Map<string, Promise<unknown>>();
+
+  /**
+   * Run `work` after everything previously submitted under `key` has settled.
+   *
+   * The returned promise carries `work`'s own result or rejection. A rejection does not poison the
+   * key: the next submission runs regardless, because a failed removal must not wedge every future
+   * provision at that key behind an error nobody can clear.
+   */
+  async run<T>(key: string, work: () => Promise<T>): Promise<T> {
+    const previous = this.#tails.get(key) ?? Promise.resolve();
+    const turn = previous.then(work, work);
+    // The tail entry is removed when this turn settles with nothing queued behind it. The map
+    // identity check is what makes the cleanup safe under concurrent submission: a newer tail
+    // means a later submission queued behind this one, and the entry is now that one's to clean up.
+    const tail = turn.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.#tails.set(key, tail);
+    void tail.then(() => {
+      if (this.#tails.get(key) === tail) this.#tails.delete(key);
+    });
+    return turn;
+  }
+
+  /** Keys with unsettled work — an observability convenience, never a guard. */
+  get depth(): number {
+    return this.#tails.size;
+  }
+}

package/src/core/paths.ts

@@ -0,0 +1,84 @@
+/**
+ * Path handling, written without `node:path` because this module is import-free by contract.
+ *
+ * Absolute always, on the wire and at every boundary — a relative path means "relative to a cwd the
+ * other end cannot see", which is a bug waiting for a second machine.
+ */
+import type { Result } from './result.js';
+import { ok, refuse } from './result.js';
+
+const WINDOWS_DRIVE = /^[A-Za-z]:[\\/]/;
+
+/** POSIX `/x`, Windows `C:\x`, or a UNC `\\server\share`. */
+export function isAbsolutePath(candidate: string): boolean {
+  if (candidate.startsWith('/')) return true;
+  if (candidate.startsWith('\\\\')) return true;
+  return WINDOWS_DRIVE.test(candidate);
+}
+
+/**
+ * Separators to `/`, redundant separators collapsed, `.` dropped and `..` resolved textually.
+ *
+ * Textual resolution deliberately does NOT consult the filesystem, so it cannot follow a symlink.
+ * A caller enforcing a real jail must canonicalize through the filesystem first — see
+ * `host/`, which is the only module that can.
+ */
+export function normalizePath(input: string): string {
+  const isUnc = input.startsWith('\\\\');
+  const unified = input.replace(/\\/g, '/');
+  const hasDrive = WINDOWS_DRIVE.test(input);
+  const rooted = unified.startsWith('/') || hasDrive || isUnc;
+
+  const segments: string[] = [];
+  let prefix = '';
+
+  let body = unified;
+  if (hasDrive) {
+    prefix = `${unified.slice(0, 2)}/`;
+    body = unified.slice(3);
+  } else if (isUnc) {
+    prefix = '//';
+    body = unified.slice(2);
+  } else if (rooted) {
+    prefix = '/';
+    body = unified.slice(1);
+  }
+
+  for (const segment of body.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+        segments.pop();
+      } else if (!rooted) {
+        segments.push('..');
+      }
+      // Rooted paths cannot climb above their root; `/..` is `/`.
+      continue;
+    }
+    segments.push(segment);
+  }
+
+  const joined = segments.join('/');
+  if (prefix === '') return joined === '' ? '.' : joined;
+  return prefix + joined;
+}
+
+/** Normalizes, and refuses anything not absolute. The shape every boundary should take. */
+export function requireAbsolute(candidate: string): Result<string> {
+  if (!isAbsolutePath(candidate)) {
+    return refuse('path-not-absolute', `not an absolute path: ${candidate}`);
+  }
+  return ok(normalizePath(candidate));
+}
+
+/**
+ * Is `candidate` at or beneath `root`? Both are normalized first; the comparison is
+ * segment-wise, so `/a/bc` is NOT inside `/a/b`.
+ */
+export function isContainedBy(candidate: string, root: string): boolean {
+  const normalizedRoot = normalizePath(root);
+  const normalizedCandidate = normalizePath(candidate);
+  if (normalizedCandidate === normalizedRoot) return true;
+  const boundary = normalizedRoot.endsWith('/') ? normalizedRoot : `${normalizedRoot}/`;
+  return normalizedCandidate.startsWith(boundary);
+}