@mozaik-ai/core 3.8.4 → 3.8.6

package/README.md

@@ -93,12 +93,25 @@ The environment fans every item out to every subscriber synchronously and withou
 
 ---
 
-## Agent Loop Implementation
+## Reactive agent
 
-The easiest way to build **and control** an agent loop is to override three handlers on `BaseAgentParticipant`:
+A reactive agent extends `BaseAgentParticipant` and overrides the handlers it wants to react on. Each handler is already a no-op in the base class, so only the relevant ones need bodies:
 
 ```ts
-export class CustomAgent extends BaseAgentParticipant {
+import {
+	BaseAgentParticipant,
+	Participant,
+	UserMessageItem,
+	FunctionCallItem,
+	AgenticEnvironment,
+	ModelContext,
+	GenerativeModel,
+	InputStream,
+	InferenceRunner,
+	FunctionCallRunner,
+} from "@mozaik-ai/core"
+
+export class ReactiveAgent extends BaseAgentParticipant {
 	constructor(
 		inputSource: InputStream,
 		inferenceRunner: InferenceRunner,
@@ -110,30 +123,48 @@ export class CustomAgent extends BaseAgentParticipant {
 		super(inputSource, inferenceRunner, functionCallRunner)
 	}
 
+	// A message from a human (or any other participant) → record it and think.
 	async onMessage(message: string): Promise<void> {
 		this.context.addContextItem(UserMessageItem.create(message))
 		this.runInference(this.environment, this.context, this.model)
 	}
 
+	// The agent just produced a function call → execute it.
 	async onFunctionCall(item: FunctionCallItem): Promise<void> {
 		this.context.addContextItem(item)
 		this.executeFunctionCall(this.environment, item)
 	}
 
+	// The tool just produced an output → feed it back and run inference again.
 	async onFunctionCallOutput(item: FunctionCallOutputItem): Promise<void> {
 		this.context.addContextItem(item)
 		this.runInference(this.environment, this.context, this.model)
 	}
+
+	// Keep the local context in sync with model-emitted reasoning and replies.
+	async onReasoning(item: ReasoningItem): Promise<void> {
+		this.context.addContextItem(item)
+	}
+
+	async onModelMessage(item: ModelMessageItem): Promise<void> {
+		this.context.addContextItem(item)
+	}
 }
 ```
 
+Three things to note:
+
+1. The split between self handlers and `onExternal*` handlers means a participant can encode "act on my own outputs" separately from "observe others", without inspecting `source` by hand.
+2. The agent never `await`s its own capability calls inside the handlers — those methods are non-blocking, so the environment keeps delivering events while inference and tool execution run in the background.
+3. Behaviors compose by **reaction**, not orchestration. Add a second agent that overrides `onExternalModelMessage` and you get a critique loop. Add a `TranscriptLogger` and you get a UI stream. Neither change touches the existing participants.
+
 ---
 
 ## Reacting to external events
 
 Participants can listen to external events and react by overriding methods like `onMessage`, `onExternalFunctionCall`, `onExternalFunctionCallOutput`, `onExternalReasoning`, and `onExternalModelMessage`.
 
-### Passive observer
+## Passive observer
 
 You can create observers that don't run inference themselves but watch what's happening in the conversation and take side actions (logging, metrics, persistence, etc.). Subclass `Participant` and override only the handlers you care about:
 
@@ -169,71 +200,6 @@ export class TranscriptLogger extends Participant {
 }
 ```
 
-### Reactive agent
-
-A reactive agent extends `BaseAgentParticipant` and overrides the handlers it wants to react on. Each handler is already a no-op in the base class, so only the relevant ones need bodies:
-
-```ts
-import {
-	BaseAgentParticipant,
-	Participant,
-	UserMessageItem,
-	FunctionCallItem,
-	AgenticEnvironment,
-	ModelContext,
-	GenerativeModel,
-	InputStream,
-	InferenceRunner,
-	FunctionCallRunner,
-} from "@mozaik-ai/core"
-
-export class ReactiveAgent extends BaseAgentParticipant {
-	constructor(
-		inputSource: InputStream,
-		inferenceRunner: InferenceRunner,
-		functionCallRunner: FunctionCallRunner,
-		private readonly environment: AgenticEnvironment,
-		private readonly context: ModelContext,
-		private readonly model: GenerativeModel,
-	) {
-		super(inputSource, inferenceRunner, functionCallRunner)
-	}
-
-	// A message from a human (or any other participant) → record it and think.
-	async onMessage(message: string): Promise<void> {
-		this.context.addContextItem(UserMessageItem.create(message))
-		this.runInference(this.environment, this.context, this.model)
-	}
-
-	// The agent just produced a function call → execute it.
-	async onFunctionCall(item: FunctionCallItem): Promise<void> {
-		this.context.addContextItem(item)
-		this.executeFunctionCall(this.environment, item)
-	}
-
-	// The tool just produced an output → feed it back and run inference again.
-	async onFunctionCallOutput(item: FunctionCallOutputItem): Promise<void> {
-		this.context.addContextItem(item)
-		this.runInference(this.environment, this.context, this.model)
-	}
-
-	// Keep the local context in sync with model-emitted reasoning and replies.
-	async onReasoning(item: ReasoningItem): Promise<void> {
-		this.context.addContextItem(item)
-	}
-
-	async onModelMessage(item: ModelMessageItem): Promise<void> {
-		this.context.addContextItem(item)
-	}
-}
-```
-
-Three things to note:
-
-1. The split between self handlers and `onExternal*` handlers means a participant can encode "act on my own outputs" separately from "observe others", without inspecting `source` by hand.
-2. The agent never `await`s its own capability calls inside the handlers — those methods are non-blocking, so the environment keeps delivering events while inference and tool execution run in the background.
-3. Behaviors compose by **reaction**, not orchestration. Add a second agent that overrides `onExternalModelMessage` and you get a critique loop. Add a `TranscriptLogger` and you get a UI stream. Neither change touches the existing participants.
-
 ---
 
 ## Context and models (reference)
@@ -264,51 +230,28 @@ const response = await runtime.infer(new InferenceRequest(new Gpt54(), context))
 
 ---
 
-## Advanced: overriding generators
+## Overriding Generators
 
-`BaseAgentParticipant` and `BaseHumanParticipant` are deliberately thin shells around three generator interfaces. Swap any of them to change _how_ events are produced without touching the environment, the participants, or any consumers.
+Mozaik uses generators for inference, function calls, and message streams — that's what lets the system emit events incrementally so participants can react to them as they arrive. Swap any generator to change _how_ events are produced.
 
 ### Custom `InputStream`
 
-An `InputStream` is the minimal text-source contract a participant uses to feed messages into the environment:
-
-```ts
-export interface InputStream {
-	stream(signal?: AbortSignal): AsyncIterable<string>
-}
-```
-
-Each yielded string is delivered to every other participant through `onMessage(message: string)`. This keeps the wire format dead simple: participants exchange text, and each one decides how to turn that text into a `ContextItem` for its own `ModelContext`.
-
 ```ts
 import { InputStream } from "@mozaik-ai/core"
 
-export class QueueInputStream implements InputStream {
-	private readonly queue: string[] = []
-	private resolveNext?: () => void
-
-	push(message: string) {
-		this.queue.push(message)
-		this.resolveNext?.()
-		this.resolveNext = undefined
-	}
-
-	async *stream(signal?: AbortSignal): AsyncIterable<string> {
-		while (!signal?.aborted) {
-			while (this.queue.length > 0) {
-				yield this.queue.shift()!
-			}
-			await new Promise<void>((resolve) => (this.resolveNext = resolve))
-		}
+export class HelloInputStream implements InputStream {
+	async *stream(): AsyncIterable<string> {
+		yield "Hello"
+		yield "World"
 	}
 }
 ```
 
-Use it for stdin, websockets, an HTTP queue, or anything that produces text over time. A reactive agent typically wraps the incoming string in a `UserMessageItem` inside `onMessage` before adding it to its `ModelContext` — see the [Reactive agent](#reactive-agent) example above.
+Each yielded string is delivered to other participants through `onMessage(message: string)`.
 
 ### Custom `InferenceRunner`
 
-Wrap any model runtime — including `OpenAIResponses` — and decide how its output becomes a stream of items. Here we expand a single `InferenceResponse` into per-item delivery:
+An `InferenceRunner` can yield `ReasoningItem`, `FunctionCallItem`, and `ModelMessageItem`.
 
 ```ts
 import {
@@ -336,11 +279,9 @@ export class OpenAIInferenceRunner implements InferenceRunner {
 }
 ```
 
-Replace the body with a streaming runtime and items will flow into the environment as soon as the model produces them.
-
 ### Custom `FunctionCallRunner`
 
-Resolve a `FunctionCallItem` against a tool registry and yield its output:
+A `FunctionCallRunner` can only produce `FunctionCallOutputItem`.
 
 ```ts
 import { FunctionCallRunner, FunctionCallItem, FunctionCallOutputItem, Tool } from "@mozaik-ai/core"
@@ -364,7 +305,7 @@ export class ToolRegistryFunctionCallRunner implements FunctionCallRunner {
 import { BaseAgentParticipant, AgenticEnvironment } from "@mozaik-ai/core"
 
 const agent = new BaseAgentParticipant(
-	new QueueInputStream(),
+	new HelloInputStream(),
 	new OpenAIInferenceRunner(),
 	new ToolRegistryFunctionCallRunner(tools),
 )
@@ -372,16 +313,41 @@ const agent = new BaseAgentParticipant(
 agent.join(new AgenticEnvironment())
 ```
 
-You now own input, inference, and tool execution end-to-end while keeping the same `Participant` contract — and any other participant in the environment can still observe and react to everything the agent emits.
-
 ---
 
 ## Made with Mozaik
 
 - **[baro](https://github.com/Lotus015/baro)** — a Claude agent orchestrator where ten specialized participants (planner, executors, reviewer, fixer, librarian, auditor, and more) work fully concurrently on the same goal, like a team collaborating in real time instead of a single agent doing everything alone.
 
+```mermaid
+flowchart LR
+    Conductor[Conductor] -->|"RunStart / LevelCompute / StorySpawn"| Bus(("Mozaik Bus"))
+    Factory[StoryFactory] -->|"spawn StoryAgent"| Bus
+    Story[StoryAgent] -->|"StoryResult / retries"| Bus
+    Librarian[Librarian] -->|"index exploration outputs"| Bus
+    Sentry[Sentry] -->|"flag file conflicts"| Bus
+    Critic[Critic] -->|"per-turn verdict"| Bus
+    Surgeon[Surgeon] -->|"emit ReplanItem"| Bus
+    Operator[Operator] -->|"bridge TUI commands"| Bus
+    Auditor[Auditor] -->|"write JSONL log"| Bus
+    Cartographer[Cartographer] -->|"emit UI frames"| Bus
+    Bus -->|"StorySpawnRequest"| Factory
+    Bus -->|"StoryResult / LevelCompleted"| Conductor
+    Bus -->|"tool calls"| Librarian
+    Bus -->|"Edit/Write calls"| Sentry
+    Bus -->|"agent turns"| Critic
+    Bus -->|"terminal failure"| Surgeon
+    Bus -->|"user input"| Operator
+    Bus -->|"all events"| Auditor
+    Bus -->|"all events"| Cartographer
+```
+
 ---
 
+## Contributing
+
+Contributions are welcome. Please read the [Contributing Guidelines](./CONTRIBUTING.md) before opening an issue or pull request.
+
 ## Author & License
 
 Created by the [JigJoy](https://jigjoy.io) team.  

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mozaik-ai/core",
-	"version": "3.8.4",
+	"version": "3.8.6",
 	"description": "A TypeScript framework for building reactive agents",
 	"main": "dist/index.js",
 	"module": "dist/index.mjs",
@@ -36,11 +36,13 @@
 	"keywords": [
 		"agentic-environment",
 		"reactive-agents",
+		"collaborative-agents",
 		"non-blocking agents",
 		"event-driven agents",
 		"ai-infrastructure",
 		"ai-developer-tools",
 		"context-management",
+		"agent-swarms",
 		"llm-framework",
 		"openai",
 		"typescript framework"