@deepstrike/sdk 0.2.28 → 0.2.31

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,62 @@
+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.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-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.1", baseURLProfileKey: "glm.anthropic", policies: GLM_POLICIES },
+    minimax: { providerId: "minimax", defaultModel: "MiniMax-M2.7", 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/facade.js

@@ -58,6 +58,11 @@ export async function runFanout(opts) {
         ],
     };
     const outcome = await runner.runWorkflow(spec, opts.sessionId ? { sessionId: opts.sessionId } : undefined);
+    // The synthesis node is the last spec node; the kernel ids nodes `wf-node{index}`. Prefer that id,
+    // but fall back to the last completed node's output so a kernel id-scheme change can't silently
+    // return an empty synthesis.
     const synthesisId = `wf-node${opts.tasks.length}`;
-    return { synthesis: outcome.outputs[synthesisId] ?? "", outputs: outcome.outputs };
+    const lastCompleted = outcome.completed[outcome.completed.length - 1];
+    const synthesis = outcome.outputs[synthesisId] ?? (lastCompleted ? outcome.outputs[lastCompleted] : undefined) ?? "";
+    return { synthesis, outputs: outcome.outputs };
 }

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;

package/dist/runtime/reactive-session.js

@@ -0,0 +1,127 @@
+import { collectText } from "./runner.js";
+import { SignalGateway } from "../os/public.js";
+import { InMemoryEventStream, isVisibleTo } from "./event-stream.js";
+import { tool } from "../tools/index.js";
+export class ReactiveSession {
+    opts;
+    peerSpecs = new Map();
+    runners = new Map();
+    policyState = {};
+    eventStream;
+    gateway;
+    constructor(opts) {
+        this.opts = opts;
+        this.eventStream = opts.eventStream ?? new InMemoryEventStream();
+        this.gateway = opts.signalGateway ?? new SignalGateway();
+    }
+    /** Register a peer persona and record it in the group membership (lineage). */
+    addPeer(personaId, spec = {}) {
+        this.peerSpecs.set(personaId, spec);
+        void this.opts.runGroup.budgetStore.join(this.opts.runGroup.id, { sessionId: personaId, role: spec.role });
+    }
+    peers() {
+        return [...this.peerSpecs.keys()];
+    }
+    blackboard() {
+        return this.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.
+     */
+    async emit(event) {
+        const bbEvent = await this.eventStream.append(event);
+        const candidates = [...this.peerSpecs.entries()]
+            .map(([personaId, spec]) => ({ personaId, role: spec.role, channels: spec.channels }))
+            // Only personas that can actually see the event are eligible to react.
+            .filter(p => isVisibleTo(bbEvent, p));
+        const chosen = await this.opts.turnPolicy(bbEvent, candidates, this.policyState);
+        const eligible = new Set(candidates.map(p => p.personaId));
+        const reactions = [];
+        for (const personaId of chosen) {
+            if (!eligible.has(personaId))
+                continue;
+            reactions.push({ personaId, output: await this.driveTurn(personaId, bbEvent) });
+        }
+        return reactions;
+    }
+    /** Targeted preemption: deliver a critical signal to one persona's loop only (L0 recipient routing). */
+    async interrupt(personaId, signal) {
+        this.gateway.ingest({
+            source: "gateway",
+            signalType: "alert",
+            urgency: "critical",
+            payload: signal.payload ?? {},
+            ...signal,
+            recipient: personaId,
+        });
+    }
+    /** Broadcast a signal to every persona (each sees it on its next turn). */
+    async broadcast(signal) {
+        this.gateway.ingest({
+            source: "gateway",
+            signalType: "event",
+            urgency: "normal",
+            payload: signal.payload ?? {},
+            ...signal,
+            recipient: undefined,
+        });
+    }
+    getRunner(personaId) {
+        let runner = this.runners.get(personaId);
+        if (!runner) {
+            runner = this.opts.makeRunner(personaId, {
+                runGroup: this.opts.runGroup,
+                signalSource: this.gateway,
+                eventStream: this.eventStream,
+            });
+            this.runners.set(personaId, runner);
+        }
+        return runner;
+    }
+    async driveTurn(personaId, event) {
+        const runner = this.getRunner(personaId);
+        const goal = this.opts.goalFor?.(personaId, event) ??
+            this.peerSpecs.get(personaId)?.goal ??
+            "React to the latest events on the shared blackboard.";
+        // Turn-body seam (the DAG-in-Peer enabler): a persona's reaction can be any orchestration form,
+        // not just a single agent turn. Per-peer `react` wins, then session `reactWith`, else the default
+        // `run()`. Whatever the body drives (e.g. `runner.runWorkflow`) inherits the shared RunGroup.
+        const react = this.peerSpecs.get(personaId)?.react ?? this.opts.reactWith;
+        if (react)
+            return react({ personaId, goal, event, runner });
+        // run() with the persona's stable sessionId replays its prior turns from the SessionLog, so this
+        // is continuity-preserving whether or not the persona has acted before (stateless-handler safe).
+        return collectText(runner.run({ sessionId: personaId, goal }));
+    }
+    /**
+     * 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 async resume(opts) {
+        const session = new ReactiveSession(opts);
+        for (const member of await opts.runGroup.budgetStore.members(opts.runGroup.id)) {
+            session.peerSpecs.set(member.sessionId, opts.peerSpecs?.[member.sessionId] ?? { role: member.role });
+        }
+        return session;
+    }
+}
+/**
+ * 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 function readRecentTool(eventStream, viewer) {
+    return tool("read_recent", "Read recent events from the shared blackboard visible to you (optionally a single channel).", {
+        type: "object",
+        properties: {
+            since_seq: { type: "number", description: "Only events after this seq (default: from the start)." },
+            channel: { type: "string", description: "Restrict to one channel you subscribe to." },
+        },
+    }, async (args) => {
+        const sinceSeq = typeof args.since_seq === "number" ? args.since_seq : -1;
+        const channel = typeof args.channel === "string" ? args.channel : undefined;
+        const events = await eventStream.readSince(sinceSeq, viewer);
+        const filtered = channel ? events.filter(e => e.channel === channel) : events;
+        return JSON.stringify(filtered.map(e => ({ seq: e.seq, source: e.source, channel: e.channel, payload: e.payload })));
+    });
+}

package/dist/runtime/run-group.d.ts

@@ -0,0 +1,74 @@
+/**
+ * L1 (RunGroup) — a governance domain shared by N peer agent sessions of one logical run.
+ *
+ * The kernel (execution vehicle) is ephemeral and torn down between stateless turns, so the
+ * cumulative budget + membership that must span the whole group live outside any vehicle: in a
+ * `GroupBudgetStore`. Each member's run is seeded at boot with the group's accumulated spend (tokens
+ * + sub-agent spawns) so the run-level token cap and the cumulative spawn cap are enforced across all
+ * members, registers itself as a member (lineage), and charges its own consumption back when it ends.
+ * Per spec §2.5, only *cumulative* budget is shared this way; instantaneous concurrency stays
+ * vehicle-scoped.
+ *
+ * Two built-in stores:
+ * - `InMemoryGroupBudgetStore` — process-local; fine for a single replica / tests.
+ * - `SessionLogGroupBudgetStore` — persists the ledger + membership to any `SessionLog` (fold-on-read
+ *   under a group-anchor key), so a logical run's governance + lineage survive process boundaries and
+ *   span replicas when backed by a durable `SessionLog`.
+ */
+import type { SessionLog } from "./session-log.js";
+/** Cumulative resources spent across a run group. */
+export interface GroupLedger {
+    /** Total tokens spent by all members. */
+    tokensSpent: number;
+    /** Total sub-agents spawned by all members (running + completed). */
+    subagentsSpawned: number;
+}
+/** A member's contribution to charge back to the group ledger. */
+export interface GroupCharge {
+    tokens?: number;
+    subagents?: number;
+}
+/** A persona session that participated in the logical run (process-table lineage). */
+export interface GroupMember {
+    sessionId: string;
+    role?: string;
+}
+export interface GroupBudgetStore {
+    /** Cumulative spend across the group so far. */
+    read(groupId: string): GroupLedger | Promise<GroupLedger>;
+    /** Add a member's spend to the group's cumulative totals. */
+    charge(groupId: string, delta: GroupCharge): void | Promise<void>;
+    /** Register a persona session as a member of the group (idempotent by sessionId). */
+    join(groupId: string, member: GroupMember): void | Promise<void>;
+    /** All persona sessions of the logical run — the cross-invocation lineage (R2). */
+    members(groupId: string): GroupMember[] | Promise<GroupMember[]>;
+}
+/** Process-local default store. One ledger + member set per group id. */
+export declare class InMemoryGroupBudgetStore implements GroupBudgetStore {
+    private readonly ledgers;
+    private readonly memberships;
+    read(groupId: string): GroupLedger;
+    charge(groupId: string, delta: GroupCharge): void;
+    join(groupId: string, member: GroupMember): void;
+    members(groupId: string): GroupMember[];
+}
+/**
+ * Persists the group ledger + membership to a `SessionLog`, keyed by a group-anchor session whose id
+ * is the group id. Budget/membership rebuild by folding `group_budget_charged` / `group_member_joined`
+ * events on read (spec §2.4). Durable + replica-spanning when the underlying `SessionLog` is.
+ */
+export declare class SessionLogGroupBudgetStore implements GroupBudgetStore {
+    private readonly log;
+    constructor(log: SessionLog);
+    read(groupId: string): Promise<GroupLedger>;
+    charge(groupId: string, delta: GroupCharge): Promise<void>;
+    join(groupId: string, member: GroupMember): Promise<void>;
+    members(groupId: string): Promise<GroupMember[]>;
+}
+/** Binds a runner to a governance domain: a stable group id + the store its members share. */
+export interface RunGroup {
+    /** Stable id for this logical run's governance domain; all members pass the same one. */
+    id: string;
+    /** Shared cumulative-budget + membership store. */
+    budgetStore: GroupBudgetStore;
+}

package/dist/runtime/run-group.js

@@ -0,0 +1,72 @@
+/** Process-local default store. One ledger + member set per group id. */
+export class InMemoryGroupBudgetStore {
+    ledgers = new Map();
+    memberships = new Map();
+    read(groupId) {
+        return this.ledgers.get(groupId) ?? { tokensSpent: 0, subagentsSpawned: 0 };
+    }
+    charge(groupId, delta) {
+        const cur = this.read(groupId);
+        this.ledgers.set(groupId, {
+            tokensSpent: cur.tokensSpent + Math.max(0, delta.tokens ?? 0),
+            subagentsSpawned: cur.subagentsSpawned + Math.max(0, delta.subagents ?? 0),
+        });
+    }
+    join(groupId, member) {
+        if (!this.memberships.has(groupId))
+            this.memberships.set(groupId, new Map());
+        this.memberships.get(groupId).set(member.sessionId, member);
+    }
+    members(groupId) {
+        return [...(this.memberships.get(groupId)?.values() ?? [])];
+    }
+}
+/**
+ * Persists the group ledger + membership to a `SessionLog`, keyed by a group-anchor session whose id
+ * is the group id. Budget/membership rebuild by folding `group_budget_charged` / `group_member_joined`
+ * events on read (spec §2.4). Durable + replica-spanning when the underlying `SessionLog` is.
+ */
+export class SessionLogGroupBudgetStore {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    async read(groupId) {
+        let tokensSpent = 0;
+        let subagentsSpawned = 0;
+        for (const { event } of await this.log.read(groupId)) {
+            if (event.kind === "group_budget_charged") {
+                tokensSpent += event.tokens;
+                subagentsSpawned += event.subagents;
+            }
+        }
+        return { tokensSpent, subagentsSpawned };
+    }
+    async charge(groupId, delta) {
+        await this.log.append(groupId, {
+            kind: "group_budget_charged",
+            tokens: Math.max(0, delta.tokens ?? 0),
+            subagents: Math.max(0, delta.subagents ?? 0),
+        });
+    }
+    async join(groupId, member) {
+        // Idempotent: don't grow the log with duplicate joins for the same session.
+        const existing = await this.members(groupId);
+        if (existing.some(m => m.sessionId === member.sessionId))
+            return;
+        await this.log.append(groupId, {
+            kind: "group_member_joined",
+            session_id: member.sessionId,
+            ...(member.role ? { role: member.role } : {}),
+        });
+    }
+    async members(groupId) {
+        const seen = new Map();
+        for (const { event } of await this.log.read(groupId)) {
+            if (event.kind === "group_member_joined") {
+                seen.set(event.session_id, { sessionId: event.session_id, role: event.role });
+            }
+        }
+        return [...seen.values()];
+    }
+}