@ouro.bot/cli 0.1.0-alpha.929 → 0.1.0-alpha.930

package/changelog.json

@@ -1,6 +1,13 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.930",
+      "changes": [
+        "Receive session-native Shepherd feedback with automatic source context, durable receipts, private Teams acknowledgements and correlated clarification replies.",
+        "Use each supervising agent's configured display name across Shepherd entry points, addressing and acknowledgements."
+      ]
+    },
     {
       "version": "0.1.0-alpha.929",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.929",
+  "runtimeVersion": "0.1.0-alpha.930",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.929</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.930</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/auth/auth-flow.js

@@ -48,6 +48,7 @@ const runtime_1 = require("../../nerves/runtime");
 const identity_1 = require("../identity");
 const migrate_config_1 = require("../migrate-config");
 const provider_models_1 = require("../provider-models");
+const agent_presentation_1 = require("../../senses/shepherd/agent-presentation");
 const provider_credentials_1 = require("../provider-credentials");
 const vault_unlock_1 = require("../../repertoire/vault-unlock");
 const ANTHROPIC_SETUP_TOKEN_PREFIX = "sk-ant-oat01-";
@@ -107,6 +108,7 @@ function readAgentConfigForAgent(agentName, bundlesRoot = (0, identity_1.getAgen
     // equivalent configs for the same file.
     const config = {
         ...parsed,
+        displayName: (0, agent_presentation_1.validateAgentDisplayName)(parsed.displayName),
         senses: (0, identity_1.normalizeSenses)(parsed.senses, configPath),
         habitPaidTurnsPerDay: (0, identity_1.normalizeHabitPaidTurnsPerDay)(agentName, parsed.habitPaidTurnsPerDay, configPath),
     };

package/dist/heart/daemon/daemon.js

@@ -2049,6 +2049,9 @@ class OuroDaemon {
             case "agent.senseTurn":
                 return handleAgentSenseTurn(command, { socketPath: this.socketPath });
             /* v8 ignore stop */
+            case "agent.shepherdFeedback":
+            case "agent.shepherdFeedbackStatus":
+                return (await Promise.resolve().then(() => __importStar(require("../../senses/shepherd/feedback-submit")))).executeFeedbackCommand(command);
             case "cron.list": {
                 const jobs = this.scheduler.listJobs();
                 const summary = jobs.length === 0

package/dist/heart/identity.js

@@ -63,6 +63,7 @@ const path = __importStar(require("path"));
 const runtime_1 = require("../nerves/runtime");
 const migrate_config_1 = require("./migrate-config");
 const autonomy_budget_1 = require("./autonomy-budget");
+const agent_presentation_1 = require("../senses/shepherd/agent-presentation");
 var autonomy_budget_2 = require("./autonomy-budget");
 Object.defineProperty(exports, "normalizeHabitPaidTurnsPerDay", { enumerable: true, get: function () { return autonomy_budget_2.normalizeHabitPaidTurnsPerDay; } });
 /** Single source of truth for per-provider credential field names, env var mappings, and prompt labels. */
@@ -515,6 +516,7 @@ function loadAgentConfig(owner) {
     // Required<AgentConfig> contract test in identity-contract.test.ts.
     const config = {
         ...parsed,
+        displayName: (0, agent_presentation_1.validateAgentDisplayName)(parsed.displayName),
         version,
         enabled,
         humanFacing,

package/dist/heart/mcp/mcp-server.js

@@ -46,6 +46,8 @@ const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
 const session_id_resolver_1 = require("../daemon/session-id-resolver");
 const pending_1 = require("../../mind/pending");
+const feedback_source_1 = require("../../senses/shepherd/feedback-source");
+const redact_1 = require("../../senses/shepherd/redact");
 exports.SENSE_TURN_MAX_RETRIES = 3;
 exports.SENSE_TURN_RETRY_DELAYS_MS = [1000, 2000, 4000];
 exports.SENSE_TURN_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
@@ -416,12 +418,58 @@ function createMcpServer(options) {
         const toolName = params.name;
         const toolArgs = (params.arguments ?? {});
         /* v8 ignore stop */
+        if (toolName === "shepherd_feedback" || toolName === "shepherd_feedback_status") {
+            await runFeedbackTool(request, toolName, toolArgs);
+            return;
+        }
         // ── Conversation tools: these run a real agent turn ──
         const conversationMessage = buildConversationMessage(toolName, toolArgs);
         if (conversationMessage !== null) {
             await runConversationTool(request, conversationMessage);
             return;
         }
+        async function runFeedbackTool(request, toolName, args) {
+            const requestId = stringArg(args, "request_id");
+            const validRequestId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(requestId);
+            try {
+                const submitting = toolName === "shepherd_feedback";
+                const allowed = submitting ? ["request_id", "feedback", "context"] : ["request_id"];
+                if (!validRequestId || Object.keys(args).some(key => !allowed.includes(key)))
+                    throw new Error("Invalid feedback request identity or routing arguments");
+                const feedback = stringArg(args, "feedback");
+                if (submitting && (!feedback.trim() || feedback.length > 2000 ||
+                    args.context !== undefined && (typeof args.context !== "string" || Buffer.byteLength(JSON.stringify(args.context)) > 8192))) {
+                    throw new Error("Feedback must be 1–2000 characters with at most 8 KiB of context");
+                }
+                const command = submitting
+                    ? { kind: "agent.shepherdFeedback", agent, friendId, origin: await (0, feedback_source_1.resolveFeedbackOrigin)(),
+                        submission: { requestId, feedback, ...(typeof args.context === "string" ? { context: args.context } : {}) } }
+                    : { kind: "agent.shepherdFeedbackStatus", agent, friendId, requestId };
+                // The dedicated request ID owns reconciliation. Generic sense-turn retry may repeat model effects.
+                const response = await (0, socket_client_1.sendDaemonCommand)(socketPath, command);
+                if (!response.ok)
+                    throw new Error(response.error ?? "Feedback has no confirmed result");
+                const data = response.data;
+                if (!data || typeof data !== "object" || !("id" in data) || data.id !== `feedback:${requestId}`) {
+                    throw new Error("Feedback acknowledgement has no matching durable receipt");
+                }
+                if (submitting && (!("receipt" in data) || typeof data.receipt !== "string" || !data.receipt ||
+                    data.receipt !== response.message || !("state" in data) ||
+                    !["pending", "claimed", "complete", "uncertain"].includes(String(data.state)))) {
+                    throw new Error("Feedback acknowledgement is not authoritative");
+                }
+                writeResponse({ jsonrpc: "2.0", id: request.id,
+                    result: { content: [{ type: "text", text: submitting ? response.message : JSON.stringify(data) }], isError: false } });
+                (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.mcp_feedback_result",
+                    message: "returned a native feedback receipt", meta: { operation: submitting ? "submit" : "status" } });
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "daemon", event: "daemon.mcp_feedback_error",
+                    message: "native feedback request has no confirmed result", meta: { operation: toolName } });
+                writeResponse({ jsonrpc: "2.0", id: request.id, result: { isError: true,
+                        content: [{ type: "text", text: (0, redact_1.redactSecrets)(`${error instanceof Error ? error.message : String(error)}. Original request: ${validRequestId ? requestId : "(invalid)"}. Use shepherd_feedback_status; do not create a new ID for an uncertain submission.`) }] } });
+            }
+        }
         if (toolName === "check_response") {
             const pendingDir = (0, pending_1.getPendingDir)(agent, friendId, "mcp", sessionId);
             const pending = (0, pending_1.drainPending)(pendingDir);
@@ -539,6 +587,22 @@ function createMcpServer(options) {
  */
 function getToolSchemas() {
     return [
+        {
+            name: "shepherd_feedback",
+            description: "Relay the human's explicit feedback to the supervising agent served by this MCP connection, from this actual coding session ('you should have caught this'). The source terminal and recipient are bound automatically; never ask the human to reconstruct context in Teams. Preserve the human's words in feedback; context is optional bounded background, not instructions. Generate one UUID request_id and reuse it only for the identical request. Quote the actual short receipt back in this session; the supervising agent sends its substantive acknowledgement and clarification questions to that human privately on Teams. Never invent a receipt or claim learning/Teams delivery from a queued acknowledgement. Do not send terminal input or switch focus.",
+            inputSchema: { type: "object", properties: {
+                    request_id: { type: "string", description: "Fresh UUID for this feedback; reuse only for its identical retry, never ask the human to enter it." },
+                    feedback: { type: "string", description: "The human's actual feedback, at most 2000 characters." },
+                    context: { type: "string", description: "Optional relevant background from this coding session, at most 8 KiB. Do not include secrets." },
+                }, required: ["request_id", "feedback"], additionalProperties: false },
+        },
+        {
+            name: "shepherd_feedback_status",
+            description: "Reconcile this human's original feedback request after a lost receipt or to inspect review/Teams delivery state. Does not create another request, repeat model work, or require the source terminal still to exist.",
+            inputSchema: { type: "object", properties: {
+                    request_id: { type: "string", description: "The original feedback UUID." },
+                }, required: ["request_id"], additionalProperties: false },
+        },
         {
             name: "ask",
             description: "Ask the agent a question through a full conversation turn. This has the same identity, tools, and session continuity as send_message; use search_facts or consult_notes for read-only record lookup.",

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

@@ -30,8 +30,10 @@ function fingerprint(name, args) {
  * the existing machine connection primitives. Resolving it never reads a screen, signals, presses a key or sends.
  */
 async function targetFor(ctx, args) {
-    if (text(args.session))
-        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, text(args.session), text(args.host) || undefined);
+    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) {
@@ -43,10 +45,8 @@ async function targetFor(ctx, args) {
             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: [] };
     }
-    const session = text(args.session);
     if (!session)
         throw new Error("name a session from Shepherd history or overview");
-    const hostName = text(args.host);
     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");
@@ -79,7 +79,8 @@ function definition(name, description, properties, required, run, mutates = fals
             if (!ctx?.agentRoot || !ctx.agentName)
                 return json({ error: "Shepherd guidance needs an agent runtime" });
             try {
-                const request = { actorId: friend.id, requestId: text(args.request_id), requestFingerprint: fingerprint(name, args) };
+                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) {
@@ -104,8 +105,12 @@ function definition(name, description, properties, required, run, mutates = fals
 }
 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 => (!text(args.session) || r.session === text(args.session)) && (!text(args.host) || r.host === text(args.host)))
+            .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) };
@@ -141,7 +146,7 @@ exports.shepherdGuidanceToolDefinitions = [
         }, 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) {
+        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) };
         }

package/dist/repertoire/tools-shepherd.js

@@ -47,6 +47,7 @@ const tools_base_1 = require("./tools-base");
 const tools_shepherd_guidance_1 = require("./tools-shepherd-guidance");
 const guidance_1 = require("../senses/shepherd/guidance");
 const target_binding_1 = require("../senses/shepherd/target-binding");
+const agent_presentation_1 = require("../senses/shepherd/agent-presentation");
 /**
  * Shepherd's tools: every coding-agent session on this machine's terminal host with a current screen
  * and what Shepherd last decided about it (`shepherd_overview`), a deeper read (`shepherd_read`), a status
@@ -123,7 +124,7 @@ exports.shepherdOverviewToolDefinition = {
         type: "function",
         function: {
             name: "shepherd_overview",
-            description: "A live, read-only snapshot of every terminal on this machine's host (cmux): agent, folder, workspace and tab, plus a freshly read, redacted, bounded currentScreen with its observation time. Use currentScreen to answer what agents are doing now in one reply; lastReturn is historical and must not be presented as current status. Include every listed terminal exactly once with its complete ref (surface:12), including plain shells and Ouro composers; never omit a row or abbreviate subsequent refs to bare numbers. terminalCount is authoritative; derive disjoint category counts from those same rows. Classify activity as working, needs human, waiting on outside dependency, idle/local work finished, shell, or unknown. An idle prompt does not establish delivered work: do not use a generic Done bucket for locally finished work that still needs review, approval, merge, publication, deployment or verification. State those remaining steps inline. An agent explicitly reporting an outside reviewer wait belongs under waiting even when its prompt is idle; that is neither premature completion nor a request for routine continuation. A currentScreen.error explicitly identifies a terminal that could not be read; explain it inline with the other sessions, not by asking for another turn. For deeper details use shepherd_read. Historical lastReturn includes the prior judgment time, kind, action and reason.",
+            description: "A live, read-only snapshot of every terminal on this machine's host (cmux): agent, folder, workspace and tab, plus a freshly read, redacted, bounded currentScreen with its observation time. Use currentScreen to answer what agents are doing now in one reply; lastReturn is historical and must not be presented as current status. Include every listed terminal exactly once with its complete ref (surface:12), including plain shells and supervisor composers; never omit a row or abbreviate subsequent refs to bare numbers. terminalCount is authoritative; derive disjoint category counts from those same rows. Classify activity as working, needs human, waiting on outside dependency, idle/local work finished, shell, or unknown. An idle prompt does not establish delivered work: do not use a generic Done bucket for locally finished work that still needs review, approval, merge, publication, deployment or verification. State those remaining steps inline. An agent explicitly reporting an outside reviewer wait belongs under waiting even when its prompt is idle; that is neither premature completion nor a request for routine continuation. A currentScreen.error explicitly identifies a terminal that could not be read; explain it inline with the other sessions, not by asking for another turn. For deeper details use shepherd_read. Historical lastReturn includes the prior judgment time, kind, action and reason.",
             parameters: { type: "object", properties: {}, additionalProperties: false },
         },
     },
@@ -227,12 +228,12 @@ exports.shepherdSendToolDefinition = {
         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.`,
+            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 "[<your configured name> for <their name>] <text>" and submitted with Enter. key is pressed alone: one of ${exports.SEND_KEYS.join(", ")} (a menu or permission prompt, escape to interrupt, ctrl-c to cancel). enter, tab, a digit, y and n can approve or choose on a prompt, so they need screen from a shepherd_read made just before, and nothing is sent if the terminal changed since; tell the human what a prompt asks before approving it unless they have seen it. Pass screen with text too when the text answers what is on screen. To interrupt and then instruct, send escape, read again, then send the text. It also types into the terminal the human has focused on this machine.`,
             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." },
+                    text: { type: "string", description: "The human's instruction, one line. Sent with [<your configured name> for <their name>] and Enter." },
                     key: { type: "string", enum: [...exports.SEND_KEYS], description: "One key to press instead of text." },
                     screen: { type: "string", description: "The screen fingerprint from the shepherd_read just before. Required for enter, tab, a digit, y and n." },
                 },
@@ -273,7 +274,7 @@ exports.shepherdSendToolDefinition = {
             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}`;
+            const typed = key ? null : `[${(0, agent_presentation_1.readAgentPresentation)(ctx.agentName, ctx.agentRoot).name} for ${friend.name}] ${line}`;
             if (key)
                 await host.key(target.id, key);
             else

package/dist/repertoire/tools.js

@@ -207,7 +207,8 @@ function selectToolsForChannel(capabilities, toolPreferences, _context, provider
         ...(inner ? [tools_flow_1.restTool] : [tools_flow_1.observeTool, tools_flow_1.settleTool]),
         ...(capabilities?.chatStyle ? [tools_flow_1.speakTool] : []),
     ].filter((tool) => (!sanctuary || (knownSanctuaryProfile && tool.function.name !== "observe"))
-        && (!relationship || relationship.advertisedToolNames.includes(tool.function.name)));
+        && (!relationship || relationship.advertisedToolNames.includes(tool.function.name))
+        && (!context?.allowedEngineTools || context.allowedEngineTools.includes(tool.function.name)));
     return Object.freeze({
         ordinary: Object.freeze(ordinary.map((definition) => definition === hostTool ? definition : Object.freeze({
             ...definition,

package/dist/senses/shepherd/agent-presentation.js

@@ -0,0 +1,88 @@
+"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.validateAgentDisplayName = validateAgentDisplayName;
+exports.agentPresentation = agentPresentation;
+exports.readAgentPresentation = readAgentPresentation;
+exports.agentAddressPattern = agentAddressPattern;
+exports.stripAgentAddress = stripAgentAddress;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+function validateAgentDisplayName(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.length || value.length > 80 || value.trim() !== value ||
+        /[<>\[\]\\\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value)) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.agent_display_name_invalid",
+            message: "configured agent displayName is invalid", meta: { field: "displayName" } });
+        throw new Error("agent.json displayName must be 1–80 characters without markup, controls or surrounding whitespace");
+    }
+    return value;
+}
+function agentPresentation(agent, config) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(agent) || agent.includes("..")) {
+        throw new Error("agent presentation requires a safe configured identifier");
+    }
+    const name = validateAgentDisplayName(config.displayName) ?? agent;
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.agent_presentation_resolved",
+        message: "resolved explicit agent presentation", meta: { configured: config.displayName !== undefined } });
+    return { name, aliases: [...new Set([name, agent])] };
+}
+function readAgentPresentation(agent, root) {
+    let encoded;
+    try {
+        encoded = fs.readFileSync(path.join(root, "agent.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.agent_presentation_missing",
+            message: "agent presentation config is missing; using its routing identifier", meta: { configured: false } });
+        return agentPresentation(agent, {});
+    }
+    const config = JSON.parse(encoded);
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        throw new Error("agent.json presentation must be an object");
+    return agentPresentation(agent, { displayName: validateAgentDisplayName(config.displayName) });
+}
+function agentAddressPattern(aliases) {
+    if (!aliases.length)
+        return "(?!)";
+    return `^@(?:${aliases.map(alias => alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?:\\s+|$)`;
+}
+function stripAgentAddress(message, aliases) {
+    return message.replace(new RegExp(agentAddressPattern(aliases), "iu"), "");
+}

package/dist/senses/shepherd/attention-page.js

@@ -2,12 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_ATTENTION_BODY_BYTES = void 0;
 exports.attentionPage = attentionPage;
+const agent_presentation_1 = require("./agent-presentation");
 exports.MAX_ATTENTION_BODY_BYTES = 16_384;
 /** No model content or target metadata is interpolated into executable HTML. */
-function attentionPage(nonce) {
+function attentionPage(nonce, presentation = (0, agent_presentation_1.agentPresentation)("Agent", {})) {
     (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_attention_page_rendered", message: "rendered the independent session attention view" });
+    const name = presentation.name.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Ouro</title>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${name}</title>
 <style nonce="${nonce}">
 :root{color-scheme:dark;font:15px -apple-system,BlinkMacSystemFont,sans-serif;color:#eee;background:#17191d}
 *{box-sizing:border-box}body{margin:0}main{max-width:680px;height:100dvh;min-height:340px;margin:auto;display:flex;flex-direction:column;padding:20px;gap:16px}
@@ -21,12 +23,13 @@ textarea{width:100%;resize:none;min-height:82px;outline:none}textarea:focus{bord
 button{cursor:pointer}button:disabled{opacity:.45;cursor:default}#send{background:#a8b8ff;color:#141823;border-color:transparent;font-weight:600}
 #status{font-size:12px;color:#9da4ae}#error{color:#e0b275;font-size:13px;margin:0}form{display:flex;flex-direction:column;gap:8px}
 </style></head><body><main>
-<header><h1>Ouro</h1><span class="badge">Your session companion</span></header>
+<header><h1>${name}</h1><span class="badge">Your session companion</span></header>
 <label for="target">About<select id="target" aria-label="Session to discuss"></select><button id="refresh" type="button" aria-label="Refresh session choices">Refresh</button></label>
-<section id="conversation" aria-live="polite"><p id="empty">Ask Ouro about this session, steer the work, or correct a handback.<br>Your coding agent's input stays untouched.</p></section>
-<p id="error" role="alert"></p><form id="compose"><textarea id="draft" aria-label="Message Ouro" placeholder="Message Ouro..." maxlength="12000"></textarea>
-<footer><span id="status">Independent of the coding agent</span><div class="actions"><button id="recover" type="button" hidden>Reconnect</button><button id="cancel" type="button" hidden>Cancel Ouro</button><button id="send" type="submit" disabled>Send</button></div></footer></form>
+<section id="conversation" aria-live="polite"><p id="empty">Ask ${name} about this session, steer the work, or correct a handback.<br>Your coding agent's input stays untouched.</p></section>
+<p id="error" role="alert"></p><form id="compose"><textarea id="draft" aria-label="Message ${name}" placeholder="Message ${name}..." maxlength="12000"></textarea>
+<footer><span id="status">Independent of the coding agent</span><div class="actions"><button id="recover" type="button" hidden>Reconnect</button><button id="cancel" type="button" hidden>Cancel ${name}</button><button id="send" type="submit" disabled>Send</button></div></footer></form>
 </main><script nonce="${nonce}">
+const agentName=${JSON.stringify(presentation.name).replaceAll("<", "\\u003c")},address=new RegExp(${JSON.stringify((0, agent_presentation_1.agentAddressPattern)(presentation.aliases))},'iu');
 const fragment=new URLSearchParams(location.hash.slice(1));const initialTarget=fragment.get('session');const token=fragment.get('token')||location.hash.slice(1).split('&')[0]||sessionStorage.getItem('ouroAttentionToken');
 if(token){sessionStorage.setItem('ouroAttentionToken',token);history.replaceState(null,'',location.pathname);}
 const view=sessionStorage.getItem('ouroAttentionView')||crypto.randomUUID();sessionStorage.setItem('ouroAttentionView',view);
@@ -49,7 +52,7 @@ async function api(route,body) {
     ...(body?{body:JSON.stringify(body)}:{})
   });
   const data=await response.json();
-  if(!response.ok) {const error=Error(data.error||'Ouro could not accept this action.');error.status=response.status;throw error;}
+  if(!response.ok) {const error=Error(data.error||agentName+' could not accept this action.');error.status=response.status;throw error;}
   return data;
 }
 function acknowledge(submitted) {
@@ -86,13 +89,13 @@ function render(next) {
     if(atBottom)conversation.scrollTop=conversation.scrollHeight;
   } else if(!next.messages.length&&!el('empty')) {
     conversation.replaceChildren();
-    const p=document.createElement('p');p.id='empty';p.textContent="Ask Ouro about this session. Your coding agent's input stays untouched.";conversation.append(p);
+    const p=document.createElement('p');p.id='empty';p.textContent="Ask "+agentName+" about this session. Your coding agent's input stays untouched.";conversation.append(p);
   }
   messagesSignature=nextMessages;
   const available=next.targets.some(target=>target.id===next.target);
   el('send').disabled=next.active||sending||!bindingReady||!available||pendingFault||!!(pending&&pending.target!==next.target);
   el('cancel').hidden=!next.active;el('recover').hidden=!next.active&&!pending;
-  el('status').textContent=next.active?'Ouro is replying...':!next.targets.length?'No coding sessions available':!available?'Choose an available session':'Independent of the coding agent';
+  el('status').textContent=next.active?agentName+' is replying...':!next.targets.length?'No coding sessions available':!available?'Choose an available session':'Independent of the coding agent';
 }
 async function refresh() {
   try {render(await api('/state'));}
@@ -115,7 +118,7 @@ el('compose').onsubmit=async event=>{
   event.preventDefault();
   if(sending||!bindingReady||pendingFault||!state?.target||state.active)return;
   const message=el('draft').value;
-  if(!message.replace(/^@ouro(?:\\s+|$)/i,'').trim())return;
+  if(!message.replace(address,'').trim())return;
   if(pending&&(pending.message!==message||pending.target!==state.target)) {
     el('error').textContent='Reconnect before changing a message whose acknowledgement was lost.';return;
   }

package/dist/senses/shepherd/attention-sidebar.js

@@ -38,9 +38,11 @@ exports.installAttentionSidebar = installAttentionSidebar;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const runtime_1 = require("../../nerves/runtime");
+const agent_presentation_1 = require("./agent-presentation");
 const MARKER = "// Generated by Ouro session attention.";
 /** Opens beside the coding terminal without moving focus; the view then pins a fresh hint. */
-function attentionSidebar(url) {
+function attentionSidebar(url, name = "Agent") {
+    (0, agent_presentation_1.validateAgentDisplayName)(name);
     const parsed = new URL(url);
     if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1" || !/^[0-9a-f]{64}$/.test(parsed.hash.slice(1))) {
         throw new Error("Attention sidebar requires its private loopback entry.");
@@ -48,17 +50,17 @@ function attentionSidebar(url) {
     (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_attention_sidebar_generated", message: "generated the native session attention entry", meta: { format: "swift" } });
     return `${MARKER}
 VStack(alignment: .leading, spacing: 12) {
-    Text("Ouro").font(.headline)
+    Text(${JSON.stringify(name)}).font(.headline)
     Text("Talk about this session without touching its input.").font(.caption).foregroundColor(.secondary)
     ForEach(workspaces.filter { $0.selected }) { w in
         Button(action: { cmux("browser.open_split", focus: false, workspace_id: w.id, url: ${JSON.stringify(url)}) }) {
-            Text("Talk to Ouro")
+            Text(${JSON.stringify(`Talk to ${name}`)})
         }
     }
 }.padding(16)
 `;
 }
-function installAttentionSidebar(directory, url, agent = "ouro") {
+function installAttentionSidebar(directory, url, agent = "ouro", displayName = agent) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent))
         throw new Error("Attention requires a safe agent name.");
     const file = path.join(directory, `ouro-attention-${agent}.swift`);
@@ -67,7 +69,7 @@ function installAttentionSidebar(directory, url, agent = "ouro") {
         throw new Error("An independently authored ouro-attention sidebar already exists; it was not overwritten.");
     }
     const staging = `${file}.pending`;
-    fs.writeFileSync(staging, attentionSidebar(url), { mode: 0o600 });
+    fs.writeFileSync(staging, attentionSidebar(url, displayName), { mode: 0o600 });
     fs.chmodSync(staging, 0o600);
     fs.renameSync(staging, file);
     return file;

package/dist/senses/shepherd/attention.js

@@ -47,12 +47,18 @@ const composer_1 = require("./composer");
 const surface_1 = require("./surface");
 const attention_page_1 = require("./attention-page");
 const attention_sidebar_1 = require("./attention-sidebar");
+const identity_1 = require("../../heart/identity");
+const agent_presentation_1 = require("./agent-presentation");
 function suggestedTarget(targets) {
     const hints = targets.filter(target => target.selected);
     return hints.length === 1 ? hints[0] : targets.length === 1 ? targets[0] : null;
 }
 /** An owner-only loopback view of the existing fixed-target composer, not another model runtime. */
 async function startShepherdAttention(options) {
+    const presentation = options.displayName === undefined
+        ? (0, agent_presentation_1.readAgentPresentation)(options.agent, (0, identity_1.getAgentRoot)(options.agent))
+        : (0, agent_presentation_1.agentPresentation)(options.agent, { displayName: options.displayName });
+    const name = presentation.name;
     const friendId = await (options.resolveOwner ?? (() => (0, surface_1.resolveExistingLocalOwner)((0, surface_1.localShepherdFriendStore)(options.agent))))();
     const makeClient = options.client ?? (() => new frontend_socket_client_1.SocketFrontendClient(options.socketPath));
     const discovery = makeClient();
@@ -78,7 +84,7 @@ async function startShepherdAttention(options) {
     const getComposer = (view, target) => {
         if (!view.composer)
             view.composer = new composer_1.ShepherdComposer({
-                client: makeClient(), agent: options.agent, friendId, target,
+                client: makeClient(), agent: options.agent, displayName: name, friendId, target,
                 notice: text => append(view, "notice", text), answer: text => append(view, "ouro", text),
             });
         return view.composer;
@@ -103,7 +109,7 @@ async function startShepherdAttention(options) {
                     "Content-Security-Policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'`,
                     "Referrer-Policy": "no-referrer", "X-Content-Type-Options": "nosniff",
                 });
-                return response.end((0, attention_page_1.attentionPage)(nonce));
+                return response.end((0, attention_page_1.attentionPage)(nonce, presentation));
             }
             if (request.headers["x-ouro-attention"] !== token)
                 return json(403, { error: "Open attention from its local entry." });
@@ -155,7 +161,7 @@ async function startShepherdAttention(options) {
             }
             if (request.url === "/select") {
                 if (view.composer?.busy)
-                    return json(409, { error: "Wait for or cancel Ouro before changing the session." });
+                    return json(409, { error: `Wait for or cancel ${name} before changing the session.` });
                 if (typeof fields.target !== "string")
                     return json(400, { error: "Choose a session." });
                 const refresh = makeClient();
@@ -166,7 +172,7 @@ async function startShepherdAttention(options) {
                     refresh.close();
                 }
                 if (view.composer?.busy)
-                    return json(409, { error: "Ouro started replying while the session list refreshed; the conversation was not changed." });
+                    return json(409, { error: `${name} started replying while the session list refreshed; the conversation was not changed.` });
                 const next = fields.target === "current" ? suggestedTarget(targets) : (0, composer_1.selectShepherdTarget)(targets, fields.target);
                 if (view.target?.id !== next?.id) {
                     view.composer?.close();
@@ -178,8 +184,8 @@ async function startShepherdAttention(options) {
             }
             if (request.url === "/send") {
                 if (typeof fields.id !== "string" || !surface_1.SHEPHERD_UUID.test(fields.id)
-                    || typeof fields.message !== "string" || !fields.message.replace(/^@ouro(?:\s+|$)/i, "").trim())
-                    return json(400, { error: "Enter a message for Ouro." });
+                    || typeof fields.message !== "string" || !(0, agent_presentation_1.stripAgentAddress)(fields.message, presentation.aliases).trim())
+                    return json(400, { error: `Enter a message for ${name}.` });
                 if (!view.target)
                     return json(409, { error: "Choose the session you want to discuss." });
                 if (fields.target !== undefined && fields.target !== view.target.id)
@@ -191,7 +197,7 @@ async function startShepherdAttention(options) {
                     return json(202, state(view, viewId, fields.id));
                 }
                 if (view.composer?.busy)
-                    return json(409, { error: "Ouro is already replying. Your draft has not been sent." });
+                    return json(409, { error: `${name} is already replying. Your draft has not been sent.` });
                 if (submissions.size >= 2_000)
                     return json(409, { error: "Attention reached its message limit. Restart Shepherd before sending more messages." });
                 const bound = getComposer(view, view.target);
@@ -245,9 +251,10 @@ async function startShepherdAttention(options) {
     };
 }
 async function startManagedShepherdAttention(options) {
-    const app = await startShepherdAttention(options);
+    const presentation = (0, agent_presentation_1.readAgentPresentation)(options.agent, (0, identity_1.getAgentRoot)(options.agent));
+    const app = await startShepherdAttention({ ...options, displayName: presentation.name });
     try {
-        (0, attention_sidebar_1.installAttentionSidebar)(path.join(os.homedir(), ".config/cmux/sidebars"), app.url, options.agent);
+        (0, attention_sidebar_1.installAttentionSidebar)(path.join(os.homedir(), ".config/cmux/sidebars"), app.url, options.agent, presentation.name);
         const { socketPath, auth } = options.cmuxConnection;
         const validated = (0, node_child_process_1.spawnSync)("cmux", ["--socket", socketPath, "sidebar", "validate", `ouro-attention-${options.agent}`], {
             encoding: "utf8",
@@ -258,7 +265,7 @@ async function startManagedShepherdAttention(options) {
             },
         });
         if (validated.error || validated.status !== 0)
-            throw new Error(`Could not validate Ouro's native entry: ${validated.error?.message ?? validated.stderr}`);
+            throw new Error(`Could not validate ${presentation.name}'s native entry: ${validated.error?.message ?? validated.stderr}`);
         return app;
     }
     catch (error) {
@@ -271,7 +278,7 @@ async function runShepherdAttention(options) {
     try {
         const opened = (0, node_child_process_1.spawnSync)("cmux", ["browser", "open", app.url + (options.session ? `&session=${options.session}` : ""), "--focus", "false"], { encoding: "utf8" });
         if (opened.error || opened.status !== 0)
-            throw new Error(`Could not open Ouro attention in cmux: ${opened.error?.message ?? opened.stderr}`);
+            throw new Error(`Could not open session attention in cmux: ${opened.error?.message ?? opened.stderr}`);
         await new Promise(resolve => {
             const stop = () => {
                 process.removeListener("SIGINT", stop);

package/dist/senses/shepherd/cmux.js

@@ -147,7 +147,7 @@ function createCmuxHost(client, options = {}) {
         })));
         const identities = await (options.identifyTerminals ?? terminal_process_1.identifyTerminalProcesses)(entries.filter((entry) => entry.type === "terminal" && entry.tty).map((entry) => entry.tty));
         return entries.map((entry) => {
-            const identity = entry.tty ? identities.get(entry.tty) : undefined;
+            const identity = entry.tty ? identities.get(entry.tty.replace(/^\/dev\//, "")) : undefined;
             return { ...entry, agent: identity?.agent ?? entry.agent, cwd: identity?.cwd ?? entry.cwd };
         });
     }