@byok-sdk/core 0.30.2 → 0.32.0

package/dist/mailbox.d.ts

@@ -15,6 +15,7 @@ import type { CollectExpiredInput, CollectExpiredResult } from './retention';
  * `@byok-sdk/protocol`, and core must not grow an edge to it (§12.1 invariant).
  */
 import type { ContentHash } from './blob';
+import { ByokCoreError } from './errors';
 import type { TenantId } from './tenant';
 /**
  * Row lifecycle. `pending` and `acked` are derived from the device cursor;
@@ -46,9 +47,12 @@ export interface MailboxBody {
  * How an append is admitted against the tenant's `mailboxLimitBytes`.
  *
  * Mailbox bytes have one authority: the retained rows. Usage is the tenant's
- * `SUM(byteSize)` over every retained row in any state, and the limit is
- * checked in the same serialized unit that inserts the row — there is no
- * counter for a writer to forget, so deleting a row needs no accounting.
+ * `SUM(byteSize)` over its `pending` rows, and the limit is checked in the same
+ * serialized unit that inserts the row — there is no counter for a writer to
+ * forget, so acking, dead-lettering or deleting a row needs no accounting.
+ * `acked` and `expired` rows stay retained for retention and §12.7.5
+ * visibility but hold no quota, so undelivered-and-lost work can never wedge
+ * a tenant at its limit.
  *
  * - `limited`: refused with `storage_quota_exceeded` when `used + byteSize`
  *   exceeds the limit, and with `storage_entitlement_missing` when the tenant
@@ -76,13 +80,14 @@ export interface MailboxAppendInput {
     readonly materialize: (seq: number) => MailboxBody | Promise<MailboxBody>;
     /**
      * Limit admission for a NEW row. An existing `messageId` returns its row
-     * before any check, so a retry is never refused for capacity.
+     * before any capacity check, so a retry is never refused for capacity. A
+     * closed stream refuses before even that (see {@link MailboxStore.closeStream}).
      */
     readonly admission: MailboxAdmission;
 }
 /** Tenant mailbox usage, derived from the retained rows on every read. */
 export interface MailboxUsage {
-    /** `SUM(byteSize)` over every retained row (`pending`, `acked`, `expired`). */
+    /** `SUM(byteSize)` over the retained `pending` rows. */
     readonly bytes: bigint;
 }
 export interface MailboxReadQuery {
@@ -113,8 +118,9 @@ export interface MailboxPage {
      * whole point of the field.
      *
      * `1` for a mailbox that has lost nothing, so a fresh device's cursor `0` is
-     * always inside the window. Monotonic for as long as dead-lettered rows are
-     * retained, which §12.7.5 requires.
+     * always inside the window. Monotonic: `collectExpired` reaps old dead
+     * letters but always keeps each device's highest-seq one, which is the
+     * evidence this floor is read from.
      *
      * This is a READ of the retained window, never a second retention authority:
      * `collectExpired` decides what is retained, this reports what it cost.
@@ -144,7 +150,7 @@ export interface MailboxCursorState {
 /**
  * Retention cutoffs.
  *
- * Both instants must be **canonical ISO-8601 UTC** (`YYYY-MM-DDTHH:mm:ss.sssZ`);
+ * All three instants must be **canonical ISO-8601 UTC** (`YYYY-MM-DDTHH:mm:ss.sssZ`);
  * anything else is rejected with `timestamp_not_canonical`. A retention sweep
  * deletes rows, so an offset-bearing string that a string comparison and a SQL
  * `timestamptz` comparison read differently is the worst place to guess — see
@@ -153,8 +159,41 @@ export interface MailboxCursorState {
 export interface MailboxCollectExpiredInput extends CollectExpiredInput {
     /** Acked rows appended before this instant are deleted. */
     readonly ackedBefore: string;
-    /** Unacked rows appended before this instant move to `expired`, never deleted here. */
+    /** Unacked rows appended before this instant move to `expired`. */
     readonly expireUnackedBefore: string;
+    /**
+     * Dead letters (`expired` rows) appended before this instant are deleted,
+     * except each device's highest-seq dead letter: that row is the evidence for
+     * `recoverableFrom`, so a reap never moves the floor. Only rows that were
+     * already `expired` when the call started are eligible; a row this call
+     * expires waits for the next call. Reaped rows count in `removed`.
+     */
+    readonly reapDeadLettersBefore: string;
+}
+/**
+ * Which of one device's `pending` rows {@link MailboxStore.expirePending}
+ * dead-letters. A listed seq that is not `pending` (acked, already expired, or
+ * never written) is skipped.
+ */
+export interface MailboxExpirePendingInput {
+    readonly deviceId: string;
+    readonly seqs: readonly number[];
+}
+/** Why a device's stream was closed: the device it addressed was retired. */
+export declare const MAILBOX_STREAM_CLOSE_CAUSES: readonly ['device_revoked', 'device_superseded'];
+export type MailboxStreamCloseCause = (typeof MAILBOX_STREAM_CLOSE_CAUSES)[number];
+/** An append refused because its device's stream was closed when the device was retired. */
+export declare class MailboxStreamClosedError extends ByokCoreError {
+    readonly deviceId: string;
+    readonly closeCause: MailboxStreamCloseCause;
+    constructor(deviceId: string, closeCause: MailboxStreamCloseCause, options?: ErrorOptions);
+}
+export interface MailboxCloseStreamInput {
+    readonly deviceId: string;
+    readonly cause: MailboxStreamCloseCause;
+}
+export interface MailboxReopenStreamInput {
+    readonly deviceId: string;
 }
 /**
  * Mailbox port. Tenant-first, async.
@@ -165,11 +204,13 @@ export interface MailboxCollectExpiredInput extends CollectExpiredInput {
  * server has returned to that device),
  * `timestamp_not_canonical` (a retention cutoff that is not a canonical
  * ISO-8601 UTC instant), `storage_quota_exceeded` and
- * `storage_entitlement_missing` (a `limited` append refused at admission).
+ * `storage_entitlement_missing` (a `limited` append refused at admission), and
+ * `mailbox_stream_closed` ({@link MailboxStreamClosedError}, any append to a
+ * closed stream).
  */
 export interface MailboxStore {
     append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
-    /** The tenant's mailbox bytes, summed from the retained rows. */
+    /** The tenant's mailbox bytes, summed from the retained `pending` rows. */
     readUsage(tenant: TenantId): Promise<MailboxUsage>;
     /** Pure read. Never advances the cursor, never deletes, never marks acked. */
     readAfter(tenant: TenantId, query: MailboxReadQuery): Promise<MailboxPage>;
@@ -178,6 +219,36 @@ export interface MailboxStore {
     /** The one and only ack. Monotonic and bounded by the recorded delivery watermark. */
     advanceCursor(tenant: TenantId, input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
     readCursor(tenant: TenantId, deviceId: string): Promise<MailboxCursorState>;
-    /** Retention hook: delete acked rows, dead-letter unacked ones. */
+    /** Retention hook: delete acked rows, reap old dead letters below the floor, dead-letter unacked ones. */
     collectExpired(tenant: TenantId, input: MailboxCollectExpiredInput): Promise<CollectExpiredResult>;
+    /**
+     * Dead-letters the listed undelivered rows of a task the Host abandoned,
+     * without waiting for retention. Only `pending` rows move, and only to
+     * `expired`: nothing is deleted, no row returns to `pending`, the cursor is
+     * untouched, and the device's `seq` allocator keeps counting. The moved rows
+     * stop holding mailbox quota and raise `recoverableFrom` exactly as a
+     * retention sweep would. Serialized with the device's appends and acks.
+     */
+    expirePending(tenant: TenantId, input: MailboxExpirePendingInput): Promise<{
+        readonly expired: number;
+    }>;
+    /**
+     * Closes a retired device's stream and dead-letters every `pending` row on
+     * it, as one step serialized with the device's appends: an append ordered
+     * before it has its row expired here, and every append ordered after it is
+     * refused with `mailbox_stream_closed`, whatever its admission and even for
+     * a known `messageId`. The stream need not exist yet; closing creates it
+     * closed. Closing a closed stream keeps its first close instant, records the
+     * new cause and still expires pending rows. Cursor, `seq` and
+     * `recoverableFrom` move exactly as {@link expirePending} moves them.
+     */
+    closeStream(tenant: TenantId, input: MailboxCloseStreamInput): Promise<{
+        readonly expired: number;
+    }>;
+    /**
+     * Reopens a stream for a device registered again under the same id. Rows,
+     * cursor, `seq` and `recoverableFrom` are untouched, so delivery stays
+     * monotonic across the close. A no-op on an open or absent stream.
+     */
+    reopenStream(tenant: TenantId, input: MailboxReopenStreamInput): Promise<void>;
 }

package/dist/presence.d.ts

@@ -18,12 +18,34 @@ import type { TenantId } from './tenant';
 /** The five presence levels. */
 export declare const PRESENCE_LEVELS: readonly ['online', 'thinking', 'working', 'error', 'offline'];
 export type PresenceLevel = (typeof PRESENCE_LEVELS)[number];
+/**
+ * The capability matrix a daemon reported for one runtime: the shape of
+ * `@byok-sdk/protocol`'s `RuntimeCapabilities` (#1103). Omitted fields are unknown.
+ */
+export interface PresenceRuntimeCapabilities {
+    readonly steer?: boolean;
+    readonly resume?: boolean;
+    readonly approvalInteractive?: boolean;
+    readonly mcpToolsets?: boolean;
+    readonly messageDraft?: boolean;
+    readonly toolAuthorizationAuto?: boolean;
+    readonly durablePi?: boolean;
+    readonly preparedLane?: boolean;
+    readonly isolation?: {
+        readonly userContext?: boolean;
+        readonly userMcpServers?: boolean;
+        readonly sessionPersistence?: boolean;
+    };
+}
 /** Runtime facts observed by a daemon's real local probe. Omitted fields are unknown. */
 export interface PresenceRuntimeFact {
     readonly id: string;
     readonly version?: string;
     readonly authPresent?: boolean;
+    readonly capabilities?: PresenceRuntimeCapabilities;
 }
+/** A frozen copy of one runtime fact holding only the known fields; every presence store returns this. */
+export declare function freezePresenceRuntimeFact(runtime: PresenceRuntimeFact): PresenceRuntimeFact;
 /** Unexpired presence facts nested in the tenant aggregate. */
 export interface TenantReadinessPresence {
     readonly level: PresenceLevel;