@sema-agent/core 7.56.0 → 7.57.0

package/LICENSE

@@ -5,7 +5,7 @@ Parameters
 Licensor:             clay (github.com/clayboby)
 Licensed Work:        @sema-agent/core (sema-core) and the satellite packages
                       published from this repository (currently
-                      @sema-agent/mods-kernel)
+                      @sema-agent/mods-kernel, @sema-agent/primitives and @sema-agent/core-stores-sql)
                       (formerly published as @sema-ai/core)
                       The Licensed Work is (c) 2026 clay.
 Additional Use Grant: You may make production use of the Licensed Work for

package/dist/agents/org-delivery-gate.js

@@ -7,9 +7,8 @@ export function principalInboxConsumerOf(deps) {
     const raw = deps.principalInboxConsumer;
     if (raw === undefined)
         return { kind: "none" };
-    if (raw === "terminals") {
-        throw consumerRefusal(`RunnerDeps.principalInboxConsumer "terminals" is not available yet: the shared held decision ledger is not yet available, so a letter a person refused in one terminal could be delivered by another. Declare { assistant: "<agent handle>" } or leave the seat absent.`, "terminals_unsupported");
-    }
+    if (raw === "terminals")
+        return { kind: "terminals" };
     if (raw !== null && typeof raw === "object" && !Array.isArray(raw) && Object.getPrototypeOf(raw) === Object.prototype) {
         const keys = Reflect.ownKeys(raw);
         const handle = raw.assistant;
@@ -32,7 +31,7 @@ export function isOrgDeliveryRefusalCode(value) {
 export function mintCrossPrincipalRecord(input) {
     const { from, body, receiptId, sentAt, consumer } = input;
     if (consumer?.kind !== "terminals" && consumer?.kind !== "assistant") {
-        throw consumerRefusal(`an organization delivery gate is minting a principal-inbox letter, but the deployment declares no principal-inbox consumer (RunnerDeps.principalInboxConsumer is absent): nobody would ever read it. Declare { assistant: "<agent handle>" }.`, "no_consumer");
+        throw consumerRefusal(`an organization delivery gate is minting a principal-inbox letter, but the deployment declares no principal-inbox consumer (RunnerDeps.principalInboxConsumer is absent): nobody would ever read it. Declare "terminals" or { assistant: "<agent handle>" }.`, "no_consumer");
     }
     if (typeof body.content !== "string")
         throw new TypeError("mintCrossPrincipalRecord: body.content must be a string");

package/dist/agents/peer-held-queue.d.ts

@@ -1,10 +1,12 @@
-import type { MailboxPeerMeta } from "../core/mailbox-store.js";
+import { type MailboxPeerMeta, type MailboxDecisionOutcome, type MailboxDecision } from "../core/mailbox-store.js";
 import type { CrossSessionHoldCause, CrossSessionInboundVerdict } from "./cross-session-judge.js";
 import { type PeerDeliveryReceiptState } from "./peer-notices.js";
 /** The `cause` vocabulary of a `peer.inbound_disposition{disposition:"held"}` notice: the parity
  *  judge's causes plus the drain-stage gate's TRANSIENT `rate_limited` (a bucket-wait, not a review
  *  hold — it never enters the held queue; the drain stops at that seq and re-judges next pass). */
 export type PeerInboundHoldCause = CrossSessionHoldCause | "rate_limited";
+/** The decisions a card can stand for: held, approved, or handed over but not yet injected. */
+export type PeerCardDecision = Extract<MailboxDecision, "held" | "approved" | "delivered">;
 export interface PeerHeldEntry {
     /** The recipient box seq of the held record (its identity for the review face). */
     readonly seq: number;
@@ -21,12 +23,16 @@ export interface PeerHeldEntry {
     readonly heldAt: number;
     /** The cause last announced for this entry (re-judgment may move it). */
     cause: CrossSessionHoldCause;
-    /** Approved by the review face while no run of the session was live: delivered at the next flush
-     *  (a re-judgment that now refuses still wins — CC `l0e`'s approve arm re-checks policy). */
-    released?: boolean;
+    /** The record's decision as this queue last read or wrote it: `held`; `approved` (deliverable,
+     *  waiting for a lease-holding pass — a re-judgment that now refuses still wins); `delivered` (this
+     *  queue took the hand-over move and the injection is still owed; a policy that now refuses ends it as `dropped`). */
+    decision: PeerCardDecision;
 }
-export type PeerHeldSettlement = "expired" | "delivered" | "refused" | "denied" | "dropped";
-export type PeerHeldSettleReason = "evicted" | "deadline" | "shutdown" | "rejudge" | "approved" | "denied" | "cancelled" | "inject_failed" | "superseded";
+/** How an entry left this queue. `retired` — the CARD left this process but no decision was taken: the
+ *  record stays held in its box for the next consumer (a queue-local event no receipt announced,
+ *  or a record another consumer settled). Every other word is the record's own final fate. */
+export type PeerHeldSettlement = "expired" | "delivered" | "refused" | "denied" | "dropped" | "retired";
+export type PeerHeldSettleReason = "evicted" | "deadline" | "shutdown" | "rejudge" | "approved" | "denied" | "cancelled" | "inject_failed" | "superseded" | "decided_elsewhere";
 /** The clock/timer seam (tests inject a virtual one). Handles are opaque. */
 export interface PeerClock {
     now(): number;
@@ -36,81 +42,95 @@ export interface PeerClock {
 export declare const realPeerClock: PeerClock;
 /** The live seats a bound run gives the queue. `inject` is the ONLY member that is run-scoped (a run's
  *  own injection lane); the others survive the run (the receipt route rides the mailbox, the judge
- *  reads the deployment's settings getter) and are what a headless deadline settles through. */
+ *  reads the deployment's settings getter, the decision seat is the store) and are what a headless
+ *  deadline settles through. */
 export interface PeerHeldQueueSink {
     /** Re-judge an entry against the recipient's CURRENT settings and mode class (CC `M`). */
     judge: (entry: PeerHeldEntry) => CrossSessionInboundVerdict;
-    /** Deliver a released entry into the live run's model context. Absent ⇒ no run is live. Throws ⇒
-     *  the lane refused the frame (settled `dropped`, receipt sent). Returns `"deferred"` ⇒ the run is
-     *  live but this pass's delivery budget is spent: the entry stays released and goes at the next
-     *  pass's flush (the same wait a run-less approval takes). */
+    /** Deliver a deliverable entry into the live run's model context. Absent ⇒ no run is live. Throws ⇒
+     *  the lane refused the frame. Returns `"deferred"` ⇒ the run is live but this pass's delivery budget
+     *  is spent: the entry stays deliverable and goes at the next pass's flush (unless the policy refuses it first). */
     inject?: (entry: PeerHeldEntry) => void | "deferred";
+    /** Would {@link inject} take this entry NOW (a live pass that holds this box's lease, with budget left)?
+     *  Asked BEFORE the hand-over move (and before a refusal ends a handed-over card), so a process that cannot
+     *  deliver never takes a move out of `delivered`. Absent ⇒
+     *  the presence of `inject` decides. */
+    canInject?: (entry: PeerHeldEntry) => boolean;
     /** The receipt to the sender (the binding routes it into the sender's box). */
     receipt: (entry: PeerHeldEntry, state: PeerDeliveryReceiptState) => void;
+    /** Does a receipt about this entry reach a sender? A queue-local event (eviction, shutdown, a refused
+     *  release) is a decision about the record exactly when it does — the sender is told it is final. */
+    tellsSender: (entry: PeerHeldEntry) => boolean;
+    /** THE decision seat: the store's compare-and-set of this entry's record (`MailboxStore.moveDecision`). */
+    decide: (entry: PeerHeldEntry, expect: MailboxDecision | undefined, next: MailboxDecision) => Promise<MailboxDecisionOutcome>;
     /** Announce an entry entering the queue (or its cause changing on re-judgment). */
     onHeld?: (entry: PeerHeldEntry, heldCount: number, cause: CrossSessionHoldCause, reannounce: boolean) => void;
     /** Announce an entry leaving the queue. */
     onSettled?: (entry: PeerHeldEntry, settlement: PeerHeldSettlement, reason: PeerHeldSettleReason, heldCount: number) => void;
+    /** A decision move the store could not take (it threw): the card stays as it was and is tried again later. */
+    onFault?: (entry: PeerHeldEntry, error: unknown) => void;
 }
 export interface PeerHeldQueueConfig {
     sink: PeerHeldQueueSink;
     /** The resolved `dialogExpiry`: ms before a REVIEW-cause hold expires; `null` = never. */
     dialogExpiryMs: number | null;
 }
-export type PeerHeldSettleOutcome = "gone" | "delivered" | "released_pending" | "dropped" | "dropped_by_policy" | "denied" | "expired";
+/** The approval face's answer. `decided_elsewhere` — another consumer's move won the record first (the
+ *  card now shows that state, or left the queue when it was final); `released_pending` — approved, and a
+ *  lease-holding pass delivers it. */
+export type PeerHeldSettleOutcome = "gone" | "delivered" | "released_pending" | "dropped" | "dropped_by_policy" | "denied" | "expired" | "decided_elsewhere";
+/** What {@link PeerHeldQueue.hold} did with a record the judgment holds: `held` — this call held it
+ *  (card + `held` receipt); `adopted` — it was already held (or deliverable) and this queue now shows it
+ *  without a receipt; `uncarded` — held, but this queue is full and no card it carries can be settled to
+ *  make room (none would tell its sender); a final word — another consumer settled it; `gone` —
+ *  no such record any more; `fault` — the store refused the move (reported through `onFault`). */
+export type PeerHoldOutcome = "held" | "adopted" | "uncarded" | "denied" | "expired" | "refused" | "dropped" | "gone" | "fault";
 export interface PeerHeldQueue {
     /** The registry key (scope + box). */
     readonly key: string;
     /** Bind (or re-bind) the live seats. Idempotent per run; a later bind replaces an earlier one. */
     configure(cfg: PeerHeldQueueConfig): void;
-    /** The bound run ended: approvals now park as `released`; deadlines and receipts keep working. */
+    /** The bound run ended: approvals now wait as `approved`; deadlines and receipts keep working. */
     detachLeg(): void;
     /** `true` once {@link configure} ran at least once (the queue can route receipts). */
     configured(): boolean;
-    /** Park a message (CC `v` hold arm): evict-oldest when full, arm the deadline for a review cause,
-     *  announce, receipt `held`. */
-    hold(entry: Omit<PeerHeldEntry, "heldAt" | "released">): void;
-    /** Re-judge every entry against current settings (CC `D`): released ⇒ delivered (or parked
-     *  `released` with no live run), refused ⇒ refused with a receipt, still held ⇒ re-announced only
-     *  when the cause moved. */
-    rejudge(): {
+    /**
+     * Hold a record (CC `v` hold arm). `decision` is the record's decision in the snapshot the caller judged:
+     * absent ⇒ the move absent → `held` is taken (its winner sends the `held` receipt); `held` / `approved` ⇒
+     * the record is already held elsewhere and this queue only shows it (an approved card is not announced).
+     * At the cap, settles the oldest held card that tells its sender (it is then a decision); arms the
+     * deadline for a hold cause a person could answer.
+     */
+    hold(entry: Omit<PeerHeldEntry, "heldAt" | "decision">, decision?: PeerCardDecision): Promise<PeerHoldOutcome>;
+    /** Re-judge every entry against current settings (CC `D`): deliverable ⇒ handed over (or kept with no
+     *  live run), refused ⇒ refused with a receipt, still held ⇒ re-announced only when the cause moved.
+     *  Every move goes through the decision seat. */
+    rejudge(): Promise<{
         released: number;
         refused: number;
         held: number;
-    };
+    }>;
     /**
-     * #1036 — the box is this queue's durable seat, so an entry whose record is no longer IN the box was
-     * settled by whoever held the lease meanwhile (a takeover acked it, delivered or refused). Called by a
-     * drain right after it claims the lease, with the seqs the claimed snapshot holds (a claim marks EVERY
-     * unacked record, so absence is absence): such entries leave the queue as `expired` / `superseded`,
-     * with no receipt (the owner that settled them sent one) and no decision recorded (there is no record
-     * left to decide about). Returns how many were retired.
+     * Bring the cards in line with the box a lease-holding drain just read, seq → the record's decision
+     * (every unacked record of the box is in it, so absence is absence): a card whose record is gone was
+     * settled by whoever held the lease meanwhile — it leaves as `retired` / `superseded`, with no receipt;
+     * a card whose record another consumer settled leaves as that final state / `decided_elsewhere`, with no
+     * receipt (the winner sent it); a card whose record another consumer approved now shows `approved`.
+     * Returns how many cards left.
      */
-    reconcile(present: ReadonlySet<number>): number;
-    /** The review face (CC `l0e`): approve re-judges then delivers (or parks `released` with no live
-     *  run), deny/cancel drop with the matching receipt. `"gone"` when nothing is held under that seq. */
-    settle(seq: number, decision: "approve" | "deny" | "cancel"): PeerHeldSettleOutcome;
+    reconcile(snapshot: ReadonlyMap<number, MailboxDecision | undefined>): number;
+    /** The review face (CC `l0e`): approve re-judges then delivers (or answers `released_pending` with no
+     *  live run), deny/cancel settle with the matching receipt. `"gone"` when nothing is held under that
+     *  seq. The answer is the store's: a move another consumer won answers `decided_elsewhere`. */
+    settle(seq: number, decision: "approve" | "deny" | "cancel"): Promise<PeerHeldSettleOutcome>;
+    /** Is a card for this seq in the queue? */
+    has(seq: number): boolean;
     list(): readonly PeerHeldEntry[];
     size(): number;
-    /** CC `HBe` — a graceful shutdown settles everything still held as `expired` with receipts. */
-    shutdown(): void;
-    /**
-     * #1036 — the TERMINAL DECISIONS this queue has taken about records that are still parked in
-     * the box, seq → the settlement word. Since a held record now stays in its durable box (the box is
-     * this queue's durable seat), a decision taken BETWEEN runs — a human's deny, a deadline, an
-     * eviction — has to survive the run whose ledger recorded it, or the session's next run re-judges
-     * the record from scratch and can deliver a message a person already refused. A decision is kept
-     * only until a drain that holds the lease acks past it ({@link PeerHeldQueue.forgetDecisions}); it
-     * is process-level, like the queue itself, and a crash loses it exactly as it loses the queue.
-     */
-    decisions(): ReadonlyMap<number, PeerHeldSettlement>;
-    /** #1036 — a lease-owning drain acked these seqs out of the box: their decisions are spent. */
-    forgetDecisions(seqs: Iterable<number>): void;
+    /** CC `HBe` — a graceful shutdown settles everything still held as `expired` with receipts (where a
+     *  receipt reaches a sender; elsewhere the cards just leave this process). */
+    shutdown(): Promise<void>;
 }
-/** #1036 — how many terminal decisions about still-parked records one box's queue remembers
- *  (see {@link PeerHeldQueue.decisions}). Several times the queue's own cap: the queue bounds what is
- *  LIVE, this bounds what has been decided and not yet observed as consumed. */
-export declare const PEER_HELD_DECISION_MEMORY: number;
 export declare function createPeerHeldQueue(key: string, opts?: {
     cap?: number;
     clock?: PeerClock;