@yaklabs-ai/plugin-sdk 0.15.3 → 0.26.3

package/dist/canonical-transcript.d.ts

@@ -27,7 +27,7 @@ declare type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessa
 
 declare type AgentSessionEvent = Exclude<HerdHarnessEvent, {
     readonly type: "tool_execution_start" | "tool_execution_end";
-}> | HerdHarnessEventWithCallerMetadata | SessionInfoUpdatedExtensionEvent | SubstrateDiagnosticSessionEvent | SessionCwdTransitionEvent | CostFactSessionEvent | ManagedHumanQueueUpdatedSessionEvent | BackgroundTaskStartedSessionEvent | BackgroundTaskProgressSessionEvent | BackgroundTaskCompletedSessionEvent | BackgroundTaskFailedSessionEvent | BackgroundTaskCancelledSessionEvent | BackgroundTaskResultQueuedSessionEvent | UserShellCommandResultQueuedSessionEvent | TurnBoundDeliveryDiscardedSessionEvent | CompactionTriggeredSessionEvent | CompactionShadowThresholdSessionEvent | CompactionFailedSessionEvent | SilentOverflowDetectedSessionEvent | ToolResultClampedSessionEvent | ToolResultImageBoundedSessionEvent | ContextWindowSnapshotSessionEvent | ResourceRosterSessionEvent | ResourceInvokedSessionEvent | CustomEntrySessionEvent | RunRecoverySettledSessionEvent | RunFailureObservedSessionEvent | RunFailedSessionEvent | RunRetryWaitSessionEvent | RunRetryingSessionEvent | RunRecoveredSessionEvent | UriAccessSessionEvent;
+}> | HerdHarnessEventWithCallerMetadata | SessionInfoUpdatedExtensionEvent | SubstrateDiagnosticSessionEvent | SessionCwdTransitionEvent | CostFactSessionEvent | ManagedHumanQueueUpdatedSessionEvent | BackgroundTaskStartedSessionEvent | BackgroundTaskProgressSessionEvent | BackgroundTaskCompletedSessionEvent | BackgroundTaskFailedSessionEvent | BackgroundTaskCancelledSessionEvent | BackgroundTaskResultQueuedSessionEvent | UserShellCommandResultQueuedSessionEvent | TurnBoundDeliveryDiscardedSessionEvent | CompactionTriggeredSessionEvent | CompactionShadowThresholdSessionEvent | CompactionFailedSessionEvent | SilentOverflowDetectedSessionEvent | ToolResultClampedSessionEvent | ToolResultImageBoundedSessionEvent | ContextWindowSnapshotSessionEvent | ResourceRosterSessionEvent | ResourceInvokedSessionEvent | CustomEntrySessionEvent | RunRecoverySettledSessionEvent | RunFailureObservedSessionEvent | RunFailedSessionEvent | RunRetryWaitSessionEvent | RunRetryingSessionEvent | RunRecoveredSessionEvent | UriAccessSessionEvent | UriObservationSessionEvent;
 
 declare const Alpha: TAlpha;
 
@@ -221,7 +221,7 @@ declare type AttachmentsMessage = CustomMessage<AttachmentsDetails> & {
  * or an {@link IdentityAttribution} for identity-bearing origins with no registry entry.
  *
  * Narrowing hazard: `SourceInfo` and `IdentityAttribution` both have a `string` `source`,
- * so a `source` value never distinguishes them — narrow `SourceInfo` by `"path" in x`
+ * so a `source` value never distinguishes them - narrow `SourceInfo` by `"path" in x`
  * (its required field), not by inspecting `source`.
  */
 declare type AttributionSource = SourceInfo | {
@@ -237,7 +237,7 @@ declare type AttributionSource = SourceInfo | {
 /**
  * The availability-facts message: who the user is connected as, which auth-gated tools are
  * waiting on a connect, and which installed plugins are not connected. DURABLE and never
- * turn-bound — that is the whole point of the kind.
+ * turn-bound - that is the whole point of the kind.
  *
  * These three facts used to be rendered into the system prompt, where they were the last
  * in-session prefix mutation (#2996): each of them changes on a connect or disconnect, and a
@@ -457,7 +457,7 @@ declare interface BillingIdentity {
      */
     readonly accountId?: string;
     /**
-     * The account incarnation this credential belongs to — what per-account consent
+     * The account incarnation this credential belongs to - what per-account consent
      * is pinned to. Unchanged by a token refresh; advanced by an explicit reconnect,
      * replacement, or removal, which is what makes a stale grant detectable.
      */
@@ -467,15 +467,6 @@ declare interface BillingIdentity {
 /** Creates a Boolean type. */
 declare function Boolean_2(options?: TSchemaOptions): TBoolean;
 
-declare interface BranchSummaryEntry extends EntryBase {
-    type: "branch_summary";
-    fromId: string | null;
-    summary: string;
-    details?: JsonValue_2;
-    usage?: Usage;
-    fromHook: boolean;
-}
-
 declare interface BranchSummaryMessage {
     role: "branchSummary";
     summary: string;
@@ -504,7 +495,7 @@ export declare interface CanonicalAgentTurn {
     /** Latest lifecycle timestamp of that prefix, excluding the current continuation. */
     readonly settledCompletedAt?: string;
     /**
-     * Wall-clock span of the whole turn — the earliest and latest lifecycle
+     * Wall-clock span of the whole turn - the earliest and latest lifecycle
      * timestamps across its items (message starts/completions and tool
      * starts/completions). Per-tool execution spans alone under-report a turn
      * whose time went to thinking or streaming tool arguments; the settled
@@ -541,7 +532,7 @@ export declare interface CanonicalFinalAnswerBlock {
     readonly responseId: string;
     readonly sourceMessageId: string;
     readonly responseSequence: number;
-    /** Turn-scoped, ascending per emitted text block in emission order — finer-grained than `responseSequence`, which shares one value across a message split into several text blocks. */
+    /** Turn-scoped, ascending per emitted text block in emission order - finer-grained than `responseSequence`, which shares one value across a message split into several text blocks. */
     readonly streamStage: number;
     readonly phase: "final";
     readonly status: CanonicalTerminalStatus;
@@ -563,7 +554,7 @@ export declare interface CanonicalNarrationBlock {
     readonly responseId: string;
     readonly sourceMessageId: string;
     readonly responseSequence: number;
-    /** Turn-scoped, ascending per emitted text block in emission order — finer-grained than `responseSequence`, which shares one value across a message split into several text blocks. */
+    /** Turn-scoped, ascending per emitted text block in emission order - finer-grained than `responseSequence`, which shares one value across a message split into several text blocks. */
     readonly streamStage: number;
     readonly phase: "narration";
     readonly status: CanonicalTerminalStatus;
@@ -592,7 +583,7 @@ export declare interface CanonicalProvisionalResponseBlock {
     readonly responseId: string;
     readonly sourceMessageId: string;
     readonly responseSequence: number;
-    /** Turn-scoped, ascending per emitted text block in emission order — finer-grained than `responseSequence`, which shares one value across a message split into several text blocks. */
+    /** Turn-scoped, ascending per emitted text block in emission order - finer-grained than `responseSequence`, which shares one value across a message split into several text blocks. */
     readonly streamStage: number;
     readonly phase: "provisional" | "interrupted" | "error";
     readonly status: CanonicalTerminalStatus;
@@ -619,10 +610,10 @@ export declare interface CanonicalProvisionalResponseBlock {
 }
 
 /**
- * A user steering message the run absorbed MID-TURN (it rode the same run —
+ * A user steering message the run absorbed MID-TURN (it rode the same run -
  * see {@link isSteerContinuation}). It stays INSIDE the agent turn at its
- * chronological position — after the work that preceded it and before the
- * work that followed — so the transcript never reorders around it: a steer
+ * chronological position - after the work that preceded it and before the
+ * work that followed - so the transcript never reorders around it: a steer
  * rendered as a trailing sibling turn would sink ever further below the
  * work that actually came after it as the turn kept growing.
  */
@@ -822,7 +813,7 @@ declare interface CompactionFailedSessionEvent {
 
 /**
  * Why a session-initiated compaction ran. `threshold` is the pluggable-policy
- * usage check, now consulted at TWO points — every tool-batch boundary inside a
+ * usage check, now consulted at TWO points - every tool-batch boundary inside a
  * run (mid-turn, which stops the run so compaction can run before the next LLM
  * request) and during post-run settlement; `overflow_recovery` is the
  * compact-once step of overflow recovery (#1280); `silent_overflow` is a
@@ -835,8 +826,8 @@ declare type CompactionReason = "threshold" | "overflow_recovery" | "silent_over
  * Emitted at most once per compaction episode: the first post-turn consult
  * where the KERNEL DEFAULT threshold policy would have compacted had the
  * episode's opening manual/suggestion compaction not already shrunk the
- * context. The shadow sample is `contextTokens + debtTokens` — the observed
- * meter plus the opening compaction's estimated drop — so this row marks the
+ * context. The shadow sample is `contextTokens + debtTokens` - the observed
+ * meter plus the opening compaction's estimated drop - so this row marks the
  * OBSERVED counterfactual crossing that replay-based counterfactuals
  * previously had to simulate. An episode whose next real compaction arrives
  * before the crossing emits nothing (censored), and an episode whose opening
@@ -861,7 +852,7 @@ declare interface CompactionSummaryMessage {
 }
 
 /**
- * Emitted when the session begins a compaction (before calling the harness) — an
+ * Emitted when the session begins a compaction (before calling the harness) - an
  * automatic trigger OR a user-requested `/compact` (`reason: "manual"`). The
  * kernel's own `session_compact` event reports completion. `tokensBefore` and
  * `contextWindow` explain an automatic trigger's threshold math; a manual trigger
@@ -948,7 +939,7 @@ declare function ConstructorParametersDeferred<Type extends TSchema>(type: Type,
  * Typed counters from the cold-boundary supersede pass, for callers that record them as
  * analytics rather than read them as a log line. The same numbers the
  * `context_projection_reads_superseded` diagnostic carries, computed once and handed to both
- * sinks — the diagnostic is the human/log surface, this is the machine one.
+ * sinks - the diagnostic is the human/log surface, this is the machine one.
  *
  * `reclaimedTokens` is CARRIED, not footprint: the pass recomputes on every provider request, so
  * the same superseded read is counted again on each later request it keeps off the wire. Summing
@@ -978,16 +969,16 @@ declare interface ContextElisionStats {
 /**
  * The actual context usage of a session at a point in time.
  *
- * `tokens` is the number every consumer uses — UI percentage, compaction
+ * `tokens` is the number every consumer uses - UI percentage, compaction
  * thresholds, overflow reasoning. It is pi's `estimateContextTokens` result:
  * the provider-reported usage of the last valid assistant message (which
  * already counts the system prompt, tool definitions, and the entire history
- * sent on that turn — the provider's own tokenizer is authoritative) plus a
+ * sent on that turn - the provider's own tokenizer is authoritative) plus a
  * client-side estimate for messages appended after it (the un-sent tail).
  *
  * `basis` is `"provider"` once at least one assistant turn carries valid
  * usage, `"estimate"` before that (new or never-run sessions, and the single
- * turn immediately after a compaction — see the engine's `computeContextUsage`).
+ * turn immediately after a compaction - see the engine's `computeContextUsage`).
  * Estimation error is then bounded by the tail, not the whole conversation.
  */
 declare interface ContextUsage {
@@ -1003,14 +994,14 @@ declare interface ContextUsage {
 
 /**
  * A single attributed token bucket within a context window snapshot. Tokens are
- * estimated, not authoritative — the provider reports ground-truth totals via
+ * estimated, not authoritative - the provider reports ground-truth totals via
  * `message_end` usage events.
  *
  * `attributions` is an ordered list of sources that jointly own these tokens. A
  * tool result that went through a URI module and a converter carries all three
  * sources (tool, module, converter) so each layer can be accounted for. A tool
  * result whose details carry a `skillName` (a current or historical
- * whole-skill `read skill://…` dispatch) is labelled
+ * whole-skill `read skill://...` dispatch) is labelled
  * `tool_result:skill:<name>` instead of `tool_result:<toolName>`,
  * so per-skill token cost is attributable without a new bucket category.
  */
@@ -1055,7 +1046,7 @@ declare interface ContextWindowSnapshot {
      */
     readonly usage: ContextUsage;
     readonly buckets: readonly ContextWindowBucket[];
-    /** Sum of bucket estimates — composition metadata, NOT the context usage. */
+    /** Sum of bucket estimates - composition metadata, NOT the context usage. */
     readonly estimatedTotalTokens: number;
     readonly model: {
         readonly provider: string;
@@ -1066,8 +1057,8 @@ declare interface ContextWindowSnapshot {
 }
 
 /**
- * Emitted whenever the live attribution view is recomputed — on activation,
- * provider-request boundaries, settlement, model changes, and compaction — with
+ * Emitted whenever the live attribution view is recomputed - on activation,
+ * provider-request boundaries, settlement, model changes, and compaction - with
  * an estimated token breakdown of the full context window attributed to its
  * sources (system prompt sections, tool definitions, conversation messages).
  * Counts are
@@ -1082,9 +1073,9 @@ declare interface ContextWindowSnapshotSessionEvent {
     readonly type: "context_window_snapshot";
     readonly snapshot: ContextWindowSnapshot;
     /**
-     * Why this snapshot was taken. `provider_request` — emitted synchronously
+     * Why this snapshot was taken. `provider_request` - emitted synchronously
      * from the model-boundary context hook (every LLM request boundary);
-     * `refresh` — emitted on all other paths (post-compaction rebuild, model
+     * `refresh` - emitted on all other paths (post-compaction rebuild, model
      * change, post-run settlement). Absent on legacy non-recordable snapshots.
      */
     readonly cause?: "provider_request" | "refresh";
@@ -1108,8 +1099,8 @@ declare interface ContextWindowSnapshotSessionEvent {
  * The single declaration of the local amount basis for herd and the daemon:
  * durable.ts's replay schema and agent-runtime's spend-store validation set
  * derive from this tuple rather than re-typing it (kay#7331). The renderer-facing
- * `KayCostAmountBasis` in `@bonsai/analytics-contract` is a restated copy —
- * that package imports nothing from herd — and agent-runtime's `spend-store.ts`
+ * `KayCostAmountBasis` in `@bonsai/analytics-contract` is a restated copy -
+ * that package imports nothing from herd - and agent-runtime's `spend-store.ts`
  * pins the two equal at compile time. It stays a plain string tuple, not a Zod
  * enum: herd's `cost/durable.ts` is where Zod enters for replay validation.
  */
@@ -1148,7 +1139,7 @@ declare type CostAmountBasis = (typeof COST_AMOUNT_BASES)[number];
 
 /**
  * Emitted once per model-backed session operation that carried real token usage
- * (Cost C4, #314): the operation's {@link TurnCostFact} — tokens, the transport's
+ * (Cost C4, #314): the operation's {@link TurnCostFact} - tokens, the transport's
  * USD figure and basis, the requested/response models, and the billing identity
  * that ran it. Hosts fold it onto the usage operation they already track and
  * persist it for cross-session spend. Synthetic; herd-owned; live-only (a reopened session
@@ -1202,7 +1193,7 @@ declare interface CustomAgentMessages {
 /**
  * Mirror of `AgentSession.appendCustomEntry`, emitted after the entry is durably
  * persisted. `customType` and `data` are host-owned and opaque to herd. Live-only:
- * entries already in the log are not re-emitted when a stored session is opened — seed
+ * entries already in the log are not re-emitted when a stored session is opened - seed
  * from `collectCustomEntries`. Legacy `"context_attribution"` entries recorded
  * by older builds are never re-emitted through this host-facing event.
  */
@@ -1210,6 +1201,12 @@ declare interface CustomEntrySessionEvent {
     readonly type: "custom_entry";
     readonly customType: string;
     readonly data: unknown;
+    /**
+     * The stored entry's id, as a bounded read of the log names it, so a reader that seeded from
+     * the log can tell an entry it already holds from a new one. Absent from emitters that do not
+     * know it.
+     */
+    readonly entryId?: string;
 }
 
 declare interface CustomMessage<T = unknown> {
@@ -1273,7 +1270,7 @@ declare const DAEMON_SERVICE_TURN_CUSTOM_TYPE = "daemon_service_turn";
 /**
  * A daemon-synthesized turn; `service` selects the per-service wrapper at the
  * boundary. `followup_lane` (a followup session's instruction turn) has no
- * reserved wrapper tag yet — it renders through the generic provenance-aware
+ * reserved wrapper tag yet - it renders through the generic provenance-aware
  * `kay_context` fallback until the lane message shape settles.
  */
 declare interface DaemonServiceTurnDetails {
@@ -1282,8 +1279,8 @@ declare interface DaemonServiceTurnDetails {
     /**
      * A short, HUMAN-facing description of this turn, for a visible service whose
      * `content` is not written for a person. For `"continuation"`, `content` is
-     * the MODEL's input — a runtime-authored instruction ("Complete the
-     * remaining part of that request. Do not propose another …") — and showing
+     * the MODEL's input - a runtime-authored instruction ("Complete the
+     * remaining part of that request. Do not propose another ...") - and showing
      * it to a person reads as though the user is being instructed, so the visible
      * row renders THIS instead. A continuation renderer missing a summary must
      * degrade to its own generic phrasing, never to `content`. For
@@ -1375,9 +1372,9 @@ declare interface DroppedContribution {
 
 /**
  * The Dynamic Context message: retrieval-produced context delivered right after human
- * text enters the conversation (prompt, steer, or a drained follow-up batch — one
+ * text enters the conversation (prompt, steer, or a drained follow-up batch - one
  * message per delivery moment). Assembled by the daemon's Dynamic Context coordinator
- * from per-contributor sections; push-only (contributors add a section or nothing —
+ * from per-contributor sections; push-only (contributors add a section or nothing -
  * they never mutate the human text or cancel the turn). Persisted like any other
  * message so the append-only transcript keeps the prompt cache warm.
  */
@@ -1385,7 +1382,7 @@ declare const DYNAMIC_CONTEXT_CUSTOM_TYPE = "dynamic_context";
 
 /**
  * The delivery moment that produced a Dynamic Context message: a new human prompt, a
- * mid-run steer, or a drained follow-up queue bundled as one batch (the batch law —
+ * mid-run steer, or a drained follow-up queue bundled as one batch (the batch law -
  * one retrieval pass per delivery moment, N drained texts = one message).
  */
 declare type DynamicContextChannel = "prompt" | "steer" | "follow_up";
@@ -1422,7 +1419,7 @@ declare type DynamicContextMessage = CustomMessage<DynamicContextDetails> & {
 /**
  * One contributor's section of a Dynamic Context message. `contributorId` owns the
  * inner wrapper tag at the model boundary (derived from the registration id, sanitized
- * by the projection — never free-form), so sections stay parsable per contributor.
+ * by the projection - never free-form), so sections stay parsable per contributor.
  */
 declare interface DynamicContextSection {
     readonly contributorId: string;
@@ -1634,7 +1631,7 @@ declare interface FinalOutputCapture {
     readonly toolCallId: string;
     /** The terminality fact when the transcript carries the stamped receipt. */
     readonly terminatesRun?: boolean;
-    /** The tool details' `message` — legacy transcripts only. */
+    /** The tool details' `message` - legacy transcripts only. */
     readonly message?: string;
     readonly result: unknown;
     /** The tool details' `sessionTitle`. */
@@ -1710,17 +1707,17 @@ declare type GrammarVariants = Partial<Record<GrammarFormat, string>>;
 /**
  * Herd-owned replacement for pi 0.82.1's `AgentHarnessEvent` union (removed in
  * pi 0.84's v2 lane model). The NAMES and PAYLOAD SHAPES are the legacy ones:
- * they are AgentSession's public session-event surface — the interactive
- * reducer, the events adapter, and agent-runtime all key on them — so the
- * v2→herd translation happens once, inside AgentSession's event funnel
+ * they are AgentSession's public session-event surface - the interactive
+ * reducer, the events adapter, and agent-runtime all key on them - so the
+ * v2->herd translation happens once, inside AgentSession's event funnel
  * (`_wireHarnessEvents`), never at each consumer. Not generic: the legacy
  * generic carried resource typing herd never exposed on an event.
  *
- * The hook-named members (`before_agent_start`, `context`, …) carry bare
+ * The hook-named members (`before_agent_start`, `context`, ...) carry bare
  * `type` payloads: in the v2 model these are HOOK invocations that never reach
  * the event stream, but the names stay in the union (and in the events
  * adapter's disposition table) so a narrowing here cannot silently invalidate
- * a downstream keying. `after_provider_response` is the exception — it is
+ * a downstream keying. `after_provider_response` is the exception - it is
  * routed through the v2 `after_response` hook into herd's quota capture.
  */
 declare type HerdHarnessEvent = {
@@ -1799,14 +1796,6 @@ declare type HerdHarnessEvent = {
     readonly type: "session_compact";
     readonly compactionEntry: CompactionEntry;
     readonly fromHook: boolean;
-} | {
-    readonly type: "session_before_tree";
-} | {
-    readonly type: "session_tree";
-    readonly newLeafId: string | null;
-    readonly oldLeafId: string | null;
-    readonly summaryEntry?: BranchSummaryEntry;
-    readonly fromHook?: boolean;
 } | {
     readonly type: "summary_operation_settled";
 } | {
@@ -1997,7 +1986,7 @@ declare type InteractiveActivityPhase = "running" | "failed";
 
 /**
  * A single in-flight (or just-failed) session activity. At most one is active at
- * a time — compaction serializes, and any future activity kind that overlaps
+ * a time - compaction serializes, and any future activity kind that overlaps
  * would model concurrency explicitly rather than by widening this slot. `running`
  * drives a non-alarming in-progress status; `failed` is a transient, gentle
  * notice that the next run start clears. Cleared to `undefined` on success.
@@ -2058,8 +2047,6 @@ declare interface InteractiveMessageItem {
     readonly deliveredVia?: UserMessageDeliveryLane | (string & {});
     /** Send-time presentation position, when supplied by the originating surface. */
     readonly presentationAnchor?: PresentationAnchor;
-    /** @deprecated Never set: a session has one branch, so no item is off it. Kept one version for plugins that read it; remove after. */
-    readonly abandoned?: true;
     readonly status: InteractiveMessageStatus;
     readonly text: string;
     readonly parts: readonly InteractiveContentPart[];
@@ -2081,7 +2068,7 @@ declare interface InteractiveMessageItem {
      * carry them (mirrors the tool fields below): `startedAt` from
      * `message_start`, `completedAt` from the terminal `message_end`. On the
      * resume/load path both come from the stored entry's timestamp. They give
-     * turns a wall-clock span (canonical `startedAt`/`completedAt`) — per-tool
+     * turns a wall-clock span (canonical `startedAt`/`completedAt`) - per-tool
      * execution spans alone under-report a turn whose time went to
      * thinking/streaming.
      */
@@ -2125,7 +2112,7 @@ export declare interface InteractiveModeState {
     readonly completedRunBoundaryAnchors?: readonly InteractiveRunBoundaryAnchor[];
     readonly backgroundTasksById: Readonly<Record<string, InteractiveBackgroundTaskState>>;
     readonly nextItemIndex: number;
-    /** Host-owned `custom_entry` data per customType, oldest→newest (see CustomEntrySessionEvent). */
+    /** Host-owned `custom_entry` data per customType, oldest->newest (see CustomEntrySessionEvent). */
     readonly customEntries: Readonly<Record<string, readonly unknown[]>>;
     /**
      * The session's current transient lifecycle activity (compaction today), or
@@ -2169,7 +2156,7 @@ declare interface InteractiveRunState {
     /**
      * Present while an agent-level retry is in flight (run stays `"running"`):
      * the 1-based attempt number and the policy's max attempts, for surfacing a
-     * "retrying…" affordance. Runtime projections retain it only during the actual
+     * "retrying..." affordance. Runtime projections retain it only during the actual
      * sleep and correlate it by `waitId`; legacy raw events clear on `run_recovered`. See #126.
      */
     readonly retry?: {
@@ -2182,7 +2169,7 @@ declare interface InteractiveRunState {
      * Present while the run's driving PROCESS is being replaced and its input is
      * expected to be re-driven (run stays `"running"`). A bare flag on purpose:
      * unlike {@link InteractiveRunState.retry} there is no attempt number,
-     * ceiling, or provider reason to report — a surface may say the run is coming
+     * ceiling, or provider reason to report - a surface may say the run is coming
      * back and nothing else. Replaced wholesale by the next run status, so a
      * re-drive that lands (or a failure that terminalizes) clears it. See the
      * `resuming` {@link HostRunStatus}.
@@ -2238,8 +2225,8 @@ declare interface InteractiveToolCallState {
     /**
      * Present when {@link resultText} is the HEAD of a longer result that a
      * host's wire projection cut to a byte budget; `bytes` is the full
-     * result's UTF-8 length. The reducer never sets this — live results arrive
-     * whole — so a surface reading it knows the full text exists on the
+     * result's UTF-8 length. The reducer never sets this - live results arrive
+     * whole - so a surface reading it knows the full text exists on the
      * session log and can fetch it on demand. Absent means `resultText` is
      * complete.
      */
@@ -2248,8 +2235,6 @@ declare interface InteractiveToolCallState {
     };
     readonly failure?: ToolCallFailureOccurrence;
     readonly backgroundTaskId?: string;
-    /** @deprecated Never set; see {@link InteractiveMessageItem.abandoned}. */
-    readonly abandoned?: true;
     readonly attemptId: string;
     readonly waveId: string;
     readonly responseId?: string;
@@ -2656,8 +2641,8 @@ declare interface ManagedHumanQueueItemSnapshot {
 }
 
 /**
- * Lifecycle of a managed item. `queued` — live in a substrate queue, awaiting
- * delivery. `editing` — pulled out of every queue (delivery prevented) while
+ * Lifecycle of a managed item. `queued` - live in a substrate queue, awaiting
+ * delivery. `editing` - pulled out of every queue (delivery prevented) while
  * the human edits it; the engine's `ManagedHumanQueue.completeEdit` returns it to
  * `queued`.
  */
@@ -2671,7 +2656,7 @@ declare interface ManagedHumanQueueSnapshot {
 
 /**
  * Authoritative snapshot of the managed human-message queue (see `ManagedHumanQueue`).
- * Emitted whenever the queue changes — a mutation command, or a reconcile that observed the
+ * Emitted whenever the queue changes - a mutation command, or a reconcile that observed the
  * loop draining/clearing items. Carries the monotonic `revision` UI clients use for optimistic
  * concurrency and stable per-item ids the renderer keys on (unlike Pi's raw `queue_update`,
  * whose messages have no identity). Synthetic; herd-owned; live-only.
@@ -3518,7 +3503,7 @@ export declare interface ReconstructableEntry extends Omit<ToolCallSourceEntry,
  *
  * Latency pairing (`pairToolCallsFromEntries`) is intentionally NOT done here:
  * the reconstructed state carries no per-call duration, so pairing would only
- * compute-and-discard — and keying `isError` off that pairing was the source of
+ * compute-and-discard - and keying `isError` off that pairing was the source of
  * the multiple-results-per-call bug. Analytics consumers that want duration call
  * the pairing leaf directly.
  */
@@ -3620,7 +3605,7 @@ declare type RequiredKeys<Properties extends TProperties, Result extends Propert
 /**
  * Provenance for one discovered resource, carried so the runtime can emit
  * attributed usage events (loaded/invoked). This is the identity the runtime
- * uses — `name` is the lookup/dedup key; `harness`/`scope` are provenance.
+ * uses - `name` is the lookup/dedup key; `harness`/`scope` are provenance.
  *
  * Discovery is the only place provenance is known (the prompt-facing contract
  * drops it), so loaders populate this alongside the resources themselves.
@@ -3640,7 +3625,7 @@ declare interface ResourceAttribution {
     readonly scope: "project" | "user";
     /**
      * The skill's canonical namespace (the `<sourceId>` in `skill://<sourceId>/<name>`
-     * — see `skillSourceId` in herd-agent's `core/tools/uri/skill-uri-parse.ts`). A skill's
+     * - see `skillSourceId` in herd-agent's `core/tools/uri/skill-uri-parse.ts`). A skill's
      * real identity is the qualified `<sourceId>/<name>` pair, since discovery
      * shadows duplicate bare names across sources; `name` alone is not a stable
      * key. Absent for non-skill resources (context files, prompt templates),
@@ -3654,8 +3639,8 @@ declare interface ResourceAttribution {
 /**
  * Emitted each time a resource is invoked through the session's single
  * `invokeSkill` chokepoint. `via` distinguishes a programmatic application
- * (`explicit`, e.g. a slash command bound to a skill) from a `read skill://…`
- * URI dispatch (`uri`, contract Law 7 — usage rides both URI analytics and
+ * (`explicit`, e.g. a slash command bound to a skill) from a `read skill://...`
+ * URI dispatch (`uri`, contract Law 7 - usage rides both URI analytics and
  * this event). Additive: `observability/normalize.ts` renders the diagnostic
  * event, while the fact adapter projects it into `herd.resource.invoked` for
  * the runtime usage recorder; both pass additive fields through without an
@@ -3686,12 +3671,12 @@ declare interface ResourceInvokedSessionEvent {
  * carries 100+ skills/context files, discovery re-runs per session create AND
  * per subagent spawn, and a per-resource loop would append 100+ events in one
  * tick against the sink's drop threshold. Set-shaping also makes the set
- * boundary BE the row — "latest roster per session" is a contract, not a
+ * boundary BE the row - "latest roster per session" is a contract, not a
  * timestamp-clustering heuristic (no removal event exists, so per-resource
  * rows could not reconstruct the set on their own). Synthetic; herd-internal.
  *
  * Because it is state rather than a notification, `AgentSession.subscribe`
- * delivers the latest one to a listener that attaches after it was emitted —
+ * delivers the latest one to a listener that attaches after it was emitted -
  * the only session event that gets attach-time delivery.
  */
 declare interface ResourceRosterSessionEvent {
@@ -3734,7 +3719,7 @@ declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?:
 declare const RUN_CONTINUATION_CARRIER_CUSTOM_TYPE = "herd_run_continuation";
 
 /** Observed cause of a failed request or interrupted run. */
-declare const RUN_FAILURE_REASONS: readonly ["auth", "cancelled", "content_blocked", "context_overflow", "invalid_request", "model_disabled", "model_unavailable", "network", "organization_unavailable", "overloaded", "quota_exhausted", "rate_limit", "runtime_interrupted", "safeguard_block", "seat_unpaid", "server_error", "sign_in_required", "stream_interrupted", "timeout", "unknown"];
+declare const RUN_FAILURE_REASONS: readonly ["account_unreachable", "auth", "cancelled", "content_blocked", "context_overflow", "final_output_missing", "invalid_request", "model_disabled", "model_unavailable", "network", "organization_unavailable", "overloaded", "quota_exhausted", "rate_limit", "runtime_interrupted", "safeguard_block", "seat_unpaid", "server_error", "sign_in_required", "stream_interrupted", "timeout", "unknown"];
 
 /** Replay a durable run boundary at its position among the transcript's messages. */
 export declare function runBoundaryReplayEvent(entry: Pick<ReconstructableEntry, "type" | "customType" | "data">): HostRunStatusChange | undefined;
@@ -3780,9 +3765,11 @@ declare const runFailureCauseSchema: z.ZodObject<{
     reason: z.ZodEnum<{
         cancelled: "cancelled";
         timeout: "timeout";
+        account_unreachable: "account_unreachable";
         auth: "auth";
         content_blocked: "content_blocked";
         context_overflow: "context_overflow";
+        final_output_missing: "final_output_missing";
         invalid_request: "invalid_request";
         model_disabled: "model_disabled";
         model_unavailable: "model_unavailable";
@@ -3903,7 +3890,7 @@ declare interface RunRetryingSessionEvent {
     readonly channel: RunChannel;
     readonly attempt: number;
     /**
-     * Recovery actions taken so far in this run, 1-based — the honest lifetime
+     * Recovery actions taken so far in this run, 1-based - the honest lifetime
      * count. `attempt`/`maxAttempts` are relative to the CURRENT failure streak
      * and reset when provider work succeeds between two failures (#3007), so on
      * a long run they read "1 of 2" repeatedly; this field is what says how much
@@ -3939,10 +3926,10 @@ declare type RunRetryWaitSessionEvent = {
 
 /**
  * A durable runtime notice: the daemon telling the HUMAN, in the transcript,
- * that something it was going to do on their behalf did not happen — and why.
+ * that something it was going to do on their behalf did not happen - and why.
  * Same kernel posture as {@link COLLABORATION_MESSAGE_CUSTOM_TYPE}: the kernel
  * persists and projects the typed carrier; the daemon decides when one is
- * warranted. Delivery never starts a run — that is the type's whole reason to
+ * warranted. Delivery never starts a run - that is the type's whole reason to
  * exist. Its producers are the daemon's `RuntimeNoticeKind`s (agent-runtime
  * `context-message-builders.ts`). The first was #3365's dropped-continuation
  * path, retired with readiness continuations (#12512): a state a user could not
@@ -3955,7 +3942,7 @@ declare const RUNTIME_NOTICE_CUSTOM_TYPE = "runtime_notice";
 /**
  * Details of a {@link RUNTIME_NOTICE_CUSTOM_TYPE} entry. `noticeKind` is a
  * closed vocabulary owned by the daemon's builder (`RuntimeNoticeKind` in
- * agent-runtime) — the kernel persists and projects whatever kind arrives,
+ * agent-runtime) - the kernel persists and projects whatever kind arrives,
  * typed as string here for the same reason collaboration `kind` stays narrow
  * there and open here: the kernel must not need a release to learn a new one.
  */
@@ -4357,7 +4344,7 @@ declare function ScriptMapping(input: unknown): unknown;
 
 /**
  * Emitted by `AgentSession.reroot` when the session's working directory
- * transitions in place — the lifecycle replacement for the retired
+ * transitions in place - the lifecycle replacement for the retired
  * `getSessionCwdIssue` guard, which mis-modelled a differing cwd as a fault. A
  * re-root is a supported transition, never an error. `from`/`to` are the prior
  * and new roots; `reason` distinguishes the trigger (`"agent-reroot"` for an
@@ -4365,7 +4352,7 @@ declare function ScriptMapping(input: unknown): unknown;
  * move, `"worktree-isolation"` for the legacy worktree flow, or any host-supplied
  * string). Synthetic; herd-internal. Fed to subscribers and the
  * observability source; not persisted by the kernel (the host appends the durable
- * `cwd_transition` log entry — see herd-agent ARCHITECTURE.md → "Session cwd").
+ * `cwd_transition` log entry - see herd-agent ARCHITECTURE.md -> "Session cwd").
  */
 declare interface SessionCwdTransitionEvent {
     readonly type: "cwd_transition";
@@ -4395,7 +4382,7 @@ declare interface SessionInfoUpdatedExtensionEvent extends SessionInfoSnapshot {
 /**
  * Emitted the moment a silent overflow is detected: a provider accepted an
  * over-window request and reported usage past the context window without
- * erroring (#1280 telemetry trigger (c)). Detection-time and unconditional —
+ * erroring (#1280 telemetry trigger (c)). Detection-time and unconditional -
  * unlike the forced compaction it schedules, which can be deferred or skipped
  * by the post-turn guards (auto-compaction disabled, compaction in flight).
  * Synthetic; herd-internal; live-only.
@@ -4541,7 +4528,7 @@ declare const SUBAGENT_RESULT_CUSTOM_TYPE = "subagent_result";
 
 /**
  * A child-declared, openable result reference: a resolved URI + a display title.
- * Kernel-generic on purpose — herd-agent must not learn Bonsai "artifact" semantics.
+ * Kernel-generic on purpose - herd-agent must not learn Bonsai "artifact" semantics.
  */
 declare interface SubagentDeliverable {
     readonly uri: string;
@@ -4551,7 +4538,7 @@ declare interface SubagentDeliverable {
 /**
  * Details of a subagent-result context message. Provenance rides the fixed `provenance` key (the
  * `AttributionSource` family: `{source:"subagent", sourceId: childSessionId, label?}`), shared with
- * every other context kind — the legacy `attribution` sibling is no longer written.
+ * every other context kind - the legacy `attribution` sibling is no longer written.
  */
 declare interface SubagentResultDetails {
     readonly provenance: AttributionSource;
@@ -4566,10 +4553,10 @@ declare interface SubagentResultDetails {
      */
     readonly summary?: string;
     /**
-     * The settled task this result answers — the per-assignment correlation key
+     * The settled task this result answers - the per-assignment correlation key
      * (#2933). `childSessionId` alone is NOT an identity: follow-up tasks reuse
      * the child session, so one child can produce many results. Absent on rows
-     * persisted before the key existed — readers of legacy rows must tolerate
+     * persisted before the key existed - readers of legacy rows must tolerate
      * several same-`sourceId` rows with no task key and treat recency, not
      * first-match, as the tiebreaker.
      */
@@ -4598,14 +4585,14 @@ declare type SubagentResultMessage = CustomMessage<SubagentResultDetails> & {
 /**
  * One unified diagnostic for the extension substrates (tools, URI modules, converters, search
  * providers): a component misbehaved or an ambiguous registration was detected. Carries enough to
- * answer "where in the pipeline + which component" — the owning extension/layer is resolved at
+ * answer "where in the pipeline + which component" - the owning extension/layer is resolved at
  * normalization via the substrate attribution index. Never alters dispatch; the chosen/fallback
  * path still runs (and for `execute_threw` the original error still propagates to the agent).
  * Diagnostic; herd-internal.
  *
- * - `stage` — `match` (a predicate threw), `merge` (layer assembly dropped it), `execute` (the
+ * - `stage` - `match` (a predicate threw), `merge` (layer assembly dropped it), `execute` (the
  *   component's `read`/`convert`/`write` threw).
- * - `reason` — `match_threw` | `reserved_id` (claimed the reserved `builtin:` id) |
+ * - `reason` - `match_threw` | `reserved_id` (claimed the reserved `builtin:` id) |
  *   `scheme_conflict` (scheme ownership rejected the module) | `overlap`
  *   (2+ matched the same pass; first wins) | `spoof_mismatch` (a declared mime the leading
  *   bytes definitively contradict; selection re-keyed onto the true type) | `sync_threw` (the
@@ -6864,6 +6851,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         "not-found": "not-found";
         permission: "permission";
         unavailable: "unavailable";
+        waiting: "waiting";
     }>;
     retryable: z.ZodBoolean;
     action: z.ZodEnum<{
@@ -6872,6 +6860,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         retry: "retry";
         "correct-input": "correct-input";
         connect: "connect";
+        wait: "wait";
     }>;
     details: z.ZodOptional<z.ZodObject<{
         moduleId: z.ZodOptional<z.ZodString>;
@@ -6880,6 +6869,7 @@ declare const toolCallFailureCauseSchema: z.ZodObject<{
         uri: z.ZodOptional<z.ZodString>;
         path: z.ZodOptional<z.ZodString>;
         validationField: z.ZodOptional<z.ZodString>;
+        validationRule: z.ZodOptional<z.ZodString>;
         errorName: z.ZodOptional<z.ZodString>;
         errorCode: z.ZodOptional<z.ZodString>;
         providerCode: z.ZodOptional<z.ZodString>;
@@ -7768,7 +7758,7 @@ declare interface TUppercaseMapping extends TMappingType {
  *
  * `error` and `aborted` are kept apart rather than folded into one "not ok":
  * a provider that failed and a user who interrupted produce the same shape of
- * cost fact — a turn with no output — and only this distinguishes them.
+ * cost fact - a turn with no output - and only this distinguishes them.
  * Mirrors the vocabulary already exported for tool calls, plus the abort case
  * a model call has and a tool call does not.
  */
@@ -7780,7 +7770,7 @@ declare const TURN_COST_OUTCOMES: readonly ["ok", "error", "aborted"];
  *
  * Turn-bound kinds die with the run they were queued against
  * (`TURN_BOUND_CUSTOM_TYPES`), and that includes a placement a DURABLE rail
- * made — the rail's copy of the message is deleted from the kernel's queues
+ * made - the rail's copy of the message is deleted from the kernel's queues
  * with everyone else's. The rail cannot see that from outside: its push
  * resolved, so without this event its row stays marked delivered while nothing
  * is queued anywhere, and the delivery is owed forever.
@@ -7792,7 +7782,7 @@ declare const TURN_COST_OUTCOMES: readonly ["ok", "error", "aborted"];
  */
 declare interface TurnBoundDeliveryDiscardedSessionEvent {
     readonly type: "turn_bound_delivery_discarded";
-    /** `details.deliveryId` of the discarded message — the rail's own row identity. */
+    /** `details.deliveryId` of the discarded message - the rail's own row identity. */
     readonly deliveryId: string;
     /** The discarded message's `customType`, for the host's own diagnostics. */
     readonly customType: string;
@@ -7811,7 +7801,7 @@ declare interface TurnCostFact {
      * Without it a failed provider call is indistinguishable from a success at
      * call granularity: both arrive as a fact with zero tokens and no cost, and
      * the only failure signal anywhere is `run.settled.failureCategory`, which
-     * is absent whenever a run dies unsettled — exactly the incident shape.
+     * is absent whenever a run dies unsettled - exactly the incident shape.
      */
     readonly outcome?: TurnCostOutcome;
     /** pi provider id that served the turn. */
@@ -7835,7 +7825,7 @@ declare interface TurnCostFact {
      *
      * Absent whenever the span cannot be paired: the kernel's one-shot
      * completions (compaction, branch-summary) never fire pi's provider-request
-     * hook, and a turn the human aborted is deliberately left unmeasured — its
+     * hook, and a turn the human aborted is deliberately left unmeasured - its
      * wall time records when someone hit stop, not how fast the provider was.
      * A reader must treat absence as "not measured", never as zero.
      */
@@ -8197,7 +8187,7 @@ declare type TZipDistributionArray<Arguments extends TSchema[], DistributionArra
 
 declare const UI_ACTION_CUSTOM_TYPE = "ui_action";
 
-/** A generative-UI interaction — the human acting, carried with its originating tool call. */
+/** A generative-UI interaction - the human acting, carried with its originating tool call. */
 declare interface UiActionDetails {
     readonly provenance: AttributionSource;
     /**
@@ -8287,21 +8277,14 @@ declare interface UriAccessSessionEvent {
     readonly phase: UriAccessPhase;
     /**
      * The resolved connection's record id when connection resolution ran (see
-     * `UriAccess.connectionId`) — an opaque identity, never the account
+     * `UriAccess.connectionId`) - an opaque identity, never the account
      * `@selector` the `uri` contract strips. Replay consumers pass it back so a
      * re-read binds the SAME connection instead of blindly re-resolving.
      */
     readonly connectionId?: string;
-    /**
-     * Present (always `true`) when the owning module's `observes(uri)` predicate
-     * marks THIS resource observable (see `UriAccess.observable`) — the
-     * per-resource replayability signal ambient index consumers gate on for
-     * reads and CRUD mutations.
-     */
-    readonly observable?: true;
     /**
      * Present (always `true`) on an executed read whose provider fetch
-     * concluded with a principled not-found (see `UriAccess.notFound`) — the
+     * concluded with a principled not-found (see `UriAccess.notFound`) - the
      * retirement trigger for consumers holding state under this uri.
      */
     readonly notFound?: true;
@@ -8313,7 +8296,7 @@ declare interface UriAccessSessionEvent {
     };
     /**
      * The result identities an executed `search` dispatch returned, in rank
-     * order (see `UriAccess.resultUris`) — what the model actually saw, for
+     * order (see `UriAccess.resultUris`) - what the model actually saw, for
      * joining against later reads of the same URIs. Empty means a real
      * zero-hit search; absent means no result set applies.
      */
@@ -8322,6 +8305,33 @@ declare interface UriAccessSessionEvent {
     readonly at: string;
 }
 
+/**
+ * The indexable form a module returned with one executed read (see
+ * `RawResource.observation` in `@herd/uri`, whose `ObservationMaterial` this
+ * restates). Carries document text, so it is never a herd fact: the host
+ * routes it to its index alone and neither publishes nor stores it.
+ * Synthetic; herd-owned; live-only.
+ */
+declare interface UriObservationSessionEvent {
+    readonly type: "uri_observation";
+    /** The dispatch URI the read served (see `UriAccessSessionEvent.uri`). */
+    readonly uri: string;
+    readonly ownerModuleId: string;
+    /** The resolved connection's record id (see `UriAccessSessionEvent.connectionId`). */
+    readonly connectionId?: string;
+    readonly observation: {
+        readonly uri: string;
+        readonly kind: string;
+        readonly title?: string;
+        readonly text?: readonly string[];
+        readonly createdAt?: string;
+        readonly updatedAt?: string;
+        readonly version?: string;
+        readonly retainForMs?: number;
+    };
+    readonly sessionId: string;
+}
+
 declare interface Usage {
     input: number;
     output: number;
@@ -8347,14 +8357,14 @@ declare interface Usage {
 
 /**
  * The user-invoked message: everything the composer INTENTIONALLY pulled into a
- * send — today the resolved content of skill- and prompt-template-bound slash
- * commands — carried beside the human turn instead of fabricated into its text.
+ * send - today the resolved content of skill- and prompt-template-bound slash
+ * commands - carried beside the human turn instead of fabricated into its text.
  * The user turn stays exactly what was typed (`/pr-review 123`); this message
  * delivers what that intent resolved to, one message per send, in per-feature
- * sections (`skills`, `prompt_templates` — a future feature adds a SIBLING
+ * sections (`skills`, `prompt_templates` - a future feature adds a SIBLING
  * section, never a second meaning for an existing one). Sibling of
  * `dynamic_context` in grammar (a sectioned wrapper) but not in policy: it is
- * assembled synchronously and fail-closed at command dispatch — never a
+ * assembled synchronously and fail-closed at command dispatch - never a
  * retrieval pass, budget, or debounce, because the content IS the send's
  * meaning, not something computed from it.
  */
@@ -8369,18 +8379,18 @@ declare const USER_PASTED_CONTENT_CUSTOM_TYPE = "user_pasted_content";
 
 /**
  * The user shell command result: a command the HUMAN ran directly through the
- * composer's `!` shell escape — no model in the loop, no permission prompt —
+ * composer's `!` shell escape - no model in the loop, no permission prompt -
  * carried into context so the agent can pick up where the user's manual work
  * left off. The third verb of the user-origin family: `tab_context` is what the
  * user is looking at, `ui_action` is what they clicked, `user_shell_command` is
- * what they DID. Durable (never turn-bound) and it must never wake the agent —
+ * what they DID. Durable (never turn-bound) and it must never wake the agent -
  * delivery policy lives with the host (D1: silent context).
  */
 declare const USER_SHELL_COMMAND_CUSTOM_TYPE = "user_shell_command";
 
 /**
  * Details of a `user_invoked` message. The message `content` is empty by
- * construction — the model wrapper renders entirely from these typed sections
+ * construction - the model wrapper renders entirely from these typed sections
  * (the `dynamic_context` details-first posture). One typed slot per feature
  * section; both are always present (empty arrays elide their section at the
  * model boundary).
@@ -8393,7 +8403,7 @@ declare interface UserInvokedDetails {
 
 /**
  * One invocation entry inside a `user_invoked` feature section: the resource's
- * resolved name, the literal command the user typed (`/pr-review 123` — kept
+ * resolved name, the literal command the user typed (`/pr-review 123` - kept
  * verbatim, alias and all), and the resolved content that command pulled in.
  */
 declare interface UserInvokedEntry {
@@ -8454,7 +8464,7 @@ declare type UserPastedContentMessage = CustomMessage<UserPastedContentDetails>
  */
 declare interface UserShellCommandDetails {
     readonly provenance: AttributionSource;
-    /** The background-task id the run rode — correlates the card with live task events. */
+    /** The background-task id the run rode - correlates the card with live task events. */
     readonly taskId: string;
     readonly command: string;
     readonly cwd: string;
@@ -8474,7 +8484,7 @@ declare type UserShellCommandMessage = CustomMessage<UserShellCommandDetails> &
 
 /**
  * Live-only control signal emitted after a user shell command's typed result
- * landed. The host's delivery policy keys off it — today that policy is "never
+ * landed. The host's delivery policy keys off it - today that policy is "never
  * wake the agent" (D1 silent context), and this event is the seam a host would
  * use to flip a surface to conditional/auto respond later. Sibling of
  * {@link BackgroundTaskResultQueuedEvent}, split by origin: that one may wake,
@@ -8491,7 +8501,7 @@ declare interface UserShellCommandResultQueuedSessionEvent {
  * Where a user shell command's typed result landed (see
  * `AgentSession.runUserShellCommand`): `"follow_up"` joined a live run at
  * its follow-up boundary; `"appended"` was persisted straight into durable
- * history because the session was idle — model-visible from the next run,
+ * history because the session was idle - model-visible from the next run,
  * with NO run started.
  */
 declare type UserShellResultChannel = "follow_up" | "appended";