@naswerks/periscope 1.0.0 → 1.0.1

package/src/persistence/transition-log.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 { isCauseEvent, isCauseKind } from '../state/model.js';
+import type { Result } from '../core/result.js';
+import { ok, refuse } 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 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: SessionTransition): TranscriptEntry {
+  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: TranscriptEntry): Result<SessionTransition> {
+  if (entry.type !== TRANSITION_ENTRY_TYPE) {
+    return refuse<SessionTransition>(
+      '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<SessionTransition>('transcript-entry-malformed', 'the transition carries no cause');
+  }
+  const { kind, event, detail } = cause as Record<string, unknown>;
+  if (typeof kind !== 'string' || !isCauseKind(kind)) {
+    return refuse<SessionTransition>(
+      'transcript-entry-malformed',
+      `the cause kind is not a declared kind: ${String(kind)}`,
+    );
+  }
+  if (typeof event !== 'string' || !isCauseEvent(event)) {
+    return refuse<SessionTransition>(
+      '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<SessionTransition>('transcript-entry-malformed', 'the transition carries no seq');
+  }
+  const where = entry['where'];
+  if (where === null || typeof where !== 'object') {
+    return refuse<SessionTransition>('transcript-entry-malformed', 'the transition carries no where');
+  }
+
+  return ok({
+    sessionId: (entry['sessionId'] as string | null) ?? null,
+    seq,
+    at: typeof entry.timestamp === 'string' ? entry.timestamp : '',
+    from: entry['from'] as SessionTransition['from'],
+    to: entry['to'] as SessionTransition['to'],
+    activity: (entry['activity'] as SessionTransition['activity']) ?? null,
+    entryId: (entry['entryId'] as string | null) ?? null,
+    cause: { kind, event, detail: typeof detail === 'string' ? detail : '' },
+    where: where as SessionTransition['where'],
+    correlationId: (entry['correlationId'] as string | null) ?? 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: OpenEntry, at: string, reason: string): TranscriptEntry {
+  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: readonly TranscriptEntry[]): Result<SessionTransition[]> {
+  const found: SessionTransition[] = [];
+  for (const entry of entries) {
+    if (entry.type !== TRANSITION_ENTRY_TYPE) continue;
+    const decoded = decodeTransition(entry);
+    if (!decoded.ok) return refuse<SessionTransition[]>(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: readonly TranscriptEntry[]): Map<string, TranscriptEntry> {
+  const marks = new Map<string, TranscriptEntry>();
+  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: SessionTransition): string {
+  return `transition:${transition.sessionId ?? 'unidentified'}:${transition.correlationId ?? '-'}:${transition.seq}`;
+}

package/src/protocol.ts

@@ -0,0 +1,215 @@
+/**
+ * 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';
+
+// The declared state model travels with the wire: a `session_update` carries a transition, so a
+// consumer parsing frames needs the vocabulary to read one. This is the model's public home — the
+// controller reads these types and builds whatever its own conventions mean on top of them.
+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';
+
+// `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 type { InboundCheck } from './control/seq.js';
+export { SeqTracker } from './control/seq.js';
+
+// The refusal vocabulary travels with the wire: a `bulk_failed` frame carries one, so a consumer
+// parsing frames needs the type to read it.
+export type { Refusal, RefusalReason } from './core/refusal.js';
+export { REFUSAL_REASONS, isRefusalReason } from './core/refusal.js';
+
+export type { Result } from './core/result.js';
+
+// ---------------------------------------------------------------------------
+// The permission surface — the one thing a controller is required to implement, so the one thing
+// this subpath must be able to type.
+//
+// The package's headline safety claim is that `@naswerks/periscope/protocol` structurally cannot reach
+// `src/host/`. Without these re-exports, a stranger writing a controller would have to import the
+// permission types from the main barrel — forfeiting the boundary the subpath exists to provide —
+// or hand-copy them, or resort to `ReturnType<typeof …>`. The one surface they cannot avoid
+// implementing would be the one surface the safe import path did not carry.
+//
+// These cost the boundary nothing, which is why they can ship here. `gate/decision.ts` has zero
+// imports and `gate/escalate.ts` imports only `./decision.js`; both are type-only from this file's
+// point of view. `src/pins/protocol-closure.test.ts` is the arbiter, and it stays green: no `host/`
+// reach, no `node:` builtin, no Node-only global.
+//
+// Note what is not here, because the omission is deliberate. `SessionStore` and `SessionKey` are
+// re-exports of the Agent SDK's own types (`host/session-store.ts`), and `readTurnSpend` is a
+// runtime function in `host/telemetry.ts`. Routing any of the three through here would either drag
+// `host/` into this closure or make the wire subpath import the Agent SDK — contradicting this
+// file's own header claim that it does not. Whether the wire should grow its own session/spend
+// types, independent of the SDK's, is a wire-vocabulary decision and belongs to whoever designs
+// the API. It is deliberately not taken here.
+// ---------------------------------------------------------------------------
+
+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';
+
+// `EscalationOptions` names a credential, so the credential's own types have to be reachable from
+// the same import path or the option is untypeable by the consumer it exists for. They cost the
+// closure nothing: `control/credential.ts` imports `core/result.ts` and nothing else — no `host/`
+// reach, no `node:` builtin, no Node-only global — so `pins/protocol-closure.test.ts` stays the
+// arbiter and stays green. The one implementation is deliberately not re-exported here: it refuses
+// by name, and a wire consumer types against the interface rather than instantiating the package's.
+export type { Authorization, ControllerCredential } from './control/credential.js';

package/src/sessions/index.ts

@@ -0,0 +1,27 @@
+/** 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';