@naswerks/periscope 1.0.0 → 1.0.1

package/src/host/bulk-post.ts

@@ -0,0 +1,166 @@
+/**
+ * The host half of the bulk lane: bytes leave over an outbound HTTP POST, never over the link.
+ *
+ * The link carries a locator and gets back a receipt; the content travels here. That inversion is
+ * what keeps a megabyte transcript off a socket that also carries the transitions telling you what
+ * a session is doing — a single large frame would otherwise stall every session sharing the link.
+ *
+ * The read is streamed. Buffering a whole transcript to send it would block the event loop for
+ * every other session this host is serving, which is the same failure in a different costume.
+ */
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import { requireAbsolute } from '../core/paths.js';
+
+export interface BulkPostRequest {
+  readonly deliveryId: string;
+  readonly postUrl: string;
+  /**
+   * The only origin this delivery may reach. Required, with no default, and that is the mechanism
+   * rather than a style.
+   *
+   * `postUrl` is chosen by the peer and arrives verbatim on the wire; this is the value that says
+   * which peer the host actually works for. An optional field defaulting to "no binding" would let
+   * every present and future caller inherit a fail-open nobody picked. Required, the compiler
+   * forces each caller to name the origin it trusts.
+   *
+   * Compute it with {@link bulkOriginFor}, which is the only thing that knows how to turn the
+   * host's configured `ws(s)://` controller URL into the `http(s)://` origin a POST lands on.
+   */
+  readonly allowedOrigin: string;
+  /** Absolute. A relative path means "relative to a cwd the controller cannot see". */
+  readonly filePath: string;
+  readonly fromOffset: number;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+/**
+ * The host's ONE controller origin, derived from the link URL it already dials.
+ *
+ * Derived, never separately configured. The host dials `controllerUrl` and trusts whatever
+ * answers it; the bulk POST goes to the same deployment over plain HTTP. Reading a second setting
+ * would create a way for the two to disagree, and a host whose "trusted origin" is configured apart
+ * from the one it actually talks to is a host that can be pointed at two peers at once.
+ */
+export function bulkOriginFor(controllerUrl: string): Result<string> {
+  let parsed: URL;
+  try {
+    parsed = new URL(controllerUrl);
+  } catch {
+    return refuse('bulk-target-invalid', `the configured controller URL is not a URL: ${controllerUrl}`);
+  }
+
+  // The link speaks WebSocket and the bulk lane speaks HTTP against the SAME deployment, so the
+  // scheme is mapped rather than compared: `wss://host:8443/periscope/link` and
+  // `https://host:8443/periscope/bulk/<id>` are one controller, and `URL.origin` alone would call
+  // them different peers.
+  const scheme =
+    parsed.protocol === 'ws:' ? 'http:' : parsed.protocol === 'wss:' ? 'https:' : parsed.protocol;
+  if (scheme !== 'http:' && scheme !== 'https:') {
+    return refuse('bulk-target-invalid', `a controller URL cannot carry scheme ${parsed.protocol}`);
+  }
+
+  return ok(`${scheme}//${parsed.host}`);
+}
+
+export interface BulkPostReceipt {
+  readonly deliveryId: string;
+  readonly byteCount: number;
+  /**
+   * The file's stat at the moment the delivery was read (size total, mtime as floored epoch ms).
+   * Carried so a transcript puller can detect the CLI rewriting the file under it — a byte-offset
+   * resume across a rewrite is invalid, and only the deliverer's own stat can say.
+   */
+  readonly sizeBytes: number;
+  readonly mtimeMs: number;
+}
+
+export async function postBulk(request: BulkPostRequest): Promise<Result<BulkPostReceipt>> {
+  const absolute = requireAbsolute(request.filePath);
+  if (!absolute.ok) return { ok: false, refusal: absolute.refusal };
+
+  let target: URL;
+  try {
+    target = new URL(request.postUrl);
+  } catch {
+    return refuse('bulk-target-invalid', `not a URL: ${request.postUrl}`);
+  }
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+    return refuse('bulk-target-invalid', `unsupported scheme: ${target.protocol}`);
+  }
+
+  // The destination is the peer's choice; whether it is reached is not.
+  //
+  // The caller attaches this host's durable, non-expiring paired credential to the request (see
+  // `host.ts`'s `#deliver`). With a credential riding along, a peer-named `postUrl` is an
+  // exfiltration surface: any code path that can compose a `BulkRequest` could name
+  // `http://attacker.example/x` and receive the operator's transcript and the device credential
+  // that outlives the discovery of the theft.
+  //
+  // Checked after the scheme, on purpose. A garbled URL should still say it is garbled; this reason
+  // is reserved for a target that is well-formed and simply is not this host's controller.
+  if (target.origin !== request.allowedOrigin) {
+    return refuse(
+      'bulk-target-not-controller',
+      `refusing to deliver to ${target.origin}: this host posts bulk content only to its own ` +
+        `controller at ${request.allowedOrigin}. The destination rides the wire, so a peer that ` +
+        `names another origin is asking for the transcript AND this host's durable credential`,
+    );
+  }
+
+  try {
+    const stats = await stat(absolute.value);
+    const start = Math.min(Math.max(0, request.fromOffset), stats.size);
+    const byteCount = stats.size - start;
+
+    // Bounded to the bytes the header promised. `content-length` is declared from the stat above,
+    // but the stream was opened after it: reading a live transcript (the headline use case) lets
+    // the CLI append between the two, so an unbounded stream drains past the declared length and
+    // the delivery dies as `bulk-delivery-failed`, a name that blames the delivery for a file that
+    // simply moved. The end offset is inclusive, hence the -1.
+    //
+    // The zero-byte arm is not `end: start - 1`: `end` must be a non-negative integer, so an
+    // empty delivery at offset 0 would throw rather than send nothing. An empty stream is the
+    // honest encoding of "the header promised no bytes".
+    const stream =
+      byteCount > 0
+        ? createReadStream(absolute.value, { start, end: start + byteCount - 1 })
+        : Readable.from([]);
+    const response = await fetch(target, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/octet-stream',
+        'content-length': String(byteCount),
+        'x-delivery-id': request.deliveryId,
+        ...request.headers,
+      },
+      body: Readable.toWeb(stream) as ReadableStream<Uint8Array>,
+      // Required by undici whenever the body is a stream: the request body is still being sent
+      // while the response is read. Without it the fetch rejects before a byte moves.
+      duplex: 'half',
+    });
+
+    if (!response.ok) {
+      return refuse(
+        'bulk-delivery-failed',
+        `controller answered ${response.status} ${response.statusText} for delivery ${request.deliveryId}`,
+      );
+    }
+
+    return ok({
+      deliveryId: request.deliveryId,
+      byteCount,
+      sizeBytes: stats.size,
+      mtimeMs: Math.floor(stats.mtimeMs),
+    });
+  } catch (error) {
+    return refuse(
+      'bulk-delivery-failed',
+      `delivery ${request.deliveryId} failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/host/claude-transcripts.ts

@@ -0,0 +1,404 @@
+/**
+ * The discovery door: read-only enumeration and tail-probing of the agent CLI's own transcript
+ * directory, `~/.claude/projects`.
+ *
+ * The posture, stated once because it is the whole design. This host names `~/.claude` in one
+ * other place, `host/paths.ts`, to protect it from the sessions it runs. That protection is about
+ * the agent's hands; this module is the host's own eyes, a deliberate read-only capability over a
+ * directory every Claude session on the machine writes into (a VS Code session and a session this
+ * host started land side by side). The two postures do not touch: nothing here weakens the gate,
+ * and nothing here can write.
+ *
+ * Read-only is a property, not a promise. The module's filesystem surface is exactly
+ * `createReadStream`, `readdir` and `stat`; no write-capable API is imported, and
+ * `src/pins/transcript-readonly.test.ts` holds the import surface to that allowlist.
+ *
+ * The jail: three layers, all three always, for every caller-supplied name:
+ *   1. the strict name allowlist (`NAME_ALLOWLIST`);
+ *   2. an explicit `'.'` / `'..'` reject — dot-names PASS the regex, so this layer is load-bearing;
+ *   3. resolve-then-containment — the real resolver first, then `isContainedBy` against the root,
+ *      so a name the first two layers somehow admitted still cannot shape a path outside it.
+ * A violation refuses `transcript-path-escape`, naming the layer. An ABSENT transcript is a value,
+ * never a refusal: a missing projects directory is a fresh machine and lists as empty.
+ *
+ * The rewrite hazard: the CLI rewrites a transcript on compaction,
+ * so a byte-offset resume across a rewrite is invalid. Every answer that carries an offset also
+ * carries the file's current (size, mtime) pair; a caller that sees either move under it re-reads
+ * whole rather than resuming. A file SHORTER than the asked offset is treated as rewritten and
+ * scanned from 0.
+ *
+ * Project slugs are OPAQUE NAMES, never decoded: the CLI flattens every non-alphanumeric character
+ * of a directory path to `-` (on win32 `C:\src\x\.y` becomes `C--src-x--y`), so the
+ * mapping is not invertible and nothing here tries.
+ */
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import { isContainedBy, normalizePath } from '../core/paths.js';
+import { TRANSCRIPT_PAGE_SIZE, TRANSCRIPT_WHAT_PREFIX } from '../control/frames.js';
+import { nodePathResolver } from './paths.js';
+
+/**
+ * The strict name allowlist — drive/path characters only. `'.'` and `'..'` PASS this regex, which
+ * is exactly why the dot-name reject below is its own layer rather than a tightening of this one.
+ */
+export const NAME_ALLOWLIST = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * The agent's home when nothing configures one: the folder the agent CLI keeps its state in, under
+ * the user's home directory. Null when there is no home to derive it from — a refusable state,
+ * never a fallback: inventing one would turn "this machine has no home directory" into a silent
+ * empty listing that reads as a fresh machine.
+ */
+export function defaultAgentHome(env: NodeJS.ProcessEnv = process.env): string | null {
+  const home = env['USERPROFILE'] ?? env['HOME'];
+  if (typeof home === 'string' && home.trim() !== '') {
+    return normalizePath(`${home.replace(/[\\/]+$/, '')}/.claude`);
+  }
+  return null;
+}
+
+/** Where the agent CLI keeps transcripts under its home: derived, never configured on its own. */
+export function transcriptsRootUnder(agentHome: string): string {
+  return normalizePath(`${agentHome.replace(/[\\/]+$/, '')}/projects`);
+}
+
+/** The transcripts root under the default agent home, or null when there is no home. */
+export function claudeProjectsRoot(env: NodeJS.ProcessEnv = process.env): string | null {
+  const home = defaultAgentHome(env);
+  return home === null ? null : transcriptsRootUnder(home);
+}
+
+/** One transcript on disk. `mtimeMs` is a floored integer so equality against a stamp holds. */
+export interface DiscoveredTranscript {
+  readonly projectSlug: string;
+  readonly sessionId: string;
+  readonly sizeBytes: number;
+  readonly mtimeMs: number;
+  /**
+   * The working directory the CLI recorded on its entries, read off the file's own head, never
+   * decoded from the slug (the flattening is not invertible). The resume handle's other half: the
+   * CLI keeps transcripts per cwd, so a resume that does not run there finds nothing. Null when the
+   * head carries none.
+   */
+  readonly cwd: string | null;
+}
+
+/** How much of a transcript's head is read for its `cwd` — the first entries, never the file. */
+const CWD_HEAD_BYTES = 64 * 1024;
+
+/**
+ * The first `cwd` string on the file's first entries, or null. A summary line carries none; the first
+ * user or assistant entry does. Every failure is null — the listing describes files, it does not refuse
+ * over one of them.
+ */
+async function readTranscriptCwd(path: string): Promise<string | null> {
+  let head = '';
+  try {
+    for await (const chunk of createReadStream(path, {
+      start: 0,
+      end: CWD_HEAD_BYTES - 1,
+      encoding: 'utf8',
+    })) {
+      head += chunk as string;
+    }
+  } catch {
+    return null;
+  }
+  for (const line of head.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const entry: unknown = JSON.parse(trimmed);
+      if (
+        typeof entry === 'object' &&
+        entry !== null &&
+        typeof (entry as { cwd?: unknown }).cwd === 'string'
+      ) {
+        const cwd = (entry as { cwd: string }).cwd;
+        if (cwd.length > 0) return cwd;
+      }
+    } catch {
+      // a partial last line inside the window, or a non-JSON line — keep looking
+    }
+  }
+  return null;
+}
+
+export interface TranscriptPage {
+  readonly entries: readonly DiscoveredTranscript[];
+  readonly totalCount: number;
+  /** Ask again from here for the next page; null when this page ends the listing. */
+  readonly nextIndex: number | null;
+}
+
+/** What a tail probe answers. `absent` true means the transcript does not exist — a real negative. */
+export interface TranscriptTailAnswer {
+  readonly absent: boolean;
+  readonly found: boolean;
+  readonly newOffset: number;
+  readonly sizeBytes: number | null;
+  readonly mtimeMs: number | null;
+}
+
+/**
+ * THE JAIL. Resolve `{root}/{projectSlug}/{sessionId}.jsonl` with all three layers applied to both
+ * caller-supplied names. The one path-shaping function in this module — list, tail and the bulk
+ * resolver all come through here, so there is no second door to keep honest.
+ */
+export function resolveTranscriptPath(root: string, projectSlug: string, sessionId: string): Result<string> {
+  for (const [value, what] of [
+    [projectSlug, 'projectSlug'],
+    [sessionId, 'sessionId'],
+  ] as const) {
+    if (value === '.' || value === '..') {
+      return refuse('transcript-path-escape', `${what} is a dot-name — refused by the dot-name layer`);
+    }
+    if (!NAME_ALLOWLIST.test(value)) {
+      return refuse(
+        'transcript-path-escape',
+        `${what} fails the name allowlist — refused by the allowlist layer`,
+      );
+    }
+  }
+
+  const resolvedRoot = normalizePath(nodePathResolver(root));
+  const candidate = normalizePath(nodePathResolver(`${resolvedRoot}/${projectSlug}/${sessionId}.jsonl`));
+  if (!isContainedBy(candidate, resolvedRoot)) {
+    return refuse(
+      'transcript-path-escape',
+      `the resolved path leaves the projects root — refused by the containment layer`,
+    );
+  }
+  return ok(candidate);
+}
+
+/**
+ * Enumerate every session transcript: direct-child `*.jsonl` per slug directory (nested files are
+ * the CLI's subagent transcripts and are not part of this listing). Newest first by mtime, paged.
+ * A missing root is a fresh machine and answers an empty listing, never an error; a file deleted
+ * between readdir and stat is skipped for the same reason.
+ */
+export async function listTranscripts(
+  root: string,
+  page: { fromIndex?: number; pageSize?: number } = {},
+): Promise<TranscriptPage> {
+  const fromIndex = Math.max(0, page.fromIndex ?? 0);
+  const pageSize = Math.max(1, page.pageSize ?? TRANSCRIPT_PAGE_SIZE);
+  const resolvedRoot = normalizePath(nodePathResolver(root));
+
+  let slugDirs;
+  try {
+    slugDirs = (await readdir(resolvedRoot, { withFileTypes: true })).filter(
+      (entry) =>
+        entry.isDirectory() && NAME_ALLOWLIST.test(entry.name) && entry.name !== '.' && entry.name !== '..',
+    );
+  } catch {
+    return { entries: [], totalCount: 0, nextIndex: null };
+  }
+
+  const all: Omit<DiscoveredTranscript, 'cwd'>[] = [];
+  for (const slugDir of slugDirs) {
+    let files;
+    try {
+      files = await readdir(`${resolvedRoot}/${slugDir.name}`, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.isFile() || !file.name.endsWith('.jsonl')) continue;
+      const sessionId = file.name.slice(0, -'.jsonl'.length);
+      if (sessionId === '.' || sessionId === '..' || !NAME_ALLOWLIST.test(sessionId)) continue;
+      try {
+        const stats = await stat(`${resolvedRoot}/${slugDir.name}/${file.name}`);
+        all.push({
+          projectSlug: slugDir.name,
+          sessionId,
+          sizeBytes: stats.size,
+          mtimeMs: Math.floor(stats.mtimeMs),
+        });
+      } catch {
+        // Deleted between readdir and stat — the listing describes what exists, not what did.
+      }
+    }
+  }
+
+  all.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  // The cwd is read for the PAGE only — one head per listed row, never one per file on the machine.
+  const entries: DiscoveredTranscript[] = await Promise.all(
+    all.slice(fromIndex, fromIndex + pageSize).map(async (entry) => ({
+      ...entry,
+      cwd: await readTranscriptCwd(`${resolvedRoot}/${entry.projectSlug}/${entry.sessionId}.jsonl`),
+    })),
+  );
+  const nextIndex = fromIndex + entries.length;
+  return {
+    entries,
+    totalCount: all.length,
+    nextIndex: nextIndex < all.length ? nextIndex : null,
+  };
+}
+
+/**
+ * Probe one transcript from `fromOffset` for a user entry matching `needle` (null = any user-text
+ * entry). Jail violations refuse; an absent file answers `{absent: true}`; a read that FAILS is a
+ * refusal (`transcript-read-failed`), never a false negative — to the asker "no new entry" and
+ * "could not look" must not be the same answer.
+ */
+export async function tailTranscript(
+  root: string,
+  projectSlug: string,
+  sessionId: string,
+  probe: { fromOffset?: number; needle?: string | null } = {},
+): Promise<Result<TranscriptTailAnswer>> {
+  const resolved = resolveTranscriptPath(root, projectSlug, sessionId);
+  if (!resolved.ok) return resolved;
+
+  let stats;
+  try {
+    stats = await stat(resolved.value);
+  } catch {
+    return ok({ absent: true, found: false, newOffset: 0, sizeBytes: null, mtimeMs: null });
+  }
+  if (!stats.isFile()) {
+    return ok({ absent: true, found: false, newOffset: 0, sizeBytes: null, mtimeMs: null });
+  }
+
+  const sizeBytes = stats.size;
+  const mtimeMs = Math.floor(stats.mtimeMs);
+  const asked = Math.max(0, probe.fromOffset ?? 0);
+  // A file shorter than the baseline was rewritten (compaction, or a fork replacing it): scan from
+  // the start and let the needle reject stale entries — resuming into a rewritten file would read
+  // from the middle of a line that no longer exists.
+  const start = sizeBytes < asked ? 0 : asked;
+  const needle = probe.needle ?? null;
+
+  if (start >= sizeBytes) {
+    return ok({ absent: false, found: false, newOffset: sizeBytes, sizeBytes, mtimeMs });
+  }
+
+  try {
+    const found = await scanForUserEntry(resolved.value, start, sizeBytes, needle);
+    return ok({ absent: false, found, newOffset: sizeBytes, sizeBytes, mtimeMs });
+  } catch (error) {
+    return refuse(
+      'transcript-read-failed',
+      `reading ${projectSlug}/${sessionId} failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * The bulk-lane resolver for transcript reads: `claude-transcript:{slug}/{sessionId}` to a jailed
+ * absolute path. A locator outside the namespace is refused as an invalid bulk target so an
+ * embedder composing several resolvers can tell "not mine" from "mine and malformed".
+ */
+export function claudeTranscriptResolver(root: string): (what: string, sessionKey: string) => Result<string> {
+  return (what: string): Result<string> => {
+    if (!what.startsWith(TRANSCRIPT_WHAT_PREFIX)) {
+      return refuse(
+        'bulk-target-invalid',
+        `this host resolves "${TRANSCRIPT_WHAT_PREFIX}{projectSlug}/{sessionId}" locators; got "${what}"`,
+      );
+    }
+    const rest = what.slice(TRANSCRIPT_WHAT_PREFIX.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0 || slash === rest.length - 1) {
+      return refuse(
+        'bulk-target-invalid',
+        `a transcript locator is "${TRANSCRIPT_WHAT_PREFIX}{projectSlug}/{sessionId}"; got "${what}"`,
+      );
+    }
+    return resolveTranscriptPath(root, rest.slice(0, slash), rest.slice(slash + 1));
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The user-entry predicate: the rule that decides whether a new user entry landed.
+// ---------------------------------------------------------------------------
+
+/** Collapse every whitespace run to one space and trim, so needle matching survives reflowing. */
+const normalizeForMatch = (text: string): string => text.replace(/\s+/g, ' ').trim();
+
+/** A user entry's text: a flat string content, or its concatenated `text` blocks. */
+function userTextOf(message: unknown): string {
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  let out = '';
+  for (const block of content) {
+    if (
+      block !== null &&
+      typeof block === 'object' &&
+      (block as { type?: unknown }).type === 'text' &&
+      typeof (block as { text?: unknown }).text === 'string'
+    ) {
+      out += (block as { text: string }).text;
+    }
+  }
+  return out;
+}
+
+/**
+ * One line: does it count as a matching user entry? Unparseable or foreign lines are skipped,
+ * never thrown — a truncated LAST line is the normal state of a file being appended to. A
+ * tool-result-only user line has no text block and so never matches.
+ */
+export function isMatchingUserEntry(line: string, needle: string | null): boolean {
+  let root: unknown;
+  try {
+    root = JSON.parse(line);
+  } catch {
+    return false;
+  }
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) return false;
+  if ((root as { type?: unknown }).type !== 'user') return false;
+  const message = (root as { message?: unknown }).message;
+  if (message === null || typeof message !== 'object' || Array.isArray(message)) return false;
+  const role = (message as { role?: unknown }).role;
+  if (role !== undefined && role !== 'user') return false;
+
+  const text = userTextOf(message);
+  if (text.trim().length === 0) return false;
+  if (needle === null || needle === '') return true;
+  return normalizeForMatch(text).includes(needle);
+}
+
+/**
+ * Read `[start, end)` in chunks with a line carry, so a large transcript never lands in one buffer
+ * and a partial final line is simply the last carry. The final carry is tested too — an
+ * unterminated tail is still a line.
+ */
+function scanForUserEntry(file: string, start: number, end: number, needle: string | null): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    const stream = createReadStream(file, { start, end: end - 1, encoding: 'utf8' });
+    let carry = '';
+    let found = false;
+
+    stream.on('data', (chunk) => {
+      if (found) return;
+      const text = carry + String(chunk);
+      const lines = text.split('\n');
+      carry = lines.pop() ?? '';
+      for (const raw of lines) {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.length === 0) continue;
+        if (isMatchingUserEntry(line, needle)) {
+          found = true;
+          stream.destroy();
+          return;
+        }
+      }
+    });
+    stream.on('error', reject);
+    stream.on('close', () => {
+      if (!found && carry.length > 0) {
+        const line = carry.endsWith('\r') ? carry.slice(0, -1) : carry;
+        if (line.length > 0 && isMatchingUserEntry(line, needle)) found = true;
+      }
+      resolve(found);
+    });
+  });
+}