@teaflask/assistant 0.3.0 → 0.7.0

package/dist/core/execution-inbox.js

@@ -4,7 +4,6 @@ import { MEMBER_ANSWERABLE_KINDS } from "./execution-kinds.js";
 import { coworkerExecutionRequestOf, executionRequestedPayloadOf, recordOrNull, } from "./execution-request-narrowing.js";
 export { coworkerExecutionRequestOf, executionRequestedPayloadOf, } from "./execution-request-narrowing.js";
 const PENDING = { kind: "pending" };
-/** Narrow a tool_result_recorded CUSTOM event's wire value. */
 export function toolResultRecordedPayloadOf(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -22,69 +21,40 @@ export class ExecutionInbox {
     currentRunId = null;
     seenRunIds = new Set();
     seenToolCallIds = new Set();
-    // The coworker requests REST has named, by interrupt id — what a
-    // stream marker for one of them is re-labelled from.
     coworkerAsks = new Map();
     entryList = [];
-    // --- the stream side -------------------------------------------------
     noteRunStarted(runId) {
         this.currentRunId = runId;
         if (this.seenRunIds.has(runId)) {
-            // A run id already seen is a RE-ENTERED historical segment: the
-            // thread stream re-opens an old run's segment whenever a row lands
-            // late under it (a coworker's answer is recorded under its
-            // dispatching turn's run) — nothing began, nothing closes.
             return false;
         }
         this.seenRunIds.add(runId);
-        // A run beginning for the first time is closing evidence for the
-        // assistant's straggler entries — only the newest run can still be
-        // awaiting input. A coworker's pause outlives the parent's runs.
         return this._removeWhere((entry) => entry.asker.kind === "assistant" && entry.runId !== runId);
     }
     noteToolCallStart(toolCallId) {
-        // TOOL_CALL_START precedes its pause marker in stream order, so the
-        // set is complete by the time anchoring is judged — nothing to
-        // publish here (the approval inbox's own semantics).
         this.seenToolCallIds.add(toolCallId);
         return false;
     }
     noteExecutionRequested(payload) {
         if (this.currentRunId === null) {
-            // A marker outside any run segment is unanchorable — ignore it.
             return false;
         }
         const runId = this.currentRunId;
         if (this._hasEntry(payload.interrupt_id)) {
-            // A replayed marker for an entry we already hold: keep the entry's
-            // status — replay must never reopen an already-reported request.
             return false;
         }
         const coworkerAsk = this.coworkerAsks.get(payload.interrupt_id);
         if (coworkerAsk !== undefined) {
             if (MEMBER_ANSWERABLE_KINDS.has(payload.request.kind)) {
-                // The stream door of the adoption's skip below: not held here
-                // either, or it would be an assistant entry minting a question card.
                 return false;
             }
-            // A marker for a request REST already named as a coworker's: its
-            // round is the coworker's own and never meets the parent's
-            // arbitration below.
             this.entryList.push(_entryOf(payload, this.seenToolCallIds, coworkerAsk.runId, coworkerAsk));
             return true;
         }
-        // THE PREMISE: round arbitration is the ASSISTANT's alone. A coworker's
-        // entry carries the dispatching turn's run id and the CHILD's segment
-        // round — two namespaces that share a bucket only by accident — and its
-        // lifetime is REST's, so it neither competes with nor supersedes the
-        // parent's rounds (the dashboard's inbox-asker census pins it).
         const newestRound = this._newestRoundOf(runId);
         if (newestRound !== null && payload.round < newestRound) {
-            // A lower round replaying after a later pause is history, not an ask.
             return false;
         }
-        // A higher round supersedes the run's earlier entries (round
-        // namespacing: multi-pause turns re-emit cards and must not collide).
         if (newestRound !== null && payload.round > newestRound) {
             this._removeWhere((entry) => entry.asker.kind === "assistant" &&
                 entry.runId === runId &&
@@ -93,14 +63,6 @@ export class ExecutionInbox {
         this.entryList.push(_entryOf(payload, this.seenToolCallIds, runId, null));
         return true;
     }
-    // --- the REST side -------------------------------------------
-    /**
-     * The coworker requests the turn snapshot lists, adopted: a card not
-     * held opens a pending entry addressed to its dispatching turn; a held
-     * pending entry the stream delivered first is re-labelled; a coworker
-     * entry no turn lists anymore is gone (its row left paused). Bypasses
-     * the marker path's round arbitration — a coworker's round is its own.
-     */
     adoptCoworkerRequests(turns) {
         let changed = false;
         const listed = new Set();
@@ -111,8 +73,6 @@ export class ExecutionInbox {
                     continue;
                 }
                 const interruptId = request.card.interrupt_id;
-                // The label and drill-in handle the snapshot carries are the ledger
-                // join's to render; the entry keeps only what its readers use.
                 const ask = {
                     asker: { kind: "coworker", ordinal: request.ordinal },
                     turnId: turn.id,
@@ -120,18 +80,6 @@ export class ExecutionInbox {
                 };
                 this.coworkerAsks.set(interruptId, ask);
                 if (MEMBER_ANSWERABLE_KINDS.has(request.card.request.kind)) {
-                    // A coworker's request has exactly one door, the driver's POST
-                    // under its dispatching turn. A member-answerable kind would leave
-                    // through the question-set submit instead, addressed by the
-                    // assistant's run and staling that whole run on a 409 — so it is
-                    // held on neither door: not adopted here, and the ask is remembered
-                    // so a stream marker for the id is dropped by noteExecutionRequested
-                    // instead of landing as the assistant's (the playground twin's
-                    // posture). Unreachable today: a coworker runs HEADLESS and ask_user
-                    // mounts on LIVE only — the approval inbox's asker-carrying card
-                    // does not change that.
-                    // A marker that beat the snapshot here landed as the assistant's;
-                    // it leaves now.
                     const dropped = this._removeWhere((entry) => entry.interruptId === interruptId);
                     changed = dropped || changed;
                     continue;
@@ -155,46 +103,24 @@ export class ExecutionInbox {
         }
         return changed;
     }
-    /** A 409 for a coworker's request speaks for that request alone. */
     markCoworkerRequestStale(interruptId) {
         return this._staleWhere((entry) => entry.asker.kind === "coworker" && entry.interruptId === interruptId);
     }
-    /** The member's send voids every paused coworker of the thread. */
     markCoworkerRequestsStale() {
         return this._staleWhere((entry) => entry.asker.kind === "coworker");
     }
     noteToolResultRecorded(interruptId, ok) {
-        // The receipt is the stream saying "a delivery happened" — on a replay
-        // it lands right after the marker it answers, so the entry flips to
-        // reported in the same burst and the driver can never claim an
-        // already-answered request. The gated call's result (or RUN_ERROR, or
-        // the settled turn's word) still closes the entry, as on the live path.
         return this._transition(interruptId, ["pending", "executing"], {
             kind: "reported",
             ok,
         });
     }
     noteToolCallResult(toolCallId) {
-        // The gated call producing a result is the resume made visible.
         return this._removeWhere((entry) => entry.toolCallId === toolCallId);
     }
     noteRunFinished() {
-        // A RUN_FINISHED closes nothing by itself. THE PREMISE: the thread
-        // streamer synthesizes a RUN_FINISHED for the LIVE run right before it
-        // re-enters an old run's segment for a late row (a coworker's answer or
-        // receipt lands under its dispatching turn's run), and the two frames
-        // are indistinguishable on the wire from a real terminal — so removing
-        // the run's entries here would lose a live pause's ask that nothing
-        // re-delivers. The run's entries die on their own evidence (the receipt,
-        // the gated call's result), on a first-seen run beginning (the
-        // straggler wipe above), on RUN_ERROR, or on the durable turn record's
-        // word (reconcileWithTurns) — the approval inbox's posture too
-        // (the dashboard's run-lifecycle census pins it).
         return false;
     }
-    /** The durable turn record's word: the assistant's entries
-     *  whose run belongs to a SETTLED turn are gone — the REST-driven close a
-     *  synthesized terminal cannot fake. */
     reconcileWithTurns(turns) {
         const settledRuns = new Set(turns
             .filter((turn) => isTerminalTurnStatus(turn.status))
@@ -203,14 +129,9 @@ export class ExecutionInbox {
         return this._removeWhere((entry) => entry.asker.kind === "assistant" && settledRuns.has(entry.runId));
     }
     noteRunError() {
-        // RUN_ERROR carries no runId, and a serving RUN_ERROR ends the stream —
-        // nothing of the assistant's can be answered anymore.
         return this._removeWhere((entry) => entry.asker.kind === "assistant");
     }
-    // --- the driver side ---------------------------------------------------
     beginExecution(interruptId) {
-        // The at-most-once claim: synchronous, so two overlapping passes (or
-        // StrictMode's double connection) can never both win the same entry.
         return this._transition(interruptId, ["pending"], { kind: "executing" });
     }
     settleReported(interruptId, ok) {
@@ -220,21 +141,14 @@ export class ExecutionInbox {
         });
     }
     settlePostFailed(interruptId) {
-        // The POST failed, not the execution — the entry returns to pending so
-        // a later pass re-POSTs the stored outcome. Re-execution is the
-        // ledger's to prevent, never this transition's to allow.
         return this._transition(interruptId, ["executing"], PENDING);
     }
     markRunStale(runId) {
-        // A 409 speaks for the whole pause: none of the run's open asks can
-        // land anymore. Reported entries keep their honest note.
         return this._staleWhere((entry) => entry.asker.kind === "assistant" && entry.runId === runId);
     }
-    // --- reading -------------------------------------------------------------
     entries() {
         return this.entryList.map((entry) => ({ ...entry }));
     }
-    // --- internals -------------------------------------------------------------
     _hasEntry(interruptId) {
         return this.entryList.some((entry) => entry.interruptId === interruptId);
     }
@@ -277,8 +191,6 @@ function _entryOf(payload, seenToolCallIds, runId, ask) {
         interruptId: payload.interrupt_id,
         toolName: payload.tool_name,
         toolCallId: payload.tool_call_id ?? null,
-        // A coworker's card names the CHILD run's tool call, which never
-        // streams in the parent's transcript — it anchors nothing here.
         anchored: payload.tool_call_id != null && seenToolCallIds.has(payload.tool_call_id),
         kind: payload.request.kind,
         action: recordOrNull(payload.request.action),
@@ -290,18 +202,6 @@ function _entryOf(payload, seenToolCallIds, runId, ask) {
         turnId: ask?.turnId ?? null,
     };
 }
-/**
- * The subscriber that feeds the stream into the inbox: markers open
- * entries, receipts report them, and the resume's own evidence closes
- * them. Only the server-named run id from RUN_STARTED is trusted — the
- * connect-run's input.runId is the client's own and never names a
- * recorded run.
- *
- * A quiet close needs nothing from this recorder: an open entry survives
- * it untouched, because nothing about being answerable depends on whether
- * the turn parked. The REST consult that tells a park from a dropped
- * connection, and the go/no-go it drives, stay the approval recorder's.
- */
 export function executionInboxRecorder(inbox, onEntriesChanged) {
     const publishWhen = (changed) => {
         if (changed) {
@@ -341,4 +241,3 @@ export function executionInboxRecorder(inbox, onEntriesChanged) {
         },
     };
 }
-//# sourceMappingURL=execution-inbox.js.map

package/dist/core/execution-kinds.d.ts

@@ -4,27 +4,9 @@ export declare const READ_PAGE_REQUEST_KIND = "builtin.read_page";
 export declare const HIGHLIGHT_REQUEST_KIND = "builtin.highlight";
 export declare const PREFILL_FORM_REQUEST_KIND = "builtin.prefill_form";
 export declare const ASK_QUESTIONS_REQUEST_KIND = "builtin.ask_questions";
-/**
- * The kinds whose executor is the MEMBER, not this client: the driver
- * must never auto-answer them (its unknown-kind fallback would post
- * kind_unsupported and withdraw the ask). Their entries stay pending in
- * the inbox — closing on stream evidence like every entry — and are
- * answered through the store's submitQuestionAnswers / cancelQuestionSet
- * when the member submits the rendered panel. Any kind NOT here — one
- * this client predates, or one it has since retired (the question set's
- * one-question predecessor) — is answered
- * kind_unsupported through the driver: the contract's documented
- * degrade, which the server turns into "ask it in chat" — never an
- * invisible wait.
- */
 export declare const MEMBER_ANSWERABLE_KINDS: ReadonlySet<string>;
 export declare const MAX_DELIVERY_ATTEMPTS = 3;
 type ExecutionErrorCode = "kind_unsupported" | "execution_failed";
-/** What the failing API itself said, when the host adapter's error
- *  carried it: the HTTP status, the API's own error code, and its
- *  per-field problems (a 422's validation list). Optional and additive
- *  — an adapter that throws a bare Error yields none. Every member is
- *  bounded before it rides (execution-handlers.ts). */
 export interface ExecutionFailureDetail {
     status: number;
     code: string;
@@ -32,13 +14,9 @@ export interface ExecutionFailureDetail {
         path: string;
         message: string;
     }[];
-    /** How many problems the API named beyond `fields` — the per-detail
-     *  cap and the door fit both drop from the tail, and a partial list
-     *  must never read as complete. Present only when positive. */
     fieldsOmitted?: number;
 }
 interface ExecutionError {
-    /** Distinguishes "this client can't serve the kind" from a real failure. */
     code: ExecutionErrorCode;
     message: string;
     detail?: ExecutionFailureDetail;
@@ -54,4 +32,3 @@ export declare const KIND_UNSUPPORTED_OUTCOME: Extract<ExecutionOutcome, {
     ok: false;
 }>;
 export {};
-//# sourceMappingURL=execution-kinds.d.ts.map

package/dist/core/execution-kinds.js

@@ -1,56 +1,12 @@
-// The execution-request kind vocabulary, as a dependency-free leaf:
-// these constants used to live in execution-handlers.ts,
-// whose HANDLERS legitimately import the transport adapter, the DOM
-// reader subtree and the affordances — but the KINDS are pure
-// vocabulary, and the tool-decision anchor family (a value export of
-// the ./transcript projection entry) needs only the member-answerable
-// table. Reading it through the handlers dragged 16
-// transport/reader/affordance modules into an entry whose own law is
-// "React-free and transport-free by construction"
-// (tests/bundle-closure.test.ts pins the closure now).
-// execution-handlers.ts re-exports everything here, so its consumers
-// are unchanged.
-//
-// The same maneuver holds for the outcome vocabulary: the canned
-// kind-unsupported refusal (and the ExecutionOutcome shape it inhabits)
-// moved here from execution-handlers.ts so ./transcript can export it —
-// the dashboard playground answers unservable execution kinds with the
-// package's own sentence rather than a transcription of it. Like the
-// kinds, these are import-free values, so the entry's closure stays
-// transport-free.
-// The execution-request kinds the navigate, http_actions, and read_page
-// capabilities mint (the serving contract, "Execution-request kinds").
 export const NAVIGATE_REQUEST_KIND = "builtin.navigate";
 export const HTTP_INTENT_REQUEST_KIND = "http_intent";
 export const READ_PAGE_REQUEST_KIND = "builtin.read_page";
 export const HIGHLIGHT_REQUEST_KIND = "builtin.highlight";
 export const PREFILL_FORM_REQUEST_KIND = "builtin.prefill_form";
-// The conversational elicitation kind: the assistant asked the
-// member a SET of questions in one pause; every answer is plain text.
-// Deliberately NOT in execution-handlers' handler registry.
 export const ASK_QUESTIONS_REQUEST_KIND = "builtin.ask_questions";
-/**
- * The kinds whose executor is the MEMBER, not this client: the driver
- * must never auto-answer them (its unknown-kind fallback would post
- * kind_unsupported and withdraw the ask). Their entries stay pending in
- * the inbox — closing on stream evidence like every entry — and are
- * answered through the store's submitQuestionAnswers / cancelQuestionSet
- * when the member submits the rendered panel. Any kind NOT here — one
- * this client predates, or one it has since retired (the question set's
- * one-question predecessor) — is answered
- * kind_unsupported through the driver: the contract's documented
- * degrade, which the server turns into "ask it in chat" — never an
- * invisible wait.
- */
 export const MEMBER_ANSWERABLE_KINDS = new Set([
     ASK_QUESTIONS_REQUEST_KIND,
 ]);
-// A delivery that keeps failing on transport trouble stops re-posting
-// after this many attempts went wrong — the turn then parks exactly as
-// it did before the driver existed, and reopening the thread re-arms the
-// pass. One value for every deliverer (the package driver and the
-// dashboard playground's refusal pass), here because the
-// ./transcript entry exports it and this leaf is import-free.
 export const MAX_DELIVERY_ATTEMPTS = 3;
 export const KIND_UNSUPPORTED_OUTCOME = {
     ok: false,
@@ -60,4 +16,3 @@ export const KIND_UNSUPPORTED_OUTCOME = {
             "you were trying to do and how they can do it themselves.",
     },
 };
-//# sourceMappingURL=execution-kinds.js.map

package/dist/core/execution-request-narrowing.d.ts

@@ -1,30 +1,15 @@
 import type { ToolExecutionRequestedPayload } from "../contract/events.js";
-/** One coworker request as the turn snapshot lists it, narrowed. */
 export interface CoworkerExecutionRequest {
     ordinal: number;
     label: string;
     childSessionId: string;
     card: ToolExecutionRequestedPayload;
 }
-/** The turn fields the coworker adoption reads — the serving and the
- *  dashboard turn shapes both satisfy it. */
 export interface CoworkerRequestTurn {
     id: string;
     run_id: string | null;
     pending_coworker_executions?: readonly unknown[] | null;
 }
-/**
- * Narrow one pending_coworker_executions item (any by contract): the
- * asker's identity plus the card in the marker's own shape, so the
- * marker narrowing above serves both askers. Malformed → null.
- */
 export declare function coworkerExecutionRequestOf(value: unknown): CoworkerExecutionRequest | null;
-/**
- * Narrow a tool_execution_requested CUSTOM event's wire value (any by
- * contract). Malformed payloads return null and are ignored — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize".
- */
 export declare function executionRequestedPayloadOf(value: unknown): ToolExecutionRequestedPayload | null;
 export declare function recordOrNull(value: unknown): Record<string, unknown> | null;
-//# sourceMappingURL=execution-request-narrowing.d.ts.map

package/dist/core/execution-request-narrowing.js

@@ -1,14 +1,3 @@
-// The execution wire's narrowers: a
-// tool_execution_requested marker's value and a turn snapshot's coworker
-// request item, both `any` by contract. Malformed values return null and
-// are ignored — the contract's "clients MUST ignore events and fields they
-// do not recognize". A dependency-free leaf, so the ./transcript entry
-// exports the coworker narrowing without dragging the inbox along.
-/**
- * Narrow one pending_coworker_executions item (any by contract): the
- * asker's identity plus the card in the marker's own shape, so the
- * marker narrowing above serves both askers. Malformed → null.
- */
 export function coworkerExecutionRequestOf(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -30,12 +19,6 @@ export function coworkerExecutionRequestOf(value) {
         card,
     };
 }
-/**
- * Narrow a tool_execution_requested CUSTOM event's wire value (any by
- * contract). Malformed payloads return null and are ignored — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize".
- */
 export function executionRequestedPayloadOf(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -79,4 +62,3 @@ export function recordOrNull(value) {
     }
     return null;
 }
-//# sourceMappingURL=execution-request-narrowing.js.map

package/dist/core/host-fill.js

@@ -1,11 +1,3 @@
-// The fall-through rule for every host-provided node slot in the package:
-// a fill declines exactly when it is a value React renders as nothing
-// REGARDLESS of content — null, undefined, and both booleans, so the
-// idiomatic `cond && <X/>` falls through on its false arm to the package
-// default. Renderable emptiness ("", 0, []) is the host's deliberate
-// content and counts as filled. One predicate, so no slot can gate on
-// `!= null` and hand a `false` to the screen as a blank.
 export function hostFillDeclines(fill) {
     return fill === null || fill === undefined || typeof fill === "boolean";
 }
-//# sourceMappingURL=host-fill.js.map

package/dist/core/hotkey.js

@@ -1,27 +1,5 @@
-// The batteries-root's hotkey grammar: parsing "mod+k"-style specs and
-// matching them against keyboard events. Pure over an event-shaped input
-// on purpose — no DOM or window imports — so the script-tag distribution
-// can reuse the exact same binding semantics outside React.
-//
-// Matching is by event.key, the repo-wide idiom. Known limitation: on
-// macOS the Option key rewrites event.key ("alt+k" arrives as key "˚"),
-// so alt chords are not reliably bindable — none of our defaults use alt,
-// and a host that needs one owns the trigger via <AssistantPalette/>.
 export const DEFAULT_ASSISTANT_HOTKEY = "mod+k";
 const MODIFIER_TOKENS = ["mod", "ctrl", "meta", "alt", "shift"];
-/**
- * Parses a "mod+k"-style spec: "+"-separated tokens in any order, exactly
- * one non-modifier token (the key), at least one modifier drawn from
- * mod|ctrl|meta|alt|shift, case-insensitive. Exactly these five names —
- * no cmd/command/option aliases; a rejected alias warns loudly at the
- * call site, which beats two spellings of the same chord. A modifier-less
- * spec ("/", "k") is rejected too: the palette opens from anywhere, so a
- * bare key would swallow that character in every input on the page — and
- * for the same reason shift alone only pairs with a non-printable key
- * ("shift+f1" yes, "shift+k" no: Shift+letter is just typing a capital).
- * Returns null on anything else — the caller decides what a bad binding
- * means.
- */
 export function parseHotkey(spec) {
     const binding = {
         key: "",
@@ -56,12 +34,6 @@ export function parseHotkey(spec) {
     }
     return binding;
 }
-/**
- * Exact-chord match: named modifiers must be down and unnamed ones up
- * ("mod+k" does not match mod+shift+k — ⌘⇧K is someone else's chord).
- * `mod` is satisfied by meta or ctrl and absorbs exactly one of them, so
- * "mod+k" accepts ⌘K and Ctrl+K but rejects ⌘Ctrl+K.
- */
 export function hotkeyMatches(binding, event) {
     if (event.key.toLowerCase() !== binding.key) {
         return false;
@@ -72,8 +44,6 @@ export function hotkeyMatches(binding, event) {
     if (_explicitlyNamedPrimaryIsUp(binding, event)) {
         return false;
     }
-    // Primaries held down beyond the explicitly named ones: mod claims
-    // exactly one of them; without mod there must be none.
     const unclaimedPrimariesDown = Number(event.metaKey && !binding.meta) +
         Number(event.ctrlKey && !binding.ctrl);
     return unclaimedPrimariesDown === (binding.mod ? 1 : 0);
@@ -81,9 +51,6 @@ export function hotkeyMatches(binding, event) {
 function _isModifierToken(token) {
     return MODIFIER_TOKENS.includes(token);
 }
-// A key token is any single non-empty word that isn't a modifier — one
-// event.key value ("k", "escape", "/"). Whitespace or an empty token
-// (a stray "+") is a malformed spec, not a key.
 function _isKeyToken(token) {
     return token !== "" && !/\s/.test(token);
 }
@@ -97,12 +64,9 @@ function _shiftIsTheOnlyModifier(binding) {
         !binding.meta &&
         !binding.alt);
 }
-// A single-character event.key is a character the press would have typed
-// ("k", "/", "?"); multi-character names ("f1", "escape") are actions.
 function _isPrintableKey(key) {
     return key.length === 1;
 }
 function _explicitlyNamedPrimaryIsUp(binding, event) {
     return (binding.meta && !event.metaKey) || (binding.ctrl && !event.ctrlKey);
 }
-//# sourceMappingURL=hotkey.js.map

package/dist/core/identity-pair.js

@@ -0,0 +1,18 @@
+export const IDENTITY_PAIR_WARNING = "userId and getEndUserToken must be set together — a non-empty id with its vouch; the session runs anonymous until both are.";
+export function namedIdentityOf(input) {
+    const userId = namedUserIdOf(input.userId);
+    const getEndUserToken = input.getEndUserToken ?? undefined;
+    return userId !== undefined && getEndUserToken !== undefined
+        ? { userId, getEndUserToken }
+        : null;
+}
+export function identityPairIsHalfSet(input) {
+    const nothingSet = (input.userId ?? undefined) === undefined &&
+        (input.getEndUserToken ?? undefined) === undefined;
+    return !nothingSet && namedIdentityOf(input) === null;
+}
+export function namedUserIdOf(userId) {
+    return userId === null || userId === undefined || userId === ""
+        ? undefined
+        : userId;
+}

package/dist/core/idle-recheck.js

@@ -1,32 +1,5 @@
-// The leased idle re-read: while a surface is mounted over a
-// conversation whose newest known turn holds no stream, a bounded
-// single-flight interval GET is the only way a background-initiated
-// delivery turn becomes visible.
 import { turnHoldsAStream } from "./connection-driver.js";
-// The leased idle re-read: while a surface is MOUNTED and the
-// newest known turn holds no stream, the thread snapshot is the only
-// place a background-initiated delivery turn becomes visible — the
-// entity's settle-wake and janitor-re-wake openers have no push signal
-// the client can hold (the parent stream emits nothing until the delivery
-// run's first event, and the server's 60s handoff hold only pushes to a
-// socket that is already open). One lightweight GET per interval per
-// open conversation; ≤60s of added latency against the janitor's own
-// 15-minute sweep. Leased only: a headless embed must not poll for the
-// life of the page — its attach happens at the next mount through the
-// first-connect arm of the truth table.
 const IDLE_RECHECK_INTERVAL_MS = 60_000;
-// Armed while a surface is mounted over a conversation whose newest
-// known turn holds no stream — parked, awaiting_input, terminal, or
-// none: settle wakes and the janitor's re-wakes grow delivery turns
-// on terminal threads too, so gating on "parked" would miss them. The
-// re-read only calls refreshConversation(). An UNCHANGED read notifies
-// no subscriber: adoption keeps the _active reference when the thread
-// record did not move (the guard and its premise live in
-// adoptRefreshedDetail) and every cell publisher compares before it
-// sets — so an idle tick costs one GET and nothing renders. A read
-// that DID move still publishes, which is what flips the connect gate
-// on a landed queued/working turn and disarms this interval on that
-// same publish.
 export function syncIdleRecheck(store) {
     const wanted = !store._disposed &&
         store._leaseHolders.length > 0 &&
@@ -37,14 +10,6 @@ export function syncIdleRecheck(store) {
         return;
     }
     store._idleRecheckTimer ??= setInterval(() => {
-        // Single-flight (the delivery probe's own refreshOnce posture):
-        // this transport aborts nothing, so a tick that stacked a new
-        // GET behind an accepted-then-stalled one would add a wedged
-        // connection per minute for the life of the page — on HTTP/1.1
-        // exhausting the per-host budget and starving the SSE stream
-        // itself. One read in flight at a time; a wedged read quiets the
-        // interval instead of multiplying, and the flag clears the
-        // moment the read settles.
         if (store._idleRecheckInFlight) {
             return;
         }
@@ -60,4 +25,3 @@ export function clearIdleRecheck(store) {
         store._idleRecheckTimer = null;
     }
 }
-//# sourceMappingURL=idle-recheck.js.map

package/dist/core/memory-provenance-anchors.d.ts

@@ -1,70 +1,35 @@
 import type { AgentSubscriber } from "@ag-ui/client";
+/**
+ * A notice that the assistant saved a memory. It never contains the memory's
+ * content.
+ */
 export interface MemoryUpdated {
+    /**
+     * The saved memory's id; a repeated report of the same save carries the
+     * same id, so use it to de-duplicate.
+     */
     memoryId: string;
-    /** Open vocabulary: "org" | "user" today; render unknowns generically. */
+    /**
+     * Who the memory is for: "org" is shared across all your users, "user" is
+     * private to the current user. Show any other value generically.
+     */
     scope: string;
-    /** The canned human sentence — never the memory's content. */
+    /**
+     * A short sentence for the user saying a memory was saved, not the memory
+     * itself.
+     */
     summary: string;
 }
 export declare const EMPTY_MEMORY_PROVENANCE_ANCHORS: ReadonlyMap<string, MemoryUpdated>;
-/**
- * Narrow a memory_updated marker's value. Null means ignore — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize": without its durable id the row has no reconcile key, and
- * without a sentence there is nothing safe to show.
- */
 export declare function memoryUpdatedAnchorOf(value: unknown): MemoryUpdated | null;
-/**
- * Reconcile-by-id, never append: the first anchor for a memory id wins,
- * so every replay re-delivery — and any delayed duplicate — is a no-op.
- * Insertion order is stream order, which is how consumers list the rows.
- */
 export declare function withMemoryUpdateAnchored(previous: ReadonlyMap<string, MemoryUpdated>, update: MemoryUpdated): ReadonlyMap<string, MemoryUpdated>;
-/**
- * A defensive copy for seeding from the resume store: entries that are
- * not a well-formed provenance record are dropped rather than rendered —
- * a dropped entry becomes a missing row until the next full replay,
- * never a crash.
- */
 export declare function wellFormedMemoryProvenanceAnchorsOf(stored: ReadonlyMap<string, MemoryUpdated>): ReadonlyMap<string, MemoryUpdated>;
 export declare const EMPTY_MEMORY_ATTRIBUTION_ANCHORS: ReadonlyMap<string, string>;
-/**
- * Reconcile-by-id, never move: the first message a memory id attributes
- * to wins, so a re-delivery flushing against a drifted message list is a
- * no-op — identical map identity, the anchor family's arbitration law.
- */
 export declare function withMemoryAttributed(previous: ReadonlyMap<string, string>, memoryId: string, messageId: string): ReadonlyMap<string, string>;
-/**
- * A defensive copy for seeding from the resume store: pairs that are not
- * two non-empty strings are dropped rather than rendered — a dropped
- * pair becomes a missing footer until the next full replay, never a
- * crash.
- */
 export declare function wellFormedMemoryAttributionAnchorsOf(stored: ReadonlyMap<string, string>): ReadonlyMap<string, string>;
-/**
- * The footer projection: provenance records grouped under the message
- * each one attributed to, in stream order (the provenance map's
- * insertion order). A record without attribution is skipped — an old
- * history renders no footer rather than a synthesized one.
- */
 export declare function memoryFootersOf(provenance: ReadonlyMap<string, MemoryUpdated>, attribution: ReadonlyMap<string, string>): ReadonlyMap<string, MemoryUpdated[]>;
-/** The recorder's two write channels: the provenance record itself, and
- *  the message id its footer renders under. */
 export interface MemoryUpdatedRecorderSink {
     onMemoryAnchored: (update: MemoryUpdated) => void;
     onMemoryAttributed: (memoryId: string, messageId: string) => void;
 }
-/**
- * Records each memory_updated marker's memory id → narrowed payload, and
- * attributes each write to the assistant prose message whose run caused
- * it. Attribution follows the receipt-family stream-position idiom
- * (core/receipt-anchors.ts): writes observed while the run is live
- * buffer and flush at the terminal against the run's own newest prose;
- * a run that authored no prose drops its buffer honestly (the annotated
- * tool row still tells the story, and an earlier turn's prose must never
- * adopt this turn's write). A marker arriving AFTER the terminal — the
- * settled-then-provenance arrival a reconnect tail produces — attributes
- * immediately, so the footer engages without waiting for another event.
- */
 export declare function memoryUpdatedRecorder(sink: MemoryUpdatedRecorderSink): AgentSubscriber;
-//# sourceMappingURL=memory-provenance-anchors.d.ts.map