@stackstackstack/dsh-agent 0.1.5

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/** Package-owned agent lifecycle invariants. @module @stackstackstack/dsh-agent/invariant */
+const PACKAGE_NAME = "@stackstackstack/dsh-agent";
+/** Cordis companion plugin name. */
+const name = "agent-invariant";
+/** Services required before the companion can register. */
+const inject = ["invariants"];
+/** Install the agent contribution into its child registration fiber. */
+const install = (ctx, fail) => {
+	const lastStatus = /* @__PURE__ */ new WeakMap();
+	ctx.on("agent/status", ({ agent, status }) => {
+		if (lastStatus.get(agent) === status) fail(`agent/status repeated ${status} (no-op transition)`);
+		lastStatus.set(agent, status);
+	}, { global: true });
+};
+/**
+* Register the agent invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/consumed-work.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How one agent log accounts for the work it consumed.
+ *
+ * The turn and step vocabulary alone cannot answer this. A turn that stops
+ * before its first step leaves a `turn/end` shaped exactly like the balanced
+ * no-op turns a rejection or an empty claim produces, so reading turns in
+ * isolation either credits cut-short work as finished or convicts every no-op.
+ * The missing fact is the inbox's own record: {@link Inbox} logs each mutation
+ * with `removedCount` and marks a cancellation `outcome: 'canceled'`, which
+ * separates a turn claiming its input from work being dropped unrun.
+ *
+ * @module @stackstackstack/dsh-agent/consumed-work
+ */
+import type { SessionEvent } from '@stackstackstack/dsh-session';
+/** How one agent log accounts for the work it consumed. */
+export interface ConsumedWork {
+    /**
+     * The latest closed turn that accounts for consumed work: one that entered a
+     * model step, or one that claimed inbox input and then failed, was stopped,
+     * or was rejected. Absent when no turn closed over any work.
+     */
+    readonly end?: SessionEvent<'turn/end'>;
+    /**
+     * Whether accepted work was cancelled out of the inbox, unrun, after that
+     * turn. This is the only account of input a cancellation took before any turn
+     * could open over it — no `turn/end` describes it.
+     */
+    readonly droppedUnrun: boolean;
+}
+/**
+ * Fold one agent log, or an owned suffix of one, into its account of consumed
+ * work. Single pass, and every input is the log itself: no caller has to sample
+ * live state before cancelling, so a cancellation issued by anyone — the owner's
+ * teardown, an ancestor's interrupt, an unloading plugin — reads the same.
+ * @param events - the log, or an owned suffix, to fold.
+ * @returns the accounting turn when one closed, and whether work was dropped unrun after it.
+ */
+export declare function foldConsumedWork(events: readonly SessionEvent[]): ConsumedWork;
+//# sourceMappingURL=consumed-work.d.ts.map

package/lib/types/consumed-work.js

@@ -0,0 +1,92 @@
+/**
+ * How one agent log accounts for the work it consumed.
+ *
+ * The turn and step vocabulary alone cannot answer this. A turn that stops
+ * before its first step leaves a `turn/end` shaped exactly like the balanced
+ * no-op turns a rejection or an empty claim produces, so reading turns in
+ * isolation either credits cut-short work as finished or convicts every no-op.
+ * The missing fact is the inbox's own record: {@link Inbox} logs each mutation
+ * with `removedCount` and marks a cancellation `outcome: 'canceled'`, which
+ * separates a turn claiming its input from work being dropped unrun.
+ *
+ * @module @stackstackstack/dsh-agent/consumed-work
+ */
+/**
+ * Whether a turn that consumed input but never reached a step ends in a way
+ * that accounts for that input. Only a `completed` end does not: it had
+ * nothing left to run once its claim was rewritten away. A `blocked` end is
+ * that input's ending too — the pre-step rejection that produced it discarded
+ * the claimed messages, so the work it took will never run.
+ * @param reason - the turn's recorded ending.
+ * @returns whether the ending accounts for the input the turn took.
+ */
+function accountsForClaim(reason) {
+    switch (reason.kind) {
+        case 'completed':
+            return false;
+        case 'blocked':
+        case 'aborted':
+        case 'interrupted':
+        case 'error':
+            return true;
+        /* v8 ignore next 4 -- unreachable: the one unnamed built-in, `max-tokens`, requires a step,
+         * so its turn short-circuits as stepped before this call, and `TurnEndReasonMap` is
+         * merge-extensible, so a backend-added variant cannot be listed; an unnameable ending over
+         * consumed input must not read as success. */
+        default:
+            return true;
+    }
+}
+/**
+ * Fold one agent log, or an owned suffix of one, into its account of consumed
+ * work. Single pass, and every input is the log itself: no caller has to sample
+ * live state before cancelling, so a cancellation issued by anyone — the owner's
+ * teardown, an ancestor's interrupt, an unloading plugin — reads the same.
+ * @param events - the log, or an owned suffix, to fold.
+ * @returns the accounting turn when one closed, and whether work was dropped unrun after it.
+ */
+export function foldConsumedWork(events) {
+    const stepped = new Set();
+    const claimed = new Set();
+    let open;
+    let end;
+    let droppedUnrun = false;
+    for (const event of events) {
+        switch (event.type) {
+            case 'turn/start':
+                open = event.data.turn;
+                break;
+            case 'step/start':
+                stepped.add(event.data.turn);
+                break;
+            case 'agent/inbox/spliced': {
+                const { removedCount, outcome, inserted } = event.data;
+                if (removedCount === undefined)
+                    break;
+                // A replacement keeps the work pending under a new identity, so only a
+                // cancellation that leaves nothing behind drops it.
+                if (outcome === 'canceled')
+                    droppedUnrun ||= inserted.length === 0;
+                // Claims are the loop's own step-boundary reads, always inside a turn.
+                else if (open !== undefined)
+                    claimed.add(open);
+                break;
+            }
+            case 'turn/end': {
+                const { turn, reason } = event.data;
+                open = undefined;
+                if (stepped.delete(turn) || (claimed.delete(turn) && accountsForClaim(reason))) {
+                    end = event;
+                    // Anything dropped before this turn closed is what its own ending
+                    // reports; only a later drop is still unaccounted for.
+                    droppedUnrun = false;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return { ...end === undefined ? {} : { end }, droppedUnrun };
+}
+//# sourceMappingURL=consumed-work.js.map

package/lib/types/dispatch.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Agent-scoped dispatch and prompt assembly helpers. The fused dispatcher
+ * {@link agentEvents} couples the agent subject to its scope carrier, so the
+ * scope key and the payload's `agent` cannot diverge; repeat dispatchers (the
+ * loop driver) build it once in the agent's constructor and reuse it.
+ * @module @stackstackstack/dsh-agent/dispatch
+ */
+import type { Context, Events } from '@deepseek-ai/cordis';
+import type { Scoped } from '@stackstackstack/dsh-scope';
+import type { AssembleContext } from '@stackstackstack/dsh-system-prompt';
+import type { Agent } from './runtime-types.ts';
+/** Extract the parameter tuple from an event handler type (its `this` is not part of the tuple). */
+type Params<F> = F extends (...args: infer P) => unknown ? P : never;
+/** Extract the return type from an event handler type. */
+type Return<F> = F extends (...args: never[]) => infer R ? R : never;
+/**
+ * The event names whose subject is an agent: the handler's first parameter is
+ * a payload object carrying the `agent` subject AND the handler declares a
+ * `Scoped<Agent>` `this` (the scope-carrier contract). The `this` check keeps
+ * accidental payload-happens-to-carry-an-Agent events (or zero-arg events,
+ * whose parameter tuple would satisfy a bare rest-tuple check via callability)
+ * out of the fused-dispatch surface.
+ */
+export type AgentSubjectEvent = {
+    [K in keyof Events]: Events[K] extends (this: Scoped<Agent>, ...args: infer P) => unknown ? P extends [infer Payload, ...unknown[]] ? Payload extends {
+        agent: Agent;
+    } ? K : never : never : never;
+}[keyof Events];
+/** The full payload object of one agent-subject event. */
+type PayloadOf<K extends AgentSubjectEvent> = Params<Events[K]> extends [infer Payload, ...unknown[]] ? Payload : never;
+/** The event arguments AFTER the payload: the waterfall `next` when present. */
+type Tail<K extends AgentSubjectEvent> = Params<Events[K]> extends [unknown, ...infer R] ? R : never;
+/**
+ * The payload as emit-side callers pass it: the full payload minus the agent
+ * field, which the fused dispatcher injects so subject and scope key cannot
+ * diverge.
+ */
+type PayloadRest<K extends AgentSubjectEvent> = Omit<PayloadOf<K> & object, 'agent'>;
+/**
+ * The fused dispatcher {@link agentEvents} returns: each method dispatches the
+ * named agent-subject event with the agent's scope carrier as `thisArg` and
+ * the agent itself injected into the payload.
+ */
+export interface AgentEventDispatch {
+    /**
+     * Fire-and-forget notification in the agent's scope. Every listener is
+     * invoked; synchronous throws and returned-promise rejections are logged and
+     * contained per listener, so a notification cannot veto lifecycle progress
+     * or starve a later observer.
+     * @param name - the agent-subject event to emit.
+     * @param payload - the event's payload fields; `agent` is injected.
+     */
+    emit<K extends AgentSubjectEvent>(name: K, payload: PayloadRest<K>): void;
+    /**
+     * Awaited in-order dispatch (Cordis `serial`) in the agent's scope.
+     * @param name - the agent-subject event to dispatch.
+     * @param payload - the event's payload fields; `agent` is injected.
+     * @returns the serial chain's result (the first bail value, if any).
+     */
+    serial<K extends AgentSubjectEvent>(name: K, payload: PayloadRest<K>): Promise<Awaited<Return<Events[K]>>>;
+    /**
+     * Around-middleware dispatch (Cordis `waterfall`) in the agent's scope. The
+     * declared event parameters already end with the `next` callback, so `rest`
+     * is exactly the event's arguments after the payload — the final element
+     * being the innermost `next` (the default the listener chain wraps).
+     * @param name - the agent-subject event to dispatch.
+     * @param payload - the event's payload fields; `agent` is injected.
+     * @param rest - the event's arguments after the payload (the `next` callback).
+     * @returns the waterfall's composed result.
+     */
+    waterfall<K extends AgentSubjectEvent>(name: K, payload: PayloadRest<K>, ...rest: Tail<K>): Return<Events[K]>;
+}
+/**
+ * Build the fused scope carrier for one agent subject.
+ *
+ * The carrier is a stateless routing object. {@link agentEvents} accepts an
+ * existing carrier, so callers that dispatch repeatedly for the same agent
+ * (the loop driver) build it once in the agent's constructor and reuse it,
+ * keeping hot-path dispatches allocation-free.
+ * @param agent - the subject agent and scope key.
+ * @returns the carrier passed as the event dispatcher `this` value.
+ */
+export declare function agentCarrier(agent: Agent): Scoped<Agent>;
+/**
+ * Build a dispatcher that couples the agent subject to its scope carrier.
+ * @param ctx - the context to dispatch through (any context of the app).
+ * @param agent - the subject agent; also the scope-carrier key.
+ * @param carrier - the scope carrier to dispatch through; defaults to
+ * {@link agentCarrier} for the agent. Pass a constructor-built carrier to
+ * avoid rebuilding it for every dispatch.
+ * @returns the fused dispatcher.
+ */
+export declare function agentEvents(ctx: Context, agent: Agent, carrier?: Scoped<Agent>): AgentEventDispatch;
+/**
+ * Emit one contained agent notification without allocating a retained dispatcher.
+ * @param ctx - the context to dispatch through.
+ * @param agent - the subject agent and scope key.
+ * @param name - the agent-subject event to emit.
+ * @param payload - the event's payload fields; `agent` is injected.
+ */
+export declare function emitAgentEvent<K extends AgentSubjectEvent>(ctx: Context, agent: Agent, name: K, payload: PayloadRest<K>): void;
+/**
+ * Build the prompt assembly context with agent and scope set together, so
+ * agent-scoped prompt and tool contributions cannot be silently omitted.
+ * @param agent - the agent the assembly is for.
+ * @param signal - the current turn's explicit control signal, when assembly belongs to a turn.
+ * @returns the context to pass to `assemble()`.
+ */
+export declare function assembleContextFor(agent: Agent, signal?: AbortSignal): AssembleContext;
+export {};
+//# sourceMappingURL=dispatch.d.ts.map

package/lib/types/dispatch.js

@@ -0,0 +1,95 @@
+/**
+ * Agent-scoped dispatch and prompt assembly helpers. The fused dispatcher
+ * {@link agentEvents} couples the agent subject to its scope carrier, so the
+ * scope key and the payload's `agent` cannot diverge; repeat dispatchers (the
+ * loop driver) build it once in the agent's constructor and reuse it.
+ * @module @stackstackstack/dsh-agent/dispatch
+ */
+import { scopeTarget } from '@stackstackstack/dsh-scope';
+/**
+ * Build the fused scope carrier for one agent subject.
+ *
+ * The carrier is a stateless routing object. {@link agentEvents} accepts an
+ * existing carrier, so callers that dispatch repeatedly for the same agent
+ * (the loop driver) build it once in the agent's constructor and reuse it,
+ * keeping hot-path dispatches allocation-free.
+ * @param agent - the subject agent and scope key.
+ * @returns the carrier passed as the event dispatcher `this` value.
+ */
+export function agentCarrier(agent) {
+    return scopeTarget(agent, agent);
+}
+/**
+ * Build a dispatcher that couples the agent subject to its scope carrier.
+ * @param ctx - the context to dispatch through (any context of the app).
+ * @param agent - the subject agent; also the scope-carrier key.
+ * @param carrier - the scope carrier to dispatch through; defaults to
+ * {@link agentCarrier} for the agent. Pass a constructor-built carrier to
+ * avoid rebuilding it for every dispatch.
+ * @returns the fused dispatcher.
+ */
+export function agentEvents(ctx, agent, carrier = agentCarrier(agent)) {
+    // The ordinary dispatch methods forward through Cordis' variadic mixins. The
+    // fused (carrier, name, payload, ...rest) tuple is provably a valid argument
+    // list for the matching thisArg overload, but TypeScript cannot relate the
+    // generic Tail<K> spread back to that overload's conditional parameter
+    // tuple — hence one contained, shape-preserving cast per method.
+    const fused = (payload) => 
+    // The dispatcher owns the subject injection; callers pass PayloadRest, so
+    // the fused record is exactly the declared payload. The spread comes
+    // first, so a structurally acceptable payload that happens to carry an
+    // `agent` field can never override the injected subject.
+    ({ ...payload, agent });
+    return {
+        emit(name, payload) {
+            // Cordis emit invokes callbacks through Array.map: one synchronous throw
+            // starves later listeners, and returned promises are discarded. Agent
+            // notifications are non-vetoing, so resolve the same filtered callback
+            // set ourselves and contain both failure modes independently.
+            const args = [carrier, name, fused(payload)];
+            const callbacks = ctx.events.dispatch('emit', args);
+            for (const callback of callbacks) {
+                try {
+                    const returned = callback(...args);
+                    void Promise.resolve(returned).catch((error) => {
+                        ctx.logger.warn(`agent event "${name}" listener rejected: ${String(error)}`);
+                    });
+                }
+                catch (error) {
+                    ctx.logger.warn(`agent event "${name}" listener threw: ${String(error)}`);
+                }
+            }
+        },
+        async serial(name, payload) {
+            // oxlint-disable-next-line typescript/unbound-method -- the events mixin accessor returns a pre-bound function
+            const serial = ctx.serial;
+            return await serial(carrier, name, fused(payload));
+        },
+        waterfall(name, payload, ...rest) {
+            // oxlint-disable-next-line typescript/unbound-method -- the events mixin accessor returns a pre-bound function
+            const waterfall = ctx.waterfall;
+            return waterfall(carrier, name, fused(payload), ...rest);
+        },
+    };
+}
+/**
+ * Emit one contained agent notification without allocating a retained dispatcher.
+ * @param ctx - the context to dispatch through.
+ * @param agent - the subject agent and scope key.
+ * @param name - the agent-subject event to emit.
+ * @param payload - the event's payload fields; `agent` is injected.
+ */
+export function emitAgentEvent(ctx, agent, name, payload) {
+    agentEvents(ctx, agent).emit(name, payload);
+}
+/**
+ * Build the prompt assembly context with agent and scope set together, so
+ * agent-scoped prompt and tool contributions cannot be silently omitted.
+ * @param agent - the agent the assembly is for.
+ * @param signal - the current turn's explicit control signal, when assembly belongs to a turn.
+ * @returns the context to pass to `assemble()`.
+ */
+export function assembleContextFor(agent, signal) {
+    return { agent, scope: agent, ...signal === undefined ? {} : { signal } };
+}
+//# sourceMappingURL=dispatch.js.map

package/lib/types/inbox.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Incremental projection of durable agent inbox events.
+ *
+ * @module @stackstackstack/dsh-agent/inbox
+ */
+import type { MessageId } from '@stackstackstack/dsh-llm';
+import type { Session, UserMessage } from '@stackstackstack/dsh-session';
+import type { InboxTarget } from './types.ts';
+/** Live notifications committed by inbox mutations. */
+export interface InboxNotifications {
+    /** Publish one inserted message. */
+    inserted(message: UserMessage): void;
+    /** Publish one discarded message. */
+    discarded(message: UserMessage): void;
+    /** Publish one claimed message inside its owning turn. */
+    claimed(message: UserMessage, turn: number): void;
+}
+/** A replay-once projection that incrementally consumes later inbox splices. */
+export declare class Inbox {
+    private readonly session;
+    private readonly notifications;
+    private readonly state;
+    constructor(session: Session, notifications: InboxNotifications);
+    /** Prompts awaiting individual turns. */
+    get nextTurn(): readonly UserMessage[];
+    /** Input awaiting the next step boundary. */
+    get nextStep(): readonly UserMessage[];
+    /** Whether either pending-message list contains work. */
+    get hasPending(): boolean;
+    /** Durably cancel all pending input, clearing next-step before next-turn. */
+    clear(): void;
+    /**
+     * Remove and return the complete batch proposed for one step, publishing
+     * each claimed message. The durable splices are pure deletions.
+     * @param target - whether this boundary also consumes one queued turn.
+     * @param turn - turn that will own the claimed batch.
+     * @returns next-step input followed by the queued turn, when requested.
+     * @internal - The agent loop's step-boundary operation, not a plugin extension point.
+     */
+    claim(target: InboxTarget, turn: number): UserMessage[];
+    /**
+     * Append one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to append.
+     * @throws if the message identity is already pending.
+     */
+    append(target: InboxTarget, message: UserMessage): void;
+    /**
+     * Prepend one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to prepend.
+     * @throws if the message identity is already pending.
+     */
+    prepend(target: InboxTarget, message: UserMessage): void;
+    /**
+     * Replace one pending message in place, possibly changing its identity. A
+     * successful replacement publishes the old message as discarded and the new
+     * message as inserted.
+     * @param messageId - identity of the pending message to replace.
+     * @param newMessage - replacement message.
+     * @returns whether the message was still pending.
+     * @throws if the replacement duplicates another pending message identity.
+     */
+    replace(messageId: MessageId, newMessage: UserMessage): boolean;
+    /**
+     * Remove one pending message and durably record its cancellation.
+     * @param messageId - identity of the pending message to remove.
+     * @returns whether the message was still pending.
+     */
+    remove(messageId: MessageId): boolean;
+    /**
+     * Apply standard splice semantics and durably record the normalized result.
+     * The durable event commits before the live projection mutates, so synchronous
+     * `session/event` observers see the pre-splice lists and can reconstruct the
+     * removed messages from the normalized coordinates.
+     * @param target - pending list to mutate.
+     * @param start - splice position.
+     * @param deleteCount - maximum number of messages to remove.
+     * @param inserted - messages to insert at the resolved position.
+     * @returns messages removed by the splice.
+     */
+    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];
+    /** Locate one pending identity across both owned lists. */
+    private locate;
+    /** Commit one normalized mutation and publish its live notifications. */
+    private mutate;
+    /** Apply one normalized durable splice to the projection. */
+    private apply;
+    /** Validate one normalized splice against the current projection. */
+    private validate;
+}
+//# sourceMappingURL=inbox.d.ts.map

package/lib/types/inbox.js

@@ -0,0 +1,185 @@
+/**
+ * Incremental projection of durable agent inbox events.
+ *
+ * @module @stackstackstack/dsh-agent/inbox
+ */
+/** A replay-once projection that incrementally consumes later inbox splices. */
+export class Inbox {
+    session;
+    notifications;
+    state = { 'next-turn': [], 'next-step': [] };
+    constructor(session, notifications) {
+        this.session = session;
+        this.notifications = notifications;
+        for (const event of session.events.slice(session.header.seedLength ?? 0)) {
+            if (event.type !== 'agent/inbox/spliced')
+                continue;
+            try {
+                this.apply(event.data);
+            }
+            catch (error) {
+                throw new Error(`invalid persisted inbox splice at session seq ${event.seq}`, { cause: error });
+            }
+        }
+    }
+    /** Prompts awaiting individual turns. */
+    get nextTurn() {
+        return this.state['next-turn'];
+    }
+    /** Input awaiting the next step boundary. */
+    get nextStep() {
+        return this.state['next-step'];
+    }
+    /** Whether either pending-message list contains work. */
+    get hasPending() {
+        return this.nextTurn.length > 0 || this.nextStep.length > 0;
+    }
+    /** Durably cancel all pending input, clearing next-step before next-turn. */
+    clear() {
+        this.splice('next-step', 0, this.nextStep.length, []);
+        this.splice('next-turn', 0, this.nextTurn.length, []);
+    }
+    /**
+     * Remove and return the complete batch proposed for one step, publishing
+     * each claimed message. The durable splices are pure deletions.
+     * @param target - whether this boundary also consumes one queued turn.
+     * @param turn - turn that will own the claimed batch.
+     * @returns next-step input followed by the queued turn, when requested.
+     * @internal - The agent loop's step-boundary operation, not a plugin extension point.
+     */
+    claim(target, turn) {
+        const claimed = this.mutate('next-step', 0, this.nextStep.length, [], false);
+        if (target === 'next-turn') {
+            claimed.push(...this.mutate('next-turn', 0, 1, [], false));
+        }
+        for (const message of claimed)
+            this.notifications.claimed(message, turn);
+        return claimed;
+    }
+    /**
+     * Append one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to append.
+     * @throws if the message identity is already pending.
+     */
+    append(target, message) {
+        this.splice(target, this.state[target].length, 0, [message]);
+    }
+    /**
+     * Prepend one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to prepend.
+     * @throws if the message identity is already pending.
+     */
+    prepend(target, message) {
+        this.splice(target, 0, 0, [message]);
+    }
+    /**
+     * Replace one pending message in place, possibly changing its identity. A
+     * successful replacement publishes the old message as discarded and the new
+     * message as inserted.
+     * @param messageId - identity of the pending message to replace.
+     * @param newMessage - replacement message.
+     * @returns whether the message was still pending.
+     * @throws if the replacement duplicates another pending message identity.
+     */
+    replace(messageId, newMessage) {
+        const location = this.locate(messageId);
+        if (location === undefined)
+            return false;
+        this.splice(location.target, location.index, 1, [newMessage]);
+        return true;
+    }
+    /**
+     * Remove one pending message and durably record its cancellation.
+     * @param messageId - identity of the pending message to remove.
+     * @returns whether the message was still pending.
+     */
+    remove(messageId) {
+        const location = this.locate(messageId);
+        if (location === undefined)
+            return false;
+        this.splice(location.target, location.index, 1, []);
+        return true;
+    }
+    /**
+     * Apply standard splice semantics and durably record the normalized result.
+     * The durable event commits before the live projection mutates, so synchronous
+     * `session/event` observers see the pre-splice lists and can reconstruct the
+     * removed messages from the normalized coordinates.
+     * @param target - pending list to mutate.
+     * @param start - splice position.
+     * @param deleteCount - maximum number of messages to remove.
+     * @param inserted - messages to insert at the resolved position.
+     * @returns messages removed by the splice.
+     */
+    splice(target, start, deleteCount, inserted) {
+        return this.mutate(target, start, deleteCount, inserted, true);
+    }
+    /** Locate one pending identity across both owned lists. */
+    locate(messageId) {
+        for (const target of ['next-turn', 'next-step']) {
+            const index = this.state[target].findIndex(message => message.id === messageId);
+            if (index >= 0)
+                return { target, index };
+        }
+        return undefined;
+    }
+    /** Commit one normalized mutation and publish its live notifications. */
+    mutate(target, start, deleteCount, inserted, discardRemoved) {
+        const inbox = this.state[target];
+        const truncatedStart = Math.trunc(start);
+        const offset = Number.isNaN(truncatedStart) ? 0 : truncatedStart;
+        const actualStart = offset < 0
+            ? Math.max(inbox.length + offset, 0)
+            : Math.min(offset, inbox.length);
+        const truncatedDeleteCount = Math.trunc(deleteCount);
+        const actualDeleteCount = Math.min(Math.max(Number.isNaN(truncatedDeleteCount) ? 0 : truncatedDeleteCount, 0), inbox.length - actualStart);
+        if (actualDeleteCount === 0 && inserted.length === 0)
+            return [];
+        const outcome = discardRemoved && actualDeleteCount > 0 ? 'canceled' : undefined;
+        const splice = {
+            target,
+            start: actualStart,
+            ...(actualDeleteCount === 0 ? {} : { removedCount: actualDeleteCount }),
+            inserted,
+            ...(outcome === undefined ? {} : { outcome }),
+        };
+        this.validate(splice);
+        const event = this.session.append('agent/inbox/spliced', splice);
+        const removed = inbox.splice(actualStart, actualDeleteCount, ...event.data.inserted);
+        if (discardRemoved) {
+            for (const message of removed)
+                this.notifications.discarded(message);
+        }
+        for (const message of event.data.inserted)
+            this.notifications.inserted(message);
+        return removed;
+    }
+    /** Apply one normalized durable splice to the projection. */
+    apply(splice) {
+        this.validate(splice);
+        const inbox = this.state[splice.target];
+        return inbox.splice(splice.start, splice.removedCount ?? 0, ...splice.inserted);
+    }
+    /** Validate one normalized splice against the current projection. */
+    validate(splice) {
+        const inbox = this.state[splice.target];
+        const removedCount = splice.removedCount ?? 0;
+        if (!Number.isSafeInteger(splice.start) || splice.start < 0 || splice.start > inbox.length
+            || !Number.isSafeInteger(removedCount) || removedCount < 0
+            || splice.start + removedCount > inbox.length) {
+            throw new Error('invalid inbox splice');
+        }
+        const candidate = inbox.toSpliced(splice.start, removedCount, ...splice.inserted);
+        const ids = new Set();
+        for (const message of splice.target === 'next-turn'
+            ? [...candidate, ...this.nextStep]
+            : [...this.nextTurn, ...candidate]) {
+            if (ids.has(message.id))
+                throw new Error(`message "${message.id}" is already pending`);
+            ids.add(message.id);
+        }
+    }
+}
+//# sourceMappingURL=inbox.js.map