@deepstrike/sdk 0.2.30 → 0.2.32

package/dist/providers/qwen.js

@@ -1,54 +1,29 @@
-import OpenAI from "openai";
-import { withServerRuntimeGuard } from "../runtime/server.js";
-import { AnthropicProvider } from "./anthropic.js";
-import { CircuitBreaker, omitExtensionKeys, openAICachedPromptTokens } from "./base.js";
-import { OpenAIChatAdapter } from "./openai-chat.js";
+import { OpenAIChatProvider } from "./openai.js";
+import { AnthropicCompatibleProvider } from "./anthropic-compatible.js";
+import { omitExtensionKeys } from "./base.js";
 import { endpointProfiles } from "./profiles.js";
-const QWEN_POLICIES = {
-    "qwen3.7-max-preview": { maxTurns: 45 },
-    "qwen3.7-plus-preview": { maxTurns: 40 },
-    "qwen3.6-max-preview": { maxTurns: 40 },
-    "qwen3.6-plus": { maxTurns: 35 },
-    "qwen3.6-flash": { maxTurns: 20 },
-    "qwen3.6-35b-a3b": { maxTurns: 25 },
-    "qwen3.6-27b": { maxTurns: 25 },
-    "qwen3.5-plus": { maxTurns: 35 },
-    "qwen3.5-flash": { maxTurns: 20 },
-    "qwen3.5-397b-a17b": { maxTurns: 35 },
-    "qwen3.5-122b-a10b": { maxTurns: 25 },
-    "qwen3.5-35b-a3b": { maxTurns: 20 },
-    "qwen3.5-27b": { maxTurns: 20 },
-};
+import { QWEN_POLICIES, anthropicVendorProfiles } from "./vendor-profiles.js";
 /**
  * Qwen over its Anthropic-compatible endpoint.
+ * @deprecated Prefer `qwen({ protocol: "anthropic" })`. Behavior is now fully
+ * data-driven via `anthropicVendorProfiles.qwen`; this thin shim is kept for
+ * backward compatibility and `instanceof` checks.
  */
-export class QwenAnthropicProvider extends AnthropicProvider {
-    constructor(apiKey, model = "qwen3.6-plus", retry, baseURL = endpointProfiles["qwen.anthropic"].baseURL) {
-        super(apiKey, model, retry, {
-            baseURL,
-            authMode: "api-key",
-        });
-    }
-    providerName() {
-        return "qwen";
-    }
-    runtimePolicy() {
-        return QWEN_POLICIES[this.model] ?? {};
+export class QwenAnthropicProvider extends AnthropicCompatibleProvider {
+    constructor(apiKey, model, retry, baseURL) {
+        super(anthropicVendorProfiles.qwen, apiKey, model, retry, baseURL);
     }
 }
-export class QwenProvider {
-    model;
-    client;
-    circuit;
-    maxRetries;
-    baseDelay;
-    chat = new OpenAIChatAdapter();
-    constructor(apiKey, model = "qwen3.6-plus", retry = { maxRetries: 3, baseDelay: 1000 }, baseURL = endpointProfiles["qwen.dashscope"].baseURL) {
-        this.model = model;
-        this.client = withServerRuntimeGuard(() => new OpenAI({ apiKey, baseURL }));
-        this.circuit = new CircuitBreaker();
-        this.maxRetries = retry.maxRetries;
-        this.baseDelay = retry.baseDelay;
+/**
+ * Qwen / DashScope over its OpenAI-compatible (DashScope) endpoint. Reasoning is carried
+ * out-of-band as `reasoning_content`; thinking is opted into via `enable_thinking` /
+ * `thinking_budget` (sent under `extra_body`). The streaming / tool-call machinery and the
+ * default `{ reasoning_content }` replay are inherited from OpenAIChatProvider; only request
+ * shaping and the (string-coerced) replay peek differ, supplied via the Template-Method hooks.
+ */
+export class QwenProvider extends OpenAIChatProvider {
+    constructor(apiKey, model = "qwen3.6-plus", retry, baseURL = endpointProfiles["qwen.dashscope"].baseURL) {
+        super(apiKey, model, retry, baseURL);
     }
     runtimePolicy() {
         return QWEN_POLICIES[this.model] ?? {};
@@ -68,8 +43,35 @@ export class QwenProvider {
             },
         };
     }
-    buildChatMessages(context) {
-        return this.chat.buildMessages(context, { descriptor: this.descriptor() });
+    // DashScope auto prefix-caches and does not accept OpenAI's `prompt_cache_key`; omit it.
+    cacheKeyParams() {
+        return {};
+    }
+    // Reasoning arrives out-of-band as `reasoning_content`, never as inline <thinking> tags.
+    usesInlineThinkingTags() {
+        return false;
+    }
+    requestBodyExtras(extensions) {
+        // DashScope vendor knobs travel under `extra_body` in OpenAI-compat mode: thinking + web search.
+        const extraBody = { ...this.thinkingExtraBody(extensions), ...this.searchExtraBody(extensions) };
+        return Object.keys(extraBody).length ? { extra_body: extraBody } : {};
+    }
+    requestExtensions(extensions) {
+        return omitExtensionKeys(extensions, [
+            "model", "messages", "tools", "stream", "stream_options", "extra_body",
+            "enableThinking", "enable_thinking", "thinkingBudget", "thinking_budget",
+            "enable_search", "search_options",
+        ]);
+    }
+    // DashScope web search (Qwen vendor feature): `extensions={ enable_search: true }` + optional
+    // `search_options` (forced_search / search_strategy / enable_citation …). Mirrors the Python provider.
+    searchExtraBody(extensions) {
+        if (!extensions?.enable_search)
+            return {};
+        return {
+            enable_search: true,
+            ...(extensions.search_options != null ? { search_options: extensions.search_options } : {}),
+        };
     }
     peekProviderReplay(message) {
         const fields = this.chat.peekReplayFields(message);
@@ -82,129 +84,6 @@ export class QwenProvider {
             this.chat.rememberReplayFields(message, { reasoning_content: replay.reasoning_content });
         }
     }
-    async complete(context, tools, extensions) {
-        if (this.circuit.isOpen())
-            throw new Error("Circuit breaker open");
-        const msgs = this.buildChatMessages(context);
-        const extraBody = this.thinkingExtraBody(extensions);
-        let lastErr;
-        for (let i = 0; i < this.maxRetries; i++) {
-            try {
-                const resp = await this.client.chat.completions.create({
-                    ...this.requestExtensions(extensions),
-                    model: this.model,
-                    messages: msgs,
-                    ...(tools.length ? { tools: this.chat.buildTools(tools) } : {}),
-                    ...(extraBody ? { extra_body: extraBody } : {}),
-                });
-                this.circuit.recordSuccess();
-                const choice = resp.choices[0].message;
-                const toolCalls = this.chat.normalizeToolCalls(choice.tool_calls ?? []);
-                return { role: "assistant", content: choice.content ?? "", tokenCount: resp.usage?.completion_tokens ?? resp.usage?.total_tokens, toolCalls };
-            }
-            catch (err) {
-                lastErr = err;
-                this.circuit.recordFailure();
-                if (i < this.maxRetries - 1)
-                    await new Promise(r => setTimeout(r, this.baseDelay * 2 ** i));
-            }
-        }
-        throw lastErr;
-    }
-    async *stream(context, tools, extensions) {
-        const msgs = this.buildChatMessages(context);
-        const toolCallBufs = {};
-        const emittedToolCallIndexes = new Set();
-        let reasoningContent = "";
-        let finalText = "";
-        const extraBody = this.thinkingExtraBody(extensions);
-        const stream = await this.client.chat.completions.create({
-            ...this.requestExtensions(extensions),
-            model: this.model,
-            messages: msgs,
-            ...(tools.length ? { tools: this.chat.buildTools(tools) } : {}),
-            stream: true,
-            stream_options: { include_usage: true },
-            ...(extraBody ? { extra_body: extraBody } : {}),
-        });
-        let totalTokens = 0;
-        let inputTokens = 0;
-        let outputTokens = 0;
-        let cacheReadTokens = 0;
-        for await (const chunk of stream) {
-            if (chunk.usage) {
-                totalTokens = chunk.usage.total_tokens;
-                inputTokens = chunk.usage.prompt_tokens ?? 0;
-                outputTokens = chunk.usage.completion_tokens ?? 0;
-                cacheReadTokens = openAICachedPromptTokens(chunk.usage);
-                continue;
-            }
-            const choice = chunk.choices[0];
-            if (!choice)
-                continue;
-            const delta = choice.delta;
-            if (!delta)
-                continue;
-            if (delta.reasoning_content) {
-                reasoningContent += String(delta.reasoning_content);
-                yield { type: "thinking_delta", delta: delta.reasoning_content };
-            }
-            if (delta.content) {
-                finalText += String(delta.content);
-                yield { type: "text_delta", delta: delta.content };
-            }
-            for (const tc of delta.tool_calls ?? []) {
-                const idx = tc.index;
-                if (!toolCallBufs[idx])
-                    toolCallBufs[idx] = { id: tc.id ?? "", name: "", argsBuf: "" };
-                if (tc.function?.name)
-                    toolCallBufs[idx].name += tc.function.name;
-                toolCallBufs[idx].argsBuf += tc.function?.arguments ?? "";
-            }
-            if (choice.finish_reason === "tool_calls") {
-                const toolCalls = Object.values(toolCallBufs).map(tb => ({
-                    id: tb.id, name: tb.name, arguments: tb.argsBuf || "{}",
-                }));
-                this.chat.rememberReplayFields({ content: finalText, toolCalls }, { reasoning_content: reasoningContent });
-                for (const [index, tb] of Object.entries(toolCallBufs)) {
-                    const idx = Number(index);
-                    if (emittedToolCallIndexes.has(idx))
-                        continue;
-                    let args = {};
-                    try {
-                        args = JSON.parse(tb.argsBuf || "{}");
-                    }
-                    catch {
-                        args = {};
-                    }
-                    emittedToolCallIndexes.add(idx);
-                    yield { type: "tool_call", id: tb.id, name: tb.name, arguments: args };
-                }
-            }
-        }
-        const toolCalls = Object.values(toolCallBufs).map(tb => ({
-            id: tb.id, name: tb.name, arguments: tb.argsBuf || "{}",
-        }));
-        if (toolCalls.length || reasoningContent) {
-            this.chat.rememberReplayFields({ content: finalText, toolCalls }, { reasoning_content: reasoningContent });
-        }
-        for (const [index, tb] of Object.entries(toolCallBufs)) {
-            const idx = Number(index);
-            if (emittedToolCallIndexes.has(idx))
-                continue;
-            let args = {};
-            try {
-                args = JSON.parse(tb.argsBuf || "{}");
-            }
-            catch {
-                args = {};
-            }
-            emittedToolCallIndexes.add(idx);
-            yield { type: "tool_call", id: tb.id, name: tb.name, arguments: args };
-        }
-        if (totalTokens > 0)
-            yield { type: "usage", totalTokens, inputTokens, outputTokens, ...(cacheReadTokens > 0 ? { cacheReadInputTokens: cacheReadTokens } : {}) };
-    }
     thinkingExtraBody(extensions) {
         const enableThinking = Boolean(extensions?.enableThinking ?? extensions?.enable_thinking);
         const thinkingBudget = extensions?.thinkingBudget ?? extensions?.thinking_budget;
@@ -215,10 +94,4 @@ export class QwenProvider {
             ...(typeof thinkingBudget === "number" ? { thinking_budget: thinkingBudget } : {}),
         };
     }
-    requestExtensions(extensions) {
-        return omitExtensionKeys(extensions, [
-            "model", "messages", "tools", "stream", "stream_options", "extra_body",
-            "enableThinking", "enable_thinking", "thinkingBudget", "thinking_budget",
-        ]);
-    }
 }

package/dist/providers/registry.d.ts

@@ -0,0 +1,18 @@
+import type { LLMProvider } from "../types.js";
+export type ProviderRetry = {
+    maxRetries: number;
+    baseDelay: number;
+};
+/** Constructs a provider for one `(providerId, endpointProtocol)` pair. The lambda absorbs the
+ *  per-class constructor-shape differences (e.g. AnthropicProvider takes a `{ baseURL }` options
+ *  object, the rest take a positional `baseURL` string). */
+export type ProviderMaker = (apiKey: string, model: string | undefined, retry: ProviderRetry | undefined, baseURL: string | undefined) => LLMProvider;
+/** Build the registry key for a `(providerId, endpointProtocol)` pair. */
+export declare function providerRegistryKey(providerId: string, protocol: string): string;
+/**
+ * Single source of truth for which provider class backs each `(vendor, wire)` pair. Consumed by
+ * both `createProvider` (catalog) and the per-backend factory functions, so the two can no longer
+ * drift. Adding a vendor/wire = add a row here (+ its `vendor-profiles` / `endpointProfiles` data) —
+ * no dispatch branch to edit. Values are the same named classes as before, so `instanceof` holds.
+ */
+export declare const PROVIDER_REGISTRY: Record<string, ProviderMaker>;

package/dist/providers/registry.js

@@ -0,0 +1,35 @@
+import { AnthropicProvider } from "./anthropic.js";
+import { OpenAIChatProvider } from "./openai.js";
+import { OpenAIResponsesProvider } from "./openai-responses.js";
+import { DeepSeekProvider, DeepSeekAnthropicProvider } from "./deepseek.js";
+import { KimiProvider, KimiAnthropicProvider } from "./kimi.js";
+import { QwenProvider, QwenAnthropicProvider } from "./qwen.js";
+import { GLMProvider, GLMAnthropicProvider } from "./glm.js";
+import { MiniMaxOpenAIProvider, MiniMaxAnthropicProvider } from "./minimax.js";
+import { GeminiProvider } from "./gemini.js";
+/** Build the registry key for a `(providerId, endpointProtocol)` pair. */
+export function providerRegistryKey(providerId, protocol) {
+    return `${providerId}:${protocol}`;
+}
+/**
+ * Single source of truth for which provider class backs each `(vendor, wire)` pair. Consumed by
+ * both `createProvider` (catalog) and the per-backend factory functions, so the two can no longer
+ * drift. Adding a vendor/wire = add a row here (+ its `vendor-profiles` / `endpointProfiles` data) —
+ * no dispatch branch to edit. Values are the same named classes as before, so `instanceof` holds.
+ */
+export const PROVIDER_REGISTRY = {
+    "anthropic:anthropic-messages": (k, m, r, b) => new AnthropicProvider(k, m, r, { baseURL: b }),
+    "openai:openai-chat": (k, m, r, b) => new OpenAIChatProvider(k, m, r, b),
+    "openai:openai-responses": (k, m, r, b) => new OpenAIResponsesProvider(k, m, r, b),
+    "deepseek:openai-chat": (k, m, r, b) => new DeepSeekProvider(k, m, r, b),
+    "deepseek:anthropic-messages": (k, m, r, b) => new DeepSeekAnthropicProvider(k, m, r, b),
+    "kimi:openai-chat": (k, m, r, b) => new KimiProvider(k, m, r, b),
+    "kimi:anthropic-messages": (k, m, r, b) => new KimiAnthropicProvider(k, m, r, b),
+    "qwen:openai-chat": (k, m, r, b) => new QwenProvider(k, m, r, b),
+    "qwen:anthropic-messages": (k, m, r, b) => new QwenAnthropicProvider(k, m, r, b),
+    "glm:openai-chat": (k, m, r, b) => new GLMProvider(k, m, r, b),
+    "glm:anthropic-messages": (k, m, r, b) => new GLMAnthropicProvider(k, m, r, b),
+    "minimax:openai-chat": (k, m, r, b) => new MiniMaxOpenAIProvider(k, m, r, b),
+    "minimax:anthropic-messages": (k, m, r, b) => new MiniMaxAnthropicProvider(k, m, r, b),
+    "gemini:gemini": (k, m, r, b) => new GeminiProvider(k, m, r, b),
+};

package/dist/providers/vendor-profiles.d.ts

@@ -0,0 +1,54 @@
+import type { RuntimePolicy } from "../types.js";
+import { endpointProfiles } from "./profiles.js";
+import type { ProviderId } from "./profiles.js";
+export type EndpointProfileKey = keyof typeof endpointProfiles;
+export interface AnthropicVendorProfile {
+    /** Identity advertised in `descriptor().provider`. */
+    providerId: ProviderId;
+    /** Model used when the caller does not pass one. */
+    defaultModel: string;
+    /** Endpoint profile whose `baseURL` is the Anthropic-compatible wire for this vendor. */
+    baseURLProfileKey: EndpointProfileKey;
+    /** Recommended `maxTurns` per model id; missing model → empty policy. */
+    policies: Record<string, RuntimePolicy>;
+}
+export declare const DEEPSEEK_POLICIES: Record<string, RuntimePolicy>;
+export declare const KIMI_POLICIES: Record<string, RuntimePolicy>;
+export declare const QWEN_POLICIES: Record<string, RuntimePolicy>;
+export declare const GLM_POLICIES: Record<string, RuntimePolicy>;
+export declare const MINIMAX_POLICIES: Record<string, RuntimePolicy>;
+export declare const anthropicVendorProfiles: {
+    deepseek: {
+        providerId: "deepseek";
+        defaultModel: string;
+        baseURLProfileKey: "deepseek.anthropic";
+        policies: Record<string, RuntimePolicy>;
+    };
+    kimi: {
+        providerId: "kimi";
+        defaultModel: string;
+        baseURLProfileKey: "kimi.anthropic";
+        policies: Record<string, RuntimePolicy>;
+    };
+    qwen: {
+        providerId: "qwen";
+        defaultModel: string;
+        baseURLProfileKey: "qwen.anthropic";
+        policies: Record<string, RuntimePolicy>;
+    };
+    glm: {
+        providerId: "glm";
+        defaultModel: string;
+        baseURLProfileKey: "glm.anthropic";
+        policies: Record<string, RuntimePolicy>;
+    };
+    minimax: {
+        providerId: "minimax";
+        defaultModel: string;
+        baseURLProfileKey: "minimax.anthropic";
+        policies: Record<string, RuntimePolicy>;
+    };
+};
+export type AnthropicVendorId = keyof typeof anthropicVendorProfiles;
+/** Resolve the Anthropic-compatible base URL for a vendor profile. */
+export declare function anthropicVendorBaseURL(profile: AnthropicVendorProfile): string;

package/dist/providers/vendor-profiles.js

@@ -0,0 +1,66 @@
+import { endpointProfiles } from "./profiles.js";
+export const DEEPSEEK_POLICIES = {
+    "deepseek-chat": { maxTurns: 25 },
+    "deepseek-reasoner": { maxTurns: 50 },
+    "deepseek-v4-flash": { maxTurns: 20 },
+    "deepseek-v4-pro": { maxTurns: 35 },
+};
+export const KIMI_POLICIES = {
+    "moonshot-v1-8k": { maxTurns: 15 },
+    "moonshot-v1-32k": { maxTurns: 20 },
+    "moonshot-v1-128k": { maxTurns: 30 },
+    "kimi-k2.5": { maxTurns: 30 },
+    "kimi-k2.6": { maxTurns: 35 },
+    "kimi-k2-thinking": { maxTurns: 50 },
+    "kimi-k2-thinking-turbo": { maxTurns: 40 },
+};
+export const QWEN_POLICIES = {
+    "qwen3.7-max-preview": { maxTurns: 45 },
+    "qwen3.7-plus-preview": { maxTurns: 40 },
+    "qwen3.6-max-preview": { maxTurns: 40 },
+    "qwen3.6-plus": { maxTurns: 35 },
+    "qwen3.6-flash": { maxTurns: 20 },
+    "qwen3.6-35b-a3b": { maxTurns: 25 },
+    "qwen3.6-27b": { maxTurns: 25 },
+    "qwen3.5-plus": { maxTurns: 35 },
+    "qwen3.5-flash": { maxTurns: 20 },
+    "qwen3.5-397b-a17b": { maxTurns: 35 },
+    "qwen3.5-122b-a10b": { maxTurns: 25 },
+    "qwen3.5-35b-a3b": { maxTurns: 20 },
+    "qwen3.5-27b": { maxTurns: 20 },
+};
+export const GLM_POLICIES = {
+    "glm-5.2": { maxTurns: 50 },
+    "glm/glm-5.2": { maxTurns: 50 },
+    "glm-5.1": { maxTurns: 50 },
+    "glm/glm-5.1": { maxTurns: 50 },
+    "glm-4-plus": { maxTurns: 35 },
+    "glm/glm-4-plus": { maxTurns: 35 },
+    "glm-4-flash": { maxTurns: 15 },
+    "glm/glm-4-flash": { maxTurns: 15 },
+    "glm-4-air": { maxTurns: 20 },
+    "glm/glm-4-air": { maxTurns: 20 },
+};
+export const MINIMAX_POLICIES = {
+    "MiniMax-M3": { maxTurns: 35 },
+    "MiniMax-M3-highspeed": { maxTurns: 35 },
+    "MiniMax-M2.7": { maxTurns: 35 },
+    "MiniMax-M2.7-highspeed": { maxTurns: 35 },
+    "MiniMax-M2.5": { maxTurns: 25 },
+    "MiniMax-M2.5-highspeed": { maxTurns: 25 },
+    "MiniMax-M2.1": { maxTurns: 25 },
+    "MiniMax-M2.1-highspeed": { maxTurns: 25 },
+    "MiniMax-M2": { maxTurns: 20 },
+    "MiniMax-Text-01": { maxTurns: 20 },
+};
+export const anthropicVendorProfiles = {
+    deepseek: { providerId: "deepseek", defaultModel: "deepseek-v4-flash", baseURLProfileKey: "deepseek.anthropic", policies: DEEPSEEK_POLICIES },
+    kimi: { providerId: "kimi", defaultModel: "kimi-k2.6", baseURLProfileKey: "kimi.anthropic", policies: KIMI_POLICIES },
+    qwen: { providerId: "qwen", defaultModel: "qwen3.6-plus", baseURLProfileKey: "qwen.anthropic", policies: QWEN_POLICIES },
+    glm: { providerId: "glm", defaultModel: "glm-5.2", baseURLProfileKey: "glm.anthropic", policies: GLM_POLICIES },
+    minimax: { providerId: "minimax", defaultModel: "MiniMax-M3", baseURLProfileKey: "minimax.anthropic", policies: MINIMAX_POLICIES },
+};
+/** Resolve the Anthropic-compatible base URL for a vendor profile. */
+export function anthropicVendorBaseURL(profile) {
+    return endpointProfiles[profile.baseURLProfileKey].baseURL;
+}

package/dist/runtime/event-stream.d.ts

@@ -0,0 +1,44 @@
+/**
+ * L2 (Blackboard) — a shared, append-only event stream that N peer agent sessions of one logical run
+ * observe. This is the pluggable storage seam (like `SessionLog`): the default `InMemoryEventStream`
+ * is process-local; back it with Postgres/Redis to span replicas/restarts.
+ *
+ * Visibility (spec §6.1): events are shared by default. Optional `channel` / `audience` tags scope an
+ * event to a subset of personas, enforced at the framework boundary (`readSince(seq, viewer)` + the
+ * `read_recent` tool) — context isolation, not convention.
+ */
+/** One entry on the shared blackboard. `channel`/`audience` are optional visibility scoping. */
+export interface BlackboardEvent {
+    seq: number;
+    payload: unknown;
+    /** Emitting persona id (or external source), for audit / `reactByMention`. */
+    source?: string;
+    /** Channel this event belongs to; only personas subscribed to it see it. Omit ⇒ all see it. */
+    channel?: string;
+    /** Explicit recipient persona ids; only they see it. Omit ⇒ all see it (subject to `channel`). */
+    audience?: string[];
+}
+/** A reader's identity for visibility filtering. */
+export interface EventViewer {
+    personaId: string;
+    /** Channels this persona is subscribed to. */
+    channels?: string[];
+}
+/** Default full-share visibility rule (spec §6.1). */
+export declare function isVisibleTo(event: Pick<BlackboardEvent, "channel" | "audience">, viewer: EventViewer): boolean;
+export interface EventStream {
+    /** Append an event; returns it stamped with its assigned `seq`. */
+    append(event: Omit<BlackboardEvent, "seq">): Promise<BlackboardEvent>;
+    /** Events after `seq`. With a `viewer`, only those visible to it (default: all). */
+    readSince(seq: number, viewer?: EventViewer): Promise<BlackboardEvent[]>;
+    /** Notify a listener on each appended event. Returns an unsubscribe fn. */
+    subscribe(cb: (e: BlackboardEvent) => void): () => void;
+}
+/** Process-local default blackboard. */
+export declare class InMemoryEventStream implements EventStream {
+    private readonly events;
+    private readonly listeners;
+    append(event: Omit<BlackboardEvent, "seq">): Promise<BlackboardEvent>;
+    readSince(seq: number, viewer?: EventViewer): Promise<BlackboardEvent[]>;
+    subscribe(cb: (e: BlackboardEvent) => void): () => void;
+}

package/dist/runtime/event-stream.js

@@ -0,0 +1,39 @@
+/**
+ * L2 (Blackboard) — a shared, append-only event stream that N peer agent sessions of one logical run
+ * observe. This is the pluggable storage seam (like `SessionLog`): the default `InMemoryEventStream`
+ * is process-local; back it with Postgres/Redis to span replicas/restarts.
+ *
+ * Visibility (spec §6.1): events are shared by default. Optional `channel` / `audience` tags scope an
+ * event to a subset of personas, enforced at the framework boundary (`readSince(seq, viewer)` + the
+ * `read_recent` tool) — context isolation, not convention.
+ */
+/** Default full-share visibility rule (spec §6.1). */
+export function isVisibleTo(event, viewer) {
+    if (event.audience === undefined && event.channel === undefined)
+        return true;
+    if (event.audience?.includes(viewer.personaId))
+        return true;
+    if (event.channel !== undefined && viewer.channels?.includes(event.channel))
+        return true;
+    return false;
+}
+/** Process-local default blackboard. */
+export class InMemoryEventStream {
+    events = [];
+    listeners = new Set();
+    async append(event) {
+        const stamped = { ...event, seq: this.events.length };
+        this.events.push(stamped);
+        for (const l of this.listeners)
+            l(stamped);
+        return stamped;
+    }
+    async readSince(seq, viewer) {
+        const after = this.events.filter(e => e.seq > seq);
+        return viewer ? after.filter(e => isVisibleTo(e, viewer)) : after;
+    }
+    subscribe(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+}

package/dist/runtime/reactive-session.d.ts

@@ -0,0 +1,125 @@
+/**
+ * L2 (ReactiveSession) — the user-facing primitive for "N peer agents over a shared event stream"
+ * (spec §6). It composes the lower layers so teams don't hand-roll the pattern:
+ *   - L1 `RunGroup`     — shared governance domain (cumulative budget + lineage) across the personas.
+ *   - L0 `SignalGateway`— recipient-routed signals (targeted `interrupt` / `broadcast`).
+ *   - `EventStream`     — the shared blackboard (pluggable; default in-memory).
+ *   - `TurnPolicy`      — who reacts to each event (the one caller-customizable seam).
+ *
+ * Stateless-friendly: `emit` can run inside an HTTP handler; each persona's turn is a normal
+ * `run({sessionId})` whose continuity comes from its `SessionLog`, and `resume()` rebuilds the peer
+ * set from the persisted `RunGroup` membership — no hot in-process loop required.
+ */
+import type { RuntimeRunner } from "./runner.js";
+import type { RunGroup } from "./run-group.js";
+import type { SignalSource, RuntimeSignal } from "../signals/types.js";
+import { SignalGateway } from "../os/public.js";
+import type { BlackboardEvent, EventStream, EventViewer } from "./event-stream.js";
+import type { TurnPolicy } from "./turn-policy.js";
+import type { RegisteredTool } from "../tools/index.js";
+/**
+ * How a persona executes one reactive turn. The default body is a single `runner.run(...)` agent turn;
+ * override it to make a persona's turn a *different orchestration form* — e.g. drive a DAG via
+ * `ctx.runner.runWorkflow(spec)` (DAG-in-Peer) or any composite. The runner is already wired to the
+ * shared `RunGroup`, so whatever the body spawns stays under one governance domain. Must return the
+ * persona's reaction text.
+ */
+export interface ReactorContext {
+    personaId: string;
+    goal: string;
+    event: BlackboardEvent;
+    /** The persona's runner — wired to the shared RunGroup / signal gateway / blackboard. */
+    runner: RuntimeRunner;
+}
+export type ReactorTurn = (ctx: ReactorContext) => Promise<string>;
+/** Per-persona registration: its base reaction goal, role, channel subscriptions, and turn body. */
+export interface ReactivePeerSpec {
+    goal?: string;
+    role?: string;
+    channels?: string[];
+    /**
+     * Override this persona's turn body (the seam for composing other mechanisms into a peer). Defaults
+     * to the session `reactWith`, then to a single `run()` agent turn. Use to make this peer's reaction
+     * a workflow DAG, a nested ensemble, etc. — all under the shared `RunGroup`.
+     */
+    react?: ReactorTurn;
+}
+/** What the caller appends to the blackboard via `emit`. */
+export interface EmitEvent {
+    payload: unknown;
+    source?: string;
+    channel?: string;
+    audience?: string[];
+}
+export interface ReactiveSessionOptions {
+    /** Shared governance domain — all personas run under it (L1). */
+    runGroup: RunGroup;
+    /** Who reacts to each event (L2). */
+    turnPolicy: TurnPolicy;
+    /** Shared blackboard. Defaults to a process-local `InMemoryEventStream`. */
+    eventStream?: EventStream;
+    /** Shared signal gateway for targeted interrupt / broadcast (L0). Defaults to a fresh one. */
+    signalGateway?: SignalGateway;
+    /**
+     * Build a runner for a persona, wiring in the shared governance + signal routing. The app owns the
+     * provider / execution plane / tools; spread `shared` into the `RuntimeRunner` options and register
+     * `readRecentTool(shared.eventStream, viewer)` so the persona can read the blackboard.
+     */
+    makeRunner: (personaId: string, shared: {
+        runGroup: RunGroup;
+        signalSource: SignalSource;
+        eventStream: EventStream;
+    }) => RuntimeRunner;
+    /** Goal for a persona's reactive turn. Defaults to a generic "react to the blackboard" prompt. */
+    goalFor?: (personaId: string, event: BlackboardEvent) => string;
+    /**
+     * Default turn body for peers that don't set their own `react`. Defaults to a single `run()` agent
+     * turn. Override to make every peer's turn a different orchestration form (e.g. a workflow DAG).
+     */
+    reactWith?: ReactorTurn;
+}
+/** A persona's reaction to an emitted event. */
+export interface Reaction {
+    personaId: string;
+    output: string;
+}
+export declare class ReactiveSession {
+    private readonly opts;
+    private readonly peerSpecs;
+    private readonly runners;
+    private readonly policyState;
+    private readonly eventStream;
+    private readonly gateway;
+    constructor(opts: ReactiveSessionOptions);
+    /** Register a peer persona and record it in the group membership (lineage). */
+    addPeer(personaId: string, spec?: ReactivePeerSpec): void;
+    peers(): string[];
+    blackboard(): EventStream;
+    /**
+     * Append an event to the blackboard, ask the `TurnPolicy` which (visible) peers react, and drive one
+     * turn for each — returning their outputs. Each turn runs under the shared `RunGroup` governance.
+     */
+    emit(event: EmitEvent): Promise<Reaction[]>;
+    /** Targeted preemption: deliver a critical signal to one persona's loop only (L0 recipient routing). */
+    interrupt(personaId: string, signal: Partial<RuntimeSignal> & {
+        payload?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Broadcast a signal to every persona (each sees it on its next turn). */
+    broadcast(signal: Partial<RuntimeSignal> & {
+        payload?: Record<string, unknown>;
+    }): Promise<void>;
+    private getRunner;
+    private driveTurn;
+    /**
+     * Rebuild a session from a persisted `RunGroup`: load its members (lineage) as peers. The blackboard
+     * continuity comes from the (persistent) `EventStream`. Turn-policy cursor state is not restored.
+     */
+    static resume(opts: ReactiveSessionOptions & {
+        peerSpecs?: Record<string, ReactivePeerSpec>;
+    }): Promise<ReactiveSession>;
+}
+/**
+ * A `read_recent` tool a persona uses to read the shared blackboard, scoped to what it may see. Register
+ * one per persona inside `makeRunner`. `viewer` is the reading persona (id + subscribed channels).
+ */
+export declare function readRecentTool(eventStream: EventStream, viewer: EventViewer): RegisteredTool;