@ouro.bot/cli 0.1.0-alpha.96 → 0.1.0-alpha.960

package/dist/repertoire/tools-shepherd.js

@@ -0,0 +1,325 @@
+"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 node_crypto_1 = require("node:crypto");
+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 submit 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. When they answer a Shepherd notice you sent them, on any channel, with something meant for that coding session, that is such a request: shepherd_read the session the notice names, check it still shows the agent and folder the notice named, send their answer, then tell them what you sent. A thank-you or a question for you is not; if it is unclear which session or what to send, ask. 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. submission.state accepted means only that the terminal host accepted input; it may still be queued behind credential approval or a busy agent. It does not prove receiver receipt, resumed execution, restored capability or useful progress. Report those as unverified, never "unblocked" or "all unblocked" from this result or an unchanged screen. Each stronger claim needs fresh evidence from the exact target instance after this attempt, tied to this instruction; receipt alone is not progress or restored credentials. unknown may already have arrived: preserve the attempt and do not blindly resend.`,
+            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 label = `[${(0, agent_presentation_1.readAgentPresentation)(ctx.agentName, ctx.agentRoot).name} for ${friend.name}]`;
+            // The agent sometimes writes the label itself; type it once.
+            const typed = key ? null : `${label} ${line.toLowerCase().startsWith(label.toLowerCase()) ? line.slice(label.length).trimStart() : line}`;
+            const input = key ? { key } : { text: typed };
+            const attemptId = (0, node_crypto_1.randomUUID)();
+            const attemptedAt = new Date().toISOString();
+            const receiptTarget = { host: host.name, id: target.id, ref: target.ref, instance: target.instance ?? null };
+            const verification = { received: "unverified", execution: "unverified", capability: "unverified", progress: "unverified" };
+            const retry = "Do not resend blindly; reconcile this attempt with the exact receiver first.";
+            // A rejected/expired call can follow a partial paste or an accepted key.
+            // Neither host provides an agent-receipt or progress acknowledgement here.
+            try {
+                if (key)
+                    await host.key(target.id, key);
+                else
+                    await host.prompt(target.id, typed);
+            }
+            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_send_unknown",
+                    message: "terminal input outcome is unknown; do not blindly resend",
+                    meta: { ...meta, session: target.id, ref: target.ref, instance: target.instance ?? null, attemptId, attemptedAt, error: message },
+                });
+                return {
+                    error: message, session: target.ref, attempted: input,
+                    submission: { state: "unknown", attemptId, attemptedAt, reportedAt: new Date().toISOString(), target: receiptTarget },
+                    verification, retry,
+                };
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.shepherd_send",
+                message: "terminal host accepted input; receiver receipt and progress unverified",
+                meta: { ...meta, session: target.id, ref: target.ref, instance: target.instance ?? null, attemptId, attemptedAt, agent: target.agent, focused: target.focused, screenChecked: !!seen },
+            });
+            await host.signal(target.id, `submitted for ${friend.name}; receipt unverified`.slice(0, STATUS_MAX_CHARS)).catch(() => undefined);
+            return {
+                session: target.ref, submitted: input, focused: target.focused,
+                submission: { state: "accepted", attemptId, attemptedAt, reportedAt: new Date().toISOString(), target: receiptTarget },
+                verification, retry,
+            };
+        });
+    },
+    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];

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" },
+};