clawdbot 2026.1.4-1

package/dist/agents/steerable-agent-loop.js

@@ -0,0 +1,338 @@
+import { streamSimple, validateToolArguments } from "@mariozechner/pi-ai";
+class EventStream {
+    isComplete;
+    extractResult;
+    queue = [];
+    waiting = [];
+    done = false;
+    finalResultPromise;
+    resolveFinalResult;
+    constructor(isComplete, extractResult) {
+        this.isComplete = isComplete;
+        this.extractResult = extractResult;
+        this.finalResultPromise = new Promise((resolve) => {
+            this.resolveFinalResult = resolve;
+        });
+    }
+    push(event) {
+        if (this.done)
+            return;
+        if (this.isComplete(event)) {
+            this.done = true;
+            this.resolveFinalResult(this.extractResult(event));
+        }
+        const waiter = this.waiting.shift();
+        if (waiter) {
+            waiter({ value: event, done: false });
+        }
+        else {
+            this.queue.push(event);
+        }
+    }
+    end(result) {
+        this.done = true;
+        if (result !== undefined) {
+            this.resolveFinalResult(result);
+        }
+        while (this.waiting.length > 0) {
+            const waiter = this.waiting.shift();
+            if (waiter) {
+                waiter({ value: undefined, done: true });
+            }
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.queue.length > 0) {
+                const next = this.queue.shift();
+                if (next !== undefined) {
+                    yield next;
+                }
+            }
+            else if (this.done) {
+                return;
+            }
+            else {
+                const result = await new Promise((resolve) => this.waiting.push(resolve));
+                if (result.done)
+                    return;
+                yield result.value;
+            }
+        }
+    }
+    result() {
+        return this.finalResultPromise;
+    }
+}
+function createAgentStream() {
+    return new EventStream((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
+}
+export function agentLoop(prompt, context, config, signal, streamFn) {
+    const stream = createAgentStream();
+    void (async () => {
+        const newMessages = [prompt];
+        const currentContext = {
+            ...context,
+            messages: [...context.messages, prompt],
+        };
+        stream.push({ type: "agent_start" });
+        stream.push({ type: "turn_start" });
+        stream.push({ type: "message_start", message: prompt });
+        stream.push({ type: "message_end", message: prompt });
+        await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
+    })();
+    return stream;
+}
+export function agentLoopContinue(context, config, signal, streamFn) {
+    const lastMessage = context.messages[context.messages.length - 1];
+    if (!lastMessage) {
+        throw new Error("Cannot continue: no messages in context");
+    }
+    if (lastMessage.role !== "user" && lastMessage.role !== "toolResult") {
+        throw new Error(`Cannot continue from message role: ${lastMessage.role}. Expected 'user' or 'toolResult'.`);
+    }
+    const stream = createAgentStream();
+    void (async () => {
+        const newMessages = [];
+        const currentContext = { ...context };
+        stream.push({ type: "agent_start" });
+        stream.push({ type: "turn_start" });
+        await runLoop(currentContext, newMessages, config, signal, stream, streamFn);
+    })();
+    return stream;
+}
+async function runLoop(currentContext, newMessages, config, signal, stream, streamFn) {
+    let hasMoreToolCalls = true;
+    let firstTurn = true;
+    const getQueuedMessages = config.getQueuedMessages;
+    let queuedMessages = getQueuedMessages
+        ? await getQueuedMessages()
+        : [];
+    let queuedAfterTools = null;
+    while (hasMoreToolCalls || queuedMessages.length > 0) {
+        if (!firstTurn) {
+            stream.push({ type: "turn_start" });
+        }
+        else {
+            firstTurn = false;
+        }
+        if (queuedMessages.length > 0) {
+            for (const { original, llm } of queuedMessages) {
+                stream.push({ type: "message_start", message: original });
+                stream.push({ type: "message_end", message: original });
+                if (llm) {
+                    currentContext.messages.push(llm);
+                    newMessages.push(llm);
+                }
+            }
+            queuedMessages = [];
+        }
+        const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
+        newMessages.push(message);
+        if (message.stopReason === "error" || message.stopReason === "aborted") {
+            stream.push({ type: "turn_end", message, toolResults: [] });
+            stream.push({ type: "agent_end", messages: newMessages });
+            stream.end(newMessages);
+            return;
+        }
+        const toolCalls = message.content.filter((c) => c.type === "toolCall");
+        hasMoreToolCalls = toolCalls.length > 0;
+        const toolResults = [];
+        if (hasMoreToolCalls) {
+            const toolExecution = await executeToolCalls(currentContext.tools, message, signal, stream, config.getQueuedMessages);
+            toolResults.push(...toolExecution.toolResults);
+            queuedAfterTools = toolExecution.queuedMessages ?? null;
+            currentContext.messages.push(...toolResults);
+            newMessages.push(...toolResults);
+        }
+        stream.push({ type: "turn_end", message, toolResults: toolResults });
+        if (queuedAfterTools && queuedAfterTools.length > 0) {
+            queuedMessages = queuedAfterTools;
+            queuedAfterTools = null;
+        }
+        else {
+            queuedMessages = getQueuedMessages
+                ? await getQueuedMessages()
+                : [];
+        }
+    }
+    stream.push({ type: "agent_end", messages: newMessages });
+    stream.end(newMessages);
+}
+async function streamAssistantResponse(context, config, signal, stream, streamFn) {
+    const processedMessages = config.preprocessor
+        ? await config.preprocessor(context.messages, signal)
+        : [...context.messages];
+    const processedContext = {
+        systemPrompt: context.systemPrompt,
+        messages: [...processedMessages].map((m) => {
+            if (m.role === "toolResult") {
+                const { details: _details, ...rest } = m;
+                return rest;
+            }
+            return m;
+        }),
+        tools: context.tools,
+    };
+    const streamFunction = streamFn || streamSimple;
+    const resolvedApiKey = (config.getApiKey
+        ? await config.getApiKey(config.model.provider)
+        : undefined) || config.apiKey;
+    const response = await streamFunction(config.model, processedContext, {
+        ...config,
+        apiKey: resolvedApiKey,
+        signal,
+    });
+    let partialMessage = null;
+    let addedPartial = false;
+    for await (const event of response) {
+        switch (event.type) {
+            case "start":
+                partialMessage = event.partial;
+                context.messages.push(partialMessage);
+                addedPartial = true;
+                stream.push({ type: "message_start", message: { ...partialMessage } });
+                break;
+            case "text_start":
+            case "text_delta":
+            case "text_end":
+            case "thinking_start":
+            case "thinking_delta":
+            case "thinking_end":
+            case "toolcall_start":
+            case "toolcall_delta":
+            case "toolcall_end":
+                if (partialMessage) {
+                    partialMessage = event.partial;
+                    context.messages[context.messages.length - 1] = partialMessage;
+                    stream.push({
+                        type: "message_update",
+                        assistantMessageEvent: event,
+                        message: { ...partialMessage },
+                    });
+                }
+                break;
+            case "done":
+            case "error": {
+                const finalMessage = await response.result();
+                if (addedPartial) {
+                    context.messages[context.messages.length - 1] = finalMessage;
+                }
+                else {
+                    context.messages.push(finalMessage);
+                }
+                if (!addedPartial) {
+                    stream.push({ type: "message_start", message: { ...finalMessage } });
+                }
+                stream.push({ type: "message_end", message: finalMessage });
+                return finalMessage;
+            }
+        }
+    }
+    return await response.result();
+}
+async function executeToolCalls(tools, assistantMessage, signal, stream, getQueuedMessages) {
+    const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+    const results = [];
+    let queuedMessages;
+    for (let index = 0; index < toolCalls.length; index++) {
+        const toolCall = toolCalls[index];
+        const tool = tools?.find((t) => t.name === toolCall.name);
+        stream.push({
+            type: "tool_execution_start",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            args: toolCall.arguments,
+        });
+        let result;
+        let isError = false;
+        try {
+            if (!tool)
+                throw new Error(`Tool ${toolCall.name} not found`);
+            const validatedArgs = validateToolArguments(tool, toolCall);
+            result = await tool.execute(toolCall.id, validatedArgs, signal, (partialResult) => {
+                stream.push({
+                    type: "tool_execution_update",
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    args: toolCall.arguments,
+                    partialResult,
+                });
+            });
+        }
+        catch (err) {
+            result = {
+                content: [
+                    {
+                        type: "text",
+                        text: err instanceof Error ? err.message : String(err),
+                    },
+                ],
+                details: {},
+            };
+            isError = true;
+        }
+        stream.push({
+            type: "tool_execution_end",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            result,
+            isError,
+        });
+        const toolResultMessage = {
+            role: "toolResult",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            content: result.content,
+            details: result.details,
+            isError,
+            timestamp: Date.now(),
+        };
+        results.push(toolResultMessage);
+        stream.push({ type: "message_start", message: toolResultMessage });
+        stream.push({ type: "message_end", message: toolResultMessage });
+        if (getQueuedMessages) {
+            const queued = await getQueuedMessages();
+            if (queued.length > 0) {
+                queuedMessages = queued;
+                const remainingCalls = toolCalls.slice(index + 1);
+                for (const skipped of remainingCalls) {
+                    results.push(skipToolCall(skipped, stream));
+                }
+                break;
+            }
+        }
+    }
+    return { toolResults: results, queuedMessages };
+}
+function skipToolCall(toolCall, stream) {
+    const result = {
+        content: [{ type: "text", text: "Skipped due to queued user message." }],
+        details: {},
+    };
+    stream.push({
+        type: "tool_execution_start",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        args: toolCall.arguments,
+    });
+    stream.push({
+        type: "tool_execution_end",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        result,
+        isError: true,
+    });
+    const toolResultMessage = {
+        role: "toolResult",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: result.content,
+        details: result.details,
+        isError: true,
+        timestamp: Date.now(),
+    };
+    stream.push({ type: "message_start", message: toolResultMessage });
+    stream.push({ type: "message_end", message: toolResultMessage });
+    return toolResultMessage;
+}

package/dist/agents/steerable-provider-transport.js

@@ -0,0 +1,48 @@
+import { agentLoop, agentLoopContinue } from "./steerable-agent-loop.js";
+export class SteerableProviderTransport {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    getModel(cfg) {
+        let model = cfg.model;
+        if (this.options.corsProxyUrl && cfg.model.baseUrl) {
+            model = {
+                ...cfg.model,
+                baseUrl: `${this.options.corsProxyUrl}/?url=${encodeURIComponent(cfg.model.baseUrl)}`,
+            };
+        }
+        return model;
+    }
+    buildContext(messages, cfg) {
+        return {
+            systemPrompt: cfg.systemPrompt,
+            messages,
+            tools: cfg.tools,
+        };
+    }
+    buildLoopConfig(model, cfg) {
+        return {
+            model,
+            reasoning: cfg.reasoning,
+            getApiKey: this.options.getApiKey,
+            getQueuedMessages: cfg.getQueuedMessages,
+        };
+    }
+    async *run(messages, userMessage, cfg, signal) {
+        const model = this.getModel(cfg);
+        const context = this.buildContext(messages, cfg);
+        const pc = this.buildLoopConfig(model, cfg);
+        for await (const ev of agentLoop(userMessage, context, pc, signal)) {
+            yield ev;
+        }
+    }
+    async *continue(messages, cfg, signal) {
+        const model = this.getModel(cfg);
+        const context = this.buildContext(messages, cfg);
+        const pc = this.buildLoopConfig(model, cfg);
+        for await (const ev of agentLoopContinue(context, pc, signal)) {
+            yield ev;
+        }
+    }
+}

package/dist/agents/system-prompt.js

@@ -0,0 +1,104 @@
+export function buildAgentSystemPromptAppend(params) {
+    const thinkHint = params.defaultThinkLevel && params.defaultThinkLevel !== "off"
+        ? `Default thinking level: ${params.defaultThinkLevel}.`
+        : "Default thinking level: off.";
+    const extraSystemPrompt = params.extraSystemPrompt?.trim();
+    const ownerNumbers = (params.ownerNumbers ?? [])
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const ownerLine = ownerNumbers.length > 0
+        ? `Owner numbers: ${ownerNumbers.join(", ")}. Treat messages from these numbers as the user.`
+        : undefined;
+    const reasoningHint = params.reasoningTagHint
+        ? [
+            "ALL internal reasoning MUST be inside <think>...</think>.",
+            "Do not output any analysis outside <think>.",
+            "Format every reply as <think>...</think> then <final>...</final>, with no other text.",
+            "Only the final user-visible reply may appear inside <final>.",
+            "Only text inside <final> is shown to the user; everything else is discarded and never seen by the user.",
+            "Example:",
+            "<think>Short internal reasoning.</think>",
+            "<final>Hey there! What would you like to do next?</final>",
+        ].join(" ")
+        : undefined;
+    const runtimeInfo = params.runtimeInfo;
+    const runtimeLines = [];
+    if (runtimeInfo?.host)
+        runtimeLines.push(`Host: ${runtimeInfo.host}`);
+    if (runtimeInfo?.os) {
+        const archSuffix = runtimeInfo.arch ? ` (${runtimeInfo.arch})` : "";
+        runtimeLines.push(`OS: ${runtimeInfo.os}${archSuffix}`);
+    }
+    else if (runtimeInfo?.arch) {
+        runtimeLines.push(`Arch: ${runtimeInfo.arch}`);
+    }
+    if (runtimeInfo?.node)
+        runtimeLines.push(`Node: ${runtimeInfo.node}`);
+    if (runtimeInfo?.model)
+        runtimeLines.push(`Model: ${runtimeInfo.model}`);
+    const lines = [
+        "You are Clawd, a personal assistant running inside Clawdbot.",
+        "",
+        "## Tooling",
+        "Pi lists the standard tools above. This runtime enables:",
+        "- grep: search file contents for patterns",
+        "- find: find files by glob pattern",
+        "- ls: list directory contents",
+        "- bash: run shell commands (supports background via yieldMs/background)",
+        "- process: manage background bash sessions",
+        "- whatsapp_login: generate a WhatsApp QR code and wait for linking",
+        "- browser: control clawd's dedicated browser",
+        "- canvas: present/eval/snapshot the Canvas",
+        "- nodes: list/describe/notify/camera/screen on paired nodes",
+        "- cron: manage cron jobs and wake events",
+        "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
+        "",
+        "## Workspace",
+        `Your working directory is: ${params.workspaceDir}`,
+        "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.",
+        "",
+        params.sandboxInfo?.enabled ? "## Sandbox" : "",
+        params.sandboxInfo?.enabled
+            ? [
+                "Tool execution is isolated in a Docker sandbox.",
+                "Some tools may be unavailable due to sandbox policy.",
+                params.sandboxInfo.workspaceDir
+                    ? `Sandbox workspace: ${params.sandboxInfo.workspaceDir}`
+                    : "",
+                params.sandboxInfo.browserControlUrl
+                    ? `Sandbox browser control URL: ${params.sandboxInfo.browserControlUrl}`
+                    : "",
+                params.sandboxInfo.browserNoVncUrl
+                    ? `Sandbox browser observer (noVNC): ${params.sandboxInfo.browserNoVncUrl}`
+                    : "",
+            ]
+                .filter(Boolean)
+                .join("\n")
+            : "",
+        params.sandboxInfo?.enabled ? "" : "",
+        ownerLine ? "## User Identity" : "",
+        ownerLine ?? "",
+        ownerLine ? "" : "",
+        "## Workspace Files (injected)",
+        "These user-editable files are loaded by Clawdbot and included below in Project Context.",
+        "",
+        "## Messaging Safety",
+        "Never send streaming/partial replies to external messaging surfaces; only final replies should be delivered there.",
+        "Clawdbot handles message transport automatically; respond normally and your reply will be delivered to the current chat.",
+        "",
+        "## Reply Tags",
+        "To request a native reply/quote on supported surfaces, include one tag in your reply:",
+        "- [[reply_to_current]] replies to the triggering message.",
+        "- [[reply_to:<id>]] replies to a specific message id when you have it.",
+        "Tags are stripped before sending; support depends on the current provider config.",
+        "",
+    ];
+    if (extraSystemPrompt) {
+        lines.push("## Group Chat Context", extraSystemPrompt, "");
+    }
+    if (reasoningHint) {
+        lines.push("## Reasoning Format", reasoningHint, "");
+    }
+    lines.push("## Heartbeats", 'If you receive a heartbeat poll (a user message containing just "HEARTBEAT"), and there is nothing that needs attention, reply exactly:', "HEARTBEAT_OK", 'Clawdbot treats a leading/trailing "HEARTBEAT_OK" as a heartbeat ack (and may discard it).', 'If something needs attention, do NOT include "HEARTBEAT_OK"; reply with the alert text instead.', "", "## Runtime", ...runtimeLines, thinkHint);
+    return lines.filter(Boolean).join("\n");
+}

package/dist/agents/tool-display.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import { shortenHomeInString } from "../utils.js";
+const TOOL_DISPLAY_CONFIG = (() => {
+    try {
+        const raw = fs.readFileSync(new URL("./tool-display.json", import.meta.url), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+})();
+const FALLBACK = TOOL_DISPLAY_CONFIG.fallback ?? { emoji: "🧩" };
+const TOOL_MAP = TOOL_DISPLAY_CONFIG.tools ?? {};
+function normalizeToolName(name) {
+    return (name ?? "tool").trim();
+}
+function defaultTitle(name) {
+    const cleaned = name.replace(/_/g, " ").trim();
+    if (!cleaned)
+        return "Tool";
+    return cleaned
+        .split(/\s+/)
+        .map((part) => part.length <= 2 && part.toUpperCase() === part
+        ? part
+        : `${part.at(0)?.toUpperCase() ?? ""}${part.slice(1)}`)
+        .join(" ");
+}
+function normalizeVerb(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.replace(/_/g, " ");
+}
+function coerceDisplayValue(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return undefined;
+        const firstLine = trimmed.split(/\r?\n/)[0]?.trim() ?? "";
+        if (!firstLine)
+            return undefined;
+        return firstLine.length > 160 ? `${firstLine.slice(0, 157)}…` : firstLine;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        const values = value
+            .map((item) => coerceDisplayValue(item))
+            .filter((item) => Boolean(item));
+        if (values.length === 0)
+            return undefined;
+        const preview = values.slice(0, 3).join(", ");
+        return values.length > 3 ? `${preview}…` : preview;
+    }
+    return undefined;
+}
+function lookupValueByPath(args, path) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    let current = args;
+    for (const segment of path.split(".")) {
+        if (!segment)
+            return undefined;
+        if (!current || typeof current !== "object")
+            return undefined;
+        const record = current;
+        current = record[segment];
+    }
+    return current;
+}
+function resolveDetailFromKeys(args, keys) {
+    for (const key of keys) {
+        const value = lookupValueByPath(args, key);
+        const display = coerceDisplayValue(value);
+        if (display)
+            return display;
+    }
+    return undefined;
+}
+function resolveReadDetail(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const record = args;
+    const path = typeof record.path === "string" ? record.path : undefined;
+    if (!path)
+        return undefined;
+    const offset = typeof record.offset === "number" ? record.offset : undefined;
+    const limit = typeof record.limit === "number" ? record.limit : undefined;
+    if (offset !== undefined && limit !== undefined) {
+        return `${path}:${offset}-${offset + limit}`;
+    }
+    return path;
+}
+function resolveWriteDetail(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const record = args;
+    const path = typeof record.path === "string" ? record.path : undefined;
+    return path;
+}
+function resolveActionSpec(spec, action) {
+    if (!spec || !action)
+        return undefined;
+    return spec.actions?.[action] ?? undefined;
+}
+export function resolveToolDisplay(params) {
+    const name = normalizeToolName(params.name);
+    const key = name.toLowerCase();
+    const spec = TOOL_MAP[key];
+    const emoji = spec?.emoji ?? FALLBACK.emoji ?? "🧩";
+    const title = spec?.title ?? defaultTitle(name);
+    const label = spec?.label ?? name;
+    const actionRaw = params.args && typeof params.args === "object"
+        ? params.args.action
+        : undefined;
+    const action = typeof actionRaw === "string" ? actionRaw.trim() : undefined;
+    const actionSpec = resolveActionSpec(spec, action);
+    const verb = normalizeVerb(actionSpec?.label ?? action);
+    let detail;
+    if (key === "read")
+        detail = resolveReadDetail(params.args);
+    if (!detail && (key === "write" || key === "edit" || key === "attach")) {
+        detail = resolveWriteDetail(params.args);
+    }
+    const detailKeys = actionSpec?.detailKeys ?? spec?.detailKeys ?? FALLBACK.detailKeys ?? [];
+    if (!detail && detailKeys.length > 0) {
+        detail = resolveDetailFromKeys(params.args, detailKeys);
+    }
+    if (!detail && params.meta) {
+        detail = params.meta;
+    }
+    if (detail) {
+        detail = shortenHomeInString(detail);
+    }
+    return {
+        name,
+        emoji,
+        title,
+        label,
+        verb,
+        detail,
+    };
+}
+export function formatToolDetail(display) {
+    const parts = [];
+    if (display.verb)
+        parts.push(display.verb);
+    if (display.detail)
+        parts.push(display.detail);
+    if (parts.length === 0)
+        return undefined;
+    return parts.join(" · ");
+}
+export function formatToolSummary(display) {
+    const detail = formatToolDetail(display);
+    return detail
+        ? `${display.emoji} ${display.label}: ${detail}`
+        : `${display.emoji} ${display.label}`;
+}