@sema-agent/core 7.29.0 → 7.30.0

package/dist/agents/peer-held-queue.js

@@ -10,11 +10,13 @@ export const realPeerClock = {
     clearTimeout: (h) => clearTimeout(h),
 };
 const crashHandlers = new WeakMap();
+export const PEER_HELD_DECISION_MEMORY = PEER_HELD_QUEUE_CAP * 4;
 export function createPeerHeldQueue(key, opts = {}) {
     const cap = opts.cap ?? PEER_HELD_QUEUE_CAP;
     const clock = opts.clock ?? realPeerClock;
     const entries = [];
     const deadlines = new Map();
+    const decisions = new Map();
     let cfg;
     const sinkOrThrow = () => {
         if (cfg === undefined)
@@ -44,6 +46,15 @@ export function createPeerHeldQueue(key, opts = {}) {
     const settleOut = (entry, settlement, reason, receipt) => {
         const sink = sinkOrThrow();
         remove(entry);
+        if (settlement !== "delivered") {
+            decisions.set(entry.seq, settlement);
+            while (decisions.size > PEER_HELD_DECISION_MEMORY) {
+                const oldest = decisions.keys().next();
+                if (oldest.done === true)
+                    break;
+                decisions.delete(oldest.value);
+            }
+        }
         if (receipt !== undefined)
             safe(() => sink.receipt(entry, receipt));
         safe(() => sink.onSettled?.(entry, settlement, reason, entries.length));
@@ -71,7 +82,8 @@ export function createPeerHeldQueue(key, opts = {}) {
         if (sink.inject === undefined)
             return "no_leg";
         try {
-            sink.inject(entry);
+            if (sink.inject(entry) === "deferred")
+                return "no_leg";
         }
         catch {
             settleOut(entry, "dropped", "inject_failed", "dropped");
@@ -80,6 +92,18 @@ export function createPeerHeldQueue(key, opts = {}) {
         settleOut(entry, "delivered", reason, "delivered");
         return "delivered";
     };
+    const reconcile = (present) => {
+        const sink = sinkOrThrow();
+        let retired = 0;
+        for (const entry of [...entries]) {
+            if (present.has(entry.seq))
+                continue;
+            remove(entry);
+            retired += 1;
+            safe(() => sink.onSettled?.(entry, "expired", "superseded", entries.length));
+        }
+        return retired;
+    };
     const rejudge = () => {
         const sink = sinkOrThrow();
         let released = 0;
@@ -151,6 +175,7 @@ export function createPeerHeldQueue(key, opts = {}) {
             safe(() => sink.receipt(entry, "held"));
         },
         rejudge,
+        reconcile,
         settle(seq, decision) {
             const sink = sinkOrThrow();
             const entry = entries.find((e) => e.seq === seq);
@@ -186,6 +211,11 @@ export function createPeerHeldQueue(key, opts = {}) {
         },
         list: () => entries.map((e) => ({ ...e, ...(e.hopChain !== undefined ? { hopChain: [...e.hopChain] } : {}), ...(e.peerMeta !== undefined ? { peerMeta: { ...e.peerMeta } } : {}) })),
         size: () => entries.length,
+        decisions: () => decisions,
+        forgetDecisions(seqs) {
+            for (const seq of seqs)
+                decisions.delete(seq);
+        },
         shutdown() {
             if (cfg === undefined) {
                 entries.length = 0;
@@ -199,6 +229,7 @@ export function createPeerHeldQueue(key, opts = {}) {
         },
     };
     crashHandlers.set(queue, () => {
+        decisions.clear();
         entries.length = 0;
         for (const h of deadlines.values())
             clock.clearTimeout(h);

package/dist/agents/peer-session-drain.d.ts

@@ -1,9 +1,10 @@
 import { type MailboxCrossProcessVerdict, type MailboxStore } from "../core/mailbox-store.js";
-import type { SessionBoxBinding, SystemInjectionPriority, TaskNotificationPayload } from "../core/task-notification.js";
+import { type SessionBoxBinding, type SystemInjectionPriority, type TaskNotificationPayload } from "../core/task-notification.js";
+import { type FrameSettlement } from "../core/frame-settlement.js";
 import { type EngineNotice, type RunnerDeps } from "../core/types.js";
 import { type PermissionModeClass } from "./cross-session-envelope.js";
 import { type CrossSessionInboundSettingLayers } from "./cross-session-judge.js";
-import { type PeerAdmissionConfig } from "./peer-admission.js";
+import { type PeerLaneConfig } from "./peer-admission.js";
 import { type PeerDirectory } from "./peer-directory.js";
 import { createListAgentsTool } from "./list-agents-tool.js";
 import type { AskEffective } from "../core/wiring-manifest.js";
@@ -46,13 +47,34 @@ export declare function judgePeerLaneMount(deps: {
  * revival lane), and a drain per child on a box nobody writes would cost a lease claim per turn on
  * every background agent. `undefined` on every refusal — silently: no host asked for a box here.
  */
-export declare function judgeSessionBoxDrain(deps: Pick<RunnerDeps, "mailboxStore" | "onError">, leg: {
+export declare function judgeSessionBoxDrain(deps: Pick<RunnerDeps, "mailboxStore" | "onError" | "sessionBoxEngineFrames">, leg: {
     sessionId: string;
     scope: string;
     isDelegatedChild: boolean;
 }): SessionBoxBinding | undefined;
-/** The disposition arms of a `peer.inbound_disposition` notice (closed set; `detail.disposition`). */
-export type PeerInboundDisposition = "refused" | "held" | "admission_refused" | "notice_unrouted" | "notice_user_only";
+/** What one pull of the box handed back: the records read (already rendered frames), and what is still waiting. */
+export interface PulledInbox {
+    delivered: TaskNotificationPayload[];
+    /** Records still leased in the box after this pull (the next pull, or the next boundaries, read them). */
+    pending: number;
+    /** How many of the waiting records their sender marked urgent. */
+    urgent: number;
+}
+/** The disposition arms of a `peer.inbound_disposition` notice (closed set; `detail.disposition`).
+ *  #1036 adds `resupply_exhausted`: a record whose frame a compaction summarized away, was
+ *  re-supplied once, and was summarized away AGAIN. It settles (leaves the box) — but as a DISCLOSED
+ *  loss, never as "the model read it". The cap is a bound on delivery attempts; it does not
+ *  manufacture a consumption proof. */
+export type PeerInboundDisposition = "refused" | "held" | "admission_refused" | "notice_unrouted" | "notice_user_only" | "resupply_exhausted";
+/**
+ * #1036 — how many times a record whose frame was summarized away is handed over again before the
+ * drain gives up and discloses. `1` = one repair, i.e. at most two occurrences of one record in one
+ * run. A cap exists because repair that cannot converge is a loop; it is this small because the
+ * second occurrence already says everything the first did. RUN-SCOPED (the ledger is in memory): a
+ * crash or a takeover re-serves the record at `attempt: 1`, the at-least-once posture this lane has
+ * always had, not a new hole.
+ */
+export declare const PEER_RESUPPLY_CAP = 1;
 export interface PeerSessionDrainOptions {
     mailbox: MailboxStore;
     /** This session (the box owner) and this leg's cycle id (the lease owner). */
@@ -64,8 +86,8 @@ export interface PeerSessionDrainOptions {
     inject: (notification: TaskNotificationPayload, opts?: {
         priority?: SystemInjectionPriority;
     }) => void;
-    /** Deployment tuning of the admission gate (the same seat SendMessage reads). */
-    admission?: Partial<PeerAdmissionConfig>;
+    /** The peer lane's knob table (admission gate + delivery budgets + listing window; the same seat SendMessage reads). */
+    lane?: Partial<PeerLaneConfig>;
     /** The recipient's self-token set for the hop check, read live (the run's peer identity ref). */
     ownTokens: () => readonly string[];
     /** The recipient's `crossSessionInbound` layers, read at every drain. */
@@ -74,7 +96,7 @@ export interface PeerSessionDrainOptions {
     selfModeClass: () => PermissionModeClass | "unknown";
     /** This session's display name (its directory row's name), for receipts and idle notices it authors. */
     selfName?: () => string | undefined;
-    /** Awaited ONCE before the first round (a directory lookup that fills `selfName`, say); a rejection is swallowed. */
+    /** Awaited ONCE before the first pass (a directory lookup that fills `selfName`, say); a rejection is swallowed. */
     warmup?: () => Promise<unknown>;
     /** The deployment's `dialogExpiry` (raw; resolved at bind — an out-of-vocabulary value is announced
      *  once through `onError` and the default applies). Absent ⇒ the default (5 m). */
@@ -89,14 +111,55 @@ export interface PeerSessionDrainOptions {
         sessionId: string;
         classification: string;
     }) => void;
+    /** #1036 — the LEG's settlement seam: the receipts the harness records when a frame reaches
+     *  the transcript and the effects the compaction commit beat records. Absent ⇒ the drain mints a
+     *  private one, which is honest but inert: nothing fills it, so every delivered record waits for a
+     *  receipt that never comes and stays parked (at-least-once). Every production binding supplies it. */
+    settlement?: FrameSettlement;
     leaseTtlMs?: number;
     /** Tests: a virtual clock for the held deadlines and idle timers (honored when this process first sees the session). */
     clock?: PeerClock;
 }
 export interface PeerSessionDrain {
-    /** One drain round (serialized: a boundary never overlaps a still-running round). */
+    /**
+     * One drain pass (serialized: a boundary never overlaps a still-running pass).
+     *
+     * @contract cross_session.settled_means_committed_and_not_summarized — a session-box record is acked
+     * only after a frame carrying it has been committed to the transcript and no compaction applied up to
+     * that settlement beat summarized that entry away. A summarized frame is re-supplied once (a new
+     * occurrence of the SAME record: same `task_id`, same `seq`, `attempt: 2`, `resupplied: true`), and a
+     * re-supplied occurrence summarized again settles as `resupply_exhausted`, disclosed — never as seen.
+     * OBSERVABLE: a `compacted` frame counting a not-yet-acked delivered record
+     * (`summarizedCrossSessionMessages >= 1`) is followed, in the same boundary's delivery half, by a
+     * re-supply frame for it or by a `resupply_exhausted` disposition — never by silence; a record
+     * committed and never summarized is never shown twice; no compaction implies no re-supply.
+     */
     drain(): Promise<void>;
-    /** Run end: ack the last batch and release the lease so the session's next cycle claims at once. */
+    /**
+     * The PULL face (the `ReadInbox` tool): one pass over the same box, same cursor, same judgments —
+     * but the records are RETURNED instead of injected, up to `limit` (default = the pass budget). A
+     * record a boundary already handed over is never returned again, and a record returned here is
+     * never injected later: one cursor (`settledUpTo`), two readers. Never acks (the next boundary does).
+     */
+    pull(limit?: number, toolCallId?: string, charBudget?: number): Promise<PulledInbox>;
+    /**
+     * #1036 — THE TURN BOUNDARY's pass, called by the boundary lane as its tail so it runs AFTER that
+     * boundary's compaction (a hook of its own would have been registration-order luck). The settlement
+     * half always runs; the delivery half only when `continues` — a boundary this leg will not follow
+     * with another request cannot produce a transcript receipt for anything handed over there.
+     */
+    boundaryRound(o: {
+        continues: boolean;
+    }): Promise<void>;
+    /** #1036 — "is this engine frame's record still parked in this box?" The terminal sweep's
+     *  per-session pend must skip those: the box re-serves them itself, and a process-local copy beside
+     *  a parked record is two sources of truth for one message. */
+    isBoxBacked(payload: unknown): boolean;
+    /** #1036 — "does this leg hold a record a landed compaction could still break?" The compaction
+     *  commit beat asks before recording its effect, so a run that will never read one records none. */
+    wantsCompactionEffects(): boolean;
+    /** Run end: settle what reached the transcript, then release the lease so the session's next cycle
+     *  claims at once. What did NOT reach it stays parked (at-least-once, next run re-serves it). */
     finish(): Promise<void>;
     /** The run began working (cancels a pending idle fire). */
     busy(): void;
@@ -112,6 +175,15 @@ export declare function createPeerSessionDrain(opts: PeerSessionDrainOptions): P
  *  before it — both read this one cell. */
 export interface PeerLaneRefs {
     askEffective?: AskEffective;
+    /** The bound drain's pull face (filled by {@link bindPeerLaneDrain}); the `ReadInbox` tool reads it late. */
+    pull?: (limit?: number, toolCallId?: string, charBudget?: number) => Promise<PulledInbox>;
+    /** #1036 — the bound drain's BOUNDARY pass (filled by {@link bindPeerLaneDrain}); the leg's
+     *  prepared seat copies it out so the turn-boundary lane can tail-call it. */
+    boundaryRound?: (o: {
+        continues: boolean;
+    }) => Promise<void>;
+    /** #1036 — the bound drain's box-backed predicate (filled by {@link bindPeerLaneDrain}). */
+    isBoxBacked?: (payload: unknown) => boolean;
 }
 /**
  * The mount verdict + its loud half: `true` = the lane mounts on this leg; `false` = no seat, or the
@@ -153,7 +225,10 @@ export declare function listAgentsMountable(face: {
 /** design/385 §5.1 — the ListAgents mount (alias ListPeers): read-only, concurrency-safe, on the peer
  *  seat's own arm beside SendMessage; a caller-supplied tool of the same name wins (skip, not throw). */
 export declare function mountListAgents(args: {
-    peerDirectory: PeerDirectory;
+    /** The directory when the peer lane is up; absent on a delegation-only mount (agent lanes list, no peer rows). */
+    peerDirectory?: PeerDirectory;
+    /** The resolved listing freshness window (the peer lane's knob table). */
+    freshWindowMs?: number;
     sessionId: string;
     scope: string;
     hostTaskId: string;
@@ -190,18 +265,21 @@ export interface PeerDrainHarness {
 export declare function bindPeerSessionDrain(harness: PeerDrainHarness, opts: PeerSessionDrainOptions): PeerSessionDrain;
 /**
  * The leg-side spelling of {@link bindPeerSessionDrain}: the deployment seats the drain reads
- * (`mailboxStore` / `peerAdmission` / `crossSessionInbound` / `crossSessionDialogExpiry` / the two
+ * (`mailboxStore` / `peerLane` / `crossSessionInbound` / `crossSessionDialogExpiry` / the two
  * sinks) come straight off deps, the recipient's mode class folds off the lane refs — one binding call
  * per leg, no per-seat plumbing.
  */
 export declare function bindPeerLaneDrain(harness: PeerDrainHarness, args: {
-    deps: Pick<RunnerDeps, "mailboxStore" | "peerDirectory" | "peerAdmission" | "crossSessionInbound" | "crossSessionDialogExpiry" | "onNotice" | "onError">;
+    deps: Pick<RunnerDeps, "mailboxStore" | "peerDirectory" | "peerLane" | "crossSessionInbound" | "crossSessionDialogExpiry" | "onNotice" | "onError">;
     sessionId: string;
     runId: string;
     scope: string;
     inject: PeerSessionDrainOptions["inject"];
     ownTokens: () => readonly string[];
     refs: PeerLaneRefs;
+    /** #1036 — the leg's settlement seam (receipts + compaction effects), minted by the
+     *  orchestrator and shared with the harness sink and the compaction commit beat. */
+    settlement?: FrameSettlement;
     selfName?: () => string | undefined;
     parked?: () => boolean;
     lastTurnText?: () => string | undefined;