@m4trix/core 0.9.0 → 0.11.0

package/dist/matrix/index.js

@@ -1,4 +1,4 @@
-import { Brand, Schema, Effect, PubSub, Queue, Cause } from 'effect';
+import { Brand, Schema, Tracer, Layer, Effect, Exit, PubSub, Queue, Cause } from 'effect';
 export { Schema as S } from 'effect';
 import { randomUUID } from 'crypto';
 
@@ -150,7 +150,16 @@ var createEventPlane = (options) => Effect.gen(function* () {
   };
   const publishToPubSub = (channel, envelope) => PubSub.publish(getPubsub(channel), envelope);
   const publish = (channel, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
-    Effect.flatMap(() => publishToPubSub(channel, envelope))
+    Effect.flatMap(() => publishToPubSub(channel, envelope)),
+    Effect.withSpan("event.publish", {
+      attributes: {
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        channel,
+        runId: envelope.meta.runId,
+        contextId: envelope.meta.contextId
+      }
+    })
   );
   const publishToChannels = (targetChannels, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
     Effect.flatMap(
@@ -159,7 +168,15 @@ var createEventPlane = (options) => Effect.gen(function* () {
         { concurrency: "unbounded" }
       )
     ),
-    Effect.map((results) => results.every(Boolean))
+    Effect.map((results) => results.every(Boolean)),
+    Effect.withSpan("event.publish", {
+      attributes: {
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        runId: envelope.meta.runId,
+        contextId: envelope.meta.contextId
+      }
+    })
   );
   const subscribe = (channel) => PubSub.subscribe(getPubsub(channel));
   const getRunEvents = (runId, contextId) => {
@@ -192,8 +209,17 @@ var createEventPlane = (options) => Effect.gen(function* () {
     shutdown
   };
 });
-var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.gen(function* () {
+function payloadForSpan(payload, maxLen = 500) {
+  try {
+    const s = JSON.stringify(payload);
+    return s.length > maxLen ? `${s.slice(0, maxLen)}...` : s;
+  } catch {
+    return String(payload);
+  }
+}
+var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue, channelName) => Effect.gen(function* () {
   const listensTo = agent.getListensTo?.() ?? [];
+  const agentId = agent.getId();
   const processOne = () => Effect.gen(function* () {
     const envelope = yield* Queue.take(dequeue);
     if (listensTo.length > 0 && !listensTo.includes(envelope.name)) {
@@ -204,34 +230,51 @@ var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.ge
       envelope.meta.contextId
     );
     const contextEvents = plane.getContextEvents(envelope.meta.contextId);
-    yield* Effect.tryPromise({
-      try: () => agent.invoke({
-        triggerEvent: envelope,
-        emit: (userEvent) => {
-          const fullEnvelope = {
-            name: userEvent.name,
-            meta: envelope.meta,
-            payload: userEvent.payload
-          };
-          if (emitQueue) {
-            Effect.runPromise(
-              Queue.offer(emitQueue, {
-                channels: publishesTo,
-                envelope: fullEnvelope
-              })
-            ).catch(() => {
-            });
-          } else {
-            Effect.runFork(
-              plane.publishToChannels(publishesTo, fullEnvelope)
-            );
-          }
-        },
-        runEvents,
-        contextEvents
-      }),
-      catch: (e) => e
-    });
+    yield* Effect.withSpan("agent.listen", {
+      attributes: {
+        agentId,
+        "event.name": envelope.name,
+        "event.payload": payloadForSpan(envelope.payload),
+        ...channelName !== void 0 && { channel: channelName }
+      }
+    })(
+      Effect.withSpan("agent.invoke", {
+        attributes: {
+          agentId,
+          "event.name": envelope.name,
+          "event.payload": payloadForSpan(envelope.payload)
+        }
+      })(
+        Effect.tryPromise({
+          try: () => agent.invoke({
+            triggerEvent: envelope,
+            emit: (userEvent) => {
+              const fullEnvelope = {
+                name: userEvent.name,
+                meta: envelope.meta,
+                payload: userEvent.payload
+              };
+              if (emitQueue) {
+                Effect.runPromise(
+                  Queue.offer(emitQueue, {
+                    channels: publishesTo,
+                    envelope: fullEnvelope
+                  })
+                ).catch(() => {
+                });
+              } else {
+                Effect.runFork(
+                  plane.publishToChannels(publishesTo, fullEnvelope)
+                );
+              }
+            },
+            runEvents,
+            contextEvents
+          }),
+          catch: (e) => e
+        })
+      )
+    );
   }).pipe(
     Effect.catchAllCause(
       (cause) => Cause.isInterrupted(cause) ? Effect.void : Effect.sync(() => {
@@ -253,7 +296,8 @@ var run = (network, plane, options) => Effect.gen(function* () {
         reg.publishesTo,
         dequeue,
         plane,
-        emitQueue
+        emitQueue,
+        channel.name
       );
     }
   }
@@ -327,7 +371,8 @@ function expose(network, options) {
     select,
     plane: providedPlane,
     onRequest,
-    triggerEvents
+    triggerEvents,
+    tracingLayer
   } = options;
   const triggerEventDef = triggerEvents?.[0];
   const triggerEventName = triggerEventDef?.name ?? "request";
@@ -341,7 +386,7 @@ function expose(network, options) {
     const payload = await extractPayload(req);
     const signal = req.request?.signal;
     const program = Effect.gen(function* () {
-      const plane = providedPlane ?? (yield* createEventPlane({ network }));
+      const plane = providedPlane ?? (yield* createEventPlane({ network, store: network.getStore() }));
       if (!providedPlane) {
         const emitQueue = yield* Queue.unbounded();
         yield* Effect.fork(
@@ -409,7 +454,8 @@ function expose(network, options) {
       }
       return stream;
     });
-    return Effect.runPromise(program.pipe(Effect.scoped));
+    const runnable = tracingLayer ? program.pipe(Effect.provide(tracingLayer), Effect.scoped) : program.pipe(Effect.scoped);
+    return Effect.runPromise(runnable);
   };
   return {
     protocol: "sse",
@@ -441,6 +487,7 @@ var AgentNetwork = class _AgentNetwork {
     this.channels = /* @__PURE__ */ new Map();
     this.agentRegistrations = /* @__PURE__ */ new Map();
     this.spawnerRegistrations = [];
+    this._store = createInMemoryNetworkStore();
   }
   /* ─── Public Static Factory ─── */
   static setup(callback) {
@@ -528,6 +575,10 @@ var AgentNetwork = class _AgentNetwork {
   getSpawnerRegistrations() {
     return this.spawnerRegistrations;
   }
+  /** Store defined at network setup time. Shared across all event planes created for this network. */
+  getStore() {
+    return this._store;
+  }
   /**
    * Expose the network as a streamable API (e.g. SSE). Returns an ExposedAPI
    * that adapters (NextEndpoint, ExpressEndpoint) consume to produce streamed
@@ -553,7 +604,11 @@ var AgentNetwork = class _AgentNetwork {
   }
   runScoped(network, capacity) {
     return Effect.gen(function* () {
-      const plane = yield* createEventPlane({ network, capacity });
+      const plane = yield* createEventPlane({
+        network,
+        capacity,
+        store: network.getStore()
+      });
       yield* Effect.fork(run(network, plane));
       return plane;
     });
@@ -711,6 +766,157 @@ var AgentFactory = class _AgentFactory {
     );
   }
 };
+var CAMEL_CASE_REGEX = /^[a-z][a-zA-Z0-9]*$/;
+var LayerName = Brand.refined(
+  (s) => typeof s === "string" && CAMEL_CASE_REGEX.test(s),
+  (s) => Brand.error(`Expected camelCase (e.g. myLayerFoo), got: ${s}`)
+);
+var SkillDependency = {
+  of(config) {
+    const name = LayerName(config.name);
+    const decode = Schema.decodeUnknown(config.shape);
+    return {
+      _tag: "SkillDependencyDef",
+      name,
+      _name: config.name,
+      shape: config.shape,
+      decode
+    };
+  }
+};
+function toLayerArray(layers) {
+  if (layers.length === 1 && Array.isArray(layers[0])) {
+    return layers[0];
+  }
+  return [...layers];
+}
+function assertUniqueLayerNames(layers) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const dep of layers) {
+    const key = dep.name;
+    if (seen.has(key)) {
+      throw new Error(`Duplicate layer name: ${key}`);
+    }
+    seen.add(key);
+  }
+}
+var Skill = class _Skill {
+  constructor(params) {
+    this._inputSchema = params.inputSchema;
+    this._chunkSchema = params.chunkSchema;
+    this._doneSchema = params.doneSchema;
+    this._layers = params.layers;
+    this._defineFn = params.defineFn;
+  }
+  getState() {
+    return {
+      inputSchema: this._inputSchema,
+      chunkSchema: this._chunkSchema,
+      doneSchema: this._doneSchema,
+      layers: this._layers,
+      defineFn: this._defineFn
+    };
+  }
+  static of(_options) {
+    return new _Skill({
+      layers: []
+    });
+  }
+  input(schema) {
+    return new _Skill({
+      ...this.getState(),
+      inputSchema: schema
+    });
+  }
+  chunk(schema) {
+    return new _Skill({
+      ...this.getState(),
+      chunkSchema: schema
+    });
+  }
+  done(schema) {
+    return new _Skill({
+      ...this.getState(),
+      doneSchema: schema
+    });
+  }
+  use(...layers) {
+    const normalized = toLayerArray(layers);
+    const allLayers = [...this._layers, ...normalized];
+    assertUniqueLayerNames(allLayers);
+    return new _Skill({
+      ...this.getState(),
+      layers: allLayers
+    });
+  }
+  define(fn) {
+    const state = this.getState();
+    const inputSchema = state.inputSchema;
+    const chunkSchema = state.chunkSchema;
+    const doneSchema = state.doneSchema;
+    const defineFn = fn;
+    if (!inputSchema || !chunkSchema || !doneSchema || !defineFn) {
+      throw new Error(
+        "Skill.define requires input(), chunk(), and done() to be called before define()"
+      );
+    }
+    const decodeInput = Schema.decodeUnknown(inputSchema);
+    const decodeChunk = Schema.decodeUnknown(chunkSchema);
+    const decodeDone = Schema.decodeUnknown(doneSchema);
+    const runDefine = async (input, runtime) => {
+      const layersObj = runtime?.layers ?? {};
+      const chunks = [];
+      const emit = (chunk) => {
+        const decoded = Effect.runSync(
+          decodeChunk(chunk)
+        );
+        chunks.push(decoded);
+      };
+      const done = await defineFn({
+        input,
+        emit,
+        layers: layersObj
+      });
+      const decodedDone = Effect.runSync(
+        decodeDone(done)
+      );
+      return { chunks, done: decodedDone };
+    };
+    return {
+      invokeStream: async function* (input, runtime) {
+        const decodedInput = Effect.runSync(
+          decodeInput(input)
+        );
+        const layersObj = runtime?.layers ?? {};
+        const chunks = [];
+        const emit = (chunk) => {
+          const decoded = Effect.runSync(
+            decodeChunk(chunk)
+          );
+          chunks.push(decoded);
+        };
+        const done = await defineFn({
+          input: decodedInput,
+          emit,
+          layers: layersObj
+        });
+        const decodedDone = Effect.runSync(
+          decodeDone(done)
+        );
+        for (const c of chunks) {
+          yield c;
+        }
+        yield { _tag: "Done", done: decodedDone };
+      },
+      invoke: async (input, runtime) => {
+        const decodedInput = Effect.runSync(
+          decodeInput(input)
+        );
+        return runDefine(decodedInput, runtime);
+      }
+    };
+  }
+};
 
 // src/matrix/io/protocols/sse.ts
 function formatSSE(envelope) {
@@ -848,7 +1054,79 @@ var ExpressEndpoint = {
     };
   }
 };
+var randomHexString = (length) => {
+  const chars = "abcdef0123456789";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+};
+var ConsoleSpan = class {
+  constructor(name, parent, context, links, startTime, kind, depth) {
+    this.name = name;
+    this.parent = parent;
+    this.context = context;
+    this.startTime = startTime;
+    this.kind = kind;
+    this.depth = depth;
+    this._tag = "Span";
+    this.sampled = true;
+    this.attributes = /* @__PURE__ */ new Map();
+    this.links = [];
+    this.traceId = parent._tag === "Some" ? parent.value.traceId : randomHexString(32);
+    this.spanId = randomHexString(16);
+    this.links = Array.from(links);
+    this.status = { _tag: "Started", startTime };
+  }
+  end(endTime, exit) {
+    if (this.status._tag === "Ended")
+      return;
+    const startTime = this.status.startTime;
+    const durationNs = endTime - startTime;
+    const durationMs = Number(durationNs) / 1e6;
+    const indent = "  ".repeat(this.depth);
+    const attrs = Object.fromEntries(this.attributes);
+    const status = Exit.isSuccess(exit) ? "ok" : "error";
+    console.log(
+      `${indent}[trace] ${this.name} ${durationMs.toFixed(2)}ms (${status})`,
+      Object.keys(attrs).length > 0 ? attrs : ""
+    );
+    this.status = { _tag: "Ended", startTime, endTime, exit };
+  }
+  attribute(key, value) {
+    this.attributes.set(key, value);
+  }
+  event(_name, _startTime, _attributes) {
+  }
+  addLinks(links) {
+    this.links.push(...links);
+  }
+};
+function getDepth(parent) {
+  if (parent._tag === "None")
+    return 0;
+  const p = parent.value;
+  if (p._tag === "ExternalSpan")
+    return 0;
+  return 1 + getDepth(p.parent);
+}
+var consoleTracer = Tracer.make({
+  span: (name, parent, context, links, startTime, kind) => new ConsoleSpan(
+    name,
+    parent,
+    context,
+    links,
+    startTime,
+    kind,
+    getDepth(parent)
+  ),
+  context: (f) => f()
+});
+var consoleTracerLayer = Layer.setTracer(
+  consoleTracer
+);
 
-export { Agent, AgentFactory, AgentNetwork, AgentNetworkEvent, Channel, ChannelName, ConfiguredChannel, EventMetaSchema, ExposeAuthError, ExpressEndpoint, NextEndpoint, Sink, formatSSE, isHttpStreamSink, toSSEStream };
+export { Agent, AgentFactory, AgentNetwork, AgentNetworkEvent, Channel, ChannelName, ConfiguredChannel, EventMetaSchema, ExposeAuthError, ExpressEndpoint, LayerName, NextEndpoint, Sink, Skill, SkillDependency, consoleTracer, consoleTracerLayer, formatSSE, isHttpStreamSink, toSSEStream };
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map