@naswerks/periscope 1.0.0 → 1.0.1

package/src/identity/store.ts

@@ -0,0 +1,98 @@
+/**
+ * What is persisted, and the port that persists it.
+ *
+ * The shape and its validation live here, not with the filesystem, and the dependency direction
+ * is the reason: `host/` may import this, and this may never import `host/`. Reading a cache is two
+ * jobs — getting bytes off a disk, and deciding whether what they say is usable — and only the
+ * first needs a machine. Keeping the second here means every malformed-cache branch is drivable
+ * without writing a file.
+ */
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { AuthProtocol } from './device-code.js';
+import type { TokenSet } from './token.js';
+
+/**
+ * The persisted record.
+ *
+ * `authority` and `clientId` ride along so a cache minted against one provider is never presented
+ * to another — a re-pointed host discards rather than replays, which matters because the token
+ * would otherwise be sent to an audience it was not issued for. `protocol` exists for the
+ * protocol-mismatch guard: material minted by one flow is discarded rather than refreshed when the
+ * host is configured for the other.
+ */
+export interface CachedTokens {
+  readonly tokens: TokenSet;
+  readonly protocol: AuthProtocol;
+  readonly authority: string;
+  readonly clientId: string;
+}
+
+/**
+ * The port the credential holds.
+ *
+ * An interface rather than the concrete file cache so the credential's whole decision surface —
+ * expired, re-pointed, wrong protocol, corrupt — is testable with an in-memory double, and so an
+ * embedder with its own secret storage can supply one without this package growing an opinion
+ * about keychains.
+ */
+export interface TokenStore {
+  read(): Result<CachedTokens>;
+  write(cached: CachedTokens): Result<unknown>;
+  clear(): void;
+}
+
+/** Validate a parsed cache into the shape the rest of the host relies on. */
+export function readCachedTokens(parsed: unknown): Result<CachedTokens> {
+  if (typeof parsed !== 'object' || parsed === null) {
+    return refuse('credential-cache-unreadable', 'the token cache is not a JSON object');
+  }
+  const record = parsed as Record<string, unknown>;
+  const tokens = record['tokens'];
+  const protocol = record['protocol'];
+  const authority = record['authority'];
+  const clientId = record['clientId'];
+
+  if (typeof tokens !== 'object' || tokens === null) {
+    return refuse('credential-cache-unreadable', 'the token cache carries no tokens object');
+  }
+  const tokenRecord = tokens as Record<string, unknown>;
+  const accessToken = tokenRecord['accessToken'];
+  const expiresAt = tokenRecord['expiresAt'];
+
+  if (typeof accessToken !== 'string' || accessToken === '' || typeof expiresAt !== 'number') {
+    return refuse(
+      'credential-cache-unreadable',
+      'the cached token has no accessToken or no numeric expiresAt',
+    );
+  }
+  if (protocol !== 'loopback' && protocol !== 'device-code') {
+    return refuse(
+      'credential-cache-unreadable',
+      'the token cache does not say which flow minted it, so it cannot be safely refreshed',
+    );
+  }
+  if (typeof authority !== 'string' || authority === '' || typeof clientId !== 'string' || clientId === '') {
+    return refuse(
+      'credential-cache-unreadable',
+      'the token cache does not record the authority and client it was minted for',
+    );
+  }
+
+  const refreshToken = tokenRecord['refreshToken'];
+  const tokenType = tokenRecord['tokenType'];
+  const scope = tokenRecord['scope'];
+
+  return ok({
+    tokens: {
+      accessToken,
+      refreshToken: typeof refreshToken === 'string' && refreshToken !== '' ? refreshToken : null,
+      expiresAt,
+      tokenType: typeof tokenType === 'string' && tokenType !== '' ? tokenType : 'Bearer',
+      scope: typeof scope === 'string' ? scope : null,
+    },
+    protocol,
+    authority,
+    clientId,
+  });
+}

package/src/identity/token.ts

@@ -0,0 +1,203 @@
+/**
+ * The token exchange — building the requests, reading the responses, and deciding when what the
+ * host holds is still usable. Pure: no network here, so every branch including the ugly ones is
+ * drivable.
+ *
+ * The redaction in this file is load-bearing, not hygiene. Mapping a provider's error response
+ * into a readable message is the single most likely place a token ends up in a log, because the
+ * natural implementation — echo the body so the operator can see what happened — is also the one
+ * that writes credential material to disk. Everything a provider says passes through
+ * `redactSecrets` before it becomes a refusal `detail`, and `token.test.ts` drives a failure path
+ * carrying a token and asserts the token appears nowhere in the output.
+ */
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { IdentityConfig } from './config.js';
+
+/** What this host holds after a successful exchange. */
+export interface TokenSet {
+  readonly accessToken: string;
+  /** Null when the provider issued none — then expiry means an interactive sign-in. */
+  readonly refreshToken: string | null;
+  /** Epoch milliseconds. */
+  readonly expiresAt: number;
+  readonly tokenType: string;
+  readonly scope: string | null;
+}
+
+/**
+ * How long before expiry a token is treated as already expired.
+ *
+ * A token that expires in four seconds is not usable for a request that takes five. The skew also
+ * covers clock drift between this host and the provider, which is why it is generous.
+ */
+export const EXPIRY_SKEW_MS = 60_000;
+
+/** The field names whose values must never reach a log, at any nesting depth. */
+const SECRET_FIELDS = ['access_token', 'refresh_token', 'id_token', 'code', 'code_verifier', 'client_secret'];
+
+/**
+ * Collect every credential-shaped value in a parsed body.
+ *
+ * Recursive because providers nest error payloads, and a token one level down is exactly as
+ * damaging as one at the top.
+ */
+export function secretsIn(body: unknown): string[] {
+  const found: string[] = [];
+  const visit = (node: unknown, depth: number): void => {
+    if (depth > 8 || typeof node !== 'object' || node === null) return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item, depth + 1);
+      return;
+    }
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      if (SECRET_FIELDS.includes(key) && typeof value === 'string' && value !== '') found.push(value);
+      else visit(value, depth + 1);
+    }
+  };
+  visit(body, 0);
+  return found;
+}
+
+/** Replace every known secret with a marker. Longest first, so a prefix cannot leave a tail behind. */
+export function redactSecrets(text: string, secrets: readonly string[]): string {
+  let out = text;
+  for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+    if (secret === '') continue;
+    out = out.split(secret).join('[redacted]');
+  }
+  return out;
+}
+
+/** Bound a provider-supplied string before it becomes a message. */
+function bounded(value: string, max = 200): string {
+  return value.length <= max ? value : `${value.slice(0, max)}… (${value.length} chars)`;
+}
+
+function form(pairs: Record<string, string>): string {
+  const body = new URLSearchParams();
+  for (const [key, value] of Object.entries(pairs)) body.set(key, value);
+  return body.toString();
+}
+
+/** The authorization-code redemption body. */
+export function codeExchangeBody(
+  config: IdentityConfig,
+  code: string,
+  codeVerifier: string,
+  redirectUri: string,
+): string {
+  return form({
+    grant_type: 'authorization_code',
+    client_id: config.clientId,
+    code,
+    redirect_uri: redirectUri,
+    code_verifier: codeVerifier,
+    scope: config.scopes.join(' '),
+  });
+}
+
+/** The refresh body. */
+export function refreshBody(config: IdentityConfig, refreshToken: string): string {
+  return form({
+    grant_type: 'refresh_token',
+    client_id: config.clientId,
+    refresh_token: refreshToken,
+    scope: config.scopes.join(' '),
+  });
+}
+
+/**
+ * Turn a token-endpoint response into a `TokenSet`, or into the right kind of refusal.
+ *
+ * Two failure reasons, and they must not be collapsed — the same discipline the permission gate
+ * uses. A non-2xx is the provider refusing or an outage: the fix is a credential, a tenant policy,
+ * or a retry. A 2xx whose body cannot be used is version skew or a misconfigured endpoint: the fix
+ * is code or configuration. One is the provider's problem and one is this host's.
+ */
+export function readTokenResponse(status: number, body: unknown, nowMs: number): Result<TokenSet> {
+  const secrets = secretsIn(body);
+
+  if (status < 200 || status >= 300) {
+    const record = typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {};
+    const error = typeof record['error'] === 'string' ? record['error'] : `HTTP ${status}`;
+    const description = typeof record['error_description'] === 'string' ? record['error_description'] : null;
+    // Only the two named fields are quoted — the body is never dumped. That is the first of two
+    // defences here, and it is the one that is easy to lose: "echo what the provider said so the
+    // operator can see it" is the natural implementation and it writes tokens to a log.
+    const message = description === null ? error : `${error}: ${description}`;
+
+    // `invalid_grant` is a different answer from every other non-2xx, and conflating them hides a
+    // dead grant behind retries. RFC 6749 section 5.2 defines it as the grant being expired, revoked,
+    // or issued to another client - none of which the next attempt improves. Everything else here is
+    // something a retry may well survive: a gateway hiccup, a throttle, a provider blip.
+    //
+    // This reader serves both grant exchanges, and the conclusion holds for each. On a refresh the
+    // refresh token has lapsed; on the initial code exchange the authorization code has expired or
+    // been replayed. Either way the material presented is spent and the next attempt with the same
+    // material fails identically - what differs is only which sign-in a person has to redo.
+    //
+    // The name is the RFC's, not a provider's. Providers append their own diagnostic codes to
+    // `error_description` and no one provider's is canonical; branching on the standard name is
+    // what keeps the rule true for a host pointed somewhere else.
+    if (error === 'invalid_grant') {
+      return refuse(
+        'token-grant-rejected',
+        redactSecrets(
+          bounded(`${message} - this grant is no longer valid; a new sign-in is required`),
+          secrets,
+        ),
+      );
+    }
+
+    return refuse('token-request-failed', redactSecrets(bounded(message), secrets));
+  }
+
+  if (typeof body !== 'object' || body === null) {
+    return refuse(
+      'token-response-invalid',
+      'the token endpoint returned 2xx with a body that is not a JSON object',
+    );
+  }
+  const record = body as Record<string, unknown>;
+
+  const accessToken = record['access_token'];
+  if (typeof accessToken !== 'string' || accessToken === '') {
+    return refuse('token-response-invalid', 'the token endpoint returned 2xx with no access_token');
+  }
+
+  // `expires_in` is only recommended by RFC 6749, and this host refuses without it anyway. An
+  // unattended host that does not know when its token dies cannot decide when to refresh — it would
+  // either refresh on every single call or discover expiry as a 401 in the middle of doing
+  // something. Neither is acceptable, and guessing a lifetime would be inventing a fact.
+  const expiresIn = record['expires_in'];
+  const seconds = typeof expiresIn === 'number' ? expiresIn : Number(expiresIn);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    return refuse(
+      'token-response-invalid',
+      'the token endpoint returned 2xx with no usable expires_in; an unattended host cannot decide when to refresh a token whose lifetime it does not know',
+    );
+  }
+
+  const refreshToken = record['refresh_token'];
+  const scope = record['scope'];
+  const tokenType = record['token_type'];
+
+  return ok({
+    accessToken,
+    refreshToken: typeof refreshToken === 'string' && refreshToken !== '' ? refreshToken : null,
+    expiresAt: nowMs + seconds * 1000,
+    tokenType: typeof tokenType === 'string' && tokenType !== '' ? tokenType : 'Bearer',
+    scope: typeof scope === 'string' ? scope : null,
+  });
+}
+
+/** Is this token still usable, allowing for the skew? */
+export function isFresh(tokens: TokenSet, nowMs: number): boolean {
+  return tokens.expiresAt - EXPIRY_SKEW_MS > nowMs;
+}
+
+/** The header a fresh token is presented as. */
+export function authorizationValue(tokens: TokenSet): string {
+  return `${tokens.tokenType} ${tokens.accessToken}`;
+}

package/src/index.ts

@@ -0,0 +1,140 @@
+/**
+ * The public surface of the package.
+ *
+ * Everything a consumer may depend on is named here or on the `./protocol` subpath. A module not
+ * re-exported from one of the two is internal, whatever its file path suggests.
+ */
+
+// The wire contract, re-exported so `@naswerks/periscope` alone is enough for a host-side consumer. A
+// controller that wants only the wire should import `@naswerks/periscope/protocol` instead — that path
+// cannot reach the privileged module.
+export * from './protocol.js';
+
+// The outbound link.
+export type { LinkHandlers, LinkOptions } from './control/link.js';
+export { ControllerLink } from './control/link.js';
+
+// Forwarding a session's live output onto the link, and the table that declares which lane each
+// message rides. Not on `./protocol` — the table is keyed off the SDK's own message union, so it
+// reaches the privileged module by construction.
+export type { ForwardSessionOptions, FrameSink } from './control/stream.js';
+export { forwardSession } from './control/stream.js';
+export type { RoutingRow, StreamLane } from './control/stream-routing.js';
+export { MESSAGE_ROUTING, discriminatorsOn, laneFor } from './control/stream-routing.js';
+
+export type { LinkCause, LinkState, LinkTransition } from './control/link-state.js';
+export { LINK_CAUSES, LinkStateMachine } from './control/link-state.js';
+
+export type { BackoffOptions } from './control/backoff.js';
+export { DEFAULT_BACKOFF, nextDelayMs } from './control/backoff.js';
+
+export type { QueueStats } from './control/queue.js';
+export { BoundedFrameQueue } from './control/queue.js';
+
+export type { Authorization, ControllerCredential } from './control/credential.js';
+export { UnconfiguredCredential } from './control/credential.js';
+
+// The pure core.
+export {
+  HOST_NOUNS,
+  SDK_NOUNS,
+  isAbsolutePath,
+  isContainedBy,
+  isDeclaredNoun,
+  isOk,
+  nounOf,
+  normalizePath,
+  ok,
+  refuse,
+  refusal,
+  requireAbsolute,
+  systemClock,
+  systemTicker,
+  valueOr,
+} from './core/index.js';
+export type { Clock, HostNoun, SdkNoun, Ticker } from './core/index.js';
+
+// The declared state model, its machine, its store and the coverage table.
+export * from './state/index.js';
+
+// The agent session lifecycle and the registry of live sessions.
+export * from './sessions/index.js';
+
+// The privileged module, exported deliberately: a host-side embedder needs it, and naming it here
+// keeps the boundary visible rather than hiding it behind a deep import.
+export type { BulkPostReceipt, BulkPostRequest, MachineFacts } from './host/index.js';
+export {
+  credentialPaths,
+  nodePathResolver,
+  periscopeCredentialDir,
+  postBulk,
+  readMachineFacts,
+  tokenCachePath,
+} from './host/index.js';
+
+// The composer. Everything above this line is a part; this is the one export that assembles them
+// into a session that is gated, observed, persisted and on the wire. An embedder writing
+// `registry.create({cwd})` by hand gets a correct-looking session with no gate and no observation,
+// which is why the assembly ships rather than living in a document.
+export type {
+  BulkResolver,
+  ComposeSessionOptions,
+  ComposedSession,
+  GateTimings,
+  HostEvent,
+  PeriscopeHostOptions,
+} from './host/index.js';
+export { PeriscopeHost, composeSession } from './host/index.js';
+
+// Identity — the pure flows, plus the two impure halves that live in `host/` by the same rule as
+// everything else that touches the machine.
+export * from './identity/index.js';
+export type { DeviceCodeInstruction, LoopbackListener, SignInDeps, TokenCacheWrite } from './host/index.js';
+export {
+  DEFAULT_SIGN_IN_TIMEOUT_MS,
+  FileTokenCache,
+  LOOPBACK_HOST,
+  openLoopbackListener,
+  probeModeEnforcement,
+  protocolFor,
+  refresherFor,
+  resolveEndpoints,
+  signIn,
+  signInWithDeviceCode,
+} from './host/index.js';
+
+export type { HookFailureListener, ObservationHookOptions } from './host/hooks.js';
+export { mergeHooks, observationHooks, wiredHookEvents } from './host/hooks.js';
+export { readWhere } from './host/git-facts.js';
+
+// The permission gate. Registered after observationHooks — see permissionHooks' own note on why the
+// order is load-bearing.
+export * from './gate/index.js';
+
+// Workspace provisioning — the directory a session runs in. The two providers ship; the interesting
+// policies (a shared directory per task, a branch naming rule, a cleanup schedule) are the
+// embedder's and are written against `WorkspaceProvider` rather than added here.
+export * from './workspace/index.js';
+export { nodeCommandEffects, nodeWorkspaceEffects } from './host/workspace-fs.js';
+
+// The generic tool mechanism: descriptors in, an in-process MCP server out. The host validates a
+// call against the schema it was handed, attaches session identity, forwards, and returns — it never
+// learns what any tool means. `createToolServer` sits in `host/` because it names the SDK.
+export * from './mcp/index.js';
+export { createToolServer } from './host/mcp-server.js';
+
+// Durability. The pure half — the store contract, the receipt read path, the transition log's
+// encoding and the retention policy — plus the two impure halves in `host/`: the local JSONL
+// effects, and the bridge that presents a store to the SDK.
+export * from './persistence/index.js';
+export {
+  asSessionStore,
+  nodeStoreEffects,
+  readMirrorDrop,
+  toSessionKey,
+  toTranscriptKey,
+} from './host/index.js';
+
+// Cost, usage and rate limits — read from the agent's own result, never computed from a price table.
+export * from './telemetry/index.js';
+export { readRateLimit, readTaskSpend, readTurnSpend } from './host/index.js';

package/src/mcp/descriptor.ts

@@ -0,0 +1,75 @@
+/**
+ * The descriptor contract — what an embedder supplies so this host can register an in-process tool.
+ *
+ * The descriptor is deliberately language-neutral. An embedder composing this host from another
+ * language, or a controller whose descriptors an embedder forwards,
+ * cannot express a TypeScript schema library's types, and asking it to would put a TypeScript
+ * dependency on the wire — which is precisely the leak this package is built to avoid. So a
+ * descriptor is JSON: a name, a description, and a JSON-Schema object. The host converts it
+ * (schema.ts) into what the SDK needs.
+ *
+ * The host never learns what a tool means. It validates the descriptor's shape, converts the
+ * schema it was handed, checks a call's arguments against that schema, attaches session identity,
+ * forwards, and returns the answer. There is no branch anywhere on a tool's name — pinned by
+ * pins/mcp-generic.test.ts, which registers the same descriptors under permuted names and requires
+ * the results to be identical.
+ *
+ * The subset is declared, not inferred. Only the constructs below are convertible. A descriptor
+ * carrying anything else is refused at registration rather than converted to something permissive —
+ * see schema.ts, where that rule is the most consequential line in this directory.
+ */
+import type { JsonValue } from '../control/frames.js';
+
+/** The JSON-Schema types this host converts. Anything else is refused by name. */
+export const SUPPORTED_SCHEMA_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'] as const;
+
+export type SupportedSchemaType = (typeof SUPPORTED_SCHEMA_TYPES)[number];
+
+/**
+ * One node of a tool's input schema.
+ *
+ * Everything is optional because this is what ARRIVES — an untrusted object off the wire, not a
+ * shape this package constructs. Validation happens in schema.ts and reports what was wrong.
+ */
+export interface JsonSchemaNode {
+  readonly type?: string;
+  readonly description?: string;
+  /** A closed set of literal values. Takes precedence over `type`. */
+  readonly enum?: readonly JsonValue[];
+  /** For `array`. */
+  readonly items?: JsonSchemaNode;
+  /** For `object`. */
+  readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
+  readonly required?: readonly string[];
+  /** JSON-Schema draft-4 style, and the spelling most emitters produce. */
+  readonly nullable?: boolean;
+}
+
+/** A tool's input schema. Always an object at the top level — `tool()` takes a shape, not a type. */
+export interface JsonSchemaObject extends JsonSchemaNode {
+  readonly type?: 'object';
+  readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
+  readonly required?: readonly string[];
+}
+
+/** One tool, as the embedder describes it. */
+export interface ToolDescriptor {
+  /** What the agent calls. Reaches the model as `mcp__{server}__{name}`. */
+  readonly name: string;
+  /** What the tool does, in the model's terms. The only thing that makes it usable. */
+  readonly description: string;
+  readonly inputSchema: JsonSchemaObject;
+}
+
+/**
+ * A tool name both the MCP protocol and the agent CLI accept.
+ *
+ * Conservative on purpose: the name is concatenated into `mcp__{server}__{name}`, so a name carrying
+ * the separator would produce a tool the agent addresses ambiguously — and the failure would look
+ * like the wrong tool being called rather than like a bad name.
+ */
+const NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+export function isUsableToolName(name: string): boolean {
+  return NAME_PATTERN.test(name) && !name.includes('__');
+}

package/src/mcp/index.ts

@@ -0,0 +1,23 @@
+/**
+ * In-process MCP servers and the tool descriptors that build them.
+ *
+ * `createToolServer` is not here. It calls the SDK, so it lives in `host/mcp-server.ts` under the
+ * rule that one directory names the SDK — see that file. Everything in this directory is the
+ * decisions: the descriptor contract, the schema conversion, and the plan a server is built from.
+ */
+export type { JsonSchemaNode, JsonSchemaObject, SupportedSchemaType, ToolDescriptor } from './descriptor.js';
+export { SUPPORTED_SCHEMA_TYPES, isUsableToolName } from './descriptor.js';
+
+export type { ZodRawShape } from './schema.js';
+export { toRawShape, toZod } from './schema.js';
+
+export type {
+  McpServerOptions,
+  ToolCall,
+  ToolCallIdentity,
+  ToolInvoker,
+  ToolPlan,
+  ToolResponse,
+  ToolResult,
+} from './server.js';
+export { planTools } from './server.js';