@ouro.bot/cli 0.1.0-alpha.751 → 0.1.0-alpha.752

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.752",
+      "changes": [
+        "Make Telegram attachments usable and relationship-private for the Sanctuary Butler.",
+        "Preserve owner-confirmed household kinship without expanding authority.",
+        "Accept verified routine-restart policy grants through the typed boolean contract."
+      ]
+    },
     {
       "version": "0.1.0-alpha.751",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.751",
+  "runtimeVersion": "0.1.0-alpha.752",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-08-30T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.ouro/tool-profiles.json

@@ -2,15 +2,15 @@
   "version": 2,
   "profiles": {
     "sanctuary-owner": {
-      "version": 5,
+      "version": 6,
       "contextScopes": ["household.status", "household.policy", "household.private"],
-      "toolNames": ["external_event_disposition", "query_active_work", "save_friend_note", "telegram_contact_manage", "query_cares", "care_manage", "await_condition", "resolve_await", "cancel_await", "unraid_list_containers", "unraid_get_container_logs", "unraid_get_storage", "sanctuary_get_media_optimization", "unraid_get_disks", "unraid_get_notifications", "unraid_get_system", "unraid_check_services", "sanctuary_get_download_queue", "sanctuary_resume_download_queue", "unraid_restart_container", "steward_policy_manage", "send_message", "ponder", "rest", "settle", "speak"],
+      "toolNames": ["external_event_disposition", "query_active_work", "save_friend_note", "telegram_contact_manage", "query_cares", "care_manage", "await_condition", "resolve_await", "cancel_await", "list_recent_attachments", "materialize_attachment", "describe_image", "unraid_list_containers", "unraid_get_container_logs", "unraid_get_storage", "sanctuary_get_media_optimization", "unraid_get_disks", "unraid_get_notifications", "unraid_get_system", "unraid_check_services", "sanctuary_get_download_queue", "sanctuary_resume_download_queue", "unraid_restart_container", "steward_policy_manage", "send_message", "ponder", "rest", "settle", "speak"],
       "effectScopes": ["telegram.proactive", "telegram.request_return", "telegram.owner_event"]
     },
     "sanctuary-household": {
-      "version": 4,
+      "version": 5,
       "contextScopes": ["household.status", "own_requests"],
-      "toolNames": ["save_friend_note", "await_condition", "resolve_await", "cancel_await", "unraid_list_containers", "unraid_get_storage", "unraid_get_disks", "unraid_get_system", "unraid_check_services", "unraid_restart_container", "settle", "speak"],
+      "toolNames": ["save_friend_note", "await_condition", "resolve_await", "cancel_await", "list_recent_attachments", "materialize_attachment", "describe_image", "unraid_list_containers", "unraid_get_storage", "unraid_get_disks", "unraid_get_system", "unraid_check_services", "unraid_restart_container", "settle", "speak"],
       "effectScopes": ["telegram.request_return"]
     },
     "sanctuary-event": {

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>Mendelow Cloud Butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.751</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.752</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/attachments/sources/index.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAttachmentSourceAdapter = getAttachmentSourceAdapter;
 const bluebubbles_1 = require("./bluebubbles");
 const cli_local_file_1 = require("./cli-local-file");
+const telegram_1 = require("./telegram");
 const ATTACHMENT_SOURCE_ADAPTERS = {
     bluebubbles: bluebubbles_1.blueBubblesAttachmentSourceAdapter,
     "cli-local-file": cli_local_file_1.cliLocalFileAttachmentSourceAdapter,
+    telegram: telegram_1.telegramAttachmentSourceAdapter,
 };
 function getAttachmentSourceAdapter(source) {
     const adapter = ATTACHMENT_SOURCE_ADAPTERS[source];

package/dist/heart/attachments/sources/telegram.js

@@ -0,0 +1,71 @@
+"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.telegramAttachmentSourceAdapter = void 0;
+exports.buildTelegramAttachmentRecord = buildTelegramAttachmentRecord;
+const path = __importStar(require("node:path"));
+const originals_1 = require("../originals");
+const types_1 = require("../types");
+const runtime_1 = require("../../../nerves/runtime");
+function buildTelegramAttachmentRecord(input, now = Date.now()) {
+    if (!input.fileId.trim())
+        throw new Error("Telegram attachment file id is required");
+    if (!path.isAbsolute(input.localPath))
+        throw new Error("Telegram attachment local path must be absolute");
+    (0, runtime_1.emitNervesEvent)({ component: "engine", event: "engine.telegram_attachment_record_built", message: "Telegram attachment record entered the shared attachment substrate", meta: {} });
+    return (0, types_1.createAttachmentRecord)({
+        source: "telegram",
+        sourceId: input.fileId,
+        displayName: input.displayName,
+        mimeType: input.mimeType,
+        byteCount: input.byteCount,
+        sourceData: { localPath: path.resolve(input.localPath) },
+    }, now);
+}
+exports.telegramAttachmentSourceAdapter = {
+    source: "telegram",
+    async materializeOriginal({ attachment, agentRoot }) {
+        if (attachment.source !== "telegram")
+            throw new Error(`telegram adapter cannot materialize ${attachment.source} attachments`);
+        const localPath = attachment.sourceData.localPath;
+        if (typeof localPath !== "string" || !path.isAbsolute(localPath))
+            throw new Error("Telegram attachment local path is invalid");
+        const ownedRoot = path.resolve(agentRoot, "state", "attachments", "materialized", "telegram");
+        if (!path.resolve(localPath).startsWith(`${ownedRoot}${path.sep}`))
+            throw new Error("Telegram attachment local path is outside the owned attachment root");
+        await (0, originals_1.ensureReadableFile)(localPath);
+        return (0, originals_1.buildOriginalMaterializedAttachment)(attachment, localPath);
+    },
+};

package/dist/heart/attachments/store.js

@@ -41,6 +41,7 @@ exports.getRecentAttachment = getRecentAttachment;
 exports.listRecentAttachments = listRecentAttachments;
 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");
 const identity_1 = require("../identity");
 exports.MAX_RECENT_ATTACHMENTS = 100;
@@ -75,8 +76,36 @@ function readRecentAttachments(agentName, agentRoot = (0, identity_1.getAgentRoo
 }
 function writeRecentAttachments(agentName, agentRoot, attachments) {
     const targetPath = getRecentAttachmentsPath(agentName, agentRoot);
-    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    fs.writeFileSync(targetPath, JSON.stringify(attachments, null, 2), "utf-8");
+    const directory = path.dirname(targetPath);
+    fs.mkdirSync(directory, { recursive: true });
+    const temporaryPath = `${targetPath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+    try {
+        fs.writeFileSync(temporaryPath, JSON.stringify(attachments, null, 2), { encoding: "utf-8", mode: 0o600 });
+        const temporary = fs.openSync(temporaryPath, "r");
+        try {
+            fs.fsyncSync(temporary);
+        }
+        finally {
+            fs.closeSync(temporary);
+        }
+        fs.renameSync(temporaryPath, targetPath);
+        const directoryHandle = fs.openSync(directory, "r");
+        try {
+            fs.fsyncSync(directoryHandle);
+        }
+        finally {
+            fs.closeSync(directoryHandle);
+        }
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporaryPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
 }
 function cacheRecentAttachment(agentName, attachment, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
     const deduped = readRecentAttachments(agentName, agentRoot).filter((entry) => entry.id !== attachment.id);

package/dist/mind/prompt.js

@@ -1279,6 +1279,11 @@ function relationshipFriendContextSection(context) {
         `channel: ${context.channel.channel}`,
         "this conversation and this friend's own relationship notes are the only personal context available in this turn.",
     ];
+    const connection = friend.connections?.[0];
+    const connectionName = connection?.name.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 80);
+    const relationship = connection?.relationship.replace(/[\r\n\t]+/gu, " ").trim().slice(0, 40);
+    if (connectionName && relationship)
+        lines.push(`relationship: ${connectionName}’s ${relationship}`);
     if (Object.keys(friend.notes).length > 0) {
         lines.push("", "## what i know about this friend");
         for (const [key, entry] of Object.entries(friend.notes)) {

package/dist/repertoire/tools-attachments.js

@@ -180,13 +180,14 @@ exports.attachmentToolDefinitions = [
                 },
             },
         },
-        handler: async (args) => {
+        handler: async (args, ctx) => {
             const agentName = (0, identity_1.getAgentName)();
             const kind = trimArg(args.kind);
+            const allowed = ctx?.attachmentIds ? new Set(ctx.attachmentIds) : null;
             const attachments = (0, store_1.listRecentAttachments)(agentName, {
                 kind: kind ? kind : undefined,
-                limit: parseLimit(args.limit),
-            });
+                limit: allowed ? undefined : parseLimit(args.limit),
+            }).filter((attachment) => !allowed || allowed.has(attachment.id)).slice(0, parseLimit(args.limit));
             return (0, tool_results_1.okToolResult)("list_recent_attachments", attachments);
         },
         summaryKeys: ["kind", "limit"],
@@ -218,11 +219,13 @@ exports.attachmentToolDefinitions = [
                 },
             },
         },
-        handler: async (args) => {
+        handler: async (args, ctx) => {
             const attachmentId = resolveAttachmentId(args);
             if (!attachmentId) {
                 return missingAttachmentId("materialize_attachment");
             }
+            if (ctx?.attachmentIds && !ctx.attachmentIds.includes(attachmentId))
+                return attachmentNotFound("materialize_attachment", attachmentId);
             const agentName = (0, identity_1.getAgentName)();
             const variant = trimArg(args.variant) === "vision_safe" ? "vision_safe" : "original";
             try {
@@ -262,11 +265,13 @@ exports.attachmentToolDefinitions = [
                 },
             },
         },
-        handler: async (args) => {
+        handler: async (args, ctx) => {
             const attachmentId = resolveAttachmentId(args);
             if (!attachmentId) {
                 return missingAttachmentId("describe_image");
             }
+            if (ctx?.attachmentIds && !ctx.attachmentIds.includes(attachmentId))
+                return attachmentNotFound("describe_image", attachmentId);
             const prompt = trimArg(args.prompt);
             if (!prompt) {
                 return missingPrompt();

package/dist/repertoire/tools-steward-policy.js

@@ -63,15 +63,20 @@ exports.stewardPolicyToolDefinition = {
         else if (args.action === "grant_routine_action") {
             if (args.provenance !== "stated" && args.provenance !== "installed_explicit_policy")
                 throw new Error("routine action provenance is invalid");
+            const targets = arrayArgument(args.targetsJson, "targetsJson");
+            const exclusions = arrayArgument(args.exclusionsJson, "exclusionsJson");
+            const verificationRequired = args.verificationRequired;
+            if (verificationRequired !== true)
+                throw new Error("verificationRequired must be true");
             mutation = {
                 kind: "grant_routine_action",
                 key: args.key ?? "",
                 action: args.routineAction ?? "",
-                targets: arrayArgument(args.targetsJson, "targetsJson"),
+                targets,
                 maxCount: Number(args.maxCount),
                 windowMs: Number(args.windowMs),
-                verificationRequired: args.verificationRequired === "true",
-                exclusions: arrayArgument(args.exclusionsJson, "exclusionsJson"),
+                verificationRequired,
+                exclusions,
                 provenance: args.provenance,
                 ...(args.expiresAt ? { expiresAt: args.expiresAt } : {}),
             };

package/dist/repertoire/tools.js

@@ -58,6 +58,9 @@ const SANCTUARY_RELATIONSHIP_BASE_TOOLS = new Set([
     "await_condition",
     "resolve_await",
     "cancel_await",
+    "list_recent_attachments",
+    "materialize_attachment",
+    "describe_image",
     "send_message",
 ]);
 const SANCTUARY_TELEGRAM_SURFACE = new Set([
@@ -69,6 +72,9 @@ const SANCTUARY_TELEGRAM_SURFACE = new Set([
     "await_condition",
     "resolve_await",
     "cancel_await",
+    "list_recent_attachments",
+    "materialize_attachment",
+    "describe_image",
     ...tools_unraid_1.unraidToolDefinitions.map((definition) => definition.tool.function.name),
     "steward_policy_manage",
     "ponder",

package/dist/senses/telegram-admission.js

@@ -56,6 +56,17 @@ const TERMINAL_STATUSES = new Set([
 ]);
 const ADMISSION_ID = /^[a-f0-9]{20}$/u;
 const CANONICAL_ID = /^[1-9][0-9]*$/u;
+const KINSHIP = new Set(["brother", "sister", "sibling", "mother", "father", "parent", "son", "daughter", "aunt", "uncle", "cousin", "grandmother", "grandfather", "wife", "husband", "partner"]);
+function normalizeKinship(value) {
+    const normalized = value === "mom" || value === "mum" ? "mother"
+        : value === "dad" ? "father"
+            : value === "grandma" ? "grandmother"
+                : value === "grandpa" ? "grandfather"
+                    : value;
+    if (!KINSHIP.has(normalized))
+        throw new Error("Telegram admission kinship is invalid");
+    return normalized;
+}
 const DEFAULT_LIMITS = {
     maxPendingContacts: 32,
     maxTextBytes: 16 * 1024,
@@ -107,6 +118,7 @@ function validateRecord(value, expectedId) {
         || typeof record.displayLabel !== "string" || [...record.displayLabel].length > 120
         || typeof record.displayCode !== "string" || record.displayCode.length < 4 || record.displayCode.length > 32
         || typeof record.hasAttachments !== "boolean"
+        || (record.ownerRelationship !== undefined && !KINSHIP.has(record.ownerRelationship))
         || ![record.createdAt, record.updatedAt, record.expiresAt].every(Number.isSafeInteger)
         || (record.friendId !== null && (typeof record.friendId !== "string" || !record.friendId))
         || (record.acknowledgementArtifactId !== null && typeof record.acknowledgementArtifactId !== "string")
@@ -422,6 +434,7 @@ class FileTelegramAdmissionStore {
             ...(input.friendId ? { friendId: input.friendId } : {}),
             ...(input.acknowledgementArtifactId ? { acknowledgementArtifactId: input.acknowledgementArtifactId } : {}),
             ...(input.ownerCardArtifactId ? { ownerCardArtifactId: input.ownerCardArtifactId } : {}),
+            ...(input.ownerRelationship ? { ownerRelationship: input.ownerRelationship } : {}),
             ...(input.ingress ? { ingressSessionKey: input.ingress.sessionKey, ingressEventId: input.ingress.eventId, ingressReference: input.ingress.reference } : {}),
             ...(terminal || input.ingress ? { quarantinedText: null } : {}),
         };
@@ -532,6 +545,7 @@ function createTelegramAdmissionController(options) {
                 chatId: record.chatId,
                 admissionId: record.id,
                 displayLabel: record.displayLabel,
+                ...(record.ownerRelationship ? { relationship: record.ownerRelationship } : {}),
                 defaults: {
                     trustLevel: "friend",
                     admissionState: "active",
@@ -565,7 +579,7 @@ function createTelegramAdmissionController(options) {
                 });
                 const committed = {
                     ...committedBase,
-                    orientation: { ...exports.NEWLY_ADMITTED_ORIENTATION, attachmentsNeedResend: record.hasAttachments },
+                    orientation: { ...exports.NEWLY_ADMITTED_ORIENTATION, attachmentsNeedResend: record.hasAttachments, ...(record.ownerRelationship ? { relationship: record.ownerRelationship } : {}) },
                 };
                 if (committed.admissionId !== record.id || committed.friendId !== record.friendId || committed.reference !== `telegram-admission:${record.id}`) {
                     throw new Error("Telegram admission committed ingress changed identity");
@@ -584,7 +598,7 @@ function createTelegramAdmissionController(options) {
                 sessionKey: record.ingressSessionKey,
                 eventId: record.ingressEventId,
                 reference: record.ingressReference,
-                orientation: { ...exports.NEWLY_ADMITTED_ORIENTATION, attachmentsNeedResend: record.hasAttachments },
+                orientation: { ...exports.NEWLY_ADMITTED_ORIENTATION, attachmentsNeedResend: record.hasAttachments, ...(record.ownerRelationship ? { relationship: record.ownerRelationship } : {}) },
             });
             if (settlement === "indeterminate") {
                 await compensateFriend(record);
@@ -638,7 +652,9 @@ function createTelegramAdmissionController(options) {
             if (!input.replyToMessageId || Buffer.byteLength(input.text, "utf8") > 80)
                 return null;
             const normalized = input.text.normalize("NFKC").trim().toLocaleLowerCase("en-US");
-            const decision = /^(?:yes|allow|approve|let (?:them|him|her) in|yes,? (?:that(?:'|’)s|that is) my (?:brother|sister|sibling|mom|mother|mum|dad|father|parent|son|daughter|aunt|uncle|cousin|grandmother|grandma|grandfather|grandpa|wife|husband|partner))$/u.test(normalized) ? "allow"
+            const kinshipMatch = /^yes,? (?:that(?:'|’)s|that is) my (brother|sister|sibling|mom|mother|mum|dad|father|parent|son|daughter|aunt|uncle|cousin|grandmother|grandma|grandfather|grandpa|wife|husband|partner)$/u.exec(normalized);
+            const relationship = kinshipMatch ? normalizeKinship(kinshipMatch[1]) : undefined;
+            const decision = /^(?:yes|allow|approve|let (?:them|him|her) in)$/u.test(normalized) || relationship ? "allow"
                 : /^(?:no|deny|decline)$/u.test(normalized) ? "deny"
                     : /^(?:block|block (?:them|him|her))$/u.test(normalized) ? "block"
                         : null;
@@ -650,7 +666,7 @@ function createTelegramAdmissionController(options) {
             const record = options.store.read(binding.admissionId);
             if (record.ownerCardArtifactId !== binding.artifactId || record.status !== "pending")
                 return null;
-            return { admissionId: record.id, decision };
+            return { admissionId: record.id, decision, ...(relationship ? { relationship } : {}) };
         },
         async decide(input) {
             return withDecisionLease(input.admissionId, async () => {
@@ -671,7 +687,7 @@ function createTelegramAdmissionController(options) {
                     await settleOwnerCard(record);
                     return record;
                 }
-                record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "pending", nextStatus: "approved" });
+                record = options.store.compareAndSwap({ admissionId: record.id, expectedStatus: "pending", nextStatus: "approved", ...(input.relationship ? { ownerRelationship: input.relationship } : {}) });
                 record = await resume(record.id);
                 await settleOwnerCard(record);
                 return record;

package/dist/senses/telegram-attachments.js

@@ -0,0 +1,182 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TELEGRAM_ATTACHMENT_BYTES = void 0;
+exports.ingestTelegramAttachments = ingestTelegramAttachments;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const store_1 = require("../heart/attachments/store");
+const store_2 = require("../heart/attachments/store");
+const originals_1 = require("../heart/attachments/originals");
+const originals_2 = require("../heart/attachments/originals");
+const telegram_1 = require("../heart/attachments/sources/telegram");
+const runtime_1 = require("../nerves/runtime");
+exports.MAX_TELEGRAM_ATTACHMENT_BYTES = 20_000_000;
+const MAX_TELEGRAM_ATTACHMENTS_PER_MESSAGE = 8;
+const SAFE_FILE_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]{1,512}$/u;
+async function readBounded(response, limit) {
+    const advertised = Number(response.headers.get("content-length"));
+    if (Number.isFinite(advertised) && advertised > limit)
+        throw new Error("advertised size exceeds limit");
+    if (!response.body)
+        throw new Error("empty response body");
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > limit)
+                throw new Error("download exceeds limit");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+}
+async function atomicWrite(filePath, buffer) {
+    const directory = path.dirname(filePath);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    let handle;
+    try {
+        handle = await fs.open(temporary, "wx", 0o600);
+        await handle.writeFile(buffer);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.rename(temporary, filePath);
+        const directoryHandle = await fs.open(directory, "r");
+        try {
+            await directoryHandle.sync();
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await fs.unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+            throw error; });
+    }
+}
+async function ingestTelegramAttachments(input) {
+    const fetchImpl = input.fetch ?? globalThis.fetch;
+    const unique = [...new Map(input.attachments.map((attachment) => [attachment.fileId, attachment])).values()]
+        .slice(0, MAX_TELEGRAM_ATTACHMENTS_PER_MESSAGE);
+    const attachments = [];
+    const notices = [];
+    for (const candidate of unique) {
+        try {
+            if (!/^[A-Za-z0-9_-]{1,512}$/u.test(candidate.fileId))
+                throw new Error("invalid file id");
+            if (candidate.byteCount !== undefined && (!Number.isSafeInteger(candidate.byteCount) || candidate.byteCount < 0 || candidate.byteCount > exports.MAX_TELEGRAM_ATTACHMENT_BYTES))
+                throw new Error("advertised size exceeds limit");
+            const cached = (0, store_2.getRecentAttachment)(input.agentName, `attachment:telegram:${candidate.fileId}`, input.agentRoot);
+            if (cached?.source === "telegram") {
+                const localPath = cached.sourceData.localPath;
+                if (typeof localPath === "string") {
+                    await (0, originals_2.ensureReadableFile)(localPath);
+                    attachments.push(cached);
+                    continue;
+                }
+            }
+            const recoverable = (0, telegram_1.buildTelegramAttachmentRecord)({
+                fileId: candidate.fileId,
+                displayName: candidate.displayName,
+                mimeType: candidate.mimeType,
+                byteCount: candidate.byteCount,
+                localPath: path.resolve(input.agentRoot, "state", "attachments", ".pending", candidate.fileId),
+            });
+            const recoverablePath = (0, originals_1.originalStoragePath)(input.agentRoot, recoverable, recoverable.mimeType);
+            try {
+                const stat = await fs.lstat(recoverablePath);
+                if (!stat.isFile() || stat.size > exports.MAX_TELEGRAM_ATTACHMENT_BYTES)
+                    throw new Error("persisted attachment is invalid");
+                const recovered = (0, store_1.cacheRecentAttachment)(input.agentName, (0, telegram_1.buildTelegramAttachmentRecord)({
+                    fileId: candidate.fileId,
+                    displayName: candidate.displayName,
+                    mimeType: candidate.mimeType,
+                    byteCount: stat.size,
+                    localPath: recoverablePath,
+                }), input.agentRoot);
+                attachments.push(recovered);
+                continue;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const remote = await input.api.request("getFile", { file_id: candidate.fileId });
+            if (typeof remote.file_path !== "string" || !SAFE_FILE_PATH.test(remote.file_path))
+                throw new Error("invalid remote path");
+            if (remote.file_size !== undefined && (!Number.isSafeInteger(remote.file_size) || remote.file_size < 0 || remote.file_size > exports.MAX_TELEGRAM_ATTACHMENT_BYTES))
+                throw new Error("advertised size exceeds limit");
+            const response = await fetchImpl(`https://api.telegram.org/file/bot${input.botToken}/${remote.file_path}`, { signal: AbortSignal.timeout(30_000) });
+            if (!response.ok)
+                throw new Error(`download failed with HTTP ${response.status}`);
+            const buffer = await readBounded(response, exports.MAX_TELEGRAM_ATTACHMENT_BYTES);
+            const provisional = (0, telegram_1.buildTelegramAttachmentRecord)({
+                fileId: candidate.fileId,
+                displayName: candidate.displayName,
+                mimeType: candidate.mimeType ?? response.headers.get("content-type") ?? undefined,
+                byteCount: buffer.length,
+                localPath: path.resolve(input.agentRoot, "state", "attachments", ".pending", candidate.fileId),
+            });
+            const localPath = (0, originals_1.originalStoragePath)(input.agentRoot, provisional, provisional.mimeType);
+            await atomicWrite(localPath, buffer);
+            const record = (0, store_1.cacheRecentAttachment)(input.agentName, (0, telegram_1.buildTelegramAttachmentRecord)({
+                fileId: candidate.fileId,
+                displayName: candidate.displayName,
+                mimeType: provisional.mimeType,
+                byteCount: buffer.length,
+                localPath,
+            }), input.agentRoot);
+            attachments.push(record);
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.telegram_attachment_ingested", message: "Telegram attachment entered the shared attachment store", meta: { kind: record.kind, byteCount: buffer.length } });
+        }
+        catch (error) {
+            notices.push(`attachment unavailable: ${candidate.displayName}`);
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.telegram_attachment_ingest_error", message: "Telegram attachment ingestion failed", meta: { kind: candidate.kind, reason: error instanceof Error ? error.name : "unknown" } });
+        }
+    }
+    return { attachments, notices };
+}

package/dist/senses/telegram-client.js

@@ -479,18 +479,56 @@ function createTelegramLongPoll(options) {
             reject(signal.reason);
         }, { once: true });
     });
+    const inboundAttachments = (message) => {
+        const result = [];
+        const push = (media, kind, fallbackName, fallbackMimeType) => {
+            if (typeof media?.file_id !== "string" || !media.file_id.trim())
+                return;
+            result.push({
+                fileId: media.file_id,
+                kind,
+                displayName: media.file_name?.trim() || fallbackName,
+                ...((media.mime_type?.trim() || fallbackMimeType) ? { mimeType: media.mime_type?.trim().toLowerCase() || fallbackMimeType } : {}),
+                ...(Number.isSafeInteger(media.file_size) ? { byteCount: media.file_size } : {}),
+            });
+        };
+        const photo = message.photo?.filter((candidate) => typeof candidate.file_id === "string" && candidate.file_id.trim())
+            .sort((left, right) => (left.file_size ?? left.width ?? 0) - (right.file_size ?? right.width ?? 0)).at(-1);
+        if (photo)
+            result.push({ fileId: photo.file_id, kind: "image", displayName: "telegram-photo.jpg", mimeType: "image/jpeg", ...(Number.isSafeInteger(photo.file_size) ? { byteCount: photo.file_size } : {}) });
+        push(message.document, "document", "telegram-document");
+        push(message.audio, "audio", "telegram-audio", "audio/mpeg");
+        push(message.voice, "audio", "telegram-voice.ogg", "audio/ogg");
+        push(message.video, "binary", "telegram-video.mp4", "video/mp4");
+        push(message.animation, "binary", "telegram-animation.mp4", "video/mp4");
+        push(message.sticker, message.sticker?.is_animated || message.sticker?.is_video ? "binary" : "image", message.sticker?.is_animated ? "telegram-sticker.tgs" : message.sticker?.is_video ? "telegram-sticker.webm" : "telegram-sticker.webp", message.sticker?.is_animated ? "application/x-tgsticker" : message.sticker?.is_video ? "video/webm" : "image/webp");
+        return result;
+    };
+    const rawAttachmentCount = (message) => [
+        message.document, message.audio, message.video, message.voice, message.animation, message.sticker,
+    ].filter(Boolean).length + (message.photo?.length ? 1 : 0);
     const authorizedMessage = (update) => {
         const message = update.message;
         const userId = message?.from ? String(message.from.id) : "";
         const chatId = message ? String(message.chat.id) : "";
-        if (!message || message.chat.type !== "private" || userId !== options.expectedUserId || chatId !== options.expectedChatId || typeof message.text !== "string")
+        if (!message || message.chat.type !== "private" || userId !== options.expectedUserId || chatId !== options.expectedChatId)
+            return null;
+        const attachments = inboundAttachments(message);
+        const attachmentCount = rawAttachmentCount(message);
+        const attachmentNotices = attachmentCount > attachments.length
+            ? ["attachment unavailable: Telegram media metadata was incomplete"]
+            : [];
+        const text = message.text ?? message.caption ?? "";
+        if (typeof text !== "string" || (!text && attachmentCount === 0))
             return null;
         return {
             updateId: update.update_id,
             messageId: String(message.message_id),
             userId,
             chatId,
-            text: message.text,
+            text,
+            attachments,
+            ...(attachmentNotices.length ? { attachmentNotices } : {}),
             ...(Number.isSafeInteger(message.reply_to_message?.message_id) && message.reply_to_message.message_id > 0
                 ? { replyToMessageId: String(message.reply_to_message.message_id) }
                 : {}),
@@ -506,6 +544,8 @@ function createTelegramLongPoll(options) {
             return null;
         const displayLabel = [message.from.first_name, message.from.last_name].filter(Boolean).join(" ")
             || (message.from.username ? `@${message.from.username}` : `Telegram user ${userId}`);
+        const attachments = inboundAttachments(message);
+        const attachmentCount = rawAttachmentCount(message);
         return {
             updateId: update.update_id,
             messageId: message.message_id,
@@ -514,8 +554,9 @@ function createTelegramLongPoll(options) {
             chatId,
             text: message.text ?? message.caption ?? "",
             displayLabel,
-            hasAttachments: Boolean(message.document || message.photo?.length || message.audio || message.video
-                || message.voice || message.animation || message.sticker),
+            hasAttachments: attachmentCount > 0,
+            attachments,
+            ...(attachmentCount > attachments.length ? { attachmentNotices: ["attachment unavailable: Telegram media metadata was incomplete"] } : {}),
         };
     };
     const authorizedCallback = (update) => {

package/dist/senses/telegram-effect-adapter.js

@@ -676,7 +676,7 @@ function appendTelegramInboundEvent(envelope, input) {
         name: "telegram-user",
         toolCallId: null,
         toolCalls: [],
-        attachments: [],
+        attachments: [...new Set(input.attachmentIds ?? [])],
         time: { authoredAt: null, authoredAtSource: "unknown", observedAt: input.recordedAt, observedAtSource: "ingest", recordedAt: input.recordedAt, recordedAtSource: "save" },
         relations: {
             replyToEventId: input.relations?.replyToEventId ?? null,
@@ -710,14 +710,16 @@ async function recordTelegramEffectsInSession(input) {
         let changed = false;
         if (input.inbound) {
             const existing = envelope.events.filter((event) => event.relations.references.includes(input.inbound.reference));
-            if (existing.length > 1 || (existing.length === 1 && (existing[0].role !== "user" || existing[0].content !== input.inbound.text))) {
+            const expectedAttachmentIds = [...new Set(input.inbound.attachmentIds ?? [])];
+            if (existing.length > 1 || (existing.length === 1 && (existing[0].role !== "user" || existing[0].content !== input.inbound.text
+                || JSON.stringify(existing[0].attachments) !== JSON.stringify(expectedAttachmentIds)))) {
                 throw new Error("Telegram session has conflicting inbound ingress");
             }
             if (existing.length === 1) {
                 inboundReceipt = { eventId: existing[0].id, reference: input.inbound.reference };
             }
             else {
-                envelope = appendTelegramInboundEvent(envelope, { ...input.inbound, recordedAt: new Date().toISOString() });
+                envelope = appendTelegramInboundEvent(envelope, { ...input.inbound, attachmentIds: expectedAttachmentIds, recordedAt: new Date().toISOString() });
                 inboundReceipt = { eventId: envelope.events.at(-1).id, reference: input.inbound.reference };
                 changed = true;
             }

package/dist/senses/telegram.js

@@ -78,6 +78,8 @@ const approval_store_1 = require("../heart/approval-store");
 const tools_awaiting_1 = require("../repertoire/tools-awaiting");
 const obligations_1 = require("../arc/obligations");
 const orientation_frame_1 = require("../heart/orientation-frame");
+const render_1 = require("../heart/attachments/render");
+const telegram_attachments_1 = require("./telegram-attachments");
 const pending_1 = require("../mind/pending");
 const relationship_authorization_1 = require("../repertoire/relationship-authorization");
 const telegram_admission_1 = require("./telegram-admission");
@@ -1094,9 +1096,11 @@ function createTelegramSenseApp(options) {
                 source: {
                     kind: "telegram_newly_admitted",
                     authority: "presentation_only",
-                    routingHint: input.orientation.attachmentsNeedResend
-                        ? "This is this person’s first admitted turn. Welcome them warmly and briefly explain what the household Butler can help with before answering their request. Their original message included attachments that were not downloaded; ask them to resend those attachments now."
-                        : "This is this person’s first admitted turn. Welcome them warmly and briefly explain what the household Butler can help with before answering their request.",
+                    routingHint: [
+                        "This is this person’s first admitted turn. Welcome them warmly and briefly explain what the household Butler can help with before answering their request.",
+                        input.orientation.relationship ? `The owner identified this person as their ${input.orientation.relationship}.` : null,
+                        input.orientation.attachmentsNeedResend ? "Their original message included attachments that were not downloaded; ask them to resend those attachments now." : null,
+                    ].filter(Boolean).join(" "),
                 },
             }
             : undefined;
@@ -1110,7 +1114,7 @@ function createTelegramSenseApp(options) {
             ingressRelations: { replyToEventId: null, threadRootEventId: null, references: [input.reference] },
             precommittedIngress: { eventId: input.eventId, reference: input.reference },
             ...(orientationFrame ? { orientationFrame } : {}),
-            toolContext: { ...(toolContext ?? {}) },
+            toolContext: { ...(toolContext ?? {}), attachmentIds: input.attachmentIds ?? [] },
             prepareRunAgentOptions: prepareRelationshipRunAgentOptions({ friendId: input.friendId, requestId: input.requestId,
                 sessionEventId: input.eventId, userId: input.userId, chatId: input.chatId, sessionKey: input.sessionKey }),
             deliverySink: { onDelivery: (delivery) => deliver(delivery.text, delivery.kind === "settle") },
@@ -1202,7 +1206,26 @@ function createTelegramSenseApp(options) {
             await recordAcceptedEffects((0, shared_turn_1.getSenseSessionPath)(options.agentName, target.friendId, "telegram", target.sessionKey, agentRoot), [artifact]);
         }
     };
-    const onMessageBody = async (message) => {
+    const hydrateAuthorizedMessage = async (message) => {
+        if (!message.attachments?.length)
+            return { text: [message.text, ...(message.attachmentNotices ?? [])].filter(Boolean).join("\n"), attachmentIds: [] };
+        const ingested = await (0, telegram_attachments_1.ingestTelegramAttachments)({
+            agentName: options.agentName,
+            agentRoot,
+            botToken,
+            api,
+            ...(options.attachmentFetch ? { fetch: options.attachmentFetch } : {}),
+            attachments: message.attachments ?? [],
+        });
+        const attachmentIds = ingested.attachments.map((attachment) => attachment.id);
+        return {
+            text: [message.text, (0, render_1.renderAttachmentBlock)(ingested.attachments), ...(message.attachmentNotices ?? []), ...ingested.notices].filter(Boolean).join("\n"),
+            attachmentIds,
+        };
+    };
+    const onMessageBody = async (rawMessage) => {
+        const hydrated = await hydrateAuthorizedMessage(rawMessage);
+        const message = { ...rawMessage, text: hydrated.text };
         const currentFriendId = configuredOwnerFriendId;
         const currentSessionKey = configuredOwnerSessionKey;
         const currentSessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, currentFriendId, "telegram", currentSessionKey, agentRoot);
@@ -1268,7 +1291,7 @@ function createTelegramSenseApp(options) {
                     store: getEffectJournal(),
                     sessionPath: currentSessionPath,
                     artifacts: [],
-                    inbound: { text: message.text, reference: inboundReference, relations: ingressRelations },
+                    inbound: { text: message.text, reference: inboundReference, attachmentIds: hydrated.attachmentIds, relations: ingressRelations },
                 })
                 : null;
             const collected = await collectToolReceipts(() => runTurn({
@@ -1297,7 +1320,9 @@ function createTelegramSenseApp(options) {
                         }
                     },
                 },
-                ...(toolContext ? { toolContext } : {}),
+                ...(toolContext || options.resolveRelationshipAuthorization ? {
+                    toolContext: { ...(toolContext ?? {}), ...(options.resolveRelationshipAuthorization ? { attachmentIds: hydrated.attachmentIds } : {}) },
+                } : {}),
                 ...(options.resolveRelationshipAuthorization ? {
                     prepareRunAgentOptions: prepareRelationshipRunAgentOptions({
                         friendId: currentFriendId,
@@ -1369,7 +1394,7 @@ function createTelegramSenseApp(options) {
             const fallback = "I couldn't complete that turn. The failure was recorded; please try again.";
             if (deliveredMessageIds.length === 0)
                 turnEffects.push(await deliverButlerEffect(fallback, `turn:${subject}:${message.updateId}:fallback`, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); }));
-            await recordAcceptedEffects(currentSessionPath, turnEffects, { text: message.text, reference: inboundReference });
+            await recordAcceptedEffects(currentSessionPath, turnEffects, { text: message.text, reference: inboundReference, attachmentIds: hydrated.attachmentIds });
         }
         finally {
             if (acceptanceMarker) {
@@ -1412,10 +1437,10 @@ function createTelegramSenseApp(options) {
         }
     };
     const onMessage = (message) => runWithAcceptanceAuditOwner(async () => {
-        const ownerDecision = admissionController?.parseOwnerDecision({
+        const ownerDecision = !message.attachments?.length && !message.attachmentNotices?.length ? admissionController?.parseOwnerDecision({
             text: message.text,
             ...(message.replyToMessageId ? { replyToMessageId: Number(message.replyToMessageId) } : {}),
-        });
+        }) : null;
         if (ownerDecision) {
             const actor = await options.admission?.resolveOwner({ botId: botId, userId: message.userId, chatId: message.chatId, sessionKey: configuredOwnerSessionKey });
             if (!actor)
@@ -1423,6 +1448,11 @@ function createTelegramSenseApp(options) {
             await admissionController.decide({ ...ownerDecision, actorFriendId: actor.friendId });
             return;
         }
+        if ((message.attachments?.length || message.attachmentNotices?.length) && options.admission) {
+            const actor = await options.admission.resolveOwner({ botId: botId, userId: message.userId, chatId: message.chatId, sessionKey: configuredOwnerSessionKey });
+            if (!actor || actor.friendId !== configuredOwnerFriendId)
+                throw new Error("Telegram attachment owner relationship is not active");
+        }
         await onMessageBody(message);
     });
     const onUnknownMessage = admissionController && options.admission ? async (message) => {
@@ -1431,12 +1461,21 @@ function createTelegramSenseApp(options) {
             await admissionController.handleUnknown(message);
             return;
         }
+        const hydrated = await hydrateAuthorizedMessage({
+            updateId: message.updateId,
+            messageId: String(message.messageId),
+            userId: message.userId,
+            chatId: message.chatId,
+            text: message.text,
+            attachments: message.attachments,
+            attachmentNotices: message.attachmentNotices,
+        });
         const sessionKey = `telegram:${message.botId}:${message.userId}`;
         const reference = `telegram-inbound:${(0, node_crypto_1.createHmac)("sha256", identityKey).update(`${message.botId}\0${message.userId}\0${message.updateId}\0${message.messageId}`).digest("hex")}`;
         const sessionPath = (0, shared_turn_1.getSenseSessionPath)(options.agentName, approved.friendId, "telegram", sessionKey, agentRoot);
-        const receipt = await (0, telegram_effect_adapter_1.recordTelegramEffectsInSession)({ store: getEffectJournal(), sessionPath, artifacts: [], inbound: { text: message.text, reference } });
+        const receipt = await (0, telegram_effect_adapter_1.recordTelegramEffectsInSession)({ store: getEffectJournal(), sessionPath, artifacts: [], inbound: { text: hydrated.text, reference, attachmentIds: hydrated.attachmentIds } });
         await dispatchResolvedRelationshipTurn({ friendId: approved.friendId, sessionKey, requestId: reference, eventId: receipt.eventId,
-            reference, text: message.text, userId: message.userId, chatId: message.chatId });
+            reference, text: hydrated.text, attachmentIds: hydrated.attachmentIds, userId: message.userId, chatId: message.chatId });
     } : undefined;
     const onUpdate = async (update) => {
         const callback = update.callback_query;
@@ -1812,8 +1851,14 @@ async function createProductionTelegramRelationshipComposition(agentName, creden
                 target: { kind: "create", record: { id: (0, node_crypto_1.randomUUID)(), name: "Household member" } },
             });
             const current = claimed.record;
-            const updated = { ...current, trustLevel: input.defaults.trustLevel, admissionState: input.defaults.admissionState,
-                initiativePolicy: input.defaults.initiativePolicy, capabilityProfileId: input.defaults.capabilityProfileId, updatedAt: new Date().toISOString() };
+            const now = new Date().toISOString();
+            const connections = input.relationship
+                ? [{ name: owner.name, relationship: input.relationship }, ...(current.connections ?? []).filter((connection) => !(connection.name === owner.name && connection.relationship === input.relationship))]
+                : current.connections;
+            const updated = { ...current,
+                ...(connections ? { connections } : {}),
+                trustLevel: input.defaults.trustLevel, admissionState: input.defaults.admissionState,
+                initiativePolicy: input.defaults.initiativePolicy, capabilityProfileId: input.defaults.capabilityProfileId, updatedAt: now };
             await store.put(current.id, updated);
             return { kind: claimed.status === "created" ? "created" : "existing", friendId: current.id };
         },

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.751",
+  "version": "0.1.0-alpha.752",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.751",
+      "version": "0.1.0-alpha.752",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.751",
+  "version": "0.1.0-alpha.752",
   "engines": {
     "node": ">=22"
   },