@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/repertoire/tools-shell.js

@@ -0,0 +1,149 @@
+"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: (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 = (0, child_process_1.execSync)(a.command, {
+                encoding: "utf-8",
+                timeout,
+            });
+            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.js

@@ -0,0 +1,262 @@
+"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");
+/**
+ * Shepherd's tools: every coding-agent session on this machine's terminal host with what Shepherd
+ * last decided about it (`shepherd_overview`), what a session shows (`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;
+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 {
+        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 });
+    }
+}
+exports.shepherdOverviewToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_overview",
+            description: "Every terminal session on this machine's terminal host (cmux), with the coding agent there when known, and the last time Shepherd judged a return of control in it: when, what kind (premature, gate, done, unclear, loop_guard, error), whether it answered, and why. Read-only.",
+            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);
+        return {
+            host: host.name,
+            sessions: (await host.list()).map((session) => {
+                const record = last.get(session.id);
+                return { ...session, ...(record ? { lastReturn: { 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) => {
+            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) => {
+            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 "[Ouro 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 the [Ouro for <name>] prefix 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) => {
+            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 : `[Ouro 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];

package/dist/repertoire/tools-steward-policy.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stewardPolicyToolDefinition = void 0;
+const steward_policy_1 = require("../heart/steward-policy");
+const runtime_1 = require("../nerves/runtime");
+function arrayArgument(raw, label) {
+    if (!raw)
+        throw new Error(`${label} is required`);
+    const value = JSON.parse(raw);
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))
+        throw new Error(`${label} must be a JSON string array`);
+    return value;
+}
+exports.stewardPolicyToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "steward_policy_manage",
+            description: "Read or update the household steward's typed desired-state and routine-action policy. Updates require the current authenticated owner Telegram request and fresh authorization. Replay identities can never update it. correct_provenance (key, source, correction) is only for fixing a wrong attribution on an existing desired state: it replaces the recorded source and records the correction note, never changes the value, and leaves an audit row; do not use it to change a value. expectedVersion is optional; omit it to apply against the current policy version, or supply a version from read for explicit stale-write detection.",
+            parameters: {
+                type: "object",
+                properties: {
+                    action: { type: "string", enum: ["read", "set_desired_state", "grant_routine_action", "correct_provenance"] },
+                    expectedVersion: { type: "integer", minimum: 0, description: "Optional version returned by read. When omitted, the runtime uses the current policy version." },
+                    key: { type: "string" },
+                    value: { type: "string" },
+                    provenance: { type: "string", enum: ["stated", "observed", "default", "installed_explicit_policy"] },
+                    source: { type: "string", description: "Who or what stated this. For correct_provenance, the corrected attribution that replaces the recorded source." },
+                    correction: { type: "string", description: "correct_provenance only: required note naming what is being corrected and why." },
+                    routineAction: { type: "string" },
+                    targetsJson: { type: "string", description: "JSON array of exact target names" },
+                    maxCount: { type: "integer", minimum: 1 },
+                    windowMs: { type: "integer", minimum: 1 },
+                    verificationRequired: { type: "boolean" },
+                    exclusionsJson: { type: "string", description: "JSON array of exact excluded target names" },
+                    expiresAt: { type: "string" },
+                },
+                required: ["action"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        if (!ctx?.agentRoot)
+            throw new Error("steward policy runtime is unavailable");
+        if (!ctx.relationshipAuthorization)
+            throw new Error("steward policy access requires authenticated relationship authority");
+        if (args.action === "read") {
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.steward_policy_tool_call", message: "read steward policy", meta: { action: "read" } });
+            return JSON.stringify((0, steward_policy_1.readStewardPolicy)(ctx.agentRoot));
+        }
+        const relationship = ctx.relationshipAuthorization;
+        const actor = relationship.actor;
+        if (!actor)
+            throw new Error("steward policy mutation requires authenticated relationship authority");
+        const { friendId, trustLevel, sessionEventId } = actor;
+        const { profileId, requestId } = relationship;
+        (0, steward_policy_1.assertNotReplayIdentity)(ctx.agentRoot, [friendId, ctx.delegatedCommand?.delegateFriendId]);
+        const sessionKey = ctx.currentSession?.key;
+        const delegated = ctx.delegatedCommand;
+        // Two ways to hold owner authority: the owner's own Telegram turn, or a delegated
+        // command the A2A server admitted (grant checked, owner already notified).
+        const sessionMatches = () => delegated
+            ? ctx.currentSession?.channel === "a2a" && ctx.delegatedCommand === delegated
+                && friendId === delegated.principalFriendId && requestId === delegated.commandId
+                && sessionEventId === `a2a-delegated:${delegated.commandId}`
+            : ctx.currentSession?.friendId === friendId && ctx.currentSession.channel === "telegram";
+        if (trustLevel !== "family" || profileId !== "sanctuary-owner" || typeof requestId !== "string" || !requestId.trim()
+            || typeof sessionKey !== "string" || !sessionKey.trim() || !sessionEventId.trim()
+            || !sessionMatches() || ctx.currentExternalEvent) {
+            throw new Error(delegated
+                ? "steward policy mutation requires a current admitted delegated owner command"
+                : "steward policy mutation requires a current authenticated owner Telegram request and session");
+        }
+        const sourceFor = (raw) => delegated
+            ? `${delegated.principalName} via ${delegated.delegateName} (delegated)${raw?.trim() ? `: ${raw.trim()}` : ""}`
+            : raw ?? "";
+        const expectedVersion = args.expectedVersion === undefined ? undefined : Number(args.expectedVersion);
+        if (expectedVersion !== undefined && (!Number.isSafeInteger(expectedVersion) || expectedVersion < 0))
+            throw new Error("expectedVersion must be a nonnegative integer");
+        let mutation;
+        if (args.action === "set_desired_state") {
+            if (args.provenance !== "stated" && args.provenance !== "observed" && args.provenance !== "default")
+                throw new Error("desired state provenance is invalid");
+            mutation = { kind: "set_desired_state", key: args.key ?? "", value: args.value ?? "", provenance: args.provenance, source: sourceFor(args.source), ...(args.expiresAt ? { expiresAt: args.expiresAt } : {}) };
+        }
+        else if (args.action === "correct_provenance") {
+            mutation = { kind: "correct_provenance", key: args.key ?? "", source: sourceFor(args.source), correction: args.correction ?? "" };
+        }
+        else if (args.action === "grant_routine_action") {
+            if (args.provenance !== "stated" && args.provenance !== "installed_explicit_policy")
+                throw new Error("routine action provenance is invalid");
+            const targets = arrayArgument(args.targetsJson, "targetsJson");
+            const exclusions = arrayArgument(args.exclusionsJson, "exclusionsJson");
+            const verificationRequired = args.verificationRequired;
+            if (verificationRequired !== true)
+                throw new Error("verificationRequired must be true");
+            mutation = {
+                kind: "grant_routine_action",
+                key: args.key ?? "",
+                action: args.routineAction ?? "",
+                targets,
+                maxCount: Number(args.maxCount),
+                windowMs: Number(args.windowMs),
+                verificationRequired,
+                exclusions,
+                provenance: args.provenance,
+                ...(args.expiresAt ? { expiresAt: args.expiresAt } : {}),
+            };
+        }
+        else
+            throw new Error("steward policy action is invalid");
+        const agentRoot = ctx.agentRoot;
+        return Promise.resolve(relationship.authorizeTool("steward_policy_manage", args)).then((authorization) => {
+            if (!authorization.allowed)
+                throw new Error(`steward policy authorization denied: ${authorization.reason}`);
+            if (typeof authorization.profileVersion !== "number" || !Number.isSafeInteger(authorization.profileVersion) || authorization.profileVersion < 1 || !authorization.receiptId.trim()) {
+                throw new Error("steward policy owner authorization is not versioned");
+            }
+            if (ctx.relationshipAuthorization !== relationship || relationship.profileId !== profileId || relationship.requestId !== requestId
+                || relationship.actor?.friendId !== friendId || relationship.actor.trustLevel !== trustLevel || relationship.actor.sessionEventId !== sessionEventId
+                || ctx.currentSession?.key !== sessionKey || !sessionMatches() || ctx.currentExternalEvent) {
+                throw new Error("steward policy owner authorization or session changed before mutation");
+            }
+            const versionBefore = (0, steward_policy_1.readStewardPolicy)(agentRoot).version;
+            const result = (0, steward_policy_1.updateStewardPolicy)(agentRoot, {
+                expectedVersion: expectedVersion ?? (0, steward_policy_1.readStewardPolicy)(agentRoot).version,
+                actor: {
+                    friendId, trustLevel, sessionEventId,
+                    authorization: { profileId, requestId, sessionKey, receiptId: authorization.receiptId, profileVersion: authorization.profileVersion },
+                    ...(delegated ? { delegatedVia: { delegateFriendId: delegated.delegateFriendId, delegateDid: delegated.delegateDid, noticeId: delegated.noticeId } } : {}),
+                },
+                mutation,
+            });
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.steward_policy_tool_call", message: "updated steward policy", meta: { action: args.action } });
+            if (mutation.kind === "set_desired_state" && result.version === versionBefore) {
+                // A same-value restatement writes nothing; the entry is necessarily present.
+                const existing = result.desiredStates[mutation.key];
+                return JSON.stringify({ ...result, unchanged: true, note: `already recorded as ${existing.value} (source: ${existing.source})` });
+            }
+            return JSON.stringify(result);
+        });
+    },
+    riskProfile: (args) => args.action === "read"
+        ? { mutates: "none", risk: "low" }
+        : { mutates: "durable_state_write", risk: "high", reason: "updates typed household steward policy under current authenticated owner authority" },
+};