@deepstrike/sdk 0.2.30 → 0.2.32

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()];
+    }
+}

package/dist/runtime/runner.d.ts

@@ -5,6 +5,7 @@ import type { SignalSource } from "../signals/types.js";
 import type { SessionLog, SessionEvent } from "./session-log.js";
 import type { ArchiveStore } from "./archive.js";
 import type { ExecutionPlane } from "./execution-plane.js";
+import type { RunGroup } from "./run-group.js";
 import { type MemoryPolicy, type ResourceQuota } from "../kernel.js";
 import type { AgentRunSpec, MilestoneCheckResult, MilestoneContract, MilestonePolicy, WorkflowSpec } from "../types/agent.js";
 import { type SubAgentOrchestrator } from "./sub-agent-orchestrator.js";
@@ -117,6 +118,14 @@ export interface RuntimeOptions {
      * and memory-write syscalls are admitted unconditionally (pre-M2 behavior).
      */
     resourceQuota?: ResourceQuota;
+    /**
+     * L1 (RunGroup): bind this runner to a governance domain shared by N peer sessions of one logical
+     * run. Members pass the same `id` + `budgetStore`; the kernel's run-level token cap is then enforced
+     * against the group's cumulative spend (seeded at boot, charged at run end) rather than per-vehicle.
+     * Unset ⇒ N=1, pre-L1 per-run budget (byte-identical). Only cumulative budget is shared; instantaneous
+     * concurrency stays vehicle-scoped (spec §2.5).
+     */
+    runGroup?: RunGroup;
     /**
      * Optional long-term memory policy (`set_memory_policy`). Tunes the kernel's memory subsystem
      * (retrieval top-k, stale-warning age, write validation, memory path). Unset leaves the kernel

package/dist/runtime/runner.js

@@ -146,7 +146,7 @@ export class RuntimeRunner {
      * exactly as a mid-run spawn would be. Must run BEFORE `start_run` so the in-kernel gate enforces
      * every policy from the first spawn. No config ⇒ the native-profile defaults (铁律: defaults only).
      */
-    applyKernelPolicies(runtime) {
+    applyKernelPolicies(runtime, groupTokensBase, groupSpawnsBase) {
         // K2: lower governance / attention / scheduler / quota in ONE `configure_run` event instead of
         // the previous 2–4 separate `set_*` / `load_governance_policy` events. The kernel applies each
         // present field via the same path its granular event uses; absent fields are left untouched.
@@ -168,12 +168,19 @@ export class RuntimeRunner {
             const q = this.opts.resourceQuota;
             config.resource_quota = {
                 ...(q.maxConcurrentSubagents !== undefined ? { max_concurrent_subagents: q.maxConcurrentSubagents } : {}),
+                ...(q.maxTotalSubagents !== undefined ? { max_total_subagents: q.maxTotalSubagents } : {}),
                 ...(q.maxSpawnDepth !== undefined ? { max_spawn_depth: q.maxSpawnDepth } : {}),
                 ...(q.memoryWritesPerWindow !== undefined
                     ? { memory_writes_per_window: [q.memoryWritesPerWindow.maxWrites, q.memoryWritesPerWindow.windowMs] }
                     : {}),
             };
         }
+        if (groupTokensBase !== undefined && groupTokensBase > 0) {
+            config.group_tokens_base = groupTokensBase;
+        }
+        if (groupSpawnsBase !== undefined && groupSpawnsBase > 0) {
+            config.group_spawns_base = groupSpawnsBase;
+        }
         kernelApply(runtime, this.pendingObservations, { kind: "configure_run", config });
     }
     async appendMemorySyscallObservations(sessionId, observations) {
@@ -435,7 +442,18 @@ export class RuntimeRunner {
         // already set by an in-flight `run()`) keep the original in-place behavior with no teardown.
         const bootstrapped = !this.activeKernel || !this.currentSessionId;
         if (bootstrapped) {
-            this.bootstrapWorkflowKernel(opts?.sessionId ?? `wf-${crypto.randomUUID()}`, spec);
+            const sessionId = opts?.sessionId ?? `wf-${crypto.randomUUID()}`;
+            // L1: a standalone workflow is a member of its runner's governance domain too. Seed the
+            // bootstrap kernel with the group's cumulative spend (so the cumulative spawn/token cap bites
+            // while scheduling DAG nodes) and register membership — mirroring `execute()`. Mid-run callers
+            // skip this: their parent `run()` already seeds + counts the nodes via `localSubagentsSpawned()`.
+            let groupLedger;
+            if (this.opts.runGroup) {
+                const g = this.opts.runGroup;
+                groupLedger = await g.budgetStore.read(g.id);
+                await g.budgetStore.join(g.id, { sessionId, role: this.opts.agentId });
+            }
+            this.bootstrapWorkflowKernel(sessionId, spec, groupLedger?.tokensSpent, groupLedger?.subagentsSpawned);
         }
         const parentSessionId = this.currentSessionId;
         const runtime = this.activeKernel;
@@ -453,6 +471,17 @@ export class RuntimeRunner {
         }
         finally {
             if (bootstrapped) {
+                // L1: charge the standalone workflow's node spawns back to the group so the cumulative spawn
+                // cap (`maxTotalSubagents`) counts workflow nodes — they are member runs whose own
+                // `execute()` charge contributes 0 spawns, so without this the node count is invisible to the
+                // group. The envelope kernel's TaskTable holds one proc per scheduled node, so
+                // `localSubagentsSpawned()` is exactly that node count (the envelope itself burns no tokens).
+                if (this.opts.runGroup) {
+                    const subagents = runtime.localSubagentsSpawned?.() ?? 0;
+                    if (subagents > 0) {
+                        await this.opts.runGroup.budgetStore.charge(this.opts.runGroup.id, { subagents });
+                    }
+                }
                 this.activeKernel = null;
                 this.currentSessionId = null;
                 this.pendingObservations = [];
@@ -466,7 +495,7 @@ export class RuntimeRunner {
      * and records a `run_started` event so the standalone run is resumable from the session log. Sets
      * `activeKernel` / `currentSessionId`; `runWorkflow` is responsible for tearing them down.
      */
-    bootstrapWorkflowKernel(sessionId, spec) {
+    bootstrapWorkflowKernel(sessionId, spec, groupTokensBase, groupSpawnsBase) {
         this.interrupted = false;
         this.abortController = new AbortController();
         this.pendingObservations = [];
@@ -485,7 +514,7 @@ export class RuntimeRunner {
             criteria: [],
             agent_id: this.opts.agentId,
         }).catch(() => { });
-        this.applyKernelPolicies(runtime);
+        this.applyKernelPolicies(runtime, groupTokensBase, groupSpawnsBase);
         // K1: no explicit `start_run` — the host `load_workflow` (fired next by `runWorkflow`) self-bootstraps
         // the run on the 0.2.30 core, matching the agent-reachable `submit_workflow` path.
         return runtime;
@@ -542,7 +571,7 @@ export class RuntimeRunner {
         if (!source)
             return null;
         while (!batchState.settled) {
-            const sig = await source.nextSignal();
+            const sig = await source.nextSignal(this.currentSessionId ?? undefined);
             if (batchState.settled)
                 break;
             if (!sig) {
@@ -867,6 +896,7 @@ export class RuntimeRunner {
             maxTokens: this.opts.maxTokens,
             maxTurns: effectiveMaxTurns,
             timeoutMs: effectiveTimeoutMs !== undefined ? BigInt(effectiveTimeoutMs) : undefined,
+            maxTotalTokens: this.opts.maxTotalTokens !== undefined ? BigInt(this.opts.maxTotalTokens) : undefined,
         });
         this.activeKernel = runtime;
         this.nextArchiveStart = nextCompressedArchiveStart;
@@ -1004,7 +1034,16 @@ export class RuntimeRunner {
                 : baseSpec;
             startPayload.run_spec = agentRunSpecToKernel(spec);
         }
-        this.applyKernelPolicies(runtime);
+        // L1: seed the kernel with the group's cumulative spend so the run-level token cap + cumulative
+        // spawn cap span the whole governance domain (other members' prior spend). No group ⇒ per-run.
+        // Also register this session as a member so the run's lineage (R2) spans personas/invocations.
+        let groupLedger;
+        if (this.opts.runGroup) {
+            const g = this.opts.runGroup;
+            groupLedger = await g.budgetStore.read(g.id);
+            await g.budgetStore.join(g.id, { sessionId, role: this.opts.agentId });
+        }
+        this.applyKernelPolicies(runtime, groupLedger?.tokensSpent, groupLedger?.subagentsSpawned);
         // Multimodal upload: seed the user's attachments (images/audio) as a history
         // message before start_run pushes the "[TASK STATE]" anchor. init_task does not
         // clear history, so order becomes [attachment user msg, "Proceed…"] — both land
@@ -1061,7 +1100,7 @@ export class RuntimeRunner {
                     break;
                 }
                 if (this.opts.signalSource) {
-                    const sig = await this.opts.signalSource.nextSignal();
+                    const sig = await this.opts.signalSource.nextSignal(this.currentSessionId ?? undefined);
                     if (sig) {
                         // Kernel-routed: the kernel decides disposition (dedup/queue/interrupt) and emits
                         // `signal_disposed`. An actionable disposition yields a new action to adopt; queued/observed/
@@ -1484,6 +1523,14 @@ export class RuntimeRunner {
             turnsUsed,
             totalTokens,
         }));
+        // L1: charge this vehicle's local spend (tokens + sub-agent spawns) back to the governance domain
+        // so the next member is seeded with the updated cumulative totals.
+        if (this.opts.runGroup) {
+            const subagents = runtime.localSubagentsSpawned?.() ?? 0;
+            if (totalTokens > 0 || subagents > 0) {
+                await this.opts.runGroup.budgetStore.charge(this.opts.runGroup.id, { tokens: totalTokens, subagents });
+            }
+        }
         if (this.opts.dreamStore && this.opts.agentId) {
             const newMsgs = runtime.drainNewMessages().map(m => ({
                 role: m.role,
@@ -1925,6 +1972,8 @@ function signalToKernelEvent(sig) {
             summary: String(sig.payload?.goal ?? sig.kind ?? "signal"),
             payload: sig.payload ?? {},
             ...(sig.dedupeKey ? { dedupe_key: sig.dedupeKey } : {}),
+            ...(sig.recipient ? { recipient: sig.recipient } : {}),
+            ...(sig.topic ? { topic: sig.topic } : {}),
             timestamp_ms: Date.now(),
         },
     };

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

@@ -275,6 +275,14 @@ export type SessionEvent = {
     kind: "summary_upgraded";
     compressed_seq: number;
     summary: string;
+} | {
+    kind: "group_member_joined";
+    session_id: string;
+    role?: string;
+} | {
+    kind: "group_budget_charged";
+    tokens: number;
+    subagents: number;
 };
 export interface SessionLog {
     append(sessionId: string, event: SessionEvent): Promise<number>;

package/dist/runtime/turn-policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * L2 (TurnPolicy) — who reacts to a blackboard event. This is the one caller-customizable seam of a
+ * `ReactiveSession`; the framework supplies a spanning default set (addressing / delegated /
+ * deterministic-cyclic) plus combinators, so teams compose rather than hand-roll turn-taking.
+ *
+ * Stateful policies (e.g. `roundRobin`) must keep their cursor in `state`, which a `ReactiveSession`
+ * persists to the group store so it survives stateless turns.
+ */
+import type { BlackboardEvent } from "./event-stream.js";
+/** A peer the policy can choose to activate. */
+export interface PeerView {
+    personaId: string;
+    role?: string;
+    channels?: string[];
+}
+/**
+ * Decide which peers react to `event`. Async to allow LLM-delegated selection. `state` is opaque,
+ * persisted across turns by the session (for cursors etc.); mutate-and-return it.
+ */
+export type TurnPolicy = (event: BlackboardEvent, peers: PeerView[], state: Record<string, unknown>) => string[] | Promise<string[]>;
+/** Addressing: react iff the event names the peer (its `audience`, or its id/role in the payload). */
+export declare function reactByMention(): TurnPolicy;
+/**
+ * Delegated: a designated persona (or fn) decides who reacts. The most flexible escape hatch — the
+ * selector can be an LLM call. `select` receives the event + candidate peers and returns chosen ids.
+ */
+export declare function directorDriven(directorId: string, select: (event: BlackboardEvent, peers: PeerView[]) => string[] | Promise<string[]>): TurnPolicy;
+/** Deterministic: cycle through peers in order, one per event. Cursor persisted in `state`. */
+export declare function roundRobin(): TurnPolicy;
+/** Combinator: first policy that selects a non-empty set wins (e.g. mention, else director). */
+export declare function firstNonEmpty(...policies: TurnPolicy[]): TurnPolicy;
+/** Combinator: union of all policies' selections (deduped, order-stable). */
+export declare function union(...policies: TurnPolicy[]): TurnPolicy;

package/dist/runtime/turn-policy.js

@@ -0,0 +1,58 @@
+const idsOf = (peers) => peers.map(p => p.personaId);
+/** Addressing: react iff the event names the peer (its `audience`, or its id/role in the payload). */
+export function reactByMention() {
+    return (event, peers) => {
+        const hay = typeof event.payload === "string" ? event.payload : JSON.stringify(event.payload ?? "");
+        return idsOf(peers).filter(id => {
+            const peer = peers.find(p => p.personaId === id);
+            if (event.audience?.includes(id))
+                return true;
+            if (hay.includes(id))
+                return true;
+            return peer.role !== undefined && hay.includes(peer.role);
+        });
+    };
+}
+/**
+ * Delegated: a designated persona (or fn) decides who reacts. The most flexible escape hatch — the
+ * selector can be an LLM call. `select` receives the event + candidate peers and returns chosen ids.
+ */
+export function directorDriven(directorId, select) {
+    return async (event, peers) => {
+        const chosen = await select(event, peers);
+        const valid = new Set(idsOf(peers));
+        return chosen.filter(id => valid.has(id) && id !== directorId);
+    };
+}
+/** Deterministic: cycle through peers in order, one per event. Cursor persisted in `state`. */
+export function roundRobin() {
+    return (event, peers, state) => {
+        if (peers.length === 0)
+            return [];
+        const cursor = typeof state.rrCursor === "number" ? state.rrCursor : 0;
+        const idx = cursor % peers.length;
+        state.rrCursor = cursor + 1;
+        return [peers[idx].personaId];
+    };
+}
+/** Combinator: first policy that selects a non-empty set wins (e.g. mention, else director). */
+export function firstNonEmpty(...policies) {
+    return async (event, peers, state) => {
+        for (const p of policies) {
+            const chosen = await p(event, peers, state);
+            if (chosen.length > 0)
+                return chosen;
+        }
+        return [];
+    };
+}
+/** Combinator: union of all policies' selections (deduped, order-stable). */
+export function union(...policies) {
+    return async (event, peers, state) => {
+        const out = new Set();
+        for (const p of policies)
+            for (const id of await p(event, peers, state))
+                out.add(id);
+        return [...out];
+    };
+}

package/dist/signals/gateway.d.ts

@@ -16,8 +16,13 @@ export declare class SignalGateway implements SignalSource {
     private timers;
     private queue;
     private listeners;
-    /** Called by the agent loop each turn. Returns the oldest queued signal or null. */
-    nextSignal(): Promise<RuntimeSignal | null>;
+    /**
+     * Called by the agent loop each turn. Returns the oldest queued signal or null.
+     * When `recipient` is given, returns only the oldest signal addressed to it (plus
+     * unaddressed broadcasts); signals addressed to other recipients stay queued, so one
+     * shared gateway can serve N peer loops. Omit ⇒ legacy FIFO drain (any signal).
+     */
+    nextSignal(recipient?: string): Promise<RuntimeSignal | null>;
     /** Register a listener that is called synchronously whenever a signal is emitted. */
     onSignal(listener: (sig: RuntimeSignal) => void): void;
     /** Schedule a ScheduledPrompt to fire at its `runAtMs`. Idempotent by goal+time. */

package/dist/signals/gateway.js

@@ -15,9 +15,19 @@ export class SignalGateway {
     queue = [];
     listeners = [];
     // ── SignalSource interface (pull model) ─────────────────────────────────────
-    /** Called by the agent loop each turn. Returns the oldest queued signal or null. */
-    async nextSignal() {
-        return this.queue.shift() ?? null;
+    /**
+     * Called by the agent loop each turn. Returns the oldest queued signal or null.
+     * When `recipient` is given, returns only the oldest signal addressed to it (plus
+     * unaddressed broadcasts); signals addressed to other recipients stay queued, so one
+     * shared gateway can serve N peer loops. Omit ⇒ legacy FIFO drain (any signal).
+     */
+    async nextSignal(recipient) {
+        if (recipient === undefined)
+            return this.queue.shift() ?? null;
+        const idx = this.queue.findIndex(s => s.recipient === undefined || s.recipient === recipient);
+        if (idx === -1)
+            return null;
+        return this.queue.splice(idx, 1)[0];
     }
     // ── Push API ────────────────────────────────────────────────────────────────
     /** Register a listener that is called synchronously whenever a signal is emitted. */

package/dist/signals/types.d.ts

@@ -7,11 +7,20 @@ export interface RuntimeSignal {
     urgency: RuntimeSignalUrgency;
     payload: Record<string, unknown>;
     dedupeKey?: string;
+    /** Target a specific session loop (its `sessionId`). Omitted ⇒ broadcast (any puller). */
+    recipient?: string;
+    /** Optional pub/sub topic (carried through; multi-subscriber routing deferred). */
+    topic?: string;
     /** @deprecated Use source/signalType/urgency directly. */
     kind?: "interrupt" | "scheduled" | "external";
     /** @deprecated Prefer explicit `urgency`. */
     priority?: number;
 }
 export interface SignalSource {
-    nextSignal(): Promise<RuntimeSignal | null>;
+    /**
+     * Pull the next pending signal. When `recipient` is given, return only signals
+     * addressed to it (plus unaddressed broadcasts); other recipients' signals stay
+     * queued. Omit ⇒ legacy FIFO drain (any signal).
+     */
+    nextSignal(recipient?: string): Promise<RuntimeSignal | null>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.30",
+    "@deepstrike/core": "0.2.32",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },