@llblab/pi-actors 0.19.11 → 0.20.0

package/dist/lib/actor-messages.js

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+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/actor-recipe-context.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Actor recipe context prompt helpers.
+ * Zones: async runner prompt context, recipe provenance, LLM child launches
+ */
+import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import type { TemplateRecipeContextRecord } from "./recipe-references.ts";
+export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
+    you_are_here?: true;
+    you_are_here_path?: string;
+}
+export declare function markRecipeContextRecords(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): MarkedRecipeContextRecord[];
+export declare function formatRecipeContextJsonl(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
+export declare function buildRecipeContextPromptBlock(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
+export declare function appendRecipeContextToPiArgs(command: string, args: string[], records: TemplateRecipeContextRecord[] | undefined, context?: CommandTemplateActorRecipeContext): string[];

package/dist/lib/actor-recipe-context.js

@@ -0,0 +1,79 @@
+/**
+ * Actor recipe context prompt helpers.
+ * Zones: async runner prompt context, recipe provenance, LLM child launches
+ */
+import { basename } from "node:path";
+function commandName(command) {
+    return basename(command).toLowerCase();
+}
+function isPiCommand(command) {
+    return commandName(command) === "pi";
+}
+function findPrintPromptIndex(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if ((arg === "-p" || arg === "--print") && index + 1 < args.length) {
+            return index + 1;
+        }
+    }
+    return undefined;
+}
+function matchesActorContext(record, context) {
+    if (!context)
+        return record.role === "entry";
+    if (context.file && context.file === record.file)
+        return true;
+    if (context.name && context.name === record.name)
+        return true;
+    if (context.alias && context.alias === record.alias)
+        return true;
+    return false;
+}
+function contextPath(record, context) {
+    return record.import_path.join(".") || context?.path || record.name;
+}
+export function markRecipeContextRecords(records, context) {
+    let marked = false;
+    const result = records.map((record) => {
+        if (marked || !matchesActorContext(record, context))
+            return record;
+        marked = true;
+        return {
+            ...record,
+            you_are_here: true,
+            you_are_here_path: contextPath(record, context),
+        };
+    });
+    return result;
+}
+export function formatRecipeContextJsonl(records, context) {
+    return markRecipeContextRecords(records, context)
+        .map((record) => JSON.stringify(record))
+        .join("\n");
+}
+export function buildRecipeContextPromptBlock(records, context) {
+    const jsonl = formatRecipeContextJsonl(records, context);
+    if (!jsonl)
+        return "";
+    return [
+        "Actor recipe context bundle follows as JSONL.",
+        'Each line is one recipe/context record; `"you_are_here": true` marks the recipe node that launched this actor.',
+        "Use this as workflow/composition context, while the task prompt remains authoritative.",
+        "```jsonl",
+        jsonl,
+        "```",
+    ].join("\n");
+}
+export function appendRecipeContextToPiArgs(command, args, records, context) {
+    if (!records || records.length === 0 || !isPiCommand(command))
+        return args;
+    const promptIndex = findPrintPromptIndex(args);
+    if (promptIndex === undefined)
+        return args;
+    const block = buildRecipeContextPromptBlock(records, context);
+    if (!block)
+        return args;
+    const next = [...args];
+    next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
+    return next;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Actor room persistence helpers.
+ * Zones: room timelines, room rosters, cross-branch discovery state
+ * Owns small file-backed room state; routing policy stays in tools/runtime adapters.
+ */
+import type { ActorMessage } from "./actor-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 RoomStatus {
+    room: string;
+    message_count: number;
+    roster_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 declare function readBranchInboxMessages(stateDir: string, run: string, address: string, limit?: number): Array<ActorMessage & {
+    id?: string;
+    queued_at?: string;
+    status?: string;
+}>;
+export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
+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;