@ouro.bot/cli 0.1.0-alpha.90 → 0.1.0-alpha.901

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,180 @@
+"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.shepherdSignalToolDefinition = exports.shepherdReadToolDefinition = exports.shepherdOverviewToolDefinition = 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");
+/**
+ * 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`), and a status
+ * line or notification for the human (`shepherd_signal`).
+ */
+const STATUS_MAX_CHARS = 120;
+const READ_MAX_CHARS = 16_000;
+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.",
+            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 screen = (0, redact_1.redactSecrets)(await host.read(session, boundedLines(args.lines)));
+            return { session, text: screen.slice(-READ_MAX_CHARS), truncated: screen.length > READ_MAX_CHARS };
+        });
+    },
+    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)" },
+};
+exports.shepherdToolDefinitions = [exports.shepherdOverviewToolDefinition, exports.shepherdReadToolDefinition, exports.shepherdSignalToolDefinition];

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