hyperbrane 0.1.1 → 0.2.0

package/dist/agent/workerBundle.js

@@ -1,31 +1,4 @@
-import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
 import { join } from "node:path";
-let bundled;
-/**
- * The worker, once per process. Under Bun with the sources at hand (a checkout) it is bundled from
- * them; otherwise (Node, or the built package, which ships no sources) it comes from
- * agent/workerBundle.generated.ts (scripts/bundle-worker.ts).
- */
-export function workerBundle() {
-    bundled ??= load().catch((error) => {
-        bundled = undefined;
-        throw error;
-    });
-    return bundled;
-}
-async function load() {
-    const fromSources = "Bun" in globalThis && existsSync(join(import.meta.dirname, "session", "main.ts"));
-    const source = fromSources ? await buildWorkerSource() : (await import("./workerBundle.generated.js")).WORKER_SOURCE;
-    return { source, build: createHash("sha256").update(source).digest("hex").slice(0, 16) };
-}
-/** Bundles the worker with Bun.build. */
-export async function buildWorkerSource() {
-    const result = await Bun.build({
-        entrypoints: [join(import.meta.dirname, "session", "main.ts")],
-        target: "bun",
-    });
-    if (!result.success)
-        throw new Error(`bundling the session worker failed:\n${result.logs.join("\n")}`);
-    return result.outputs[0].text();
-}
+import { scriptBundle } from "../lib/scriptBundle.js";
+export const workerEntry = () => join(import.meta.dirname, "session", "main.ts");
+export const workerBundle = scriptBundle(workerEntry, async () => (await import("./workerBundle.generated.js")).WORKER_SOURCE);

package/dist/agent/workerReplacement.d.ts

@@ -0,0 +1,3 @@
+import { type WorkerClient } from "./session/client.ts";
+import type { ConnectWorker } from "./session/workerConnection.ts";
+export declare function replacingWorkerClient(connect: ConnectWorker, replace: (replaceBuild: boolean) => Promise<void>): WorkerClient;

package/dist/agent/workerReplacement.js

@@ -0,0 +1,49 @@
+import { SandboxConnectionRefusedError } from "../sandbox/api.js";
+import { createWorkerClient } from "./session/client.js";
+import { WorkerMethodNotFoundError, WorkerProtocolMismatchError } from "./session/worker/protocol.js";
+export function replacingWorkerClient(connect, replace) {
+    const reconnecting = async (onNotification) => {
+        try {
+            return await connect(onNotification);
+        }
+        catch (error) {
+            if (!(error instanceof SandboxConnectionRefusedError))
+                throw error;
+            await replace(false);
+            return connect(onNotification);
+        }
+    };
+    const client = createWorkerClient(reconnecting);
+    const outdated = async (error) => {
+        if (!(error instanceof WorkerProtocolMismatchError || error instanceof WorkerMethodNotFoundError))
+            throw error;
+        await replace(error instanceof WorkerMethodNotFoundError);
+    };
+    return {
+        async call(method, params) {
+            try {
+                return await client.call(method, params);
+            }
+            catch (error) {
+                await outdated(error);
+                return client.call(method, params);
+            }
+        },
+        async *stream(session, afterId) {
+            let streamed = false;
+            try {
+                for await (const message of client.stream(session, afterId)) {
+                    streamed = true;
+                    yield message;
+                }
+                return;
+            }
+            catch (error) {
+                if (streamed)
+                    throw error;
+                await outdated(error);
+            }
+            yield* client.stream(session, afterId);
+        },
+    };
+}

package/dist/cli/agent.js

@@ -1,9 +1,8 @@
-import { AGENT_BACKENDS } from "../agent/api.js";
+import { AGENT_BACKENDS, AGENT_PERMISSION_MODES, } from "../agent/api.js";
 import { CPULimit, MemoryLimit } from "../dimension/api.js";
 import { QUIET_FLAG, UsageError, forEach, printList, requireFlag } from "./command.js";
 import { createTerminalPrinter, preview } from "./streamPrinter.js";
 import { formatTable } from "./table.js";
-/** How often `session attach` looks for permission requests and questions to point out. */
 const PENDING_POLL_MS = 1_000;
 function backendArg(name) {
     const backend = AGENT_BACKENDS.find((known) => known === name);
@@ -11,7 +10,6 @@ function backendArg(name) {
         throw new UsageError(`unknown backend ${name}: use one of ${AGENT_BACKENDS.join(", ")}`);
     return backend;
 }
-/** "AGENT/SESSION" -> the session's ref. */
 function sessionRef(arg) {
     const slash = arg.indexOf("/");
     if (slash <= 0 || slash === arg.length - 1)
@@ -21,7 +19,6 @@ function sessionRef(arg) {
 function refName({ agentName, sessionName }) {
     return `${agentName}/${sessionName}`;
 }
-/** --env KEY=VALUE flags -> an environment. */
 function envFlag(flags) {
     const entries = flags.env;
     if (!Array.isArray(entries) || entries.length === 0)
@@ -35,10 +32,6 @@ function envFlag(flags) {
     }
     return env;
 }
-/**
- * Points out, once each, the permission requests and questions the session is waiting on, with the
- * command that answers them. Returns the function that stops looking.
- */
 function watchPending(agents, ref) {
     const seen = new Set();
     const name = refName(ref);
@@ -97,10 +90,23 @@ export const agentCommands = {
             summary: `Install or update backends in an agent's dimension (${AGENT_BACKENDS.join(", ")})`,
             args: ["AGENT", "BACKEND..."],
             async run([agent, ...backends], _flags, { agents }) {
-                backends.forEach(backendArg); // all known, before installing any
+                backends.forEach(backendArg);
                 await forEach(backends, (backend) => agents.install(agent, backendArg(backend)));
             },
         },
+        backends: {
+            summary: "Show the backends installed in an agent's dimension",
+            args: ["AGENT"],
+            flags: QUIET_FLAG,
+            async run([agent], flags, { agents }) {
+                const rows = (await agents.listBackends(agent)).map(({ backend, version, ready }) => [
+                    backend,
+                    version ?? "-",
+                    ready ? "ready" : version ? "incomplete or outdated: install it" : "not installed",
+                ]);
+                printList(flags, ["BACKEND", "VERSION", "STATUS"], rows);
+            },
+        },
         rm: {
             summary: "Stop one or more agents' workers (their sessions stay in the dimension)",
             args: ["NAME..."],
@@ -137,7 +143,15 @@ const modelCommands = {
         },
     },
 };
-/** A sign-in status as lines for the terminal: what to do next when it's waiting for the user. */
+function describeStatus(status) {
+    if (status.state === "tool")
+        return `tool: ${status.tools.join(", ")}`;
+    if (status.state !== "exited")
+        return status.state;
+    if (status.signal)
+        return `exited (${status.signal})`;
+    return status.code === null ? "exited" : `exited (code ${status.code})`;
+}
 function describeAuth(name, status) {
     if (status.state === "signedIn")
         return "signed in";
@@ -201,6 +215,22 @@ const taskCommands = {
 const permissionCommands = {
     summary: "List and answer a session's permission requests: tool calls waiting to run",
     commands: {
+        mode: {
+            summary: `Show the session's permission mode, or switch it: "ask" before each tool call, or "auto" to allow them all (the waiting ones too)`,
+            args: ["AGENT/SESSION", "[MODE]"],
+            async run([name, mode], _flags, { agents }) {
+                const ref = sessionRef(name);
+                if (mode === undefined) {
+                    const session = (await agents.listSessions()).find((candidate) => candidate.agentName === ref.agentName && candidate.name === ref.sessionName);
+                    return console.log(session?.permissionMode ?? "ask");
+                }
+                const known = AGENT_PERMISSION_MODES.find((candidate) => candidate === mode);
+                if (!known)
+                    throw new UsageError(`unknown permission mode ${mode}: use one of ${AGENT_PERMISSION_MODES.join(", ")}`);
+                await agents.setPermissionMode(ref, known);
+                console.log(known);
+            },
+        },
         ls: {
             summary: "List a session's tool calls waiting for permission",
             args: ["AGENT/SESSION"],
@@ -280,7 +310,7 @@ export const sessionCommands = {
                     .map((session) => [
                     `${session.agentName}/${session.name}`,
                     session.backend,
-                    session.status,
+                    describeStatus(session.status),
                     session.model ?? "(default)",
                     session.nativeId ?? "",
                 ])
@@ -354,7 +384,6 @@ export const sessionCommands = {
                 const ref = sessionRef(name);
                 const stopWatching = watchPending(agents, ref);
                 const printer = createTerminalPrinter({ paced: true });
-                // Ctrl-C: out with what's still being typed, and the terminal back to normal text.
                 process.once("SIGINT", () => {
                     printer.close();
                     process.exit(130);
@@ -390,8 +419,8 @@ export const sessionCommands = {
                     before: typeof flags.before === "string" ? timeFlag(flags.before) : undefined,
                 });
                 const printer = createTerminalPrinter({ paced: false });
-                for (const { type, message } of page.messages)
-                    printer.printTranscript(type, message.content);
+                for (const message of page.messages)
+                    printer.printTranscript(message);
                 printer.close();
                 if (page.nextBefore)
                     process.stderr.write(`(older: hyperbrane session logs ${name} --before ${page.nextBefore})\n`);
@@ -403,7 +432,7 @@ export const sessionCommands = {
             async run([name], _flags, { agents }) {
                 const ref = sessionRef(name);
                 const [state, messages] = await Promise.all([agents.getSessionStatus(ref), agents.getLastUserMessages(ref)]);
-                console.log(state);
+                console.log(describeStatus(state));
                 for (const { message, queued } of messages) {
                     const content = message.message.content;
                     const text = typeof content === "string" ? content : content.map((block) => (block.type === "text" ? block.text : "")).join("");
@@ -426,7 +455,6 @@ export const sessionCommands = {
     },
 };
 const AGO_UNITS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
-/** --before's TIME as an ISO 8601 time: a date or time, or how long ago ("30m"). */
 function timeFlag(value) {
     const ago = /^(\d+)([smhd])$/.exec(value);
     const time = ago ? Date.now() - Number(ago[1]) * AGO_UNITS[ago[2]] : Date.parse(value);

package/dist/cli/command.d.ts

@@ -1,34 +1,35 @@
-import type { Services } from "./services.ts";
+import type { AgentClient, AgentProvision, AgentSessionCapabilities } from "../agent/api.ts";
+import type { DimensionClient } from "../dimension/api.ts";
+import type { GatewayClient, PortalClient } from "../portal-gateway/api.ts";
 export type Flag = {
     type: "string" | "boolean";
     short?: string;
-    /** Shown in help, e.g. "BYTES". */
     value?: string;
     description: string;
-    /** May be given more than once; its value is then a string[]. */
     multiple?: boolean;
 };
 export type Flags = Record<string, string | boolean | string[] | undefined>;
+export type Clients = {
+    readonly dimensions: DimensionClient;
+    readonly gateways: GatewayClient;
+    readonly portals: PortalClient;
+    readonly agents: AgentClient & AgentProvision & AgentSessionCapabilities;
+};
 export type Command = {
     summary: string;
-    /** Positional arguments: "NAME" is required, "[NAME]" optional, a trailing "NAME..." takes one or more. */
     args?: string[];
     flags?: Record<string, Flag>;
-    run(args: string[], flags: Flags, services: Services): Promise<void>;
+    run(args: string[], flags: Flags, clients: Clients): Promise<void>;
 };
 export type CommandGroup = {
     summary: string;
-    /** A group may hold groups of its own: `hyperbrane session permission allow`. */
     commands: Record<string, Command | CommandGroup>;
-    /** Runs when the next word isn't one of `commands`: `hyperbrane session model A/S` next to `... model set`. */
     default?: Command;
 };
 export declare function isGroup(entry: Command | CommandGroup): entry is CommandGroup;
-/** Bad invocation: printed with a pointer to --help. */
 export declare class UsageError extends Error {
     name: string;
 }
-/** Some items of a multi-item command failed; each error was already printed. */
 export declare class PartialFailure extends Error {
     name: string;
 }
@@ -37,9 +38,7 @@ export declare function parseCommand(command: Command, argv: string[]): {
     flags: Flags;
 };
 export declare function requireFlag(flags: Flags, name: string): string;
-/** docker rm style: every item is attempted, each success prints its name, failures print and fail the command. */
 export declare function forEach(names: string[], action: (name: string) => Promise<void>): Promise<void>;
-/** `ls` output: the table, or with -q only the first column. */
 export declare function printList(flags: Flags, headers: string[], rows: string[][]): void;
 export declare const QUIET_FLAG: Record<string, Flag>;
 export declare function commandUsage(path: string, command: Command): string;

package/dist/cli/command.js

@@ -3,11 +3,9 @@ import { formatTable } from "./table.js";
 export function isGroup(entry) {
     return "commands" in entry;
 }
-/** Bad invocation: printed with a pointer to --help. */
 export class UsageError extends Error {
     name = "UsageError";
 }
-/** Some items of a multi-item command failed; each error was already printed. */
 export class PartialFailure extends Error {
     name = "PartialFailure";
 }
@@ -39,7 +37,6 @@ export function requireFlag(flags, name) {
         throw new UsageError(`--${name} is required`);
     return value;
 }
-/** docker rm style: every item is attempted, each success prints its name, failures print and fail the command. */
 export async function forEach(names, action) {
     let failed = false;
     for (const name of names) {
@@ -55,7 +52,6 @@ export async function forEach(names, action) {
     if (failed)
         throw new PartialFailure();
 }
-/** `ls` output: the table, or with -q only the first column. */
 export function printList(flags, headers, rows) {
     if (flags.quiet) {
         for (const row of rows)

package/dist/cli/dimension.js

@@ -8,13 +8,12 @@ function statusColumn(dimension) {
     }
     return dimension.status[0].toUpperCase() + dimension.status.slice(1);
 }
-function dimensionRow(dimension) {
-    const usage = dimension.memoryUsage === null ? "--" : formatBytes(dimension.memoryUsage);
+function dimensionRow(dimension, usage) {
     return [
         dimension.name,
         statusColumn(dimension),
-        dimension.cpuUsage === null ? "--" : formatCpuPercent(dimension.cpuUsage),
-        `${usage} / ${formatBytes(dimension.memoryLimit)}`,
+        usage ? formatCpuPercent(usage.cpuUsage) : "--",
+        `${usage ? formatBytes(usage.memoryUsage) : "--"} / ${formatBytes(dimension.memoryLimit)}`,
         String(dimension.cpuLimit),
         dimension.directory,
     ];
@@ -26,9 +25,10 @@ export const dimensionCommands = {
             summary: "List dimensions",
             flags: QUIET_FLAG,
             async run(_args, flags, { dimensions }) {
-                const rows = (await dimensions.getDimensions())
+                const [list, usage] = await Promise.all([dimensions.listDimensions(), dimensions.getDimensionUsage()]);
+                const rows = list
                     .sort((a, b) => a.name.localeCompare(b.name))
-                    .map(dimensionRow);
+                    .map((dimension) => dimensionRow(dimension, usage.find((used) => used.name === dimension.name)));
                 printList(flags, ["NAME", "STATUS", "CPU %", "MEM USAGE / LIMIT", "CPUS", "DIRECTORY"], rows);
             },
         },

package/dist/cli/gateway.js

@@ -7,10 +7,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { resolve } from "node:path";
-import anthropic from "../upstreams/anthropic.js";
-import openai from "../upstreams/openai.js";
+import { BUILTIN_UPSTREAMS as BUILTINS } from "../upstreams/index.js";
 import { QUIET_FLAG, UsageError, forEach, printList, requireFlag } from "./command.js";
-const BUILTIN_UPSTREAMS = { anthropic, openai };
+const BUILTIN_UPSTREAMS = Object.fromEntries(BUILTINS.map((upstream) => [upstream.name, upstream]));
 const TRAFFIC_ACTIONS = ["BLOCK", "DELAY", "ASK", "INTERCEPT"];
 export const gatewayCommands = {
     summary: "Manage portal gateways: proxies that hold credentials for the dimensions behind them",
@@ -37,10 +36,8 @@ export const gatewayCommands = {
         create: {
             summary: "Create a gateway, finish creating one that was interrupted, or upgrade one to the current image",
             args: ["NAME"],
-            async run([name], _flags, { gateways, portals }) {
+            async run([name], _flags, { gateways }) {
                 await gateways.createGateway({ name: name });
-                // An upgrade replaces the container, and its portals' links with it.
-                await portals.restorePortals({ gatewayName: name });
                 console.log(name);
             },
         },

package/dist/cli/main.js

@@ -1,24 +1,14 @@
 #!/usr/bin/env bun
-import { createPortalWatcher } from "../portal-gateway/portalService.js";
 import { PartialFailure, UsageError, commandUsage, groupUsage, parseCommand, isGroup, } from "./command.js";
 import { agentCommands, sessionCommands } from "./agent.js";
 import { dimensionCommands } from "./dimension.js";
 import { credentialCommands, gatewayCommands, keyCommands, ruleCommands, upstreamCommands } from "./gateway.js";
 import { portalCommands } from "./portal.js";
-import { createServices } from "./services.js";
-const daemon = {
-    summary: "Run the background work until stopped: restoring portals after container restarts",
-    async run(_args, _flags, { portals, docker }) {
-        const watcher = createPortalWatcher(portals, docker);
-        watcher.start();
-        console.error("hyperbrane daemon running; Ctrl-C to stop");
-        await new Promise((done) => {
-            process.once("SIGINT", done);
-            process.once("SIGTERM", done);
-        });
-        await watcher.stop();
-    },
-};
+import { createAgentClient } from "../agent/agentClient.js";
+import { createDimensionClient } from "../dimension/client.js";
+import { createGatewayClient } from "../portal-gateway/gatewayClient.js";
+import { createPortalClient } from "../portal-gateway/portalClient.js";
+import { createSandboxClient } from "../sandbox/client.js";
 const GROUPS = {
     dimension: dimensionCommands,
     gateway: gatewayCommands,
@@ -30,9 +20,8 @@ const GROUPS = {
     agent: agentCommands,
     session: sessionCommands,
 };
-const COMMANDS = { daemon };
 function usage() {
-    const names = [...Object.keys(GROUPS), ...Object.keys(COMMANDS)];
+    const names = Object.keys(GROUPS);
     const width = Math.max(...names.map((name) => name.length)) + 3;
     return [
         "Usage:  hyperbrane COMMAND",
@@ -42,21 +31,14 @@ function usage() {
         "Management Commands:",
         ...Object.entries(GROUPS).map(([name, group]) => `  ${name.padEnd(width)}${group.summary}`),
         "",
-        "Commands:",
-        ...Object.entries(COMMANDS).map(([name, command]) => `  ${name.padEnd(width)}${command.summary}`),
-        "",
         "Run 'hyperbrane COMMAND --help' for more information on a command.",
     ].join("\n");
 }
 const isHelp = (arg) => arg === "--help" || arg === "-h";
-/** Resolves the command to run, or returns help text to print. Groups nest: each word picks an entry. */
 function resolveCommand(argv) {
     const [first] = argv;
     if (first === undefined || isHelp(first) || first === "help")
         return { help: usage() };
-    const standalone = COMMANDS[first];
-    if (standalone)
-        return { path: first, command: standalone, rest: argv.slice(1) };
     let group = GROUPS[first];
     if (!group)
         return new UsageError(`unknown command ${first}`);
@@ -99,14 +81,15 @@ async function main(argv) {
         console.error(`Error: ${error.message}\nRun 'hyperbrane ${path} --help' for usage.`);
         return 2;
     }
-    const services = createServices();
-    // A container restart takes its portals with it, and nothing else may be running to notice: every
-    // command re-wires what's gone first (a quick look at each gateway when nothing is).
-    await services.portals.restorePortals().catch((error) => {
-        console.error(`Warning: restoring portals failed: ${error.message}`);
-    });
+    const machine = createSandboxClient({ kind: "local" });
+    const clients = {
+        dimensions: createDimensionClient(machine),
+        gateways: createGatewayClient(machine),
+        portals: createPortalClient(machine),
+        agents: createAgentClient(machine),
+    };
     try {
-        await command.run(parsed.args, parsed.flags, services);
+        await command.run(parsed.args, parsed.flags, clients);
         return 0;
     }
     catch (error) {

package/dist/cli/streamPrinter.d.ts

@@ -1,22 +1,14 @@
-import type { AgentStreamingMessage } from "../agent/api.ts";
+import type { AgentStreamingMessage, AgentTranscriptMessage } from "../agent/api.ts";
 export declare function preview(value: unknown): string;
-/** The part of stdout the printer uses. */
 export type TerminalStream = {
     isTTY?: boolean;
     write(chunk: string): unknown;
 };
 export interface TerminalPrinter {
-    /** A stream message: partial text and thinking as they arrive, tool calls and results, and how each turn ended. */
     print(message: AgentStreamingMessage): void;
-    /** A complete message of a transcript. */
-    printTranscript(role: "user" | "assistant", content: unknown): void;
+    printTranscript(message: AgentTranscriptMessage): void;
     close(): void;
 }
-/**
- * Prints to `stream` (stdout); `paced` text is typed out steadily (see createPacedOutput) when it's
- * a terminal. A complete assistant message's text is printed only if none of it streamed: claude
- * reports failures it hits before reaching the API (a TLS error, say) as a synthetic message.
- */
 export declare function createTerminalPrinter({ paced, stream }: {
     paced: boolean;
     stream?: TerminalStream;

package/dist/cli/streamPrinter.js

@@ -1,18 +1,10 @@
-/** Longest a tool input or result is shown, in characters. */
 const PREVIEW_LENGTH = 400;
-/** The pacer's clock: about a frame. */
 const TICK_MS = 16;
-/** Deltas arriving this close together are one burst. */
 const BURST_GAP_MS = 20;
-/** How far back the arrival rate is measured. */
 const RATE_WINDOW_MS = 2_000;
-/** The time a lone first burst is spread over, before there's a rate to go by. */
 const FIRST_BURST_MS = 300;
-/** Typing runs this much faster than text arrives, so the buffer drains rather than grows. */
 const CATCH_UP = 1.1;
-/** The slowest the pacer types, in characters per ms. */
 const MIN_RATE = 0.06;
-/** No character waits longer than this to be typed, whatever the pace. */
 const MAX_LAG_MS = 1_000;
 const DIM = "\x1b[2m";
 const NORMAL = "\x1b[22m";
@@ -20,10 +12,6 @@ export function preview(value) {
     const text = typeof value === "string" ? value : JSON.stringify(value);
     return text.length > PREVIEW_LENGTH ? `${text.slice(0, PREVIEW_LENGTH)}…` : text;
 }
-/**
- * Writes to `stream`, switching styles as text changes between answer and thinking: dimmed on a
- * terminal, marked with [thinking] otherwise. Thinking always ends on a line of its own.
- */
 function createStyledWriter(stream) {
     const tty = stream.isTTY === true;
     let style = "text";
@@ -47,25 +35,15 @@ function createStyledWriter(stream) {
         },
     };
 }
-/** Writes everything at once, as it comes. */
 function createDirectOutput(stream) {
     const writer = createStyledWriter(stream);
     return { text: writer.text, line: writer.line, close: () => writer.line("") };
 }
-/**
- * Types text out at a steady pace instead of in the bursts it arrives in (model APIs send several
- * words at once, then pause for a while): at the rate text has been arriving, a little faster, so
- * each burst lasts until about when the next one comes, and never more than MAX_LAG_MS behind. A
- * pause shows only when the model pauses for longer than that. Lines wait for the text before
- * them, then go out whole.
- */
 function createPacedOutput(stream) {
     const writer = createStyledWriter(stream);
     const queue = [];
-    /** Recent bursts: when each came, and how many characters. */
     const bursts = [];
     let waitingChars = 0;
-    /** Characters the pace has allowed but not yet typed (fractions carry over between ticks). */
     let credit = 0;
     let lastTick = 0;
     let timer;
@@ -79,22 +57,12 @@ function createPacedOutput(stream) {
         while (bursts.length > 1 && now - bursts[0].at > RATE_WINDOW_MS)
             bursts.shift();
     }
-    /**
-     * Characters per ms the text has been arriving at: the bursts before the newest over the time they
-     * span up to it, since the newest is what covers the time ahead. A lone burst is spread over
-     * FIRST_BURST_MS.
-     */
     function arrivalRate() {
         if (bursts.length < 2)
             return (bursts[0]?.chars ?? 0) / FIRST_BURST_MS;
         const earlier = bursts.slice(0, -1).reduce((sum, burst) => sum + burst.chars, 0);
         return earlier / (bursts.at(-1).at - bursts[0].at);
     }
-    /**
-     * The least that keeps every waiting chunk within MAX_LAG_MS, spread evenly over the ticks left
-     * rather than all at once when it's due: for each chunk, the characters up to its end over the
-     * ticks until its deadline. Only matters when text arrives faster than the rate predicted.
-     */
     function deadlinePace() {
         const now = performance.now();
         let before = 0;
@@ -110,7 +78,6 @@ function createPacedOutput(stream) {
     }
     function tick() {
         const now = performance.now();
-        // A late tick (a busy event loop) catches up, but not by more than a few frames at once.
         credit += Math.max(MIN_RATE, arrivalRate() * CATCH_UP) * Math.min(now - lastTick, TICK_MS * 4);
         lastTick = now;
         let budget = Math.max(Math.floor(credit), deadlinePace());
@@ -141,14 +108,12 @@ function createPacedOutput(stream) {
         lastTick = performance.now();
         timer = setInterval(tick, TICK_MS);
     }
-    // Nothing is banked while idle: the next burst paces from zero instead of coming out at once.
     function stop() {
         clearInterval(timer);
         timer = undefined;
         credit = 0;
     }
     function text(chunk, style) {
-        // Code points, so a character outside the BMP is never split across ticks.
         const chars = [...chunk];
         queue.push({ kind: "text", style, chars, arrivedAt: performance.now() });
         waitingChars += chars.length;
@@ -173,11 +138,19 @@ function createPacedOutput(stream) {
     }
     return { text, line, close };
 }
-/**
- * A message's content as a terminal transcript: the user's words as "> ...", tool calls and their
- * results on lines of their own, and the assistant's text and thinking when `withText` (a stream has
- * already printed them as partial output).
- */
+function printSystem(output, message) {
+    output.line(`\n[${describeSystem(message)}]\n`);
+}
+function describeSystem(message) {
+    if (message.subtype === "compact_boundary") {
+        const meta = message.compact_metadata;
+        return meta ? `compacted, ${meta.trigger}, from ${meta.pre_tokens} tokens` : "compacted";
+    }
+    const { event } = message;
+    if (event.kind === "review")
+        return `review ${event.state}: ${event.review}`;
+    return `subagent ${event.agent} (${event.path}) ${event.activity}`;
+}
 function printContent(output, role, content, withText) {
     if (typeof content === "string") {
         if (role === "user")
@@ -201,11 +174,6 @@ function printContent(output, role, content, withText) {
             output.line(`[result${block.is_error ? ", error" : ""}] ${preview(block.content ?? "")}\n`);
     }
 }
-/**
- * Prints to `stream` (stdout); `paced` text is typed out steadily (see createPacedOutput) when it's
- * a terminal. A complete assistant message's text is printed only if none of it streamed: claude
- * reports failures it hits before reaching the API (a TLS error, say) as a synthetic message.
- */
 export function createTerminalPrinter({ paced, stream = process.stdout }) {
     const output = paced && stream.isTTY ? createPacedOutput(stream) : createDirectOutput(stream);
     let streamed = false;
@@ -239,13 +207,15 @@ export function createTerminalPrinter({ paced, stream = process.stdout }) {
                     output.line("\n[done]\n");
                 return;
             case "system":
+                if (message.subtype === "compact_boundary" || message.subtype === "session_event")
+                    return printSystem(output, message);
                 output.line(`[session ${message.session_id}, model ${message.model}]\n`);
                 return;
         }
     }
     return {
         print,
-        printTranscript: (role, content) => printContent(output, role, content, true),
+        printTranscript: (message) => (message.type === "system" ? printSystem(output, message) : printContent(output, message.type, message.message.content, true)),
         close: output.close,
     };
 }

package/dist/cli/table.d.ts

@@ -1,7 +1,4 @@
 export declare function formatTable(headers: string[], rows: string[][]): string;
-/** 268435456 -> "256MiB", 1597440 -> "1.523MiB" (docker's units.BytesSize). */
 export declare function formatBytes(bytes: number): string;
-/** 0.0512 cores -> "5.12%" (docker stats' CPU %: 100% is one full core). */
 export declare function formatCpuPercent(cores: number): string;
-/** Seconds -> "3 minutes", "About an hour", ... (docker's units.HumanDuration). */
 export declare function formatDuration(seconds: number): string;