@deepstrike/sdk 0.2.39 → 0.2.40

package/dist/runtime/reaction-checkpoint.js

@@ -0,0 +1,83 @@
+/** Process-local reference implementation; durable stores implement the same atomic contract. */
+export class InMemoryReactionCheckpointStore {
+    opts;
+    states = new Map();
+    leaseSeq = 0;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async claim(checkpointKey, leaseMs = this.opts.defaultLeaseMs ?? 900_000) {
+        if (!Number.isFinite(leaseMs) || leaseMs <= 0)
+            throw new RangeError("leaseMs must be positive");
+        const now = this.opts.now?.() ?? Date.now();
+        const state = this.states.get(checkpointKey) ?? {
+            outputs: new Map(),
+            completed: false,
+        };
+        this.states.set(checkpointKey, state);
+        if (state.completed)
+            return { status: "completed", reactions: this.reactions(state) };
+        if (state.lease && state.lease.expiresAtMs > now)
+            return { status: "busy" };
+        const token = `${checkpointKey}:lease-${++this.leaseSeq}`;
+        const expiresAtMs = now + leaseMs;
+        state.lease = { token, expiresAtMs };
+        return {
+            status: "claimed",
+            claim: {
+                checkpointKey,
+                leaseToken: token,
+                leaseExpiresAtMs: expiresAtMs,
+                plan: state.plan ? [...state.plan] : undefined,
+                outputs: Object.fromEntries(state.outputs),
+            },
+        };
+    }
+    async savePlan(receipt, personaIds) {
+        const state = this.current(receipt);
+        if (!state)
+            return null;
+        state.plan ??= [...new Set(personaIds)];
+        return [...state.plan];
+    }
+    async record(receipt, reaction) {
+        const state = this.current(receipt);
+        if (!state)
+            return false;
+        state.outputs.set(reaction.personaId, reaction.output);
+        return true;
+    }
+    async complete(receipt) {
+        const state = this.current(receipt);
+        if (!state)
+            return false;
+        if (!state.plan || state.plan.some(personaId => !state.outputs.has(personaId))) {
+            throw new Error("cannot complete a reaction checkpoint with unfinished personas");
+        }
+        state.completed = true;
+        delete state.lease;
+        return true;
+    }
+    async release(receipt) {
+        const state = this.current(receipt);
+        if (!state)
+            return false;
+        delete state.lease;
+        return true;
+    }
+    current(receipt) {
+        const state = this.states.get(receipt.checkpointKey);
+        return state?.lease?.token === receipt.leaseToken ? state : undefined;
+    }
+    reactions(state) {
+        return (state.plan ?? []).map(personaId => ({ personaId, output: state.outputs.get(personaId) }));
+    }
+}
+export class ReactionInProgressError extends Error {
+    checkpointKey;
+    constructor(checkpointKey) {
+        super(`reaction checkpoint is already in progress: ${checkpointKey}`);
+        this.checkpointKey = checkpointKey;
+        this.name = "ReactionInProgressError";
+    }
+}

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

@@ -17,6 +17,7 @@ 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";
+import type { ReactionCheckpointStore, ReactionRecord } from "./reaction-checkpoint.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
@@ -47,6 +48,8 @@ export interface ReactivePeerSpec {
 /** What the caller appends to the blackboard via `emit`. */
 export interface EmitEvent {
     payload: unknown;
+    /** Stable external request/event key used for append and reaction idempotency. */
+    idempotencyKey?: string;
     source?: string;
     channel?: string;
     audience?: string[];
@@ -58,6 +61,10 @@ export interface ReactiveSessionOptions {
     turnPolicy: TurnPolicy;
     /** Shared blackboard. Defaults to a process-local `InMemoryEventStream`. */
     eventStream?: EventStream;
+    /** Persisted event-level reaction plan/output checkpoints. Defaults to process-local memory. */
+    checkpointStore?: ReactionCheckpointStore;
+    /** Lease covering one event's reaction plan. Default: 15 minutes. */
+    reactionLeaseMs?: number;
     /** Shared signal gateway for targeted interrupt / broadcast (L0). Defaults to a fresh one. */
     signalGateway?: SignalGateway;
     /**
@@ -79,9 +86,7 @@ export interface ReactiveSessionOptions {
     reactWith?: ReactorTurn;
 }
 /** A persona's reaction to an emitted event. */
-export interface Reaction {
-    personaId: string;
-    output: string;
+export interface Reaction extends ReactionRecord {
 }
 export declare class ReactiveSession {
     private readonly opts;
@@ -90,6 +95,7 @@ export declare class ReactiveSession {
     private readonly policyState;
     private readonly eventStream;
     private readonly gateway;
+    private readonly checkpointStore;
     constructor(opts: ReactiveSessionOptions);
     /** Register a peer persona and record it in the group membership (lineage). */
     addPeer(personaId: string, spec?: ReactivePeerSpec): void;

package/dist/runtime/reactive-session.js

@@ -2,6 +2,7 @@ import { collectText } from "./runner.js";
 import { SignalGateway } from "../os/public.js";
 import { InMemoryEventStream, isVisibleTo } from "./event-stream.js";
 import { tool } from "../tools/index.js";
+import { InMemoryReactionCheckpointStore, ReactionInProgressError, } from "./reaction-checkpoint.js";
 export class ReactiveSession {
     opts;
     peerSpecs = new Map();
@@ -9,10 +10,12 @@ export class ReactiveSession {
     policyState = {};
     eventStream;
     gateway;
+    checkpointStore;
     constructor(opts) {
         this.opts = opts;
         this.eventStream = opts.eventStream ?? new InMemoryEventStream();
         this.gateway = opts.signalGateway ?? new SignalGateway();
+        this.checkpointStore = opts.checkpointStore ?? new InMemoryReactionCheckpointStore();
     }
     /** Register a peer persona and record it in the group membership (lineage). */
     addPeer(personaId, spec = {}) {
@@ -37,19 +40,47 @@ export class ReactiveSession {
      */
     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) });
+        const eventIdentity = bbEvent.idempotencyKey ?? `seq:${bbEvent.seq}`;
+        const checkpointKey = JSON.stringify([this.opts.runGroup.id, eventIdentity]);
+        const checkpoint = await this.checkpointStore.claim(checkpointKey, this.opts.reactionLeaseMs);
+        if (checkpoint.status === "completed")
+            return checkpoint.reactions;
+        if (checkpoint.status === "busy")
+            throw new ReactionInProgressError(checkpointKey);
+        const receipt = checkpoint.claim;
+        try {
+            const candidates = [...this.peerSpecs.entries()]
+                .map(([personaId, spec]) => ({ personaId, role: spec.role, channels: spec.channels }))
+                .filter(p => isVisibleTo(bbEvent, p));
+            const eligible = new Set(candidates.map(p => p.personaId));
+            const selected = checkpoint.claim.plan
+                ?? (await this.opts.turnPolicy(bbEvent, candidates, this.policyState)).filter(id => eligible.has(id));
+            const plan = await this.checkpointStore.savePlan(receipt, selected);
+            if (!plan)
+                throw new Error("reaction checkpoint lease was lost before saving the plan");
+            const outputs = new Map(Object.entries(checkpoint.claim.outputs));
+            const reactions = [];
+            for (const personaId of plan) {
+                let output = outputs.get(personaId);
+                if (output === undefined) {
+                    if (!eligible.has(personaId))
+                        throw new Error(`reaction persona is unavailable: ${personaId}`);
+                    output = await this.driveTurn(personaId, bbEvent);
+                    if (!await this.checkpointStore.record(receipt, { personaId, output })) {
+                        throw new Error("reaction checkpoint lease was lost before recording output");
+                    }
+                }
+                reactions.push({ personaId, output });
+            }
+            if (!await this.checkpointStore.complete(receipt)) {
+                throw new Error("reaction checkpoint lease was lost before completion");
+            }
+            return reactions;
+        }
+        catch (cause) {
+            await this.checkpointStore.release(receipt);
+            throw cause;
         }
-        return reactions;
     }
     /** Targeted preemption: deliver a critical signal to one persona's loop only (L0 recipient routing). */
     async interrupt(personaId, signal) {
@@ -64,13 +95,12 @@ export class ReactiveSession {
     }
     /** Broadcast a signal to every persona (each sees it on its next turn). */
     async broadcast(signal) {
-        this.gateway.ingest({
+        this.gateway.broadcast(this.peers(), {
             source: "gateway",
             signalType: "event",
             urgency: "normal",
             payload: signal.payload ?? {},
             ...signal,
-            recipient: undefined,
         });
     }
     getRunner(personaId) {

package/dist/runtime/reliability.d.ts

@@ -0,0 +1,48 @@
+/** A failure raised by an observer after the owning mutation has already committed. */
+export interface ObserverFailure {
+    component: string;
+    operation: string;
+    cause: unknown;
+    committed: true;
+}
+export type ObserverErrorHandler = (failure: ObserverFailure) => void;
+/** Immutable identity and cancellation boundary for one runtime operation. */
+export interface OperationContext {
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly agentId?: string;
+    readonly signal: AbortSignal;
+    readonly deadlineMs?: number;
+    readonly provenance?: Readonly<Record<string, string>>;
+}
+export interface BackgroundTaskFailure {
+    readonly label: string;
+    readonly operation: OperationContext;
+    readonly cause: unknown;
+}
+export type BackgroundTaskErrorHandler = (failure: BackgroundTaskFailure) => void;
+/** Compose an adapter timeout with the operation cancellation/deadline boundary. */
+export declare function operationAbortSignal(operation: OperationContext | undefined, timeoutMs: number, now?: () => number): AbortSignal;
+/** Report an observer failure without allowing the reporter to change the committed result. */
+export declare function reportObserverFailure(handler: ObserverErrorHandler | undefined, failure: Omit<ObserverFailure, "committed">): void;
+/**
+ * Serialize async mutations by owner key while allowing unrelated keys to proceed concurrently.
+ * The queued tail is always resolved, so one failed mutation cannot poison later operations.
+ */
+export declare class KeyedSerialExecutor {
+    private readonly tails;
+    run<T>(key: string, operation: () => Promise<T>): Promise<T>;
+}
+/** Owns best-effort asynchronous work for exactly one operation. */
+export declare class ManagedTaskScope {
+    private readonly onTaskError?;
+    private readonly tasks;
+    private readonly controller;
+    private closed;
+    readonly operation: OperationContext;
+    constructor(operation: OperationContext, onTaskError?: BackgroundTaskErrorHandler | undefined);
+    get pending(): number;
+    spawn(label: string, work: (operation: OperationContext) => Promise<void> | void): void;
+    drain(): Promise<void>;
+    cancel(reason?: unknown): Promise<void>;
+}

package/dist/runtime/reliability.js

@@ -0,0 +1,86 @@
+/** Compose an adapter timeout with the operation cancellation/deadline boundary. */
+export function operationAbortSignal(operation, timeoutMs, now = Date.now) {
+    const remaining = operation?.deadlineMs === undefined
+        ? timeoutMs
+        : Math.min(timeoutMs, operation.deadlineMs - now());
+    const timeout = remaining <= 0
+        ? AbortSignal.abort(new Error("operation deadline exceeded"))
+        : AbortSignal.timeout(remaining);
+    return operation ? AbortSignal.any([operation.signal, timeout]) : timeout;
+}
+/** Report an observer failure without allowing the reporter to change the committed result. */
+export function reportObserverFailure(handler, failure) {
+    try {
+        handler?.({ ...failure, committed: true });
+    }
+    catch {
+        // The reporter is itself an observer. There is no additional semantic owner to fail here.
+    }
+}
+/**
+ * Serialize async mutations by owner key while allowing unrelated keys to proceed concurrently.
+ * The queued tail is always resolved, so one failed mutation cannot poison later operations.
+ */
+export class KeyedSerialExecutor {
+    tails = new Map();
+    async run(key, operation) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let release;
+        const gate = new Promise(resolve => { release = resolve; });
+        const tail = previous.then(() => gate);
+        this.tails.set(key, tail);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            void tail.then(() => {
+                if (this.tails.get(key) === tail)
+                    this.tails.delete(key);
+            });
+        }
+    }
+}
+/** Owns best-effort asynchronous work for exactly one operation. */
+export class ManagedTaskScope {
+    onTaskError;
+    tasks = new Set();
+    controller = new AbortController();
+    closed = false;
+    operation;
+    constructor(operation, onTaskError) {
+        this.onTaskError = onTaskError;
+        this.operation = {
+            ...operation,
+            signal: AbortSignal.any([operation.signal, this.controller.signal]),
+        };
+    }
+    get pending() {
+        return this.tasks.size;
+    }
+    spawn(label, work) {
+        if (this.closed)
+            throw new Error("task scope is closed");
+        const task = Promise.resolve()
+            .then(() => work(this.operation))
+            .catch(cause => {
+            try {
+                this.onTaskError?.({ label, operation: this.operation, cause });
+            }
+            catch {
+                // Failure reporting is observational and cannot own the task result.
+            }
+        })
+            .finally(() => { this.tasks.delete(task); });
+        this.tasks.add(task);
+    }
+    async drain() {
+        this.closed = true;
+        await Promise.all([...this.tasks]);
+    }
+    async cancel(reason) {
+        this.controller.abort(reason);
+        await this.drain();
+    }
+}

package/dist/runtime/remote-vpc-plane.js

@@ -1,5 +1,6 @@
 import { LocalExecutionPlane } from "./execution-plane.js";
 import { formatToolError } from "../tools/errors.js";
+import { operationAbortSignal } from "./reliability.js";
 /**
  * ExecutionPlane that forwards tool calls over HTTP to a worker inside a customer VPC.
  *
@@ -48,7 +49,7 @@ export class RemoteVpcPlane {
         if (auth)
             headers["Authorization"] = auth;
         // Fire all remote calls concurrently; yield results in dispatch order
-        const pending = remoteCalls.map(call => this.callRemote(call, headers).then(result => ({ call, result })));
+        const pending = remoteCalls.map(call => this.callRemote(call, headers, ctx.operation).then(result => ({ call, result })));
         for (const p of pending) {
             const { call, result } = await p;
             yield {
@@ -60,14 +61,14 @@ export class RemoteVpcPlane {
             };
         }
     }
-    async callRemote(call, headers) {
+    async callRemote(call, headers, operation) {
         try {
             const args = JSON.parse(call.arguments || "{}");
             const response = await fetch(`${this.opts.baseUrl}/execute`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify({ name: call.name, arguments: args }),
-                signal: AbortSignal.timeout(this.opts.timeoutMs ?? 30_000),
+                signal: operationAbortSignal(operation, this.opts.timeoutMs ?? 30_000),
             });
             if (!response.ok) {
                 const body = await response.text().catch(() => "");

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

@@ -1,21 +1,3 @@
-/**
- * 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 {
     /** ③ loop-agent rounds completed across the group (seeds the pacing trap's max_rounds). */
@@ -32,6 +14,19 @@ export interface GroupCharge {
     /** ③ loop-agent: completed rounds to add to the group's round count. */
     rounds?: number;
 }
+export interface GroupBudgetRequest {
+    /** Group-wide hard limits. An omitted axis is unbounded for this admission. */
+    limits: GroupCharge;
+    /** Maximum capacity this member wants to hold for its lifetime. */
+    requested: GroupCharge;
+}
+export interface GroupBudgetReservation {
+    id: string;
+    groupId: string;
+    memberId: string;
+    /** Capacity granted to this member. May be lower than requested when the group is nearly full. */
+    granted: GroupCharge;
+}
 /** A persona session that participated in the logical run (process-table lineage). */
 export interface GroupMember {
     sessionId: string;
@@ -43,36 +38,44 @@ export interface GroupMember {
     kind?: "peer" | "vehicle";
 }
 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[]>;
+    reserve(groupId: string, request: GroupBudgetRequest & {
+        memberId: string;
+    }): GroupBudgetReservation | Promise<GroupBudgetReservation>;
+    /** Idempotently replace a reservation with actual usage. */
+    settle(groupId: string, reservationId: string, actual: GroupCharge): void | Promise<void>;
+    /** Idempotently discard an unused reservation. */
+    release(groupId: string, reservationId: string): void | Promise<void>;
 }
 /** Process-local default store. One ledger + member set per group id. */
 export declare class InMemoryGroupBudgetStore implements GroupBudgetStore {
     private readonly ledgers;
     private readonly memberships;
+    private readonly reservations;
     read(groupId: string): GroupLedger;
-    charge(groupId: string, delta: GroupCharge): void;
+    private applyCharge;
     join(groupId: string, member: GroupMember): void;
     members(groupId: string): GroupMember[];
+    reserve(groupId: string, request: GroupBudgetRequest & {
+        memberId: string;
+    }): GroupBudgetReservation;
+    settle(groupId: string, reservationId: string, actual: GroupCharge): void;
+    release(groupId: string, reservationId: string): void;
 }
-/**
- * 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[]>;
+/** One member's reservation lifecycle. */
+export declare class GroupBudgetScope {
+    private readonly group;
+    readonly granted: GroupCharge;
+    readonly reservationId: string;
+    private closed;
+    private constructor();
+    static open(group: RunGroup, member: GroupMember, request: GroupBudgetRequest): Promise<GroupBudgetScope>;
+    settle(actual: GroupCharge): Promise<void>;
+    get isClosed(): boolean;
+    release(): Promise<void>;
 }
 /** Binds a runner to a governance domain: a stable group id + the store its members share. */
 export interface RunGroup {