@ouro.bot/cli 0.1.0-alpha.742 → 0.1.0-alpha.744

package/dist/repertoire/relationship-authorization.js

@@ -0,0 +1,194 @@
+"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.renderRelationshipPreferences = renderRelationshipPreferences;
+exports.withRelationshipPreference = withRelationshipPreference;
+exports.loadRelationshipCapabilityRegistry = loadRelationshipCapabilityRegistry;
+exports.relationshipSubjectFromFriend = relationshipSubjectFromFriend;
+exports.createRelationshipAuthorizationEvaluator = createRelationshipAuthorizationEvaluator;
+exports.resolveProfileScopedRelationshipAuthorization = resolveProfileScopedRelationshipAuthorization;
+exports.authorizeRelationshipAccess = authorizeRelationshipAccess;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+function renderRelationshipPreferences(friend) {
+    const now = Date.now();
+    return Object.entries(friend.relationshipPolicy?.preferences ?? {})
+        .filter(([, preference]) => !preference.expiresAt || Date.parse(preference.expiresAt) > now)
+        .slice(0, 20)
+        .map(([category, preference]) => `- source=${preference.source}; provenance=${preference.provenance}; category=${category}; value=${String(preference.value).replace(/\s+/gu, " ").trim().slice(0, 500)}; version=${preference.version}; precedence=current${preference.expiresAt ? `; expires=${preference.expiresAt}` : ""}`);
+}
+function withRelationshipPreference(friend, input) {
+    const current = friend.relationshipPolicy ?? { schemaVersion: 1, version: 0, preferences: {} };
+    const previous = current.preferences[input.category];
+    return {
+        ...friend,
+        relationshipPolicy: {
+            schemaVersion: 1,
+            version: current.version + 1,
+            preferences: { ...current.preferences, [input.category]: { value: input.value, provenance: input.provenance, source: input.source, version: (previous?.version ?? 0) + 1 } },
+        },
+        updatedAt: new Date().toISOString(),
+    };
+}
+const deny = (reason) => ({ allowed: false, reason });
+function authorizationReceipt(value) {
+    return `relationship-${(0, node_crypto_1.createHash)("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function stringList(value, label) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim()))
+        throw new Error(`${label} must be a string array`);
+    return [...new Set(value)];
+}
+function loadRelationshipCapabilityRegistry(agentRoot) {
+    const filePath = path.join(agentRoot, "tool-profiles.json");
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (raw.version !== 2 || !raw.profiles || typeof raw.profiles !== "object" || Array.isArray(raw.profiles))
+        throw new Error("relationship capability registry version 2 is required");
+    const profiles = {};
+    for (const [id, value] of Object.entries(raw.profiles)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`relationship capability profile ${id} is invalid`);
+        const candidate = value;
+        if (!Number.isInteger(candidate.version) || Number(candidate.version) < 1)
+            throw new Error(`relationship capability profile ${id} version is invalid`);
+        profiles[id] = {
+            id,
+            version: Number(candidate.version),
+            contextScopes: stringList(candidate.contextScopes, `${id}.contextScopes`),
+            toolNames: stringList(candidate.toolNames, `${id}.toolNames`),
+            effectScopes: stringList(candidate.effectScopes, `${id}.effectScopes`),
+        };
+    }
+    return { version: 2, profiles };
+}
+function relationshipSubjectFromFriend(friend) {
+    return {
+        friendId: friend.id,
+        trustLevel: friend.trustLevel ?? "stranger",
+        admissionState: friend.admissionState ?? "unverified",
+        initiativePolicy: friend.initiativePolicy ?? "none",
+        ...(friend.capabilityProfileId ? { capabilityProfileId: friend.capabilityProfileId } : {}),
+    };
+}
+function createRelationshipAuthorizationEvaluator(input) {
+    const subject = relationshipSubjectFromFriend(input.friend);
+    const relationshipProfile = subject.capabilityProfileId ? input.registry.profiles[subject.capabilityProfileId] : undefined;
+    const turnProfile = input.profileId ? input.registry.profiles[input.profileId] : relationshipProfile;
+    const profile = relationshipProfile && turnProfile
+        ? {
+            id: turnProfile.id,
+            version: turnProfile.version,
+            contextScopes: turnProfile.contextScopes.filter((scope) => relationshipProfile.contextScopes.includes(scope)),
+            toolNames: turnProfile.toolNames.filter((name) => relationshipProfile.toolNames.includes(name)),
+            effectScopes: turnProfile.effectScopes.filter((scope) => relationshipProfile.effectScopes.includes(scope)),
+        }
+        : undefined;
+    const effectiveSubject = { ...subject, ...(profile ? { capabilityProfileId: profile.id } : {}) };
+    const profiles = profile ? [profile] : [];
+    const evaluate = (request) => authorizeRelationshipAccess({
+        relationship: effectiveSubject,
+        profiles,
+        request,
+        activeRequestId: input.requestId,
+        requestPhase: input.requestPhase,
+    });
+    const advertisedToolNames = profile?.toolNames.filter((name) => evaluate({ kind: "tool", name, ...(input.requestId ? { requestId: input.requestId, returnTargetFriendId: subject.friendId } : {}) }).allowed) ?? [];
+    const authorizedContextScopes = profile?.contextScopes.filter((scope) => evaluate({ kind: "context", scope }).allowed) ?? [];
+    return {
+        subject,
+        ...(profile ? { profileId: profile.id } : {}),
+        authorizedContextScopes,
+        advertisedToolNames,
+        ...(input.sessionEventId ? { actor: { friendId: subject.friendId, trustLevel: subject.trustLevel, sessionEventId: input.sessionEventId } } : {}),
+        authorizeContext: (scope) => evaluate({ kind: "context", scope }),
+        authorizeTool: (name) => evaluate({ kind: "tool", name, ...(input.requestId ? { requestId: input.requestId, returnTargetFriendId: subject.friendId } : {}) }),
+        authorizeEffect: (scope) => evaluate({ kind: "effect", scope, ...(input.requestId ? { requestId: input.requestId, returnTargetFriendId: subject.friendId } : {}) }),
+    };
+}
+async function resolveProfileScopedRelationshipAuthorization(input) {
+    const friends = await input.store.listAll?.() ?? [];
+    const matches = friends.filter((friend) => friend.capabilityProfileId === input.relationshipProfileId);
+    if (matches.length !== 1)
+        throw new Error(`relationship profile ${input.relationshipProfileId} must resolve to exactly one Friend`);
+    return createRelationshipAuthorizationEvaluator({
+        friend: matches[0],
+        registry: input.registry,
+        ...(input.profileId ? { profileId: input.profileId } : {}),
+        ...(input.requestId ? { requestId: input.requestId } : {}),
+        ...(input.requestPhase ? { requestPhase: input.requestPhase } : {}),
+        ...(input.sessionEventId ? { sessionEventId: input.sessionEventId } : {}),
+    });
+}
+function authorizeRelationshipAccess(input) {
+    if (input.request.kind === "admission_gate") {
+        const pending = input.pendingAdmission;
+        const now = Date.parse(input.now ?? new Date().toISOString());
+        if (!pending || pending.admissionId !== input.request.admissionId || pending.botId !== input.request.botId || pending.userId !== input.request.userId || pending.chatId !== input.request.chatId || pending.expiresAt !== input.request.expiresAt || now >= Date.parse(input.request.expiresAt) || input.request.idempotencyKey !== `ack:${input.request.admissionId}`) {
+            return deny("admission gate authorization does not match a current pending admission");
+        }
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.relationship_authorized", message: "authorized fixed admission gate acknowledgement", meta: { authorizationKind: "admission_gate", admissionId: input.request.admissionId } });
+        return { allowed: true, authorizationKind: "admission_gate", receiptId: authorizationReceipt(input.request), admissionId: input.request.admissionId, idempotencyKey: input.request.idempotencyKey, expiresAt: input.request.expiresAt };
+    }
+    const relationship = input.relationship;
+    if (!relationship || relationship.admissionState !== "active")
+        return deny("relationship admission is not active");
+    if (relationship.trustLevel !== "friend" && relationship.trustLevel !== "family")
+        return deny("relationship trust is insufficient");
+    const profile = input.profiles.find((candidate) => candidate.id === relationship.capabilityProfileId);
+    if (!profile || !Number.isInteger(profile.version) || profile.version < 1)
+        return deny("relationship capability profile is missing or stale");
+    if (input.request.kind === "context" && !profile.contextScopes.includes(input.request.scope))
+        return deny("context scope is not authorized by the relationship profile");
+    if (input.request.kind === "tool" && !profile.toolNames.includes(input.request.name))
+        return deny("tool is not authorized by the relationship profile");
+    if (input.request.kind === "effect" && !profile.effectScopes.includes(input.request.scope))
+        return deny("effect is not authorized by the relationship profile");
+    const requestId = input.request.kind === "context" ? undefined : input.request.requestId;
+    const returnTarget = input.request.kind === "context" ? undefined : input.request.returnTargetFriendId;
+    if (relationship.initiativePolicy === "none")
+        return deny("initiative policy denies contact");
+    if (relationship.initiativePolicy === "reactive_only" && input.request.kind !== "context") {
+        if (input.requestPhase !== "inbound" || !requestId || requestId !== input.activeRequestId || returnTarget !== relationship.friendId)
+            return deny("initiative policy is reactive only");
+    }
+    if (relationship.initiativePolicy === "request_follow_up_only" && input.request.kind !== "context") {
+        if (!requestId || requestId !== input.activeRequestId || returnTarget !== relationship.friendId)
+            return deny("initiative policy requires the matching active request and return target");
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.relationship_authorized", message: "authorized relationship access", meta: { authorizationKind: "relationship", friendId: relationship.friendId, profileId: profile.id, profileVersion: profile.version, requestKind: input.request.kind } });
+    return { allowed: true, authorizationKind: "relationship", receiptId: authorizationReceipt({ relationship, request: input.request, activeRequestId: input.activeRequestId, requestPhase: input.requestPhase, profile }), friendId: relationship.friendId, profileId: profile.id, profileVersion: profile.version, requestId: requestId ?? null };
+}

package/dist/repertoire/tools-awaiting.js

@@ -34,8 +34,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 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");
@@ -44,6 +52,9 @@ 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)
@@ -108,7 +119,7 @@ function resolveDeliveryDeps(agentName) {
         return injected.buildDeliveryDeps(agentName);
     return defaultDeliveryDeps(agentName);
 }
-function fileAwait(args, agentRoot, agentName, sessionFriendId, sessionChannel) {
+function fileAwait(args, agentRoot, agentName, sessionFriendId, sessionChannel, sessionKey, requestId) {
     const nameError = validateName(args.name);
     if (nameError)
         return JSON.stringify({ error: nameError });
@@ -118,26 +129,55 @@ function fileAwait(args, agentRoot, agentName, sessionFriendId, sessionChannel)
     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 = args.alert ?? sessionChannel ?? null;
+    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 });
-    fs.writeFileSync(filePath, rendered, "utf-8");
+    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",
@@ -162,10 +202,14 @@ function archiveAwait(agentRoot, name, updates) {
         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]) => [
@@ -181,6 +225,10 @@ function archiveAwait(agentRoot, name, updates) {
     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)
@@ -210,7 +258,31 @@ async function resolveAwaitTool(name, verdict, observation, agentRoot, agentName
         });
         return JSON.stringify({ verdict: "no", recorded: true });
     }
-    // verdict === "yes" — archive and alert
+    // 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(),
@@ -219,36 +291,26 @@ async function resolveAwaitTool(name, verdict, observation, agentRoot, agentName
     /* 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 },
     });
-    let alert = null;
-    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) },
-        });
+    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) {
@@ -273,6 +335,7 @@ function cancelAwaitTool(name, reason, agentRoot, agentName) {
     /* 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",
@@ -281,6 +344,105 @@ function cancelAwaitTool(name, reason, agentRoot, agentName) {
     });
     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: {
@@ -297,6 +459,7 @@ exports.awaitingToolDefinitions = [
                         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"],
@@ -306,6 +469,10 @@ exports.awaitingToolDefinitions = [
         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,
@@ -313,8 +480,9 @@ exports.awaitingToolDefinitions = [
                 alert: a.alert,
                 mode: a.mode,
                 max_age: a.max_age,
+                wake_at: a.wake_at,
                 body: a.body,
-            }, agentRoot, agentName, ctx?.currentSession?.friendId ?? null, ctx?.currentSession?.channel ?? null);
+            }, 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" },
     },
@@ -335,9 +503,32 @@ exports.awaitingToolDefinitions = [
                 },
             },
         },
-        handler: async (a) => {
+        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: {
@@ -362,9 +553,21 @@ exports.awaitingToolDefinitions = [
                 },
             },
         },
-        handler: (a) => {
+        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" },

package/dist/repertoire/tools-base.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tools = exports.baseToolDefinitions = exports.editFileReadTracker = exports.renderInnerProgressStatus = exports.speakTool = exports.restTool = exports.settleTool = exports.observeTool = exports.ponderTool = void 0;
+exports.routineActionRequester = routineActionRequester;
 const tools_files_1 = require("./tools-files");
 const tools_shell_1 = require("./tools-shell");
 const tools_notes_1 = require("./tools-notes");
@@ -28,6 +29,7 @@ const tools_runtime_1 = require("./tools-runtime");
 const tools_orientation_1 = require("./tools-orientation");
 const tools_rsvp_1 = require("./tools-rsvp");
 const tools_habits_1 = require("./tools-habits");
+const tools_telegram_contacts_1 = require("./tools-telegram-contacts");
 // Re-export flow tools for consumers that import them from tools-base
 var tools_flow_1 = require("./tools-flow");
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_flow_1.ponderTool; } });
@@ -38,6 +40,18 @@ Object.defineProperty(exports, "speakTool", { enumerable: true, get: function ()
 // Re-export renderInnerProgressStatus for consumers
 var tools_session_2 = require("./tools-session");
 Object.defineProperty(exports, "renderInnerProgressStatus", { enumerable: true, get: function () { return tools_session_2.renderInnerProgressStatus; } });
+function routineActionRequester(ctx) {
+    const actor = ctx?.relationshipAuthorization?.actor;
+    if (!actor)
+        return null;
+    if (actor.trustLevel === "family")
+        return { kind: "owner", friendId: actor.friendId };
+    const requestId = ctx?.relationshipAuthorization?.requestId;
+    const session = ctx?.currentSession;
+    if (actor.trustLevel !== "friend" || !requestId || !session || session.friendId !== actor.friendId)
+        return null;
+    return { kind: "household_request", friendId: actor.friendId, requestId, origin: { friendId: session.friendId, channel: session.channel, key: session.key } };
+}
 // Tracks which file paths have been read via read_file in this session.
 // edit_file requires a file to be read first (must-read-first guard).
 exports.editFileReadTracker = new Set();
@@ -71,6 +85,7 @@ exports.baseToolDefinitions = [
     ...tools_runtime_1.runtimeToolDefinitions,
     ...tools_rsvp_1.rsvpToolDefinitions,
     ...tools_habits_1.habitToolDefinitions,
+    tools_telegram_contacts_1.telegramContactToolDefinition,
 ];
 // Convenience array of just the tool schemas (no handler/integration metadata).
 // Used by consumers that need the OpenAI function-tool format.