@ouro.bot/cli 0.1.0-alpha.894 → 0.1.0-alpha.897

package/dist/repertoire/bitwarden-store.js

@@ -43,6 +43,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BitwardenCredentialStore = void 0;
 exports.sanitizeCredentialErrorDetail = sanitizeCredentialErrorDetail;
+exports.readBwCliVersion = readBwCliVersion;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -169,6 +170,7 @@ const BW_LOCK_STALE_MS = BW_LOCK_TIMEOUT_MS * 2;
 const BW_DATA_FILENAME = "data.json";
 const BW_SYNC_MARKER_FILENAME = ".ouro-last-sync";
 const BW_SYNC_FRESH_MS = 60_000;
+const BW_TERMINAL_LOGIN_ERROR_RETRY_MS = 15 * 60_000;
 /** In-process async mutex keyed by appDataDir. */
 const inProcessLocks = new Map();
 function isPidAlive(pid) {
@@ -365,6 +367,58 @@ function isBwNotInstalled(err) {
     const code = err.code;
     return code === "ENOENT" || /\bspawn\b.*\benoent\b/.test(msg) || msg.includes("command not found");
 }
+/**
+ * Read the installed @bitwarden/cli version from the package that owns the
+ * resolved `bw` binary. Returns null when the binary is not an npm install.
+ */
+function readBwCliVersion(bwBinaryPath) {
+    let dir;
+    try {
+        dir = path.dirname(fs.realpathSync(bwBinaryPath));
+    }
+    catch {
+        return null;
+    }
+    for (let depth = 0; depth < 4; depth++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+            if (pkg.name === "@bitwarden/cli" && typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch {
+            // Keep walking up toward the package root.
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+/** Another process holds the profile; the profile itself is not at fault. */
+function isBwLockTimeout(err) {
+    return err.message.includes("bw CLI lock timeout");
+}
+/**
+ * A local bw step (unlock of an already-authenticated profile) failed for a
+ * reason that says nothing about the vault server: the profile on disk is
+ * unusable. Network, lock and missing-binary failures are not this, and
+ * neither is a rejected unlock secret.
+ */
+class LocalProfileUnusableError extends Error {
+    localError;
+    constructor(localError) {
+        super(localError.message);
+        this.localError = localError;
+    }
+}
+function asLocalProfileFailure(err) {
+    if (isTransientError(err) || isBwNotInstalled(err) || isBwLockTimeout(err) || isBwInvalidUnlockSecretMessage(err.message)) {
+        return err;
+    }
+    return new LocalProfileUnusableError(err);
+}
+/** A bw version as a safe directory name component. */
+function bwProfileDirName(version) {
+    return `bw-${version.replace(/[^A-Za-z0-9._-]/g, "_")}`;
+}
 /** Check if the error is transient (network/timeout) and worth retrying. */
 function isTransientError(err) {
     const msg = err.message.toLowerCase();
@@ -372,7 +426,18 @@ function isTransientError(err) {
         msg.includes("etimedout") ||
         msg.includes("enotfound") ||
         msg.includes("socket hang up") ||
+        msg.includes("econnreset") ||
+        msg.includes("eai_again") ||
+        msg.includes("enetunreach") ||
+        msg.includes("ehostunreach") ||
+        msg.includes("fetch failed") ||
+        msg.includes("429") ||
+        msg.includes("too many requests") ||
+        msg.includes("502") ||
         msg.includes("503") ||
+        msg.includes("504") ||
+        msg.includes("bad gateway") ||
+        msg.includes("gateway timeout") ||
         msg.includes("server unavailable") ||
         msg.includes("timed out"));
 }
@@ -491,17 +556,22 @@ class BitwardenCredentialStore {
     serverUrl;
     email;
     masterPassword;
+    /** The agent's bw folder; each bw version keeps its own profile under it. */
+    agentDataDir;
+    /** The profile directory for the running bw version (BITWARDENCLI_APPDATA_DIR). */
     appDataDir;
     onInvalidUnlockSecret;
     onLoginSuccess;
     sessionToken = null;
     terminalLoginError = null;
+    terminalLoginErrorAt = 0;
     bwBinaryPath = "bw";
     structuredItemCache = null;
     constructor(serverUrl, email, masterPassword, options = {}) {
         this.serverUrl = serverUrl;
         this.email = email;
         this.masterPassword = masterPassword;
+        this.agentDataDir = options.appDataDir;
         this.appDataDir = options.appDataDir;
         this.onInvalidUnlockSecret = options.onInvalidUnlockSecret;
         this.onLoginSuccess = options.onLoginSuccess;
@@ -543,11 +613,21 @@ class BitwardenCredentialStore {
      */
     async login() {
         if (this.terminalLoginError) {
-            throw this.terminalLoginError;
+            // A long-lived process retries a terminal failure after a while instead
+            // of holding it until restart; rejected secrets are paused separately.
+            if (Date.now() - this.terminalLoginErrorAt < BW_TERMINAL_LOGIN_ERROR_RETRY_MS) {
+                throw this.terminalLoginError;
+            }
+            this.terminalLoginError = null;
         }
         // Ensure bw CLI is installed before any bw commands
         this.bwBinaryPath = await (0, bw_installer_1.ensureBwCli)();
-        if (this.appDataDir) {
+        if (this.agentDataDir) {
+            // Each bw version gets its own profile directory, so machines with
+            // several bw installs (one per Node version) never migrate or fight
+            // over one another's state.
+            const bwVersion = readBwCliVersion(this.bwBinaryPath);
+            this.appDataDir = bwVersion ? path.join(this.agentDataDir, bwProfileDirName(bwVersion)) : this.agentDataDir;
             fs.mkdirSync(this.appDataDir, { recursive: true, mode: 0o700 });
         }
         let lastError;
@@ -562,7 +642,7 @@ class BitwardenCredentialStore {
                 lastError = err instanceof Error ? err : new Error(String(err));
                 // Don't retry non-transient errors (auth failures, bw not installed)
                 if (!isTransientError(lastError)) {
-                    this.terminalLoginError = lastError;
+                    this.setTerminalLoginError(lastError);
                     if (isBwInvalidUnlockSecretMessage(lastError.message)) {
                         await this.notifyInvalidUnlockSecret(lastError);
                     }
@@ -581,15 +661,76 @@ class BitwardenCredentialStore {
                 await delay(backoffMs);
             }
         }
-        this.terminalLoginError = lastError;
+        this.setTerminalLoginError(lastError);
         /* v8 ignore next -- invalid unlock errors are non-transient and exit through the non-retry path above @preserve */
         if (isBwInvalidUnlockSecretMessage(lastError.message)) {
             await this.notifyInvalidUnlockSecret(lastError);
         }
         throw lastError;
     }
-    /** Single login attempt — called by login() retry loop. */
+    setTerminalLoginError(error) {
+        this.terminalLoginError = error;
+        this.terminalLoginErrorAt = Date.now();
+    }
+    /**
+     * Single login attempt — called by login() retry loop.
+     *
+     * The bw profile directory is a disposable cache; the durable secret is the
+     * machine's vault unlock material. When a local step fails on an
+     * authenticated profile (a corrupt or half-migrated profile, a missing
+     * session), the profile is moved aside and rebuilt with one fresh login.
+     * Server steps (login, sync), network failures, lock contention and
+     * rejected secrets never discard the profile, so a bad secret or a flaky
+     * server costs at most one server login per attempt.
+     */
     async loginAttempt() {
+        try {
+            await this.loginWithLocalProfile();
+        }
+        catch (error) {
+            if (!(error instanceof LocalProfileUnusableError))
+                throw error;
+            await this.discardLocalProfile(error.localError);
+            try {
+                await this.loginWithLocalProfile();
+            }
+            catch (retryError) {
+                throw retryError instanceof LocalProfileUnusableError ? retryError.localError : retryError;
+            }
+        }
+    }
+    /**
+     * Move the local bw profile aside so the next bw command starts from an
+     * empty profile. The previous data file is kept as one `.discarded` copy
+     * for diagnosis and is overwritten by the next discard.
+     */
+    async discardLocalProfile(cause) {
+        const appDataDir = this.appDataDir;
+        this.sessionToken = null;
+        this.structuredItemCache = null;
+        await withBwLock(appDataDir, async () => {
+            const dataPath = path.join(appDataDir, BW_DATA_FILENAME);
+            try {
+                fs.renameSync(dataPath, `${dataPath}.discarded`);
+            }
+            catch {
+                // Already gone: another process discarded it first, which is the same outcome.
+            }
+            fs.rmSync(path.join(appDataDir, BW_SYNC_MARKER_FILENAME), { force: true });
+        });
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            event: "repertoire.bw_local_profile_discarded",
+            component: "repertoire",
+            message: "discarded unusable local bw profile; logging in fresh with the saved unlock secret",
+            meta: {
+                email: this.email,
+                serverUrl: this.serverUrl,
+                error: sanitizeCredentialErrorDetail(cause.message),
+            },
+        });
+    }
+    async loginWithLocalProfile() {
         let status = await this.readStatus();
         if (this.shouldRebuildLocalProfile(status)) {
             await this.rebuildLocalProfile("local bw profile did not match requested vault", status);
@@ -692,7 +833,12 @@ class BitwardenCredentialStore {
             const err = error;
             if (!isBwAlreadyLoggedInError(err))
                 throw err;
-            return this.execBwWithPasswordEnv(["unlock", "--raw"]);
+        }
+        try {
+            return await this.execBwWithPasswordEnv(["unlock", "--raw"]);
+        }
+        catch (error) {
+            throw asLocalProfileFailure(error);
         }
     }
     forgetLocalSyncMarker() {
@@ -754,7 +900,7 @@ class BitwardenCredentialStore {
         catch (error) {
             const err = error;
             if (!isBwInvalidUnlockSecretMessage(err.message))
-                throw err;
+                throw asLocalProfileFailure(err);
             await this.rebuildLocalProfile(reason, status, err);
             /* v8 ignore next -- defensive: rebuildLocalProfile always stores a string session token on success @preserve */
             return this.sessionToken ?? "";

package/dist/repertoire/credential-access.js

@@ -46,15 +46,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCredentialStore = getCredentialStore;
 exports.probeCredentialVaultAccess = probeCredentialVaultAccess;
 exports.resetCredentialStore = resetCredentialStore;
-const crypto = __importStar(require("node:crypto"));
 const fs = __importStar(require("node:fs"));
-const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const runtime_1 = require("../nerves/runtime");
 const identity = __importStar(require("../heart/identity"));
 const bitwarden_store_1 = require("./bitwarden-store");
 const vault_unlock_1 = require("./vault-unlock");
 let stores = new Map();
+function rejectedUnlockMessage(agentName, reason) {
+    return [
+        `The vault rejected the unlock secret saved on this machine for ${agentName} (${reason}).`,
+        "The saved secret was kept. If the vault's unlock secret changed, run",
+        `\`ouro vault unlock --agent ${agentName}\` once with the current secret.`,
+    ].join(" ");
+}
 function loadVaultSectionForAgent(agentName) {
     const configPath = path.join(identity.getAgentRoot(agentName), "agent.json");
     try {
@@ -65,14 +70,6 @@ function loadVaultSectionForAgent(agentName) {
         return { configPath };
     }
 }
-function bitwardenAppDataDir(agentName, vaultConfig, homeDir = os.homedir()) {
-    const digest = crypto
-        .createHash("sha256")
-        .update(`${agentName}:${vaultConfig.serverUrl}:${vaultConfig.email}`)
-        .digest("hex")
-        .slice(0, 24);
-    return path.join(homeDir, ".ouro-cli", "bitwarden", digest);
-}
 function getCredentialStore(agentNameInput) {
     const agentName = agentNameInput ?? identity.getAgentName();
     if (agentName === "SerpentGuide") {
@@ -87,6 +84,11 @@ function getCredentialStore(agentNameInput) {
     const cached = stores.get(cacheKey);
     if (cached)
         return cached;
+    const agentDataDir = (0, vault_unlock_1.bitwardenAppDataDir)(agentName, vaultConfig);
+    const rejection = (0, vault_unlock_1.readVaultUnlockRejection)(agentDataDir);
+    if (rejection) {
+        throw new Error(rejectedUnlockMessage(agentName, rejection.reason));
+    }
     const unlock = (0, vault_unlock_1.readVaultUnlockSecret)({
         agentName,
         email: vaultConfig.email,
@@ -94,25 +96,22 @@ function getCredentialStore(agentNameInput) {
     });
     const unlockConfig = { agentName, email: vaultConfig.email, serverUrl: vaultConfig.serverUrl };
     const unlockSource = unlock.source ?? unlockConfig;
-    let invalidUnlockCleared = false;
     let canonicalUnlockStored = false;
     const store = new bitwarden_store_1.BitwardenCredentialStore(vaultConfig.serverUrl, vaultConfig.email, unlock.secret, {
-        appDataDir: bitwardenAppDataDir(agentName, vaultConfig),
+        appDataDir: agentDataDir,
         onInvalidUnlockSecret: (error) => {
-            if (invalidUnlockCleared)
-                return;
-            invalidUnlockCleared = true;
-            (0, vault_unlock_1.clearVaultUnlockSecret)({
-                agentName,
-                email: unlockSource.email,
-                serverUrl: unlockSource.serverUrl,
-            });
+            // The vault rejected the saved secret. Keep the saved secret: deleting
+            // the only durable copy turns any misclassified bw or server error
+            // into a human prompt. Record the rejection on disk so no process
+            // retries it against the server; `ouro vault unlock` or any
+            // successful login clears the record.
             stores.delete(cacheKey);
+            (0, vault_unlock_1.recordVaultUnlockRejection)(agentDataDir, error.message);
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
-                event: "repertoire.credential_store_invalid_unlock_cleared",
+                event: "repertoire.credential_store_unlock_rejected",
                 component: "repertoire",
-                message: "cleared rejected local vault unlock material",
+                message: "vault rejected the saved local unlock secret; kept it and paused retries until a new secret is saved",
                 meta: {
                     agentName,
                     serverUrl: vaultConfig.serverUrl,
@@ -123,6 +122,7 @@ function getCredentialStore(agentNameInput) {
             });
         },
         onLoginSuccess: () => {
+            (0, vault_unlock_1.clearVaultUnlockRejection)(agentDataDir);
             if (canonicalUnlockStored)
                 return;
             if (unlockSource.serverUrl === vaultConfig.serverUrl && unlockSource.email === vaultConfig.email)
@@ -170,7 +170,11 @@ async function probeCredentialVaultAccess(agentNameInput, unlockSecret, options
         throw new Error((0, vault_unlock_1.credentialVaultNotConfiguredError)(agentName, configPath));
     }
     const vaultConfig = identity.resolveVaultConfig(agentName, vault);
-    const store = new bitwarden_store_1.BitwardenCredentialStore(vaultConfig.serverUrl, vaultConfig.email, unlockSecret, { appDataDir: bitwardenAppDataDir(agentName, vaultConfig, options.homeDir) });
+    const agentDataDir = (0, vault_unlock_1.bitwardenAppDataDir)(agentName, vaultConfig, options.homeDir);
+    const store = new bitwarden_store_1.BitwardenCredentialStore(vaultConfig.serverUrl, vaultConfig.email, unlockSecret, {
+        appDataDir: agentDataDir,
+        onLoginSuccess: () => (0, vault_unlock_1.clearVaultUnlockRejection)(agentDataDir),
+    });
     await store.get("__ouro_vault_probe__");
 }
 function resetCredentialStore() {

package/dist/repertoire/guardrails.js

@@ -441,9 +441,9 @@ const TRAVEL_TRUSTED_TOOLS = new Set(["weather_lookup", "travel_advisory", "geoc
 const A2A_TRUSTED_TOOLS = new Set(["a2a_list_peers", "a2a_send_message", "a2a_get_task"]);
 const COMMERCE_FAMILY_TOOLS = new Set(["commerce_checkout_preview", "commerce_checkout_commit", "commerce_receipt_get", "commerce_access_log"]);
 const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
-// The cmux tools read the owner's terminals and speak to them through their desktop, so only family may use them.
+// The Shepherd tools read the owner's terminals and speak to them through their desktop, so only family may use them.
 // A call with no known trust level fails closed.
-const CMUX_FAMILY_TOOLS = new Set(["cmux_overview", "cmux_read", "cmux_signal", "cmux_reply_once", "cmux_correct"]);
+const SHEPHERD_FAMILY_TOOLS = new Set(["shepherd_overview", "shepherd_read", "shepherd_signal"]);
 const MAIL_FAMILY_TOOLS = new Set(["mail_screener", "mail_decide", "mail_access_log", "mail_send", "mail_index_refresh"]);
 const MAIL_DELEGATED_READ_TOOLS = new Set(["mail_recent", "mail_search"]);
 function opaqueAnsiShellAtoms(command) {
@@ -1184,8 +1184,8 @@ function checkTrustLevelGuardrails(toolName, args, context) {
     const mailResult = mailTrustGuardrail(toolName, args, context);
     if (!mailResult.allowed)
         return mailResult;
-    if (CMUX_FAMILY_TOOLS.has(toolName) && context.trustLevel !== "family") {
-        return deny("the owner's cmux terminals require family trust.");
+    if (SHEPHERD_FAMILY_TOOLS.has(toolName) && context.trustLevel !== "family") {
+        return deny("the owner's terminals require family trust.");
     }
     // Credential tools have their own trust rules that apply at all levels
     const credentialResult = checkCredentialTrustGuardrails(toolName, context);

package/dist/repertoire/tools-shepherd.js

@@ -0,0 +1,181 @@
+"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 client_1 = require("../senses/shepherd/client");
+const cmux_1 = require("../senses/shepherd/cmux");
+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, cmux_1.createCmuxHost)((0, client_1.createCmuxClient)(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.js

@@ -37,7 +37,7 @@ const tools_unraid_1 = require("./tools-unraid");
 const tools_flow_1 = require("./tools-flow");
 const tools_steward_policy_1 = require("./tools-steward-policy");
 const tools_house_care_1 = require("./tools-house-care");
-const tools_cmux_1 = require("./tools-cmux");
+const tools_shepherd_1 = require("./tools-shepherd");
 const steward_policy_1 = require("../heart/steward-policy");
 const relationship_authorization_1 = require("./relationship-authorization");
 const tool_approval_1 = require("../heart/tool-approval");
@@ -98,7 +98,7 @@ Object.defineProperty(exports, "speakTool", { enumerable: true, get: function ()
 var tools_surface_2 = require("./tools-surface");
 Object.defineProperty(exports, "surfaceToolDef", { enumerable: true, get: function () { return tools_surface_2.surfaceToolDef; } });
 // All tool definitions in a single registry
-const additionalDefinitions = [...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...tools_house_care_1.houseCareToolDefinitions, tools_surface_1.surfaceToolDefinition, ...tools_cmux_1.cmuxToolDefinitions];
+const additionalDefinitions = [...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...tools_house_care_1.houseCareToolDefinitions, tools_surface_1.surfaceToolDefinition, ...tools_shepherd_1.shepherdToolDefinitions];
 const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
 class ToolSelectionError extends Error {
 }
@@ -172,8 +172,8 @@ function selectToolsForChannel(capabilities, toolPreferences, _context, provider
         });
         ordinary = [
             ...tools_base_1.baseToolDefinitions,
-            // The cmux sense's tools exist only for an agent that turned the sense on in agent.json.
-            ...((0, tools_cmux_1.cmuxToolsEnabled)(context?.agentRoot ?? safeGetAgentRoot()) ? tools_cmux_1.cmuxToolDefinitions : []),
+            // The Shepherd tools exist only for an agent that turned the sense on in agent.json.
+            ...((0, tools_shepherd_1.shepherdToolsEnabled)(context?.agentRoot ?? safeGetAgentRoot()) ? tools_shepherd_1.shepherdToolDefinitions : []),
             ...(capabilities?.channel === "bluebubbles" ? tools_bluebubbles_1.bluebubblesToolDefinitions : []),
             ...(capabilities?.channel === "voice" ? tools_voice_1.voiceToolDefinitions : []),
             ...((0, tools_voice_local_1.localAudioToolGate)({ ...context, context: _context }).ok ? [tools_voice_local_1.voiceLocalAudioToolDefinition] : []),