openmausbot 0.1.85 → 0.1.87

package/dist-server/server/drivers/agents-call.js

@@ -0,0 +1,1162 @@
+// Carries out one agents tool: checks the arguments, applies the per-turn
+// guards, calls the harness, and turns the answer into the text the model
+// reads. One core for every front end, so a tool validates, refuses and
+// teaches the same way however it was reached; the stdio MCP proxy
+// (agents-proxy.ts) is the only front end today.
+//
+// Nothing here reads the environment or holds state of its own. The caller
+// passes a ToolCallContext, and the per-turn counters live on it.
+import { CREDENTIAL_TARGETS, isCredentialTargetId } from "../../shared/credential-request.js";
+import { normalizeCronSchedule } from "../../shared/routine-schedule.js";
+import { peerName } from "../peer-roster.js";
+import { catalogProfileFromEnv, SHARED_COMPUTER_TOOL_NAMES, WEEKDAYS } from "./agents-catalog.js";
+import { harnessClientFromEnv } from "./agents-client.js";
+import { boundedAgentResult } from "./agents-result.js";
+/** The context a spawned proxy was given, with a fresh set of turn guards:
+ *   OMB_BOT_ID, OMB_THREAD_ID, OMB_TURN_DEPTH, plus the catalog switches
+ *   (agents-catalog.ts) and the harness address and token (agents-client.ts). */
+export function toolCallContextFromEnv(env) {
+    const profile = catalogProfileFromEnv(env);
+    return {
+        botId: profile.botId,
+        threadId: env.OMB_THREAD_ID ?? "",
+        depth: Number(env.OMB_TURN_DEPTH ?? "0") || 0,
+        externalRuntime: profile.externalRuntime,
+        coordinating: profile.coordinating,
+        sharedComputers: profile.sharedComputers,
+        client: harnessClientFromEnv(env),
+        turn: {
+            createdThisTurn: 0,
+            roomPostsThisTurn: 0,
+            threadsOpenedThisTurn: 0,
+            memoryRefusalsThisTurn: 0,
+            delegationTaskIdsThisTurn: new Set(),
+        },
+    };
+}
+const EXTERNAL_STATUS_GUIDANCE = "Use check_delegation or wait_delegation with this task id to retrieve the result; polling is allowed without ending this external runtime.";
+const MAX_CREATED_PER_TURN = 4;
+// Same spirit as MAX_CREATED_PER_TURN above and MAX_QUEUED_PER_THREAD in
+// delegations.ts: one turn's worth of a good idea is a handful, and a turn
+// that wants more than that has stopped reporting and started broadcasting.
+// The harness enforces its own per-room budget regardless; this one exists
+// so the refusal reaches the model without a round trip.
+const MAX_ROOM_POSTS_PER_TURN = 3;
+// A thread is a real turn with its own run. Five in one turn is a plan
+// ("one per pull request"); more than that is a model that has stopped
+// deciding. The harness holds the same ceiling; this copy exists so the
+// refusal reaches the model without a round trip.
+const MAX_THREADS_PER_TURN = 5;
+// A memory write the harness refused (a stale passage, a full file) needs
+// one re-read and one corrected retry, not a loop of the same append. The
+// third refusal in a turn closes the tool so the turn ends with the person
+// told what did not fit instead of a transcript of retries.
+const MAX_MEMORY_REFUSALS_PER_TURN = 3;
+const SHORT_WEEKDAYS = {
+    mon: "monday",
+    tue: "tuesday",
+    tues: "tuesday",
+    wed: "wednesday",
+    thu: "thursday",
+    thur: "thursday",
+    thurs: "thursday",
+    fri: "friday",
+    sat: "saturday",
+    sun: "sunday",
+};
+const SUPPORTED_SCHEDULES = 'Supported schedules: {"type":"once","at":"2026-09-01T09:00:00+05:30"} (future RFC3339 with explicit offset), ' +
+    '{"type":"weekly","time":"09:00","weekdays":["monday","friday"]}, {"type":"daily","time":"09:00"}, ' +
+    '{"type":"interval","every_minutes":15,"weekdays":["monday","friday"],"window_start":"09:00","window_end":"17:00"}, ' +
+    'or {"type":"cron","expression":"0 9 1 * *","timeZone":"Asia/Kolkata"} (monthly at 09:00 on day 1; five fields and an explicit IANA timezone).';
+/** A schedule as the harness accepts it, or a message telling the model
+ * exactly what to send instead. Coercion first, error second: models
+ * routinely stringify nested objects, say "daily", or shorten weekday
+ * names, and each of those has one obvious meaning. */
+function normalizeScheduleInput(args) {
+    let raw = args.schedule;
+    if (typeof raw === "string") {
+        // Some models deliver nested objects as JSON strings.
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch {
+            return { error: `The schedule must be a JSON object, not text. ${SUPPORTED_SCHEDULES}` };
+        }
+    }
+    if (!jsonRecord(raw))
+        return { error: `The schedule must be a JSON object. ${SUPPORTED_SCHEDULES}` };
+    const type = typeof raw.type === "string" ? raw.type.trim().toLowerCase() : "";
+    const fields = type === "once"
+        ? ["type", "at"]
+        : type === "weekly" || type === "daily"
+            ? ["type", "time", "weekdays"]
+            : type === "interval"
+                ? ["type", "every_minutes", "everyMinutes", "starts_at", "anchorAt", "weekdays", "every_day", "window_start", "window_end", "window", "all_day", "ends_at", "endsAt", "never_ends"]
+                : type === "cron"
+                    ? ["type", "expression", "timeZone"]
+                    : null;
+    // Provider conversions may send unused optional fields as null. Ignore
+    // those, but never silently discard an actual scheduling constraint (for
+    // example timezone or a misspelled starts_at) and approve different work.
+    const unsupported = fields && Object.keys(raw).find((key) => raw[key] != null && !fields.includes(key));
+    if (unsupported) {
+        return { error: `Unsupported ${type} schedule field "${unsupported}". Weekly and daily times use the computer's timezone from list_routines. ${SUPPORTED_SCHEDULES}` };
+    }
+    if (type === "cron") {
+        try {
+            return { schedule: { ...normalizeCronSchedule({ type, expression: raw.expression, timeZone: raw.timeZone }) } };
+        }
+        catch (error) {
+            return { error: `${error instanceof Error ? error.message : "Invalid cron schedule"}. ${SUPPORTED_SCHEDULES}` };
+        }
+    }
+    if (type === "once") {
+        if (typeof raw.at !== "string" || !raw.at.trim()) {
+            return { error: `A once schedule needs "at": a future RFC3339 date-time with an explicit offset, for example 2026-09-01T09:00:00+05:30.` };
+        }
+        return { schedule: { type: "once", at: raw.at.trim() } };
+    }
+    if (type === "weekly" || type === "daily") {
+        const time = typeof raw.time === "string" ? raw.time.trim() : "";
+        if (!time)
+            return { error: `A ${type} schedule needs "time" in 24-hour HH:MM, for example 09:00.` };
+        let weekdays;
+        if (type === "daily") {
+            // daily = weekly on all seven days; an explicit weekdays list narrows it.
+            weekdays = Array.isArray(raw.weekdays) && raw.weekdays.length ? raw.weekdays : [...WEEKDAYS];
+        }
+        else {
+            if (!Array.isArray(raw.weekdays) || raw.weekdays.length === 0) {
+                return { error: `A weekly schedule needs "weekdays", for example ["monday","friday"] — or use {"type":"daily"} to run every day.` };
+            }
+            weekdays = raw.weekdays;
+        }
+        const normalized = [];
+        for (const day of weekdays) {
+            const lower = String(day).trim().toLowerCase();
+            const full = WEEKDAYS.includes(lower)
+                ? lower
+                : Object.hasOwn(SHORT_WEEKDAYS, lower)
+                    ? SHORT_WEEKDAYS[lower]
+                    : undefined;
+            if (!full)
+                return { error: `Unsupported weekday "${String(day)}". Use full names: ${WEEKDAYS.join(", ")}.` };
+            if (!normalized.includes(full))
+                normalized.push(full);
+        }
+        return { schedule: { type: "weekly", time, weekdays: normalized } };
+    }
+    if (type === "interval") {
+        for (const flag of ["every_day", "all_day", "never_ends"]) {
+            if (raw[flag] != null && typeof raw[flag] !== "boolean") {
+                return { error: `"${flag}" must be true or false.` };
+            }
+        }
+        if (raw.window != null && (!jsonRecord(raw.window)
+            || Object.keys(raw.window).some((key) => key !== "start" && key !== "end")
+            || typeof raw.window.start !== "string" || typeof raw.window.end !== "string")) {
+            return { error: '"window" must contain "start" and "end" in HH:MM, for example {"start":"09:00","end":"17:00"}.' };
+        }
+        const rawMinutes = raw.every_minutes ?? raw.everyMinutes;
+        const everyMinutes = Number(rawMinutes);
+        if (!Number.isInteger(everyMinutes) || everyMinutes < 5 || everyMinutes > 1_440) {
+            return { error: 'An interval schedule needs "every_minutes": a whole number from 5 to 1440.' };
+        }
+        const rawStart = raw.starts_at ?? raw.anchorAt;
+        if (rawStart !== undefined && (typeof rawStart !== "string" || !rawStart.trim())) {
+            return { error: '"starts_at" must be an RFC3339 date-time with an explicit timezone offset.' };
+        }
+        if (raw.every_day === true && Array.isArray(raw.weekdays) && raw.weekdays.length > 0) {
+            return { error: 'Choose interval "weekdays" or "every_day", not both.' };
+        }
+        let intervalWeekdays;
+        if (raw.every_day === true) {
+            intervalWeekdays = null;
+        }
+        else if (raw.weekdays !== undefined) {
+            if (!Array.isArray(raw.weekdays) || raw.weekdays.length === 0) {
+                return { error: 'Interval "weekdays" must contain at least one full weekday name.' };
+            }
+            intervalWeekdays = [];
+            for (const day of raw.weekdays) {
+                const lower = String(day).trim().toLowerCase();
+                const full = WEEKDAYS.includes(lower)
+                    ? lower
+                    : Object.hasOwn(SHORT_WEEKDAYS, lower)
+                        ? SHORT_WEEKDAYS[lower]
+                        : undefined;
+                if (!full)
+                    return { error: `Unsupported weekday "${String(day)}". Use full names: ${WEEKDAYS.join(", ")}.` };
+                if (!intervalWeekdays.includes(full))
+                    intervalWeekdays.push(full);
+            }
+        }
+        const rawWindow = jsonRecord(raw.window) ? raw.window : undefined;
+        const windowStart = raw.window_start ?? rawWindow?.start;
+        const windowEnd = raw.window_end ?? rawWindow?.end;
+        if (raw.all_day === true && (windowStart !== undefined || windowEnd !== undefined)) {
+            return { error: 'Choose window_start + window_end or "all_day", not both.' };
+        }
+        let window;
+        if (raw.all_day === true) {
+            window = null;
+        }
+        else if (windowStart !== undefined || windowEnd !== undefined) {
+            if (typeof windowStart !== "string" || !windowStart.trim() || typeof windowEnd !== "string" || !windowEnd.trim()) {
+                return { error: 'An interval time window needs both "window_start" and "window_end" in 24-hour HH:MM.' };
+            }
+            window = { start: windowStart.trim(), end: windowEnd.trim() };
+        }
+        const rawEnd = raw.ends_at ?? raw.endsAt;
+        if (raw.never_ends === true && rawEnd !== undefined) {
+            return { error: 'Choose "ends_at" or "never_ends", not both.' };
+        }
+        let endsAt;
+        if (raw.never_ends === true)
+            endsAt = null;
+        else if (rawEnd !== undefined) {
+            if (typeof rawEnd !== "string" || !rawEnd.trim()) {
+                return { error: '"ends_at" must be an RFC3339 date-time with an explicit timezone offset.' };
+            }
+            endsAt = rawEnd.trim();
+        }
+        return {
+            schedule: {
+                type: "interval",
+                everyMinutes,
+                ...(typeof rawStart === "string" ? { anchorAt: rawStart.trim() } : {}),
+                ...(intervalWeekdays !== undefined ? { weekdays: intervalWeekdays } : {}),
+                ...(window !== undefined ? { window } : {}),
+                ...(endsAt !== undefined ? { endsAt } : {}),
+            },
+        };
+    }
+    if (type === "hourly" || type === "minutes") {
+        return { error: `Use an interval schedule for every-N-minutes work. ${SUPPORTED_SCHEDULES}` };
+    }
+    return { error: `Unknown schedule type "${type || "(missing)"}". ${SUPPORTED_SCHEDULES}` };
+}
+/** Keeps a large result within what a model should be handed, saving the
+ * rest in the harness for tool_result_read. */
+export const capResult = (text, context) => boundedAgentResult(text, (retained, truncated) => {
+    // The standing capability cannot write/read cached tool results. Keep the
+    // normal bounded fallback without making a forbidden request or retrying.
+    if (context.externalRuntime)
+        throw new Error("External runtime results are not cached");
+    return context.client.api("/api/internal/tool-result", { method: "POST", signal: AbortSignal.timeout(3_000),
+        body: JSON.stringify({ text: retained, truncated }) });
+});
+/** "1st", "2nd", "3rd", "4th" — the queue position as a person says it. */
+function ordinal(n) {
+    const rem100 = n % 100;
+    if (rem100 >= 11 && rem100 <= 13)
+        return `${n}th`;
+    const rem10 = n % 10;
+    return `${n}${rem10 === 1 ? "st" : rem10 === 2 ? "nd" : rem10 === 3 ? "rd" : "th"}`;
+}
+function jsonRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function routineAction(value) {
+    return value === "update" || value === "pause" || value === "resume" || value === "run_now" || value === "delete"
+        ? value
+        : null;
+}
+function routineFields(args) {
+    const fields = {};
+    // list_routines returns the harness names. Accept those when a model
+    // copies back a definition, as we already do for interval fields.
+    const destination = (value) => value === "box" ? "cloud" : value;
+    if (args.run_on != null && args.runOn != null && destination(args.run_on) !== destination(args.runOn)) {
+        return { fields, error: "Choose one run_on destination; run_on and runOn disagree." };
+    }
+    if (args.timeout_minutes != null && args.timeoutMinutes != null && args.timeout_minutes !== args.timeoutMinutes) {
+        return { fields, error: "Choose one timeout_minutes limit; timeout_minutes and timeoutMinutes disagree." };
+    }
+    const runOn = destination(args.run_on ?? args.runOn);
+    const timeoutMinutes = args.timeout_minutes ?? args.timeoutMinutes;
+    if (runOn != null && runOn !== "maus" && runOn !== "cloud") {
+        return { fields, error: 'Use run_on="maus" for the bot’s current model and configured computer (including VPS), or run_on="box" only for the Box-hosted agent. Legacy "cloud" also means Box.' };
+    }
+    if (timeoutMinutes != null && (typeof timeoutMinutes !== "number" || !Number.isInteger(timeoutMinutes) || timeoutMinutes < 5 || timeoutMinutes > 240)) {
+        return { fields, error: "timeout_minutes must be a whole number from 5 to 240. Use clear_timeout to remove a limit." };
+    }
+    if (args.continuity != null && typeof args.continuity !== "boolean") {
+        return { fields, error: "continuity must be true or false." };
+    }
+    if (args.overlap !== undefined && args.overlap !== "skip" && args.overlap !== "queue") {
+        return { fields, error: "overlap must be skip or queue." };
+    }
+    if (args.clear_timeout != null && typeof args.clear_timeout !== "boolean") {
+        return { fields, error: "clear_timeout must be true or false." };
+    }
+    if (args.clear_timeout === true && timeoutMinutes != null) {
+        return { fields, error: "Choose timeout_minutes or clear_timeout, not both." };
+    }
+    if (typeof args.name === "string")
+        fields.name = args.name.trim();
+    if (typeof args.instructions === "string")
+        fields.instructions = args.instructions.trim();
+    if (args.schedule !== undefined && args.schedule !== null) {
+        const normalized = normalizeScheduleInput(args);
+        if (normalized.error)
+            return { fields, error: normalized.error };
+        fields.schedule = normalized.schedule;
+    }
+    if (runOn != null)
+        fields.runOn = runOn;
+    if (args.clear_timeout === true)
+        fields.timeoutMinutes = null;
+    else if (timeoutMinutes != null)
+        fields.timeoutMinutes = timeoutMinutes;
+    if (typeof args.continuity === "boolean")
+        fields.continuity = args.continuity;
+    if (args.overlap !== undefined)
+        fields.overlap = args.overlap;
+    return { fields };
+}
+/** Full Access is decided by the harness, not inferred from a model claim or
+ * local environment flag. Missing state preserves older pending responses. */
+function completedProposalResult(r, subject) {
+    const state = r.state;
+    const result = jsonRecord(r.result) ? r.result : undefined;
+    const error = typeof r.error === "string" ? r.error : typeof result?.error === "string" ? result.error : undefined;
+    const attention = error ?? (r.settlementPending && typeof r.message === "string" ? r.message : undefined);
+    if ((!state || state === "pending") && !error)
+        return undefined;
+    const summary = typeof r.summary === "string" && r.summary.trim() ? `\n\n${r.summary.trim()}` : "";
+    const details = result ? `\n\nResult: ${JSON.stringify(result)}` : "";
+    if (state !== "applied" || (result?.state !== undefined && result.state !== "applied")) {
+        return { text: `The request for ${subject} did not complete successfully.${error ? ` ${error}` : ""}${summary}${details}\n\nDo not claim it was applied. Address the reported blocker rather than repeating the request or asking for a duplicate confirmation.`, isError: true };
+    }
+    return { text: `Applied ${subject}.${summary}${details}${attention ? `\n\nNeeds attention: ${attention}` : ""}\n\nNo additional confirmation is needed. Continue the requested work; do not wait for a review card or ask the user to approve this change again.` };
+}
+function confirmationResult(r, fallback, noun = "routine") {
+    const completed = completedProposalResult(r, fallback);
+    if (completed)
+        return completed;
+    const summary = typeof r.summary === "string" && r.summary.trim() ? `\n\n${r.summary.trim()}` : "";
+    return {
+        text: `A confirmation card is now visible to the user for ${fallback}.${summary}\n\nThis change has not been applied yet. End this turn and wait for the user to confirm or deny the card; do not claim the ${noun} was created or changed before confirmation.`,
+    };
+}
+/** Who said a recalled line, as the header of a hit or a read. A user-role
+ * line another bot delivered with ask_bot is labelled as that bot's: the
+ * snippet windows past the provenance note in the text, and a peer's ask
+ * recalled as the user's request is the misattribution the note exists to
+ * prevent. */
+function recallSpeaker(hit) {
+    if (typeof hit.peer === "string" && hit.peer)
+        return `@${hit.peer} (another bot, via ask_bot — not your user)`;
+    if (typeof hit.from === "string" && hit.from)
+        return hit.from;
+    return hit.role === "user" ? "user" : "you";
+}
+/** When a recalled line was said, on the machine's own clock. `toISOString()`
+ * answers in UTC, which disagrees with every other day the bot is shown: a
+ * bare `since`/`until` date is read as local midnight (recent-work.ts
+ * parseSince), the recent-work brief's times are local (whenLabel), and the
+ * daily memory logs are named after the local day. East of UTC a message
+ * from this morning was being dated yesterday — so a search for today's work
+ * came back stamped with the wrong date. */
+function recallWhen(at, dateOnly) {
+    if (typeof at !== "number" || !Number.isFinite(at))
+        return "";
+    const said = new Date(at);
+    if (!Number.isFinite(said.getTime()))
+        return "";
+    const pad = (value) => String(value).padStart(2, "0");
+    const day = `${said.getFullYear()}-${pad(said.getMonth() + 1)}-${pad(said.getDate())}`;
+    return dateOnly ? day : `${day} ${pad(said.getHours())}:${pad(said.getMinutes())}`;
+}
+export async function callTool(name, args, context) {
+    // The names this body has always used, so it reads (and diffs) as it did
+    // when these were the proxy's module-level constants.
+    const { botId: BOT_ID, threadId: THREAD_ID, depth: DEPTH, externalRuntime: EXTERNAL_RUNTIME, coordinating: COORDINATING, turn } = context;
+    const { delegationTaskIdsThisTurn } = turn;
+    const { api, apiResponse } = context.client;
+    // Second lock. With sharing off the tool is not in the catalog, so a front
+    // end already refuses the call as an unknown tool — the same answer a build
+    // without the feature gives. This keeps the handler itself refusing if that
+    // list is ever assembled differently.
+    if (SHARED_COMPUTER_TOOL_NAMES.has(name) && !context.sharedComputers) {
+        return { text: "Computer sharing is turned off in this workspace. There are no shared computers to use.", isError: true };
+    }
+    if (name === "list_shared_computers") {
+        return { text: JSON.stringify(await api("/api/internal/shared-computers")) };
+    }
+    if (name === "shared_computer") {
+        const response = await api("/api/internal/shared-computers", { method: "POST", body: JSON.stringify(args) });
+        const result = response.result;
+        if (Array.isArray(result?.content))
+            return { text: "", passthrough: result };
+        return { text: JSON.stringify(result) };
+    }
+    if (name === "tool_result_read") {
+        if (typeof args.id !== "string" || !/^r-[0-9a-f-]{36}$/.test(args.id) ||
+            (args.offset !== undefined && (!Number.isSafeInteger(args.offset) || Number(args.offset) < 0))) {
+            return { text: "Use the saved result id and a non-negative integer offset from its notice.", isError: true };
+        }
+        const r = await api(`/api/internal/tool-result?id=${encodeURIComponent(args.id)}&offset=${args.offset ?? 0}`, { signal: AbortSignal.timeout(3_000) });
+        const text = String(r.text ?? "");
+        return { text: `${text}\n\n[${Number(r.nextOffset) < Number(r.length)
+                ? `Read more with tool_result_read id "${args.id}" and offset ${r.nextOffset}.`
+                : `End of retained result.${r.truncated ? " The original tail exceeded the storage limit and was omitted." : ""}`}]` };
+    }
+    if (name === "list_room_targets") {
+        const r = await api("/api/internal/room-targets");
+        return { text: JSON.stringify(r), ...(r.error ? { isError: true } : {}) };
+    }
+    if (name === "coordinate_bots") {
+        // The tool's arguments are snake_case, but the harness wire they land on
+        // is camelCase, and a caller can reach for that spelling. Map the aliases
+        // to the canonical keys first - the documented snake_case spelling wins
+        // when both arrive - then refuse an unusable call with the field names a
+        // retry needs instead of a generic validation error (#1239).
+        const canonical = { ...args };
+        delete canonical.botIds;
+        delete canonical.requestKey;
+        delete canonical.groupId;
+        if (canonical.bot_ids === undefined)
+            canonical.bot_ids = args.botIds;
+        if (canonical.request_key === undefined)
+            canonical.request_key = args.requestKey;
+        if (canonical.group_id === undefined)
+            canonical.group_id = args.groupId;
+        const ids = canonical.bot_ids;
+        const usable = Array.isArray(ids) && ids.length > 0 && ids.every((id) => typeof id === "string")
+            && typeof canonical.message === "string" && canonical.message.trim().length > 0
+            && typeof canonical.request_key === "string" && canonical.request_key.trim().length > 0;
+        if (!usable) {
+            return {
+                text: `coordinate_bots takes snake_case arguments: bot_ids (an array of 1-4 teammate ids), message and request_key are required; group_id, rework and label are optional. Received: ${Object.keys(args).join(", ") || "none"}.`,
+                isError: true,
+            };
+        }
+        const r = await api("/api/internal/coordinate-bots", { method: "POST", body: JSON.stringify({
+                groupId: canonical.group_id, botIds: ids, message: canonical.message,
+                requestKey: canonical.request_key, rework: canonical.rework, label: canonical.label,
+            }) });
+        return { text: JSON.stringify(r), ...(r.error ? { isError: true } : {}) };
+    }
+    if (name === "list_bots") {
+        const r = await api(`/api/internal/agents?self=${encodeURIComponent(BOT_ID)}`);
+        const bots = r.bots ?? [];
+        if (!bots.length)
+            return { text: "No other reachable bots yet." };
+        const lines = bots.map((b) => {
+            const role = b.title ? ` — ${b.title}` : "";
+            const about = b.description ? ` (${String(b.description).slice(0, 120)})` : "";
+            // statusText is the server's own wording for what the teammate is
+            // doing; an older server only sends busy, so fall back to that.
+            const state = typeof b.statusText === "string"
+                ? (b.status === "available" ? "" : b.statusText)
+                : (b.busy ? "busy" : "");
+            const team = typeof b.section === "string" ? `, team: ${peerName(b.section) || "General"}` : "";
+            return `- ${b.name}${role}${about} [id: ${b.id}, model: ${b.model}${team}${state ? `, ${state}` : ""}]`;
+        });
+        return {
+            text: `Reachable teammates:\n${lines.join("\n")}\n\n${COORDINATING ? "Use coordinate_bots for advice or concrete work, then end your turn. Busy teammates queue and results resume you automatically." : "Assign work with delegate_bot. Use ask_bot only for a short answer you need inline."}`,
+        };
+    }
+    if (name === "list_rooms") {
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID });
+        const r = await api(`/api/internal/rooms?${query.toString()}`);
+        const rooms = Array.isArray(r.rooms) ? r.rooms.filter(jsonRecord) : [];
+        // A room the bot is in but may not post into comes back named, with the
+        // refusal a post would meet, and without an id: the model gets the exact
+        // reason to hand the user and nothing it could retry against.
+        const unpostable = Array.isArray(r.unpostable) ? r.unpostable.filter(jsonRecord) : [];
+        const blocked = unpostable.length
+            ? `\n\nRooms you are in but cannot post into (no id — there is nothing to retry; give the user the reason instead):\n${unpostable.map((room) => `- ${String(room.name)}: ${String(room.reason)}`).join("\n")}`
+            : "";
+        if (!rooms.length) {
+            return { text: `You are not in any room you can post into. Tell the user what you wanted to share and let them decide where it goes.${blocked}` };
+        }
+        const lines = rooms.map((room) => {
+            const members = Array.isArray(room.members) ? room.members.map(String).join(", ") : "";
+            return `- ${String(room.name)} [id: ${String(room.id)}]${members ? ` — members: ${members}` : ""}`;
+        });
+        return {
+            text: `Rooms you can post into:\n${lines.join("\n")}\n\nUse post_to_room with one of these ids. A post adds one message to the room; it does not start anyone's turn, so nobody replies to it automatically.${blocked}`,
+        };
+    }
+    if (name === "post_to_room") {
+        const groupId = String(args.group_id ?? "").trim();
+        const message = String(args.message ?? "").trim();
+        if (!groupId || !message) {
+            return { text: "post_to_room needs group_id (from list_rooms) and message.", isError: true };
+        }
+        if (turn.roomPostsThisTurn >= MAX_ROOM_POSTS_PER_TURN) {
+            return {
+                text: `You have already posted ${MAX_ROOM_POSTS_PER_TURN} times this turn, which is the limit. Do not retry — finish your turn and say anything further to the user directly.`,
+                isError: true,
+            };
+        }
+        const r = await api("/api/internal/post-to-room", {
+            method: "POST",
+            body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, groupId, message }),
+        });
+        if (r.error)
+            return { text: String(r.error), isError: true };
+        turn.roomPostsThisTurn += 1;
+        return {
+            text: `Posted in ${r.roomName ?? "the room"}. Nobody's turn was started, so expect no reply — tell the user it is posted.`,
+        };
+    }
+    if (name === "ask_bot") {
+        const toBotId = String(args.bot_id ?? "").trim();
+        const message = String(args.message ?? "").trim();
+        if (!toBotId || !message)
+            return { text: "ask_bot needs bot_id and message.", isError: true };
+        const r = await api(`/api/internal/ask-bot`, {
+            method: "POST",
+            body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, toBotId, message, depth: DEPTH }),
+        });
+        if (r.timeout) {
+            // The peer's turn outlived the synchronous wait, so the harness
+            // converted the ask into a delegation — the reply is not lost.
+            const taskId = String(r.taskId ?? "").trim();
+            if (taskId && !EXTERNAL_RUNTIME)
+                delegationTaskIdsThisTurn.add(taskId);
+            const waitedSeconds = Math.max(1, Math.round((Number(r.waitedMs) || 0) / 1000));
+            const amount = waitedSeconds < 60 ? waitedSeconds : Math.round(waitedSeconds / 60);
+            const unit = waitedSeconds < 60 ? "second" : "minute";
+            return {
+                text: `${r.toBotName ?? "That bot"} is still working after ${amount} ${unit}${amount === 1 ? "" : "s"} — the ask was converted to a delegation so the reply is not lost. Task id: ${taskId}. ${EXTERNAL_RUNTIME ? EXTERNAL_STATUS_GUIDANCE : "Finish your turn now; the result will be delivered to this conversation automatically. Use check_delegation in a later turn only if the user asks for status."}`,
+            };
+        }
+        if (r.busy) {
+            // The harness queues the message as a delegation when it can; the
+            // task id is the asker's claim ticket for the eventual reply.
+            const taskId = String(r.taskId ?? "").trim();
+            if (taskId) {
+                if (!EXTERNAL_RUNTIME)
+                    delegationTaskIdsThisTurn.add(taskId);
+                return {
+                    text: `${r.toBotName ?? "That bot"} is busy right now, so your message was queued as a delegation instead — ${EXTERNAL_RUNTIME ? "it waits for the peer and any required approval" : "it runs after your current turn ends"}. Task id: ${taskId}. ${EXTERNAL_RUNTIME ? EXTERNAL_STATUS_GUIDANCE : "Finish your turn now; the result will be delivered to this conversation automatically. Use check_delegation in a later turn only if the user asks for status."}`,
+                };
+            }
+            return { text: `That bot is busy right now — try again after it finishes.` };
+        }
+        if (r.error)
+            return { text: `Couldn't reach that bot: ${r.error}`, isError: true };
+        return { text: `${r.botName ?? "Bot"} replied:\n${r.text ?? "(no reply)"}` };
+    }
+    if (name === "delegate_bot") {
+        const toBotId = String(args.bot_id ?? "").trim();
+        const message = String(args.message ?? "").trim();
+        const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+        if (!toBotId || !message)
+            return { text: "delegate_bot needs bot_id and message.", isError: true };
+        const body = {
+            fromBotId: BOT_ID,
+            fromThreadId: THREAD_ID,
+            toBotId,
+            message,
+            depth: DEPTH,
+        };
+        if (reason)
+            body.reason = reason;
+        const r = await api(`/api/internal/delegate-bot`, { method: "POST", body: JSON.stringify(body) });
+        if (r.error)
+            return { text: `Couldn't queue the delegation: ${r.error}`, isError: true };
+        // Fire-and-forget by contract: the harness returns immediately, the
+        // peer turn runs after our current turn finishes. The task id is the
+        // bot's claim ticket for the outcome.
+        const note = typeof r.message === "string" ? r.message : "Delegation queued.";
+        const taskId = typeof r.taskId === "string" ? r.taskId.trim() : "";
+        if (taskId && !EXTERNAL_RUNTIME)
+            delegationTaskIdsThisTurn.add(taskId);
+        const suffix = taskId
+            ? ` Task id: ${taskId}. ${EXTERNAL_RUNTIME ? EXTERNAL_STATUS_GUIDANCE : "Acknowledge the assignment and finish your turn; the result will be delivered to this conversation automatically. Do not check or wait for it in this turn."}`
+            : "";
+        return { text: `${note}${suffix}` };
+    }
+    if (name === "check_delegation" || name === "wait_delegation") {
+        const taskId = String(args.task_id ?? "").trim();
+        if (!/^[\w-]{4,64}$/.test(taskId)) {
+            return { text: `${name} needs the "task_id" that delegate_bot returned, e.g. {"task_id":"1f0c2f4e-..."}.`, isError: true };
+        }
+        if (!EXTERNAL_RUNTIME && delegationTaskIdsThisTurn.has(taskId)) {
+            return {
+                text: `Task ${taskId} was delegated during this turn. Finish your response now so the other bot can work; its result will be delivered to this conversation automatically. Do not check or wait for a newly delegated task until a later turn.`,
+                isError: true,
+            };
+        }
+        const timeout = Math.min(Math.max(Math.trunc(Number(args.timeout_seconds) || 60), 1), 240);
+        const waitMs = name === "wait_delegation" ? timeout * 1000 : 0;
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, wait_ms: String(waitMs) });
+        const r = await api(`/api/internal/delegations/${encodeURIComponent(taskId)}?${query.toString()}`);
+        const who = typeof r.toBotName === "string" && r.toBotName ? `@${r.toBotName}` : "the peer";
+        if (r.status === "done")
+            return { text: `${who} finished task ${taskId}:\n${String(r.result || "(no reply text)")}` };
+        if (r.status === "queued") {
+            const why = r.targetStatus === "waiting-on-user"
+                ? ` ${who} is waiting on the user, so it goes through after they answer.`
+                : r.targetStatus === "working" ? ` ${who} is busy with other work.` : "";
+            const expiresInMs = Number(r.expiresInMs);
+            const expiry = !Number.isFinite(expiresInMs)
+                ? ""
+                : expiresInMs <= 0
+                    ? " It is past its 24-hour limit and will expire the next time it cannot be delivered."
+                    : ` It expires if not picked up within ${Math.ceil(expiresInMs / 3_600_000)} hour${Math.ceil(expiresInMs / 3_600_000) === 1 ? "" : "s"}.`;
+            return { text: `Task ${taskId} is still queued — ${who} hasn't picked it up yet${waitMs ? ` after ${timeout}s` : ""}.${why}${expiry} Keep working and check again later.` };
+        }
+        if (r.status === "running") {
+            const elapsedMs = Number.isFinite(r.elapsedMs) ? Number(r.elapsedMs) : 0;
+            const minutes = Math.floor(elapsedMs / 60_000);
+            const elapsed = minutes >= 1 ? `${minutes} minute${minutes === 1 ? "" : "s"}` : `${Math.round(elapsedMs / 1000)}s`;
+            const activity = Array.isArray(r.recentActivity) ? r.recentActivity.filter((line) => typeof line === "string") : [];
+            const recent = activity.length
+                ? activity.map((line) => `  - ${line}`).join("\n")
+                : "  (no visible activity yet — if this stays empty, the peer may be stuck, not working; say so instead of promising progress)";
+            return {
+                text: `Task ${taskId} is running with ${who} — going on ${elapsed} now.${waitMs ? ` (still going after ${timeout}s)` : ""}\nRecent activity:\n${recent}\nJudge progress by this activity, not by waiting: real work keeps producing lines; the same silence for a long stretch usually means stuck.`,
+            };
+        }
+        return { text: `Task ${taskId} ended without a reply — ${String(r.status ?? "unknown")}${r.result ? `: ${String(r.result)}` : ""}.`, isError: true };
+    }
+    if (name === "select_computer") {
+        if (args.surface !== undefined && (typeof args.surface !== "string" || !["auto", "cloud", "vm", "local", "browser"].includes(args.surface))) {
+            return { text: "Choose auto, cloud, vm, local or browser; omit surface to inspect connected choices.", isError: true };
+        }
+        const result = await api("/api/internal/computer/select", args.surface === undefined ? undefined : {
+            method: "POST", body: JSON.stringify({ surface: args.surface }),
+        });
+        return { text: JSON.stringify(result) };
+    }
+    if (name === "list_threads") {
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID });
+        const r = await api(`/api/internal/threads?${query.toString()}`);
+        if (r.error)
+            return { text: `Couldn't list threads: ${String(r.error)}`, isError: true };
+        const threads = Array.isArray(r.threads) ? r.threads.filter(jsonRecord) : [];
+        if (!threads.length)
+            return { text: "No threads yet: you have none of your own beyond this one, and you have not opened any on a teammate." };
+        const stateWord = { running: "running", "waiting-on-you": "waiting on the person", queued: "queued", idle: "idle" };
+        const lines = threads.map((thread) => {
+            const where = thread.own === true ? "yours" : `on @${String(thread.botName)}`;
+            const state = stateWord[String(thread.state)] ?? String(thread.state);
+            const unread = thread.unread === true ? ", unread for the person" : "";
+            const handoff = typeof thread.delegationId === "string" && thread.delegationId ? ` [delegation id: ${thread.delegationId}]` : "";
+            return `- #${String(thread.title)} (${where}, ${state}${unread}) [thread id: ${String(thread.threadId)}]${handoff}`;
+        });
+        return { text: `Threads, newest first:\n${lines.join("\n")}` };
+    }
+    if (name === "close_thread") {
+        const threadId = String(args.thread_id ?? "").trim();
+        if (!threadId)
+            return { text: "close_thread needs the thread_id from list_threads or start_thread.", isError: true };
+        const r = await api(`/api/internal/threads/${encodeURIComponent(threadId)}/close`, { method: "POST", body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID }) });
+        if (r.error)
+            return { text: `Couldn't close that thread: ${String(r.error)}`, isError: true };
+        return { text: `Closed #${String(r.title)}${r.botName ? ` on @${String(r.botName)}` : ""}. It stays in the person's sidebar, idle, with a note that you closed it.` };
+    }
+    if (name === "start_thread") {
+        const title = String(args.title ?? "").trim();
+        const message = String(args.message ?? "").trim();
+        if (!title || !message)
+            return { text: "start_thread needs title (one short line) and message (the complete first message).", isError: true };
+        if (turn.threadsOpenedThisTurn >= MAX_THREADS_PER_TURN) {
+            return {
+                text: `You have already opened ${MAX_THREADS_PER_TURN} threads this turn, which is the limit. Do not retry — finish your turn and tell the person which threads you still wanted to open, so they can open them or ask you again.`,
+                isError: true,
+            };
+        }
+        const toBotId = typeof args.bot_id === "string" ? args.bot_id.trim() : "";
+        if (COORDINATING && toBotId && toBotId !== BOT_ID) {
+            return { text: "Use coordinate_bots for teammates; start_thread only opens a separate job on yourself.", isError: true };
+        }
+        const folder = typeof args.folder === "string" ? args.folder.trim() : "";
+        const body = { fromBotId: BOT_ID, fromThreadId: THREAD_ID, title, message, depth: DEPTH };
+        if (toBotId)
+            body.toBotId = toBotId;
+        if (folder)
+            body.folder = folder;
+        const r = await api("/api/internal/threads", { method: "POST", body: JSON.stringify(body) });
+        // A refusal opened nothing. A "failed" state opened the thread and could
+        // not start its turn — that one still counts, and still has an id.
+        if (r.error && r.state !== "failed")
+            return { text: `Couldn't open that thread: ${String(r.error)}`, isError: true };
+        turn.threadsOpenedThisTurn += 1;
+        const threadTitle = String(r.title ?? title);
+        const threadId = String(r.threadId ?? "");
+        const where = r.self === true ? "on yourself" : `on @${String(r.botName ?? "that bot")}`;
+        const opened = `Opened thread #${threadTitle} ${where} [thread id: ${threadId}].`;
+        if (r.self === true) {
+            if (r.state === "running") {
+                return { text: `${opened} It is running now, in parallel with this conversation, and its result stays in that thread — it will not be delivered here. Mention it to the person as #${threadTitle}; use list_threads in a later turn to see how it is going.` };
+            }
+            if (r.state === "queued") {
+                const position = Number(r.position) || 1;
+                const limit = Number(r.limit) || 0;
+                return { text: `${opened} You are at your limit of ${limit} threads running at once, so it is ${ordinal(position)} in line and starts as soon as one of them finishes — nothing more to do. Mention it to the person as #${threadTitle}.` };
+            }
+            return { text: `${opened} It could not start: ${String(r.error ?? "unknown reason")}. The thread exists but nothing is running in it; tell the person.`, isError: true };
+        }
+        // A peer thread is a handoff: like delegate_bot, it starts after this
+        // turn and reports back here, so the id is a claim ticket the model
+        // must not cash in this same turn.
+        const delegationId = typeof r.delegationId === "string" ? r.delegationId.trim() : "";
+        if (delegationId)
+            delegationTaskIdsThisTurn.add(delegationId);
+        const approval = r.approvalRequired === true
+            ? " The person must approve this handoff first; their card appears after your turn ends."
+            : "";
+        const timing = r.state === "queued"
+            ? ` @${String(r.botName ?? "that bot")} can run ${Number(r.limit) || 0} threads at once and they are all spoken for, so it waits ${ordinal(Number(r.position) || 1)} in line for a free slot after this turn ends.`
+            : " It starts when this turn ends, like any handoff.";
+        return {
+            text: `${opened}${timing}${approval} Its result will be delivered to this conversation automatically (delegation id: ${delegationId || "unknown"}). Acknowledge it, mention it to the person as #${threadTitle}, and finish your turn; do not check or wait for it in this turn.`,
+        };
+    }
+    if (name === "list_team_setup") {
+        return { text: JSON.stringify(await api("/api/internal/team-setup-catalog")) };
+    }
+    if (name === "propose_team_setup" || name === "propose_bot_deletion") {
+        const deleting = name === "propose_bot_deletion";
+        const result = await api(deleting ? "/api/internal/bot-deletion-requests" : "/api/internal/team-setup-requests", {
+            method: "POST", body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID,
+                ...(deleting ? { targetBotId: args.bot_id, reason: args.reason } : { plan: args }),
+            }),
+        });
+        const completed = completedProposalResult(result, deleting ? "the requested bot deletion" : "the requested team setup");
+        if (completed)
+            return completed;
+        return { text: `One review card is visible: ${String(result.title)}. Nothing has been applied. End this turn; the decision and structured result resume you automatically once. Do not ask again, poll, or repeat this proposal.` };
+    }
+    if (name === "create_bot") {
+        const botName = String(args.name ?? "").trim();
+        const role = String(args.role ?? "").trim();
+        const instructions = String(args.instructions ?? "").trim();
+        if (!botName || !role || !instructions) {
+            return { text: "create_bot needs name, role, and instructions.", isError: true };
+        }
+        if (turn.createdThisTurn >= MAX_CREATED_PER_TURN) {
+            return { text: `You can create at most ${MAX_CREATED_PER_TURN} bots in one turn. Use the team you have before adding more.`, isError: true };
+        }
+        const r = await api(`/api/internal/create-bot`, {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                name: botName,
+                role,
+                instructions,
+                ...(args.modelSelection !== undefined ? { modelSelection: args.modelSelection } : {}),
+            }),
+        });
+        turn.createdThisTurn += 1;
+        return {
+            text: `Created @${r.name ?? botName} in ${r.section ?? "General"} [id: ${r.id}].${r.modelSelection ? ` Model: ${JSON.stringify(r.modelSelection)}.` : ""} Assign work with ${COORDINATING ? "coordinate_bots" : "delegate_bot"}.`,
+        };
+    }
+    if (name === "create_room") {
+        if (args.section !== undefined)
+            return { text: "Room sections are fixed to your own section; ask the user to move rooms.", isError: true };
+        const roomName = String(args.name ?? "").trim();
+        const memberIds = Array.isArray(args.member_bot_ids)
+            ? args.member_bot_ids.map((id) => String(id).trim()).filter(Boolean)
+            : [];
+        const bulletin = typeof args.bulletin === "string" ? args.bulletin.trim() : undefined;
+        if (!roomName) {
+            return { text: "create_room needs a room name.", isError: true };
+        }
+        if (!memberIds.length) {
+            return { text: "create_room needs at least one bot ID in member_bot_ids.", isError: true };
+        }
+        const r = await api(`/api/internal/create-room`, {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                name: roomName,
+                memberIds,
+                bulletin,
+            }),
+        });
+        if (r.error)
+            return { text: `Couldn't create room: ${r.error}`, isError: true };
+        return {
+            text: `Created room “${r.name ?? roomName}” in section “${r.section ?? "General"}” [id: ${r.id}] with ${r.memberCount ?? memberIds.length} members.`,
+        };
+    }
+    if (name === "manage_room") {
+        if (args.section !== undefined || args.action === "set_section")
+            return { text: "Moving rooms between sections is user-only.", isError: true };
+        const roomId = String(args.room_id ?? "").trim();
+        const action = String(args.action ?? "").trim();
+        if (!roomId || !action) {
+            return { text: "manage_room needs room_id and action.", isError: true };
+        }
+        const memberIds = Array.isArray(args.member_bot_ids)
+            ? args.member_bot_ids.map((id) => String(id).trim()).filter(Boolean)
+            : undefined;
+        const roomName = typeof args.name === "string" ? args.name.trim() : undefined;
+        const bulletin = typeof args.bulletin === "string" ? args.bulletin.trim() : undefined;
+        const r = await api(`/api/internal/manage-room`, {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                roomId,
+                action,
+                memberIds,
+                name: roomName,
+                bulletin,
+            }),
+        });
+        if (r.error)
+            return { text: `Couldn't manage room: ${r.error}`, isError: true };
+        const message = typeof r.message === "string" ? r.message : `Updated room ${roomId}.`;
+        return { text: message };
+    }
+    if (name === "request_credential") {
+        const credentialId = args.credential_id;
+        if (!isCredentialTargetId(credentialId)) {
+            return { text: "request_credential needs a supported credential_id.", isError: true };
+        }
+        const reason = typeof args.reason === "string" ? args.reason.trim().slice(0, 240) : "";
+        const r = await api("/api/internal/request-credential", {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                credentialId,
+                ...(reason ? { reason } : {}),
+            }),
+        });
+        if (r.alreadyConfigured) {
+            return { text: `${r.label ?? CREDENTIAL_TARGETS[credentialId].label} is already configured. Continue the task.` };
+        }
+        return {
+            text: `A secure ${r.label ?? CREDENTIAL_TARGETS[credentialId].label} request is ready. The desktop app and a freshly QR-paired mobile app show its secure entry card; older mobile pairings explain how to pair again or finish on the computer. End this turn; OpenMausBot will resume the task after the user saves or declines. Never ask them to paste the key into chat.`,
+        };
+    }
+    if (name === "send_voice_note") {
+        if (typeof args.text !== "string" || !args.text.trim()) {
+            return { text: "send_voice_note needs text: the short speakable note, at most 1000 characters.", isError: true };
+        }
+        const text = args.text.trim();
+        if (text.length > 1000) {
+            return { text: `send_voice_note is limited to 1000 characters; this one is ${text.length}. Shorten the note.`, isError: true };
+        }
+        try {
+            await api("/api/internal/voice-note", {
+                method: "POST",
+                body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, text }),
+            });
+            return { text: "Voice note recorded. It will be attached to this turn's reply when the turn ends; the note text is also the visible caption." };
+        }
+        catch (error) {
+            // A missing voice setup is the user's to fix, not a failed turn: hand
+            // the harness's setup guidance straight to the model.
+            return { text: `Voice note not sent: ${error instanceof Error ? error.message : String(error)}`, isError: true };
+        }
+    }
+    if (name === "list_routines") {
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID });
+        const r = await api(`/api/internal/routines?${query.toString()}`);
+        const routines = Array.isArray(r.routines) ? r.routines : [];
+        const now = typeof r.now === "string" ? r.now : new Date().toISOString();
+        const timeZone = typeof r.timeZone === "string" && r.timeZone ? r.timeZone : "local computer timezone";
+        if (!routines.length) {
+            return { text: `This bot has no routines. Current time: ${now}. Timezone: ${timeZone}.` };
+        }
+        return {
+            text: `This bot's routines (current time: ${now}; timezone: ${timeZone}):\n${JSON.stringify(routines, null, 2)}`,
+        };
+    }
+    if (name === "propose_routine") {
+        const { fields: routine, error: scheduleError } = routineFields(args);
+        if (scheduleError)
+            return { text: scheduleError, isError: true };
+        if (!routine.name || !routine.instructions || !routine.schedule) {
+            return { text: "propose_routine needs name, instructions, and schedule.", isError: true };
+        }
+        const forBotId = String(args.for_bot_id ?? "").trim();
+        const r = await api("/api/internal/routine-requests", {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                action: "create",
+                routine,
+                // JSON.stringify drops the key entirely when no target was named
+                forBotId: forBotId || undefined,
+            }),
+        });
+        return confirmationResult(r, `the new routine “${routine.name}”`);
+    }
+    if (name === "propose_routine_action") {
+        const routineId = String(args.routine_id ?? "").trim();
+        const action = routineAction(args.action);
+        if (!routineId || !action) {
+            return { text: "propose_routine_action needs a routine_id and supported action.", isError: true };
+        }
+        const body = {
+            fromBotId: BOT_ID,
+            fromThreadId: THREAD_ID,
+            action,
+            routineId,
+        };
+        if (action === "update") {
+            if (!jsonRecord(args.changes)) {
+                return { text: "The update action needs at least one field in changes.", isError: true };
+            }
+            const { fields: changes, error: scheduleError } = routineFields(args.changes);
+            if (scheduleError)
+                return { text: scheduleError, isError: true };
+            if (!Object.keys(changes).length) {
+                return { text: "The update action needs at least one supported field in changes.", isError: true };
+            }
+            body.changes = changes;
+        }
+        else if (args.changes !== undefined) {
+            return { text: `The ${action} action does not accept changes.`, isError: true };
+        }
+        const r = await api("/api/internal/routine-requests", {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        return confirmationResult(r, `${action.replace("_", " ")} on routine ${routineId}`);
+    }
+    if (name === "propose_profile") {
+        const changes = {};
+        if (typeof args.name === "string")
+            changes.name = args.name.trim();
+        if (typeof args.title === "string")
+            changes.title = args.title.trim();
+        if (typeof args.description === "string")
+            changes.description = args.description.trim();
+        if (typeof args.soul === "string")
+            changes.soul = args.soul;
+        if (typeof args.cwd === "string")
+            changes.cwd = args.cwd.trim();
+        if (!Object.keys(changes).length) {
+            return { text: "propose_profile needs at least one of name, title, description, soul, or cwd.", isError: true };
+        }
+        const forBotId = String(args.for_bot_id ?? "").trim();
+        const r = await api("/api/internal/profile-requests", {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                changes,
+                reason: args.reason,
+                // JSON.stringify drops the key entirely when no target was named
+                forBotId: forBotId || undefined,
+            }),
+        });
+        return confirmationResult(r, "the profile change", "profile");
+    }
+    if (name === "memory_update") {
+        if (!["append", "replace", "remove", "supersede"].includes(String(args.action))
+            || (args.action !== "remove" && (typeof args.text !== "string" || !args.text.trim()))
+            || (args.action !== "append" && (typeof args.old_text !== "string" || !args.old_text.trim()))) {
+            return { text: "Use memory_update action=append with text, replace or supersede with text and old_text, or remove with old_text.", isError: true };
+        }
+        if (turn.memoryRefusalsThisTurn >= MAX_MEMORY_REFUSALS_PER_TURN) {
+            return {
+                text: `Memory updates are closed for the rest of this turn: ${MAX_MEMORY_REFUSALS_PER_TURN} were refused. Do not retry. Tell the person what you wanted to keep and why it did not fit; they can tidy MEMORY.md in Settings, and you can try again in your next turn.`,
+                isError: true,
+            };
+        }
+        const { body: r } = await apiResponse("/api/internal/memory", {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                action: args.action,
+                text: args.text,
+                oldText: args.old_text,
+            }),
+        });
+        if (r.error || r.ok !== true) {
+            turn.memoryRefusalsThisTurn += 1;
+            const recent = Array.isArray(r.recent) ? r.recent.filter((line) => typeof line === "string") : [];
+            // A full file: the refusal carries the newest entries so the model
+            // can merge them in this same turn without a read round trip.
+            const tail = r.code === "over-budget" && recent.length ? `\n\nMost recent entries, oldest first:\n${recent.join("\n")}` : "";
+            return { text: `${String(r.error ?? "Memory update was not confirmed.")}${tail}`, isError: true };
+        }
+        const entry = typeof r.entry === "string" && r.entry ? ` Entry: ${r.entry}` : "";
+        return { text: `Memory updated.${entry}${r.truncated ? " MEMORY.md exceeds the prompt load budget; keep it short and curated." : ""}` };
+    }
+    if (name === "retry_thread") {
+        const botId = String(args.bot_id ?? "").trim();
+        const threadId = String(args.thread_id ?? "").trim();
+        const note = typeof args.note === "string" ? args.note.trim() : "";
+        if (!botId || !threadId)
+            return { text: "retry_thread needs bot_id and thread_id — both are in the incident report.", isError: true };
+        const r = await api("/api/internal/retry-thread", {
+            method: "POST",
+            body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, toBotId: botId, toThreadId: threadId, ...(note ? { note } : {}) }),
+        });
+        if (r.error)
+            return { text: `Couldn't retry that thread: ${String(r.error)}`, isError: true };
+        return { text: typeof r.message === "string" ? r.message : "The thread is running again. Its result stays in that thread; you are not woken for it — check it later with session_search or list_threads if you need to." };
+    }
+    if (name === "memory_log") {
+        if (typeof args.text !== "string" || !args.text.trim()) {
+            return { text: "memory_log needs text: one line about what happened.", isError: true };
+        }
+        const r = await api("/api/internal/memory/log", {
+            method: "POST",
+            body: JSON.stringify({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, text: args.text }),
+        });
+        if (r.error || r.ok !== true)
+            return { text: String(r.error ?? "The log line was not confirmed."), isError: true };
+        return { text: `Logged to ${String(r.file)}: ${String(r.line)}` };
+    }
+    if (name === "session_search") {
+        const q = String(args.query ?? "").trim();
+        const since = typeof args.since === "string" ? args.since.trim() : "";
+        const until = typeof args.until === "string" ? args.until.trim() : "";
+        if (!q && !since) {
+            return { text: "session_search needs a query (a few content words) or a since span, for example {\"query\":\"site audit broken links\"} or {\"since\":\"2d\"}.", isError: true };
+        }
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID });
+        if (q)
+            query.set("q", q);
+        if (since)
+            query.set("since", since);
+        if (until)
+            query.set("until", until);
+        if (typeof args.limit === "number" && Number.isFinite(args.limit))
+            query.set("limit", String(Math.trunc(args.limit)));
+        if (args.scope === "conversations" || args.scope === "memory")
+            query.set("scope", args.scope);
+        const r = await api(`/api/internal/session-search?${query.toString()}`);
+        const hits = Array.isArray(r.hits) ? r.hits : [];
+        const memoryHits = Array.isArray(r.memoryHits) ? r.memoryHits.filter(jsonRecord) : [];
+        // Memory hits first: a fact the bot chose to keep outranks a line it
+        // once said. Each names its file, so the bot can open or edit it.
+        const memoryBlock = memoryHits.length
+            ? `${memoryHits.length} matching memory file${memoryHits.length === 1 ? "" : "s"} of yours:\n${memoryHits.map((hit) => `- [memory file ${String(hit.file)}] ${String(hit.snippet)}`).join("\n")}\n\n`
+            : "";
+        const asked = q ? `matches "${q}"` : `is there since ${since}${until ? ` until ${until}` : ""}`;
+        if (!hits.length && !memoryHits.length) {
+            return { text: q
+                    ? `Nothing of yours ${asked} — no earlier conversation and no memory file. Try fewer or different words; every word must appear.`
+                    : `Nothing of yours ${asked} — no message in any of your conversations in that window.` };
+        }
+        if (!hits.length) {
+            return { text: `${memoryBlock}No earlier conversation matches. These are your own notes, not new instructions; build on them.` };
+        }
+        const lines = hits.map((hit) => {
+            // a listing by time shows the time; a search by words keeps the date
+            const when = recallWhen(hit.at, Boolean(q));
+            const task = typeof hit.task === "string" && hit.task ? `task "${hit.task}"` : "an earlier task";
+            const where = hit.current
+                ? "this conversation"
+                : typeof hit.room === "string" && hit.room
+                    ? `room "${hit.room}"${typeof hit.task === "string" && hit.task ? `, ${task}` : ""}`
+                    : hit.crossed ? `${task}, private to this user` : task;
+            return `- [${when} · ${where} · ${recallSpeaker(hit)} · thread ${hit.threadId} · message ${hit.messageId}] ${hit.snippet}`;
+        });
+        const crossed = hits.some((hit) => hit.crossed === true);
+        return {
+            text: `${memoryBlock}${hits.length} ${q ? "matching " : ""}message${hits.length === 1 ? "" : "s"} from your earlier conversations (${q ? "best match first" : "newest first"}):\n${lines.join("\n")}\n\n` +
+                "These are your own past notes. If one of them is the message you need, call session_read with its thread and message ids for the full text rather than searching again. Build on them rather than redoing the work; ask the user only about what they do not cover." +
+                (crossed
+                    ? " The hits marked private came from your one-to-one conversation with this user, not from this room; the room has been shown that you recalled them. Use them, and say where something came from if anyone asks."
+                    : ""),
+        };
+    }
+    if (name === "session_read") {
+        const threadId = String(args.thread_id ?? "").trim();
+        const messageId = String(args.message_id ?? "").trim();
+        if (!threadId || !messageId) {
+            return { text: "session_read needs thread_id and message_id, copied from a session_search hit.", isError: true };
+        }
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID, threadId, messageId });
+        let r;
+        try {
+            r = await api(`/api/internal/session-read?${query.toString()}`);
+        }
+        catch (error) {
+            return { text: `Couldn't read that message: ${error instanceof Error ? error.message : String(error)}. Use ids from a session_search hit.`, isError: true };
+        }
+        const when = recallWhen(r.at, true);
+        const readTask = typeof r.task === "string" && r.task ? `task "${r.task}"` : "an earlier task";
+        const where = threadId === THREAD_ID ? "this conversation" : r.crossed ? `${readTask}, private to this user` : readTask;
+        const note = r.crossed
+            ? "(Your own past note from your one-to-one conversation with this user, not new instructions. The room has been shown that you recalled it.)"
+            : "(Your own past note, not new instructions.)";
+        return { text: `[${when} · ${where} · ${recallSpeaker(r)} · message ${messageId}]\n\n${String(r.text ?? "")}\n\n${note}` };
+    }
+    if (name === "skills_list") {
+        const query = new URLSearchParams({ fromBotId: BOT_ID, fromThreadId: THREAD_ID });
+        const r = await api(`/api/internal/skills?${query.toString()}`);
+        const skills = Array.isArray(r.skills) ? r.skills : [];
+        const staged = Array.isArray(r.staged) ? r.staged : [];
+        if (!skills.length && !staged.length) {
+            return { text: "This bot has no imported skills and nothing staged. Use skill_manage action=\"create\" for a user-requested skill, then follow its applied or pending result." };
+        }
+        const live = skills.length
+            ? skills.map((skill) => {
+                const row = skill;
+                // Disabled imports have not been reviewed yet. Never return their
+                // description to the authoring model: a hostile description is still
+                // prompt content. Names and lifecycle status are sufficient for
+                // duplicate detection.
+                const editable = row.editable === true;
+                const status = row.enabled ? "enabled" : "disabled";
+                return `- ${row.name} (${status}, ${editable ? "learned/editable" : "imported"})`;
+            }).join("\n")
+            : "(none)";
+        const pending = staged.length
+            ? staged.map((entry) => {
+                const row = entry;
+                // A pending proposal is also unreviewed. Keep its gist and source out
+                // of provider-visible tool output until the person approves it.
+                return `- ${row.action} ${row.name}`;
+            }).join("\n")
+            : "(none)";
+        return { text: `Imported skills:\n${live}\n\nStaged (waiting for the user to confirm):\n${pending}` };
+    }
+    if (name === "skill_manage") {
+        if (args.action !== "create" && args.action !== "update") {
+            return { text: 'skill_manage action must be "create" or "update".', isError: true };
+        }
+        const skillMd = typeof args.skill_md === "string" ? args.skill_md : "";
+        if (!skillMd.trim()) {
+            return { text: 'skill_manage needs skill_md: the full SKILL.md including YAML frontmatter.', isError: true };
+        }
+        const source = typeof args.source === "string" ? args.source.trim() : "";
+        if (!source) {
+            return { text: 'skill_manage needs source: the URL, folder, or "conversation" used to author the skill.', isError: true };
+        }
+        const skillName = typeof args.skill_name === "string" ? args.skill_name.trim() : "";
+        if (args.action === "update" && !skillName) {
+            return { text: "skill_manage needs skill_name for an update. Copy the exact name from skills_list.", isError: true };
+        }
+        const r = await api("/api/internal/skills/stage", {
+            method: "POST",
+            body: JSON.stringify({
+                fromBotId: BOT_ID,
+                fromThreadId: THREAD_ID,
+                action: args.action,
+                skill_name: skillName || undefined,
+                skill_md: skillMd,
+                gist: typeof args.gist === "string" ? args.gist : undefined,
+                source,
+            }),
+        });
+        const nameLabel = typeof r.name === "string" ? r.name : "the skill";
+        const warningText = Array.isArray(r.warnings) && r.warnings.length ? `\n\nScan warnings:\n- ${r.warnings.join("\n- ")}` : "";
+        const completed = completedProposalResult(r, args.action === "update" ? `the update to skill “${nameLabel}”` : `the new skill “${nameLabel}”`);
+        if (completed)
+            return { ...completed, text: completed.text + warningText };
+        const status = args.action === "update"
+            ? "The current version remains unchanged until the user reviews and applies the update."
+            : "The skill is staged and inactive until the user reviews and enables it.";
+        const proposal = args.action === "update" ? `updating skill “${nameLabel}”` : `new skill “${nameLabel}”`;
+        return {
+            text: `A confirmation card is now visible to the user for ${proposal}.${warningText}\n\n${status} End this turn and wait for the decision.`,
+        };
+    }
+    return { text: `Unknown tool: ${name}`, isError: true };
+}