@ouro.bot/cli 0.1.0-alpha.66 → 0.1.0-alpha.660

package/dist/repertoire/tools-a2a.js

@@ -0,0 +1,283 @@
+"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.a2aToolDefinitions = void 0;
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const types_1 = require("../mind/friends/types");
+const store_file_1 = require("../mind/friends/store-file");
+const runtime_1 = require("../nerves/runtime");
+const client_1 = require("../a2a/client");
+const outboundTaskTokens = new Map();
+function tokenKey(ctx, friendId, taskId) {
+    return `${ctx?.agentRoot ?? "ambient"}\n${friendId}\n${taskId}`;
+}
+function rememberTaskToken(ctx, friendId, task) {
+    /* v8 ignore next -- defensive metadata-shape guard; protocol tasks from Ouro servers always use object metadata @preserve */
+    const token = task.metadata?.a2a && typeof task.metadata.a2a === "object" && !Array.isArray(task.metadata.a2a)
+        ? task.metadata.a2a.accessToken
+        : undefined;
+    if (typeof token === "string" && token.trim()) {
+        outboundTaskTokens.set(tokenKey(ctx, friendId, task.id), token.trim());
+    }
+}
+function rememberedTaskToken(ctx, friendId, taskId) {
+    return outboundTaskTokens.get(tokenKey(ctx, friendId, taskId));
+}
+function redactTaskToken(task) {
+    const a2a = task.metadata?.a2a;
+    if (!a2a || typeof a2a !== "object" || Array.isArray(a2a) || !("accessToken" in a2a))
+        return task;
+    const { accessToken: _accessToken, ...safeA2A } = a2a;
+    return {
+        ...task,
+        metadata: {
+            ...task.metadata,
+            a2a: safeA2A,
+        },
+    };
+}
+function storeFor(ctx) {
+    if (ctx?.friendStore)
+        return ctx.friendStore;
+    /* v8 ignore next -- no-agentRoot fallback depends on process argv; normal tool calls inject agentRoot @preserve */
+    if (ctx?.agentRoot)
+        return new store_file_1.FileFriendStore(path.join(ctx.agentRoot, "friends"));
+    return new store_file_1.FileFriendStore(path.join((0, identity_1.getAgentRoot)(), "friends"));
+}
+function requireTrustedRequester(ctx) {
+    if (!ctx?.context?.friend?.id)
+        return "no friend context — cannot use A2A tools.";
+    if (!(0, types_1.isTrustedLevel)(ctx.context.friend.trustLevel))
+        return "A2A tools require friend or family trust.";
+    return null;
+}
+function isA2APeer(friend) {
+    return friend.kind === "agent" && friend.externalIds.some((id) => id.provider === "a2a-agent");
+}
+function agentNameFromRoot(agentRoot) {
+    if (!agentRoot)
+        return undefined;
+    const base = path.basename(agentRoot);
+    return base.endsWith(".ouro") ? base.slice(0, -".ouro".length) : undefined;
+}
+function textField(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function localA2ACardUrl(agentRoot) {
+    const agentName = agentNameFromRoot(agentRoot);
+    if (!agentName)
+        return undefined;
+    const result = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agentName);
+    if (!result.ok)
+        return undefined;
+    const a2a = result.config.a2a;
+    if (!a2a || typeof a2a !== "object" || Array.isArray(a2a))
+        return undefined;
+    const publicUrl = textField(a2a, "publicUrl");
+    return publicUrl ? `${publicUrl.replace(/\/+$/, "")}/.well-known/agent-card.json` : undefined;
+}
+async function resolveA2AEndpoint(friend) {
+    const metadata = friend.agentMeta?.a2a;
+    if (metadata?.endpointUrl) {
+        return { endpointUrl: metadata.endpointUrl, agentId: metadata.agentId, peerName: friend.name };
+    }
+    if (metadata?.cardUrl) {
+        const card = await (0, client_1.fetchA2AAgentCard)(metadata.cardUrl);
+        const endpointUrl = (0, client_1.endpointForCard)(card);
+        /* v8 ignore next -- fetchA2AAgentCard rejects cards without a usable endpoint before tools see them @preserve */
+        if (!endpointUrl)
+            throw new Error("A2A card has no JSONRPC endpoint");
+        /* v8 ignore next -- empty card names are invalid in practice; friend-name fallback is defensive @preserve */
+        const peerName = card.name || friend.name;
+        return { endpointUrl, agentId: metadata.agentId ?? endpointUrl, peerName };
+    }
+    const external = friend.externalIds.find((id) => id.provider === "a2a-agent");
+    if (external?.externalId?.startsWith("http")) {
+        const card = await (0, client_1.fetchA2AAgentCard)(external.externalId);
+        const endpointUrl = (0, client_1.endpointForCard)(card);
+        /* v8 ignore next -- fetchA2AAgentCard rejects cards without a usable endpoint before tools see them @preserve */
+        if (!endpointUrl)
+            throw new Error("A2A card has no JSONRPC endpoint");
+        /* v8 ignore next -- empty card names are invalid in practice; friend-name fallback is defensive @preserve */
+        const peerName = card.name || friend.name;
+        return { endpointUrl, agentId: external.externalId, peerName };
+    }
+    throw new Error("A2A peer has no endpointUrl or cardUrl in agentMeta.a2a");
+}
+exports.a2aToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "a2a_list_peers",
+                description: "List onboarded A2A agent peers from the friend model. Requires friend or family trust.",
+                parameters: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+        },
+        handler: async (_args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_a2a_list_peers",
+                message: "a2a_list_peers invoked",
+                meta: { tool: "a2a_list_peers" },
+            });
+            const guard = requireTrustedRequester(ctx);
+            if (guard)
+                return guard;
+            const store = storeFor(ctx);
+            const listAll = store.listAll;
+            if (!listAll)
+                return "friend store does not support listing.";
+            const peers = (await listAll.call(store)).filter(isA2APeer);
+            return JSON.stringify(peers.map((peer) => ({
+                id: peer.id,
+                name: peer.name,
+                trustLevel: peer.trustLevel ?? "friend",
+                endpointUrl: peer.agentMeta?.a2a?.endpointUrl,
+                cardUrl: peer.agentMeta?.a2a?.cardUrl,
+            })), null, 2);
+        },
+        summaryKeys: [],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "a2a_send_message",
+                description: "Send a message to a trusted A2A agent peer. The target peer must be an agent friend at friend/family trust.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        friend_id: { type: "string", description: "Friend record ID for the A2A agent peer." },
+                        message: { type: "string", description: "Message or task request to send." },
+                        session_key: { type: "string", description: "Optional A2A context/session key." },
+                    },
+                    required: ["friend_id", "message"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_a2a_send_message",
+                message: "a2a_send_message invoked",
+                meta: { tool: "a2a_send_message", friendId: args.friend_id },
+            });
+            const guard = requireTrustedRequester(ctx);
+            if (guard)
+                return guard;
+            const peer = await storeFor(ctx).get(args.friend_id);
+            if (!peer || !isA2APeer(peer))
+                return `A2A peer not found: ${args.friend_id}`;
+            if (!(0, types_1.isTrustedLevel)(peer.trustLevel))
+                return "target A2A peer must be friend or family trust before outbound messages.";
+            try {
+                const endpoint = await resolveA2AEndpoint(peer);
+                const task = await (0, client_1.sendA2AMessage)({
+                    endpointUrl: endpoint.endpointUrl,
+                    message: args.message,
+                    senderAgentId: agentNameFromRoot(ctx?.agentRoot) ?? "ouro-agent",
+                    senderName: agentNameFromRoot(ctx?.agentRoot) ?? "Ouro agent",
+                    senderCardUrl: localA2ACardUrl(ctx?.agentRoot),
+                    sessionKey: args.session_key,
+                });
+                rememberTaskToken(ctx, peer.id, task);
+                return JSON.stringify(redactTaskToken(task), null, 2);
+            }
+            catch (error) {
+                return `A2A send error: ${error instanceof Error ? error.message : /* v8 ignore next -- defensive non-Error transport failures */ String(error)}`;
+            }
+        },
+        summaryKeys: ["friend_id", "session_key"],
+        riskProfile: { mutates: "external_side_effect", risk: "high", reason: "sends a message to a remote agent peer" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "a2a_get_task",
+                description: "Fetch a task from a trusted A2A agent peer.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        friend_id: { type: "string", description: "Friend record ID for the A2A agent peer." },
+                        task_id: { type: "string", description: "Remote A2A task ID." },
+                        access_token: { type: "string", description: "Optional task access token from an external A2A response; omitted for tasks sent through a2a_send_message because Ouro stores it out of transcript." },
+                    },
+                    required: ["friend_id", "task_id"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_a2a_get_task",
+                message: "a2a_get_task invoked",
+                meta: { tool: "a2a_get_task", friendId: args.friend_id, taskId: args.task_id },
+            });
+            const guard = requireTrustedRequester(ctx);
+            if (guard)
+                return guard;
+            const peer = await storeFor(ctx).get(args.friend_id);
+            if (!peer || !isA2APeer(peer))
+                return `A2A peer not found: ${args.friend_id}`;
+            if (!(0, types_1.isTrustedLevel)(peer.trustLevel))
+                return "target A2A peer must be friend or family trust before task lookup.";
+            try {
+                const endpoint = await resolveA2AEndpoint(peer);
+                const task = await (0, client_1.getA2ATask)({
+                    endpointUrl: endpoint.endpointUrl,
+                    taskId: args.task_id,
+                    accessToken: args.access_token ?? rememberedTaskToken(ctx, peer.id, args.task_id),
+                    senderAgentId: agentNameFromRoot(ctx?.agentRoot) ?? "ouro-agent",
+                    senderName: agentNameFromRoot(ctx?.agentRoot) ?? "Ouro agent",
+                    senderCardUrl: localA2ACardUrl(ctx?.agentRoot),
+                });
+                rememberTaskToken(ctx, peer.id, task);
+                return JSON.stringify(redactTaskToken(task), null, 2);
+            }
+            catch (error) {
+                return `A2A task error: ${error instanceof Error ? error.message : /* v8 ignore next -- defensive non-Error transport failures */ String(error)}`;
+            }
+        },
+        summaryKeys: ["friend_id", "task_id"],
+    },
+];

package/dist/repertoire/tools-attachments.js

@@ -0,0 +1,317 @@
+"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.attachmentToolDefinitions = void 0;
+const fs = __importStar(require("node:fs/promises"));
+const identity_1 = require("../heart/identity");
+const provider_credentials_1 = require("../heart/provider-credentials");
+const minimax_1 = require("../heart/providers/minimax");
+const minimax_vlm_1 = require("../heart/providers/minimax-vlm");
+const store_1 = require("../heart/attachments/store");
+const materialize_1 = require("../heart/attachments/materialize");
+const runtime_1 = require("../nerves/runtime");
+const tool_results_1 = require("./tool-results");
+const LIST_ATTACHMENTS_DESCRIPTION = "List the most recent attachments the harness preserved across senses. Use this when you need a stable attachment_id, " +
+    "when a repair flow says an attachment could not be found, or when you want to inspect what artifacts are currently on hand " +
+    "before asking the user to resend anything.";
+const MATERIALIZE_ATTACHMENT_DESCRIPTION = "Materialize an attachment into a concrete file path the harness can inspect or hand to other tools. " +
+    "Use variant=original when you want the raw file. Use variant=vision_safe for images when you want the harness to normalize " +
+    "size and format into a VLM-safe image before retrying.";
+const DESCRIBE_IMAGE_DESCRIPTION = "Use this to inspect an image attachment with a targeted question, or to re-interrogate an image after a wrong first answer. " +
+    "The harness materializes the original attachment, normalizes it into a VLM-safe image when needed, and sends it through the vision-language model. " +
+    "Prefer specific prompts like 'what is the confirmation number?' over 'describe this image'. " +
+    "Pass attachment_id when you have it; attachment_guid is accepted as a compatibility alias.";
+function trimArg(value) {
+    return value?.trim() ?? "";
+}
+function resolveAttachmentId(args) {
+    return trimArg(args.attachment_id) || trimArg(args.attachment_guid);
+}
+function parseLimit(raw) {
+    if (!raw)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return parsed;
+}
+function normalizeThrownReason(error) {
+    const rendered = String(error);
+    return rendered.startsWith("Error: ") ? rendered.slice(7) : rendered;
+}
+function attachmentNotFound(tool, attachmentId) {
+    const friction = {
+        kind: "local_repair",
+        recoverability: "transformable",
+        summary: `Attachment ${attachmentId} is not in the recent attachment store anymore.`,
+        signature: `${tool}:attachment-not-found`,
+        suggested_next_actions: [
+            {
+                kind: "tool",
+                tool: "list_recent_attachments",
+                reason: "Find the current attachment_id for the artifact you want to inspect before retrying.",
+            },
+        ],
+    };
+    return (0, tool_results_1.frictionToolResult)(tool, friction);
+}
+function missingAttachmentId(tool) {
+    return (0, tool_results_1.frictionToolResult)(tool, {
+        kind: "input_error",
+        recoverability: "transformable",
+        summary: "An attachment id is required for this tool call.",
+        signature: `${tool}:missing-attachment-id`,
+        suggested_next_actions: [
+            {
+                kind: "tool",
+                tool: "list_recent_attachments",
+                reason: "Inspect the current recent attachments and retry with attachment_id.",
+            },
+        ],
+    });
+}
+function missingPrompt() {
+    return (0, tool_results_1.frictionToolResult)("describe_image", {
+        kind: "input_error",
+        recoverability: "transformable",
+        summary: "describe_image needs a targeted prompt before retrying.",
+        signature: "describe_image:missing-prompt",
+        suggested_next_actions: [
+            {
+                kind: "message",
+                message: "Retry with a specific question like 'what is the confirmation number?' or 'what date is shown?'",
+            },
+        ],
+    });
+}
+function normalizeMaterializeError(tool, attachmentId, reason) {
+    if (reason.startsWith("Attachment not found:")) {
+        return attachmentNotFound(tool, attachmentId);
+    }
+    if (reason.includes("is not an image")) {
+        return (0, tool_results_1.frictionToolResult)(tool, {
+            kind: "input_error",
+            recoverability: "transformable",
+            summary: `Attachment ${attachmentId} is not an image, so it cannot produce a vision_safe variant.`,
+            signature: `${tool}:not-image`,
+            suggested_next_actions: [
+                {
+                    kind: "tool",
+                    tool: "materialize_attachment",
+                    reason: "Retry with variant=original if you need the raw file instead.",
+                    args: { attachment_id: attachmentId, variant: "original" },
+                },
+            ],
+        });
+    }
+    return (0, tool_results_1.frictionToolResult)(tool, {
+        kind: "local_repair",
+        recoverability: "retryable",
+        summary: reason,
+        signature: `${tool}:materialize-failed`,
+        suggested_next_actions: [
+            {
+                kind: "tool",
+                tool: "materialize_attachment",
+                reason: "Retry materialization once more in case the file path or normalization target changed.",
+                args: { attachment_id: attachmentId, variant: "vision_safe" },
+            },
+        ],
+    });
+}
+async function buildImageDataUrl(filePath, mimeType) {
+    const buffer = await fs.readFile(filePath);
+    const encoded = buffer.toString("base64");
+    const normalizedMime = mimeType?.trim().toLowerCase() || "image/jpeg";
+    return `data:${normalizedMime};base64,${encoded}`;
+}
+exports.attachmentToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "list_recent_attachments",
+                description: LIST_ATTACHMENTS_DESCRIPTION,
+                parameters: {
+                    type: "object",
+                    properties: {
+                        kind: {
+                            type: "string",
+                            enum: ["image", "audio", "document", "binary", "unknown"],
+                            description: "Optional attachment kind filter.",
+                        },
+                        limit: {
+                            type: "string",
+                            description: "Optional numeric limit for how many attachments to return.",
+                        },
+                    },
+                },
+            },
+        },
+        handler: async (args) => {
+            const agentName = (0, identity_1.getAgentName)();
+            const kind = trimArg(args.kind);
+            const attachments = (0, store_1.listRecentAttachments)(agentName, {
+                kind: kind ? kind : undefined,
+                limit: parseLimit(args.limit),
+            });
+            return (0, tool_results_1.okToolResult)("list_recent_attachments", attachments);
+        },
+        summaryKeys: ["kind", "limit"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "materialize_attachment",
+                description: MATERIALIZE_ATTACHMENT_DESCRIPTION,
+                parameters: {
+                    type: "object",
+                    properties: {
+                        attachment_id: {
+                            type: "string",
+                            description: "Stable attachment id such as attachment:cli-local-file:... or attachment:bluebubbles:...",
+                        },
+                        attachment_guid: {
+                            type: "string",
+                            description: "Compatibility alias for older callers. Prefer attachment_id.",
+                        },
+                        variant: {
+                            type: "string",
+                            enum: ["original", "vision_safe"],
+                            description: "Which attachment variant to materialize.",
+                        },
+                    },
+                    required: ["variant"],
+                },
+            },
+        },
+        handler: async (args) => {
+            const attachmentId = resolveAttachmentId(args);
+            if (!attachmentId) {
+                return missingAttachmentId("materialize_attachment");
+            }
+            const agentName = (0, identity_1.getAgentName)();
+            const variant = trimArg(args.variant) === "vision_safe" ? "vision_safe" : "original";
+            try {
+                const materialized = await (0, materialize_1.materializeAttachment)(agentName, attachmentId, { variant });
+                return (0, tool_results_1.okToolResult)("materialize_attachment", materialized);
+            }
+            catch (error) {
+                const reason = normalizeThrownReason(error);
+                return normalizeMaterializeError("materialize_attachment", attachmentId, reason);
+            }
+        },
+        summaryKeys: ["attachment_id", "attachment_guid", "variant"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "describe_image",
+                description: DESCRIBE_IMAGE_DESCRIPTION,
+                parameters: {
+                    type: "object",
+                    properties: {
+                        attachment_id: {
+                            type: "string",
+                            description: "Stable attachment id for the image you want to inspect.",
+                        },
+                        attachment_guid: {
+                            type: "string",
+                            description: "Compatibility alias for older callers. Prefer attachment_id.",
+                        },
+                        prompt: {
+                            type: "string",
+                            description: "A targeted question about the image.",
+                        },
+                    },
+                    required: ["prompt"],
+                },
+            },
+        },
+        handler: async (args) => {
+            const attachmentId = resolveAttachmentId(args);
+            if (!attachmentId) {
+                return missingAttachmentId("describe_image");
+            }
+            const prompt = trimArg(args.prompt);
+            if (!prompt) {
+                return missingPrompt();
+            }
+            const agentName = (0, identity_1.getAgentName)();
+            try {
+                const materialized = await (0, materialize_1.materializeAttachment)(agentName, attachmentId, { variant: "vision_safe" });
+                const imageDataUrl = await buildImageDataUrl(materialized.path, materialized.mimeType);
+                const credential = await (0, provider_credentials_1.readProviderCredentialRecord)(agentName, "minimax");
+                const apiKey = credential.ok ? credential.record.credentials.apiKey : undefined;
+                if (!apiKey) {
+                    return (0, tool_results_1.frictionToolResult)("describe_image", {
+                        kind: "external_blocker",
+                        recoverability: "blocked",
+                        summary: "MiniMax credentials are missing, so image understanding is unavailable until credentials are fixed.",
+                        signature: "describe_image:minimax-missing-key",
+                        suggested_next_actions: [
+                            {
+                                kind: "message",
+                                message: "Run `ouro auth --agent <agent> --provider minimax`, then retry describe_image.",
+                            },
+                        ],
+                    });
+                }
+                const description = await (0, minimax_vlm_1.minimaxVlmDescribe)({
+                    apiKey: String(apiKey),
+                    prompt,
+                    imageDataUrl,
+                    baseURL: minimax_1.MINIMAX_PROVIDER_BASE_URL,
+                    attachmentGuid: attachmentId,
+                    mimeType: materialized.mimeType,
+                });
+                (0, runtime_1.emitNervesEvent)({
+                    component: "tools",
+                    event: "tool.describe_image_success",
+                    message: "describe_image returned a description",
+                    meta: { attachmentId },
+                });
+                return description;
+            }
+            catch (error) {
+                const reason = normalizeThrownReason(error);
+                return normalizeMaterializeError("describe_image", attachmentId, reason);
+            }
+        },
+        summaryKeys: ["attachment_id", "attachment_guid", "prompt"],
+    },
+];