spectrum-ts 1.17.1 → 2.0.0

package/dist/index.js

@@ -1,8 +1,17 @@
 import { createRequire as __spectrumCreateRequire } from "node:module"; const require = __spectrumCreateRequire(import.meta.url);
 import {
-  group,
   richlink
-} from "./chunk-JQN6CRSC.js";
+} from "./chunk-6BI4PFTP.js";
+import {
+  FUSOR_MESSAGES_CHANNEL,
+  fusor,
+  fusorEvent,
+  isFusorClient,
+  isFusorEvent
+} from "./chunk-34FQGGD7.js";
+import {
+  group
+} from "./chunk-3B4QH4JG.js";
 import {
   voice
 } from "./chunk-NNY6LMSC.js";
@@ -12,23 +21,26 @@ import {
 } from "./chunk-2D27WW5B.js";
 import {
   SpectrumCloudError,
+  cloud
+} from "./chunk-3GEJYGZK.js";
+import {
+  contact
+} from "./chunk-U7AWXDH6.js";
+import {
   broadcast,
-  cloud,
   createAsyncQueue,
   mergeStreams,
   stream
-} from "./chunk-MC6ZKFSG.js";
+} from "./chunk-5XEFJBN2.js";
 import {
-  contact,
   fromVCard,
   toVCard
-} from "./chunk-QGJFZMD5.js";
+} from "./chunk-6UZFVXQF.js";
 import {
   UnsupportedError,
   avatar,
   buildSpace,
   contentAttrs,
-  defineFusorPlatform,
   definePlatform,
   edit,
   rename,
@@ -36,7 +48,7 @@ import {
   senderAttrs,
   typing,
   wrapProviderMessage
-} from "./chunk-IPOFBAIM.js";
+} from "./chunk-NGC4DJIX.js";
 import {
   __commonJS,
   __esm,
@@ -6444,13 +6456,13 @@ var require_path = __commonJS({
         return /^(?:\/|\w+:)/.test(path2);
       }
     );
-    var normalize = (
+    var normalize2 = (
       /**
        * Normalizes the specified path.
        * @param {string} path Path to normalize
        * @returns {string} Normalized path
        */
-      path.normalize = function normalize2(path2) {
+      path.normalize = function normalize3(path2) {
         path2 = path2.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
         var parts = path2.split("/"), absolute = isAbsolute(path2), prefix = "";
         if (absolute)
@@ -6473,12 +6485,12 @@ var require_path = __commonJS({
     );
     path.resolve = function resolve(originPath, includePath, alreadyNormalized) {
       if (!alreadyNormalized)
-        includePath = normalize(includePath);
+        includePath = normalize2(includePath);
       if (isAbsolute(includePath))
         return includePath;
       if (!alreadyNormalized)
-        originPath = normalize(originPath);
-      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize(originPath + "/" + includePath) : includePath;
+        originPath = normalize2(originPath);
+      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize2(originPath + "/" + includePath) : includePath;
     };
   }
 });
@@ -24195,6 +24207,162 @@ var require_src3 = __commonJS({
   }
 });
 
+// src/content/stream-text.ts
+import z from "zod";
+var streamTextSchema = z.object({
+  type: z.literal("streamText"),
+  // A single-consumption producer of normalized text deltas. The builder
+  // closes over the normalized source; the platform driver calls it once.
+  // Kept opaque to Zod via `z.custom` (same approach as `attachment.read`).
+  stream: z.custom(
+    (v) => typeof v === "function",
+    {
+      message: "streamText.stream must be a function returning AsyncIterable<string>"
+    }
+  )
+});
+var asRecord = (value) => typeof value === "object" && value !== null ? value : void 0;
+var SKIP_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "message_start",
+  "message_delta",
+  "message_stop",
+  "content_block_start",
+  "content_block_stop",
+  "ping"
+]);
+var fromOpenAIResponses = (obj) => {
+  const type = obj.type;
+  if (typeof type !== "string" || !type.startsWith("response.")) {
+    return;
+  }
+  if (type === "response.output_text.delta" && typeof obj.delta === "string") {
+    return obj.delta;
+  }
+  return null;
+};
+var fromAnthropicDelta = (obj) => {
+  if (obj.type !== "content_block_delta") {
+    return;
+  }
+  const delta = asRecord(obj.delta);
+  if (delta?.type === "text_delta" && typeof delta.text === "string") {
+    return delta.text;
+  }
+  return null;
+};
+var fromAiSdkPart = (obj) => {
+  if (obj.type !== "text-delta") {
+    return;
+  }
+  if (typeof obj.textDelta === "string") {
+    return obj.textDelta;
+  }
+  return typeof obj.text === "string" ? obj.text : null;
+};
+var fromOpenAIChat = (obj) => {
+  if (!Array.isArray(obj.choices)) {
+    return;
+  }
+  const delta = asRecord(asRecord(obj.choices[0])?.delta);
+  const content = delta?.content;
+  return typeof content === "string" ? content : null;
+};
+var fromControlEvent = (obj) => typeof obj.type === "string" && SKIP_EVENT_TYPES.has(obj.type) ? null : void 0;
+var OBJECT_EXTRACTORS = [
+  fromOpenAIResponses,
+  fromAnthropicDelta,
+  fromAiSdkPart,
+  fromOpenAIChat,
+  fromControlEvent
+];
+var defaultExtract = (chunk) => {
+  if (typeof chunk === "string") {
+    return chunk;
+  }
+  const record = asRecord(chunk);
+  if (!record) {
+    throw new Error(
+      `streamText: cannot extract a text delta from a ${typeof chunk} chunk. Pass { extract } to map your stream's chunks to text.`
+    );
+  }
+  for (const extractor of OBJECT_EXTRACTORS) {
+    const result = extractor(record);
+    if (result !== void 0) {
+      return result;
+    }
+  }
+  throw new Error(
+    `streamText: unrecognized chunk shape (type=${String(record.type)}). Pass an { extract } function to map your provider's chunk to a text delta.`
+  );
+};
+var isReadableStream = (value) => typeof value?.getReader === "function";
+var isAsyncIterable = (value) => typeof value?.[Symbol.asyncIterator] === "function";
+async function* readableToAsync(source) {
+  if (isAsyncIterable(source)) {
+    yield* source;
+    return;
+  }
+  const reader = source.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        return;
+      }
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+var resolveChunkIterable = (source) => {
+  const textStream = source.textStream;
+  if (textStream != null) {
+    if (isReadableStream(textStream)) {
+      return readableToAsync(textStream);
+    }
+    if (isAsyncIterable(textStream)) {
+      return textStream;
+    }
+    throw new Error(
+      "streamText: `.textStream` must be an AsyncIterable or a ReadableStream."
+    );
+  }
+  if (isReadableStream(source)) {
+    return readableToAsync(source);
+  }
+  if (isAsyncIterable(source)) {
+    return source;
+  }
+  throw new Error(
+    "streamText: source must be an AsyncIterable, a ReadableStream, or an object with a `.textStream` (e.g. the AI SDK streamText() result)."
+  );
+};
+var normalize = (source, options) => {
+  const extract = options?.extract ? options.extract : defaultExtract;
+  let consumed = false;
+  return async function* normalized() {
+    if (consumed) {
+      throw new Error(
+        "streamText: this source has already been consumed \u2014 a stream can only be sent once."
+      );
+    }
+    consumed = true;
+    for await (const chunk of resolveChunkIterable(source)) {
+      const delta = extract(chunk);
+      if (delta) {
+        yield delta;
+      }
+    }
+  };
+};
+var asStreamText = (input) => streamTextSchema.parse({ type: "streamText", stream: input.stream });
+function streamText(source, options) {
+  return {
+    build: async () => asStreamText({ stream: normalize(source, options) })
+  };
+}
+
 // src/emoji/generated.ts
 var GeneratedEmoji = {
   _1stPlaceMedal: "\u{1F947}",
@@ -26124,21 +26292,6 @@ var aliases = {
 };
 var Emoji = { ...GeneratedEmoji, ...aliases };
 
-// src/fusor/types.ts
-var FUSOR_BRAND = /* @__PURE__ */ Symbol.for("spectrum.fusor.client");
-
-// src/fusor/index.ts
-function fusor(platform, verify) {
-  return {
-    [FUSOR_BRAND]: true,
-    platform,
-    verify
-  };
-}
-function isFusorClient(value) {
-  return typeof value === "object" && value !== null && value[FUSOR_BRAND] === true;
-}
-
 // src/spectrum.ts
 import {
   createLogger as createLogger2,
@@ -26146,7 +26299,7 @@ import {
   withSpan
 } from "@photon-ai/otel";
 import { RawInboundEvent as RawInboundEvent2 } from "@photon-ai/proto/photon/fusor/v1/inbound";
-import z from "zod";
+import z2 from "zod";
 
 // src/build-env.ts
 var SPECTRUM_SDK_VERSION = "local";
@@ -27282,6 +27435,23 @@ function combineReplies(outcomes) {
     body
   };
 }
+function routeHandlerResult(result, handler, deliver) {
+  if (result === void 0) {
+    return;
+  }
+  const items = Array.isArray(result) ? result : [result];
+  for (const item of items) {
+    if (!isFusorEvent(item)) {
+      deliver(item);
+      continue;
+    }
+    if (item.name === FUSOR_MESSAGES_CHANNEL) {
+      deliver(item.data);
+    } else {
+      handler.pushEvent(item.name, item.data);
+    }
+  }
+}
 function runHandlerOnce(handler, parsedRequest, deliver = handler.pushMessage) {
   return (async () => {
     try {
@@ -27302,12 +27472,7 @@ function runHandlerOnce(handler, parsedRequest, deliver = handler.pushMessage) {
       };
       const result = await handler.messages({ payload, respond });
       returned = true;
-      if (result !== void 0) {
-        const records = Array.isArray(result) ? result : [result];
-        for (const record of records) {
-          deliver(record);
-        }
-      }
+      routeHandlerResult(result, handler, deliver);
       return { ok: true, reply: reply2 };
     } catch (error) {
       const errorReason = error instanceof Error ? error.message : String(error);
@@ -27403,7 +27568,7 @@ var FusorCore = class {
     const { iterable: requestIterable, sink } = createRequestSink();
     this.requestSink = sink;
     sink.push({ init: { startSeq: 0 }, reply: void 0 });
-    const metadata = Metadata().set("authorization", `Bearer ${token}`);
+    const metadata = Metadata().set("access_token", token);
     const stream2 = client.subscribe(requestIterable, { metadata });
     try {
       for await (const response of stream2) {
@@ -27558,25 +27723,26 @@ function createStore() {
 
 // src/spectrum.ts
 var PHOTON_OTEL_ENDPOINT = "https://otlp.photon.codes";
+var STREAM_CLOSE_TIMEOUT_MS = 5e3;
 var lifecycleLog = createLogger2("spectrum.lifecycle");
 var ignoreCleanupError = () => void 0;
-var spectrumOptionsSchema = z.object({
-  flattenGroups: z.boolean().optional()
+var spectrumOptionsSchema = z2.object({
+  flattenGroups: z2.boolean().optional()
 }).optional();
-var spectrumConfigSchema = z.union([
-  z.object({
-    projectId: z.string().min(1),
-    projectSecret: z.string().min(1),
-    providers: z.array(z.custom()),
+var spectrumConfigSchema = z2.union([
+  z2.object({
+    projectId: z2.string().min(1),
+    projectSecret: z2.string().min(1),
+    providers: z2.array(z2.custom()),
     options: spectrumOptionsSchema,
-    telemetry: z.boolean().optional()
+    telemetry: z2.boolean().optional()
   }),
-  z.object({
-    projectId: z.undefined().optional(),
-    projectSecret: z.undefined().optional(),
-    providers: z.array(z.custom()),
+  z2.object({
+    projectId: z2.undefined().optional(),
+    projectSecret: z2.undefined().optional(),
+    providers: z2.array(z2.custom()),
     options: spectrumOptionsSchema,
-    telemetry: z.boolean().optional()
+    telemetry: z2.boolean().optional()
   })
 ]);
 function bootstrapTelemetry(opts) {
@@ -27614,15 +27780,21 @@ async function Spectrum(options) {
   const platformStates = /* @__PURE__ */ new Map();
   const fusorMessageSources = /* @__PURE__ */ new Map();
   const messageBroadcasters = /* @__PURE__ */ new Map();
+  const fusorEventSources = /* @__PURE__ */ new Map();
+  const eventBroadcasters = /* @__PURE__ */ new Map();
   const customEventStreams = /* @__PURE__ */ new Map();
   let stopped = false;
-  const adaptIterable = (iterable) => stream((emit, end) => {
+  const adaptIterable = (iterable, project) => stream((emit, end) => {
     const iterator = iterable[Symbol.asyncIterator]();
     const pump = (async () => {
       try {
         let result = await iterator.next();
         while (!result.done) {
-          await emit(result.value);
+          if (project) {
+            await project(result.value, emit);
+          } else {
+            await emit(result.value);
+          }
           result = await iterator.next();
         }
         end();
@@ -27694,20 +27866,20 @@ async function Spectrum(options) {
       projectConfig,
       store
     });
-    const bindSend = async function* () {
-      for await (const msg of raw) {
-        const tuples = await resolveRecordToMessages(msg, {
+    return adaptIterable(
+      raw,
+      async (record, emit) => {
+        const tuples = await resolveRecordToMessages(record, {
           client,
           config,
           definition,
           store
         });
         for (const tuple of tuples) {
-          yield tuple;
+          await emit(tuple);
         }
       }
-    };
-    return adaptIterable(bindSend());
+    );
   };
   const getOrCreateMessageBroadcast = (state) => {
     if (stopped) {
@@ -27723,6 +27895,24 @@ async function Spectrum(options) {
     }
     return broadcaster;
   };
+  const getOrCreateEventBroadcast = (platform, channel) => {
+    const queue = fusorEventSources.get(platform)?.get(channel);
+    if (!queue) {
+      return;
+    }
+    if (stopped) {
+      throw new Error(
+        `Spectrum instance has been stopped; cannot subscribe to "${platform}" event "${channel}"`
+      );
+    }
+    const key = `${platform}\0${channel}`;
+    let broadcaster = eventBroadcasters.get(key);
+    if (!broadcaster) {
+      broadcaster = broadcast(adaptIterable(queue.iterable));
+      eventBroadcasters.set(key, broadcaster);
+    }
+    return broadcaster;
+  };
   await withSpan(
     "spectrum.init",
     {
@@ -27744,6 +27934,7 @@ async function Spectrum(options) {
             config: userConfig,
             projectId,
             projectSecret,
+            projectConfig,
             store
           })
         );
@@ -27755,7 +27946,13 @@ async function Spectrum(options) {
         };
         platformStates.set(def.name, {
           ...state,
-          subscribeMessages: () => getOrCreateMessageBroadcast(state).subscribe()
+          projectConfig,
+          subscribeMessages: () => getOrCreateMessageBroadcast(state).subscribe(),
+          // Fanout subscription to a fusor event channel. Returns undefined for
+          // regular platforms (no per-channel queue) — callers fall back to the
+          // producer path. Resolved lazily, after the fusor bootstrap below has
+          // created the per-(platform, channel) queues.
+          subscribeEvent: (channel) => getOrCreateEventBroadcast(def.name, channel)?.subscribe()
         });
       }
     }
@@ -27778,10 +27975,36 @@ async function Spectrum(options) {
         continue;
       }
       const userMessages = runtime.definition.messages;
+      const declaredEvents = runtime.definition.events ?? {};
+      const eventQueues = /* @__PURE__ */ new Map();
+      for (const channel of Object.keys(declaredEvents)) {
+        eventQueues.set(channel, createAsyncQueue());
+      }
+      fusorEventSources.set(name, eventQueues);
       const handler = {
         verify: client.verify,
-        messages: async (ctx) => userMessages(ctx),
-        pushMessage: (record) => queue.push(record)
+        // Enrich the transport-level `{ payload, respond }` ctx with the same
+        // runtime context every other platform callback receives, so fusor
+        // handlers can read config/store/projectConfig directly instead of
+        // smuggling state through the payload.
+        messages: async (ctx) => userMessages({
+          ...ctx,
+          config: runtime.config,
+          store: runtime.store,
+          projectConfig: runtime.projectConfig
+        }),
+        pushMessage: (record) => queue.push(record),
+        pushEvent: (channel, data) => {
+          const eventQueue = eventQueues.get(channel);
+          if (!eventQueue) {
+            lifecycleLog.warn(
+              `spectrum: fusorEvent("${channel}", \u2026) names a channel not declared in "${name}".events; dropping`,
+              { platform: name, channel }
+            );
+            return;
+          }
+          eventQueue.push(data);
+        }
       };
       fusorCore.register(client.platform, handler);
     }
@@ -27828,30 +28051,35 @@ async function Spectrum(options) {
     const providerStreams = [];
     for (const state of platformStates.values()) {
       const { client, config, definition, store } = state;
-      const producer = definition.events?.[eventName];
-      if (!producer) {
-        continue;
-      }
-      const providerEvents = producer({
-        client,
-        config,
-        projectConfig,
-        store
-      });
-      const annotatePlatform = async function* () {
-        for await (const value of providerEvents) {
-          const annotated = await withSpan(
-            "spectrum.event",
-            {
-              "spectrum.provider": definition.name,
-              "spectrum.event.name": eventName
-            },
-            () => ({ ...value, platform: definition.name })
-          );
-          yield annotated;
+      let source = state.subscribeEvent?.(eventName);
+      if (!source) {
+        const producer = definition.events?.[eventName];
+        if (typeof producer !== "function") {
+          continue;
         }
-      };
-      providerStreams.push(adaptIterable(annotatePlatform()));
+        source = producer({ client, config, projectConfig, store });
+      }
+      const providerEvents = source;
+      providerStreams.push(
+        adaptIterable(
+          providerEvents,
+          async (value, emit2) => {
+            const annotated = await withSpan(
+              "spectrum.event",
+              {
+                "spectrum.provider": definition.name,
+                "spectrum.event.name": eventName
+              },
+              // Object payloads are flattened and tagged with `platform`. A
+              // primitive/null payload can't be spread (a string would mangle
+              // into indexed chars, a number/bool would vanish), so wrap it
+              // under `payload` instead.
+              () => typeof value === "object" && value !== null ? { ...value, platform: definition.name } : { platform: definition.name, payload: value }
+            );
+            await emit2(annotated);
+          }
+        )
+      );
     }
     const merged = mergeStreams(providerStreams);
     const pump = (async () => {
@@ -27870,6 +28098,18 @@ async function Spectrum(options) {
     };
   });
   const messagesStream = createMessagesStream();
+  const closeFusorSources = () => {
+    for (const queue of fusorMessageSources.values()) {
+      queue.close();
+    }
+    fusorMessageSources.clear();
+    for (const queues of fusorEventSources.values()) {
+      for (const queue of queues.values()) {
+        queue.close();
+      }
+    }
+    fusorEventSources.clear();
+  };
   const stopOnce = async () => {
     if (stopped) {
       return;
@@ -27884,13 +28124,31 @@ async function Spectrum(options) {
       ...Array.from(
         messageBroadcasters.values(),
         (broadcaster) => broadcaster.close()
+      ),
+      ...Array.from(
+        eventBroadcasters.values(),
+        (broadcaster) => broadcaster.close()
       )
     ];
     process.off("SIGINT", handleSignal);
     process.off("SIGTERM", handleSignal);
     const streamCloseStart = performance.now();
-    await Promise.allSettled(streamShutdowns);
-    const streamCloseMs = Math.round(performance.now() - streamCloseStart);
+    const streamSettled = Promise.allSettled(streamShutdowns);
+    let streamTimedOut = false;
+    await Promise.race([
+      streamSettled,
+      new Promise((resolve) => {
+        setTimeout(() => {
+          streamTimedOut = true;
+          resolve();
+        }, STREAM_CLOSE_TIMEOUT_MS).unref();
+      })
+    ]);
+    if (streamTimedOut) {
+      lifecycleLog.warn("stream close timed out; proceeding to teardown", {
+        timeoutMs: STREAM_CLOSE_TIMEOUT_MS
+      });
+    }
     let fusorCloseMs = 0;
     if (fusorCore) {
       const fusorCloseStart = performance.now();
@@ -27901,10 +28159,7 @@ async function Spectrum(options) {
         lifecycleLog.warn("fusor core close failed", { error });
       });
       fusorCloseMs = Math.round(performance.now() - fusorCloseStart);
-      for (const queue of fusorMessageSources.values()) {
-        queue.close();
-      }
-      fusorMessageSources.clear();
+      closeFusorSources();
     }
     const clientShutdowns = [];
     for (const state of platformStates.values()) {
@@ -27928,8 +28183,11 @@ async function Spectrum(options) {
     const clientCloseStart = performance.now();
     await Promise.allSettled(clientShutdowns);
     const clientCloseMs = Math.round(performance.now() - clientCloseStart);
+    await streamSettled.catch(() => void 0);
+    const streamCloseMs = Math.round(performance.now() - streamCloseStart);
     customEventStreams.clear();
     messageBroadcasters.clear();
+    eventBroadcasters.clear();
     platformStates.clear();
     lifecycleLog.info("Spectrum stopped", {
       providers: providerNames,
@@ -28102,13 +28360,14 @@ export {
   cloud,
   contact,
   custom,
-  defineFusorPlatform,
   definePlatform,
   edit,
   fromVCard,
   fusor,
+  fusorEvent,
   group,
   isFusorClient,
+  isFusorEvent,
   mergeStreams,
   option,
   poll,
@@ -28118,6 +28377,7 @@ export {
   resolveContents,
   richlink,
   stream,
+  streamText,
   text,
   toVCard,
   typing,

package/dist/manifest.json

@@ -11,6 +11,12 @@
     "path": "spectrum-ts/providers/slack",
     "label": "Slack"
   },
+  {
+    "key": "telegram",
+    "import": "telegram",
+    "path": "spectrum-ts/providers/telegram",
+    "label": "telegram"
+  },
   {
     "key": "terminal",
     "import": "terminal",