@llblab/pi-actors 0.19.11 → 0.20.0

package/AGENTS.md

@@ -43,7 +43,7 @@
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
 - `Template recipe graph`: The valid execution chain is `tool → template → recipe → run → template`; file-backed and co-located recipes are storage variants of that chain | Trigger: Adding registry bindings, recipes, docs, or runtime shortcuts | Action: Keep command templates synchronous and portable, use `async: true` as the detached run switch, require every recipe to own `template` directly, and reject cyclic shortcuts such as recipe-owned `tool`
 - `Layer boundary discipline`: Command-template evolution must be separated from template-recipe configuration and async-run lifecycle configuration | Trigger: Adding syntax, placeholders, imports, async controls, or docs | Action: Put portable execution graph semantics in `docs/command-templates.md`, recipe storage/import/default/reference behavior in `docs/template-recipes.md`, and detached lifecycle/state/IPC behavior in `docs/async-runs.md`; type imported recipes as command-template-shaped recipe definitions, not async-run instances
-- `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason, and ensure installed npm script entrypoints do not import `.ts` files from under `node_modules` through Node native type stripping
+- `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason, and ship compiled `dist/lib/*.js` runtime modules for installed npm script entrypoints and ensure those scripts do not import `.ts` files from under `node_modules` through Node native type stripping
 - `Registry safety boundaries`: Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed | Trigger: Loading/editing persisted config or registration logic | Action: Reject legacy `script` entries explicitly, avoid silent user-config rewrites outside the repo, and keep conflict checks before persistence/runtime registration
 - `Async run observability`: Ambient triangles count active async work units across the visible run tree: each running async run contributes at least one triangle, reported active parallel command/subagent branches contribute the visible branch count when greater than one, and descendant `pi -p` subagent processes are folded in so coordinator-plus-workers scenarios expand beyond a single coordinator marker. Event-driven terminal/outbox watchers should initiate follow-up for unhandled terminal completion/failure states, failed or in-flight `command.done` branch completions, and coordinator-bound script-authored messages with bounded body previews; actor `message` is the explicit coordinator-to-run command channel paired with these upward events. Do not restore busy-polling loops, sleep-then-status smoke examples, duplicate follow-ups for final successful leaf commands, or duplicate follow-ups for `cancel`, `kill`, or control-stop actions already handled by synchronous tool results. | Trigger: Changing async run UI, notifications, actor-message routing, or smoke-test interpretation | Action: Preserve branch-aware triangles from `progress.activeSubagents`, runtime-inferred branch bubbling for packaged fanout completion, process-tree expansion for coordinator-launched workers, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.20.0: Compiled Runtime Entrypoints
+
+- `[Packaging]` Added a build step that emits compiled `dist/lib/*.js` and declaration files from the TypeScript runtime modules, with relative `.ts` imports rewritten to `.js` for installed package execution.
+- `[Async Runs]` Replaced the emergency installed-package copy workaround in `scripts/async-runner.mjs` with dist-first imports. Installed npm packages now execute the async runner against compiled JS without relying on Node native type stripping for `.ts` files under `node_modules`; source checkouts still fall back to TypeScript imports for local development.
+- `[Scripts]` Updated `scripts/validate-recipe.mjs` to use the same dist-first import path, so packaged recipe validation also runs from compiled JS when installed from npm.
+- `[Tests]` Updated installed-package smoke coverage to simulate `node_modules/@llblab/pi-actors` with `dist`, execute scripts without `--experimental-strip-types`, and assert the old `.type-strip-lib` workaround is not used.
+- `[Package]` Changed the package description to `Local Actor Kernel for Pi`, added `tsconfig.build.json`, included `dist` in the published package, and bumped package/skill metadata to `0.20.0`.
+
 ## 0.19.11: Installed Async Runner Hotfix
 
 - `[Async Runs]` Fixed installed npm package async recipe launches on Node 22 by avoiding direct runtime imports of raw `.ts` files from under `node_modules` in `scripts/async-runner.mjs`. Installed runners now copy the package `lib` sources into the run state before importing them, keeping Node native type stripping outside the blocked `node_modules` path.

package/dist/lib/actor-inspector-tui.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Actor inspector TUI previews.
+ * Zones: terminal actor inspection, room/direct message previews, no-dependency UI formatting
+ */
+export interface ActorInspectorPreview {
+    body_preview?: string;
+    branch?: string;
+    channel: "broadcast" | "direct" | "room";
+    from?: string;
+    from_display?: string;
+    inbox_status?: string;
+    message_id?: string;
+    run: string;
+    sequence?: number;
+    summary?: string;
+    stripe?: boolean;
+    timestamp: string;
+    to: string;
+    type: string;
+}
+export interface ActorInspectorWidgetStyle {
+    actor?: (text: string) => string;
+    muted?: (text: string) => string;
+    preview?: (text: string) => string;
+    stripe?: (text: string) => string;
+    stripeAlt?: (text: string) => string;
+    target?: (text: string) => string;
+    type?: (text: string) => string;
+}
+export interface ActorInspectorRenderOptions {
+}
+export interface ActorInspectorItemViewOptions {
+    sequence: number;
+}
+export interface ActorInspectorRosterMember {
+    address: string;
+    display?: string;
+    role?: string;
+    status?: string;
+}
+export interface ActorInspectorPreviewReadOptions {
+    ownerId?: string;
+    branch?: string;
+    currentRunOnly?: boolean;
+    channels?: ActorInspectorPreview["channel"][];
+    mention?: string;
+    roomLimitPerRun?: number;
+    unreadOnly?: boolean;
+}
+export declare function readActorInspectorPreviews(stateRoot?: string, limit?: number, options?: ActorInspectorPreviewReadOptions): ActorInspectorPreview[];
+export declare function readActorInspectorRoster(stateRoot: string | undefined, run: string, room?: string): ActorInspectorRosterMember[];
+export declare function renderInspectorRosterLine(members: ActorInspectorRosterMember[], width?: number, styles?: ActorInspectorWidgetStyle): string | undefined;
+export declare function renderInspectorRosterPanel(members: ActorInspectorRosterMember[], width?: number, styles?: ActorInspectorWidgetStyle): string[] | undefined;
+export declare function renderInspectorItemView(previews: ActorInspectorPreview[], width: number | undefined, styles: ActorInspectorWidgetStyle | undefined, options: ActorInspectorItemViewOptions): string[] | undefined;
+export declare function renderInspectorWidget(previews: ActorInspectorPreview[], width?: number, styles?: ActorInspectorWidgetStyle, options?: ActorInspectorRenderOptions): string[] | undefined;

package/dist/lib/actor-inspector-tui.js

@@ -0,0 +1,559 @@
+/**
+ * Actor inspector TUI previews.
+ * Zones: terminal actor inspection, room/direct message previews, no-dependency UI formatting
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import * as Paths from "./paths.js";
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readJsonLines(file) {
+    try {
+        return fs
+            .readFileSync(file, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
+    }
+}
+function previewValue(value, maxLength = 320) {
+    if (value === undefined)
+        return undefined;
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const compact = text.replaceAll(/\s+/g, " ").trim();
+    if (!compact)
+        return undefined;
+    return compact.length > maxLength
+        ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
+        : compact;
+}
+function channelFor(message) {
+    if (message.to.startsWith("room:"))
+        return "room";
+    if (message.to === "coordinator" || message.to.startsWith("session:"))
+        return "broadcast";
+    return "direct";
+}
+function previewFromMessage(run, message, timestamp, displayNames = {}) {
+    const to = typeof message.to === "string" ? message.to : undefined;
+    const type = typeof message.type === "string" ? message.type : undefined;
+    if (!to || !type)
+        return undefined;
+    const from = typeof message.from === "string" ? message.from : undefined;
+    const summary = typeof message.summary === "string" ? message.summary : undefined;
+    const body = asRecord(message.body);
+    const display = from
+        ? typeof body.display === "string" && body.display.trim()
+            ? body.display.trim()
+            : displayNames[from]
+        : undefined;
+    return {
+        ...(previewValue(message.body)
+            ? { body_preview: previewValue(message.body) }
+            : {}),
+        channel: channelFor({ to }),
+        ...(from ? { from } : {}),
+        ...(display ? { from_display: display } : {}),
+        run,
+        ...(summary ? { summary } : {}),
+        timestamp,
+        to,
+        type,
+    };
+}
+function readRoomRosterRecords(stateDir, room) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, "rooms", room, "roster.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function memberDisplay(_address, member) {
+    const display = typeof member.display === "string" ? member.display.trim() : "";
+    return display || undefined;
+}
+function readRoomDisplayNames(stateDir, room) {
+    const roster = readRoomRosterRecords(stateDir, room);
+    return Object.fromEntries(Object.entries(roster).flatMap(([address, member]) => {
+        const display = memberDisplay(address, member);
+        return display ? [[address, display]] : [];
+    }));
+}
+function readRoomPreviews(run, stateDir) {
+    const roomsDir = path.join(stateDir, "rooms");
+    try {
+        const previews = fs
+            .readdirSync(roomsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const displayNames = readRoomDisplayNames(stateDir, entry.name);
+            return readJsonLines(path.join(roomsDir, entry.name, "messages.jsonl"))
+                .map((message) => previewFromMessage(run, message, String(message.received_at ?? message.timestamp ?? ""), displayNames))
+                .filter((preview) => Boolean(preview));
+        });
+        return previews;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
+    }
+}
+function readInboxPreviews(run, stateDir) {
+    return readJsonLines(path.join(stateDir, "inbox.jsonl"))
+        .map((message) => previewFromMessage(run, message, String(message.received_at ?? message.timestamp ?? "")))
+        .filter((preview) => Boolean(preview));
+}
+function readBranchInboxPreviews(run, stateDir) {
+    const branchesDir = path.join(stateDir, "branches");
+    try {
+        return fs
+            .readdirSync(branchesDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => readJsonLines(path.join(branchesDir, entry.name, "inbox.jsonl"))
+            .map((message) => {
+            const preview = previewFromMessage(run, message, String(message.queued_at ?? message.received_at ?? message.timestamp ?? ""));
+            if (!preview)
+                return undefined;
+            return {
+                ...preview,
+                branch: entry.name,
+                ...(typeof message.id === "string" ? { message_id: message.id } : {}),
+                ...(typeof message.status === "string" ? { inbox_status: message.status } : {}),
+            };
+        })
+            .filter((preview) => Boolean(preview)));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
+    }
+}
+function readOutboxPreviews(run, stateDir) {
+    return readJsonLines(path.join(stateDir, "outbox.jsonl"))
+        .map((event) => {
+        const message = asRecord(event.message ?? event);
+        return previewFromMessage(run, message, String(event.timestamp ?? event.created_at ?? event.emitted_at ?? ""));
+    })
+        .filter((preview) => Boolean(preview));
+}
+function getRunOwnerId(stateDir) {
+    try {
+        const meta = JSON.parse(fs.readFileSync(path.join(stateDir, "run.json"), "utf8"));
+        return typeof meta.ownerId === "string" ? meta.ownerId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesOwner(stateDir, ownerId) {
+    return ownerId === undefined || getRunOwnerId(stateDir) === ownerId;
+}
+function isUnreadPreview(preview) {
+    return preview.inbox_status === "queued" || preview.inbox_status === undefined && preview.branch !== undefined;
+}
+function matchesBranchFilter(preview, branch) {
+    const name = branch?.trim();
+    if (!name)
+        return true;
+    if (preview.branch !== undefined)
+        return preview.branch === name;
+    const address = `branch:${preview.run}/${name}`;
+    return preview.from === address || preview.to === address;
+}
+function matchesPreviewFilter(preview, options) {
+    if (options.channels?.length && !options.channels.includes(preview.channel)) {
+        return false;
+    }
+    if (options.unreadOnly && !isUnreadPreview(preview))
+        return false;
+    if (!matchesBranchFilter(preview, options.branch))
+        return false;
+    const mention = options.mention?.trim().toLowerCase();
+    if (!mention)
+        return true;
+    return [
+        preview.branch,
+        preview.from,
+        preview.from_display,
+        preview.inbox_status,
+        preview.to,
+        preview.type,
+        preview.summary,
+        preview.body_preview,
+    ].some((value) => value?.toLowerCase().includes(mention));
+}
+function limitRoomPreviewsPerRun(previews, limitPerRun) {
+    if (!Number.isFinite(limitPerRun))
+        return previews;
+    const limit = Math.max(0, Number(limitPerRun));
+    const remainingByRun = new Map();
+    const keep = new Set();
+    for (let index = previews.length - 1; index >= 0; index -= 1) {
+        const preview = previews[index];
+        if (preview.channel !== "room") {
+            keep.add(preview);
+            continue;
+        }
+        const remaining = remainingByRun.get(preview.run) ?? limit;
+        if (remaining <= 0) {
+            remainingByRun.set(preview.run, 0);
+            continue;
+        }
+        keep.add(preview);
+        remainingByRun.set(preview.run, remaining - 1);
+    }
+    return previews.filter((preview) => keep.has(preview));
+}
+export function readActorInspectorPreviews(stateRoot = Paths.getRunStateRoot(), limit = 8, options = {}) {
+    try {
+        const previews = fs
+            .readdirSync(stateRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const stateDir = path.join(stateRoot, entry.name);
+            if (!matchesOwner(stateDir, options.ownerId))
+                return [];
+            return [
+                ...readRoomPreviews(entry.name, stateDir),
+                ...readInboxPreviews(entry.name, stateDir),
+                ...readBranchInboxPreviews(entry.name, stateDir),
+                ...readOutboxPreviews(entry.name, stateDir),
+            ];
+        })
+            .filter((preview) => preview.timestamp)
+            .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        const currentRun = options.currentRunOnly
+            ? previews.at(-1)?.run
+            : undefined;
+        const sequenced = previews
+            .filter((preview) => !currentRun || preview.run === currentRun)
+            .filter((preview) => matchesPreviewFilter(preview, options))
+            .map((preview, index) => ({
+            ...preview,
+            sequence: index + 1,
+            stripe: index % 2 === 1,
+        }));
+        return limitRoomPreviewsPerRun(sequenced, options.roomLimitPerRun).slice(-Math.max(1, limit));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
+    }
+}
+function shorten(value, maxLength, options = { preserveSpaces: true }) {
+    if (!value)
+        return "-";
+    const compact = options.preserveSpaces === false
+        ? value.replaceAll(/\s+/g, "_")
+        : value.replaceAll(/\s+/g, " ").trim();
+    if (maxLength <= 1)
+        return compact.slice(0, Math.max(0, maxLength));
+    return compact.length > maxLength
+        ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
+        : compact;
+}
+function actorName(address) {
+    if (!address)
+        return "unknown";
+    const branch = /^branch:[^/]+\/(.+)$/.exec(address);
+    if (branch)
+        return branch[1] || address;
+    const run = /^run:(.+)$/.exec(address);
+    if (run)
+        return run[1] || address;
+    return address;
+}
+function roomName(address) {
+    const room = /^room:([^/]+)(?:\/(main))?$/.exec(address);
+    return room ? room[1] : undefined;
+}
+function routeActorText(preview) {
+    return preview.from_display || actorName(preview.from);
+}
+function routeText(preview) {
+    const actor = routeActorText(preview);
+    if (preview.channel === "room")
+        return `${actor} # all`;
+    if (preview.channel === "broadcast")
+        return `${actor} ⇢ ${preview.to}`;
+    return `${actor} → ${actorName(preview.to)}`;
+}
+function style(styleFn, text) {
+    return styleFn ? styleFn(text) : text;
+}
+function previewText(preview) {
+    return preview.summary || preview.body_preview || "-";
+}
+function propertyValue(value) {
+    if (value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+function displayWidth(value) {
+    return visibleWidth(value);
+}
+const lineSegmenter = new Intl.Segmenter();
+function boundedLine(value, width) {
+    if (width <= 0)
+        return "";
+    if (visibleWidth(value) <= width)
+        return value;
+    const ellipsis = "…";
+    const ellipsisWidth = visibleWidth(ellipsis);
+    if (width <= ellipsisWidth)
+        return ellipsis.slice(0, width);
+    let output = "";
+    let used = 0;
+    const maxTextWidth = width - ellipsisWidth;
+    for (const { segment } of lineSegmenter.segment(value)) {
+        const segmentWidth = visibleWidth(segment);
+        if (used + segmentWidth > maxTextWidth)
+            break;
+        output += segment;
+        used += segmentWidth;
+    }
+    return `${output}${ellipsis}`;
+}
+function padLine(plain, rendered, width, styles) {
+    const boundedPlain = boundedLine(plain, width);
+    const visible = boundedPlain === plain ? rendered : style(styles.preview, boundedPlain);
+    const padding = Math.max(0, width - visibleWidth(boundedPlain));
+    return `${visible}${" ".repeat(padding)}`;
+}
+function renderCompactInspectorEntry(preview, width, sequenceWidth, routeWidth, typeWidth, styles, stripe) {
+    const separator = "  ";
+    const prefix = " ";
+    const suffix = " ";
+    const contentWidth = Math.max(8, width - prefix.length - suffix.length);
+    const sequence = String(preview.sequence ?? 0).padStart(sequenceWidth, " ");
+    const sequencePrefix = `${sequence}${separator}`;
+    const route = routeText(preview);
+    const routePadding = " ".repeat(Math.max(0, routeWidth - displayWidth(route)));
+    const typePadding = " ".repeat(Math.max(0, typeWidth - displayWidth(preview.type)));
+    const headline = previewText(preview);
+    const lead = `${sequencePrefix}${route}${routePadding}${separator}${preview.type}${typePadding}${separator}`;
+    const visibleHeadline = boundedLine(headline, Math.max(0, contentWidth - displayWidth(lead)));
+    const plain = `${lead}${visibleHeadline}`;
+    const rendered = [
+        style(styles.muted, sequencePrefix),
+        style(styles.target, route),
+        routePadding,
+        separator,
+        style(styles.type, preview.type),
+        typePadding,
+        separator,
+        style(styles.preview, visibleHeadline),
+    ].join("");
+    const line = `${prefix}${padLine(plain, rendered, contentWidth, styles)}${suffix}`;
+    if (stripe && styles.stripe)
+        return [styles.stripe(line)];
+    if (!stripe && styles.stripeAlt)
+        return [styles.stripeAlt(line)];
+    return [line];
+}
+function renderInspectorEntry(preview, width, sequenceWidth, routeWidth, typeWidth, summaryWidth, styles, stripe) {
+    const separator = "  ";
+    const prefix = " ";
+    const suffix = " ";
+    const contentWidth = Math.max(8, width - prefix.length - suffix.length);
+    const sequence = String(preview.sequence ?? 0).padStart(sequenceWidth, " ");
+    const sequencePrefix = `${sequence}${separator}`;
+    const route = routeText(preview);
+    const type = preview.type;
+    const summary = preview.summary?.trim() ?? "";
+    const body = preview.body_preview?.trim() || (!summary ? previewText(preview) : "-");
+    const visibleRoute = boundedLine(route, routeWidth);
+    const visibleType = boundedLine(type, typeWidth);
+    const boundedRoutePadding = " ".repeat(Math.max(0, routeWidth - displayWidth(visibleRoute)));
+    const boundedTypePadding = " ".repeat(Math.max(0, typeWidth - displayWidth(visibleType)));
+    const leadParts = [
+        style(styles.muted, sequencePrefix),
+        style(styles.target, visibleRoute),
+        boundedRoutePadding,
+        separator,
+        style(styles.type, visibleType),
+        boundedTypePadding,
+        separator,
+    ];
+    let lead = `${sequencePrefix}${visibleRoute}${boundedRoutePadding}${separator}${visibleType}${boundedTypePadding}${separator}`;
+    if (summary) {
+        const visibleSummary = boundedLine(summary, summaryWidth);
+        const summaryPadding = " ".repeat(Math.max(0, summaryWidth - displayWidth(visibleSummary)));
+        lead += `${visibleSummary}${summaryPadding}${separator}`;
+        leadParts.push(style(styles.preview, visibleSummary), summaryPadding, separator);
+    }
+    const visibleBody = boundedLine(body, Math.max(0, contentWidth - displayWidth(lead)));
+    const plain = `${lead}${visibleBody}`;
+    const rendered = `${leadParts.join("")}${style(styles.preview, visibleBody)}`;
+    const line = `${prefix}${padLine(plain, rendered, contentWidth, styles)}${suffix}`;
+    if (stripe && styles.stripe)
+        return [styles.stripe(line)];
+    if (!stripe && styles.stripeAlt)
+        return [styles.stripeAlt(line)];
+    return [line];
+}
+export function readActorInspectorRoster(stateRoot = Paths.getRunStateRoot(), run, room = "main") {
+    const stateDir = path.join(stateRoot, run);
+    const roster = readRoomRosterRecords(stateDir, room);
+    return Object.entries(roster).map(([address, member]) => ({
+        address,
+        ...(memberDisplay(address, member)
+            ? { display: memberDisplay(address, member) }
+            : {}),
+        ...(typeof member.role === "string" ? { role: member.role } : {}),
+        ...(typeof member.status === "string" ? { status: member.status } : {}),
+    }));
+}
+function rosterRoleText(role) {
+    const roleLabel = role?.split(";")[0] ?? "";
+    const cleaned = roleLabel.replaceAll(/\s*\([^)]*\)\s*$/g, "").trim().toLowerCase();
+    if (!cleaned || cleaned === "actor")
+        return undefined;
+    return cleaned.replaceAll(/\s+/g, "-");
+}
+function rosterMemberText(member) {
+    const name = member.display || actorName(member.address);
+    const role = rosterRoleText(member.role);
+    if (role === "run")
+        return `run/${name}`;
+    return role ? `${name}/${role}` : name;
+}
+function isRosterMemberActive(member) {
+    const status = member.status?.trim().toLowerCase();
+    return !status || status === "present" || status === "active" || status === "running";
+}
+export function renderInspectorRosterLine(members, width = 80, styles = {}) {
+    return renderInspectorRosterPanel(members, width, styles)?.[0];
+}
+export function renderInspectorRosterPanel(members, width = 80, styles = {}) {
+    if (members.length === 0)
+        return undefined;
+    const safeWidth = Math.max(1, width);
+    const innerWidth = Math.max(1, safeWidth - 2);
+    const prefix = `roster ${members.length}: `;
+    const tokens = members.map((member) => ({
+        active: isRosterMemberActive(member),
+        text: rosterMemberText(member),
+    }));
+    const lines = [];
+    let plain = prefix;
+    let rendered = style(styles.muted, prefix);
+    const flush = () => {
+        const visible = boundedLine(plain, innerWidth);
+        const line = visible === plain ? rendered : style(styles.muted, visible);
+        lines.push(` ${line}${" ".repeat(Math.max(0, innerWidth - displayWidth(visible)))} `);
+    };
+    for (const token of tokens) {
+        const separator = plain === prefix ? "" : ", ";
+        const nextPlain = `${plain}${separator}${token.text}`;
+        const renderedToken = style(token.active ? styles.target : styles.muted, token.text);
+        if (plain !== prefix && displayWidth(nextPlain) > innerWidth) {
+            flush();
+            plain = `  ${token.text}`;
+            rendered = `${style(styles.muted, "  ")}${renderedToken}`;
+            continue;
+        }
+        plain = nextPlain;
+        rendered = `${rendered}${style(styles.muted, separator)}${renderedToken}`;
+    }
+    flush();
+    return lines;
+}
+export function renderInspectorItemView(previews, width = 80, styles = {}, options) {
+    const preview = previews.find((item) => item.sequence === options.sequence);
+    if (!preview)
+        return undefined;
+    const safeWidth = Math.max(1, width);
+    const orderedKeys = [
+        "channel",
+        "run",
+        "from",
+        "from_display",
+        "to",
+        "type",
+        "summary",
+        "body_preview",
+        "timestamp",
+        "stripe",
+    ];
+    const entries = orderedKeys
+        .filter((key) => preview[key] !== undefined)
+        .map((key) => [key, propertyValue(preview[key])]);
+    const keyWidth = Math.max(1, ...entries.map(([key]) => displayWidth(key)));
+    const sequenceText = String(preview.sequence ?? options.sequence);
+    const sequencePadding = " ".repeat(Math.max(0, keyWidth - displayWidth(sequenceText)));
+    const headerSeparator = "  ";
+    const route = routeText(preview);
+    const visibleRoute = boundedLine(route, Math.max(0, safeWidth - keyWidth - headerSeparator.length));
+    const headerPlain = `${sequenceText}${sequencePadding}${headerSeparator}${visibleRoute}`;
+    const header = `${style(styles.muted, sequenceText)}${sequencePadding}${headerSeparator}${style(styles.target, visibleRoute)}`;
+    const headerPadding = Math.max(0, safeWidth - visibleWidth(headerPlain));
+    const lines = [`${header}${" ".repeat(headerPadding)}`, ""];
+    for (const [key, value] of entries) {
+        const keyPadding = " ".repeat(Math.max(0, keyWidth - displayWidth(key)));
+        const separator = "  ";
+        const valueWidth = Math.max(0, safeWidth - keyWidth - separator.length);
+        const visibleValue = boundedLine(value, valueWidth);
+        const plain = `${key}${keyPadding}${separator}${visibleValue}`;
+        const rendered = `${style(styles.muted, key)}${keyPadding}${separator}${style(styles.preview, visibleValue)}`;
+        const padding = Math.max(0, safeWidth - visibleWidth(plain));
+        lines.push(`${rendered}${" ".repeat(padding)}`);
+    }
+    return lines;
+}
+export function renderInspectorWidget(previews, width = 80, styles = {}, options = {}) {
+    if (previews.length === 0)
+        return undefined;
+    const safeWidth = Math.max(1, width);
+    void options;
+    const visible = previews.map((preview, index) => ({
+        preview: { ...preview, sequence: preview.sequence ?? index + 1 },
+        stripe: preview.stripe ?? index % 2 === 1,
+    }));
+    const sequenceWidth = Math.max(1, ...visible.map(({ preview }) => String(preview.sequence ?? 0).length));
+    const lines = [];
+    const separatorWidth = 2;
+    const sequencePrefixWidth = sequenceWidth + separatorWidth;
+    const fixedSeparatorsWidth = separatorWidth * 3;
+    const availableForColumns = Math.max(0, safeWidth - 1 - sequencePrefixWidth - fixedSeparatorsWidth);
+    const naturalRouteWidth = Math.max(...visible.map(({ preview }) => displayWidth(routeText(preview))));
+    const naturalTypeWidth = Math.max(...visible.map(({ preview }) => displayWidth(preview.type)));
+    const routeWidth = Math.min(naturalRouteWidth, Math.max(4, Math.floor(availableForColumns * 0.35)));
+    const typeWidth = Math.min(naturalTypeWidth, Math.max(4, Math.floor(availableForColumns * 0.25)));
+    const messageWidth = Math.max(0, availableForColumns - routeWidth - typeWidth);
+    const summaryWidths = visible
+        .map(({ preview }) => preview.summary?.trim())
+        .filter((summary) => Boolean(summary))
+        .map((summary) => displayWidth(summary));
+    const summaryWidth = summaryWidths.length
+        ? Math.min(Math.max(...summaryWidths), Math.max(1, Math.floor(messageWidth * 0.5)))
+        : 0;
+    for (const { preview, stripe } of visible) {
+        lines.push(...renderInspectorEntry(preview, safeWidth, sequenceWidth, routeWidth, typeWidth, summaryWidth, styles, stripe));
+    }
+    return lines;
+}

package/dist/lib/actor-messages.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Actor message protocol helpers.
+ * Zones: 0.10 draft communication protocol, addressed messages, mailbox metadata
+ * Owns pure validation/normalization for the semantic message envelope; transport routing stays in adapters.
+ */
+export type ActorAddressKind = "branch" | "coordinator" | "room" | "run" | "session" | "tool";
+export interface ActorAddress {
+    kind: ActorAddressKind;
+    value?: string;
+    branch?: string;
+    room?: string;
+}
+export interface ActorMessage {
+    to: string;
+    type: string;
+    body?: unknown;
+    correlation_id?: string;
+    from?: string;
+    metadata?: Record<string, unknown>;
+    reply_to?: string;
+    summary?: string;
+}
+export declare function parseActorAddress(address: string): ActorAddress;
+export declare function formatActorAddress(address: ActorAddress): string;
+export declare function normalizeActorMessage(input: unknown): ActorMessage;