@ouro.bot/cli 0.1.0-alpha.94 → 0.1.0-alpha.940

package/dist/repertoire/tools-shell.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shellToolDefinitions = void 0;
+const child_process_1 = require("child_process");
+const shell_sessions_1 = require("./shell-sessions");
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const tool_arguments_1 = require("./tool-arguments");
+function shellOwner(ctx) {
+    (0, tool_arguments_1.assertRelationshipToolOwner)(ctx);
+    const agentName = ctx?.agentName ?? (0, identity_1.getAgentName)();
+    return { agentName, agentRoot: ctx?.agentRoot ?? (0, identity_1.getAgentRoot)(agentName) };
+}
+exports.shellToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "shell",
+                description: "Run a shell command and return stdout/stderr. Each call starts in the runtime's working directory; cd does not persist between calls. Use dedicated tools instead of shell when available: read_file instead of cat, edit_file instead of sed, glob instead of find, grep instead of grep/rg. Reserve shell for operations that genuinely need the shell: installing packages, running builds/tests, git operations, process management. Be careful with destructive commands -- consider reversibility before running. If a command fails, read the error output before retrying with a different approach.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        command: { type: "string" },
+                        timeout_ms: {
+                            type: "number",
+                            description: "Timeout in milliseconds. Default: 30000. Max: 600000.",
+                        },
+                        background: {
+                            type: "boolean",
+                            description: "Run in background and return immediately with a process ID. Records belong to the initiating agent and live only in process memory. Use separately authorized shell_status/shell_tail calls to monitor. Revocation does not kill a started process; runtime restart loses its record.",
+                        },
+                    },
+                    required: ["command"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        approvalPolicy: (args) => {
+            const command = typeof args.command === "string" ? args.command.trim().split(/\s+/) : [];
+            if (command[0] === "docker" && command[1] === "restart" && command.length > 2) {
+                return {
+                    kind: "required",
+                    policyId: "shell.docker-lifecycle.v1",
+                    actionClass: "service-control",
+                    requiresSoleCall: true,
+                };
+            }
+            return { kind: "not_required" };
+        },
+        handler: async (a, ctx) => {
+            (0, tool_arguments_1.assertRelationshipToolOwner)(ctx);
+            // Destructive pattern detection (friction, not a block)
+            const destructivePatterns = (0, shell_sessions_1.detectDestructivePatterns)(a.command);
+            if (destructivePatterns.length > 0) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    event: "tool.shell.destructive_detected",
+                    component: "tools",
+                    message: `destructive pattern detected: ${destructivePatterns.join(", ")}`,
+                    meta: { command: a.command, patterns: destructivePatterns },
+                });
+            }
+            // Background mode: spawn and return immediately
+            if (a.background === true) {
+                const session = (0, shell_sessions_1.spawnBackgroundShell)(a.command, shellOwner(ctx));
+                return JSON.stringify({ id: session.id, command: session.command, status: session.status });
+            }
+            const MAX_TIMEOUT = 600000;
+            const requestedTimeout = Number(a.timeout_ms) || 0;
+            let configDefault = 30000;
+            const owner = ctx?.agentName !== undefined || ctx?.agentRoot !== undefined ? shellOwner(ctx) : undefined;
+            try {
+                configDefault = (0, identity_1.loadAgentConfig)(owner).shell?.defaultTimeout ?? 30000;
+            }
+            catch (error) {
+                if (owner)
+                    throw error;
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn", component: "tools", event: "tool.shell_config_unavailable",
+                    message: "legacy shell caller has no configuration; using the default timeout",
+                    meta: { fallbackTimeout: configDefault },
+                });
+            }
+            const baseTimeout = requestedTimeout > 0 ? requestedTimeout : configDefault;
+            const timeout = Math.min(baseTimeout, MAX_TIMEOUT);
+            const output = await new Promise((resolve, reject) => {
+                const child = (0, child_process_1.exec)(a.command, { encoding: "utf-8", timeout }, (error, stdout, stderr) => {
+                    if (error)
+                        reject(Object.assign(error, { stdout, stderr }));
+                    else
+                        resolve(stdout);
+                });
+                child.stdin?.end();
+            });
+            if (destructivePatterns.length > 0) {
+                return `${output}\n\n--- destructive pattern detected: ${destructivePatterns.join(", ")} ---`;
+            }
+            return output;
+        },
+        summaryKeys: ["command"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "shell_status",
+                description: "Check separately authorized status of background shell processes owned by this agent. Omit id to list this agent's records. Records live only in process memory; runtime restart loses observability, and revoked access does not kill a started process.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Background shell process ID" },
+                    },
+                },
+            },
+        },
+        handler: (a, ctx) => {
+            if (!a.id) {
+                return JSON.stringify((0, shell_sessions_1.listShellSessions)(shellOwner(ctx)));
+            }
+            const session = (0, shell_sessions_1.getShellSession)(a.id, shellOwner(ctx));
+            if (!session)
+                return `process not found: ${a.id}`;
+            return JSON.stringify(session);
+        },
+        summaryKeys: ["id"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "shell_tail",
+                description: "Show recent output from a background shell process owned by this agent. Access is reauthorized on each call. Revocation does not kill a started process, and runtime restart loses the in-memory record.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Background shell process ID" },
+                    },
+                    required: ["id"],
+                },
+            },
+        },
+        handler: (a, ctx) => {
+            /* v8 ignore next -- schema requires id, defensive guard @preserve */
+            if (!a.id)
+                return "id is required";
+            const output = (0, shell_sessions_1.tailShellSession)(a.id, shellOwner(ctx));
+            if (output === undefined)
+                return `process not found: ${a.id}`;
+            return output || "(no output yet)";
+        },
+        summaryKeys: ["id"],
+    },
+];

package/dist/repertoire/tools-shepherd-guidance.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shepherdGuidanceToolDefinitions = void 0;
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const node_crypto_1 = require("node:crypto");
+const shepherd_config_1 = require("../heart/shepherd-config");
+const host_1 = require("../senses/shepherd/host");
+const guidance_1 = require("../senses/shepherd/guidance");
+const redact_1 = require("../senses/shepherd/redact");
+const returns_1 = require("../senses/shepherd/returns");
+const notice_outbox_1 = require("../senses/shepherd/notice-outbox");
+const target_binding_1 = require("../senses/shepherd/target-binding");
+const tools_base_1 = require("./tools-base");
+const runtime_1 = require("../nerves/runtime");
+const text = (value) => typeof value === "string" ? value.trim() : "";
+const json = (value) => JSON.stringify(value, (_key, item) => typeof item === "string" ? (0, redact_1.redactSecrets)(item) : item);
+const stringProperty = (description) => ({ type: "string", description });
+const targetProperties = {
+    host: stringProperty("Host name from history, when known. Never invent a host."),
+    session: stringProperty("Stable session ID from history, or a live session ID/ref from shepherd_overview."),
+};
+const requestProperty = { request_id: stringProperty("Unique request ID for this human instruction. Reuse it only to retry the identical request.") };
+function fingerprint(name, args) {
+    const body = JSON.stringify({ name, args }, (_key, value) => value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value);
+    return (0, node_crypto_1.createHash)("sha256").update(body).digest("hex");
+}
+/**
+ * Resolve history without a terminal connection, including vanished sessions. Only a session with no history needs
+ * the existing machine connection primitives. Resolving it never reads a screen, signals, presses a key or sends.
+ */
+async function targetFor(ctx, args) {
+    const session = text(args.session) || ctx.currentShepherdSurface?.id || "";
+    const hostName = text(args.host) || ctx.currentShepherdSurface?.host || "";
+    if (session)
+        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, session, hostName || undefined);
+    const records = (0, returns_1.readReturns)(ctx.agentRoot);
+    const returnId = text(args.return_id);
+    if (returnId) {
+        const record = records.find(r => (0, guidance_1.shepherdReturnId)(r) === returnId);
+        if (!record)
+            throw new Error("Shepherd return ID not found");
+        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, record.session, record.host);
+        if ((text(args.host) && text(args.host) !== record.host) || (text(args.session) && text(args.session) !== record.session))
+            throw new Error("target does not match the recorded return");
+        return { target: { host: record.host, session: record.session, cwd: record.cwd, task: record.task }, live: [] };
+    }
+    if (!session)
+        throw new Error("name a session from Shepherd history or overview");
+    const matching = records.filter(r => r.session === session && (!hostName || r.host === hostName));
+    if (new Set(matching.map(r => r.host)).size > 1)
+        throw new Error("session is ambiguous across hosts; name its host");
+    const record = matching.at(-1);
+    if (record) {
+        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, record.session, record.host);
+        return { target: { host: record.host, session, cwd: record.cwd, task: record.task }, live: [] };
+    }
+    const machine = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(ctx.agentName);
+    const resolved = (0, shepherd_config_1.resolveShepherdConnection)(ctx.agentName, machine.ok ? machine.config : {});
+    if (!resolved.ok)
+        throw new Error(resolved.error);
+    const host = (0, host_1.createShepherdHost)(resolved.connection, { agentName: ctx.agentName });
+    const sessions = await host.list();
+    const live = sessions.map(s => ({ host: host.name, session: s.id, cwd: s.cwd ?? null, task: null }));
+    const found = sessions.find(s => s.id === session || s.ref === session);
+    if (!found || (hostName && hostName !== host.name))
+        throw new Error("unknown session on the configured Shepherd host");
+    (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, found.id, host.name);
+    return { target: live.find(t => t.session === found.id), live };
+}
+function definition(name, description, properties, required, run, mutates = false) {
+    return {
+        tool: { type: "function", function: { name, description, parameters: { type: "object", properties, required, additionalProperties: false } } },
+        handler: async (args, ctx) => {
+            // Same real-family gate as shepherd_send, including rejection of the private runtime's family self.
+            const friend = ctx?.context?.friend;
+            if (!friend || friend.trustLevel !== "family" || !friend.id || friend.id === tools_base_1.SELF_FRIEND_ID)
+                return json({ error: "Shepherd private guidance is only for a real family member in this conversation" });
+            if (!ctx?.agentRoot || !ctx.agentName)
+                return json({ error: "Shepherd guidance needs an agent runtime" });
+            try {
+                const boundDefault = name === "shepherd_correct" && !text(args.session) && !text(args.return_id) && ctx.currentShepherdSurface;
+                const request = { actorId: friend.id, requestId: text(args.request_id), requestFingerprint: fingerprint(name, boundDefault ? { ...args, session: boundDefault.id, host: boundDefault.host } : args) };
+                if (mutates) {
+                    const prior = (0, guidance_1.readGuidance)(ctx.agentRoot).requests.find(r => r.actorId === request.actorId && r.requestId === request.requestId);
+                    if (prior) {
+                        if (prior.requestFingerprint !== request.requestFingerprint)
+                            throw new Error("request ID was already used with a different body");
+                        return json(prior.receipt);
+                    }
+                }
+                const result = await run(args, ctx, request);
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.shepherd_guidance_tool", message: "executed a private Shepherd guidance tool", meta: { tool: name, mutates } });
+                return json(result);
+            }
+            catch (error) {
+                const message = (0, redact_1.redactSecrets)(error instanceof Error ? error.message : String(error));
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_guidance_tool_error", message: "private Shepherd guidance tool failed", meta: { tool: name, error: "private_guidance_operation_failed" } });
+                return json({ error: message });
+            }
+        },
+        summaryKeys: [],
+        riskProfile: mutates ? { mutates: "durable_state_write", risk: "high", reason: "changes private operator preferences or the automatic-reply pause" } : { mutates: "none", risk: "low" },
+    };
+}
+exports.shepherdGuidanceToolDefinitions = [
+    definition("shepherd_history", "Read private Shepherd return history with stable return IDs, actual judgment/reply/outcome and your own ownerNotice receipts when tracked. Historical, not current status; a vanished terminal remains readable. The session filter is a stable ID, not a short ref. Use to understand 'that was wrong because...' before correcting it, or to check whether a notice was sent. Use displayId as the human-facing return label; never invent a shortened ID suffix. Mutations require the exact full id, not displayId. ownerNotice.state sent means transport acceptance, not proof the human read it; pending awaits a safe retry; unknown may already have arrived and must not be blindly replayed. messageId is the activity ID returned by transport. ownerNotice null means no receipt recorded for this recipient, not proof of non-delivery. ownerNoticeError explicitly identifies unavailable receipt evidence. Never types into a terminal.", targetProperties, [], async (args, ctx, request) => {
+        const session = text(args.session) || ctx.currentShepherdSurface?.id;
+        const host = text(args.host) || ctx.currentShepherdSurface?.host;
+        if (session)
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, session, host);
+        const returns = (0, returns_1.readReturns)(ctx.agentRoot)
+            .filter(r => (!session || r.session === session) && (!host || r.host === host))
+            .map(record => {
+            const id = (0, guidance_1.shepherdReturnId)(record);
+            return { ...record, id, displayId: id.slice("return:".length, "return:".length + 8) };
+        });
+        try {
+            const notices = (0, notice_outbox_1.readNoticeOutbox)(ctx.agentRoot);
+            for (const record of returns) {
+                const notice = (0, notice_outbox_1.knownNotice)(ctx.agentRoot, (0, notice_outbox_1.noticeRecordId)(record), notices);
+                if (notice)
+                    record.ownerNotice = Object.hasOwn(notice.deliveries, request.actorId) ? notice.deliveries[request.actorId] : null;
+            }
+            return { returns };
+        }
+        catch (error) {
+            const message = (0, redact_1.redactSecrets)(error instanceof Error ? error.message : String(error));
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_notice_history_error", message: "owner notice receipt evidence is unavailable; return history remains readable", meta: { error: "notice_receipts_unavailable" } });
+            return { returns, ownerNoticeError: message };
+        }
+    }),
+    definition("shepherd_correct", "Record the human's post-action correction ('that was wrong because…') or prospective instruction. Optionally learn a principle for 'in future…'. A return_id must name a real history entry; omit it for a prospective instruction, never fabricate one. Session scope is the default; project is the exact recorded folder and optional task; global only when the human deliberately generalizes. Feedback <=2000 characters; principle <=1000; at most 20 active rules. This is not an approval gate and never sends anything. For requested immediate steering use existing shepherd_send.", {
+        ...targetProperties, ...requestProperty,
+        return_id: stringProperty("Real stable return ID from shepherd_history, if correcting an actual judgment."),
+        feedback: stringProperty("The human's explanation or prospective instruction, at most 2000 characters."),
+        principle: stringProperty("Optional scoped future preference, at most 1000 characters."),
+        scope: { type: "string", enum: ["session", "project", "global"], description: "Default session. Choose global only when the human expressed generalization." },
+    }, ["request_id", "feedback"], async (args, ctx, request) => {
+        const { target, live } = await targetFor(ctx, args);
+        return (0, guidance_1.recordShepherdCorrection)(ctx.agentRoot, {
+            ...request, target, feedback: typeof args.feedback === "string" ? args.feedback : "",
+            ...(args.return_id !== undefined ? { returnId: text(args.return_id) } : {}),
+            ...(args.principle !== undefined ? { principle: typeof args.principle === "string" ? args.principle : "" } : {}),
+            ...(args.scope !== undefined ? { scope: args.scope } : {}),
+        }, live);
+    }, true),
+    definition("shepherd_guidance", "Inspect what Shepherd learned ('what did you learn?'). With a session, returns revision, pause and applicable active principles with IDs, scopes and operator provenance. Omit session to inspect all active principles and pauses, including their exact targets. No send.", targetProperties, [], async (args, ctx) => {
+        if (args.session === undefined && !ctx.currentShepherdSurface) {
+            const state = (0, guidance_1.readGuidance)(ctx.agentRoot);
+            return { revision: state.revision, principles: state.principles.filter(p => p.active), pauses: state.pauses.filter(p => p.paused) };
+        }
+        const { target } = await targetFor(ctx, args);
+        return (0, guidance_1.applicableGuidance)((0, guidance_1.readGuidance)(ctx.agentRoot), target);
+    }),
+    definition("shepherd_update_principle", "Change a learned preference ('change that') by its principle ID. Keeps its existing scope, never silently generalizes it. No send.", {
+        ...requestProperty, principle_id: stringProperty("Active principle ID from shepherd_guidance."), text: stringProperty("Replacement preference, nonempty and at most 1000 characters."),
+    }, ["request_id", "principle_id", "text"], async (args, ctx, request) => (0, guidance_1.updateShepherdPrinciple)(ctx.agentRoot, {
+        ...request, principleId: text(args.principle_id), text: typeof args.text === "string" ? args.text : "",
+    }), true),
+    definition("shepherd_forget_principle", "Forget a learned preference ('forget that') by its ID. Removes only that preference from future judgments but retains the private operator trail. Built-in judgment policy, including legitimate outside dependency waits, and all existing guards remain unchanged: forgetting does not make dependency waits premature or delivered done. No send.", {
+        ...requestProperty, principle_id: stringProperty("Active principle ID from shepherd_guidance."),
+    }, ["request_id", "principle_id"], async (args, ctx, request) => (0, guidance_1.forgetShepherdPrinciple)(ctx.agentRoot, {
+        ...request, principleId: text(args.principle_id),
+    }), true),
+    ...["pause", "resume"].map(action => definition(`shepherd_${action}`, action === "pause" ? "Leave this one alone: pause automatic Shepherd replies for this session only, durably. Independent judgment/owner notices remain. Never interrupts or types into the terminal."
+        : "Resume automatic Shepherd replies for this paused session. All focus, screen, syntax and loop guards still apply; resume is not an immediate send.", { ...targetProperties, ...requestProperty }, ["session", "request_id"], async (args, ctx, request) => {
+        const { target, live } = await targetFor(ctx, args);
+        return (0, guidance_1.setShepherdSessionPause)(ctx.agentRoot, { ...request, target, paused: action === "pause" }, live);
+    }, true)),
+];

package/dist/repertoire/tools-shepherd.js

@@ -0,0 +1,296 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shepherdToolDefinitions = exports.shepherdSendToolDefinition = exports.shepherdSignalToolDefinition = exports.shepherdReadToolDefinition = exports.shepherdOverviewToolDefinition = exports.SEND_KEYS = exports.SEND_TEXT_MAX_CHARS = void 0;
+exports.shepherdToolsEnabled = shepherdToolsEnabled;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const shepherd_config_1 = require("../heart/shepherd-config");
+const runtime_1 = require("../nerves/runtime");
+const host_1 = require("../senses/shepherd/host");
+const redact_1 = require("../senses/shepherd/redact");
+const returns_1 = require("../senses/shepherd/returns");
+const tools_base_1 = require("./tools-base");
+const tools_shepherd_guidance_1 = require("./tools-shepherd-guidance");
+const guidance_1 = require("../senses/shepherd/guidance");
+const target_binding_1 = require("../senses/shepherd/target-binding");
+const agent_presentation_1 = require("../senses/shepherd/agent-presentation");
+/**
+ * Shepherd's tools: every coding-agent session on this machine's terminal host with a current screen
+ * and what Shepherd last decided about it (`shepherd_overview`), a deeper read (`shepherd_read`), a status
+ * line or notification for the human (`shepherd_signal`), and a line or key typed for the human
+ * who asked for it (`shepherd_send`).
+ */
+const STATUS_MAX_CHARS = 120;
+const READ_MAX_CHARS = 16_000;
+const OVERVIEW_READ_LINES = 80;
+const OVERVIEW_SCREEN_MAX_CHARS = 4_000;
+const OVERVIEW_TOTAL_SCREEN_MAX_CHARS = 64_000;
+exports.SEND_TEXT_MAX_CHARS = 2_000;
+exports.SEND_KEYS = ["enter", "escape", "up", "down", "tab", "ctrl-c", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"];
+/** Keys that can approve or choose something on a prompt: pressed only on the screen the caller last read. */
+const CHOOSING_KEYS = new Set(["enter", "tab", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"]);
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function shepherdToolsEnabled(agentRoot) {
+    if (!agentRoot)
+        return false;
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(agentRoot, "agent.json"), "utf-8"));
+        return config.senses?.shepherd?.enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+function hostFor(agentName) {
+    const machine = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agentName);
+    const resolved = (0, shepherd_config_1.resolveShepherdConnection)(agentName, machine.ok ? machine.config : {});
+    return resolved.ok ? (0, host_1.createShepherdHost)(resolved.connection, { agentName }) : resolved.error;
+}
+async function withHost(tool, ctx, run) {
+    if (!ctx?.agentName || !ctx.agentRoot)
+        return JSON.stringify({ error: "the Shepherd tools need an agent runtime" });
+    const host = hostFor(ctx.agentName);
+    if (typeof host === "string")
+        return JSON.stringify({ error: host });
+    try {
+        if (ctx.currentShepherdSurface) {
+            const bound = ctx.currentShepherdSurface;
+            (0, target_binding_1.assertBoundShepherdTarget)(bound, bound.id, host.name);
+            if (!(await host.list()).some(session => session.id === bound.id))
+                throw new Error(`bound terminal ${bound.id} is gone; nothing was read or sent`);
+        }
+        const result = await run(host);
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.shepherd_tool", message: "ran a Shepherd tool", meta: { tool } });
+        return JSON.stringify(result);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_tool_error", message: "Shepherd tool call failed", meta: { tool, error: error.message } });
+        return JSON.stringify({ error: error.message });
+    }
+}
+async function currentScreen(host, session, maxChars) {
+    try {
+        const raw = await host.read(session, OVERVIEW_READ_LINES);
+        // Frame glyphs and padded empty rows otherwise crowd actual work out of a multi-terminal snapshot.
+        const content = (0, redact_1.redactSecrets)(raw).split("\n")
+            .map(line => line.replace(/[\u2500-\u259f]/g, "").trimEnd())
+            .filter(line => line.trim().length > 0).join("\n");
+        return { at: new Date().toISOString(), text: content.slice(Math.max(0, content.length - maxChars)), truncated: content.length > maxChars };
+    }
+    catch (error) {
+        const message = (0, redact_1.redactSecrets)(error instanceof Error ? error.message : String(error));
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_overview_read_error", message: "could not read one terminal in the live Shepherd overview", meta: { session, error: message } });
+        return { at: new Date().toISOString(), error: message };
+    }
+}
+exports.shepherdOverviewToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_overview",
+            description: "A live, read-only snapshot of every terminal on this machine's host (cmux): agent, folder, workspace and tab, plus a freshly read, redacted, bounded currentScreen with its observation time. Use currentScreen to answer what agents are doing now in one reply; lastReturn is historical and must not be presented as current status. Include every listed terminal exactly once with its complete ref (surface:12), including plain shells and supervisor composers; never omit a row or abbreviate subsequent refs to bare numbers. terminalCount is authoritative; derive disjoint category counts from those same rows. Classify activity as working, needs human, waiting on outside dependency, idle/local work finished, shell, or unknown. An idle prompt does not establish delivered work: do not use a generic Done bucket for locally finished work that still needs review, approval, merge, publication, deployment or verification. State those remaining steps inline. An agent explicitly reporting an outside reviewer wait belongs under waiting even when its prompt is idle; that is neither premature completion nor a request for routine continuation. A currentScreen.error explicitly identifies a terminal that could not be read; explain it inline with the other sessions, not by asking for another turn. For deeper details use shepherd_read. Historical lastReturn includes the prior judgment time, kind, action and reason.",
+            parameters: { type: "object", properties: {}, additionalProperties: false },
+        },
+    },
+    handler: (_args, ctx) => withHost("shepherd_overview", ctx, async (host) => {
+        const last = new Map();
+        for (const record of (0, returns_1.readReturns)(ctx.agentRoot))
+            last.set(record.session, record);
+        const sessions = await host.list();
+        const screenLimit = Math.min(OVERVIEW_SCREEN_MAX_CHARS, Math.floor(OVERVIEW_TOTAL_SCREEN_MAX_CHARS / Math.max(1, sessions.length)));
+        return {
+            host: host.name,
+            terminalCount: sessions.length,
+            sessions: await Promise.all(sessions.map(async (session) => {
+                const record = last.get(session.id);
+                return { ...session, currentScreen: await currentScreen(host, session.id, screenLimit), ...(record ? { lastReturn: { id: (0, guidance_1.shepherdReturnId)(record), at: record.at, kind: record.kind, action: record.action, reason: record.reason, reply: record.reply, task: record.task } } : {}) };
+            })),
+        };
+    }),
+    summaryKeys: [],
+    riskProfile: { mutates: "none", risk: "low" },
+};
+function boundedLines(value) {
+    const parsed = typeof value === "number" ? value : Number.parseInt(text(value), 10);
+    return Number.isFinite(parsed) ? Math.min(400, Math.max(1, Math.trunc(parsed))) : 60;
+}
+exports.shepherdReadToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_read",
+            description: "Read the text of one terminal session (what a coding agent shows now and what it did recently). Secret-shaped strings are redacted and the text is bounded. Read-only. Take the session id or ref from shepherd_overview. It also returns screen, a fingerprint of what the terminal shows now, for shepherd_send.",
+            parameters: {
+                type: "object",
+                properties: {
+                    session: { type: "string", description: "Session id or ref (surface:12) from shepherd_overview." },
+                    lines: { type: "number", description: "How many lines, 1-400. Default 60." },
+                },
+                required: ["session"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        const session = text(args.session).trim();
+        if (!session)
+            return Promise.resolve(JSON.stringify({ error: "name a session id or ref from shepherd_overview" }));
+        return withHost("shepherd_read", ctx, async (host) => {
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx?.currentShepherdSurface, session, host.name);
+            const lines = boundedLines(args.lines);
+            // A fingerprint needs enough lines to match the one shepherd_send takes, whatever the caller asked to see.
+            const raw = await host.read(session, Math.max(lines, redact_1.FINGERPRINT_READ_LINES));
+            const screen = (0, redact_1.redactSecrets)(raw).replace(/\n$/, "").split("\n").slice(-lines).join("\n");
+            return { session, text: screen.slice(-READ_MAX_CHARS), truncated: screen.length > READ_MAX_CHARS, screen: (0, redact_1.screenFingerprint)(raw) };
+        });
+    },
+    summaryKeys: ["session"],
+    riskProfile: { mutates: "none", risk: "low" },
+};
+exports.shepherdSignalToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_signal",
+            description: `Tell the human something through the terminal host. status sets Shepherd's one-line status on that session's workspace (at most ${STATUS_MAX_CHARS} characters; an empty string clears it). notify_title with notify_body also posts a desktop notification there. It never types into a terminal.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    session: { type: "string", description: "Session id or ref from shepherd_overview." },
+                    status: { type: "string", description: "One line for the status, or an empty string to clear it." },
+                    notify_title: { type: "string", description: "Desktop notification title." },
+                    notify_body: { type: "string", description: "Desktop notification body." },
+                },
+                required: ["session", "status"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        const session = text(args.session).trim();
+        const status = text(args.status).trim();
+        const title = text(args.notify_title).trim();
+        if (!session)
+            return Promise.resolve(JSON.stringify({ error: "name a session id or ref from shepherd_overview" }));
+        if (status.length > STATUS_MAX_CHARS || /[\r\n]/.test(status))
+            return Promise.resolve(JSON.stringify({ error: `status must be one line of at most ${STATUS_MAX_CHARS} characters` }));
+        return withHost("shepherd_signal", ctx, async (host) => {
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx?.currentShepherdSurface, session, host.name);
+            await host.signal(session, status || null, title ? { title, body: text(args.notify_body) } : undefined);
+            return { session, status: status ? "set" : "cleared", notified: !!title };
+        });
+    },
+    summaryKeys: ["session", "status"],
+    riskProfile: { mutates: "external_side_effect", risk: "high", reason: "changes what the terminal host shows the human (a status line or a desktop notification)" },
+};
+function refused(reason, meta) {
+    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_send_refused", message: "refused to type into a terminal", meta: { ...meta, reason } });
+    return { error: reason };
+}
+exports.shepherdSendToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_send",
+            description: `Type into one coding agent's terminal on this machine for the human you are talking with, because they asked you to. Use it only to deliver that human's own instruction or keypress ("tell it to run the tests", "approve that", "stop it"): never on your own initiative, and never for anyone else. Give exactly one of text or key. text is one line (at most ${exports.SEND_TEXT_MAX_CHARS} characters, no control characters), typed as "[<your configured name> for <their name>] <text>" and submitted with Enter. key is pressed alone: one of ${exports.SEND_KEYS.join(", ")} (a menu or permission prompt, escape to interrupt, ctrl-c to cancel). enter, tab, a digit, y and n can approve or choose on a prompt, so they need screen from a shepherd_read made just before, and nothing is sent if the terminal changed since; tell the human what a prompt asks before approving it unless they have seen it. Pass screen with text too when the text answers what is on screen. To interrupt and then instruct, send escape, read again, then send the text. It also types into the terminal the human has focused on this machine.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    session: { type: "string", description: "Session id or ref (surface:12) from shepherd_overview." },
+                    text: { type: "string", description: "The human's instruction, one line. Sent with [<your configured name> for <their name>] and Enter." },
+                    key: { type: "string", enum: [...exports.SEND_KEYS], description: "One key to press instead of text." },
+                    screen: { type: "string", description: "The screen fingerprint from the shepherd_read just before. Required for enter, tab, a digit, y and n." },
+                },
+                required: ["session"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        const session = text(args.session).trim();
+        const line = text(args.text).trim();
+        const key = text(args.key).trim().toLowerCase();
+        const seen = text(args.screen).trim();
+        const friend = ctx?.context?.friend;
+        const meta = { session, chars: line.length, key: key || null, friendId: friend?.id ?? null };
+        const refuse = (reason) => Promise.resolve(JSON.stringify(refused(reason, meta)));
+        // The private runtime talks to itself as a family "friend"; only a real family member's request may type.
+        if (!friend || friend.trustLevel !== "family" || friend.id === tools_base_1.SELF_FRIEND_ID)
+            return refuse("shepherd_send types only for a family member who asked for it in this conversation");
+        if (!session)
+            return refuse("name a session id or ref from shepherd_overview");
+        if (!line === !key)
+            return refuse("give exactly one of text or key");
+        if (key && !exports.SEND_KEYS.includes(key))
+            return refuse(`key must be one of ${exports.SEND_KEYS.join(", ")}`);
+        if (line.length > exports.SEND_TEXT_MAX_CHARS)
+            return refuse(`text must be at most ${exports.SEND_TEXT_MAX_CHARS} characters`);
+        if (/[\p{Cc}\u2028\u2029]/u.test(line))
+            return refuse("text must be one line with no control characters; press enter, escape or ctrl-c with key");
+        if (CHOOSING_KEYS.has(key) && !seen)
+            return refuse(`${key} can approve or choose on a prompt, so pass screen from a shepherd_read made just before`);
+        return withHost("shepherd_send", ctx, async (host) => {
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx?.currentShepherdSurface, session, host.name);
+            const target = (await host.list()).find((entry) => entry.id === session || entry.ref === session);
+            if (!target)
+                return refused(`session ${session} is gone; check shepherd_overview`, meta);
+            // Read again right before typing, as Shepherd does before its own answers: a gone or changed screen gets nothing.
+            const now = (0, redact_1.screenFingerprint)(await host.read(target.id, redact_1.FINGERPRINT_READ_LINES));
+            if (seen && seen !== now)
+                return refused("the terminal changed since it was read, so nothing was sent; read it again", meta);
+            const typed = key ? null : `[${(0, agent_presentation_1.readAgentPresentation)(ctx.agentName, ctx.agentRoot).name} for ${friend.name}] ${line}`;
+            if (key)
+                await host.key(target.id, key);
+            else
+                await host.prompt(target.id, typed);
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.shepherd_send",
+                message: "typed into a terminal for a family member",
+                meta: { ...meta, session: target.id, ref: target.ref, agent: target.agent, focused: target.focused, screenChecked: !!seen },
+            });
+            // The status line shows the human at the machine who typed; it is best effort, the send already happened.
+            await host.signal(target.id, `sent for ${friend.name}`.slice(0, STATUS_MAX_CHARS)).catch(() => undefined);
+            return { session: target.ref, sent: key ? { key } : { text: typed }, focused: target.focused };
+        });
+    },
+    summaryKeys: ["session", "key"],
+    riskProfile: { mutates: "external_side_effect", risk: "high", reason: "types into a coding agent's terminal for the human, which can answer or approve its prompts" },
+};
+exports.shepherdToolDefinitions = [exports.shepherdOverviewToolDefinition, exports.shepherdReadToolDefinition, exports.shepherdSignalToolDefinition, exports.shepherdSendToolDefinition, ...tools_shepherd_guidance_1.shepherdGuidanceToolDefinitions];