@llblab/pi-actors 0.33.0 → 0.34.0

package/dist/lib/tools-local.js

@@ -0,0 +1,156 @@
+/**
+ * Local tool definition behavior
+ * Zones: user recipe tools, generated schemas, async recipe launch
+ * Owns wrapping saved local capabilities as executable pi tools
+ */
+import * as Rooms from "./rooms.js";
+import * as AsyncRuns from "./async-runs.js";
+import * as Execution from "./execution.js";
+import * as Prompts from "./prompts.js";
+import * as RecipesReferences from "./recipes-references.js";
+import * as RecipesUsage from "./recipes-usage.js";
+import * as Schema from "./schema.js";
+import * as ToolsResponse from "./tools-response.js";
+function getRunOwnerId(ctx) {
+    return ctx.sessionManager?.getSessionId?.();
+}
+function typedArgSchema(arg, type) {
+    const description = !type || type.kind === "string"
+        ? `Argument: ${arg}`
+        : type.kind === "path"
+            ? `Path argument: ${arg}`
+            : `${type.kind[0].toUpperCase()}${type.kind.slice(1)} argument: ${arg}`;
+    return Schema.typedArgSchema(description, type);
+}
+function sampleValueForArg(arg, type, defaults) {
+    if (Object.hasOwn(defaults, arg))
+        return defaults[arg];
+    if (!type || type.kind === "string")
+        return `<${arg}>`;
+    if (type.kind === "path")
+        return `./${arg}`;
+    if (type.kind === "int")
+        return 1;
+    if (type.kind === "number")
+        return 1.5;
+    if (type.kind === "bool")
+        return true;
+    if (type.kind === "array")
+        return [`<${arg}>`];
+    return type.values[0] ?? `<${arg}>`;
+}
+function shouldAddRuntimeToolUsageHint(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (/^Argument \S+ must /.test(message) || /^Missing .* value: /.test(message));
+}
+function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
+    const optional = cfg.args.filter((arg) => !required.includes(arg));
+    const example = {};
+    for (const arg of required)
+        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+    for (const arg of optional)
+        example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+    if (includeRunId)
+        example.run_id = `${cfg.name}-1`;
+    const lines = [
+        `Expected call shape for ${cfg.name}:`,
+        `${cfg.name}(${JSON.stringify(example, null, 2)})`,
+    ];
+    if (required.length)
+        lines.push(`Required: ${required.join(", ")}`);
+    if (optional.length || includeRunId)
+        lines.push(`Optional: ${[...optional, ...(includeRunId ? ["run_id"] : [])].join(", ")}`);
+    return lines.join("\n");
+}
+function formatRuntimeToolArgumentError(cfg, error, required, includeRunId) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!shouldAddRuntimeToolUsageHint(error))
+        return error instanceof Error ? error : new Error(message);
+    return new Error(`Invalid arguments for tool "${cfg.name}": ${message}\n\n${formatRuntimeToolUsageHint(cfg, required, includeRunId)}`);
+}
+export function createRuntimeToolDefinition(cfg, exec) {
+    const paramSchema = {};
+    const required = [];
+    const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
+    const isAsyncRecipe = cfg.recipe?.async === true ||
+        RecipesReferences.isAsyncRecipeReference(cfg.template);
+    const recipeTemplate = cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
+    const requiredTemplate = recipeTemplate ?? cfg.template;
+    const requiredTemplateConfig = typeof requiredTemplate === "object" && !Array.isArray(requiredTemplate)
+        ? {
+            ...requiredTemplate,
+            args: cfg.args,
+            defaults: { ...(requiredTemplate.defaults ?? {}), ...cfg.defaults },
+        }
+        : {
+            args: cfg.args,
+            defaults: cfg.defaults,
+            template: requiredTemplate,
+        };
+    const requiredArgs = isRecipe && cfg.storedArgs !== undefined
+        ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+        : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+            ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+            : Schema.getRequiredToolArgNames(requiredTemplateConfig);
+    for (const arg of cfg.args) {
+        paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
+        if (requiredArgs.has(arg))
+            required.push(arg);
+    }
+    if (isAsyncRecipe)
+        paramSchema.run_id = Schema.stringSchema("Optional run id override for this async template recipe invocation.");
+    return {
+        name: cfg.name,
+        label: cfg.name,
+        description: cfg.description,
+        parameters: Schema.objectSchema(paramSchema, required),
+        promptSnippet: isRecipe
+            ? Prompts.formatRecipeToolPromptSnippet(cfg.recipe?.name ?? String(cfg.template), isAsyncRecipe)
+            : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            try {
+                if (cfg.sourcePath)
+                    RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
+                if (isAsyncRecipe) {
+                    const input = params;
+                    const { run_id, ...values } = input;
+                    const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
+                    const runId = typeof run_id === "string" && run_id.trim()
+                        ? run_id.trim()
+                        : `${cfg.name}-${Date.now()}`;
+                    const meta = AsyncRuns.startRun({
+                        ...base,
+                        launch_source: "tool",
+                        ownerId: getRunOwnerId(ctx),
+                        run_id: runId,
+                        tool: cfg.name,
+                        values: Schema.normalizeRuntimeValues({ ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values }, cfg.argTypes),
+                    }, ctx.cwd);
+                    Rooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
+                    Rooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: ToolsResponse.compactAsyncRunStatus(meta),
+                            },
+                        ],
+                        details: meta,
+                    };
+                }
+                if (isRecipe && recipeTemplate) {
+                    const paramsWithDefaults = {
+                        ...(cfg.recipe?.values ?? {}),
+                        ...cfg.defaults,
+                        ...params,
+                    };
+                    return await Execution.executeRegisteredTool({ ...cfg, template: recipeTemplate }, Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes), exec, ctx.cwd, signal);
+                }
+                return await Execution.executeRegisteredTool(cfg, Schema.normalizeRuntimeValues(params, cfg.argTypes), exec, ctx.cwd, signal);
+            }
+            catch (error) {
+                throw formatRuntimeToolArgumentError(cfg, error, required, isAsyncRecipe);
+            }
+        },
+    };
+}

package/dist/lib/tools-mailbox.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public tool mailbox contract helpers
+ * Zones: accepted/emitted message type declarations, contract normalization, compact type extraction
+ * Owns mailbox metadata normalization for public message and inspect tool paths
+ */
+export declare function normalizeMailboxEntry(value: unknown): Record<string, unknown> | undefined;
+export declare function normalizeMailboxContracts(mailbox: Record<string, unknown>): Record<string, unknown[]>;
+export declare function mailboxTypes(entries: unknown[]): string[];

package/dist/lib/tools-mailbox.js

@@ -0,0 +1,48 @@
+/**
+ * Public tool mailbox contract helpers
+ * Zones: accepted/emitted message type declarations, contract normalization, compact type extraction
+ * Owns mailbox metadata normalization for public message and inspect tool paths
+ */
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function normalizeMailboxEntry(value) {
+    if (typeof value === "string")
+        return { type: value };
+    const record = asRecord(value);
+    if (typeof record.type !== "string" || !record.type.trim())
+        return undefined;
+    return {
+        type: record.type.trim(),
+        ...(record.body_schema !== undefined
+            ? { body_schema: record.body_schema }
+            : {}),
+        ...(record.ack !== undefined ? { ack: record.ack } : {}),
+        ...(typeof record.idempotency === "string"
+            ? { idempotency: record.idempotency }
+            : {}),
+        ...(typeof record.level === "string" ? { level: record.level } : {}),
+        ...(record.requires_response === true ? { requires_response: true } : {}),
+        ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
+    };
+}
+export function normalizeMailboxContracts(mailbox) {
+    const accepts = Array.isArray(mailbox.accepts)
+        ? mailbox.accepts
+            .map(normalizeMailboxEntry)
+            .filter((entry) => Boolean(entry))
+        : [];
+    const emits = Array.isArray(mailbox.emits)
+        ? mailbox.emits
+            .map(normalizeMailboxEntry)
+            .filter((entry) => Boolean(entry))
+        : [];
+    return { accepts, emits };
+}
+export function mailboxTypes(entries) {
+    return entries.flatMap((entry) => typeof asRecord(entry).type === "string"
+        ? [String(asRecord(entry).type)]
+        : []);
+}

package/dist/lib/tools-message.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public message tool behavior
+ * Zones: addressed actor messages, run controls, branch/room delivery, tool actor invocation
+ * Owns the public message execution path and compact delivery responses
+ */
+export interface ActorMessageToolDeps<TContext = unknown> {
+    getTool?: (name: string) => any | undefined;
+}
+export declare function createActorMessageToolDefinition<TContext = unknown>(deps?: ActorMessageToolDeps<TContext>): any;

package/dist/lib/tools-message.js

@@ -0,0 +1,346 @@
+/**
+ * Public message tool behavior
+ * Zones: addressed actor messages, run controls, branch/room delivery, tool actor invocation
+ * Owns the public message execution path and compact delivery responses
+ */
+import * as AsyncRuns from "./async-runs.js";
+import * as Messages from "./messages.js";
+import * as Rooms from "./rooms.js";
+import * as Schema from "./schema.js";
+import * as ToolsAccess from "./tools-access.js";
+import * as ToolsMailbox from "./tools-mailbox.js";
+import * as ToolsResponse from "./tools-response.js";
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function maybeJsonText(value, verbose, compact) {
+    return verbose ? ToolsResponse.jsonText(value) : compact;
+}
+function messageBodyToRunLine(message) {
+    if (message.type !== "run.message")
+        return JSON.stringify(message);
+    if (typeof message.body === "string")
+        return message.body;
+    if (message.body === undefined)
+        return message.type;
+    return JSON.stringify(message.body);
+}
+function messageBodyToToolParams(message) {
+    if (message.body &&
+        typeof message.body === "object" &&
+        !Array.isArray(message.body)) {
+        return message.body;
+    }
+    if (message.body === undefined)
+        return {};
+    return { input: message.body };
+}
+function formatToolActorFailure(tool, message, params, error) {
+    const original = error instanceof Error ? error.message : String(error);
+    const paramsPreview = ToolsResponse.compactPreview(params, 240) ?? "{}";
+    return Object.assign(new Error(`tool actor ${tool} failed for message type ${message.type}: ${original}; params=${paramsPreview}`), {
+        message_type: message.type,
+        original_error: original,
+        params_preview: paramsPreview,
+        tool,
+    });
+}
+function assertMessageSenderBelongsToRun(message, run, routeLabel) {
+    if (!message.from) {
+        throw new Error(`message to ${message.to} requires from=<actor address>.`);
+    }
+    const sender = Messages.parseActorAddress(message.from);
+    if ((sender.kind !== "run" && sender.kind !== "branch") ||
+        sender.value !== run) {
+        throw new Error(`message to ${routeLabel} requires from=run:${run} or branch:${run}/<branch>; got ${message.from}.`);
+    }
+}
+async function routeBranchEnvelope(stateDir, runId, recipient, message, _options) {
+    const branchMessage = { ...message, to: recipient };
+    Rooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
+    try {
+        return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+    }
+    catch (error) {
+        const record = error && typeof error === "object"
+            ? error
+            : {};
+        if (record.queued === true) {
+            return {
+                control_path: record.control_path,
+                control_type: record.control_type,
+                delivery_error: record.delivery_error ??
+                    (error instanceof Error ? error.message : String(error)),
+                inbox_id: record.inbox_id,
+                queued: true,
+                run: runId,
+                sent: false,
+                state_dir: stateDir,
+            };
+        }
+        throw error;
+    }
+}
+function getRoomMulticastRecipients(message, run) {
+    const raw = message.metadata?.recipients;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new Error("room multicast metadata.recipients must be an array.");
+    }
+    return raw.map((recipient) => {
+        if (typeof recipient !== "string") {
+            throw new Error("room multicast recipients must be actor addresses.");
+        }
+        const parsed = Messages.parseActorAddress(recipient);
+        if (parsed.kind !== "branch" || parsed.value !== run) {
+            throw new Error(`room multicast recipient must be branch:${run}/<branch>; got ${recipient}.`);
+        }
+        return Messages.formatActorAddress(parsed);
+    });
+}
+function actorMessageNextActions(message, result) {
+    const actions = [];
+    const address = Messages.parseActorAddress(message.to);
+    if (result.delivery_error || result.sent === false) {
+        if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=status`);
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+        else if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+            actions.push(`inspect target=run:${address.value} view=status`);
+        }
+    }
+    if (result.queued === true) {
+        if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+        }
+        else if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+    }
+    return [...new Set(actions)].slice(0, 3);
+}
+function compactActorMessageResult(message, result) {
+    const tokens = [
+        `to=${message.to}`,
+        `type=${message.type}`,
+        `message=${result.sent === true || result.stopped === true ? "sent" : "not_sent"}`,
+    ];
+    if (result.bytes !== undefined)
+        tokens.push(`bytes=${String(result.bytes)}`);
+    if (result.queued === true)
+        tokens.push("queued=true");
+    if (result.control)
+        tokens.push(`control=${String(result.control)}`);
+    if (result.outbox)
+        tokens.push(`messages=${String(result.outbox)}`);
+    if (result.message_count !== undefined)
+        tokens.push(`messages=${String(result.message_count)}`);
+    if (result.roster_count !== undefined)
+        tokens.push(`roster=${String(result.roster_count)}`);
+    if (result.room)
+        tokens.push(`room=${String(result.room)}`);
+    if (result.tool)
+        tokens.push(`tool=${String(result.tool)}`);
+    if (result.stopped === true)
+        tokens.push("stopped=true");
+    if (result.signal)
+        tokens.push(`signal=${String(result.signal)}`);
+    if (result.invoked === true)
+        tokens.push("invoked=true");
+    if (result.delivery_error) {
+        tokens.push(`delivery_error=${ToolsResponse.compactPreview(result.delivery_error, 96)}`);
+    }
+    const nextActions = Array.isArray(result.next_actions)
+        ? result.next_actions
+        : actorMessageNextActions(message, result);
+    if (nextActions.length > 0)
+        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
+    return `\n${tokens.join(" ")}`;
+}
+export function createActorMessageToolDefinition(deps = {}) {
+    return {
+        name: "message",
+        label: "Message",
+        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
+        parameters: Schema.objectSchema({
+            body: Schema.unionSchema([
+                Schema.stringSchema("Message body. For run:<id>, this is the run-local command line."),
+                Schema.looseObjectSchema("Structured JSON message body."),
+                Schema.arraySchema("Structured JSON message body array."),
+            ]),
+            correlation_id: Schema.stringSchema("Optional correlation id for workflow/task linkage."),
+            from: Schema.stringSchema("Optional sender address, such as coordinator or run:<id>."),
+            metadata: Schema.looseObjectSchema("Optional structured metadata for routing or domain hints."),
+            reply_to: Schema.stringSchema("Optional message id this message replies to."),
+            summary: Schema.stringSchema("Optional short human-facing summary."),
+            to: Schema.stringSchema("Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>."),
+            type: Schema.stringSchema("Semantic message type, e.g. control.approve or checkpoint.needs_scope."),
+            verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
+        }, ["to", "type"]),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const input = asRecord(params);
+            const message = Messages.normalizeActorMessage(input);
+            const address = Messages.parseActorAddress(message.to);
+            let result;
+            if (address.kind === "run" && address.value) {
+                const status = ToolsAccess.assertRunAccessibleToContext(address.value, ctx);
+                const normalizedMailbox = ToolsMailbox.normalizeMailboxContracts(asRecord(status.mailbox));
+                const acceptedTypes = new Set(ToolsMailbox.mailboxTypes(normalizedMailbox.accepts));
+                const advisoryWarnings = acceptedTypes.size > 0 && !acceptedTypes.has(message.type)
+                    ? [
+                        `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
+                    ]
+                    : [];
+                if (message.type === "control.kill") {
+                    result = AsyncRuns.killRun(address.value);
+                }
+                else if (message.type === "control.archive") {
+                    result = AsyncRuns.archiveRun(address.value);
+                }
+                else if (message.type === "control.prune") {
+                    const body = asRecord(message.body);
+                    result = AsyncRuns.pruneRun(address.value, {
+                        preserveArtifacts: body.preserve_artifacts === true ||
+                            body.preserveArtifacts === true,
+                    });
+                }
+                else {
+                    result = await AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
+                }
+                if (advisoryWarnings.length > 0)
+                    result = { ...result, warnings: advisoryWarnings };
+            }
+            else if (address.kind === "branch" && address.value) {
+                const runId = address.value;
+                if (message.from)
+                    assertMessageSenderBelongsToRun(message, runId, `branch:${runId}/<branch>`);
+                const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                const stateDir = String(status.state_dir ?? "");
+                if (stateDir && address.branch) {
+                    const ensureBranchMember = (actorAddress) => {
+                        Rooms.ensureRoomMember(stateDir, runId, "main", actorAddress, {
+                            parent: `run:${runId}`,
+                            role: "branch",
+                            status: "present",
+                        }, "Branch joined default room");
+                        Rooms.writeBranchCommunicationSnapshot(stateDir, runId, actorAddress);
+                    };
+                    ensureBranchMember(message.to);
+                    if (message.from) {
+                        const sender = Messages.parseActorAddress(message.from);
+                        if (sender.kind === "branch" && sender.value === runId) {
+                            ensureBranchMember(message.from);
+                        }
+                    }
+                    Rooms.writeCommunicationSnapshot(stateDir, runId);
+                }
+                result = await routeBranchEnvelope(stateDir, runId, message.to, message, {
+                    source: "direct",
+                });
+            }
+            else if (address.kind === "room" && address.value && address.room) {
+                const runId = address.value;
+                assertMessageSenderBelongsToRun(message, runId, `room:${runId}`);
+                const status = ToolsAccess.assertRunAccessibleToContext(runId, ctx);
+                const stateDir = String(status.state_dir ?? "");
+                if (!stateDir)
+                    throw new Error(`${message.to} has no run state directory.`);
+                const recipients = getRoomMulticastRecipients(message, runId);
+                const roomResult = Rooms.appendRoomMessage(stateDir, address.room, message);
+                await Promise.all(recipients.map((recipient) => routeBranchEnvelope(stateDir, runId, recipient, message, {
+                    source: "room-multicast",
+                })));
+                result = {
+                    ...roomResult,
+                    ...(recipients.length > 0
+                        ? { multicast: recipients, multicast_count: recipients.length }
+                        : {}),
+                };
+            }
+            else if (address.kind === "tool" && address.value) {
+                const tool = deps.getTool?.(address.value);
+                if (!tool || typeof tool.execute !== "function") {
+                    throw new Error(`tool actor not found or not executable: ${address.value}`);
+                }
+                const toolParams = messageBodyToToolParams(message);
+                let toolResult;
+                try {
+                    toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
+                }
+                catch (error) {
+                    throw formatToolActorFailure(address.value, message, toolParams, error);
+                }
+                result = {
+                    invoked: true,
+                    sent: true,
+                    tool: address.value,
+                    tool_result: toolResult,
+                };
+            }
+            else if (address.kind === "coordinator" || address.kind === "session") {
+                if (!message.from) {
+                    throw new Error(`message to ${address.kind} requires from=run:<id>.`);
+                }
+                const sender = Messages.parseActorAddress(message.from);
+                if (sender.kind !== "run" || !sender.value) {
+                    throw new Error(`message to ${address.kind} currently requires from=run:<id>.`);
+                }
+                const senderStatus = ToolsAccess.assertRunAccessibleToContext(sender.value, ctx);
+                if (address.kind === "session") {
+                    if (!senderStatus.ownerId) {
+                        throw ToolsAccess.sessionMismatchError({
+                            currentSession: undefined,
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
+                    }
+                    if (senderStatus.ownerId !== address.value) {
+                        throw ToolsAccess.sessionMismatchError({
+                            currentSession: String(senderStatus.ownerId),
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
+                    }
+                }
+                result = AsyncRuns.appendRunOutboxEvent(sender.value, {
+                    body: message.body,
+                    correlation_id: message.correlation_id,
+                    delivery: message.metadata?.requires_response === true ||
+                        address.kind === "session"
+                        ? "followup"
+                        : undefined,
+                    event: message.type,
+                    from: message.from,
+                    metadata: message.metadata,
+                    reply_to: message.reply_to,
+                    summary: message.summary,
+                    to: message.to,
+                    type: message.type,
+                });
+            }
+            else {
+                throw new Error(`message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`);
+            }
+            const nextActions = actorMessageNextActions(message, result);
+            const resultWithNext = nextActions.length
+                ? { ...result, next_actions: nextActions }
+                : result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: maybeJsonText({ message, result: resultWithNext }, input.verbose === true, compactActorMessageResult(message, resultWithNext)),
+                    },
+                ],
+                details: { message, result: resultWithNext },
+            };
+        },
+    };
+}

package/dist/lib/tools-register.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public register_tool behavior
+ * Zones: runtime tool registration, tool registry mutation, register_tool schema
+ * Owns the public register_tool definition that persists local agent capabilities
+ */
+import * as Registry from "./registry.ts";
+import * as Schema from "./schema.ts";
+export type RegisterToolInput = Registry.RegisterToolInput;
+export type RegisterToolRuntimeDeps<TContext> = Registry.RegisterToolRuntimeDeps<TContext>;
+export declare function createRegisterToolDefinition<TContext>(deps: RegisterToolRuntimeDeps<TContext>): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Schema.JsonSchema;
+    execute: (_toolCallId: string, params: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: TContext) => Promise<Registry.RegisterToolResult>;
+};

package/dist/lib/tools-register.js

@@ -0,0 +1,40 @@
+/**
+ * Public register_tool behavior
+ * Zones: runtime tool registration, tool registry mutation, register_tool schema
+ * Owns the public register_tool definition that persists local agent capabilities
+ */
+import * as Prompts from "./prompts.js";
+import * as Registry from "./registry.js";
+import * as Schema from "./schema.js";
+const stringSchema = Schema.stringSchema;
+const booleanSchema = Schema.booleanSchema;
+const nullSchema = Schema.nullSchema;
+const arraySchema = Schema.arraySchema;
+const unionSchema = Schema.unionSchema;
+const objectSchema = Schema.objectSchema;
+const looseObjectSchema = Schema.looseObjectSchema;
+export function createRegisterToolDefinition(deps) {
+    return {
+        name: "register_tool",
+        label: "Register Tool",
+        description: Prompts.REGISTER_TOOL_DESCRIPTION,
+        promptSnippet: Prompts.REGISTER_TOOL_PROMPT_SNIPPET,
+        promptGuidelines: Prompts.REGISTER_TOOL_GUIDELINES,
+        parameters: objectSchema({
+            args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
+            async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
+            description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
+            name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
+            state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
+            template: unionSchema([
+                stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
+                looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
+                arraySchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateArray),
+                nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
+            ]),
+            update: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.update),
+            values: looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.values),
+        }, []),
+        execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => Registry.executeRegisterTool(params, ctx, deps),
+    };
+}

package/dist/lib/tools-response.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Public tool response formatting
+ * Zones: compact text summaries, verbose JSON switching, next-action rendering
+ * Owns model-facing response helpers shared by public tool execution paths
+ */
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function jsonText(value: unknown): string;
+export declare function compactPreview(value: unknown, maxLength?: number): string | undefined;
+export declare function compactNextActions(actions: string[]): string;
+export declare function actorRunNextActions(run: unknown): string[];
+export declare function compactAsyncRunStatus(value: unknown): string;
+export declare function compactInboxMessages(messages: Array<Record<string, unknown>>, emptyLabel: string): string;
+export declare function compactBranchInbox(messages: Array<Record<string, unknown>>): string;
+export declare function compactRunMailbox(run: string, mailbox: Record<string, unknown>, messages: Array<Record<string, unknown>>): string;
+export declare function artifactNextActions(run: unknown, artifacts: Record<string, unknown>): string[];
+export declare function maybeJsonText(value: unknown, verbose: boolean | undefined, compact: string): string;
+export declare function compactRecipeImports(summary: Record<string, unknown>): string;
+export declare function compactRecipeDoctor(summary: Record<string, unknown>): string;
+export declare function recipeRegistryNextActions(summary: Record<string, unknown>, view: string): string[];
+export declare function compactRecipeRegistry(summary: Record<string, unknown>): string;
+export declare const DEFAULT_INSPECT_LINES = 40;