@llblab/pi-actors 0.42.2 → 0.43.0

package/dist/lib/mailbox-loop.js

@@ -1,60 +0,0 @@
-/**
- * Mailbox worker loop primitives.
- * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
- * Owns reusable claim/handle/drain behavior across run and branch inboxes; scheduling and task policy stay outside.
- */
-import { claimBranchInboxMessage, updateBranchInboxMessageStatus, } from "./rooms.js";
-import { claimRunInboxMessage, updateRunInboxMessageStatus, } from "./async-runs.js";
-export function isMailboxLoopStopMessage(message) {
-    const type = message && typeof message === "object" && "type" in message
-        ? message.type
-        : undefined;
-    return type === "control.kill";
-}
-function messageId(message) {
-    return typeof message?.id === "string" ? message.id : undefined;
-}
-export function claimMailboxLoopMessage(target, options = {}) {
-    const owner = options.owner ?? "mailbox-loop";
-    const statuses = options.statuses ?? ["queued"];
-    return target.kind === "run"
-        ? claimRunInboxMessage(target.runOrDir, owner, statuses)
-        : claimBranchInboxMessage(target.stateDir, target.run, target.address, owner, statuses);
-}
-export function updateMailboxLoopMessageStatus(target, id, status, metadata = {}) {
-    return target.kind === "run"
-        ? updateRunInboxMessageStatus(target.runOrDir, id, status, metadata)
-        : updateBranchInboxMessageStatus(target.stateDir, target.run, target.address, id, status, metadata);
-}
-export async function handleMailboxLoopOnce(target, handler, options = {}) {
-    const message = claimMailboxLoopMessage(target, options);
-    const id = messageId(message);
-    if (!message || !id)
-        return { handled: false, target };
-    try {
-        await handler(message);
-        updateMailboxLoopMessageStatus(target, id, "handled");
-        return { handled: true, id, message, target };
-    }
-    catch (error) {
-        updateMailboxLoopMessageStatus(target, id, "failed", {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        throw error;
-    }
-}
-export async function drainMailboxLoopMessages(target, handler, options = {}) {
-    const maxMessages = Math.max(1, Math.floor(options.maxMessages ?? 100));
-    let handled = 0;
-    for (; handled < maxMessages; handled += 1) {
-        const result = await handleMailboxLoopOnce(target, handler, options);
-        if (!result.handled || !result.message) {
-            return { handled, stopped: false, target };
-        }
-        if (options.stopOnControl !== false &&
-            isMailboxLoopStopMessage(result.message)) {
-            return { handled: handled + 1, stopped: true, target };
-        }
-    }
-    return { handled, stopped: false, target };
-}

package/dist/lib/messages.d.ts

@@ -1,25 +0,0 @@
-/**
- * Actor message protocol.
- * Zones: addressed envelopes, address parsing, route normalization
- * Owns pure validation/normalization for semantic actor messages; 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;

package/dist/lib/messages.js

@@ -1,122 +0,0 @@
-/**
- * Actor message protocol.
- * Zones: addressed envelopes, address parsing, route normalization
- * Owns pure validation/normalization for semantic actor messages; transport routing stays in adapters.
- */
-const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
-const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
-function assertToken(value, label) {
-    const normalized = value.trim();
-    if (!normalized)
-        throw new Error(`${label} is required`);
-    if (!ADDRESS_PATTERN.test(normalized)) {
-        throw new Error(`${label} contains unsupported characters: ${value}`);
-    }
-    return normalized;
-}
-export function parseActorAddress(address) {
-    const value = address.trim();
-    if (value === "coordinator")
-        return { kind: "coordinator" };
-    const separator = value.indexOf(":");
-    if (separator < 0)
-        throw new Error(`Actor address must include kind: ${address}`);
-    const kind = value.slice(0, separator);
-    const rest = value.slice(separator + 1);
-    switch (kind) {
-        case "branch": {
-            const [run, branch, ...extra] = rest.split("/");
-            if (extra.length > 0)
-                throw new Error(`Branch address has too many parts: ${address}`);
-            return {
-                kind,
-                value: assertToken(run || "", "branch run"),
-                branch: assertToken(branch || "", "branch id"),
-            };
-        }
-        case "room": {
-            const [run, room, ...extra] = rest.split("/");
-            if (extra.length > 0)
-                throw new Error(`Room address has too many parts: ${address}`);
-            if (room && room !== "main") {
-                throw new Error("Task rooms do not support named subrooms; use room:<run>.");
-            }
-            return {
-                kind,
-                value: assertToken(run || "", "room run"),
-                room: "main",
-            };
-        }
-        case "run":
-        case "session":
-        case "tool":
-            return { kind, value: assertToken(rest, `${kind} address`) };
-        default:
-            throw new Error(`Unsupported actor address kind: ${kind}`);
-    }
-}
-export function formatActorAddress(address) {
-    if (address.kind === "coordinator")
-        return "coordinator";
-    if (address.kind === "branch") {
-        return `branch:${assertToken(address.value || "", "branch run")}/${assertToken(address.branch || "", "branch id")}`;
-    }
-    if (address.kind === "room") {
-        return `room:${assertToken(address.value || "", "room run")}`;
-    }
-    return `${address.kind}:${assertToken(address.value || "", `${address.kind} address`)}`;
-}
-function normalizeOptionalString(value, label) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== "string")
-        throw new Error(`${label} must be a string`);
-    const normalized = value.trim();
-    return normalized || undefined;
-}
-function normalizeMetadata(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== "object" || Array.isArray(value)) {
-        throw new Error("message metadata must be an object");
-    }
-    return value;
-}
-export function normalizeActorMessage(input) {
-    if (!input || typeof input !== "object" || Array.isArray(input)) {
-        throw new Error("actor message must be an object");
-    }
-    const record = input;
-    const to = normalizeOptionalString(record.to, "message.to");
-    if (!to)
-        throw new Error("message.to is required");
-    const parsedTo = parseActorAddress(to);
-    const type = normalizeOptionalString(record.type, "message.type");
-    if (!type)
-        throw new Error("message.type is required");
-    if (!MESSAGE_TYPE_PATTERN.test(type)) {
-        throw new Error(`message.type contains unsupported characters: ${type}`);
-    }
-    const from = normalizeOptionalString(record.from, "message.from");
-    if (from)
-        parseActorAddress(from);
-    const normalizedTo = formatActorAddress(parsedTo);
-    return {
-        to: normalizedTo,
-        type,
-        ...(record.body !== undefined ? { body: record.body } : {}),
-        ...(record.correlation_id !== undefined
-            ? { correlation_id: String(record.correlation_id) }
-            : {}),
-        ...(from ? { from: formatActorAddress(parseActorAddress(from)) } : {}),
-        ...(record.metadata !== undefined
-            ? { metadata: normalizeMetadata(record.metadata) }
-            : {}),
-        ...(record.reply_to !== undefined
-            ? { reply_to: String(record.reply_to) }
-            : {}),
-        ...(record.summary !== undefined
-            ? { summary: String(record.summary) }
-            : {}),
-    };
-}

package/dist/lib/rooms.d.ts

@@ -1,104 +0,0 @@
-/**
- * Actor room persistence.
- * Zones: room timelines, rosters, branch inboxes, cross-branch discovery state
- * Owns file-backed room and branch-mailbox state; routing policy stays in tools/runtime adapters.
- */
-import type { ActorMessage } from "./messages.ts";
-export interface RoomMember {
-    address: string;
-    caps?: unknown;
-    claim?: unknown;
-    display?: unknown;
-    joined_at: string;
-    last_seen: string;
-    parent?: unknown;
-    role?: unknown;
-    status?: string;
-}
-export interface RoomTimelineEntry extends ActorMessage {
-    received_at: string;
-}
-export interface RoomAppendResult {
-    room: string;
-    message_count: number;
-    roster_count: number;
-    sent: true;
-}
-export interface RoomMessagePreview {
-    body_preview?: string;
-    from?: string;
-    summary?: string;
-    timestamp: string;
-    to: string;
-    type: string;
-}
-export interface RoomCompactionInfo {
-    compacted_at: string;
-    dropped_count: number;
-    first_kept_at?: string;
-    last_kept_at?: string;
-    max_messages: number;
-}
-export interface RoomStatus {
-    room: string;
-    message_count: number;
-    roster_count: number;
-    compaction?: RoomCompactionInfo;
-    diagnostics?: string[];
-    diagnostics_count?: number;
-    last_message_at?: string;
-    last_message_from?: string;
-    last_message_summary?: string;
-    last_message_type?: string;
-}
-export interface RoomContact {
-    address: string;
-    caps?: unknown;
-    claim?: unknown;
-    parent?: unknown;
-    role?: unknown;
-    status?: string;
-}
-export interface ActorCommunicationSnapshot {
-    contacts?: RoomContact[];
-    parent?: string;
-    root: string;
-    self: string;
-    rooms: Array<{
-        address: string;
-        members?: RoomMember[];
-        name: string;
-    }>;
-    updated_at: string;
-}
-export declare function readRoomRoster(stateDir: string, room: string): Record<string, RoomMember>;
-export interface BranchInboxRecord extends ActorMessage {
-    claimed_at?: string;
-    claimed_by?: string;
-    error?: string;
-    failed_at?: string;
-    handled_at?: string;
-    id?: string;
-    queued_at?: string;
-    status?: string;
-}
-export interface BranchInboxReadResult {
-    corrupted: number;
-    messages: BranchInboxRecord[];
-}
-export declare function readBranchInboxMessages(stateDir: string, run: string, address: string, limit?: number): BranchInboxRecord[];
-export declare function readBranchInboxDiagnostics(stateDir: string, run: string, address: string, limit?: number): BranchInboxReadResult;
-export declare function getBranchInboxTerminalRetainLimit(): number;
-export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
-export declare function claimBranchInboxMessage(stateDir: string, run: string, address: string, owner?: string, statuses?: string[]): BranchInboxRecord | undefined;
-export declare function updateBranchInboxMessageStatus(stateDir: string, run: string, address: string, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
-export declare function appendRoomMessage(stateDir: string, room: string, message: ActorMessage): RoomAppendResult;
-export declare function readRoomMessages(stateDir: string, room: string, limit?: number): RoomTimelineEntry[];
-export declare function readRoomMessagePreviews(stateDir: string, room: string, limit?: number): RoomMessagePreview[];
-export declare function getRoomStatus(stateDir: string, room: string): RoomStatus;
-export declare function ensureRoomMember(stateDir: string, run: string, room: string, address: string, body: Record<string, unknown>, summary: string): RoomAppendResult;
-export declare function ensureDefaultRoom(stateDir: string, run: string): RoomAppendResult;
-export declare function readCommunicationSnapshot(stateDir: string): ActorCommunicationSnapshot | undefined;
-export declare function readRoomContacts(stateDir: string, room: string, self?: string): RoomContact[];
-export declare function writeCommunicationSnapshot(stateDir: string, run: string): ActorCommunicationSnapshot;
-export declare function writeBranchCommunicationSnapshot(stateDir: string, run: string, self: string): ActorCommunicationSnapshot;