@ouro.bot/cli 0.1.0-alpha.918 → 0.1.0-alpha.919

package/dist/mind/friend-merge.js

@@ -0,0 +1,330 @@
+"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.externalIdKey = externalIdKey;
+exports.mergeFriendRecordContent = mergeFriendRecordContent;
+exports.mergeFriends = mergeFriends;
+exports.planFriendDedupe = planFriendDedupe;
+exports.dedupeFriends = dedupeFriends;
+// Merging friend records into one person, and retiring the merged-away records.
+//
+// Two product paths use this: redeeming an identity link code (a new channel identity
+// joins its owner's record) and deduplicating records that name the same local person.
+// The target record stays authoritative: a merge never raises trust, admission,
+// initiative or capability, so merging cannot be used to escalate anyone.
+//
+// A retired record is kept as a tombstone in `friends/_retired/` (outside the store's
+// listing), never deleted silently. External-identity claim journals that pointed at the
+// retired record move beside it, so the store's claim ledger never names a record that
+// no longer exists. The claim journal layout belongs to @ouro.bot/friends; this module
+// only moves whole journal files and never rewrites them.
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const RETIRED_DIR = "_retired";
+const CLAIMS_DIR = "_external-id-claims";
+const CLAIM_FILE = /^[a-f0-9]{64}\.json$/;
+function externalIdKey(externalId) {
+    return JSON.stringify([externalId.provider, externalId.externalId, externalId.tenantId ?? null]);
+}
+/** Fold the sources into the target. The target's relationship fields always win. */
+function mergeFriendRecordContent(target, sources, nowIso) {
+    const externalIds = [...target.externalIds];
+    const seenIds = new Set(externalIds.map(externalIdKey));
+    const addedExternalIds = [];
+    const notes = { ...target.notes };
+    const preservedNoteKeys = [];
+    const tenantMemberships = [...target.tenantMemberships];
+    const toolPreferences = { ...target.toolPreferences };
+    const connections = [...(target.connections ?? [])];
+    const importedNotes = { ...(target.importedNotes ?? {}) };
+    let totalTokens = target.totalTokens;
+    let createdAt = target.createdAt;
+    for (const source of sources) {
+        for (const externalId of source.externalIds) {
+            const key = externalIdKey(externalId);
+            if (seenIds.has(key))
+                continue;
+            seenIds.add(key);
+            externalIds.push(externalId);
+            addedExternalIds.push(externalId);
+        }
+        for (const [key, note] of Object.entries(source.notes)) {
+            const existing = notes[key];
+            if (!existing) {
+                notes[key] = note;
+                continue;
+            }
+            if (existing.value === note.value)
+                continue;
+            const preservedKey = `${key}~${source.id.slice(0, 8)}`;
+            if (notes[preservedKey])
+                continue;
+            notes[preservedKey] = note;
+            preservedNoteKeys.push(preservedKey);
+        }
+        for (const tenant of source.tenantMemberships) {
+            if (!tenantMemberships.includes(tenant))
+                tenantMemberships.push(tenant);
+        }
+        for (const [tool, preference] of Object.entries(source.toolPreferences)) {
+            if (!(tool in toolPreferences))
+                toolPreferences[tool] = preference;
+        }
+        for (const connection of source.connections ?? []) {
+            if (!connections.some((known) => known.name === connection.name && known.relationship === connection.relationship)) {
+                connections.push(connection);
+            }
+        }
+        for (const [agentKey, imported] of Object.entries(source.importedNotes ?? {})) {
+            importedNotes[agentKey] = { ...imported, ...(importedNotes[agentKey] ?? {}) };
+        }
+        totalTokens += source.totalTokens;
+        if (source.createdAt < createdAt)
+            createdAt = source.createdAt;
+    }
+    const merged = {
+        ...target,
+        externalIds,
+        notes,
+        tenantMemberships,
+        toolPreferences,
+        connections,
+        ...(Object.keys(importedNotes).length > 0 ? { importedNotes } : {}),
+        totalTokens,
+        createdAt,
+        updatedAt: nowIso,
+    };
+    return { merged, addedExternalIds, preservedNoteKeys };
+}
+function writePrivateJson(filePath, value) {
+    const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temp, filePath);
+}
+function uniqueTombstonePath(retiredDir, friendId, nowIso) {
+    const plain = path.join(retiredDir, `${friendId}.json`);
+    if (!fs.existsSync(plain))
+        return plain;
+    return path.join(retiredDir, `${friendId}.${nowIso.replace(/[:.]/g, "-")}.json`);
+}
+/** Move every claim journal that names `friendId` out of the live claim ledger. */
+function moveClaimJournals(friendsDir, friendId) {
+    const claimsDir = path.join(friendsDir, CLAIMS_DIR);
+    if (!fs.existsSync(claimsDir))
+        return [];
+    const retiredClaimsDir = path.join(friendsDir, RETIRED_DIR, "external-id-claims");
+    const moved = [];
+    for (const entry of fs.readdirSync(claimsDir)) {
+        if (!CLAIM_FILE.test(entry))
+            continue;
+        let claim;
+        try {
+            claim = JSON.parse(fs.readFileSync(path.join(claimsDir, entry), "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (claim.friendId !== friendId)
+            continue;
+        fs.mkdirSync(retiredClaimsDir, { recursive: true, mode: 0o700 });
+        fs.renameSync(path.join(claimsDir, entry), path.join(retiredClaimsDir, entry));
+        moved.push(entry);
+    }
+    return moved;
+}
+async function mergeFriends(input) {
+    const nowIso = (input.now ?? (() => new Date()))().toISOString();
+    const dryRun = input.dryRun === true;
+    const sourceIds = [...new Set(input.sourceIds)];
+    if (sourceIds.length === 0 || sourceIds.includes(input.targetId)) {
+        return { ok: false, reason: "invalid_sources", message: "name at least one record to merge, other than the target" };
+    }
+    const target = await input.store.get(input.targetId);
+    if (!target || target.id !== input.targetId) {
+        return { ok: false, reason: "target_not_found", message: `friend not found: ${input.targetId}` };
+    }
+    const sources = [];
+    for (const sourceId of sourceIds) {
+        const source = await input.store.get(sourceId);
+        if (!source || source.id !== sourceId) {
+            return { ok: false, reason: "source_not_found", message: `friend not found: ${sourceId}` };
+        }
+        if ((source.kind ?? "human") !== (target.kind ?? "human")) {
+            return { ok: false, reason: "kind_mismatch", message: `cannot merge ${sourceId} into ${target.id}: an agent and a human are different friends` };
+        }
+        sources.push(source);
+    }
+    const { merged, addedExternalIds, preservedNoteKeys } = mergeFriendRecordContent(target, sources, nowIso);
+    const retiredDir = path.join(input.friendsDir, RETIRED_DIR);
+    if (dryRun) {
+        return {
+            ok: true,
+            dryRun,
+            target: merged,
+            addedExternalIds,
+            preservedNoteKeys,
+            retired: sources.map((source) => ({ friendId: source.id, name: source.name, tombstonePath: path.join(retiredDir, `${source.id}.json`), movedClaims: [] })),
+        };
+    }
+    // Order: tombstones first (nothing is lost if we stop), then the target gains the
+    // identities, then the sources leave the store and their claim journals follow them.
+    fs.mkdirSync(retiredDir, { recursive: true, mode: 0o700 });
+    const tombstones = sources.map((source) => {
+        const tombstonePath = uniqueTombstonePath(retiredDir, source.id, nowIso);
+        writePrivateJson(tombstonePath, {
+            schemaVersion: 1,
+            retiredAt: nowIso,
+            retiredInto: target.id,
+            actor: input.actor,
+            reason: input.reason,
+            record: source,
+        });
+        return { source, tombstonePath };
+    });
+    await input.store.put(target.id, merged);
+    const retired = [];
+    for (const { source, tombstonePath } of tombstones) {
+        await input.store.delete(source.id);
+        const movedClaims = moveClaimJournals(input.friendsDir, source.id);
+        retired.push({ friendId: source.id, name: source.name, tombstonePath, movedClaims });
+        (0, runtime_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.record_retired",
+            message: "retired a friend record into another record",
+            meta: { friendId: source.id, retiredInto: target.id, actor: input.actor, movedClaims: movedClaims.length },
+        });
+    }
+    const stored = (await input.store.get(target.id)) ?? merged;
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.records_merged",
+        message: "merged friend records",
+        meta: {
+            targetId: target.id,
+            sourceIds,
+            actor: input.actor,
+            reason: input.reason,
+            addedExternalIds: addedExternalIds.map((externalId) => externalId.provider),
+            preservedNoteKeys: preservedNoteKeys.length,
+        },
+    });
+    return { ok: true, dryRun, target: stored, addedExternalIds, preservedNoteKeys, retired };
+}
+function isLocalOnly(record) {
+    return record.externalIds.length > 0 && record.externalIds.every((externalId) => externalId.provider === "local");
+}
+function canonicalOrder(a, b) {
+    const notes = Object.keys(b.notes).length - Object.keys(a.notes).length;
+    if (notes !== 0)
+        return notes;
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt < b.createdAt ? -1 : 1;
+    return a.id < b.id ? -1 : 1;
+}
+/**
+ * Records are duplicates when they are human, carry only local identities, share the
+ * same name and trust level, and are joined through at least one shared local identity.
+ * The canonical record is the one with the most notes, then the oldest.
+ */
+function planFriendDedupe(records) {
+    const buckets = new Map();
+    for (const record of records) {
+        if ((record.kind ?? "human") !== "human" || !isLocalOnly(record))
+            continue;
+        const key = JSON.stringify([record.name.trim().toLowerCase(), record.trustLevel ?? "friend"]);
+        buckets.set(key, [...(buckets.get(key) ?? []), record]);
+    }
+    const groups = [];
+    for (const bucket of buckets.values()) {
+        // Union records that share any local identity.
+        const parent = bucket.map((_, index) => index);
+        const find = (index) => (parent[index] === index ? index : (parent[index] = find(parent[index])));
+        const owner = new Map();
+        bucket.forEach((record, index) => {
+            for (const externalId of record.externalIds) {
+                const key = externalIdKey(externalId);
+                const seen = owner.get(key);
+                if (seen === undefined)
+                    owner.set(key, index);
+                else
+                    parent[find(index)] = find(seen);
+            }
+        });
+        const components = new Map();
+        bucket.forEach((record, index) => {
+            const root = find(index);
+            components.set(root, [...(components.get(root) ?? []), record]);
+        });
+        for (const members of components.values()) {
+            if (members.length < 2)
+                continue;
+            const [canonical, ...duplicates] = [...members].sort(canonicalOrder);
+            groups.push({ canonical: canonical, duplicates });
+        }
+    }
+    return groups.sort((a, b) => canonicalOrder(a.canonical, b.canonical));
+}
+async function dedupeFriends(input) {
+    const listAll = input.store.listAll;
+    const records = listAll ? await listAll.call(input.store) : [];
+    const plan = planFriendDedupe(records);
+    const dryRun = input.dryRun !== false;
+    const groups = [];
+    for (const group of plan) {
+        const duplicateIds = group.duplicates.map((record) => record.id);
+        const result = await mergeFriends({
+            store: input.store,
+            friendsDir: input.friendsDir,
+            targetId: group.canonical.id,
+            sourceIds: duplicateIds,
+            actor: input.actor,
+            reason: "duplicate local records of the same person",
+            dryRun,
+            ...(input.now ? { now: input.now } : {}),
+        });
+        /* v8 ignore next -- the plan only names records it just listed; a concurrent removal is the only way here @preserve */
+        if (!result.ok)
+            throw new Error(result.message);
+        groups.push({ canonical: result.target, duplicateIds, preservedNoteKeys: result.preservedNoteKeys, addedExternalIds: result.addedExternalIds });
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.dedupe_completed",
+        message: dryRun ? "planned friend record dedupe" : "applied friend record dedupe",
+        meta: { dryRun, groups: groups.length, duplicates: groups.reduce((sum, group) => sum + group.duplicateIds.length, 0), actor: input.actor },
+    });
+    return { dryRun, groups };
+}

package/dist/repertoire/guardrails.js

@@ -307,6 +307,11 @@ exports.OURO_CLI_TRUST_MANIFEST = {
     "friend show": "friend",
     "friend create": "friend",
     "friend update": "family",
+    // Linking and merging change who the agent believes someone is: family only.
+    "friend link": "family",
+    "friend unlink": "family",
+    "friend merge": "family",
+    "friend dedupe": "family",
     "config model": "friend",
     "config models": "friend",
     "mcp list": "acquaintance",
@@ -341,7 +346,8 @@ function resolveOuroSubcommand(command) {
     /* v8 ignore next -- bare "ouro" is caught upstream by checkShellTrustGuardrails @preserve */
     if (!afterOuro)
         return null;
-    const tokens = afterOuro.split(/\s+/);
+    // `--agent <name>` may come before the subcommand; it never changes which subcommand runs.
+    const tokens = afterOuro.split(/\s+/).filter((token, index, all) => token !== "--agent" && all[index - 1] !== "--agent");
     const twoWord = tokens.length >= 2 ? `${tokens[0]} ${tokens[1]}` : null;
     // Two-word match first (e.g. "task board"), then one-word (e.g. "whoami")
     if (twoWord && exports.OURO_CLI_TRUST_MANIFEST[twoWord])
@@ -443,7 +449,7 @@ const COMMERCE_FAMILY_TOOLS = new Set(["commerce_checkout_preview", "commerce_ch
 const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
 // 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 SHEPHERD_FAMILY_TOOLS = new Set(["shepherd_overview", "shepherd_read", "shepherd_signal"]);
+const SHEPHERD_FAMILY_TOOLS = new Set(["shepherd_overview", "shepherd_read", "shepherd_signal", "shepherd_send"]);
 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) {

package/dist/repertoire/tools-base.js

@@ -32,6 +32,7 @@ const tools_orientation_1 = require("./tools-orientation");
 const tools_rsvp_1 = require("./tools-rsvp");
 const tools_habits_1 = require("./tools-habits");
 const tools_telegram_contacts_1 = require("./tools-telegram-contacts");
+const tools_friend_link_1 = require("./tools-friend-link");
 // Re-export flow tools for consumers that import them from tools-base
 var tools_flow_1 = require("./tools-flow");
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_flow_1.ponderTool; } });
@@ -86,6 +87,7 @@ exports.baseToolDefinitions = [
     ...tools_rsvp_1.rsvpToolDefinitions,
     ...tools_habits_1.habitToolDefinitions,
     tools_telegram_contacts_1.telegramContactToolDefinition,
+    tools_friend_link_1.friendLinkToolDefinition,
 ];
 // Convenience array of just the tool schemas (no handler/integration metadata).
 // Used by consumers that need the OpenAI function-tool format.

package/dist/repertoire/tools-friend-link.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.friendLinkToolDefinition = void 0;
+const identity_1 = require("../heart/identity");
+const friend_link_codes_1 = require("../mind/friend-link-codes");
+const runtime_1 = require("../nerves/runtime");
+const LINKABLE_CHANNELS = ["teams", "bluebubbles", "telegram", "mail", "voice", "mcp", "cli"];
+exports.friendLinkToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "friend_link_code",
+            description: "Issue a one-time code that links another account of the person you are talking to (for example their Teams account) to them. " +
+                "Give them the code; when they send exactly that code to you from the other account in a 1:1 chat, that account is treated as them. " +
+                "Only for family, only for themselves, and never in a group chat. The code expires in 10 minutes and works once.",
+            parameters: {
+                type: "object",
+                properties: {
+                    channel: {
+                        type: "string",
+                        enum: [...LINKABLE_CHANNELS],
+                        description: "The channel the other account will message from. Omit to accept any channel.",
+                    },
+                },
+            },
+        },
+    },
+    handler: async (args, ctx) => {
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.tool_friend_link_code",
+            message: "friend_link_code invoked",
+            meta: { channel: args.channel ?? "any" },
+        });
+        const context = ctx?.context;
+        if (!context?.friend)
+            return "no friend context: I can only issue a link code to the person I'm talking to.";
+        const friend = context.friend;
+        if (friend.trustLevel !== "family")
+            return "link codes are only for family.";
+        if (context.isGroupChat)
+            return "link codes can't be issued in a group chat. Ask me in a 1:1 chat.";
+        const channel = args.channel;
+        if (channel && !LINKABLE_CHANNELS.includes(channel))
+            return `unknown channel '${channel}'. Use one of: ${LINKABLE_CHANNELS.join(", ")}.`;
+        const issued = (0, friend_link_codes_1.issueLinkCode)({
+            agentRoot: ctx?.agentRoot ?? (0, identity_1.getAgentRoot)(),
+            friend,
+            ...(channel ? { channel: channel } : {}),
+            issuedBy: `tool:${context.channel.channel}`,
+        });
+        const where = issued.channel ? `from their ${issued.channel} account` : "from the account they want to link";
+        return `link code for ${friend.name}: ${issued.code}\nTell them to send exactly this code to me ${where}, in a 1:1 chat, before ${issued.expiresAt}. It works once.`;
+    },
+    summaryKeys: ["channel"],
+    riskProfile: { mutates: "durable_state_write", risk: "high", reason: "issues a code that links a new account to a family friend" },
+};

package/dist/repertoire/tools-shepherd.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shepherdToolDefinitions = exports.shepherdSignalToolDefinition = exports.shepherdReadToolDefinition = exports.shepherdOverviewToolDefinition = void 0;
+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"));
@@ -43,13 +43,19 @@ const runtime_1 = require("../nerves/runtime");
 const host_1 = require("../senses/shepherd/host");
 const redact_1 = require("../senses/shepherd/redact");
 const returns_1 = require("../senses/shepherd/returns");
+const tools_base_1 = require("./tools-base");
 /**
  * Shepherd's tools: every coding-agent session on this machine's terminal host with what Shepherd
- * last decided about it (`shepherd_overview`), what a session shows (`shepherd_read`), and a status
- * line or notification for the human (`shepherd_signal`).
+ * last decided about it (`shepherd_overview`), what a session shows (`shepherd_read`), a status
+ * line or notification for the human (`shepherd_signal`), and a line or key typed for the human
+ * who asked for it (`shepherd_send`).
  */
 const STATUS_MAX_CHARS = 120;
 const READ_MAX_CHARS = 16_000;
+exports.SEND_TEXT_MAX_CHARS = 2_000;
+exports.SEND_KEYS = ["enter", "escape", "up", "down", "tab", "ctrl-c", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"];
+/** Keys that can approve or choose something on a prompt: pressed only on the screen the caller last read. */
+const CHOOSING_KEYS = new Set(["enter", "tab", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"]);
 function text(value) {
     return typeof value === "string" ? value : "";
 }
@@ -118,7 +124,7 @@ exports.shepherdReadToolDefinition = {
         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.",
+            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: {
@@ -135,8 +141,11 @@ exports.shepherdReadToolDefinition = {
         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 };
+            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"],
@@ -177,4 +186,77 @@ exports.shepherdSignalToolDefinition = {
     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];
+function refused(reason, meta) {
+    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_send_refused", message: "refused to type into a terminal", meta: { ...meta, reason } });
+    return { error: reason };
+}
+exports.shepherdSendToolDefinition = {
+    tool: {
+        type: "function",
+        function: {
+            name: "shepherd_send",
+            description: `Type into one coding agent's terminal on this machine for the human you are talking with, because they asked you to. Use it only to deliver that human's own instruction or keypress ("tell it to run the tests", "approve that", "stop it"): never on your own initiative, and never for anyone else. Give exactly one of text or key. text is one line (at most ${exports.SEND_TEXT_MAX_CHARS} characters, no control characters), typed as "[Ouro for <their name>] <text>" and submitted with Enter. key is pressed alone: one of ${exports.SEND_KEYS.join(", ")} (a menu or permission prompt, escape to interrupt, ctrl-c to cancel). enter, tab, a digit, y and n can approve or choose on a prompt, so they need screen from a shepherd_read made just before, and nothing is sent if the terminal changed since; tell the human what a prompt asks before approving it unless they have seen it. Pass screen with text too when the text answers what is on screen. To interrupt and then instruct, send escape, read again, then send the text. It also types into the terminal the human has focused on this machine.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    session: { type: "string", description: "Session id or ref (surface:12) from shepherd_overview." },
+                    text: { type: "string", description: "The human's instruction, one line. Sent with the [Ouro for <name>] prefix and Enter." },
+                    key: { type: "string", enum: [...exports.SEND_KEYS], description: "One key to press instead of text." },
+                    screen: { type: "string", description: "The screen fingerprint from the shepherd_read just before. Required for enter, tab, a digit, y and n." },
+                },
+                required: ["session"],
+                additionalProperties: false,
+            },
+        },
+    },
+    handler: (args, ctx) => {
+        const session = text(args.session).trim();
+        const line = text(args.text).trim();
+        const key = text(args.key).trim().toLowerCase();
+        const seen = text(args.screen).trim();
+        const friend = ctx?.context?.friend;
+        const meta = { session, chars: line.length, key: key || null, friendId: friend?.id ?? null };
+        const refuse = (reason) => Promise.resolve(JSON.stringify(refused(reason, meta)));
+        // The private runtime talks to itself as a family "friend"; only a real family member's request may type.
+        if (!friend || friend.trustLevel !== "family" || friend.id === tools_base_1.SELF_FRIEND_ID)
+            return refuse("shepherd_send types only for a family member who asked for it in this conversation");
+        if (!session)
+            return refuse("name a session id or ref from shepherd_overview");
+        if (!line === !key)
+            return refuse("give exactly one of text or key");
+        if (key && !exports.SEND_KEYS.includes(key))
+            return refuse(`key must be one of ${exports.SEND_KEYS.join(", ")}`);
+        if (line.length > exports.SEND_TEXT_MAX_CHARS)
+            return refuse(`text must be at most ${exports.SEND_TEXT_MAX_CHARS} characters`);
+        if (/[\p{Cc}\u2028\u2029]/u.test(line))
+            return refuse("text must be one line with no control characters; press enter, escape or ctrl-c with key");
+        if (CHOOSING_KEYS.has(key) && !seen)
+            return refuse(`${key} can approve or choose on a prompt, so pass screen from a shepherd_read made just before`);
+        return withHost("shepherd_send", ctx, async (host) => {
+            const target = (await host.list()).find((entry) => entry.id === session || entry.ref === session);
+            if (!target)
+                return refused(`session ${session} is gone; check shepherd_overview`, meta);
+            // Read again right before typing, as Shepherd does before its own answers: a gone or changed screen gets nothing.
+            const now = (0, redact_1.screenFingerprint)(await host.read(target.id, redact_1.FINGERPRINT_READ_LINES));
+            if (seen && seen !== now)
+                return refused("the terminal changed since it was read, so nothing was sent; read it again", meta);
+            const typed = key ? null : `[Ouro for ${friend.name}] ${line}`;
+            if (key)
+                await host.key(target.id, key);
+            else
+                await host.prompt(target.id, typed);
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.shepherd_send",
+                message: "typed into a terminal for a family member",
+                meta: { ...meta, session: target.id, ref: target.ref, agent: target.agent, focused: target.focused, screenChecked: !!seen },
+            });
+            // The status line shows the human at the machine who typed; it is best effort, the send already happened.
+            await host.signal(target.id, `sent for ${friend.name}`.slice(0, STATUS_MAX_CHARS)).catch(() => undefined);
+            return { session: target.ref, sent: key ? { key } : { text: typed }, focused: target.focused };
+        });
+    },
+    summaryKeys: ["session", "key"],
+    riskProfile: { mutates: "external_side_effect", risk: "high", reason: "types into a coding agent's terminal for the human, which can answer or approve its prompts" },
+};
+exports.shepherdToolDefinitions = [exports.shepherdOverviewToolDefinition, exports.shepherdReadToolDefinition, exports.shepherdSignalToolDefinition, exports.shepherdSendToolDefinition];

package/dist/senses/pipeline.js

@@ -76,6 +76,7 @@ const flight_recorder_1 = require("../arc/flight-recorder");
 const context_loss_sentinel_1 = require("../heart/context-loss-sentinel");
 const cares_1 = require("../arc/cares");
 const turn_execution_lease_1 = require("../heart/turn-execution-lease");
+const friend_link_codes_1 = require("../mind/friend-link-codes");
 const VOICE_PENDING_MAX_AGE_MS = 15 * 60 * 1_000;
 const TELEGRAM_GENERIC_OUTREACH_PENDING_MAX_AGE_MS = 15 * 60 * 1_000;
 function pendingExpirationReason(channel, message, now, agentName) {
@@ -637,16 +638,16 @@ async function handleInboundTurnExclusive(input) {
             }
         }
     }
+    const firstUserMsg = input.messages.find((m) => m.role === "user");
+    const userText = firstUserMsg
+        ? (typeof firstUserMsg.content === "string"
+            ? firstUserMsg.content
+            : Array.isArray(firstUserMsg.content)
+                ? firstUserMsg.content.find((p) => p.type === "text")?.text ?? ""
+                : /* v8 ignore next -- defensive: content is always string or array @preserve */ "")
+        : "";
     // Step 0b: Slash command interception (before friend resolution / agent turn)
     {
-        const firstUserMsg = input.messages.find((m) => m.role === "user");
-        const userText = firstUserMsg
-            ? (typeof firstUserMsg.content === "string"
-                ? firstUserMsg.content
-                : Array.isArray(firstUserMsg.content)
-                    ? firstUserMsg.content.find((p) => p.type === "text")?.text ?? ""
-                    : /* v8 ignore next -- defensive: content is always string or array @preserve */ "")
-            : "";
         const parsed = (0, commands_1.parseSlashCommand)(userText);
         if (parsed) {
             const registry = (0, commands_1.getSharedCommandRegistry)();
@@ -684,6 +685,27 @@ async function handleInboundTurnExclusive(input) {
             senseType: input.capabilities.senseType,
         },
     });
+    // Step 1b: Identity link code. Runs before the trust gate so an identity the agent
+    // does not trust yet can prove it belongs to someone it does. Never a model turn.
+    if (input.channel !== "inner" && (0, friend_link_codes_1.parseLinkCode)(userText)) {
+        const agentRoot = (0, identity_1.getAgentRoot)();
+        const redemption = (await (0, friend_link_codes_1.redeemLinkCode)({
+            agentRoot,
+            friendsDir: path.join(agentRoot, "friends"),
+            store: input.friendStore,
+            text: userText,
+            claimant: resolvedContext.friend,
+            channel: input.channel,
+            isGroupChat: input.isGroupChat ?? false,
+        }));
+        input.callbacks.onTextChunk(redemption.reply);
+        return {
+            resolvedContext: redemption.status === "linked" ? { ...resolvedContext, friend: redemption.friend } : resolvedContext,
+            gateResult: { allowed: true },
+            turnOutcome: "command",
+            commandAction: "response",
+        };
+    }
     // Step 2: Trust gate
     const gateInput = {
         friend: resolvedContext.friend,

package/dist/senses/shepherd/cmux.js

@@ -70,7 +70,8 @@ const STOP_HOOKS = new Set(["Stop", "StopFailure"]);
 const IDLE_HOOKS = new Set([...STOP_HOOKS, "SessionStart"]);
 /** Hooks that say nothing about whether the main agent is working. */
 const NEUTRAL_HOOKS = new Set(["SubagentStop", "Notification"]);
-const NAMED_KEYS = new Set(["enter", "escape", "up", "down", "tab"]);
+/** Keys cmux presses with `surface.send_key`, by its own names; every other key is typed as its character. */
+const NAMED_KEYS = { enter: "enter", escape: "escape", up: "up", down: "down", tab: "tab", "ctrl-c": "ctrl+c" };
 const SUBMIT_DELAY_MS = 300;
 /** A timer that can be cancelled; the sense and the host take it as an option so tests can drive time. */
 function realSchedule(fn, ms) {
@@ -167,8 +168,9 @@ function createCmuxHost(client, options = {}) {
         async key(sessionId, key) {
             const surface = await locate(sessionId);
             const target = { workspace_id: surface.workspaceId, surface_id: surface.id };
-            if (NAMED_KEYS.has(key))
-                await client.call("surface.send_key", { ...target, key });
+            const named = NAMED_KEYS[key];
+            if (named)
+                await client.call("surface.send_key", { ...target, key: named });
             else
                 await client.call("surface.send_text", { ...target, text: key });
         },