Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

12.6 KB
Raw Blame
/**
 * The pane owner's side of the hook inbox (architecture §2.3 steps 5-6).
 *
 * A pane child appends one JSON object per line to `hook-inbox.jsonl`:
 * `stop` before a response's `message_stop` can reach Claude Code, then the
 * `inject` / `annotate` payload its `responseEnd` hooks returned, then `end` once
 * those hooks resolved (or `end` with `aborted` when the stream died first).
 *
 * At a settle the owner records the file length and reads every line up to it,
 * incrementally by byte offset. It waits only for requests that have a `stop` and
 * no `end` by then: their `responseEnd` hooks are still running. While it waits it
 * keeps reading past the recorded length, because those requests' lines can only
 * appear there; lines past the length that belong to OTHER requests are carried to
 * the next settle. A request with no `stop` is still streaming (a background
 * subagent, a side request) and is never waited for. The wait polls every 100 ms,
 * is bounded, and ends at once when the signal aborts.
 */

import {
  closeSync,
  existsSync,
  fstatSync,
  openSync,
  readFileSync,
  readSync,
  rmSync,
  statSync,
} from "node:fs";
import { join } from "node:path";
import { validateAction } from "../actions.js";
import type { JsonValue } from "../public.js";

export const INBOX_POLL_MS = 100;

export type InboxLine =
  | { v: 1; kind: "stop"; req: string }
  | { v: 1; kind: "inject"; req: string; hookId: string; text: string; at?: string }
  | {
      v: 1;
      kind: "annotate";
      req: string;
      hookId: string;
      key: string;
      value: JsonValue;
      at?: string;
    }
  | { v: 1; kind: "end"; req: string; aborted?: boolean }
  | { v: 1; kind: "capped" };

/** What one drain produced, in arrival order. */
export interface InboxDrain {
  injections: Array<{ req: string; hookId: string; text: string }>;
  annotations: Array<{ req: string; hookId: string; key: string; value: JsonValue }>;
  /** a `capped` line was read in this drain (the child stopped appending payload) */
  capped: boolean;
  /** requests still without `end` when the bound expired (their later lines go to the next drain) */
  timedOut: string[];
  /**
   * payload lines that fail the action rules the child applies: a slash
   * command, an over-long text, a bad annotation key or value. Never delivered.
   */
  invalid: Array<{ req: string; hookId: string; kind: "inject" | "annotate"; reason: string }>;
}

/**
 * Re-apply, at the owner, the rules `validateAction` applies to these actions
 * in the child. The inbox is a same-user file; a line in it is not proof that a hook
 * produced it, so it is held to what a hook could have produced. Null when valid.
 */
function payloadProblem(line: InboxLine): string | null {
  if (line.kind === "inject") {
    const v = validateAction("responseEnd", { type: "injectUserTurn", text: line.text });
    return v.ok ? null : v.reason;
  }
  if (line.kind === "annotate") {
    const v = validateAction("responseEnd", {
      type: "annotateTurn",
      key: line.key,
      value: line.value,
    });
    return v.ok ? null : v.reason;
  }
  return null;
}

function parseLine(text: string): InboxLine | null {
  let v: unknown;
  try {
    v = JSON.parse(text);
  } catch {
    return null;
  }
  if (!v || typeof v !== "object") return null;
  const o = v as Record<string, unknown>;
  if (o.v !== 1) return null;
  switch (o.kind) {
    case "capped":
      return { v: 1, kind: "capped" };
    case "stop":
    case "end":
      return typeof o.req === "string" ? (o as InboxLine) : null;
    case "inject":
      return typeof o.req === "string" && typeof o.hookId === "string" && typeof o.text === "string"
        ? (o as InboxLine)
        : null;
    case "annotate":
      return typeof o.req === "string" && typeof o.hookId === "string" && typeof o.key === "string"
        ? (o as InboxLine)
        : null;
    default:
      return null;
  }
}

/**
 * Where an `InboxReader` takes its lines from. The pane child's file is one source;
 * the interactive launcher's in-process sink is the other (`MemoryInbox`), so the
 * owner's drain rule — wait only for a `stop` without its `end`, bounded, abortable,
 * carry other requests' lines — is one implementation for both (§2.3).
 */
export interface InboxLineSource {
  /** Every line appended since the last call, in order. */
  readNew(): InboxLine[];
  /** Lines were appended that `readNew()` has not returned yet. */
  hasNew(): boolean;
}

/**
 * The interactive launcher's inbox: the same lines the pane child appends to its
 * file, kept in memory, because proxy and session events share one process there.
 */
export class MemoryInbox implements InboxLineSource {
  private lines: InboxLine[] = [];

  append(line: InboxLine): void {
    this.lines.push(line);
  }

  readNew(): InboxLine[] {
    const out = this.lines;
    this.lines = [];
    return out;
  }

  hasNew(): boolean {
    return this.lines.length > 0;
  }
}

/** The pane child's `hook-inbox.jsonl`, read incrementally by byte offset. */
class FileInbox implements InboxLineSource {
  /** bytes read from the file so far */
  private offset = 0;
  /**
   * The bytes of a partial line at the end of the last read, undecoded: a read can
   * end inside a multi-byte character, which decodes whole only with the rest.
   */
  private partial: Buffer = Buffer.alloc(0);

  constructor(readonly path: string) {}

  hasNew(): boolean {
    try {
      return statSync(this.path).size > this.offset;
    } catch {
      return false;
    }
  }

  /** Read every complete line appended since the last read. */
  readNew(): InboxLine[] {
    if (!existsSync(this.path)) return [];
    let fd: number;
    try {
      fd = openSync(this.path, "r");
    } catch {
      return [];
    }
    try {
      const size = fstatSync(fd).size;
      if (size <= this.offset) return [];
      const buf = Buffer.alloc(size - this.offset);
      const n = readSync(fd, buf, 0, buf.length, this.offset);
      const bytes = Buffer.concat([this.partial, buf.subarray(0, n)]);
      // 0x0A never occurs inside a multi-byte UTF-8 sequence: cutting there is safe
      const nl = bytes.lastIndexOf(0x0a);
      const complete = nl === -1 ? "" : bytes.subarray(0, nl).toString("utf8");
      this.partial = Buffer.from(nl === -1 ? bytes : bytes.subarray(nl + 1));
      this.offset += n;
      const out: InboxLine[] = [];
      for (const raw of complete.split("\n")) {
        if (!raw.trim()) continue;
        const line = parseLine(raw);
        if (line) out.push(line);
      }
      return out;
    } finally {
      closeSync(fd);
    }
  }
}

export class InboxReader {
  /** lines read earlier that belong to a later drain */
  private carried: InboxLine[] = [];
  /** requests that wrote `stop`, and those that wrote `end` */
  private readonly stopped = new Set<string>();
  private readonly ended = new Set<string>();
  private readonly source: InboxLineSource;
  /** the inbox file, or null for an in-memory source */
  readonly path: string | null;

  constructor(source: string | InboxLineSource) {
    if (typeof source === "string") {
      this.path = source;
      this.source = new FileInbox(source);
    } else {
      this.path = null;
      this.source = source;
    }
  }

  /** Lines appended since the last read, or lines carried for the next drain. */
  hasUnread(): boolean {
    return this.carried.length > 0 || this.source.hasNew();
  }

  private readNew(): InboxLine[] {
    return this.source.readNew();
  }

  /**
   * Forget requests that are finished, so a long session's sets stay small. A request
   * that ended before `message_stop` wrote only its `end` and was never in `stopped`;
   * it is forgotten too. An `end` is always its request's last line.
   */
  private prune(): void {
    for (const req of this.ended) this.stopped.delete(req);
    this.ended.clear();
  }

  private note(line: InboxLine): void {
    if (line.kind === "stop") this.stopped.add(line.req);
    else if (line.kind === "end") this.ended.add(line.req);
  }

  /**
   * One settle's drain. `boundMs` caps the wait for requests whose `responseEnd`
   * hooks are still running; `signal` ends it at once (pane exit, terminal state,
   * an aborted hold).
   */
  async drain(boundMs: number, signal?: AbortSignal): Promise<InboxDrain> {
    const out: InboxDrain = {
      injections: [],
      annotations: [],
      capped: false,
      timedOut: [],
      invalid: [],
    };
    const take = (line: InboxLine) => {
      if (line.kind === "inject" || line.kind === "annotate") {
        const reason = payloadProblem(line);
        if (reason !== null) {
          out.invalid.push({ req: line.req, hookId: line.hookId, kind: line.kind, reason });
          return;
        }
      }
      if (line.kind === "inject")
        out.injections.push({ req: line.req, hookId: line.hookId, text: line.text });
      else if (line.kind === "annotate")
        out.annotations.push({
          req: line.req,
          hookId: line.hookId,
          key: line.key,
          value: line.value,
        });
      else if (line.kind === "capped") out.capped = true;
    };

    // Everything up to the recorded length, plus what an earlier drain carried.
    const upTo = [...this.carried, ...this.readNew()];
    this.carried = [];
    for (const line of upTo) {
      this.note(line);
      take(line);
    }
    // Requests whose hooks are still running: a `stop`, no `end`.
    const waiting = new Set<string>();
    for (const req of this.stopped) if (!this.ended.has(req)) waiting.add(req);
    if (waiting.size === 0) {
      this.prune();
      return out;
    }

    const deadline = Date.now() + Math.max(0, boundMs);
    while (waiting.size > 0 && !signal?.aborted && Date.now() < deadline) {
      await sleepOrAbort(Math.min(INBOX_POLL_MS, Math.max(0, deadline - Date.now())), signal);
      for (const line of this.readNew()) {
        // The cap is the inbox's, not a request's: this settle reports it.
        if (line.kind === "capped") {
          take(line);
          continue;
        }
        const req = line.req;
        if (waiting.has(req)) {
          this.note(line);
          take(line);
          if (line.kind === "end") waiting.delete(req);
        } else {
          // Another request's line: the next settle takes it.
          this.carried.push(line);
        }
      }
    }
    // Still waiting at the bound: those requests' later lines go to the next drain.
    // They are not waited for again (their `stop` is remembered as ended).
    for (const req of waiting) {
      out.timedOut.push(req);
      this.ended.add(req);
    }
    this.prune();
    return out;
  }

  /**
   * The session is over and its writer gone: every payload line not taken yet, carried
   * or never read, with no wait. The caller journals them.
   */
  takeRemaining(): Array<Extract<InboxLine, { kind: "inject" | "annotate" }>> {
    const lines = [...this.carried, ...this.readNew()];
    this.carried = [];
    return lines.filter(
      (l): l is Extract<InboxLine, { kind: "inject" | "annotate" }> =>
        l.kind === "inject" || l.kind === "annotate"
    );
  }
}

function sleepOrAbort(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal?.aborted) return resolve();
    const done = () => {
      clearTimeout(t);
      signal?.removeEventListener("abort", done);
      resolve();
    };
    const t = setTimeout(done, ms);
    signal?.addEventListener("abort", done, { once: true });
  });
}

/** Every parseable line of an inbox file; [] when it is absent or unreadable. */
export function readInboxLines(path: string): InboxLine[] {
  let text: string;
  try {
    text = readFileSync(path, "utf8");
  } catch {
    return [];
  }
  const out: InboxLine[] = [];
  for (const raw of text.split("\n")) {
    if (!raw.trim()) continue;
    const line = parseLine(raw);
    if (line) out.push(line);
  }
  return out;
}

/** The inbox holds an `inject` or `annotate` line (the reap check of an owner without hooks). */
export function inboxHasPayload(path: string): boolean {
  return readInboxLines(path).some((l) => l.kind === "inject" || l.kind === "annotate");
}

/** The inbox file name in a channel session's directory (§2.3 step 1). */
export const HOOK_INBOX_FILE = "hook-inbox.jsonl";

/**
 * Create `<dir>/<name>` for a pane child, 0600 with an exclusive create (a stale file
 * of an earlier run on the same dir is removed first, so the create never follows a
 * planted path). Null when it cannot be created: the child then has no inbox, which
 * costs its injections, never the session.
 */
export function createHookInbox(dir: string, name: string = HOOK_INBOX_FILE): string | null {
  const path = join(dir, name);
  try {
    rmSync(path, { force: true });
    closeSync(openSync(path, "wx", 0o600));
    return path;
  } catch {
    return null;
  }
}