spectrum-ts 1.14.0 → 1.15.0

package/dist/{chunk-ODO6KRGX.js → chunk-2B76JFHX.js}

@@ -3,7 +3,7 @@ import {
   fetchUrlBytes,
   readSchema,
   streamSchema
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/content/voice.ts
 import { createReadStream } from "fs";

package/dist/{chunk-UGBHJEX2.js → chunk-BGV4SFVJ.js}

@@ -2,7 +2,7 @@ import {
   asGroup,
   asRichlink,
   groupSchema
-} from "./chunk-TOJQ6DPE.js";
+} from "./chunk-JBMQ5GEW.js";
 import {
   asPoll,
   asPollOption
@@ -16,7 +16,7 @@ import {
   asContact,
   fromVCard,
   toVCard
-} from "./chunk-YZ226L5Y.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   asAttachment,
@@ -29,11 +29,12 @@ import {
   reactionSchema,
   text,
   textSchema
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/imessage/index.ts
 import { createClient as createClient2, MessageEffect as MessageEffect2 } from "@photon-ai/advanced-imessage";
 import { IMessageSDK as IMessageSDK2 } from "@photon-ai/imessage-kit";
+import { withSpan } from "@photon-ai/otel";
 
 // src/providers/imessage/content/background.ts
 import z from "zod";
@@ -322,6 +323,7 @@ var readLocalAttachment = async (att) => {
 var toAttachmentContent = (att) => {
   const { localPath } = att;
   return asAttachment({
+    id: att.id,
     name: att.fileName ?? DEFAULT_ATTACHMENT_NAME,
     mimeType: att.mimeType,
     size: att.sizeBytes,
@@ -546,7 +548,7 @@ var setBackground = async (remote, spaceId, content) => {
 
 // src/providers/imessage/remote/inbound.ts
 import {
-  NotFoundError
+  NotFoundError as NotFoundError2
 } from "@photon-ai/advanced-imessage";
 
 // src/providers/imessage/cache.ts
@@ -620,45 +622,10 @@ var getPollCache = (owner) => {
   return cache;
 };
 
-// src/providers/imessage/remote/inbound.ts
-var URL_BALLOON_BUNDLE_ID = "com.apple.messages.URLBalloonProvider";
-var getBalloonBundleId = (message) => message.content.balloonBundleId;
-var messageAttachments = (message) => message.content.attachments;
-var resolveChatGuid = (message, hint) => {
-  if (hint) {
-    return hint;
-  }
-  const first = message.chatGuids?.[0];
-  return first ?? "";
-};
-var resolveSenderId = (message) => message.sender?.address ?? "";
-var isIMessageMessage = (value) => {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  const record = value;
-  return typeof record.id === "string" && record.id.length > 0 && typeof record.content === "object" && record.content !== null && typeof record.sender === "object" && record.sender !== null && typeof record.space === "object" && record.space !== null;
-};
-var asProviderGroup = (items) => groupSchema.parse({ type: "group", items });
-var buildMessageBase = (message, chatGuidHint, timestamp, phone) => {
-  const chat = resolveChatGuid(message, chatGuidHint);
-  return {
-    sender: { id: resolveSenderId(message) },
-    space: {
-      id: chat,
-      type: chat.includes(";+;") ? "group" : "dm",
-      phone
-    },
-    timestamp
-  };
-};
-var toAttachmentContent2 = (client, info) => asAttachment({
-  name: info.fileName,
-  mimeType: info.mimeType,
-  size: info.totalBytes,
-  read: async () => await downloadPrimaryAttachment(client, info.guid),
-  stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
-});
+// src/providers/imessage/remote/attachments.ts
+import {
+  NotFoundError
+} from "@photon-ai/advanced-imessage";
 var downloadPrimaryAttachmentStream = (client, attachmentGuid) => {
   const frames = client.attachments.downloadStream(attachmentGuid);
   const iterator = frames[Symbol.asyncIterator]();
@@ -713,6 +680,66 @@ var downloadPrimaryAttachment = async (client, attachmentGuid) => {
   }
   return Buffer.concat(chunks);
 };
+var getRemoteAttachment = async (client, guid) => {
+  let info;
+  try {
+    info = await client.attachments.get(guid);
+  } catch (err) {
+    if (err instanceof NotFoundError) {
+      return;
+    }
+    throw err;
+  }
+  return asAttachment({
+    id: info.guid,
+    name: info.fileName,
+    mimeType: info.mimeType,
+    size: info.totalBytes,
+    read: () => downloadPrimaryAttachment(client, info.guid),
+    stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
+  });
+};
+
+// src/providers/imessage/remote/inbound.ts
+var URL_BALLOON_BUNDLE_ID = "com.apple.messages.URLBalloonProvider";
+var getBalloonBundleId = (message) => message.content.balloonBundleId;
+var messageAttachments = (message) => message.content.attachments;
+var resolveChatGuid = (message, hint) => {
+  if (hint) {
+    return hint;
+  }
+  const first = message.chatGuids?.[0];
+  return first ?? "";
+};
+var resolveSenderId = (message) => message.sender?.address ?? "";
+var isIMessageMessage = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value;
+  return typeof record.id === "string" && record.id.length > 0 && typeof record.content === "object" && record.content !== null && typeof record.sender === "object" && record.sender !== null && typeof record.space === "object" && record.space !== null;
+};
+var asProviderGroup = (items) => groupSchema.parse({ type: "group", items });
+var buildMessageBase = (message, chatGuidHint, timestamp, phone) => {
+  const chat = resolveChatGuid(message, chatGuidHint);
+  return {
+    sender: { id: resolveSenderId(message) },
+    space: {
+      id: chat,
+      type: chat.includes(";+;") ? "group" : "dm",
+      phone
+    },
+    timestamp
+  };
+};
+var toAttachmentContent2 = (client, info) => asAttachment({
+  id: info.guid,
+  name: info.fileName,
+  mimeType: info.mimeType,
+  size: info.totalBytes,
+  read: async () => await downloadPrimaryAttachment(client, info.guid),
+  stream: async () => downloadPrimaryAttachmentStream(client, info.guid)
+});
 var toVCardContent2 = async (client, info) => {
   try {
     const buf = await downloadPrimaryAttachment(client, info.guid);
@@ -896,7 +923,7 @@ var getMessage3 = async (remote, spaceId, msgId, phone) => {
       const item = parent.content.items[childRef.partIndex];
       return isIMessageMessage(item) ? item : void 0;
     } catch (err) {
-      if (err instanceof NotFoundError) {
+      if (err instanceof NotFoundError2) {
         return;
       }
       throw err;
@@ -916,7 +943,7 @@ var getMessage3 = async (remote, spaceId, msgId, phone) => {
     cacheMessage(cache, rebuilt);
     return rebuilt;
   } catch (err) {
-    if (err instanceof NotFoundError) {
+    if (err instanceof NotFoundError2) {
       return;
     }
     throw err;
@@ -1375,7 +1402,7 @@ var editMessage = async (remote, spaceId, msgId, content) => {
 import {
   AuthenticationError,
   IMessageError,
-  NotFoundError as NotFoundError2,
+  NotFoundError as NotFoundError3,
   ValidationError
 } from "@photon-ai/advanced-imessage";
 
@@ -1751,7 +1778,7 @@ var toPollDeltaMessages = async (client, pollCache, event, phone) => {
 
 // src/providers/imessage/remote/stream.ts
 var isRetryableIMessageStreamError = (error) => {
-  if (error instanceof AuthenticationError || error instanceof NotFoundError2 || error instanceof ValidationError) {
+  if (error instanceof AuthenticationError || error instanceof NotFoundError3 || error instanceof ValidationError) {
     return false;
   }
   if (error instanceof IMessageError) {
@@ -2202,12 +2229,53 @@ var imessage = definePlatform("iMessage", {
     return await send4(remote, space.id, content);
   },
   actions: {
-    getMessage: async ({ space, messageId, client }) => {
+    getMessage: async ({ client }, space, messageId) => {
       if (isLocal(client)) {
         return getMessage2(client, messageId);
       }
       const remote = clientForPhone(client, space.phone);
       return getMessage4(remote, space.id, messageId, space.phone);
+    },
+    // Fetch an attachment by GUID. Returns a spectrum `Attachment` whose
+    // `.read()` / `.stream()` lazily download the bytes — calling both
+    // issues two independent gRPC downloads, so cache `.read()` if you
+    // need the bytes more than once. Returns `undefined` for unknown
+    // GUIDs. Local-mode iMessage is not supported.
+    getAttachment: async ({ client }, guid, phone) => {
+      if (isLocal(client)) {
+        throw UnsupportedError.action(
+          "getAttachment",
+          "iMessage (local mode)",
+          "fetching attachments by GUID requires remote iMessage"
+        );
+      }
+      if (client.length === 0) {
+        throw new Error("No iMessage clients configured");
+      }
+      const routedPhone = (() => {
+        if (isSharedMode(client)) {
+          return SHARED_PHONE;
+        }
+        if (phone) {
+          return phone;
+        }
+        if (client.length === 1) {
+          return client[0].phone;
+        }
+        throw new Error(
+          `imessage.getAttachment requires a phone in multi-phone mode. Available: ${availablePhones(client).join(", ")}`
+        );
+      })();
+      const remote = clientForPhone(client, routedPhone);
+      return withSpan(
+        "spectrum.imessage.getAttachment",
+        {
+          "spectrum.provider": "iMessage",
+          "spectrum.imessage.attachment.guid": guid,
+          "spectrum.imessage.phone": routedPhone
+        },
+        () => getRemoteAttachment(remote, guid)
+      );
     }
   }
 });

package/dist/{chunk-YZ226L5Y.js → chunk-J2ANGYYW.js}

@@ -1,6 +1,6 @@
 import {
   readSchema
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/utils/vcard.ts
 import vCard from "vcf";

package/dist/{chunk-TOJQ6DPE.js → chunk-JBMQ5GEW.js}

@@ -4,7 +4,7 @@ import {
   readSchema,
   resolveContents,
   streamSchema
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/content/group.ts
 import z from "zod";

package/dist/{chunk-VTQWVJZ5.js → chunk-TSJKUFNE.js}

@@ -1,18 +1,18 @@
 import {
   asVoice
-} from "./chunk-ODO6KRGX.js";
+} from "./chunk-2B76JFHX.js";
 import {
   asContact,
   fromVCard,
   toVCard
-} from "./chunk-YZ226L5Y.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   asAttachment,
   asCustom,
   definePlatform,
   reactionSchema
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/terminal/index.ts
 import { spawn } from "child_process";

package/dist/{chunk-5HNHMI6L.js → chunk-VOAKCXBF.js}

@@ -10,7 +10,7 @@ import {
   asReaction,
   asText,
   definePlatform
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/slack/index.ts
 import { createClient as createClient2, staticTokens } from "@photon-ai/slack";
@@ -169,6 +169,7 @@ var tsToDate = (ts) => {
   return new Date(seconds * 1e3);
 };
 var lazySlackFile = (client, teamId, file) => asAttachment({
+  id: file.id,
   name: file.name,
   mimeType: file.mimeType,
   size: file.size,

package/dist/{chunk-ZUQYLYGI.js → chunk-YEQPATHB.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-YKWKZ2PZ.js";
 import {
   asContact
-} from "./chunk-YZ226L5Y.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   asAttachment,
@@ -16,7 +16,7 @@ import {
   asReaction,
   asText,
   definePlatform
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/providers/whatsapp-business/index.ts
 import { createClient as createClient2 } from "@photon-ai/whatsapp-business";
@@ -508,6 +508,7 @@ var fetchMedia = async (client, mediaId) => {
   return response;
 };
 var lazyMedia = (client, media) => asAttachment({
+  id: media.id,
   name: media.filename ?? `media-${media.id}`,
   mimeType: media.mimeType,
   read: async () => Buffer.from(await (await fetchMedia(client, media.id)).arrayBuffer()),

package/dist/{chunk-JTS25BT3.js → chunk-YFCDKZ6W.js}

@@ -1,4 +1,5 @@
 // src/content/attachment.ts
+import { randomUUID } from "crypto";
 import { createReadStream } from "fs";
 import { readFile, stat } from "fs/promises";
 import { basename } from "path";
@@ -49,6 +50,7 @@ var fetchUrlBytes = async (url, options) => {
 var DEFAULT_ATTACHMENT_NAME = "attachment";
 var attachmentSchema = z2.object({
   type: z2.literal("attachment"),
+  id: z2.string().nonempty(),
   name: z2.string().nonempty(),
   mimeType: z2.string().nonempty(),
   size: z2.number().int().nonnegative().optional(),
@@ -91,6 +93,7 @@ var asAttachment = (input) => {
   const stream = input.stream ?? (async () => bufferToStream(await read()));
   return attachmentSchema.parse({
     type: "attachment",
+    id: input.id ?? randomUUID(),
     name: input.name,
     mimeType: input.mimeType,
     size: input.size,
@@ -101,10 +104,12 @@ var asAttachment = (input) => {
 function attachment(input, options) {
   return {
     build: async () => {
+      const id = options?.id;
       const name = resolveAttachmentName(input, options?.name);
       const mimeType = resolveAttachmentMimeType(name, options?.mimeType);
       if (input instanceof URL) {
         return asAttachment({
+          id,
           name,
           mimeType,
           read: async () => (await fetchUrlBytes(input)).data
@@ -113,6 +118,7 @@ function attachment(input, options) {
       if (typeof input === "string") {
         const stats = await stat(input);
         return asAttachment({
+          id,
           name,
           mimeType,
           size: stats.size,
@@ -123,6 +129,7 @@ function attachment(input, options) {
         });
       }
       return asAttachment({
+        id,
         name,
         mimeType,
         size: input.byteLength,
@@ -549,6 +556,7 @@ var RESERVED_SPACE_KEYS = /* @__PURE__ */ new Set([
   "stopTyping",
   "responding"
 ]);
+var PLATFORM_WISE_ACTION_KEYS = /* @__PURE__ */ new Set(["getMessage"]);
 var RESERVED_MESSAGE_KEYS = /* @__PURE__ */ new Set([
   "content",
   "direction",
@@ -561,8 +569,17 @@ var RESERVED_MESSAGE_KEYS = /* @__PURE__ */ new Set([
   "space",
   "timestamp"
 ]);
+var scopeLabel = (scope) => {
+  if (scope === "space") {
+    return "Space";
+  }
+  if (scope === "message") {
+    return "Message";
+  }
+  return "PlatformInstance";
+};
 var warnReservedAction = (scope, name, platform) => {
-  const body = `[spectrum-ts] ${platform} declared ${scope} action "${name}" which collides with a reserved ${scope === "space" ? "Space" : "Message"} key; skipping.`;
+  const body = `[spectrum-ts] ${platform} declared ${scope} action "${name}" which collides with a reserved ${scopeLabel(scope)} key; skipping.`;
   console.warn(
     supportsAnsiColor() ? `${ANSI_YELLOW}${body}${ANSI_RESET}` : body
   );
@@ -765,11 +782,7 @@ function buildSpace(params) {
   async function getMessageImpl(id) {
     const getMessage = definition.actions?.getMessage;
     if (!getMessage) {
-      warnUnsupported(
-        UnsupportedError.action("getMessage", definition.name),
-        definition.name
-      );
-      return;
+      throw UnsupportedError.action("getMessage", definition.name);
     }
     return withSpan(
       "spectrum.message.get",
@@ -779,22 +792,11 @@ function buildSpace(params) {
         "spectrum.message.id": id
       },
       async () => {
-        let raw;
-        try {
-          raw = await getMessage({
-            space: spaceRef,
-            messageId: id,
-            client,
-            config,
-            store
-          });
-        } catch (err) {
-          if (err instanceof UnsupportedError) {
-            warnUnsupported(err, definition.name);
-            return;
-          }
-          throw err;
-        }
+        const raw = await getMessage(
+          { client, config, store },
+          spaceRef,
+          id
+        );
         if (!raw) {
           return;
         }
@@ -952,6 +954,36 @@ function classifySpaceIdentifier(args) {
   }
   return { kind, identifier };
 }
+function buildInstanceActions(platformName, declared, reservedKeys, buildCtx) {
+  const out = {};
+  for (const key of PLATFORM_WISE_ACTION_KEYS) {
+    const override = declared?.[key];
+    if (override && typeof override === "function") {
+      out[key] = (...args) => override(buildCtx(), ...args);
+    } else {
+      out[key] = () => {
+        throw UnsupportedError.action(key, platformName);
+      };
+    }
+  }
+  if (!declared) {
+    return out;
+  }
+  for (const [name, factory] of Object.entries(declared)) {
+    if (PLATFORM_WISE_ACTION_KEYS.has(name)) {
+      continue;
+    }
+    if (reservedKeys.has(name)) {
+      warnReservedAction("instance", name, platformName);
+      continue;
+    }
+    if (typeof factory !== "function") {
+      continue;
+    }
+    out[name] = (...args) => factory(buildCtx(), ...args);
+  }
+  return out;
+}
 function createPlatformInstance(def, runtime) {
   const isPlatformUser = (value) => typeof value === "object" && value !== null && "__platform" in value && value.__platform === def.name;
   const resolveUserID = async (userID) => {
@@ -1087,7 +1119,26 @@ function createPlatformInstance(def, runtime) {
       return messagesIterable;
     }
   });
-  return Object.assign(base, eventProperties);
+  const instanceActions = buildInstanceActions(
+    def.name,
+    def.actions,
+    /* @__PURE__ */ new Set([
+      "user",
+      "space",
+      "messages",
+      ...Object.keys(customEvents)
+    ]),
+    () => ({
+      client: runtime.client,
+      config: runtime.config,
+      store: runtime.store
+    })
+  );
+  return Object.assign(
+    base,
+    instanceActions,
+    eventProperties
+  );
 }
 function definePlatform(name, def) {
   const fullDef = { name, ...def };

package/dist/index.d.ts

@@ -1,16 +1,11 @@
-import { C as ContentBuilder, U as User, M as Message, b as Space, c as ContentInput, d as Content, e as ProviderMessage, E as EventProducer, f as SpaceActionFn, g as MessageActionFn, h as CreateClientContext, i as Store, a as PlatformDef, P as Platform, j as PlatformProviderConfig, k as SpectrumLike, l as CustomEventStreams, A as AgentSender } from './types-CtsphK2p.js';
-export { m as AnyPlatformDef, B as Broadcaster, n as ManagedStream, o as PlatformInstance, p as PlatformMessage, q as PlatformRuntime, r as PlatformSpace, s as PlatformUser, S as SchemaMessage, t as broadcast, u as mergeStreams, v as stream } from './types-CtsphK2p.js';
+import { P as PhotoInput } from './photo-content-Deq7T2tO.js';
+export { A as Attachment, a as AttachmentInput, b as attachment } from './photo-content-Deq7T2tO.js';
 import z__default from 'zod';
-import { P as PhotoInput } from './photo-content-BJKnqgN-.js';
+import { C as ContentBuilder, U as User, M as Message, b as Space, c as ContentInput, e as Content, f as ProviderMessage, E as EventProducer, g as SpaceActionFn, h as MessageActionFn, I as InstanceActionFn, i as CreateClientContext, d as Store, a as PlatformDef, P as Platform, j as PlatformProviderConfig, k as SpectrumLike, l as CustomEventStreams, A as AgentSender } from './types-kk0L8kFG.js';
+export { m as AnyPlatformDef, B as Broadcaster, n as ManagedStream, o as PlatformInstance, p as PlatformMessage, q as PlatformRuntime, r as PlatformSpace, s as PlatformUser, S as SchemaMessage, t as broadcast, u as mergeStreams, v as stream } from './types-kk0L8kFG.js';
 import vCard from 'vcf';
 import 'hotscript';
 
-type AttachmentInput = string | Buffer | URL;
-declare function attachment(input: AttachmentInput, options?: {
-    mimeType?: string;
-    name?: string;
-}): ContentBuilder;
-
 /**
  * Set or clear the chat avatar (group icon). Universal content — providers
  * dispatch by `content.type === "avatar"` in their `send` action and decide
@@ -198,6 +193,7 @@ declare const editSchema: z__default.ZodObject<{
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -301,6 +297,7 @@ declare const editSchema: z__default.ZodObject<{
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -328,6 +325,7 @@ declare const editSchema: z__default.ZodObject<{
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -431,6 +429,7 @@ declare const editSchema: z__default.ZodObject<{
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -572,6 +571,7 @@ declare const replySchema: z__default.ZodObject<{
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -675,6 +675,7 @@ declare const replySchema: z__default.ZodObject<{
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -702,6 +703,7 @@ declare const replySchema: z__default.ZodObject<{
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -805,6 +807,7 @@ declare const replySchema: z__default.ZodObject<{
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -2817,7 +2820,7 @@ declare function definePlatform<_Name extends string, _ConfigSchema extends z__d
     id: string;
 }, _MessageSchema extends z__default.ZodType<object> | undefined = undefined, _MessageType extends ProviderMessage<_ResolvedUser, _ResolvedSpace, _MessageSchema extends z__default.ZodType<object> ? z__default.infer<_MessageSchema> : Record<never, never>> = ProviderMessage<_ResolvedUser, _ResolvedSpace, _MessageSchema extends z__default.ZodType<object> ? z__default.infer<_MessageSchema> : Record<never, never>>, _Events extends (Record<string, EventProducer<unknown, _Client, z__default.infer<_ConfigSchema>>> & {
     messages?: never;
-}) | undefined = undefined, _Static extends Record<string, unknown> = Record<never, never>, _SpaceActions extends Record<string, SpaceActionFn> = Record<never, never>, _MessageActions extends Record<string, MessageActionFn> = Record<never, never>>(name: _Name, def: {
+}) | undefined = undefined, _Static extends Record<string, unknown> = Record<never, never>, _SpaceActions extends Record<string, SpaceActionFn> = Record<never, never>, _MessageActions extends Record<string, MessageActionFn> = Record<never, never>, _Actions extends Record<string, InstanceActionFn> = Record<never, never>>(name: _Name, def: {
     lifecycle: {
         createClient: (ctx: CreateClientContext<_ConfigSchema>) => Promise<_Client>;
         destroyClient?: (ctx: {
@@ -2825,9 +2828,9 @@ declare function definePlatform<_Name extends string, _ConfigSchema extends z__d
             store: Store;
         }) => Promise<void>;
     };
-} & Omit<PlatformDef<_Name, _ConfigSchema, _UserSchema, _SpaceSchema, _SpaceParamsSchema, _Client, _ResolvedUser, _ResolvedSpace, _MessageSchema, _MessageType, _Events, _SpaceActions, _MessageActions>, "lifecycle" | "name"> & {
+} & Omit<PlatformDef<_Name, _ConfigSchema, _UserSchema, _SpaceSchema, _SpaceParamsSchema, _Client, _ResolvedUser, _ResolvedSpace, _MessageSchema, _MessageType, _Events, _SpaceActions, _MessageActions, _Actions>, "lifecycle" | "name"> & {
     static?: _Static;
-}): Platform<PlatformDef<_Name, _ConfigSchema, _UserSchema, _SpaceSchema, _SpaceParamsSchema, _Client, _ResolvedUser, _ResolvedSpace, _MessageSchema, _MessageType, _Events, _SpaceActions, _MessageActions>> & Readonly<_Static>;
+}): Platform<PlatformDef<_Name, _ConfigSchema, _UserSchema, _SpaceSchema, _SpaceParamsSchema, _Client, _ResolvedUser, _ResolvedSpace, _MessageSchema, _MessageType, _Events, _SpaceActions, _MessageActions, _Actions>> & Readonly<_Static>;
 
 type SpectrumInstance<Providers extends PlatformProviderConfig[] = PlatformProviderConfig[]> = SpectrumLike<Providers> & CustomEventStreams<Providers> & {
     readonly messages: AsyncIterable<[Space, Message]>;
@@ -2946,4 +2949,4 @@ declare class UnsupportedError extends Error {
 declare const fromVCard: (vcf: string) => ContactInput;
 declare const toVCard: (contact: Contact) => Promise<string>;
 
-export { AgentSender, type Avatar, type AvatarInput, type CloudPlatform, type Contact, type ContactAddress, type ContactDetails, type ContactEmail, type ContactInput, type ContactName, type ContactOrg, type ContactPhone, Content, ContentBuilder, ContentInput, type DedicatedTokenData, type Edit, Emoji, type EmojiKey, EventProducer, type Group, type ImessageInfoData, Message, Platform, PlatformDef, PlatformProviderConfig, type PlatformStatus, type PlatformsData, type Poll, type PollChoice, type PollChoiceInput, type PollOption, type Reaction, type Rename, type Reply, type Richlink, type SharedTokenData, type SlackTeamMeta, type SlackTokenData, Space, Spectrum, SpectrumCloudError, type SpectrumInstance, type SubscriptionData, type SubscriptionStatus, type TokenData, type Typing, UnsupportedError, type UnsupportedKind, User, type Voice, attachment, avatar, cloud, contact, custom, definePlatform, edit, fromVCard, group, option, poll, reaction, rename, reply, resolveContents, richlink, text, toVCard, typing, voice };
+export { AgentSender, type Avatar, type AvatarInput, type CloudPlatform, type Contact, type ContactAddress, type ContactDetails, type ContactEmail, type ContactInput, type ContactName, type ContactOrg, type ContactPhone, Content, ContentBuilder, ContentInput, type DedicatedTokenData, type Edit, Emoji, type EmojiKey, EventProducer, type Group, type ImessageInfoData, Message, Platform, PlatformDef, PlatformProviderConfig, type PlatformStatus, type PlatformsData, type Poll, type PollChoice, type PollChoiceInput, type PollOption, type Reaction, type Rename, type Reply, type Richlink, type SharedTokenData, type SlackTeamMeta, type SlackTokenData, Space, Spectrum, SpectrumCloudError, type SpectrumInstance, type SubscriptionData, type SubscriptionStatus, type TokenData, type Typing, UnsupportedError, type UnsupportedKind, User, type Voice, avatar, cloud, contact, custom, definePlatform, edit, fromVCard, group, option, poll, reaction, rename, reply, resolveContents, richlink, text, toVCard, typing, voice };

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   group,
   richlink
-} from "./chunk-TOJQ6DPE.js";
+} from "./chunk-JBMQ5GEW.js";
 import {
   voice
-} from "./chunk-ODO6KRGX.js";
+} from "./chunk-2B76JFHX.js";
 import {
   option,
   poll
@@ -20,7 +20,7 @@ import {
   contact,
   fromVCard,
   toVCard
-} from "./chunk-YZ226L5Y.js";
+} from "./chunk-J2ANGYYW.js";
 import {
   UnsupportedError,
   attachment,
@@ -38,7 +38,7 @@ import {
   text,
   typing,
   wrapProviderMessage
-} from "./chunk-JTS25BT3.js";
+} from "./chunk-YFCDKZ6W.js";
 
 // src/emoji/generated.ts
 var GeneratedEmoji = {

package/dist/photo-content-Deq7T2tO.d.ts

@@ -0,0 +1,33 @@
+import z__default from 'zod';
+import { C as ContentBuilder } from './types-kk0L8kFG.js';
+
+declare const attachmentSchema: z__default.ZodObject<{
+    type: z__default.ZodLiteral<"attachment">;
+    id: z__default.ZodString;
+    name: z__default.ZodString;
+    mimeType: z__default.ZodString;
+    size: z__default.ZodOptional<z__default.ZodNumber>;
+    read: z__default.ZodFunction<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
+    stream: z__default.ZodFunction<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
+}, z__default.core.$strip>;
+type Attachment = z__default.infer<typeof attachmentSchema>;
+type AttachmentInput = string | Buffer | URL;
+declare function attachment(input: AttachmentInput, options?: {
+    id?: string;
+    mimeType?: string;
+    name?: string;
+}): ContentBuilder;
+
+/**
+ * Shared building blocks for photo-style content (chat background, group
+ * avatar/icon, …) whose builders all share the same `set | clear` shape and
+ * the same `"clear"` reserved-string sentinel.
+ *
+ * Keeping the action schema and `buildPhotoAction` factory here means both
+ * `background()` and `avatar()` parse against the same structural definition
+ * and any DX fix (mime inference, read caching, sentinel docs) lands once.
+ */
+declare const CLEAR_SENTINEL: "clear";
+type PhotoInput = typeof CLEAR_SENTINEL | string | Buffer | URL;
+
+export { type Attachment as A, type PhotoInput as P, type AttachmentInput as a, attachment as b };

package/dist/providers/imessage/index.d.ts

@@ -1,8 +1,8 @@
-import { C as ContentBuilder, c as ContentInput, M as Message, S as SchemaMessage, P as Platform, a as PlatformDef, b as Space } from '../../types-CtsphK2p.js';
+import { C as ContentBuilder, c as ContentInput, M as Message, S as SchemaMessage, P as Platform, a as PlatformDef, b as Space, d as Store } from '../../types-kk0L8kFG.js';
 import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod';
 import z__default from 'zod';
-import { P as PhotoInput } from '../../photo-content-BJKnqgN-.js';
+import { P as PhotoInput, A as Attachment } from '../../photo-content-Deq7T2tO.js';
 import { MessageEffect, AdvancedIMessage } from '@photon-ai/advanced-imessage';
 import { IMessageSDK } from '@photon-ai/imessage-kit';
 import 'hotscript';
@@ -122,6 +122,39 @@ declare const imessage: Platform<PlatformDef<"iMessage", z.ZodUnion<readonly [z.
     read: (space: Space, message: Message) => Promise<void>;
 }, {
     read: (message: Message) => Promise<void>;
+}, {
+    getMessage: ({ client }: {
+        client: IMessageClient;
+        config: {
+            local: true;
+        } | {
+            local: false;
+            clients?: {
+                address: string;
+                token: string;
+                phone: string;
+            } | {
+                address: string;
+                token: string;
+                phone: string;
+            }[] | undefined;
+        };
+        store: Store;
+    }, space: ({
+        id: string;
+        type: "dm";
+        phone: string;
+    } | {
+        id: string;
+        type: "group";
+        phone: string;
+    }) & {
+        id: string;
+        __platform: string;
+    }, messageId: string) => Promise<IMessageMessage | undefined>;
+    getAttachment: ({ client }: {
+        client: IMessageClient;
+    }, guid: string, phone?: string) => Promise<Attachment | undefined>;
 }>> & Readonly<{
     effect: {
         message: {

package/dist/providers/imessage/index.js

@@ -3,12 +3,12 @@ import {
   effect,
   imessage,
   read
-} from "../../chunk-UGBHJEX2.js";
-import "../../chunk-TOJQ6DPE.js";
+} from "../../chunk-BGV4SFVJ.js";
+import "../../chunk-JBMQ5GEW.js";
 import "../../chunk-KO67KDBD.js";
 import "../../chunk-YKWKZ2PZ.js";
-import "../../chunk-YZ226L5Y.js";
-import "../../chunk-JTS25BT3.js";
+import "../../chunk-J2ANGYYW.js";
+import "../../chunk-YFCDKZ6W.js";
 export {
   background,
   effect,

package/dist/providers/index.d.ts

@@ -2,11 +2,11 @@ export { imessage } from './imessage/index.js';
 export { slack } from './slack/index.js';
 export { terminal } from './terminal/index.js';
 export { whatsappBusiness } from './whatsapp-business/index.js';
-import '../types-CtsphK2p.js';
+import '../types-kk0L8kFG.js';
 import 'hotscript';
 import 'zod';
 import 'zod/v4/core';
-import '../photo-content-BJKnqgN-.js';
+import '../photo-content-Deq7T2tO.js';
 import '@photon-ai/advanced-imessage';
 import '@photon-ai/imessage-kit';
 import '@photon-ai/slack';

package/dist/providers/index.js

@@ -1,21 +1,21 @@
 import {
   imessage
-} from "../chunk-UGBHJEX2.js";
-import "../chunk-TOJQ6DPE.js";
+} from "../chunk-BGV4SFVJ.js";
+import "../chunk-JBMQ5GEW.js";
 import {
   slack
-} from "../chunk-5HNHMI6L.js";
+} from "../chunk-VOAKCXBF.js";
 import {
   terminal
-} from "../chunk-VTQWVJZ5.js";
-import "../chunk-ODO6KRGX.js";
+} from "../chunk-TSJKUFNE.js";
+import "../chunk-2B76JFHX.js";
 import {
   whatsappBusiness
-} from "../chunk-ZUQYLYGI.js";
+} from "../chunk-YEQPATHB.js";
 import "../chunk-KO67KDBD.js";
 import "../chunk-YKWKZ2PZ.js";
-import "../chunk-YZ226L5Y.js";
-import "../chunk-JTS25BT3.js";
+import "../chunk-J2ANGYYW.js";
+import "../chunk-YFCDKZ6W.js";
 export {
   imessage,
   slack,

package/dist/providers/slack/index.d.ts

@@ -1,4 +1,4 @@
-import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-CtsphK2p.js';
+import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-kk0L8kFG.js';
 import * as z from 'zod';
 import z__default from 'zod';
 import * as _photon_ai_slack from '@photon-ai/slack';
@@ -42,6 +42,6 @@ declare const slack: Platform<PlatformDef<"Slack", z.ZodUnion<readonly [z.ZodObj
     subtype: z.ZodOptional<z.ZodString>;
     threadTs: z.ZodOptional<z.ZodString>;
     ts: z.ZodOptional<z.ZodString>;
-}, zod_v4_core.$strip>, SlackMessage, undefined, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+}, zod_v4_core.$strip>, SlackMessage, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
 
 export { slack };

package/dist/providers/slack/index.js

@@ -1,8 +1,8 @@
 import {
   slack
-} from "../../chunk-5HNHMI6L.js";
+} from "../../chunk-VOAKCXBF.js";
 import "../../chunk-YKWKZ2PZ.js";
-import "../../chunk-JTS25BT3.js";
+import "../../chunk-YFCDKZ6W.js";
 export {
   slack
 };

package/dist/providers/terminal/index.d.ts

@@ -1,4 +1,4 @@
-import { P as Platform, a as PlatformDef, M as Message, U as User, b as Space } from '../../types-CtsphK2p.js';
+import { P as Platform, a as PlatformDef, M as Message, U as User, b as Space } from '../../types-kk0L8kFG.js';
 import { ChildProcess } from 'node:child_process';
 import z__default from 'zod';
 import { Socket } from 'node:net';
@@ -107,15 +107,16 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
     } | undefined;
     id: string;
     content: {
+        type: "text";
+        text: string;
+    } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
         stream: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
         size?: number | undefined;
-    } | {
-        type: "text";
-        text: string;
     } | {
         type: "custom";
         raw: unknown;
@@ -210,15 +211,16 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
     } | {
         type: "effect";
         content: {
+            type: "text";
+            text: string;
+        } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
             stream: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
             size?: number | undefined;
-        } | {
-            type: "text";
-            text: string;
         };
         effect: string;
     } | {
@@ -237,17 +239,18 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
             kind: "clear";
         };
     } | {
-        type: "reply";
+        type: "edit";
         content: {
+            type: "text";
+            text: string;
+        } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
             stream: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
             size?: number | undefined;
-        } | {
-            type: "text";
-            text: string;
         } | {
             type: "custom";
             raw: unknown;
@@ -342,15 +345,16 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
         } | {
             type: "effect";
             content: {
+                type: "text";
+                text: string;
+            } | {
                 type: "attachment";
+                id: string;
                 name: string;
                 mimeType: string;
                 read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
                 stream: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
                 size?: number | undefined;
-            } | {
-                type: "text";
-                text: string;
             };
             effect: string;
         } | {
@@ -371,17 +375,18 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
         };
         target: Message<string, User, Space<unknown>>;
     } | {
-        type: "edit";
+        type: "reply";
         content: {
+            type: "text";
+            text: string;
+        } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
             stream: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
             size?: number | undefined;
-        } | {
-            type: "text";
-            text: string;
         } | {
             type: "custom";
             raw: unknown;
@@ -476,15 +481,16 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
         } | {
             type: "effect";
             content: {
+                type: "text";
+                text: string;
+            } | {
                 type: "attachment";
+                id: string;
                 name: string;
                 mimeType: string;
                 read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
                 stream: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
                 size?: number | undefined;
-            } | {
-                type: "text";
-                text: string;
             };
             effect: string;
         } | {
@@ -512,6 +518,6 @@ declare const terminal: Platform<PlatformDef<"Terminal", z__default.ZodObject<{
         id: string;
     };
     timestamp: Date;
-}, undefined, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+}, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
 
 export { terminal };

package/dist/providers/terminal/index.js

@@ -1,9 +1,9 @@
 import {
   terminal
-} from "../../chunk-VTQWVJZ5.js";
-import "../../chunk-ODO6KRGX.js";
-import "../../chunk-YZ226L5Y.js";
-import "../../chunk-JTS25BT3.js";
+} from "../../chunk-TSJKUFNE.js";
+import "../../chunk-2B76JFHX.js";
+import "../../chunk-J2ANGYYW.js";
+import "../../chunk-YFCDKZ6W.js";
 export {
   terminal
 };

package/dist/providers/whatsapp-business/index.d.ts

@@ -1,4 +1,4 @@
-import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-CtsphK2p.js';
+import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-kk0L8kFG.js';
 import { WhatsAppClient } from '@photon-ai/whatsapp-business';
 import * as z from 'zod';
 import z__default from 'zod';
@@ -22,6 +22,6 @@ declare const whatsappBusiness: Platform<PlatformDef<"WhatsApp Business", z.ZodU
     id: string;
 }, {
     id: string;
-}, undefined, WhatsAppMessage, undefined, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+}, undefined, WhatsAppMessage, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
 
 export { whatsappBusiness };

package/dist/providers/whatsapp-business/index.js

@@ -1,10 +1,10 @@
 import {
   whatsappBusiness
-} from "../../chunk-ZUQYLYGI.js";
+} from "../../chunk-YEQPATHB.js";
 import "../../chunk-KO67KDBD.js";
 import "../../chunk-YKWKZ2PZ.js";
-import "../../chunk-YZ226L5Y.js";
-import "../../chunk-JTS25BT3.js";
+import "../../chunk-J2ANGYYW.js";
+import "../../chunk-YFCDKZ6W.js";
 export {
   whatsappBusiness
 };

package/dist/{types-CtsphK2p.d.ts → types-kk0L8kFG.d.ts}

@@ -9,6 +9,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
     raw: z__default.ZodUnknown;
 }, z__default.core.$strip>, z__default.ZodObject<{
     type: z__default.ZodLiteral<"attachment">;
+    id: z__default.ZodString;
     name: z__default.ZodString;
     mimeType: z__default.ZodString;
     size: z__default.ZodOptional<z__default.ZodNumber>;
@@ -122,6 +123,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
         text: z__default.ZodString;
     }, z__default.core.$strip>, z__default.ZodObject<{
         type: z__default.ZodLiteral<"attachment">;
+        id: z__default.ZodString;
         name: z__default.ZodString;
         mimeType: z__default.ZodString;
         size: z__default.ZodOptional<z__default.ZodNumber>;
@@ -163,6 +165,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -266,6 +269,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -293,6 +297,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -396,6 +401,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -427,6 +433,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -530,6 +537,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -557,6 +565,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
         text: string;
     } | {
         type: "attachment";
+        id: string;
         name: string;
         mimeType: string;
         read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -660,6 +669,7 @@ declare const contentSchema: z__default.ZodDiscriminatedUnion<[z__default.ZodObj
             text: string;
         } | {
             type: "attachment";
+            id: string;
             name: string;
             mimeType: string;
             read: z__default.core.$InferOuterFunctionType<z__default.ZodTuple<readonly [], null>, z__default.ZodPromise<z__default.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
@@ -813,6 +823,60 @@ type SpaceActionFn = (space: Space, ...args: never[]) => Promise<void>;
  * `Exclude<…, keyof Message>`.
  */
 type MessageActionFn = (message: Message, ...args: never[]) => Promise<void>;
+/**
+ * A platform-defined method projected onto the value returned by
+ * `provider(spectrum)` (e.g. `imessage(spectrum).getAttachment(guid)`). The
+ * first parameter is an injected runtime context (`{ client, config, store }`);
+ * `createPlatformInstance` supplies it so callers only pass the trailing args.
+ *
+ * Unlike `SpaceActionFn` / `MessageActionFn` (which always return
+ * `Promise<void>` because they dispatch through `send`), instance actions
+ * return arbitrary data — the public signature preserves the declared return
+ * type via `InstanceActionMethods<Def>`.
+ *
+ * Two tiers live in the same `actions?` slot:
+ *
+ * - **Platform-wise actions** — fixed framework-known names (currently just
+ *   `getMessage`) whose signatures are defined by `PlatformWiseActions`. They
+ *   power universal sugar (`space.getMessage(id)`) AND surface on the
+ *   platform instance. If a provider omits one, the framework wires a
+ *   default that throws `UnsupportedError`.
+ * - **Platform-specific actions** — free-form keys each platform declares
+ *   for its own ergonomics (e.g. iMessage's `getAttachment`). Surface on
+ *   the platform instance only.
+ *
+ * Names that collide with reserved instance keys (`user`, `space`, `messages`,
+ * plus any declared `events` key) are skipped at runtime with a warning and
+ * excluded at the type level.
+ */
+type InstanceActionFn = (ctx: any, ...args: any[]) => Promise<unknown>;
+/**
+ * Framework-known action names that every platform implicitly has.
+ *
+ * Each entry's signature lives here; the framework wires the corresponding
+ * method onto the `PlatformInstance` for every platform — providers override
+ * by declaring the key inside their `actions` slot, and platforms that omit
+ * the key get a default that throws `UnsupportedError`.
+ *
+ * Add a new platform-wise capability by extending this record (and the
+ * runtime list in `define.ts`); the corresponding instance method will be
+ * surfaced on every `PlatformInstance` automatically.
+ */
+interface PlatformWiseActions<_ResolvedSpace extends {
+    id: string;
+}, _MessageType, _Client, _Config> {
+    getMessage: (ctx: {
+        client: _Client;
+        config: _Config;
+        store: Store;
+    }, space: _ResolvedSpace & {
+        id: string;
+        __platform: string;
+    }, messageId: string) => Promise<_MessageType | undefined>;
+}
+type PlatformWiseActionKey = keyof PlatformWiseActions<{
+    id: string;
+}, unknown, unknown, unknown>;
 type ResolvedSpace = Pick<Space, "id">;
 type SpaceRef = Pick<Space, "id" | "__platform">;
 type ResolvedUser = Pick<User, "id">;
@@ -886,27 +950,30 @@ interface CreateClientContext<_ConfigSchema extends z__default.ZodType<object>>
  */
 interface PlatformDef<_Name extends string = string, _ConfigSchema extends z__default.ZodType<object> = z__default.ZodType<object>, _UserSchema extends z__default.ZodType<object> | undefined = undefined, _SpaceSchema extends z__default.ZodType<object> | undefined = undefined, _SpaceParamsSchema extends z__default.ZodType<object> | undefined = undefined, _Client = unknown, _ResolvedUser extends ResolvedUser = ResolvedUser, _ResolvedSpace extends ResolvedSpace = ResolvedSpace, _MessageSchema extends z__default.ZodType<object> | undefined = undefined, _MessageType extends ProviderMessage<_ResolvedUser, _ResolvedSpace, InferSchema<_MessageSchema>> = ProviderMessage<_ResolvedUser, _ResolvedSpace, InferSchema<_MessageSchema>>, _Events extends (Record<string, EventProducer<unknown, _Client, z__default.infer<_ConfigSchema>>> & {
     messages?: never;
-}) | undefined = undefined, _SpaceActions extends Record<string, SpaceActionFn> = Record<never, never>, _MessageActions extends Record<string, MessageActionFn> = Record<never, never>> {
+}) | undefined = undefined, _SpaceActions extends Record<string, SpaceActionFn> = Record<never, never>, _MessageActions extends Record<string, MessageActionFn> = Record<never, never>, _Actions extends Record<string, InstanceActionFn> = Record<never, never>> {
     /**
-     * Optional escape hatch: platform actions beyond `send`. Currently the
-     * framework recognizes one slot:
+     * Provider-defined methods exposed on the platform instance.
      *
-     * - **`getMessage?`** — fetch a message by id from a space. Powers
-     *   `space.getMessage(id)`. When omitted, `space.getMessage()` warns and
-     *   returns `undefined`.
+     * Two tiers share this slot:
      *
-     * 99% of integrations don't need this — `messages` + `send` is the
-     * universal contract.
+     * 1. **Platform-wise actions** (`getMessage`) — framework-recognized names
+     *    declared in `PlatformWiseActions`. Override by declaring the key here
+     *    with the matching signature. The framework injects `ctx = { client,
+     *    config, store }` as the first arg and surfaces the method on the
+     *    platform instance (`im.getMessage(space, id)`). If omitted, the
+     *    framework wires a default that throws `UnsupportedError`. Powers
+     *    universal sugar like `space.getMessage(id)`.
+     *
+     * 2. **Platform-specific actions** — free-form keys like `getAttachment`.
+     *    Each gets `ctx = { client, config, store }` as the first arg; the
+     *    public signature on `PlatformInstance<Def>` drops `ctx` and preserves
+     *    the declared return type.
+     *
+     * Names that collide with reserved instance keys (`user`, `space`,
+     * `messages`, plus any declared `events` key) are skipped at runtime with
+     * a warning and excluded at the type level.
      */
-    actions?: {
-        getMessage?: (_: {
-            space: _ResolvedSpace & SpaceRef;
-            messageId: string;
-            client: NoInferClient<_Client>;
-            config: z__default.infer<_ConfigSchema>;
-            store: Store;
-        }) => Promise<_MessageType | undefined>;
-    };
+    actions?: Partial<PlatformWiseActions<_ResolvedSpace, _MessageType, NoInferClient<_Client>, z__default.infer<_ConfigSchema>>> & _Actions;
     config: _ConfigSchema;
     /**
      * Optional escape hatch: platform-specific event streams beyond the core
@@ -1028,9 +1095,7 @@ interface PlatformDef<_Name extends string = string, _ConfigSchema extends z__de
     };
 }
 interface AnyPlatformDef {
-    actions?: {
-        getMessage?: (_: any) => Promise<any>;
-    };
+    actions?: Record<string, InstanceActionFn>;
     config: z__default.ZodType<object>;
     events?: {
         [key: string]: (ctx: any) => AsyncIterable<any>;
@@ -1122,6 +1187,15 @@ type MessageActionFns<Def extends AnyPlatformDef> = NonNullable<Def["message"]>
 type MessageActionMethods<Def extends AnyPlatformDef> = {
     [K in Exclude<keyof MessageActionFns<Def>, keyof Message>]: (...args: TailArgs<Parameters<MessageActionFns<Def>[K]>>) => Promise<void>;
 };
+type AnyInstanceActionFn = (...args: any[]) => Promise<unknown>;
+type InstanceActionFns<Def extends AnyPlatformDef> = Def["actions"] extends infer A | undefined ? A extends Record<string, AnyInstanceActionFn> ? A : Record<string, never> : Record<string, never>;
+type ReservedInstanceKeys<Def extends AnyPlatformDef> = "user" | "space" | "messages" | PlatformWiseActionKey | Extract<keyof CustomEventInstanceProperties<Def>, string>;
+type InstanceActionMethods<Def extends AnyPlatformDef> = {
+    [K in Exclude<keyof InstanceActionFns<Def>, ReservedInstanceKeys<Def> | symbol | number>]: (...args: TailArgs<Parameters<InstanceActionFns<Def>[K]>>) => ReturnType<InstanceActionFns<Def>[K]>;
+};
+interface PlatformWiseInstanceMethods<Def extends AnyPlatformDef> {
+    getMessage: (space: PlatformSpace<Def>, messageId: string) => Promise<PlatformMessage<Def> | undefined>;
+}
 type PlatformSpace<Def extends AnyPlatformDef> = Omit<SpaceShapeOf<Def>, keyof Space | keyof SpaceActionMethods<Def>> & Space & SpaceActionMethods<Def>;
 type PlatformMessage<Def extends AnyPlatformDef> = Omit<SchemaInfer<Def["message"]>, keyof Message | keyof MessageActionMethods<Def>> & Message<Def["name"], PlatformUser<Def>, PlatformSpace<Def>> & MessageActionMethods<Def>;
 type PlatformUser<Def extends AnyPlatformDef> = Omit<ResolvedUserOf<Def>, keyof User> & User;
@@ -1129,7 +1203,7 @@ type PlatformInstance<Def extends AnyPlatformDef> = {
     readonly messages: AsyncIterable<[PlatformSpace<Def>, PlatformMessage<Def>]>;
     space(...args: SpaceArgs<Def>): Promise<PlatformSpace<Def>>;
     user(userID: string): Promise<PlatformUser<Def>>;
-} & CustomEventInstanceProperties<Def>;
+} & CustomEventInstanceProperties<Def> & PlatformWiseInstanceMethods<Def> & InstanceActionMethods<Def>;
 type CustomEventInstanceProperties<Def extends AnyPlatformDef> = Def["events"] extends Record<string, unknown> ? {
     [K in Exclude<keyof Def["events"], symbol | number> as K extends ReservedNames ? never : K]: AsyncIterable<InferEventPayload<NonNullable<Def["events"]>[K]>>;
 } : Record<never, never>;
@@ -1156,4 +1230,4 @@ interface Platform<Def extends AnyPlatformDef> {
     (message: Message): PlatformMessage<Def>;
 }
 
-export { type AgentSender as A, type Broadcaster as B, type ContentBuilder as C, type EventProducer as E, type Message as M, type Platform as P, type SchemaMessage as S, type User as U, type PlatformDef as a, type Space as b, type ContentInput as c, type Content as d, type ProviderMessage as e, type SpaceActionFn as f, type MessageActionFn as g, type CreateClientContext as h, type Store as i, type PlatformProviderConfig as j, type SpectrumLike as k, type CustomEventStreams as l, type AnyPlatformDef as m, type ManagedStream as n, type PlatformInstance as o, type PlatformMessage as p, type PlatformRuntime as q, type PlatformSpace as r, type PlatformUser as s, broadcast as t, mergeStreams as u, stream as v };
+export { type AgentSender as A, type Broadcaster as B, type ContentBuilder as C, type EventProducer as E, type InstanceActionFn as I, type Message as M, type Platform as P, type SchemaMessage as S, type User as U, type PlatformDef as a, type Space as b, type ContentInput as c, type Store as d, type Content as e, type ProviderMessage as f, type SpaceActionFn as g, type MessageActionFn as h, type CreateClientContext as i, type PlatformProviderConfig as j, type SpectrumLike as k, type CustomEventStreams as l, type AnyPlatformDef as m, type ManagedStream as n, type PlatformInstance as o, type PlatformMessage as p, type PlatformRuntime as q, type PlatformSpace as r, type PlatformUser as s, broadcast as t, mergeStreams as u, stream as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Bring agents to any interface — unified messaging SDK for TypeScript.",
   "repository": {
     "type": "git",

package/dist/photo-content-BJKnqgN-.d.ts

@@ -1,13 +0,0 @@
-/**
- * Shared building blocks for photo-style content (chat background, group
- * avatar/icon, …) whose builders all share the same `set | clear` shape and
- * the same `"clear"` reserved-string sentinel.
- *
- * Keeping the action schema and `buildPhotoAction` factory here means both
- * `background()` and `avatar()` parse against the same structural definition
- * and any DX fix (mime inference, read caching, sentinel docs) lands once.
- */
-declare const CLEAR_SENTINEL: "clear";
-type PhotoInput = typeof CLEAR_SENTINEL | string | Buffer | URL;
-
-export type { PhotoInput as P };