@ouro.bot/cli 0.1.0-alpha.95 → 0.1.0-alpha.951

package/dist/repertoire/tools-shell.js

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

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

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