@mozaik-ai/core 4.0.0-beta.6 → 4.0.0-beta.8

package/README.md

@@ -1,15 +1,23 @@
 <div align="center">
 <h1>Mozaik</h1>
-<p>TypeScript runtime for concurrent AI agents</p>
-
-<img width="150" height="150" alt="mozaik-avatar-dark" src="https://github.com/user-attachments/assets/e832c359-0581-42f7-96f3-d6e221c5af95" />
+<p>Mozaik is a TypeScript runtime for interoperable AI agents.</p>
 
 ![npm downloads](https://img.shields.io/npm/dt/@mozaik-ai/core) ![npm downloads weekly](https://img.shields.io/npm/dw/@mozaik-ai/core) ![npm version](https://img.shields.io/npm/v/@mozaik-ai/core)
 
-Mozaik is a TypeScript runtime for non-blocking AI agents that work independently, communicate through semantic events, and coordinate without predefined workflows.
+<img width="512" height="512" alt="agent-interoperability" src="https://github.com/user-attachments/assets/4b24bf27-afe2-4520-a396-5c46da6dab17" />
 
 </div>
 
+## Agent Interoperability
+
+Our main goal is to unlock agent interoperability across projects, so Mozaik is built around three core attributes:
+
+- **Concurrency** - Agents work independently without blocking one another.
+- **Awareness** - Agents understand other participants, events, and their shared environment.
+- **Adaptivity** - Agents change their behavior based on runtime state and emerging needs.
+
+Together, these capabilities free AI agents from specific harnesses, allowing them to work across projects - so every newly created agent adds value to the entire ecosystem.
+
 ---
 
 ## Installation

package/dist/index.d.mts

@@ -129,6 +129,46 @@ interface FunctionTool {
 }
 type Tool = FunctionTool;
 
+type SituationContext$1<TEvent extends SemanticEvent = SemanticEvent> = {
+    readonly event: TEvent;
+    readonly participant: Participant;
+};
+declare abstract class SituationSpecification<TEvent extends SemanticEvent = SemanticEvent> {
+    abstract isSatisfiedBy(situationContext: SituationContext$1<TEvent>): boolean;
+    and(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
+    or(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
+    not(): SituationSpecification<TEvent>;
+}
+
+interface SituationHandler {
+    readonly specification: SituationSpecification;
+    readonly processor: SituationProcessor;
+}
+type SituationContext<TEvent extends SemanticEvent = SemanticEvent> = {
+    readonly event: TEvent;
+    readonly participant: Participant;
+};
+interface SituationProcessor {
+    apply(context: SituationContext): void | Promise<void>;
+}
+
+type ParticipantRole = "agent" | "human";
+type ParticipantManifest = {
+    readonly id: string;
+    readonly name: string;
+    readonly role: ParticipantRole;
+    readonly capabilities?: readonly string[];
+};
+declare abstract class Participant {
+    private readonly manifest;
+    private handlers;
+    protected constructor(manifest: ParticipantManifest, handlers: SituationHandler[]);
+    getManifest(): ParticipantManifest;
+    getId(): string;
+    getHandlers(): SituationHandler[];
+    setHandlers(handlers: SituationHandler[]): void;
+}
+
 declare class SemanticEvent<TType extends string = string, TPayload = unknown> {
     readonly type: TType;
     readonly producerId: string;
@@ -141,6 +181,71 @@ declare class SemanticEvent<TType extends string = string, TPayload = unknown> {
 interface FunctionCallRunner {
     run(call: FunctionCallItem, tool: Tool): Promise<FunctionCallOutputItem>;
 }
+interface FunctionCallParams {
+    call: FunctionCallItem;
+    inferenceInput: InferenceInput;
+}
+
+type LoopStateId = "context_update" | "inference" | "inference_streaming" | "function_call" | "model_message" | "idle";
+type ReceivedMessage = {
+    content: string;
+    input: InferenceInput;
+};
+interface FunctionCallExecutionOutput {
+    item: FunctionCallOutputItem;
+}
+interface ModelMessageParams {
+    answer: ModelMessageItem;
+}
+interface LoopStateContract {
+    context_update: {
+        input: ReceivedMessage;
+        output: InferenceInput;
+    };
+    inference: {
+        input: InferenceInput;
+        output: InferenceOutput;
+    };
+    inference_streaming: {
+        input: InferenceInput;
+        output: InferenceOutput;
+    };
+    function_call: {
+        input: FunctionCallParams;
+        output: FunctionCallExecutionOutput;
+    };
+    model_message: {
+        input: ModelMessageParams;
+        output: void;
+    };
+    interception: {
+        input: InterceptionParams;
+        output: InterceptionOutput;
+    };
+    idle: {
+        input: undefined;
+        output: void;
+    };
+}
+type InterceptionOutput = {
+    type: "continue";
+    transition: LoopTransition;
+} | {
+    type: "pause";
+    pendingTransition: LoopTransition;
+} | {
+    type: "stop";
+    reason?: string;
+};
+interface InterceptionParams {
+    pendingTransition: LoopTransition;
+}
+type LoopTransition<TStateId extends LoopStateId = LoopStateId> = {
+    [K in TStateId]: {
+        nextStateId: K;
+        input: LoopStateContract[K]["input"];
+    };
+}[TStateId];
 
 type InferenceInput = {
     model: string;
@@ -299,46 +404,6 @@ declare class SystemMessageItem extends ContextItem {
     }): SystemMessageItem;
 }
 
-type SituationContext$1<TEvent extends SemanticEvent = SemanticEvent> = {
-    readonly event: TEvent;
-    readonly participant: Participant;
-};
-declare abstract class SituationSpecification<TEvent extends SemanticEvent = SemanticEvent> {
-    abstract isSatisfiedBy(situationContext: SituationContext$1<TEvent>): boolean;
-    and(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
-    or(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
-    not(): SituationSpecification<TEvent>;
-}
-
-interface SituationHandler {
-    readonly specification: SituationSpecification;
-    readonly processor: SituationProcessor;
-}
-type SituationContext<TEvent extends SemanticEvent = SemanticEvent> = {
-    readonly event: TEvent;
-    readonly participant: Participant;
-};
-interface SituationProcessor {
-    apply(context: SituationContext): void | Promise<void>;
-}
-
-type ParticipantRole = "agent" | "human";
-type ParticipantManifest = {
-    readonly id: string;
-    readonly name: string;
-    readonly role: ParticipantRole;
-    readonly capabilities?: readonly string[];
-};
-declare abstract class Participant {
-    private readonly manifest;
-    private handlers;
-    protected constructor(manifest: ParticipantManifest, handlers: SituationHandler[]);
-    getManifest(): ParticipantManifest;
-    getId(): string;
-    getHandlers(): SituationHandler[];
-    setHandlers(handlers: SituationHandler[]): void;
-}
-
 declare class Memory {
     private readonly context;
     private constructor();
@@ -394,6 +459,11 @@ declare abstract class RuntimeState {
     getParticipants(): readonly Participant[];
 }
 
+interface InterceptionHandler {
+    isSatisfiedBy(transition: LoopTransition): boolean;
+    handle(transition: LoopTransition): Promise<LoopTransition>;
+}
+
 declare class EventProcessor {
     process(event: SemanticEvent, consumer: Participant): void;
 }
@@ -427,7 +497,7 @@ declare function defineRuntime<TRuntimeState extends RuntimeState>(): {
     leave: (participant: Participant) => void;
     sendMessage: (message: string, senderId: string) => void;
     sendEvent: (event: SemanticEvent, senderId: string) => void;
-    runLoop: (agentId: string, message: string, inferenceInput: InferenceInput) => void;
+    runLoop: (agentId: string, message: string, inferenceInput: InferenceInput, interceptionHandler: InterceptionHandler) => void;
 };
 
 declare const supportedModels: GenerativeModel[];

package/dist/index.d.ts

@@ -129,6 +129,46 @@ interface FunctionTool {
 }
 type Tool = FunctionTool;
 
+type SituationContext$1<TEvent extends SemanticEvent = SemanticEvent> = {
+    readonly event: TEvent;
+    readonly participant: Participant;
+};
+declare abstract class SituationSpecification<TEvent extends SemanticEvent = SemanticEvent> {
+    abstract isSatisfiedBy(situationContext: SituationContext$1<TEvent>): boolean;
+    and(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
+    or(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
+    not(): SituationSpecification<TEvent>;
+}
+
+interface SituationHandler {
+    readonly specification: SituationSpecification;
+    readonly processor: SituationProcessor;
+}
+type SituationContext<TEvent extends SemanticEvent = SemanticEvent> = {
+    readonly event: TEvent;
+    readonly participant: Participant;
+};
+interface SituationProcessor {
+    apply(context: SituationContext): void | Promise<void>;
+}
+
+type ParticipantRole = "agent" | "human";
+type ParticipantManifest = {
+    readonly id: string;
+    readonly name: string;
+    readonly role: ParticipantRole;
+    readonly capabilities?: readonly string[];
+};
+declare abstract class Participant {
+    private readonly manifest;
+    private handlers;
+    protected constructor(manifest: ParticipantManifest, handlers: SituationHandler[]);
+    getManifest(): ParticipantManifest;
+    getId(): string;
+    getHandlers(): SituationHandler[];
+    setHandlers(handlers: SituationHandler[]): void;
+}
+
 declare class SemanticEvent<TType extends string = string, TPayload = unknown> {
     readonly type: TType;
     readonly producerId: string;
@@ -141,6 +181,71 @@ declare class SemanticEvent<TType extends string = string, TPayload = unknown> {
 interface FunctionCallRunner {
     run(call: FunctionCallItem, tool: Tool): Promise<FunctionCallOutputItem>;
 }
+interface FunctionCallParams {
+    call: FunctionCallItem;
+    inferenceInput: InferenceInput;
+}
+
+type LoopStateId = "context_update" | "inference" | "inference_streaming" | "function_call" | "model_message" | "idle";
+type ReceivedMessage = {
+    content: string;
+    input: InferenceInput;
+};
+interface FunctionCallExecutionOutput {
+    item: FunctionCallOutputItem;
+}
+interface ModelMessageParams {
+    answer: ModelMessageItem;
+}
+interface LoopStateContract {
+    context_update: {
+        input: ReceivedMessage;
+        output: InferenceInput;
+    };
+    inference: {
+        input: InferenceInput;
+        output: InferenceOutput;
+    };
+    inference_streaming: {
+        input: InferenceInput;
+        output: InferenceOutput;
+    };
+    function_call: {
+        input: FunctionCallParams;
+        output: FunctionCallExecutionOutput;
+    };
+    model_message: {
+        input: ModelMessageParams;
+        output: void;
+    };
+    interception: {
+        input: InterceptionParams;
+        output: InterceptionOutput;
+    };
+    idle: {
+        input: undefined;
+        output: void;
+    };
+}
+type InterceptionOutput = {
+    type: "continue";
+    transition: LoopTransition;
+} | {
+    type: "pause";
+    pendingTransition: LoopTransition;
+} | {
+    type: "stop";
+    reason?: string;
+};
+interface InterceptionParams {
+    pendingTransition: LoopTransition;
+}
+type LoopTransition<TStateId extends LoopStateId = LoopStateId> = {
+    [K in TStateId]: {
+        nextStateId: K;
+        input: LoopStateContract[K]["input"];
+    };
+}[TStateId];
 
 type InferenceInput = {
     model: string;
@@ -299,46 +404,6 @@ declare class SystemMessageItem extends ContextItem {
     }): SystemMessageItem;
 }
 
-type SituationContext$1<TEvent extends SemanticEvent = SemanticEvent> = {
-    readonly event: TEvent;
-    readonly participant: Participant;
-};
-declare abstract class SituationSpecification<TEvent extends SemanticEvent = SemanticEvent> {
-    abstract isSatisfiedBy(situationContext: SituationContext$1<TEvent>): boolean;
-    and(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
-    or(other: SituationSpecification<TEvent>): SituationSpecification<TEvent>;
-    not(): SituationSpecification<TEvent>;
-}
-
-interface SituationHandler {
-    readonly specification: SituationSpecification;
-    readonly processor: SituationProcessor;
-}
-type SituationContext<TEvent extends SemanticEvent = SemanticEvent> = {
-    readonly event: TEvent;
-    readonly participant: Participant;
-};
-interface SituationProcessor {
-    apply(context: SituationContext): void | Promise<void>;
-}
-
-type ParticipantRole = "agent" | "human";
-type ParticipantManifest = {
-    readonly id: string;
-    readonly name: string;
-    readonly role: ParticipantRole;
-    readonly capabilities?: readonly string[];
-};
-declare abstract class Participant {
-    private readonly manifest;
-    private handlers;
-    protected constructor(manifest: ParticipantManifest, handlers: SituationHandler[]);
-    getManifest(): ParticipantManifest;
-    getId(): string;
-    getHandlers(): SituationHandler[];
-    setHandlers(handlers: SituationHandler[]): void;
-}
-
 declare class Memory {
     private readonly context;
     private constructor();
@@ -394,6 +459,11 @@ declare abstract class RuntimeState {
     getParticipants(): readonly Participant[];
 }
 
+interface InterceptionHandler {
+    isSatisfiedBy(transition: LoopTransition): boolean;
+    handle(transition: LoopTransition): Promise<LoopTransition>;
+}
+
 declare class EventProcessor {
     process(event: SemanticEvent, consumer: Participant): void;
 }
@@ -427,7 +497,7 @@ declare function defineRuntime<TRuntimeState extends RuntimeState>(): {
     leave: (participant: Participant) => void;
     sendMessage: (message: string, senderId: string) => void;
     sendEvent: (event: SemanticEvent, senderId: string) => void;
-    runLoop: (agentId: string, message: string, inferenceInput: InferenceInput) => void;
+    runLoop: (agentId: string, message: string, inferenceInput: InferenceInput, interceptionHandler: InterceptionHandler) => void;
 };
 
 declare const supportedModels: GenerativeModel[];

package/dist/index.js

@@ -378,6 +378,16 @@ var SemanticEvent = class _SemanticEvent {
     return new _SemanticEvent(type, producerId, occurredAt, payload);
   }
 };
+var ParticipantJoinedEvent = class extends SemanticEvent {
+  static init(manifest) {
+    return SemanticEvent.create("participant.joined", manifest.id, manifest);
+  }
+};
+var ParticipantLeftEvent = class extends SemanticEvent {
+  static init(manifest) {
+    return SemanticEvent.create("participant.left", manifest.id, manifest);
+  }
+};
 var MessageSentEvent = class extends SemanticEvent {
   static init(producerId, message) {
     return SemanticEvent.create("message.sent", producerId, { message });
@@ -536,9 +546,11 @@ var RuntimeService = class {
   }
   join(participant) {
     this.state.addParticipant(participant);
+    this.publish(ParticipantJoinedEvent.init(participant.getManifest()));
   }
   leave(participant) {
     this.state.removeParticipant(participant);
+    this.publish(ParticipantLeftEvent.init(participant.getManifest()));
   }
   publish(event) {
     for (const participant of this.state.getParticipants()) {
@@ -602,28 +614,43 @@ function createSendMessage(resolveRuntime) {
 }
 
 // src/domain/agentic-environment/loop/agent-loop.ts
-var AgentLoop = class {
-  constructor(stateExecutor, transitionResolver, loopVisitor) {
+var AgentLoop = class _AgentLoop {
+  constructor(loopId, stateExecutor, transitionResolver, interceptionHandler) {
+    this.loopId = loopId;
     this.stateExecutor = stateExecutor;
     this.transitionResolver = transitionResolver;
-    this.loopVisitor = loopVisitor;
+    this.interceptionHandler = interceptionHandler;
   }
-  async run(message) {
+  async run(message, loopVisitor) {
     let transition = {
-      nextStateId: "context_preparation",
+      nextStateId: "context_update",
       input: message
     };
     while (transition.nextStateId !== "idle") {
-      const execution = await this.stateExecutor.execute(transition, this.loopVisitor);
-      transition = this.transitionResolver.resolve(execution);
+      const isInterceptionSatisfied = this.interceptionHandler.isSatisfiedBy(transition);
+      if (isInterceptionSatisfied) {
+        loopVisitor.visitInterceptionStarted(transition);
+        transition = await this.interceptionHandler.handle(transition);
+        loopVisitor.visitInterceptionFinished(transition);
+      } else {
+        const execution = await this.stateExecutor.execute(transition, loopVisitor);
+        transition = this.transitionResolver.resolve(execution);
+      }
     }
   }
+  getLoopId() {
+    return this.loopId;
+  }
+  static create(stateExecutor, transitionResolver, interceptionHandler) {
+    const loopId = crypto.randomUUID();
+    return new _AgentLoop(loopId, stateExecutor, transitionResolver, interceptionHandler);
+  }
 };
 
 // src/domain/agentic-environment/loop/state-executor.ts
 var LoopStateExecutor = class {
-  constructor(contextPreparationState, inferenceState, inferenceStreamingState, functionCallState, modelMessageState) {
-    this.contextPreparationState = contextPreparationState;
+  constructor(contextUpdateState, inferenceState, inferenceStreamingState, functionCallState, modelMessageState) {
+    this.contextUpdateState = contextUpdateState;
     this.inferenceState = inferenceState;
     this.inferenceStreamingState = inferenceStreamingState;
     this.functionCallState = functionCallState;
@@ -631,8 +658,8 @@ var LoopStateExecutor = class {
   }
   async execute(transition, loopVisitor) {
     switch (transition.nextStateId) {
-      case "context_preparation":
-        return await this.contextPreparationState.run(transition.input, loopVisitor);
+      case "context_update":
+        return await this.contextUpdateState.run(transition.input, loopVisitor);
       case "inference":
         return await this.inferenceState.run(transition.input, loopVisitor);
       case "inference_streaming":
@@ -677,19 +704,19 @@ var FunctionCallState = class {
   }
 };
 
-// src/application/states/context-preparation.ts
-var ContextPreparationState = class {
+// src/application/states/context-update.ts
+var ContextUpdateState = class {
   constructor() {
-    this.id = "context_preparation";
+    this.id = "context_update";
   }
   async run(input, loopVisitor) {
-    loopVisitor.visitContextPreparationStarted(input);
+    loopVisitor.visitContextUpdateStarted(input);
     const userMessage = UserMessageItem.create(input.content);
     const output = {
       ...input.input,
       context: input.input.context.addContextItems([userMessage])
     };
-    loopVisitor.visitContextPreparationCompleted(output);
+    loopVisitor.visitContextUpdateCompleted(output);
     return {
       stateId: this.id,
       input,
@@ -730,7 +757,7 @@ var TransitionResolver = class {
 // src/domain/agentic-environment/loop/transition-specification.ts
 var MessageReceivedSpecification = class {
   isSatisfiedBy(execution) {
-    return execution.stateId === "context_preparation";
+    return execution.stateId === "context_update";
   }
 };
 function isInferenceExecution(execution) {
@@ -763,7 +790,7 @@ var ContextPreparationToInferenceRule = class {
     this.specification = new MessageReceivedSpecification();
   }
   createTransition(execution) {
-    if (execution.stateId !== "context_preparation") {
+    if (execution.stateId !== "context_update") {
       throw new Error("Expected context_preparation execution");
     }
     const nextStateId = execution.output.streaming ? "inference_streaming" : "inference";
@@ -851,15 +878,16 @@ var ModelMessageToIdleRule = class {
 
 // src/domain/agentic-environment/loop/event-publisher-visitor.ts
 var EventPublisherLoopVisitor = class {
-  constructor(agentId, runtime) {
+  constructor(agentId, loopId, runtime) {
     this.agentId = agentId;
+    this.loopId = loopId;
     this.runtime = runtime;
   }
-  visitContextPreparationStarted(input) {
-    this.publish("context_preparation.started", input);
+  visitContextUpdateStarted(input) {
+    this.publish("context_update.started", { ...input, loopId: this.loopId });
   }
-  visitContextPreparationCompleted(output) {
-    this.publish("context_preparation.completed", output);
+  visitContextUpdateCompleted(output) {
+    this.publish("context_update.completed", { ...output, loopId: this.loopId });
   }
   visitInferenceStarted(input) {
     this.publish("inference.started", input);
@@ -879,12 +907,18 @@ var EventPublisherLoopVisitor = class {
   visitModelAnswer(input) {
     this.publish("model.answer", input);
   }
+  visitInterceptionStarted(transition) {
+    this.publish("interception.started", transition);
+  }
+  visitInterceptionFinished(transition) {
+    this.publish("interception.finished", transition);
+  }
   publish(type, payload) {
     this.runtime.publish({
       type,
       producerId: this.agentId,
       occurredAt: /* @__PURE__ */ new Date(),
-      payload
+      payload: { ...payload, loopId: this.loopId }
     });
   }
 };
@@ -918,7 +952,7 @@ var InferenceStreamingState = class {
 
 // src/application/use-cases/run-loop.ts
 function createRunLoop(resolveRuntime) {
-  return function runLoop(agentId, message, inferenceInput) {
+  return function runLoop(agentId, message, inferenceInput, interceptionHandler) {
     const runtime = resolveRuntime();
     const inferenceRunner = runtime.getInferenceRunner();
     const functionCallRunner = runtime.getFunctionCallRunner();
@@ -931,21 +965,21 @@ function createRunLoop(resolveRuntime) {
       new ModelMessageToIdleRule()
     ]);
     const stateExecutor = new LoopStateExecutor(
-      new ContextPreparationState(),
+      new ContextUpdateState(),
       new InferenceState(inferenceRunner),
       new InferenceStreamingState(inferenceRunner),
       new FunctionCallState(functionCallRunner),
       new ModelMessageState()
     );
-    const agentLoop = new AgentLoop(
-      stateExecutor,
-      transitionResolver,
-      new EventPublisherLoopVisitor(agentId, runtime)
+    const agentLoop = AgentLoop.create(stateExecutor, transitionResolver, interceptionHandler);
+    const loopVisitor = new EventPublisherLoopVisitor(agentId, agentLoop.getLoopId(), runtime);
+    agentLoop.run(
+      {
+        content: message,
+        input: inferenceInput
+      },
+      loopVisitor
     );
-    agentLoop.run({
-      content: message,
-      input: inferenceInput
-    });
   };
 }