@ouro.bot/cli 0.1.0-alpha.204 → 0.1.0-alpha.206

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_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.206",
+      "changes": [
+        "feat: capability discovery and tiered self-configuration — config registry with tier-aware metadata (T1 self-service, T2 proposal, T3 operator-only), read_config tool with topic-filtered discovery, update_config tool for T1 immediate changes, propose_config tool for T2 operator-approval flow, version-change surfacing in start-of-turn packet via buildCapabilitiesSection"
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.205",
+      "changes": [
+        "refactor: enforce subsystem boundaries — eliminate all heart/ and nerves/ static imports from senses/, move AttentionItem type to heart/, surfaceToolDef to repertoire/, SteeringFollowUpEffect to heart/turn-coordinator, inline BlueBubbles runtime state reader in daemon"
+      ]
+    },
     {
       "version": "0.1.0-alpha.204",
       "changes": [

package/dist/heart/agent-entry.js

@@ -1,4 +1,37 @@
 "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 });
 // Unified agent runtime entrypoint.
 // Requires --agent before importing runtime modules that rely on identity.
@@ -7,10 +40,12 @@ if (!process.argv.includes("--agent")) {
     console.error("Missing required --agent <name> argument.\nUsage: node dist/heart/agent-entry.js --agent ouroboros");
     process.exit(1);
 }
-const inner_dialog_worker_1 = require("../senses/inner-dialog-worker");
 const cli_logging_1 = require("../nerves/cli-logging");
 (0, cli_logging_1.configureCliRuntimeLogger)("self");
-(0, inner_dialog_worker_1.startInnerDialogWorker)().catch((error) => {
+// Dynamic import: agent-entry is boot-time wiring that starts a sense process.
+// Using dynamic import avoids a static heart/ -> senses/ dependency.
+Promise.resolve().then(() => __importStar(require("../senses/inner-dialog-worker"))).then(({ startInnerDialogWorker }) => startInnerDialogWorker())
+    .catch((error) => {
     // eslint-disable-next-line no-console -- fatal startup guard for worker process
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);

package/dist/heart/attention-types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Shared attention queue types.
+ *
+ * Canonical home for the AttentionItem interface — consumed by heart/, repertoire/, nerves/, and senses/.
+ * Placed in heart/ because attention is a turn-coordination concern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/heart/config-registry.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_REGISTRY = void 0;
+exports.getRegistryEntries = getRegistryEntries;
+exports.getRegistryEntriesByTier = getRegistryEntriesByTier;
+exports.getRegistryEntriesByTopic = getRegistryEntriesByTopic;
+exports.getRegistryEntry = getRegistryEntry;
+const runtime_1 = require("../nerves/runtime");
+// --- Validation helpers ---
+const KNOWN_PROVIDERS = ["anthropic", "azure", "minimax", "openai-codex", "github-copilot"];
+function validateNumber(value) {
+    if (typeof value !== "number")
+        return `expected number, got ${typeof value}`;
+    return undefined;
+}
+function validateBoolean(value) {
+    if (typeof value !== "boolean")
+        return `expected boolean, got ${typeof value}`;
+    return undefined;
+}
+function validateString(value) {
+    if (typeof value !== "string")
+        return `expected string, got ${typeof value}`;
+    return undefined;
+}
+function validateStringEnum(allowed) {
+    return (value) => {
+        if (typeof value !== "string")
+            return `expected string, got ${typeof value}`;
+        if (!allowed.includes(value))
+            return `expected one of [${allowed.join(", ")}], got "${value}"`;
+        return undefined;
+    };
+}
+function validateInteger(min, max) {
+    return (value) => {
+        if (typeof value !== "number")
+            return `expected number, got ${typeof value}`;
+        if (!Number.isInteger(value))
+            return `expected integer, got ${value}`;
+        if (value < min || value > max)
+            return `expected integer between ${min} and ${max}, got ${value}`;
+        return undefined;
+    };
+}
+function validateStringArray(value) {
+    if (!Array.isArray(value))
+        return `expected array, got ${typeof value}`;
+    for (let i = 0; i < value.length; i++) {
+        if (typeof value[i] !== "string")
+            return `expected string at index ${i}, got ${typeof value[i]}`;
+    }
+    return undefined;
+}
+function validateStringEnumArray(allowed) {
+    return (value) => {
+        if (!Array.isArray(value))
+            return `expected array, got ${typeof value}`;
+        for (let i = 0; i < value.length; i++) {
+            if (typeof value[i] !== "string")
+                return `expected string at index ${i}, got ${typeof value[i]}`;
+            if (!allowed.includes(value[i]))
+                return `expected one of [${allowed.join(", ")}] at index ${i}, got "${value[i]}"`;
+        }
+        return undefined;
+    };
+}
+function validateObject(requiredFields) {
+    return (value) => {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            return `expected object, got ${Array.isArray(value) ? "array" : typeof value}`;
+        }
+        const obj = value;
+        for (const [field, validator] of Object.entries(requiredFields)) {
+            if (!(field in obj))
+                return `missing required field "${field}"`;
+            const err = validator(obj[field]);
+            if (err)
+                return `field "${field}": ${err}`;
+        }
+        return undefined;
+    };
+}
+const registryData = [
+    // --- Tier 3: Operator-only ---
+    {
+        path: "version",
+        tier: 3,
+        description: "Agent config schema version. Must be an integer >= 1.",
+        default: 2,
+        effects: "Controls which config migrations apply on load. Changing incorrectly can corrupt config.",
+        topics: ["schema", "migration"],
+        validate: validateNumber,
+    },
+    {
+        path: "enabled",
+        tier: 3,
+        description: "Whether the agent is enabled. When false, the agent refuses to start.",
+        default: true,
+        effects: "Disables all agent functionality when set to false.",
+        topics: ["lifecycle", "activation"],
+        validate: validateBoolean,
+    },
+    {
+        path: "mcpServers",
+        tier: 3,
+        description: "MCP server configurations. Maps server name to command, args, and env.",
+        default: undefined,
+        effects: "Adds or removes MCP tool servers. Incorrect config can expose the agent to untrusted tool sources.",
+        topics: ["tools", "mcp", "servers", "extensions"],
+    },
+    // --- Tier 2: Proposal ---
+    {
+        path: "humanFacing.provider",
+        tier: 2,
+        description: "Provider for human-facing interactions (CLI, Teams, BlueBubbles).",
+        default: "anthropic",
+        effects: "Changes the LLM provider used for all human-facing conversations. Affects quality, latency, and cost.",
+        topics: ["model", "provider", "llm", "human"],
+        validate: validateStringEnum(KNOWN_PROVIDERS),
+    },
+    {
+        path: "humanFacing.model",
+        tier: 2,
+        description: "Model name for human-facing interactions.",
+        default: "claude-opus-4-6",
+        effects: "Changes the specific model used for human-facing conversations.",
+        topics: ["model", "provider", "llm", "human"],
+        validate: validateString,
+    },
+    {
+        path: "agentFacing.provider",
+        tier: 2,
+        description: "Provider for agent-facing interactions (inner dialog, delegation).",
+        default: "anthropic",
+        effects: "Changes the LLM provider used for inner dialog and agent-to-agent communication.",
+        topics: ["model", "provider", "llm", "agent", "inner-dialog"],
+        validate: validateStringEnum(KNOWN_PROVIDERS),
+    },
+    {
+        path: "agentFacing.model",
+        tier: 2,
+        description: "Model name for agent-facing interactions.",
+        default: "claude-opus-4-6",
+        effects: "Changes the specific model used for inner dialog and agent-to-agent communication.",
+        topics: ["model", "provider", "llm", "agent", "inner-dialog"],
+        validate: validateString,
+    },
+    {
+        path: "context.maxTokens",
+        tier: 2,
+        description: "Maximum context window size in tokens.",
+        default: 80000,
+        effects: "Larger values allow more context but increase cost and latency. Must match model capability.",
+        topics: ["context", "tokens", "memory", "performance"],
+        validate: validateInteger(1000, 1000000),
+    },
+    {
+        path: "senses.cli",
+        tier: 2,
+        description: "CLI sense configuration. Controls whether the CLI interface is enabled.",
+        default: { enabled: true },
+        effects: "Enables or disables the CLI (terminal) interaction channel.",
+        topics: ["senses", "cli", "channels", "interface"],
+        validate: validateObject({ enabled: validateBoolean }),
+    },
+    {
+        path: "senses.teams",
+        tier: 2,
+        description: "Teams sense configuration. Controls whether the Teams interface is enabled.",
+        default: { enabled: false },
+        effects: "Enables or disables the Microsoft Teams interaction channel.",
+        topics: ["senses", "teams", "channels", "interface"],
+        validate: validateObject({ enabled: validateBoolean }),
+    },
+    {
+        path: "senses.bluebubbles",
+        tier: 2,
+        description: "BlueBubbles sense configuration. Controls whether the iMessage interface is enabled.",
+        default: { enabled: false },
+        effects: "Enables or disables the BlueBubbles (iMessage) interaction channel.",
+        topics: ["senses", "bluebubbles", "imessage", "channels", "interface"],
+        validate: validateObject({ enabled: validateBoolean }),
+    },
+    {
+        path: "sync.enabled",
+        tier: 2,
+        description: "Whether git-based bundle sync is enabled.",
+        default: false,
+        effects: "Enables automatic synchronization of agent state via git. Requires sync.remote to be configured.",
+        topics: ["sync", "git", "state", "backup"],
+        validate: validateBoolean,
+    },
+    {
+        path: "sync.remote",
+        tier: 2,
+        description: "Git remote name used for bundle sync.",
+        default: "origin",
+        effects: "Controls which git remote is used when sync is enabled.",
+        topics: ["sync", "git", "remote"],
+        validate: validateString,
+    },
+    // --- Tier 1: Self-service ---
+    {
+        path: "context.contextMargin",
+        tier: 1,
+        description: "Percentage of context window reserved as margin before compaction triggers.",
+        default: 20,
+        effects: "Higher values trigger compaction earlier, preserving more headroom. Lower values use more context.",
+        topics: ["context", "compaction", "memory", "performance"],
+        validate: validateInteger(0, 100),
+    },
+    {
+        path: "phrases.thinking",
+        tier: 1,
+        description: "Array of phrases displayed while the agent is thinking.",
+        default: ["working"],
+        effects: "Changes the thinking indicator text shown to users. Purely cosmetic.",
+        topics: ["phrases", "ux", "display", "personality"],
+        validate: validateStringArray,
+    },
+    {
+        path: "phrases.tool",
+        tier: 1,
+        description: "Array of phrases displayed while the agent is running a tool.",
+        default: ["running tool"],
+        effects: "Changes the tool-use indicator text shown to users. Purely cosmetic.",
+        topics: ["phrases", "ux", "display", "personality"],
+        validate: validateStringArray,
+    },
+    {
+        path: "phrases.followup",
+        tier: 1,
+        description: "Array of phrases displayed during follow-up processing.",
+        default: ["processing"],
+        effects: "Changes the follow-up indicator text shown to users. Purely cosmetic.",
+        topics: ["phrases", "ux", "display", "personality"],
+        validate: validateStringArray,
+    },
+    {
+        path: "shell.defaultTimeout",
+        tier: 1,
+        description: "Default timeout in milliseconds for shell command execution.",
+        default: undefined,
+        effects: "Controls how long shell commands run before timing out. Undefined uses system default.",
+        topics: ["shell", "timeout", "execution", "tools"],
+        validate: validateInteger(1000, 600000),
+    },
+    {
+        path: "logging.level",
+        tier: 1,
+        description: "Minimum log level: debug, info, warn, or error.",
+        default: undefined,
+        effects: "Controls verbosity of runtime logging. Lower levels produce more output.",
+        topics: ["logging", "debug", "diagnostics"],
+        validate: validateStringEnum(["debug", "info", "warn", "error"]),
+    },
+    {
+        path: "logging.sinks",
+        tier: 1,
+        description: "Array of log sink types: 'terminal' and/or 'ndjson'.",
+        default: undefined,
+        effects: "Controls where log output is directed. Terminal shows in console, ndjson writes structured logs.",
+        topics: ["logging", "output", "diagnostics"],
+        validate: validateStringEnumArray(["terminal", "ndjson"]),
+    },
+];
+exports.CONFIG_REGISTRY = new Map(registryData.map((entry) => [entry.path, entry]));
+function getRegistryEntries() {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "config_registry.access",
+        message: "listing all registry entries",
+        meta: { count: exports.CONFIG_REGISTRY.size },
+    });
+    return [...exports.CONFIG_REGISTRY.values()];
+}
+function getRegistryEntriesByTier(tier) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "config_registry.access",
+        message: `filtering registry entries by tier ${tier}`,
+        meta: { tier },
+    });
+    return [...exports.CONFIG_REGISTRY.values()].filter((entry) => entry.tier === tier);
+}
+function getRegistryEntriesByTopic(topic) {
+    const needle = topic.toLowerCase();
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "config_registry.access",
+        message: `filtering registry entries by topic "${topic}"`,
+        meta: { topic },
+    });
+    return [...exports.CONFIG_REGISTRY.values()].filter((entry) => entry.topics.some((t) => t.toLowerCase().includes(needle)));
+}
+function getRegistryEntry(path) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "config_registry.access",
+        message: `looking up registry entry for "${path}"`,
+        meta: { path },
+    });
+    return exports.CONFIG_REGISTRY.get(path);
+}

package/dist/heart/core.js

@@ -18,7 +18,7 @@ const config_1 = require("./config");
 const identity_1 = require("./identity");
 const tools_1 = require("../repertoire/tools");
 const channel_1 = require("../mind/friends/channel");
-const surface_tool_1 = require("../senses/surface-tool");
+const tools_2 = require("../repertoire/tools");
 const runtime_1 = require("../nerves/runtime");
 const context_1 = require("../mind/context");
 const prompt_1 = require("../mind/prompt");
@@ -148,11 +148,11 @@ function getProviderDisplayLabel(facing = "human") {
     return providerLabelBuilders[provider]();
 }
 // Re-export tools, execTool, summarizeArgs from ./tools for backward compat
-var tools_2 = require("../repertoire/tools");
-Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_2.tools; } });
-Object.defineProperty(exports, "execTool", { enumerable: true, get: function () { return tools_2.execTool; } });
-Object.defineProperty(exports, "summarizeArgs", { enumerable: true, get: function () { return tools_2.summarizeArgs; } });
-Object.defineProperty(exports, "getToolsForChannel", { enumerable: true, get: function () { return tools_2.getToolsForChannel; } });
+var tools_3 = require("../repertoire/tools");
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_3.tools; } });
+Object.defineProperty(exports, "execTool", { enumerable: true, get: function () { return tools_3.execTool; } });
+Object.defineProperty(exports, "summarizeArgs", { enumerable: true, get: function () { return tools_3.summarizeArgs; } });
+Object.defineProperty(exports, "getToolsForChannel", { enumerable: true, get: function () { return tools_3.getToolsForChannel; } });
 // Re-export streaming functions for backward compat
 var streaming_1 = require("./streaming");
 Object.defineProperty(exports, "streamChatCompletion", { enumerable: true, get: function () { return streaming_1.streamChatCompletion; } });
@@ -530,7 +530,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         const activeTools = [
             ...filteredBaseTools,
             tools_1.ponderTool,
-            ...(isInnerDialog ? [surface_tool_1.surfaceToolDef, tools_1.restTool] : []),
+            ...(isInnerDialog ? [tools_2.surfaceToolDef, tools_1.restTool] : []),
             ...((currentContext?.isGroupChat || options?.isReactionSignal) && !isInnerDialog ? [tools_1.observeTool] : []),
             ...(!isInnerDialog ? [tools_1.settleTool] : []),
         ];
@@ -924,8 +924,10 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         providerRuntime.appendToolOutput(tc.id, rejection);
                         continue;
                     }
-                    // Confirmation check for mutate tools
-                    if ((0, tools_1.isConfirmationRequired)(tc.name) && !options?.skipConfirmation) {
+                    // Confirmation check for mutate tools.
+                    // confirmationAlwaysRequired tools cannot be bypassed by skipConfirmation.
+                    const needsConfirmation = (0, tools_1.isConfirmationRequired)(tc.name) && (!options?.skipConfirmation || (0, tools_1.isConfirmationAlwaysRequired)(tc.name));
+                    if (needsConfirmation) {
                         let decision = "denied";
                         if (callbacks.onConfirmAction) {
                             decision = await callbacks.onConfirmAction(tc.name, args);

package/dist/heart/daemon/sense-manager.js

@@ -38,7 +38,6 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
-const bluebubbles_runtime_state_1 = require("../../senses/bluebubbles-runtime-state");
 const identity_1 = require("../identity");
 const sense_truth_1 = require("../sense-truth");
 const process_manager_1 = require("./process-manager");
@@ -187,13 +186,35 @@ function blueBubblesRuntimeStateIsFresh(lastCheckedAt, now = Date.now()) {
     }
     return checkedAt >= now - BLUEBUBBLES_RUNTIME_FRESHNESS_WINDOW_MS;
 }
+function readBlueBubblesRuntimeJson(runtimePath) {
+    try {
+        const raw = fs.readFileSync(runtimePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        /* v8 ignore start -- branches: ternary fallbacks for missing/malformed BB runtime fields @preserve */
+        return {
+            upstreamStatus: parsed.upstreamStatus === "ok" || parsed.upstreamStatus === "error"
+                ? parsed.upstreamStatus
+                : "unknown",
+            detail: typeof parsed.detail === "string" && parsed.detail.trim()
+                ? parsed.detail
+                : "startup health probe pending",
+            lastCheckedAt: typeof parsed.lastCheckedAt === "string" ? parsed.lastCheckedAt : undefined,
+        };
+        /* v8 ignore stop */
+        /* v8 ignore start -- defensive: catch for missing/corrupt BB runtime state file @preserve */
+    }
+    catch {
+        return { upstreamStatus: "unknown", detail: "startup health probe pending" };
+    }
+    /* v8 ignore stop */
+}
 function readBlueBubblesRuntimeFacts(agent, bundlesRoot, snapshot) {
     const agentRoot = path.join(bundlesRoot, `${agent}.ouro`);
     const runtimePath = path.join(agentRoot, "state", "senses", "bluebubbles", "runtime.json");
     if (!fs.existsSync(runtimePath)) {
         return { runtime: snapshot?.runtime };
     }
-    const state = (0, bluebubbles_runtime_state_1.readBlueBubblesRuntimeState)(agent, agentRoot);
+    const state = readBlueBubblesRuntimeJson(runtimePath);
     if (!blueBubblesRuntimeStateIsFresh(state.lastCheckedAt)) {
         return { runtime: snapshot?.runtime };
     }

package/dist/heart/start-of-turn-packet.js

@@ -1,8 +1,44 @@
 "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.buildCapabilitiesSection = buildCapabilitiesSection;
 exports.buildStartOfTurnPacket = buildStartOfTurnPacket;
 exports.renderStartOfTurnPacket = renderStartOfTurnPacket;
 exports.renderCompactStartOfTurnPacket = renderCompactStartOfTurnPacket;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const runtime_1 = require("../nerves/runtime");
 const tempo_1 = require("./tempo");
 function estimateTokens(text) {
@@ -87,6 +123,64 @@ function buildResumeHint(view, obligations) {
         return "";
     return hints.join("; ");
 }
+/**
+ * Build a compact summary of capability changes between runtime versions.
+ * Reads bundle-meta.json for version info and changelog.json for change descriptions.
+ * Returns undefined if no version change detected or files are missing/malformed.
+ */
+function buildCapabilitiesSection(bundleRoot) {
+    let meta;
+    try {
+        const raw = fs.readFileSync(path.join(bundleRoot, "bundle-meta.json"), "utf-8");
+        meta = JSON.parse(raw);
+    }
+    catch {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.capabilities_check",
+            message: "bundle-meta.json missing or malformed",
+            meta: { bundleRoot },
+        });
+        return undefined;
+    }
+    const currentVersion = meta.runtimeVersion;
+    const previousVersion = meta.previousRuntimeVersion;
+    if (typeof currentVersion !== "string" || typeof previousVersion !== "string") {
+        return undefined;
+    }
+    if (currentVersion === previousVersion) {
+        return undefined;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.capabilities_version_change",
+        message: `runtime version changed from ${previousVersion} to ${currentVersion}`,
+        meta: { previousVersion, currentVersion },
+    });
+    let changelog;
+    try {
+        const raw = fs.readFileSync(path.join(bundleRoot, "changelog.json"), "utf-8");
+        changelog = JSON.parse(raw);
+    }
+    catch {
+        // changelog missing -- still report the version change
+    }
+    const parts = [`Updated from ${previousVersion} to ${currentVersion}`];
+    if (changelog && Array.isArray(changelog)) {
+        const relevantChanges = [];
+        for (const entry of changelog) {
+            if (entry.version === previousVersion)
+                break;
+            if (Array.isArray(entry.changes)) {
+                relevantChanges.push(...entry.changes);
+            }
+        }
+        if (relevantChanges.length > 0) {
+            parts.push(`: ${relevantChanges.join("; ")}`);
+        }
+    }
+    return parts.join("");
+}
 function buildStartOfTurnPacket(view, opts) {
     const tempo = view.tempo;
     const tokenBudget = tempo_1.TEMPO_BUDGETS[tempo];
@@ -128,11 +222,12 @@ function renderStartOfTurnPacket(packet) {
     // Assemble sections in priority order (highest priority first for budget allocation)
     // Each section is { label, content, priority } where lower priority number = truncated first
     const sections = [
-        { label: "syncFailure", content: packet.syncFailure ?? "", priority: 6 },
-        { label: "resume", content: packet.resumeHint, priority: 5 },
-        { label: "obligations", content: packet.obligations, priority: 4 },
-        { label: "cares", content: packet.cares, priority: 3 },
-        { label: "plot", content: packet.plotLine, priority: 2 },
+        { label: "syncFailure", content: packet.syncFailure ?? "", priority: 7 },
+        { label: "resume", content: packet.resumeHint, priority: 6 },
+        { label: "obligations", content: packet.obligations, priority: 5 },
+        { label: "cares", content: packet.cares, priority: 4 },
+        { label: "plot", content: packet.plotLine, priority: 3 },
+        { label: "capabilities", content: packet.capabilities ?? "", priority: 2 },
         { label: "presence", content: packet.presence, priority: 1 },
     ].filter((s) => s.content.length > 0);
     if (sections.length === 0) {
@@ -193,6 +288,9 @@ function formatSections(sections) {
             case "presence":
                 parts.push(`**Peers:**\n${section.content}`);
                 break;
+            case "capabilities":
+                parts.push(`**Capabilities:** ${section.content}`);
+                break;
             case "syncFailure":
                 parts.push(`**Sync warning:** ${section.content}`);
                 break;

package/dist/repertoire/tools-base.js

@@ -47,6 +47,7 @@ const file_state_1 = require("../mind/file-state");
 const scrutiny_1 = require("../mind/scrutiny");
 const identity_1 = require("../heart/identity");
 const identity_2 = require("../heart/identity");
+const config_registry_1 = require("../heart/config-registry");
 const socket_client_1 = require("../heart/daemon/socket-client");
 const thoughts_1 = require("../heart/daemon/thoughts");
 const manager_1 = require("../heart/bridges/manager");
@@ -1738,6 +1739,230 @@ exports.baseToolDefinitions = [
             return JSON.stringify(result, null, 2);
         },
     },
+    // --- Config discovery tools ---
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "read_config",
+                description: "Read current agent configuration with tier annotations, descriptions, defaults, and effects. Optionally filter by topic to see only related settings.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        related_to: {
+                            type: "string",
+                            description: "Optional topic to filter results (e.g., 'model', 'logging', 'senses'). Case-insensitive partial match.",
+                        },
+                    },
+                },
+            },
+        },
+        handler: (a) => {
+            const entries = a.related_to
+                ? (0, config_registry_1.getRegistryEntriesByTopic)(a.related_to)
+                : (0, config_registry_1.getRegistryEntries)();
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const configPath = path.join(agentRoot, "agent.json");
+            let rawConfig = {};
+            try {
+                rawConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            }
+            catch {
+                /* v8 ignore next -- defensive: agent.json read failure in read_config @preserve */
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.read_config_error", message: "failed to read agent.json", meta: { path: configPath } });
+            }
+            const result = entries.map((entry) => {
+                const parts = entry.path.split(".");
+                let current = rawConfig;
+                for (const part of parts) {
+                    if (current && typeof current === "object" && !Array.isArray(current)) {
+                        current = current[part];
+                    }
+                    else {
+                        current = undefined;
+                        break;
+                    }
+                }
+                const isExplicit = current !== undefined;
+                let source;
+                let currentValue;
+                if (isExplicit) {
+                    source = "explicit";
+                    currentValue = current;
+                }
+                else if (entry.default !== undefined) {
+                    source = "default";
+                    currentValue = entry.default;
+                }
+                else {
+                    source = "unset";
+                    currentValue = null;
+                }
+                return {
+                    path: entry.path,
+                    currentValue,
+                    source,
+                    tier: entry.tier,
+                    description: entry.description,
+                    default: entry.default !== undefined ? entry.default : null,
+                    effects: entry.effects,
+                    topics: entry.topics,
+                };
+            });
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.read_config", message: `read_config returned ${result.length} entries`, meta: { count: result.length, topic: a.related_to ?? null } });
+            return JSON.stringify({ entries: result }, null, 2);
+        },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "update_config",
+                description: "Update a Tier 1 (self-service) agent configuration value immediately. For Tier 2 keys that require operator approval, use propose_config instead. Tier 3 (operator-only) keys are refused.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Config key in dot-notation (e.g., 'context.contextMargin', 'logging.level')" },
+                        value: { type: "string", description: "New value as JSON (e.g., '25', '\"debug\"', '[\"terminal\", \"ndjson\"]')" },
+                    },
+                    required: ["path", "value"],
+                },
+            },
+        },
+        handler: (a) => {
+            const entry = (0, config_registry_1.getRegistryEntry)(a.path);
+            if (!entry) {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.update_config_error", message: `unknown config path: ${a.path}`, meta: { path: a.path } });
+                return `Error: unknown config path "${a.path}". Use read_config to see available paths.`;
+            }
+            let parsedValue;
+            try {
+                parsedValue = JSON.parse(a.value);
+            }
+            catch {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.update_config_error", message: `invalid JSON value for ${a.path}`, meta: { path: a.path, value: a.value } });
+                return `Error: invalid JSON value. Provide value as valid JSON (e.g., 25, "debug", ["terminal"]).`;
+            }
+            // Validate value against registry entry's validator
+            /* v8 ignore next -- all current entries have validators; guard kept for future entries without one @preserve */
+            if (entry.validate) {
+                const validationError = entry.validate(parsedValue);
+                if (validationError) {
+                    (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.update_config_error", message: `validation failed for ${a.path}: ${validationError}`, meta: { path: a.path, value: a.value, validationError } });
+                    return `Error: validation failed for "${a.path}": ${validationError}`;
+                }
+            }
+            // Tier 3: refuse
+            if (entry.tier === 3) {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.update_config_refused", message: `refused T3 change to ${a.path}`, meta: { path: a.path, tier: 3 } });
+                return `Refused: "${a.path}" is an operator-only (Tier 3) key. ${entry.description} Only the operator can change this value directly in agent.json.`;
+            }
+            // Tier 2: refuse — must use propose_config
+            if (entry.tier === 2) {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.update_config_refused", message: `refused T2 change to ${a.path} — use propose_config`, meta: { path: a.path, tier: 2 } });
+                return `Refused: "${a.path}" is a Tier 2 (proposal) key that requires operator approval. Use propose_config instead of update_config to propose this change.`;
+            }
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const configPath = path.join(agentRoot, "agent.json");
+            let rawConfig;
+            try {
+                rawConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            }
+            catch {
+                /* v8 ignore next -- defensive: agent.json read failure in update_config @preserve */
+                return `Error: failed to read agent.json at ${configPath}`;
+            }
+            // Apply T1 change immediately
+            const parts = entry.path.split(".");
+            let target = rawConfig;
+            for (let i = 0; i < parts.length - 1; i++) {
+                if (!(parts[i] in target) || typeof target[parts[i]] !== "object" || target[parts[i]] === null) {
+                    target[parts[i]] = {};
+                }
+                target = target[parts[i]];
+            }
+            target[parts[parts.length - 1]] = parsedValue;
+            fs.writeFileSync(configPath, JSON.stringify(rawConfig, null, 2) + "\n", "utf-8");
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.update_config_applied", message: `applied config change to ${a.path}`, meta: { path: a.path, tier: entry.tier, value: parsedValue } });
+            return `Success: "${a.path}" updated to ${JSON.stringify(parsedValue)}. Change applied immediately.`;
+        },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "propose_config",
+                description: "Propose a change to a Tier 2 (proposal) agent configuration value. Requires operator approval before the change is applied. For Tier 1 self-service keys, use update_config instead.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Config key in dot-notation (e.g., 'context.maxTokens', 'humanFacing.model')" },
+                        value: { type: "string", description: "New value as JSON (e.g., '120000', '\"azure\"', '{\"enabled\": true}')" },
+                    },
+                    required: ["path", "value"],
+                },
+            },
+        },
+        confirmationRequired: true,
+        confirmationAlwaysRequired: true,
+        handler: (a) => {
+            const entry = (0, config_registry_1.getRegistryEntry)(a.path);
+            if (!entry) {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.propose_config_error", message: `unknown config path: ${a.path}`, meta: { path: a.path } });
+                return `Error: unknown config path "${a.path}". Use read_config to see available paths.`;
+            }
+            let parsedValue;
+            try {
+                parsedValue = JSON.parse(a.value);
+            }
+            catch {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.propose_config_error", message: `invalid JSON value for ${a.path}`, meta: { path: a.path, value: a.value } });
+                return `Error: invalid JSON value. Provide value as valid JSON (e.g., 120000, "azure", {"enabled": true}).`;
+            }
+            // Validate value against registry entry's validator
+            /* v8 ignore next -- all current entries have validators; guard kept for future entries without one @preserve */
+            if (entry.validate) {
+                const validationError = entry.validate(parsedValue);
+                if (validationError) {
+                    (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.propose_config_error", message: `validation failed for ${a.path}: ${validationError}`, meta: { path: a.path, value: a.value, validationError } });
+                    return `Error: validation failed for "${a.path}": ${validationError}`;
+                }
+            }
+            // Tier 3: refuse
+            if (entry.tier === 3) {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.propose_config_refused", message: `refused T3 change to ${a.path}`, meta: { path: a.path, tier: 3 } });
+                return `Refused: "${a.path}" is an operator-only (Tier 3) key. ${entry.description} Only the operator can change this value directly in agent.json.`;
+            }
+            // Tier 1: refuse — use update_config for self-service keys
+            if (entry.tier === 1) {
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.propose_config_refused", message: `refused T1 change to ${a.path} — use update_config`, meta: { path: a.path, tier: 1 } });
+                return `Refused: "${a.path}" is a Tier 1 (self-service) key. Use update_config instead — no operator approval needed.`;
+            }
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const configPath = path.join(agentRoot, "agent.json");
+            let rawConfig;
+            try {
+                rawConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            }
+            catch {
+                /* v8 ignore next -- defensive: agent.json read failure in propose_config @preserve */
+                return `Error: failed to read agent.json at ${configPath}`;
+            }
+            // Apply T2 change (operator confirmation already obtained via confirmationAlwaysRequired)
+            const parts = entry.path.split(".");
+            let target = rawConfig;
+            for (let i = 0; i < parts.length - 1; i++) {
+                if (!(parts[i] in target) || typeof target[parts[i]] !== "object" || target[parts[i]] === null) {
+                    target[parts[i]] = {};
+                }
+                target = target[parts[i]];
+            }
+            target[parts[parts.length - 1]] = parsedValue;
+            fs.writeFileSync(configPath, JSON.stringify(rawConfig, null, 2) + "\n", "utf-8");
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.propose_config_applied", message: `applied approved config change to ${a.path}`, meta: { path: a.path, tier: entry.tier, value: parsedValue } });
+            return `Success: "${a.path}" updated to ${JSON.stringify(parsedValue)}. Change approved and applied.`;
+        },
+    },
     ...tools_1.codingToolDefinitions,
 ];
 exports.tools = exports.baseToolDefinitions.map((d) => d.tool);

package/dist/repertoire/tools.js

@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
+exports.surfaceToolDef = exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
 exports.getToolsForChannel = getToolsForChannel;
 exports.isConfirmationRequired = isConfirmationRequired;
+exports.isConfirmationAlwaysRequired = isConfirmationAlwaysRequired;
 exports.execTool = execTool;
 exports.summarizeArgs = summarizeArgs;
 exports.buildToolResultSummary = buildToolResultSummary;
@@ -66,10 +67,36 @@ Object.defineProperty(exports, "settleTool", { enumerable: true, get: function (
 Object.defineProperty(exports, "observeTool", { enumerable: true, get: function () { return tools_base_2.observeTool; } });
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_base_2.ponderTool; } });
 Object.defineProperty(exports, "restTool", { enumerable: true, get: function () { return tools_base_2.restTool; } });
+// Surface tool schema — canonical home. Handler lives in senses/surface-tool.ts.
+exports.surfaceToolDef = {
+    type: "function",
+    function: {
+        name: "surface",
+        description: "share a thought outward — deliver an answer, ask a follow-up, or surface progress to whoever needs to hear it. pass delegationId to address a held thought (see your attention queue above), or friendId for spontaneous outreach. does not end your turn.",
+        parameters: {
+            type: "object",
+            properties: {
+                content: {
+                    type: "string",
+                    description: "the message to deliver",
+                },
+                delegationId: {
+                    type: "string",
+                    description: "ID from your attention queue — addresses a specific held thought",
+                },
+                friendId: {
+                    type: "string",
+                    description: "friend to reach out to spontaneously (when not addressing a held thought)",
+                },
+            },
+            required: ["content"],
+        },
+    },
+};
 // Surface tool handler: routes content to friend's freshest session
 /* v8 ignore start -- surface handler wiring: core logic tested via surface-tool.test.ts; this wires identity/routing deps @preserve */
 const surfaceToolDefinition = {
-    tool: surface_tool_1.surfaceToolDef,
+    tool: exports.surfaceToolDef,
     handler: async (args, ctx) => {
         const queue = ctx?.delegatedOrigins ?? [];
         const agentName = (() => { try {
@@ -299,6 +326,12 @@ function isConfirmationRequired(toolName) {
     const def = allDefinitions.find((d) => d.tool.function.name === toolName);
     return def?.confirmationRequired === true;
 }
+// Check whether a tool's confirmation is non-bypassable (cannot be skipped by skipConfirmation).
+// Used for T2 config proposals that must always require operator approval.
+function isConfirmationAlwaysRequired(toolName) {
+    const def = allDefinitions.find((d) => d.tool.function.name === toolName);
+    return def?.confirmationAlwaysRequired === true;
+}
 function normalizeGuardArgs(_name, args) {
     return args;
 }

package/dist/senses/pipeline.js

@@ -390,6 +390,10 @@ async function handleInboundTurn(input) {
                 if (syncFailure) {
                     startOfTurnPacket.syncFailure = syncFailure;
                 }
+                const capabilities = (0, start_of_turn_packet_1.buildCapabilitiesSection)(agentRoot);
+                if (capabilities) {
+                    startOfTurnPacket.capabilities = capabilities;
+                }
                 renderedStartOfTurnPacket = (0, start_of_turn_packet_1.renderStartOfTurnPacket)(startOfTurnPacket);
                 if (!renderedStartOfTurnPacket)
                     renderedStartOfTurnPacket = undefined;

package/dist/senses/surface-tool.js

@@ -1,35 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.surfaceToolDef = void 0;
 exports.handleSurface = handleSurface;
 const attention_queue_1 = require("./attention-queue");
 const runtime_1 = require("../nerves/runtime");
-// ── Tool definition ──────────────────────────────────────────────
-exports.surfaceToolDef = {
-    type: "function",
-    function: {
-        name: "surface",
-        description: "share a thought outward — deliver an answer, ask a follow-up, or surface progress to whoever needs to hear it. pass delegationId to address a held thought (see your attention queue above), or friendId for spontaneous outreach. does not end your turn.",
-        parameters: {
-            type: "object",
-            properties: {
-                content: {
-                    type: "string",
-                    description: "the message to deliver",
-                },
-                delegationId: {
-                    type: "string",
-                    description: "ID from your attention queue — addresses a specific held thought",
-                },
-                friendId: {
-                    type: "string",
-                    description: "friend to reach out to spontaneously (when not addressing a held thought)",
-                },
-            },
-            required: ["content"],
-        },
-    },
-};
 async function handleSurface(input) {
     const { content, delegationId, friendId, queue, routeToFriend, advanceObligation, fulfillHeartObligation } = input;
     // Resolve target friend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.204",
+  "version": "0.1.0-alpha.206",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",