@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/repertoire/tools-awaiting.js

@@ -0,0 +1,872 @@
+"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.awaitingToolDefinitions = exports.HOUSE_CARE_AWAIT = void 0;
+exports.readAwaitDefinition = readAwaitDefinition;
+exports.setAwaitToolDeps = setAwaitToolDeps;
+exports.resetAwaitToolDeps = resetAwaitToolDeps;
+exports.readOwnerAskForAwait = readOwnerAskForAwait;
+exports.cancelAwaitTool = cancelAwaitTool;
+exports.cancelStaleAwait = cancelStaleAwait;
+exports.isBrokenBindingReason = isBrokenBindingReason;
+exports.failBrokenAwait = failBrokenAwait;
+exports.inspectRelationshipFollowUp = inspectRelationshipFollowUp;
+exports.inspectPeerAwait = inspectPeerAwait;
+exports.hasActiveRelationshipFollowUp = hasActiveRelationshipFollowUp;
+exports.hasActiveExternalEventAwait = hasActiveExternalEventAwait;
+exports.inspectExternalEventAwait = inspectExternalEventAwait;
+exports.cancelRelationshipFollowUps = cancelRelationshipFollowUps;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const identity_1 = require("../heart/identity");
+const session_events_1 = require("../heart/session-events");
+const runtime_1 = require("../nerves/runtime");
+const await_parser_1 = require("../heart/awaiting/await-parser");
+const await_alert_1 = require("../heart/awaiting/await-alert");
+const friends_1 = require("@ouro.bot/friends");
+const a2a_await_delivery_1 = require("../heart/awaiting/a2a-await-delivery");
+const pending_1 = require("../mind/pending");
+const router_1 = require("../heart/external-events/router");
+const obligations_1 = require("../arc/obligations");
+const cadence_1 = require("../heart/daemon/cadence");
+/**
+ * Bundle-root-relative locations.
+ * - `awaiting/<name>.md` — active awaits (status: pending)
+ * - `awaiting/.done/<name>.md` — terminal awaits (resolved/expired/canceled)
+ */
+function awaitingDir(agentRoot) {
+    return path.join(agentRoot, "awaiting");
+}
+function awaitingDoneDir(agentRoot) {
+    return path.join(awaitingDir(agentRoot), ".done");
+}
+function awaitFilePath(agentRoot, name) {
+    return path.join(awaitingDir(agentRoot), `${name}.md`);
+}
+function awaitDoneFilePath(agentRoot, name) {
+    return path.join(awaitingDoneDir(agentRoot), `${name}.md`);
+}
+const VALID_NAME = /^[A-Za-z0-9_-]+$/;
+function validateName(name) {
+    if (!name)
+        return "name is required";
+    if (!VALID_NAME.test(name))
+        return "name must be alphanumeric, underscores, or hyphens";
+    return null;
+}
+/**
+ * The relationship scope a resolve/cancel is judged against. A turn that is ticking an await carries that await's own
+ * binding (`awaitTick`), because the pipeline rewrites `currentSession` to the private-runtime session; that binding covers the
+ * ticked await only, so a tick can never touch any other await. Every other turn is judged by its current session.
+ */
+function relationshipScopeFor(ctx, awaitName) {
+    const tick = ctx.awaitTick;
+    if (tick) {
+        return tick.awaitName === awaitName
+            ? { session: { friendId: tick.friendId, channel: tick.channel, key: tick.key }, requestId: tick.requestId ?? undefined }
+            : { session: undefined, requestId: undefined };
+    }
+    return { session: ctx.currentSession, requestId: ctx.relationshipAuthorization?.requestId };
+}
+function readAwaitDoneDefinition(agentRoot, name) {
+    const filePath = awaitDoneFilePath(agentRoot, name);
+    try {
+        return (0, await_parser_1.parseAwaitFile)(fs.readFileSync(filePath, "utf-8"), filePath);
+    }
+    catch {
+        return null;
+    }
+}
+function readAwaitDefinition(agentRoot, name) {
+    const filePath = awaitFilePath(agentRoot, name);
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return (0, await_parser_1.parseAwaitFile)(content, filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Default delivery deps for the await alert path used from the tool.
+ * Mirrors the proactive-outreach pattern: queue to the private-runtime pending
+ * dir when no live deliverer is registered.
+ */
+function defaultDeliveryDeps(agentName) {
+    const pendingDir = (0, pending_1.getPrivateRuntimePendingDir)(agentName);
+    return {
+        agentName,
+        queuePending: (message) => {
+            // Mirror the write-as-pending convention from tools-session.
+            fs.mkdirSync(pendingDir, { recursive: true });
+            const filename = `${message.timestamp}-${Math.random().toString(36).slice(2, 10)}.json`;
+            fs.writeFileSync(path.join(pendingDir, filename), JSON.stringify({ ...message, content: (0, session_events_1.capStructuredRecordString)(message.content) }, null, 2), "utf-8");
+        },
+    };
+}
+let injected = {};
+function setAwaitToolDeps(deps) {
+    injected = deps;
+}
+function resetAwaitToolDeps() {
+    injected = {};
+}
+function resolveDeliveryDeps(agentName) {
+    const deps = injected.buildDeliveryDeps ? injected.buildDeliveryDeps(agentName) : defaultDeliveryDeps(agentName);
+    return { ...deps, deliverers: { a2a: (0, a2a_await_delivery_1.createA2AAwaitOwnerDeliverer)(agentName), ...deps.deliverers } };
+}
+const ASK_OWNER_MIN_CHOICES = 2;
+const ASK_OWNER_MAX_CHOICES = 4;
+function oneLine(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}
+/**
+ * Validates an ask_owner request. The question and choices are collapsed to single lines because they are archived as
+ * frontmatter, and choices may not contain "|" because the archive joins them with " | ".
+ */
+function parseAskOwner(question, choices) {
+    const cleanQuestion = typeof question === "string" ? oneLine(question) : "";
+    if (!cleanQuestion)
+        return { ok: false, error: "question is required for ask_owner: put the decision to the owner in plain words" };
+    if (!Array.isArray(choices) || choices.length < ASK_OWNER_MIN_CHOICES || choices.length > ASK_OWNER_MAX_CHOICES) {
+        return { ok: false, error: `ask_owner needs ${ASK_OWNER_MIN_CHOICES} to ${ASK_OWNER_MAX_CHOICES} choices` };
+    }
+    const cleanChoices = choices.map((choice) => typeof choice === "string" ? oneLine(choice) : "");
+    if (cleanChoices.some((choice) => !choice))
+        return { ok: false, error: "every ask_owner choice must be a non-empty string" };
+    if (cleanChoices.some((choice) => choice.includes("|")))
+        return { ok: false, error: 'ask_owner choices must not contain "|"' };
+    return { ok: true, question: cleanQuestion, choices: cleanChoices };
+}
+function formatOwnerQuestion(question, choices) {
+    return `${question}\n\n${choices.map((choice) => `- ${choice}`).join("\n")}`;
+}
+function failedAskOwner(agentName, name, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_ask_owner_error", message: "ask_owner could not reach the owner", meta: { agent: agentName, name, error: detail } });
+    return JSON.stringify({ error: `the owner message could not be sent (${detail}); the await is still pending, so ask_owner can be retried` });
+}
+/** At most this many ask_owner closures per requester in a rolling day, so one requester cannot make the Butler pester the owner. */
+const ASK_OWNER_DAILY_LIMIT = 3;
+const ASK_OWNER_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Across every requester who is not the owner, so many requesters together cannot flood the owner either. */
+const ASK_OWNER_NON_OWNER_DAILY_LIMIT = 6;
+function askLedgerPath(agentRoot) {
+    return path.join(awaitingDir(agentRoot), ".asks.jsonl");
+}
+/** Every ask_owner closure is appended here, because the archive is overwritten when an await name is reused. */
+function recordAsk(agentRoot, entry) {
+    fs.mkdirSync(awaitingDir(agentRoot), { recursive: true });
+    fs.appendFileSync(askLedgerPath(agentRoot), `${JSON.stringify(entry)}\n`, "utf-8");
+}
+/**
+ * The most recent time the owner was asked about this await instance, read from the runtime ask ledger (never from model text).
+ * An instance is the await name filed at `createdAt`; an ask recorded before that belongs to an earlier use of the name.
+ */
+function readOwnerAskForAwait(agentRoot, name, createdAt) {
+    let raw;
+    try {
+        raw = fs.readFileSync(askLedgerPath(agentRoot), "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const createdMs = createdAt ? Date.parse(createdAt) : Number.NaN;
+    let found = null;
+    for (const line of raw.split("\n")) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.name !== name || typeof entry.at !== "string")
+                continue;
+            const atMs = Date.parse(entry.at);
+            if (!Number.isFinite(atMs) || (Number.isFinite(createdMs) && atMs < createdMs))
+                continue;
+            if (!found || atMs >= Date.parse(found.at))
+                found = { at: entry.at, question: typeof entry.question === "string" && entry.question.length > 0 ? entry.question : null };
+        }
+        catch {
+            continue;
+        }
+    }
+    return found;
+}
+function recentAskCount(agentRoot, filer, now) {
+    let raw;
+    try {
+        raw = fs.readFileSync(askLedgerPath(agentRoot), "utf-8");
+    }
+    catch {
+        return 0;
+    }
+    return raw.split("\n").filter((line) => {
+        try {
+            const entry = JSON.parse(line);
+            const who = filer === undefined ? entry.owner === false : (entry.filer ?? null) === filer;
+            return who && typeof entry.at === "string" && now - Date.parse(entry.at) < ASK_OWNER_WINDOW_MS;
+        }
+        catch {
+            return false;
+        }
+    }).length;
+}
+const askOwnerInFlight = new Set();
+/** A friend store that cannot be read makes the filer unknown, which is never the owner; it must not fail the ask. */
+async function lookupFiler(agentRoot, friendId) {
+    try {
+        const friend = friendId ? await new friends_1.FileFriendStore(path.join(agentRoot, "friends")).get(friendId) : null;
+        return { isOwner: Boolean(friend && friend.admissionState === "active" && friend.trustLevel === "family" && friend.capabilityProfileId === "sanctuary-owner"), name: friend?.name ?? null };
+    }
+    catch {
+        return { isOwner: false, name: null };
+    }
+}
+function delivered(alert) {
+    return alert?.delivery?.status === "delivered_now" || alert?.delivery?.status === "queued_for_later";
+}
+/**
+ * The await's condition cannot be met without the owner deciding. The owner is asked once, as the agent, in the
+ * owner's own chat, and only then is the await archived as asked_owner. One notice id per await instance ties every
+ * path together: the A2A owner delivery, the direct owner message and the replay sink all dedupe on it, so a retry after
+ * a crash between send and archive sends nothing twice. An await filed from A2A goes through the A2A owner delivery,
+ * which writes the owner notice (or the replay sink during a replay window); the direct notice is only the fallback
+ * when that path blocked or failed. When someone other than the owner filed the await, the text says whose request it is
+ * about, and a non-A2A filer is also told that the owner was asked (the obligation stays open if that could not be said).
+ */
+async function askOwnerTool(name, observation, question, choices, existing, agentRoot, agentName) {
+    const parsed = parseAskOwner(question, choices);
+    if (!parsed.ok)
+        return JSON.stringify({ error: parsed.error });
+    const inFlightKey = `${agentRoot}\0${name}`;
+    if (askOwnerInFlight.has(inFlightKey))
+        return JSON.stringify({ error: `await "${name}" is already being asked; wait for the owner's reply instead of asking again` });
+    askOwnerInFlight.add(inFlightKey);
+    try {
+        const filerId = existing.filed_for_friend_id ?? null;
+        const filer = await lookupFiler(agentRoot, filerId);
+        if (!filer.isOwner && recentAskCount(agentRoot, filerId, Date.now()) >= ASK_OWNER_DAILY_LIMIT) {
+            return JSON.stringify({ error: `ask_owner limit reached: this requester has already had my owner asked ${ASK_OWNER_DAILY_LIMIT} times in the last day; do not retry ask_owner, resolve with verdict 'no' with an observation and keep polling` });
+        }
+        if (!filer.isOwner && recentAskCount(agentRoot, undefined, Date.now()) >= ASK_OWNER_NON_OWNER_DAILY_LIMIT) {
+            return JSON.stringify({ error: `ask_owner limit reached: my owner has already been asked ${ASK_OWNER_NON_OWNER_DAILY_LIMIT} times today on behalf of other requesters; do not retry ask_owner, resolve with verdict 'no' with an observation and keep polling` });
+        }
+        const isA2A = existing.filed_from === "a2a";
+        const noticeId = `await:${name}:asked_owner:${String(existing.created_at)}`;
+        const question = formatOwnerQuestion(parsed.question, parsed.choices);
+        const ownerText = filer.isOwner ? question : (0, a2a_await_delivery_1.askedOwnerText)(question, filer.name ?? (isA2A ? "a connected agent" : "a friend"));
+        let alert = null;
+        let sent = false;
+        if (isA2A) {
+            try {
+                alert = await (0, await_alert_1.deliverAwaitAlert)({ awaitFile: { ...existing, alert: "a2a" }, reason: "asked_owner", observation: question, content: question, deliveryId: noticeId, agentRoot, agentName, deliveryDeps: resolveDeliveryDeps(agentName) });
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_alert_error", message: "await alert delivery threw", meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) } });
+            }
+            sent = delivered(alert);
+        }
+        if (!sent) {
+            try {
+                await (injected.notifyOwner ? injected.notifyOwner(agentName) : (0, a2a_await_delivery_1.defaultNotifyOwner)(agentName))({ noticeId, text: ownerText });
+            }
+            catch (error) {
+                return failedAskOwner(agentName, name, error);
+            }
+        }
+        let friendNotice = null;
+        const tellsFriend = !isA2A && !filer.isOwner && Boolean(filerId);
+        if (tellsFriend) {
+            try {
+                friendNotice = await (0, await_alert_1.deliverAwaitAlert)({ awaitFile: existing, reason: "asked_owner", observation: observation.trim(), content: `About "${existing.condition ?? name}": I have asked the owner how to proceed and will let you know what they decide.`, deliveryId: `${noticeId}:filer`, agentRoot, agentName, deliveryDeps: resolveDeliveryDeps(agentName) });
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_alert_error", message: "await alert delivery threw", meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) } });
+            }
+        }
+        const askedAt = new Date().toISOString();
+        const archive = archiveAwait(agentRoot, name, {
+            status: "asked_owner",
+            asked_at: askedAt,
+            ask_question: parsed.question,
+            ask_choices: parsed.choices.join(" | "),
+            resolution_observation: observation.trim(),
+        });
+        /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
+        if (!archive.ok)
+            return JSON.stringify({ error: archive.error });
+        recordAsk(agentRoot, { filer: filerId, owner: filer.isOwner, name, at: askedAt, question: parsed.question });
+        if (!tellsFriend || delivered(friendNotice))
+            fulfillAwaitObligation(agentRoot, archive.file);
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.await_asked_owner",
+            message: "await closed by asking the owner",
+            meta: { agent: agentName, name, choices: parsed.choices.length },
+        });
+        const summary = (result) => result ? { attempted: result.attempted, status: result.delivery?.status ?? null, skipped: result.skipped ?? null } : null;
+        return JSON.stringify({
+            verdict: "ask_owner",
+            asked: true,
+            archived: awaitDoneFilePath(agentRoot, name),
+            alert: summary(alert),
+            ...(tellsFriend ? { filerNotice: summary(friendNotice) } : {}),
+        });
+    }
+    finally {
+        askOwnerInFlight.delete(inFlightKey);
+    }
+}
+function fileAwait(args, agentRoot, agentName, sessionFriendId, sessionChannel, sessionKey, requestId) {
+    const nameError = validateName(args.name);
+    if (nameError)
+        return JSON.stringify({ error: nameError });
+    if (!args.condition || !args.condition.trim()) {
+        return JSON.stringify({ error: "condition is required" });
+    }
+    if (!args.cadence || !args.cadence.trim()) {
+        return JSON.stringify({ error: "cadence is required" });
+    }
+    // Any ISO timestamp with a zone is accepted and stored in canonical form ("2026-10-12T12:09:00Z" becomes "...:00.000Z"); the alpha.910 replay refused four valid forms in a row.
+    if (args.wake_at && (!/(?:Z|[+-]\d\d:?\d\d)$/i.test(args.wake_at) || !Number.isFinite(Date.parse(args.wake_at)))) {
+        return JSON.stringify({ error: "wake_at must be an ISO timestamp with a time zone, like 2026-10-12T12:09:00Z" });
+    }
+    const wakeAt = args.wake_at ? new Date(args.wake_at).toISOString() : null;
+    const filePath = awaitFilePath(agentRoot, args.name);
+    if (fs.existsSync(filePath)) {
+        return JSON.stringify({ error: `await "${args.name}" already exists` });
+    }
+    const mode = args.mode === "quick" ? "quick" : "full";
+    const alert = sessionChannel === "external-event" ? null : args.alert ?? sessionChannel ?? null;
+    const frontmatter = {
+        condition: (0, session_events_1.capStructuredRecordString)(args.condition.trim()),
+        cadence: (0, session_events_1.capStructuredRecordString)(args.cadence.trim()),
+        alert,
+        mode,
+        max_age: typeof args.max_age === "string" ? (0, session_events_1.capStructuredRecordString)(args.max_age) : null,
+        wake_at: wakeAt,
+        status: "pending",
+        created_at: new Date().toISOString(),
+        filed_from: sessionChannel ?? "unknown",
+        filed_for_friend_id: sessionFriendId ?? null,
+        filed_from_key: sessionKey,
+        request_id: requestId,
+    };
+    let obligationId = null;
+    if (requestId && sessionFriendId && sessionChannel && sessionKey) {
+        const obligation = (0, obligations_1.createObligation)(agentRoot, {
+            origin: { friendId: sessionFriendId, channel: sessionChannel, key: sessionKey },
+            owedTo: { friendId: sessionFriendId, channel: sessionChannel, key: sessionKey },
+            requestId,
+            content: args.condition.trim(),
+        });
+        (0, obligations_1.advanceObligation)(agentRoot, obligation.id, {
+            currentSurface: { kind: "session", label: `${sessionChannel}/${sessionKey}` },
+            currentArtifact: `awaiting/${args.name}.md`,
+            nextAction: args.condition.trim(),
+        });
+        obligationId = obligation.id;
+        frontmatter.obligation_id = obligation.id;
+    }
+    const rendered = (0, await_parser_1.renderAwaitFile)(frontmatter, (0, session_events_1.capStructuredRecordString)(args.body ?? ""));
+    fs.mkdirSync(awaitingDir(agentRoot), { recursive: true });
+    try {
+        fs.writeFileSync(filePath, rendered, "utf-8");
+    }
+    catch (error) {
+        if (obligationId)
+            (0, obligations_1.fulfillObligation)(agentRoot, obligationId);
+        throw error;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.await_filed",
+        message: "filed new await",
+        meta: { agent: agentName, name: args.name, cadence: args.cadence, alert },
+    });
+    return JSON.stringify({ filed: args.name, path: filePath });
+}
+function archiveAwait(agentRoot, name, updates) {
+    const source = awaitFilePath(agentRoot, name);
+    /* v8 ignore start -- defensive: callers (resolve/cancel) already verify the file exists via readAwaitDefinition; this guards the file-disappears-between-calls race @preserve */
+    if (!fs.existsSync(source)) {
+        return { ok: false, error: `await "${name}" not found in awaiting/` };
+    }
+    /* v8 ignore stop */
+    const content = fs.readFileSync(source, "utf-8");
+    const current = (0, await_parser_1.parseAwaitFile)(content, source);
+    // merge frontmatter from the parsed file with updates
+    const merged = {
+        condition: current.condition,
+        cadence: current.cadence,
+        alert: current.alert,
+        mode: current.mode,
+        max_age: current.max_age,
+        wake_at: current.wake_at ?? null,
+        status: current.status,
+        created_at: current.created_at,
+        filed_from: current.filed_from,
+        filed_for_friend_id: current.filed_for_friend_id,
+        filed_from_key: current.filed_from_key,
+        request_id: current.request_id,
+        obligation_id: current.obligation_id,
+        ...updates,
+    };
+    const cappedMerged = Object.fromEntries(Object.entries(merged).map(([key, value]) => [
+        key,
+        typeof value === "string" ? (0, session_events_1.capStructuredRecordString)(value) : value,
+    ]));
+    const rendered = (0, await_parser_1.renderAwaitFile)(cappedMerged, (0, session_events_1.capStructuredRecordString)(current.body));
+    fs.mkdirSync(awaitingDoneDir(agentRoot), { recursive: true });
+    fs.writeFileSync(awaitDoneFilePath(agentRoot, name), rendered, "utf-8");
+    fs.unlinkSync(source);
+    // re-parse the archived file so callers see merged fields (e.g. resolution_observation)
+    const archivedContent = fs.readFileSync(awaitDoneFilePath(agentRoot, name), "utf-8");
+    const archived = (0, await_parser_1.parseAwaitFile)(archivedContent, awaitDoneFilePath(agentRoot, name));
+    return { ok: true, file: archived };
+}
+function fulfillAwaitObligation(agentRoot, awaitFile) {
+    if (awaitFile.obligation_id)
+        (0, obligations_1.fulfillObligation)(agentRoot, awaitFile.obligation_id);
+}
+/** The package-managed daily sweep must stay a byte-exact pending file in awaiting/, so it can only ever be resolved 'no'. */
+exports.HOUSE_CARE_AWAIT = "house-care-sweep";
+const isHouseCareAwait = (name) => String(name ?? "").replace(/\.md$/u, "") === exports.HOUSE_CARE_AWAIT;
+async function resolveAwaitTool(name, verdict, observation, agentRoot, agentName, ask) {
+    const nameError = validateName(name);
+    if (nameError)
+        return JSON.stringify({ error: nameError });
+    const existing = readAwaitDefinition(agentRoot, name);
+    if (!existing) {
+        if (verdict === "ask_owner" && readAwaitDoneDefinition(agentRoot, name)?.status === "asked_owner") {
+            return JSON.stringify({ error: `await "${name}" has already asked the owner and is closed; wait for the owner's reply instead of asking again` });
+        }
+        return JSON.stringify({ error: `await "${name}" not found in awaiting/` });
+    }
+    if (existing.status !== "pending") {
+        return JSON.stringify({ error: `await "${name}" is not pending (status: ${existing.status})` });
+    }
+    if (verdict !== "yes" && verdict !== "no" && verdict !== "ask_owner") {
+        return JSON.stringify({ error: `verdict must be exactly "yes", "no", or "ask_owner" (got ${JSON.stringify(verdict)}); use "no" with an observation while still waiting` });
+    }
+    if (!observation || !observation.trim()) {
+        return JSON.stringify({ error: "observation is required" });
+    }
+    if (verdict === "ask_owner")
+        return askOwnerTool(name, observation, ask?.question, ask?.choices, existing, agentRoot, agentName);
+    if (verdict === "no") {
+        // Update runtime state via recordAwaitCheck-style write
+        const { recordAwaitCheck } = await Promise.resolve().then(() => __importStar(require("../heart/awaiting/await-runtime-state")));
+        recordAwaitCheck(agentRoot, name, observation.trim(), new Date().toISOString());
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.await_check_no",
+            message: "await checked, not yet ready",
+            meta: { agent: agentName, name },
+        });
+        return JSON.stringify({ verdict: "no", recorded: true });
+    }
+    // Request-bound returns stay active through Telegram prepare/send authorization.
+    let alert = null;
+    if (existing.request_id && existing.filed_from !== "external-event") {
+        try {
+            alert = await (0, await_alert_1.deliverAwaitAlert)({ awaitFile: existing, reason: "resolved", observation: observation.trim(), agentRoot, agentName, deliveryDeps: resolveDeliveryDeps(agentName) });
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_alert_error", message: "await alert delivery threw", meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) } });
+        }
+        if (alert?.delivery?.status !== "delivered_now") {
+            return JSON.stringify({ verdict: "yes", archived: null, alert: alert ? { attempted: alert.attempted, status: alert.delivery?.status ?? null, skipped: alert.skipped ?? null } : null, advancedExternalEvents: [] });
+        }
+    }
+    const advancedEvents = existing.filed_from === "external-event" && existing.filed_from_key && existing.wake_at
+        ? (() => {
+            if (!hasActiveExternalEventAwait(agentName, { recordPath: existing.filed_from_key, awaitName: name, wakeAt: existing.wake_at }))
+                throw new Error("External event await authority changed before resolution");
+            const record = (0, router_1.readExternalEventRecord)(existing.filed_from_key);
+            if (record.agent !== agentName || record.recordPath !== existing.filed_from_key || record.executionState !== "handled"
+                || record.disposition?.awaitId !== name || record.disposition.nextWake.kind !== "at" || record.disposition.nextWake.at !== existing.wake_at) {
+                throw new Error("External event await authority changed before resolution");
+            }
+            return [(0, router_1.advanceExternalEventFromAwait)(record.recordPath, { awaitId: name, expectedVersion: record.version, expectedGeneration: record.generation })];
+        })()
+        : [];
+    const archive = archiveAwait(agentRoot, name, {
+        status: "resolved",
+        resolved_at: new Date().toISOString(),
+        resolution_observation: observation.trim(),
+    });
+    /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
+    if (!archive.ok)
+        return JSON.stringify({ error: archive.error });
+    fulfillAwaitObligation(agentRoot, archive.file);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.await_resolved",
+        message: "await resolved",
+        meta: { agent: agentName, name },
+    });
+    if (!existing.request_id) {
+        try {
+            alert = await (0, await_alert_1.deliverAwaitAlert)({ awaitFile: archive.file, reason: "resolved", observation: observation.trim(), agentRoot, agentName, deliveryDeps: resolveDeliveryDeps(agentName) });
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.await_alert_error", message: "await alert delivery threw", meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) } });
+        }
+    }
+    return JSON.stringify({
+        verdict: "yes",
+        archived: awaitDoneFilePath(agentRoot, name),
+        alert: alert ? { attempted: alert.attempted, status: alert.delivery?.status ?? null, skipped: alert.skipped ?? null } : null,
+        advancedExternalEvents: advancedEvents.map((event) => event.recordPath),
+    });
+}
+function cancelAwaitTool(name, reason, agentRoot, agentName) {
+    const nameError = validateName(name);
+    if (nameError)
+        return JSON.stringify({ error: nameError });
+    const existing = readAwaitDefinition(agentRoot, name);
+    if (!existing) {
+        return JSON.stringify({ error: `await "${name}" not found in awaiting/` });
+    }
+    if (existing.status !== "pending") {
+        return JSON.stringify({ error: `await "${name}" is not pending (status: ${existing.status})` });
+    }
+    const updates = {
+        status: "canceled",
+        canceled_at: new Date().toISOString(),
+    };
+    if (reason && reason.trim()) {
+        updates.cancel_reason = reason.trim();
+    }
+    const archive = archiveAwait(agentRoot, name, updates);
+    /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
+    if (!archive.ok)
+        return JSON.stringify({ error: archive.error });
+    fulfillAwaitObligation(agentRoot, archive.file);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.await_canceled",
+        message: "await canceled",
+        meta: { agent: agentName, name },
+    });
+    return JSON.stringify({ canceled: name, archived: awaitDoneFilePath(agentRoot, name) });
+}
+function exactFileIsMissing(filePath) {
+    try {
+        fs.lstatSync(filePath);
+        return false;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+}
+function cancelStaleAwait(agentRoot, agentName, name, reason) {
+    const result = JSON.parse(cancelAwaitTool(name, reason, agentRoot, agentName));
+    if (result.canceled !== name)
+        throw new Error(`Stale await could not be archived for repair: ${result.error ?? name}`);
+}
+/** Binding losses that mean the await is broken, as opposed to finished (fulfilled, expired). */
+function isBrokenBindingReason(reason) {
+    return reason === "request obligation is missing" || reason === "request obligation binding no longer matches";
+}
+/**
+ * An await that can never run is ended, not retried: archived as canceled with the reason, logged as an error, and
+ * the private runtime is told once that the follow-up it promised will not happen. Without this the await stayed
+ * pending and every scheduled wake failed again, silently, for days.
+ */
+function failBrokenAwait(agentRoot, agentName, awaitName, reason) {
+    cancelStaleAwait(agentRoot, agentName, awaitName, reason);
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "senses",
+        event: "senses.relationship_await_failed",
+        message: "relationship await could not run and was canceled",
+        meta: { agentName, awaitName, reason },
+    });
+    (0, pending_1.queuePendingMessageOnce)((0, pending_1.getPrivateRuntimePendingDir)(agentName), {
+        from: agentName,
+        friendId: "self",
+        channel: "inner",
+        key: "dialog",
+        content: `my await "${awaitName}" was canceled because it could not run (${reason}). the follow-up it promised did not happen; i should tell my owner and decide whether to file it again.`,
+        timestamp: Date.now(),
+        packetId: `await-failed:${awaitName}`,
+    });
+}
+function inspectRelationshipFollowUp(agentRoot, input) {
+    const awaiting = readAwaitDefinition(agentRoot, input.awaitName);
+    if (!awaiting)
+        throw new Error(`Await ${input.awaitName} could not be verified`);
+    if (!awaiting.obligation_id)
+        return { active: false, reason: "request obligation is missing" };
+    const obligationPath = path.join(agentRoot, "arc", "obligations", `${awaiting.obligation_id}.json`);
+    const obligation = (0, obligations_1.readVerifiedObligations)(agentRoot).find((candidate) => candidate.id === awaiting.obligation_id);
+    if (!obligation) {
+        if (exactFileIsMissing(obligationPath))
+            return { active: false, reason: "request obligation is missing" };
+        throw new Error(`Request obligation ${awaiting.obligation_id} exists but could not be verified`);
+    }
+    if (obligation.status === "fulfilled")
+        return { active: false, reason: "request obligation is no longer active" };
+    const matches = obligation.requestId === input.requestId
+        && obligation.origin.friendId === input.friendId && obligation.origin.channel === input.channel && obligation.origin.key === input.key
+        && obligation.owedTo?.friendId === input.friendId && obligation.owedTo.channel === input.channel && obligation.owedTo.key === input.key
+        && obligation.currentArtifact === `awaiting/${input.awaitName}.md`
+        && awaiting.status === "pending" && awaiting.obligation_id === obligation.id && awaiting.request_id === input.requestId
+        && awaiting.filed_for_friend_id === input.friendId && awaiting.filed_from === input.channel && awaiting.filed_from_key === input.key;
+    if (!matches)
+        return { active: false, reason: "request obligation binding no longer matches" };
+    const maxAge = (0, cadence_1.parseCadenceToMs)(awaiting.max_age);
+    if (input.allowElapsed !== true && maxAge !== null && awaiting.created_at && (input.now ?? Date.now()) >= Date.parse(awaiting.created_at) + maxAge) {
+        return { active: false, reason: "request obligation await expired" };
+    }
+    return { active: true };
+}
+/**
+ * The binding of an await filed in a plain A2A conversation: it has no request id and no obligation, only the peer's friend
+ * id and conversation key as provenance. It is live while it is still pending, was filed by that peer in that conversation,
+ * and has not outlived its max age.
+ */
+function inspectPeerAwait(agentRoot, input) {
+    const awaiting = readAwaitDefinition(agentRoot, input.awaitName);
+    if (!awaiting)
+        throw new Error(`Await ${input.awaitName} could not be verified`);
+    const matches = awaiting.status === "pending" && !awaiting.request_id && !awaiting.obligation_id
+        && awaiting.filed_for_friend_id === input.friendId && awaiting.filed_from === "a2a" && awaiting.filed_from_key === input.key;
+    if (!matches)
+        return { active: false, reason: "request obligation binding no longer matches" };
+    const maxAge = (0, cadence_1.parseCadenceToMs)(awaiting.max_age);
+    if (input.allowElapsed !== true && maxAge !== null && awaiting.created_at && (input.now ?? Date.now()) >= Date.parse(awaiting.created_at) + maxAge) {
+        return { active: false, reason: "request obligation await expired" };
+    }
+    return { active: true };
+}
+function hasActiveRelationshipFollowUp(agentRoot, input) {
+    if (input.awaitName)
+        return inspectRelationshipFollowUp(agentRoot, { ...input, awaitName: input.awaitName }).active;
+    const obligation = (0, obligations_1.readVerifiedPendingObligations)(agentRoot).find((candidate) => candidate.requestId === input.requestId
+        && candidate.origin.friendId === input.friendId && candidate.origin.channel === input.channel && candidate.origin.key === input.key
+        && candidate.owedTo?.friendId === input.friendId && candidate.owedTo.channel === input.channel && candidate.owedTo.key === input.key
+        && candidate.currentArtifact?.startsWith("awaiting/") && candidate.currentArtifact.endsWith(".md")
+        && (!input.awaitName || candidate.currentArtifact === `awaiting/${input.awaitName}.md`));
+    if (!obligation)
+        return false;
+    const name = path.basename(obligation.currentArtifact, ".md");
+    if (!VALID_NAME.test(name) || obligation.currentArtifact !== `awaiting/${name}.md`)
+        return false;
+    const awaiting = readAwaitDefinition(agentRoot, name);
+    if (!awaiting || awaiting.status !== "pending" || awaiting.obligation_id !== obligation.id || awaiting.request_id !== input.requestId
+        || awaiting.filed_for_friend_id !== input.friendId || awaiting.filed_from !== input.channel || awaiting.filed_from_key !== input.key)
+        return false;
+    const maxAge = (0, cadence_1.parseCadenceToMs)(awaiting.max_age);
+    return input.allowElapsed === true || maxAge === null || !awaiting.created_at || (input.now ?? Date.now()) < Date.parse(awaiting.created_at) + maxAge;
+}
+function hasActiveExternalEventAwait(agentName, input, root = (0, router_1.getExternalEventRoot)()) {
+    return inspectExternalEventAwait(agentName, input, root).active;
+}
+function inspectExternalEventAwait(agentName, input, root = (0, router_1.getExternalEventRoot)()) {
+    const relative = path.relative(path.resolve(root), path.resolve(input.recordPath));
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("External event await record is outside the event root");
+    let record;
+    try {
+        record = (0, router_1.readExternalEventRecord)(input.recordPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { active: false, reason: "external event disposition is missing" };
+        throw error;
+    }
+    const active = record.agent === agentName && record.recordPath === input.recordPath && record.executionState === "handled"
+        && record.disposition?.awaitId === input.awaitName && record.disposition.nextWake.kind === "at" && record.disposition.nextWake.at === input.wakeAt;
+    return active ? { active: true } : { active: false, reason: "external event disposition is no longer active" };
+}
+function cancelRelationshipFollowUps(agentRoot, agentName, input) {
+    const obligations = (0, obligations_1.readVerifiedPendingObligations)(agentRoot).filter((candidate) => candidate.owedTo?.friendId === input.friendId
+        && candidate.owedTo.channel === input.channel && candidate.owedTo.key === input.key);
+    for (const obligation of obligations) {
+        const artifact = obligation.currentArtifact;
+        const name = artifact?.startsWith("awaiting/") && artifact.endsWith(".md") ? path.basename(artifact, ".md") : null;
+        if (name && VALID_NAME.test(name) && artifact === `awaiting/${name}.md` && readAwaitDefinition(agentRoot, name)) {
+            cancelAwaitTool(name, "relationship revoked", agentRoot, agentName);
+        }
+        else {
+            (0, obligations_1.fulfillObligation)(agentRoot, obligation.id);
+        }
+    }
+}
+exports.awaitingToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "await_condition",
+                description: "File a one-shot waiting condition. The daemon polls on cadence; on each tick I evaluate the condition and call resolve_await. When the condition becomes true, an alert fires via my outward channel.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Filename stem (alphanumeric/underscore/hyphen). Must be unique." },
+                        condition: { type: "string", description: "Natural-language condition to watch for." },
+                        cadence: { type: "string", description: "Polling cadence (e.g. '5m', '1h')." },
+                        alert: { type: "string", description: "Channel to alert on (e.g. 'bluebubbles', 'teams'). Defaults to filing session's channel." },
+                        mode: { type: "string", description: "'full' or 'quick'. Defaults 'full'." },
+                        max_age: { type: "string", description: "Optional auto-expiry (e.g. '24h')." },
+                        wake_at: { type: "string", description: "Optional exact canonical ISO time this Await supports." },
+                        body: { type: "string", description: "Optional notes: why I filed this, what 'ready' looks like." },
+                    },
+                    required: ["name", "condition", "cadence"],
+                },
+            },
+        },
+        handler: (a, ctx) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            const event = ctx?.currentExternalEvent;
+            const eventFriendId = event ? ctx?.context?.friend.id ?? null : null;
+            if (event && !eventFriendId)
+                return JSON.stringify({ error: "external event await authority has no exact owner relationship" });
+            return fileAwait({
+                name: a.name,
+                condition: a.condition,
+                cadence: a.cadence,
+                alert: a.alert,
+                mode: a.mode,
+                max_age: a.max_age,
+                wake_at: a.wake_at,
+                body: a.body,
+            }, agentRoot, agentName, eventFriendId ?? ctx?.currentSession?.friendId ?? null, event ? "external-event" : ctx?.currentSession?.channel ?? null, event ? event.recordPath : ctx?.currentSession?.key ?? null, event ? null : ctx?.relationshipAuthorization?.requestId ?? null);
+        },
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "files a durable await condition" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "resolve_await",
+                description: "Resolve a pending await with a verdict. verdict='yes' archives and fires the alert. verdict='no' records the observation and continues polling; still pending is always 'no'. verdict='ask_owner' (with question and choices) closes the await and asks my owner to decide, exactly once: use it when the condition cannot be met without the owner deciding, for example a confirmed dead download. Never use ask_owner for \"not yet\" or a merely suspected problem; that is 'no'.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Await name (filename stem)." },
+                        verdict: { type: "string", enum: ["yes", "no", "ask_owner"], description: "Exactly 'yes' if the condition is met. Exactly 'no' for anything else, including still pending, not yet, or unable to tell: send 'no' with an observation and polling continues. 'ask_owner' only when the condition cannot be met without the owner deciding; it needs question and choices." },
+                        observation: { type: "string", description: "One-line summary of what I saw this tick." },
+                        question: { type: "string", description: "Only for ask_owner: the decision I need from my owner, in plain words." },
+                        choices: { type: "array", items: { type: "string" }, minItems: 2, maxItems: 4, description: "Only for ask_owner: 2 to 4 short options the owner can pick from." },
+                    },
+                    required: ["name", "verdict", "observation"],
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            if (isHouseCareAwait(a.name) && a.verdict !== "no")
+                return JSON.stringify({ error: `${exports.HOUSE_CARE_AWAIT} is the package-managed daily house-care sweep and never resolves: finish every tick with verdict 'no' and a one-line observation, and send any owner digest with house_digest_send` });
+            if (ctx?.relationshipAuthorization) {
+                const awaitName = String(a.name ?? "");
+                const { session, requestId } = relationshipScopeFor(ctx, awaitName);
+                const existing = readAwaitDefinition(agentRoot, awaitName);
+                let binding = null;
+                if (session?.channel === "external-event" && existing?.wake_at) {
+                    binding = inspectExternalEventAwait(agentName, { recordPath: session.key, awaitName, wakeAt: existing.wake_at });
+                }
+                else if (session?.channel === "a2a" && ctx.awaitTick && !requestId && existing && !existing.request_id
+                    && existing.filed_for_friend_id === session.friendId && existing.filed_from === "a2a" && existing.filed_from_key === session.key) {
+                    // A plain peer await is resolved only by its own tick, never from a chat turn.
+                    binding = inspectPeerAwait(agentRoot, { friendId: session.friendId, key: session.key, awaitName });
+                }
+                else if (session && requestId) {
+                    if (existing?.filed_for_friend_id !== session.friendId || existing.filed_from !== session.channel
+                        || existing.filed_from_key !== session.key || existing.request_id !== requestId) {
+                        return JSON.stringify({ error: "resolve_await is limited to the current relationship request or bound external event" });
+                    }
+                    binding = inspectRelationshipFollowUp(agentRoot, { friendId: session.friendId, channel: session.channel, key: session.key, requestId, awaitName });
+                }
+                if (binding && !binding.active) {
+                    if (isBrokenBindingReason(binding.reason))
+                        failBrokenAwait(agentRoot, agentName, awaitName, binding.reason);
+                    else
+                        cancelStaleAwait(agentRoot, agentName, awaitName, binding.reason);
+                    return JSON.stringify({ error: binding.reason });
+                }
+                if (!binding?.active)
+                    return JSON.stringify({ error: "resolve_await is limited to the current relationship request or bound external event" });
+            }
+            return resolveAwaitTool(a.name, a.verdict, a.observation, agentRoot, agentName, { question: a.question, choices: a.choices });
+        },
+        riskProfile: {
+            mutates: ["durable_state_write", "external_side_effect"],
+            risk: "high",
+            reason: "records await observations and may deliver an alert",
+        },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "cancel_await",
+                description: "Cancel a pending await without alerting. Archives with status: canceled.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Await name (filename stem)." },
+                        reason: { type: "string", description: "Optional cancel reason." },
+                    },
+                    required: ["name"],
+                },
+            },
+        },
+        handler: (a, ctx) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            if (isHouseCareAwait(a.name))
+                return JSON.stringify({ error: `${exports.HOUSE_CARE_AWAIT} is the package-managed daily house-care sweep and cannot be cancelled` });
+            if (ctx?.relationshipAuthorization) {
+                const { session, requestId } = relationshipScopeFor(ctx, String(a.name ?? ""));
+                if (!session || !requestId || !hasActiveRelationshipFollowUp(agentRoot, {
+                    friendId: session.friendId,
+                    channel: session.channel,
+                    key: session.key,
+                    requestId,
+                    awaitName: String(a.name ?? ""),
+                }))
+                    return JSON.stringify({ error: "cancel_await is limited to the current relationship request" });
+            }
+            return cancelAwaitTool(a.name, a.reason, agentRoot, agentName);
+        },
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "archives a durable await condition" },
+    },
+];