@m4trix/core 0.8.0 → 0.9.0

package/dist/matrix/index.d.ts

@@ -2,31 +2,30 @@ import { Schema, Effect, Brand, Queue, Scope } from 'effect';
 export { Schema as S } from 'effect';
 import { ParseError } from 'effect/ParseResult';
 
-type LogicFn$1<TParams, TTriggerEvent, TEmitEvent> = (ctx: {
-    params: TParams;
-    triggerEvent: TTriggerEvent;
-    emit: (event: TEmitEvent) => void;
-}) => Promise<void>;
-declare class Agent<TParams, TTriggerEvent = never, TEmitEvent = never> {
-    #private;
-    constructor(logic: LogicFn$1<TParams, TTriggerEvent, TEmitEvent>, params: TParams, listensTo?: readonly string[]);
-    getListensTo(): readonly string[];
-    invoke(options?: {
-        triggerEvent?: TTriggerEvent;
-        emit?: (event: TEmitEvent) => void;
-    }): Promise<void>;
-    getId(): string;
-}
-
 /** Standard meta carried by every event */
 declare const EventMetaSchema: Schema.Struct<{
     runId: typeof Schema.String;
-    contextId: Schema.optional<typeof Schema.String>;
+    contextId: typeof Schema.String;
     correlationId: Schema.optional<typeof Schema.String>;
     causationId: Schema.optional<typeof Schema.String>;
     ts: Schema.optional<typeof Schema.Number>;
 }>;
 type EventMeta = Schema.Schema.Type<typeof EventMetaSchema>;
+/** Envelope-like shape for events (avoids circular dep with event-plane) */
+type EnvelopeLike = {
+    name: string;
+    meta: EventMeta;
+    payload: unknown;
+};
+type RunEvents = readonly EnvelopeLike[];
+type ContextEvents = {
+    /** All events in the context across all runs */
+    readonly all: readonly EnvelopeLike[];
+    /** Get events for a specific run */
+    byRun(runId: string): readonly EnvelopeLike[];
+    /** Map of runId -> events */
+    readonly map: ReadonlyMap<string, readonly EnvelopeLike[]>;
+};
 
 type AgentNetworkEventDef<EventName extends string, PayloadSchema extends Schema.Schema.Any> = {
     readonly _tag: 'AgentNetworkEventDef';
@@ -85,6 +84,26 @@ declare const AgentNetworkEvent: {
     of<const EventName extends string, PS extends Schema.Schema.Any>(name: EventName, payload: PS): AgentNetworkEventDef<EventName, PS>;
 };
 
+type LogicFn$1<TParams, TTriggerEvent, TEmitEvent> = (ctx: {
+    params: TParams;
+    triggerEvent: TTriggerEvent;
+    emit: (event: TEmitEvent) => void;
+    runEvents: RunEvents;
+    contextEvents: ContextEvents;
+}) => Promise<void>;
+declare class Agent<TParams, TTriggerEvent = never, TEmitEvent = never> {
+    #private;
+    constructor(logic: LogicFn$1<TParams, TTriggerEvent, TEmitEvent>, params: TParams, listensTo?: readonly string[]);
+    getListensTo(): readonly string[];
+    invoke(options?: {
+        triggerEvent?: TTriggerEvent;
+        emit?: (event: TEmitEvent) => void;
+        runEvents?: RunEvents;
+        contextEvents?: ContextEvents;
+    }): Promise<void>;
+    getId(): string;
+}
+
 type BaseSchemaDefintion = Schema.Schema.Any;
 
 type EventDef$2 = AgentNetworkEventDef<string, Schema.Schema.Any>;
@@ -104,6 +123,8 @@ type LogicFn<TParams, TTriggerEvent, TEmitEvent> = (ctx: {
     params: TParams;
     triggerEvent: TTriggerEvent;
     emit: (event: TEmitEvent) => void;
+    runEvents: RunEvents;
+    contextEvents: ContextEvents;
 }) => Promise<void>;
 declare class AgentFactory<TParams = unknown, TListensTo extends EventDef$2 = never, TEmits extends EventDef$2 = never> {
     private _listensTo;
@@ -184,6 +205,8 @@ type EventPlane = {
     readonly publish: (channel: ChannelName, envelope: Envelope) => Effect.Effect<boolean>;
     readonly publishToChannels: (channels: readonly ConfiguredChannel[], envelope: Envelope) => Effect.Effect<boolean>;
     readonly subscribe: (channel: ChannelName) => Effect.Effect<Queue.Dequeue<Envelope>, never, Scope.Scope>;
+    readonly getRunEvents: (runId: string, contextId: string) => RunEvents;
+    readonly getContextEvents: (contextId: string) => ContextEvents;
     readonly shutdown: Effect.Effect<void>;
 };
 
@@ -195,6 +218,10 @@ type ExposeRequest = {
     req?: unknown;
     /** Express res (when using ExpressEndpoint) */
     res?: unknown;
+    /** Set by adapters via requestToContextId. Correlation ID between runs. */
+    contextId?: string;
+    /** Set by adapters via requestToRunId. Unique per run. */
+    runId?: string;
 };
 /** Auth result: allow or deny with optional status */
 type AuthResult = {
@@ -211,10 +238,21 @@ type ExposeSelect = {
     /** Event names to filter. Empty = all events. */
     events?: string[];
 };
+/** Unbound event shape (name + payload, no meta) - use eventDef.make(payload) to create */
+type UnboundEvent = {
+    name: string;
+    payload: unknown;
+};
 /** Context passed to onRequest callback */
 type OnRequestContext<T = unknown> = {
-    /** Emit the start event. Call with no arg to use default payload (request body), or pass custom payload. */
-    emitStartEvent: (payload?: T) => void;
+    setRunId: (id: string) => void;
+    setContextId: (id: string) => void;
+    /** Emit the start event. Pass { contextId, runId, event } where event is the unbound version of one of triggerEvents (e.g. MessageEvent.make(payload)). */
+    emitStartEvent: (opts: {
+        contextId: string;
+        runId: string;
+        event: UnboundEvent;
+    }) => void;
     /** The raw request context */
     req: ExposeRequest;
     /** Pre-parsed request body (JSON for POST, or {} for GET) */
@@ -229,10 +267,9 @@ type ExposeOptions = {
     select?: ExposeSelect;
     /** Optional: use existing EventPlane instead of creating one per request */
     plane?: EventPlane;
-    /** Event name when publishing the start event. Default: "request" */
-    startEventName?: string;
-    /** Called when a client connects, after plane is ready. Receives emitStartEvent (not the plane).
-     * Call emitStartEvent() for default payload, emitStartEvent(mapped) for custom mapping, or omit to skip. */
+    /** Event definitions that can trigger a run (e.g. from AgentNetworkEvent.of). First is used for default emit. Default: "request" when omitted. */
+    triggerEvents?: ReadonlyArray<AgentNetworkEventDef<string, Schema.Schema.Any>>;
+    /** Called when a client connects, after plane is ready. Use setRunId/setContextId and emitStartEvent. */
     onRequest?: <T = unknown>(ctx: OnRequestContext<T>) => void | Promise<void>;
 };
 /** Protocol-agnostic stream source that adapters consume */
@@ -335,7 +372,7 @@ declare class AgentNetwork {
      *
      * @example
      * const api = network.expose({ protocol: "sse", auth, select });
-     * export const GET = NextEndpoint.from(api).handler();
+     * export const GET = NextEndpoint.from(api, { requestToContextId, requestToRunId }).handler();
      */
     expose(options: ExposeOptions): ExposedAPI;
     /**
@@ -363,6 +400,11 @@ declare function toSSEStream(source: AsyncIterable<Envelope>, signal?: AbortSign
 
 /** Next.js App Router GET/POST handler signature */
 type NextGetHandler = (request: Request) => Promise<Response>;
+/** Options for NextEndpoint.from() - required to define how request maps to contextId and runId */
+type NextEndpointOptions = {
+    requestToContextId: (request: Request) => string;
+    requestToRunId: (request: Request) => string;
+};
 /**
  * Adapter for Next.js App Router. Maps an ExposedAPI to a route handler
  * that streams events as SSE. Use for both GET and POST; POST with JSON body
@@ -370,12 +412,15 @@ type NextGetHandler = (request: Request) => Promise<Response>;
  *
  * @example
  * const api = agentNetwork.expose({ protocol: "sse", auth, select });
- * const handler = NextEndpoint.from(api).handler();
+ * const handler = NextEndpoint.from(api, {
+ *   requestToContextId: (req) => req.headers.get('x-correlation-id') ?? crypto.randomUUID(),
+ *   requestToRunId: () => crypto.randomUUID(),
+ * }).handler();
  * export const GET = handler;
  * export const POST = handler;
  */
 declare const NextEndpoint: {
-    from(api: ExposedAPI): {
+    from(api: ExposedAPI, options: NextEndpointOptions): {
         handler(): NextGetHandler;
     };
 };
@@ -384,6 +429,11 @@ declare const NextEndpoint: {
 type ExpressRequest = {
     on(event: 'close', fn: () => void): void;
 };
+/** Options for ExpressEndpoint.from() - required to define how request maps to contextId and runId */
+type ExpressEndpointOptions = {
+    requestToContextId: (req: ExpressRequest) => string;
+    requestToRunId: (req: ExpressRequest) => string;
+};
 /** Minimal Express-like response (compatible with express.Response) */
 type ExpressResponse = {
     setHeader(name: string, value: string | number): void;
@@ -402,12 +452,15 @@ type ExpressHandler = (req: ExpressRequest, res: ExpressResponse) => void | Prom
  *
  * @example
  * const api = agentNetwork.expose({ protocol: "sse", auth, select });
- * app.get("/events", ExpressEndpoint.from(api).handler());
+ * app.get("/events", ExpressEndpoint.from(api, {
+ *   requestToContextId: (req) => req.headers?.['x-correlation-id'] ?? crypto.randomUUID(),
+ *   requestToRunId: () => crypto.randomUUID(),
+ * }).handler());
  */
 declare const ExpressEndpoint: {
-    from(api: ExposedAPI): {
+    from(api: ExposedAPI, options: ExpressEndpointOptions): {
         handler(): ExpressHandler;
     };
 };
 
-export { Agent, AgentBinding, AgentFactory, AgentNetwork, AgentNetworkEvent, AgentNetworkEventDef, AnyAgent, AuthResult, Channel, ChannelDef, ChannelName, ConfiguredChannel, EmitPayload, EventEnvelope, EventMeta, EventMetaSchema, EventPlane, ExposeAuthError, ExposeOptions, ExposeRequest, ExposeSelect, ExposedAPI, ExposedStream, ExpressEndpoint, ExpressHandler, ExpressRequest, ExpressResponse, NextEndpoint, NextGetHandler, OnRequestContext, SetupContext, Sink, SinkDef, SpawnCallbackContext, SpawnFn, SpawnerBuilder, StreamFactory, formatSSE, isHttpStreamSink, toSSEStream };
+export { Agent, AgentBinding, AgentFactory, AgentNetwork, AgentNetworkEvent, AgentNetworkEventDef, AnyAgent, AuthResult, Channel, ChannelDef, ChannelName, ConfiguredChannel, ContextEvents, EmitPayload, EnvelopeLike, EventEnvelope, EventMeta, EventMetaSchema, EventPlane, ExposeAuthError, ExposeOptions, ExposeRequest, ExposeSelect, ExposedAPI, ExposedStream, ExpressEndpoint, ExpressEndpointOptions, ExpressHandler, ExpressRequest, ExpressResponse, NextEndpoint, NextEndpointOptions, NextGetHandler, OnRequestContext, RunEvents, SetupContext, Sink, SinkDef, SpawnCallbackContext, SpawnFn, SpawnerBuilder, StreamFactory, UnboundEvent, formatSSE, isHttpStreamSink, toSSEStream };

package/dist/matrix/index.js

@@ -72,8 +72,66 @@ var Channel = {
     };
   }
 };
+
+// src/helper/types/noop.ts
+var asyncNoop = async () => {
+};
+
+// src/matrix/agent-network/stores/inmemory-network-store.ts
+var createInMemoryNetworkStore = () => {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    storeEvent: (contextId, runId, event) => {
+      let byRun = store.get(contextId);
+      if (!byRun) {
+        byRun = /* @__PURE__ */ new Map();
+        store.set(contextId, byRun);
+      }
+      let events = byRun.get(runId);
+      if (!events) {
+        events = [];
+        byRun.set(runId, events);
+      }
+      events.push(event);
+    },
+    getEvents: (contextId, runId) => {
+      const events = store.get(contextId)?.get(runId);
+      return events ? [...events] : [];
+    },
+    getContextEvents: (contextId) => {
+      const byRun = store.get(contextId);
+      const result = /* @__PURE__ */ new Map();
+      if (byRun) {
+        for (const [runId, events] of byRun) {
+          result.set(runId, [...events]);
+        }
+      }
+      return result;
+    },
+    getFullStore: () => {
+      const result = /* @__PURE__ */ new Map();
+      for (const [contextId, byRun] of store) {
+        const contextMap = /* @__PURE__ */ new Map();
+        for (const [runId, events] of byRun) {
+          contextMap.set(runId, [...events]);
+        }
+        result.set(contextId, contextMap);
+      }
+      return result;
+    },
+    persist: () => asyncNoop(),
+    load: () => asyncNoop()
+  };
+};
+
+// src/matrix/agent-network/event-plane.ts
 var DEFAULT_CAPACITY = 16;
-var createEventPlane = (network, capacity = DEFAULT_CAPACITY) => Effect.gen(function* () {
+var createEventPlane = (options) => Effect.gen(function* () {
+  const {
+    network,
+    capacity = DEFAULT_CAPACITY,
+    store = createInMemoryNetworkStore()
+  } = options;
   const channels = network.getChannels();
   const pubsubs = /* @__PURE__ */ new Map();
   for (const channel of channels.values()) {
@@ -86,12 +144,42 @@ var createEventPlane = (network, capacity = DEFAULT_CAPACITY) => Effect.gen(func
       throw new Error(`Channel not found: ${channel}`);
     return p;
   };
-  const publish = (channel, envelope) => PubSub.publish(getPubsub(channel), envelope);
-  const publishToChannels = (targetChannels, envelope) => Effect.all(
-    targetChannels.map((c) => publish(c.name, envelope)),
-    { concurrency: "unbounded" }
-  ).pipe(Effect.map((results) => results.every(Boolean)));
+  const recordEvent = (envelope) => {
+    const { contextId, runId } = envelope.meta;
+    store.storeEvent(contextId, runId, envelope);
+  };
+  const publishToPubSub = (channel, envelope) => PubSub.publish(getPubsub(channel), envelope);
+  const publish = (channel, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
+    Effect.flatMap(() => publishToPubSub(channel, envelope))
+  );
+  const publishToChannels = (targetChannels, envelope) => Effect.sync(() => recordEvent(envelope)).pipe(
+    Effect.flatMap(
+      () => Effect.all(
+        targetChannels.map((c) => publishToPubSub(c.name, envelope)),
+        { concurrency: "unbounded" }
+      )
+    ),
+    Effect.map((results) => results.every(Boolean))
+  );
   const subscribe = (channel) => PubSub.subscribe(getPubsub(channel));
+  const getRunEvents = (runId, contextId) => {
+    return store.getEvents(contextId, runId).slice();
+  };
+  const getContextEvents = (contextId) => {
+    const byRun = store.getContextEvents(contextId);
+    const map = /* @__PURE__ */ new Map();
+    const all = [];
+    for (const [runId, events] of byRun) {
+      const readonlyEvents = events.slice();
+      map.set(runId, readonlyEvents);
+      all.push(...readonlyEvents);
+    }
+    return {
+      all,
+      byRun: (runId) => map.get(runId) ?? [],
+      map
+    };
+  };
   const shutdown = Effect.all([...pubsubs.values()].map(PubSub.shutdown), {
     concurrency: "unbounded"
   }).pipe(Effect.asVoid);
@@ -99,6 +187,8 @@ var createEventPlane = (network, capacity = DEFAULT_CAPACITY) => Effect.gen(func
     publish,
     publishToChannels,
     subscribe,
+    getRunEvents,
+    getContextEvents,
     shutdown
   };
 });
@@ -109,6 +199,11 @@ var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.ge
     if (listensTo.length > 0 && !listensTo.includes(envelope.name)) {
       return;
     }
+    const runEvents = plane.getRunEvents(
+      envelope.meta.runId,
+      envelope.meta.contextId
+    );
+    const contextEvents = plane.getContextEvents(envelope.meta.contextId);
     yield* Effect.tryPromise({
       try: () => agent.invoke({
         triggerEvent: envelope,
@@ -131,7 +226,9 @@ var runSubscriber = (agent, publishesTo, dequeue, plane, emitQueue) => Effect.ge
               plane.publishToChannels(publishesTo, fullEnvelope)
             );
           }
-        }
+        },
+        runEvents,
+        contextEvents
       }),
       catch: (e) => e
     });
@@ -225,7 +322,15 @@ function streamFromDequeue(take, signal, eventFilter) {
   };
 }
 function expose(network, options) {
-  const { auth, select, plane: providedPlane, onRequest, startEventName = "request" } = options;
+  const {
+    auth,
+    select,
+    plane: providedPlane,
+    onRequest,
+    triggerEvents
+  } = options;
+  const triggerEventDef = triggerEvents?.[0];
+  const triggerEventName = triggerEventDef?.name ?? "request";
   const channels = resolveChannels(network, select);
   const eventFilter = select?.events;
   const mainChannel = network.getMainChannel();
@@ -236,7 +341,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 }));
       if (!providedPlane) {
         const emitQueue = yield* Queue.unbounded();
         yield* Effect.fork(
@@ -252,25 +357,46 @@ function expose(network, options) {
         yield* Effect.sleep("10 millis");
       }
       const targetChannel = mainChannel?.name ?? channels[0];
-      const emitStartEvent = (p) => {
-        const pld = p ?? payload;
+      let runId = req.runId ?? crypto.randomUUID();
+      let contextId = req.contextId ?? crypto.randomUUID();
+      const setRunId = (id) => {
+        runId = id;
+      };
+      const setContextId = (id) => {
+        contextId = id;
+      };
+      const emitStartEvent = (opts) => {
+        const meta = {
+          runId: opts.runId,
+          contextId: opts.contextId
+        };
         const envelope = {
-          name: startEventName,
-          meta: { runId: crypto.randomUUID() },
-          payload: pld
+          name: opts.event.name,
+          meta,
+          payload: opts.event.payload
         };
-        Effect.runPromise(plane.publish(targetChannel, envelope)).catch(() => {
-        });
+        Effect.runPromise(plane.publish(targetChannel, envelope)).catch(
+          () => {
+          }
+        );
       };
       const dequeue = yield* plane.subscribe(channels[0]);
       if (onRequest) {
         yield* Effect.tryPromise(
-          () => Promise.resolve(onRequest({ emitStartEvent, req, payload }))
+          () => Promise.resolve(
+            onRequest({
+              setRunId,
+              setContextId,
+              emitStartEvent,
+              req,
+              payload
+            })
+          )
         );
       } else if (!providedPlane) {
         const envelope = {
-          name: startEventName,
-          meta: { runId: crypto.randomUUID() },
+          name: triggerEventName,
+          meta: { runId, contextId },
           payload
         };
         yield* plane.publish(targetChannel, envelope);
@@ -409,7 +535,7 @@ var AgentNetwork = class _AgentNetwork {
    *
    * @example
    * const api = network.expose({ protocol: "sse", auth, select });
-   * export const GET = NextEndpoint.from(api).handler();
+   * export const GET = NextEndpoint.from(api, { requestToContextId, requestToRunId }).handler();
    */
   expose(options) {
     return expose(this, options);
@@ -427,7 +553,7 @@ var AgentNetwork = class _AgentNetwork {
   }
   runScoped(network, capacity) {
     return Effect.gen(function* () {
-      const plane = yield* createEventPlane(network, capacity);
+      const plane = yield* createEventPlane({ network, capacity });
       yield* Effect.fork(run(network, plane));
       return plane;
     });
@@ -435,7 +561,7 @@ var AgentNetwork = class _AgentNetwork {
 };
 var EventMetaSchema = Schema.Struct({
   runId: Schema.String,
-  contextId: Schema.optional(Schema.String),
+  contextId: Schema.String,
   correlationId: Schema.optional(Schema.String),
   causationId: Schema.optional(Schema.String),
   ts: Schema.optional(Schema.Number)
@@ -458,9 +584,7 @@ var AgentNetworkEvent = {
     const makeBound = (meta, payload2) => Effect.runSync(
       decodeEnvelope({ name, meta, payload: payload2 })
     );
-    const makeEffect = (payload2) => decodePayload(payload2).pipe(
-      Effect.map((p) => ({ name, payload: p }))
-    );
+    const makeEffect = (payload2) => decodePayload(payload2).pipe(Effect.map((p) => ({ name, payload: p })));
     const makeBoundEffect = (meta, payload2) => decodeEnvelope({ name, meta, payload: payload2 });
     const is = Schema.is(envelopeSchema);
     return {
@@ -493,13 +617,19 @@ var Agent = class {
     return __privateGet(this, _listensTo);
   }
   async invoke(options) {
-    const { triggerEvent, emit } = options ?? {};
+    const { triggerEvent, emit, runEvents, contextEvents } = options ?? {};
     const emitFn = emit ?? ((_event) => {
     });
     await __privateGet(this, _logic).call(this, {
       params: __privateGet(this, _params),
       triggerEvent: triggerEvent ?? void 0,
-      emit: emitFn
+      emit: emitFn,
+      runEvents: runEvents ?? [],
+      contextEvents: contextEvents ?? {
+        all: [],
+        byRun: () => [],
+        map: /* @__PURE__ */ new Map()
+      }
     });
   }
   getId() {
@@ -612,14 +742,19 @@ function toSSEStream(source, signal) {
 
 // src/matrix/io/adapters/next-endpoint.ts
 var NextEndpoint = {
-  from(api) {
+  from(api, options) {
     if (api.protocol !== "sse") {
       throw new Error(`NextEndpoint: unsupported protocol "${api.protocol}"`);
     }
+    const { requestToContextId, requestToRunId } = options;
     return {
       handler() {
         return async (request) => {
-          const req = { request };
+          const req = {
+            request,
+            contextId: requestToContextId(request),
+            runId: requestToRunId(request)
+          };
           try {
             const encoder = new TextEncoder();
             const { readable, writable } = new TransformStream();
@@ -664,12 +799,13 @@ var NextEndpoint = {
 
 // src/matrix/io/adapters/express-endpoint.ts
 var ExpressEndpoint = {
-  from(api) {
+  from(api, options) {
     if (api.protocol !== "sse") {
       throw new Error(
         `ExpressEndpoint: unsupported protocol "${api.protocol}"`
       );
     }
+    const { requestToContextId, requestToRunId } = options;
     return {
       handler() {
         return async (req, res) => {
@@ -678,7 +814,9 @@ var ExpressEndpoint = {
           const exposeReq = {
             request: { signal: controller.signal },
             req,
-            res
+            res,
+            contextId: requestToContextId(req),
+            runId: requestToRunId(req)
           };
           try {
             const encoder = new TextEncoder();