@deepstrike/sdk 0.2.30 → 0.2.31

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.31",
   "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.31",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },