@ouro.bot/cli 0.1.0-alpha.74 → 0.1.0-alpha.741

package/dist/repertoire/tools-notes.js

@@ -0,0 +1,459 @@
+"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.notesToolDefinitions = void 0;
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const skills_1 = require("./skills");
+const config_1 = require("../heart/config");
+const runtime_1 = require("../nerves/runtime");
+const identity_1 = require("../heart/identity");
+const friends_1 = require("@ouro.bot/friends");
+const diary_1 = require("../mind/diary");
+const record_paths_1 = require("../mind/record-paths");
+const provenance_trust_1 = require("../mind/provenance-trust");
+const CLAUDE_READ_ONLY_TOOLS = "Read,Grep,Glob,LS";
+function bundleRelativeLocator(filePath, ctx) {
+    const agentRoot = ctx?.agentRoot ?? (0, identity_1.getAgentRoot)();
+    const relativePath = path.relative(agentRoot, filePath);
+    if (relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
+        return relativePath.split(path.sep).join("/");
+    }
+    return filePath.split(path.sep).join("/");
+}
+exports.notesToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "list_skills",
+                description: "list all available skills",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        handler: () => JSON.stringify((0, skills_1.listSkills)()),
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "load_skill",
+                description: "load a skill by name, returns its content",
+                parameters: {
+                    type: "object",
+                    properties: { name: { type: "string" } },
+                    required: ["name"],
+                },
+            },
+        },
+        handler: (a) => {
+            try {
+                return (0, skills_1.loadSkill)(a.name);
+            }
+            catch (e) {
+                return `error: ${e}`;
+            }
+        },
+        summaryKeys: ["name"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "claude",
+                description: "use claude code to query this codebase or get an outside perspective. Use for code review, second opinions, or questions that benefit from a fresh perspective outside this conversation's context.",
+                parameters: {
+                    type: "object",
+                    properties: { prompt: { type: "string" } },
+                    required: ["prompt"],
+                },
+            },
+        },
+        handler: (a) => {
+            try {
+                const result = (0, child_process_1.spawnSync)("claude", [
+                    "-p",
+                    "--no-session-persistence",
+                    "--permission-mode",
+                    "plan",
+                    "--tools",
+                    CLAUDE_READ_ONLY_TOOLS,
+                    "--add-dir",
+                    ".",
+                ], {
+                    input: a.prompt,
+                    encoding: "utf-8",
+                    timeout: 60000,
+                });
+                if (result.error)
+                    return `error: ${result.error}`;
+                if (result.status !== 0)
+                    return `claude exited with code ${result.status}: ${result.stderr}`;
+                return result.stdout || "(no output)";
+            }
+            catch (e) {
+                return `error: ${e}`;
+            }
+        },
+        summaryKeys: ["prompt"],
+        riskProfile: {
+            mutates: "none",
+            risk: "low",
+            reason: "runs Claude Code in plan mode with only read/search/list tools",
+        },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "web_search",
+                description: "search the web using perplexity. returns ranked results with titles, urls, and snippets",
+                parameters: {
+                    type: "object",
+                    properties: { query: { type: "string" } },
+                    required: ["query"],
+                },
+            },
+        },
+        handler: async (a) => {
+            try {
+                const key = (0, config_1.getIntegrationsConfig)().perplexityApiKey;
+                if (!key)
+                    return "error: perplexityApiKey not configured in the agent vault runtime/config item";
+                const res = await fetch("https://api.perplexity.ai/search", {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${key}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ query: a.query, max_results: 5 }),
+                });
+                if (!res.ok)
+                    return `error: ${res.status} ${res.statusText}`;
+                const data = (await res.json());
+                if (!data.results?.length)
+                    return "no results found";
+                return data.results
+                    .map((r) => `${r.title}\n${r.url}\n${r.snippet}`)
+                    .join("\n\n");
+            }
+            catch (e) {
+                return `error: ${e}`;
+            }
+        },
+        summaryKeys: ["query"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "search_facts",
+                description: "Search my Desk record diary facts matching a query. Uses semantic similarity -- phrasing matters. Try different angles if the first query doesn't find what you're looking for. Search written facts before asking the human something the record may already answer.",
+                parameters: {
+                    type: "object",
+                    properties: { query: { type: "string" } },
+                    required: ["query"],
+                },
+            },
+        },
+        handler: async (a) => {
+            try {
+                const query = (a.query || "").trim();
+                if (!query)
+                    return "query is required";
+                const resultLines = [];
+                const hits = await (0, diary_1.searchDiaryEntries)(query, (0, diary_1.readDiaryEntries)());
+                for (const fact of hits) {
+                    let meta = `source=${fact.source}, createdAt=${fact.createdAt}`;
+                    if (fact.provenance) {
+                        if (fact.provenance.channel)
+                            meta += `, channel=${fact.provenance.channel}`;
+                        if (fact.provenance.friendName)
+                            meta += `, friend=${fact.provenance.friendName}`;
+                        if (fact.provenance.trust)
+                            meta += `, trust=${fact.provenance.trust}`;
+                    }
+                    const tag = (0, provenance_trust_1.classifyProvenanceTrust)(fact.provenance) === "external" ? "diary/external" : "diary";
+                    resultLines.push(`[${tag}] ${fact.text} (${meta})`);
+                }
+                return resultLines.join("\n");
+            }
+            catch (e) {
+                return `error: ${e instanceof Error ? e.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(e)}`;
+            }
+        },
+        summaryKeys: ["query"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "consult_diary",
+                description: "Inspect my Desk record diary facts. With a query, searches semantically. Without a query, returns the most recent facts. Use this for direct record inspection before asking someone to restate something already written down.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                        limit: { type: "string" },
+                    },
+                },
+            },
+        },
+        handler: async (a) => {
+            try {
+                const limitRaw = a.limit ? Number.parseInt(String(a.limit), 10) : 10;
+                const limit = Number.isFinite(limitRaw) ? Math.min(50, Math.max(1, limitRaw)) : 10;
+                const query = typeof a.query === "string" ? a.query.trim() : "";
+                const facts = (0, diary_1.readDiaryEntries)();
+                const matches = query ? await (0, diary_1.searchDiaryEntries)(query, facts) : [...facts].sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+                const items = matches.slice(0, limit).map((fact) => ({
+                    id: fact.id,
+                    text: fact.text,
+                    source: fact.source,
+                    createdAt: fact.createdAt,
+                    ...(fact.about ? { about: fact.about } : {}),
+                    ...(fact.provenance ? { provenance: fact.provenance } : {}),
+                }));
+                return JSON.stringify({ items });
+            }
+            catch (e) {
+                return `error: ${e instanceof Error ? e.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(e)}`;
+            }
+        },
+        summaryKeys: ["query", "limit"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "diary_write",
+                description: "Write an entry in my diary -- something I learned, noticed, or concluded that I want available later. Use 'about' to tag the entry to a person, topic, or context. Write for my future self: include enough context that the entry makes sense without the surrounding conversation. Prefer durable conclusions over passing noise. Don't duplicate what already belongs in friend notes.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        entry: { type: "string" },
+                        about: { type: "string" },
+                    },
+                    required: ["entry"],
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            const entry = (a.entry || "").trim();
+            if (!entry)
+                return "entry is required";
+            let provenance;
+            if (ctx?.context) {
+                const p = { tool: "diary_write" };
+                const channel = ctx.context.channel?.channel;
+                if (channel)
+                    p.channel = channel;
+                const friendId = ctx.context.friend?.id;
+                if (friendId)
+                    p.friendId = friendId;
+                const friendName = ctx.context.friend?.name;
+                if (friendName)
+                    p.friendName = friendName;
+                const trust = ctx.context.friend?.trustLevel;
+                if (trust)
+                    p.trust = trust;
+                provenance = p;
+            }
+            const result = await (0, diary_1.saveDiaryEntry)({
+                text: entry,
+                source: "tool:diary_write",
+                about: typeof a.about === "string" ? a.about : undefined,
+                provenance,
+            });
+            if (result.added > 0) {
+                ctx?.habitSession?.recordProducedRef?.({
+                    kind: "desk_record",
+                    locator: bundleRelativeLocator(path.join((0, record_paths_1.resolveRecordDiaryRoot)(), "facts.jsonl"), ctx),
+                });
+            }
+            return `saved diary entry (added=${result.added}, skipped=${result.skipped})`;
+        },
+        summaryKeys: ["entry", "about"],
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "writes Desk record diary fact" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "friend_list",
+                description: "list all friends with id, name, and trust level. use this when i need to see who i know — e.g. for cross-chat outreach decisions, screener triage, or just orienting on the friend graph.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        trust: { type: "string", enum: ["family", "friend", "stranger"], description: "optional trust filter; omit to list all" },
+                        limit: { type: "string", description: "max records to return, 1-200. defaults to 50." },
+                    },
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            /* v8 ignore start -- friend_list defensive plumbing: ctx + listAll guards, trust/limit branch fan-out, and empty-set status messages aren't all combined in tests; full coverage lives at the friend-store unit-test layer @preserve */
+            if (!ctx?.friendStore)
+                return "i can't list friends -- friend store not available";
+            if (!ctx.friendStore.listAll)
+                return "the configured friend store does not support listing.";
+            const all = await ctx.friendStore.listAll();
+            const trustFilter = a.trust;
+            const filtered = trustFilter
+                ? all.filter((f) => (f.trustLevel ?? "friend") === trustFilter)
+                : all;
+            const limitRaw = a.limit ? Number.parseInt(a.limit, 10) : 50;
+            const limit = Number.isFinite(limitRaw) ? Math.min(200, Math.max(1, limitRaw)) : 50;
+            const ordered = [...filtered].sort((left, right) => left.name.localeCompare(right.name)).slice(0, limit);
+            if (ordered.length === 0) {
+                return trustFilter ? `no friends with trust level '${trustFilter}'.` : "no friends recorded yet.";
+            }
+            /* v8 ignore stop */
+            /* v8 ignore start -- formatting branches: externalIds presence + pluralization + trust suffix variants depend on specific friend-record shapes not exhaustively combined in tests @preserve */
+            const lines = ordered.map((friend) => {
+                const externals = friend.externalIds && friend.externalIds.length > 0
+                    ? ` [${friend.externalIds.map((id) => `${id.provider}:${id.externalId}`).join(", ")}]`
+                    : "";
+                return `- ${friend.id} (${friend.trustLevel ?? "friend"}): ${friend.name}${externals}`;
+            });
+            return `${ordered.length} friend${ordered.length === 1 ? "" : "s"}${trustFilter ? ` with trust=${trustFilter}` : ""}:\n${lines.join("\n")}`;
+            /* v8 ignore stop */
+        },
+        summaryKeys: ["trust", "limit"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "get_friend_note",
+                description: "read a specific friend record by friend id. use this when i need notes/context about someone not currently active",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        friendId: { type: "string" },
+                    },
+                    required: ["friendId"],
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            const friendId = (a.friendId || "").trim();
+            if (!friendId)
+                return "friendId is required";
+            if (!ctx?.friendStore)
+                return "i can't read friend notes -- friend store not available";
+            const friend = await ctx.friendStore.get(friendId);
+            if (!friend)
+                return `friend not found: ${friendId}`;
+            return JSON.stringify(friend, null, 2);
+        },
+        summaryKeys: ["friendId"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "save_friend_note",
+                description: "save something i learned about my friend. use type 'name' to update their display name, 'tool_preference' for how they like a specific tool to behave (key = tool category like 'ado', 'graph'), or 'note' for general knowledge (key = topic). when updating an existing value, set override to true if i'm replacing/correcting it. omit override (or set false) if i'm unsure and want to check what's already saved.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        type: { type: "string", enum: ["name", "tool_preference", "note"], description: "what kind of information to save" },
+                        key: { type: "string", description: "category key (required for tool_preference and note, e.g. 'ado', 'role')" },
+                        content: { type: "string", description: "the value to save" },
+                        override: { type: "string", enum: ["true", "false"], description: "set to 'true' to overwrite an existing value" },
+                    },
+                    required: ["type", "content"],
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.save_friend_note",
+                message: "save friend note invoked",
+                meta: { type: a.type },
+            });
+            if (!ctx?.context) {
+                return "i can't save notes -- no friend context available";
+            }
+            if (!ctx.friendStore) {
+                return "i can't save notes -- friend store not available";
+            }
+            const friendId = ctx.context.friend?.id;
+            if (!friendId)
+                return "i can't save notes -- no friend identity available";
+            // Validate parameters (input-shape guards stay harness-side so we keep the
+            // first-person tool wording; applyFriendNote does the record mutation).
+            if (!a.content)
+                return "i need a content value to save";
+            const validTypes = ["name", "tool_preference", "note"];
+            if (!validTypes.includes(a.type))
+                return `i don't recognize type '${a.type}' -- use name, tool_preference, or note`;
+            if ((a.type === "tool_preference" || a.type === "note") && !a.key)
+                return "i need a key for tool_preference or note type";
+            // Record-domain logic lives in @ouro.bot/friends; this wrapper maps the
+            // structured FriendOpResult back to the tool's first-person strings.
+            const result = await (0, friends_1.applyFriendNote)(ctx.friendStore, friendId, {
+                type: a.type,
+                ...(a.key !== undefined ? { key: a.key } : {}),
+                content: a.content,
+                override: a.override === "true",
+            });
+            switch (result.status) {
+                case "saved":
+                    if (a.type === "name")
+                        return `saved: name = ${a.content}`;
+                    if (a.type === "tool_preference")
+                        return `saved: toolPreference ${a.key} = ${a.content}`;
+                    return `saved: note ${a.key} = ${a.content}`;
+                case "redirected_to_name":
+                    return `updated friend's name to '${a.content}' (stored as name, not a note)`;
+                case "override_required":
+                    // result.message embeds the existing value; append the harness merge instruction.
+                    return `${result.message}. if you want to replace it, call again with override: true. or merge both values into content and override.`;
+                case "not_found":
+                    return "i can't find the friend record on disk";
+                /* v8 ignore next 2 -- invalid is pre-empted by the harness validation above; kept for exhaustiveness @preserve */
+                case "invalid":
+                    return result.message ?? "i can't save that note";
+                default:
+                    return `error saving note: ${result.message}`;
+            }
+        },
+        summaryKeys: ["type", "key", "content"],
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "writes friend notes/preferences" },
+    },
+];

package/dist/repertoire/tools-obligations.js

@@ -0,0 +1,182 @@
+"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.obligationToolDefinitions = void 0;
+const path = __importStar(require("path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const json_store_1 = require("../arc/json-store");
+const obligations_1 = require("../arc/obligations");
+const packets_1 = require("../arc/packets");
+/**
+ * `let_go` lets the agent release a held work item from its attention loop.
+ *
+ * Two stores need release semantics:
+ *   1. ReturnObligations at `arc/obligations/inner/<id>.json` (status: queued|running|returned|deferred)
+ *      — these are what surface in the "held work items" section of the prompt.
+ *   2. Outer Obligations at `arc/obligations/<id>.json` (status: pending|...|fulfilled)
+ *      — these surface as "i owe <friend>: ..." in the commitments section.
+ *
+ * The pre-existing path to terminal state for both is the `surface` tool, which fulfills
+ * an obligation as a side-effect of delivering a response. When work is resolved EXTERNALLY
+ * (e.g. a PR merged fixed the underlying issue), there is no response to surface — the
+ * agent has no way to clear the item, so it cycles in the prompt every turn.
+ *
+ * `let_go` is the missing primitive: dismissal WITHOUT delivery.
+ */
+function outerObligationsDir(agentRoot) {
+    return path.join(agentRoot, "arc", "obligations");
+}
+function readOuterObligation(agentRoot, id) {
+    return (0, json_store_1.readJsonFile)(outerObligationsDir(agentRoot), id) ?? null;
+}
+function completeRelatedPacket(agentRoot, packet, relation) {
+    try {
+        (0, packets_1.completePonderPacket)(agentRoot, packet.id);
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.packet_completed_for_released_obligation",
+            message: "linked packet completed for released return obligation",
+            meta: { ...relation, packetId: packet.id },
+        });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "repertoire",
+            event: "repertoire.packet_completion_for_released_obligation_failed",
+            message: "failed to complete linked packet for released return obligation",
+            meta: {
+                ...relation,
+                packetId: packet.id,
+                error: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function completePacketsForReturnObligation(agentRoot, returnObligationId) {
+    for (const packet of (0, packets_1.listPonderPacketsByRelatedReturnObligationId)(agentRoot, returnObligationId)) {
+        completeRelatedPacket(agentRoot, packet, { returnObligationId });
+    }
+}
+function completePacketsForObligation(agentRoot, obligationId) {
+    for (const packet of (0, packets_1.listPonderPacketsByRelatedObligationId)(agentRoot, obligationId)) {
+        completeRelatedPacket(agentRoot, packet, { obligationId });
+    }
+}
+function letGo(args, agentRoot, agentName) {
+    if (typeof args.id !== "string" || args.id.trim().length === 0) {
+        return JSON.stringify({ error: "id is required" });
+    }
+    const id = args.id.trim();
+    const reason = typeof args.reason === "string" && args.reason.trim().length > 0
+        ? args.reason.trim()
+        : null;
+    // 1. ReturnObligation (inner) first — these are what the agent sees in "held work items".
+    const ret = (0, obligations_1.readReturnObligation)(agentName, id);
+    if (ret) {
+        if (ret.status === "returned" || ret.status === "deferred") {
+            completePacketsForReturnObligation(agentRoot, id);
+            return JSON.stringify({ kind: "return_obligation", id, already: ret.status });
+        }
+        (0, obligations_1.advanceReturnObligation)(agentName, id, {
+            status: "returned",
+            returnedAt: Date.now(),
+            returnTarget: "surface",
+        });
+        completePacketsForReturnObligation(agentRoot, id);
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.obligation_let_go",
+            message: "agent let go of return obligation",
+            meta: { kind: "return_obligation", id, reason: reason ?? null },
+        });
+        return JSON.stringify({ kind: "return_obligation", let_go: id, reason });
+    }
+    // 2. Outer Obligation — these surface as "i owe ..." in commitments.
+    const outer = readOuterObligation(agentRoot, id);
+    if (outer) {
+        if (outer.status === "fulfilled") {
+            completePacketsForObligation(agentRoot, id);
+            return JSON.stringify({ kind: "obligation", id, already: "fulfilled" });
+        }
+        (0, obligations_1.fulfillObligation)(agentRoot, id);
+        completePacketsForObligation(agentRoot, id);
+        if (reason !== null) {
+            // Persist the dismissal reason as the obligation's latestNote so future-me
+            // can read why this was released (the nerves event also captures it).
+            (0, obligations_1.advanceObligation)(agentRoot, id, { latestNote: reason });
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.obligation_let_go",
+            message: "agent let go of outer obligation",
+            meta: { kind: "obligation", id, reason: reason ?? null },
+        });
+        return JSON.stringify({ kind: "obligation", let_go: id, reason });
+    }
+    return JSON.stringify({ error: `no obligation found with id "${id}"` });
+}
+exports.obligationToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "let_go",
+                description: "release a held work item from my attention. for items that have been resolved externally, no longer apply, or are stale and just cycling in my prompt with nothing to act on. takes the id i see in the 'held work items' section (or any obligation id from arc/obligations/). optional reason is recorded for future me. idempotent — calling on an already-released item returns the existing status, not an error.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        id: {
+                            type: "string",
+                            description: "the obligation id — the bracketed id in 'held work items' (e.g. '1775976317954-s5pno43r'), or any obligation file's id from arc/obligations/.",
+                        },
+                        reason: {
+                            type: "string",
+                            description: "optional one-line reason i'm letting go (e.g. 'resolved externally by PR #701').",
+                        },
+                    },
+                    required: ["id"],
+                },
+            },
+        },
+        handler: (args) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            return letGo({ id: args.id, reason: args.reason }, agentRoot, agentName);
+        },
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "releases durable obligation state" },
+    },
+];

package/dist/repertoire/tools-orientation.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orientationToolDefinitions = void 0;
+const runtime_1 = require("../nerves/runtime");
+exports.orientationToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "orientation_get",
+                description: "return my current turn orientation frame: user-visible speech, channel/source metadata, active referents from the previous assistant response, and the current action policy. use this before mutating durable state when the user's latest message is terse, corrective, or referent-dependent.",
+                parameters: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+        },
+        handler: (_args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.orientation_get",
+                message: "orientation frame requested",
+                meta: { available: !!ctx?.orientationFrame },
+            });
+            if (!ctx?.orientationFrame)
+                return "no orientation frame is available for this turn.";
+            return JSON.stringify(ctx.orientationFrame, null, 2);
+        },
+    },
+];