@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/repertoire/tools-awaiting.js

@@ -0,0 +1,575 @@
+"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 = void 0;
+exports.readAwaitDefinition = readAwaitDefinition;
+exports.setAwaitToolDeps = setAwaitToolDeps;
+exports.resetAwaitToolDeps = resetAwaitToolDeps;
+exports.cancelAwaitTool = cancelAwaitTool;
+exports.cancelStaleAwait = cancelStaleAwait;
+exports.inspectRelationshipFollowUp = inspectRelationshipFollowUp;
+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 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;
+}
+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) {
+    if (injected.buildDeliveryDeps)
+        return injected.buildDeliveryDeps(agentName);
+    return defaultDeliveryDeps(agentName);
+}
+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" });
+    }
+    if (args.wake_at && (!Number.isFinite(Date.parse(args.wake_at)) || new Date(args.wake_at).toISOString() !== args.wake_at)) {
+        return JSON.stringify({ error: "wake_at must be a canonical ISO timestamp" });
+    }
+    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: typeof args.wake_at === "string" ? (0, session_events_1.capStructuredRecordString)(args.wake_at) : null,
+        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);
+}
+async function resolveAwaitTool(name, verdict, observation, 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})` });
+    }
+    if (verdict !== "yes" && verdict !== "no") {
+        return JSON.stringify({ error: "verdict must be 'yes' or 'no'" });
+    }
+    if (!observation || !observation.trim()) {
+        return JSON.stringify({ error: "observation is required" });
+    }
+    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}`);
+}
+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 };
+}
+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.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Await name (filename stem)." },
+                        verdict: { type: "string", description: "'yes' if the condition is met, 'no' otherwise." },
+                        observation: { type: "string", description: "One-line summary of what I saw this tick." },
+                    },
+                    required: ["name", "verdict", "observation"],
+                },
+            },
+        },
+        handler: async (a, ctx) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            if (ctx?.relationshipAuthorization) {
+                const session = ctx.currentSession;
+                const requestId = ctx.relationshipAuthorization.requestId;
+                const existing = readAwaitDefinition(agentRoot, String(a.name ?? ""));
+                const awaitName = String(a.name ?? "");
+                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 && 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) {
+                    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);
+        },
+        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 (ctx?.relationshipAuthorization) {
+                const session = ctx.currentSession;
+                const requestId = ctx.relationshipAuthorization.requestId;
+                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" },
+    },
+];