@yaklabs-ai/plugin-sdk 0.15.1 → 0.15.3

package/dist/kay-app-session-summary.d.ts

@@ -505,6 +505,7 @@ declare interface CustomAgentMessages {
     userInvoked: UserInvokedMessage;
     availabilityFacts: AvailabilityFactsMessage;
     midTurnCompactionOutcome: MidTurnCompactionOutcomeMessage;
+    runContinuationCarrier: RunContinuationCarrierMessage;
     subagentResult: SubagentResultMessage;
     backgroundTaskResult: BackgroundTaskResultMessage;
 }
@@ -1235,12 +1236,23 @@ declare interface KayAppCorpus {
      */
     readEntries(sessionId: string): AsyncIterable<TranscriptEntry>;
     /**
-     * Read one bounded physical JSONL page. The host resolves `sessionId` to its authoritative
-     * indexed path and validates the opaque cursor before opening it. When `throughEntryId` is
-     * supplied, the cursor stops at that entry's transaction line; a V4 line may carry later
-     * entries, which are returned for the caller to filter and are replayed on the next page.
-     * A page can hold no entries at all (a run of storage lines) while more follows; a record
-     * longer than the page is stepped over and counted in `oversizedRecords`.
+     * Active-branch entries from the latest canonical human turn opener (send companions included)
+     * through the anchor, oldest first. Mid-turn steers and machine wakes remain inside that window;
+     * attachment-only openers and fresh card answers count. Missing sessions/anchors return [];
+     * unsupported hosts may omit it.
+     * Reads never fall back to materializing the full log.
+     */
+    readLatestHumanWindow?(sessionId: string, options?: {
+        readonly throughEntryId?: string;
+    }): Promise<readonly TranscriptEntry[]>;
+    /**
+     * Read one bounded page of a session's stored transcript. The host resolves `sessionId` to its
+     * authoritative indexed path and validates the opaque cursor before reading. When
+     * `throughEntryId` is supplied, the page ends at that entry and the cursor stays at the start of
+     * the commit holding it: the commit's other entries are returned for the caller to filter, and
+     * the next page replays that commit. A page can hold no entries at all (storage records with no
+     * entry) while more follows; a record longer than the page is stepped over and counted in
+     * `oversizedRecords`.
      */
     readEntryBatch?(sessionId: string, options?: {
         readonly cursor?: JsonValue_3;
@@ -1255,7 +1267,7 @@ declare interface KayAppCorpus {
     readSessionSourceMark(sessionId: string): Promise<KayAppCorpusSourceMark | undefined>;
 }
 
-/** One bounded physical page from the host's incremental JSONL reader. */
+/** One bounded page from the host's stored transcript reader. */
 declare interface KayAppCorpusEntryBatch {
     readonly entries: readonly TranscriptEntry[];
     /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
@@ -1758,13 +1770,7 @@ declare interface MessageEntry extends EntryBase {
 /** TypeBox instantiation metrics */
 declare const Metrics: TMetrics;
 
-/**
- * A hidden kernel statement delivered before resuming a tool-requested compaction stop.
- *
- * Module-local, unlike every sibling above it: this message is never rendered and never matched
- * by name outside this file, so exporting the string would only publish something no surface
- * consumes. It earns an export the day one needs to recognise it.
- */
+/** A hidden kernel statement delivered before resuming a tool-requested compaction stop. */
 declare const MID_TURN_COMPACTION_OUTCOME_CUSTOM_TYPE = "mid_turn_compaction_outcome";
 
 declare interface MidTurnCompactionOutcomeDetails {
@@ -2424,6 +2430,34 @@ declare function ReturnType_2<Type extends TSchema>(type: Type, options?: TSchem
 /** Creates a deferred ReturnType action. */
 declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TReturnTypeDeferred<Type>;
 
+/**
+ * The hidden message a continued run rides as its admission ticket (a mid-turn compaction
+ * resume, a run-recovery re-drive). The engine writes it; this package's placement rows keep it
+ * out of the canonical transcript.
+ */
+declare const RUN_CONTINUATION_CARRIER_CUSTOM_TYPE = "herd_run_continuation";
+
+/**
+ * What a {@link RUN_CONTINUATION_CARRIER_CUSTOM_TYPE} carrier records about the failed turns it
+ * continues.
+ */
+declare interface RunContinuationCarrierDetails {
+    readonly provenance: {
+        readonly source: "core";
+    };
+    /**
+     * Visible text the failed turns since the previous carrier streamed before they died. Absent
+     * when they showed none (thinking, an unexecuted tool call, or a thrown attempt): such a
+     * carrier is plain.
+     */
+    readonly shownText?: string;
+}
+
+declare type RunContinuationCarrierMessage = CustomMessage<RunContinuationCarrierDetails> & {
+    readonly customType: typeof RUN_CONTINUATION_CARRIER_CUSTOM_TYPE;
+    readonly display: false;
+};
+
 /**
  * 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.

package/dist/kay-app.d.ts

@@ -755,6 +755,7 @@ declare interface CustomAgentMessages {
     userInvoked: UserInvokedMessage;
     availabilityFacts: AvailabilityFactsMessage;
     midTurnCompactionOutcome: MidTurnCompactionOutcomeMessage;
+    runContinuationCarrier: RunContinuationCarrierMessage;
     subagentResult: SubagentResultMessage;
     backgroundTaskResult: BackgroundTaskResultMessage;
 }
@@ -921,6 +922,18 @@ declare interface DeferredHandle {
     data?: JsonValue_4;
 }
 
+/**
+ * Register an ordinary workflow that polls connected accounts with independent JSON cursors.
+ * First polls initialize silently. Failed or skipped accounts retain their cursor; removed
+ * accounts are pruned. Publication finishes before replacement state is returned.
+ *
+ * Credential resolution and provider reads share a step so credentials are never step outputs.
+ * Poll callbacks must keep secrets out of their returned cursor, events, and summary. Resolution
+ * errors fail the run with a sanitized message; provider poll errors isolate the account.
+ * Key events at their source: a step can repeat before its result commits or after an engine update.
+ */
+export declare function definePoller<Cursor extends JsonValue>(app: Pick<KayAppPluginApi, "workflows" | "auth" | "events">, localId: string, options: KayAppPollerOptions<Cursor>): void;
+
 /** Creates a Dependent type */
 declare function Dependent<If extends TSchema, Then extends TSchema, Else extends TSchema>(if_: If, then_: Then, else_: Else, options?: TSchemaOptions): TDependent<If, Then, Else>;
 
@@ -1397,6 +1410,14 @@ declare const Factor: (input: string) => [unknown, string] | [];
 
 declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unknown]): unknown;
 
+/**
+ * The `ErrorOptions` for a workflow that fails BECAUSE this run failed: the run's retained
+ * failure ref as the error's `cause`, so the host reports that failure, with the same identity
+ * the session kept, instead of guessing from whichever run settled last. Empty when the run kept
+ * no failure: the throw is then the workflow's own.
+ */
+export declare function failedRunCause(outcome: KayAppSessionRunOutcome): ErrorOptions;
+
 declare type ForecastInterval = "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
 
 /** Creates a Function type. */
@@ -2468,11 +2489,25 @@ export declare interface KayAppAutomationBinding {
     readonly nextDueAtMs?: number;
     readonly expiresAtMs?: number;
     readonly maxRuns?: number;
+    readonly concurrency?: KayAppAutomationConcurrency;
     readonly runCount: number;
     /** Why a script binding's last tick failed and paused it, when it did. */
     readonly scriptLastError?: string;
 }
 
+/**
+ * How many of an automation's runs may be in progress at once. Absent means `sequential`: one at
+ * a time, in order. `parallel` runs up to `limit` at once (1 to 32, default 4), for an automation
+ * whose runs each handle their own event and can safely overlap, such as replying to separate
+ * emails.
+ */
+export declare type KayAppAutomationConcurrency = {
+    readonly mode: "sequential";
+} | {
+    readonly mode: "parallel";
+    readonly limit?: number;
+};
+
 export declare type KayAppAutomationCondition = KayAppAutomationPluginEventCondition | Extract<KayAppAutomationConditionInput, {
     readonly kind: "time";
 }> | KayAppAutomationUriChangeCondition | {
@@ -2533,10 +2568,8 @@ export declare interface KayAppAutomationContext {
 
 export declare type KayAppAutomationEffect = {
     /**
-     * STORED only: a binding created before the 2026-09-28 owner ruling (agents and plugins
-     * may not create `spawn-session` automations) can still carry this effect, so a read must
-     * still parse it. Absent from {@link KayAppAutomationEffectInput}, so no NEW binding can
-     * be minted with it.
+     * Starts a new session each time the automation fires. Created only with
+     * `owner: "user"`; the creating session's directory and project are stamped here.
      */
     readonly kind: "spawn-session";
     readonly prompt: string;
@@ -2561,16 +2594,20 @@ export declare type KayAppAutomationEffect = {
 };
 
 /**
- * What a plugin may CREATE an automation with. `spawn-session` is deliberately absent: owner
- * ruling (2026-09-28) forbids a plugin (or an agent) from minting a `spawn-session` binding —
- * durable recurring agent work belongs to a plugin workflow (`app.workflows.define` +
- * `ctx.runAgent`) or a direct `app.sessions.run`. A binding created before that ruling can still
- * carry the effect and still reads and runs; see {@link KayAppAutomationEffect}, the STORED type
- * this input narrows.
+ * What a plugin may CREATE an automation with; {@link KayAppAutomationEffect} is the STORED type
+ * this input narrows. `spawn-session` needs `owner: "user"`: an automation the creating session
+ * owns is a follow-up that brings that session back, so it cannot start a new one.
+ * `deliver-turn` is the reverse, session-owned only. A script the user owns references a skill
+ * file (`ref: {kind: "skill-file"}`), because it has no session scripts folder.
  */
 export declare type KayAppAutomationEffectInput = {
     readonly kind: "deliver-turn";
     readonly prompt: string;
+} | {
+    readonly kind: "spawn-session";
+    readonly prompt: string;
+    /** Resolve the new session's model by tier instead of the default. */
+    readonly tier?: "small" | "medium" | "large" | "ultra";
 } | {
     readonly kind: "script";
     /** The file this automation runs; every stored binding carries one. */
@@ -2709,7 +2746,7 @@ export declare interface KayAppAutomationRun {
     readonly id: string;
     readonly bindingId: string;
     readonly logicalKey: string;
-    readonly status: "claimed" | "queued" | "running" | "succeeded" | "failed" | "skipped" | "abandoned";
+    readonly status: "claimed" | "queued" | "running" | "succeeded" | "failed" | "skipped";
     readonly match: KayAppAutomationMatch;
     readonly generation: string;
     readonly claimedAtMs: number;
@@ -2783,16 +2820,17 @@ export declare type KayAppAutomationRunOutcome = {
 } | {
     readonly status: "failed";
     readonly summary?: KayAppRunSummary | undefined;
-    readonly reason: "executor_failed" | "permission_denied" | "surface_unavailable" | "target_gone";
+    /**
+     * Which part of the lane refused or failed. Absent on a run an earlier build recorded with
+     * a reason this build no longer names; nothing is reconstructed.
+     */
+    readonly reason?: "executor_failed" | "permission_denied" | "surface_unavailable" | "owner_missing" | "target_missing" | "declaration_gone" | undefined;
     readonly message?: string | undefined;
     /** How many tries the run's effect took, when more than one. */
     readonly tries?: number | undefined;
 } | {
     readonly status: "skipped";
-    readonly reason: "already_running" | "binding_inactive" | "circuit_breaker" | "concurrency_capped" | "guard_not_satisfied" | "missed_window" | "timer_cancelled";
-} | {
-    readonly status: "abandoned";
-    readonly reason: "daemon_restart";
+    readonly reason: "already_running" | "binding_inactive" | "guard_not_satisfied" | "missed_window" | "timer_cancelled";
 };
 
 export declare interface KayAppAutomations {
@@ -2824,6 +2862,12 @@ export declare interface KayAppAutomations {
     create(input: {
         readonly name: string;
         readonly description?: string;
+        /**
+         * Who owns the new automation. `session` (the default) ties it to the calling session;
+         * `user` makes it the person's own: it outlives that session, any session may switch it
+         * off, run or delete it, and the Automations page lists it. Requires SDK 0.15.3.
+         */
+        readonly owner?: "session" | "user";
         readonly condition: KayAppAutomationConditionInput;
         readonly effect: KayAppAutomationEffectInput;
         readonly enabled?: boolean;
@@ -2831,6 +2875,7 @@ export declare interface KayAppAutomations {
         readonly catchUpGraceMs?: number;
         readonly expiresAtMs?: number;
         readonly maxRuns?: number;
+        readonly concurrency?: KayAppAutomationConcurrency;
     }, ctx: KayAppAutomationContext): Promise<{
         readonly kind: "created";
         readonly binding: KayAppAutomationBinding;
@@ -3115,12 +3160,23 @@ export declare interface KayAppCorpus {
      */
     readEntries(sessionId: string): AsyncIterable<TranscriptEntry>;
     /**
-     * Read one bounded physical JSONL page. The host resolves `sessionId` to its authoritative
-     * indexed path and validates the opaque cursor before opening it. When `throughEntryId` is
-     * supplied, the cursor stops at that entry's transaction line; a V4 line may carry later
-     * entries, which are returned for the caller to filter and are replayed on the next page.
-     * A page can hold no entries at all (a run of storage lines) while more follows; a record
-     * longer than the page is stepped over and counted in `oversizedRecords`.
+     * Active-branch entries from the latest canonical human turn opener (send companions included)
+     * through the anchor, oldest first. Mid-turn steers and machine wakes remain inside that window;
+     * attachment-only openers and fresh card answers count. Missing sessions/anchors return [];
+     * unsupported hosts may omit it.
+     * Reads never fall back to materializing the full log.
+     */
+    readLatestHumanWindow?(sessionId: string, options?: {
+        readonly throughEntryId?: string;
+    }): Promise<readonly TranscriptEntry[]>;
+    /**
+     * Read one bounded page of a session's stored transcript. The host resolves `sessionId` to its
+     * authoritative indexed path and validates the opaque cursor before reading. When
+     * `throughEntryId` is supplied, the page ends at that entry and the cursor stays at the start of
+     * the commit holding it: the commit's other entries are returned for the caller to filter, and
+     * the next page replays that commit. A page can hold no entries at all (storage records with no
+     * entry) while more follows; a record longer than the page is stepped over and counted in
+     * `oversizedRecords`.
      */
     readEntryBatch?(sessionId: string, options?: {
         readonly cursor?: JsonValue;
@@ -3135,7 +3191,7 @@ export declare interface KayAppCorpus {
     readSessionSourceMark(sessionId: string): Promise<KayAppCorpusSourceMark | undefined>;
 }
 
-/** One bounded physical page from the host's incremental JSONL reader. */
+/** One bounded page from the host's stored transcript reader. */
 export declare interface KayAppCorpusEntryBatch {
     readonly entries: readonly TranscriptEntry[];
     /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
@@ -3785,11 +3841,9 @@ export declare interface KayAppPaths {
      *
      * Unlike `telemetryRoot`, this can be granted yet absent: compositions that spawn no log lane
      * (test and eval hosts) hand the daemon no logs directory, and the field is then omitted rather
-     * than guessed. Event content redaction differs by lane and configuration — the daemon lane
-     * omits tool content outright; the Desktop lane captures it when `observability.contentCapture`
-     * is on (off by default in packaged builds, on by default unpackaged — a packaged user CAN
-     * enable it, so never assume rows from a packaged install are content-free). Absent `content`
-     * on a row is the normal case.
+     * than guessed. Desktop and daemon logs contain the same diagnostic facts exported to
+     * PostHog; call content is never recorded. Historical files can contain private content
+     * from older builds, and diagnostic errors/stacks can contain file paths.
      */
     readonly logsRoot?: string;
 }
@@ -3926,7 +3980,7 @@ export declare interface KayAppPluginApi {
      */
     readonly sessionEvents: KayAppSessionEvents;
     /**
-     * Grant-gated time-triggered workflow registration. Present for a plugin the host has a workflow
+     * Grant-gated workflow registration, started on a time schedule or the plugin's own events. Present for a plugin the host has a workflow
      * namespace for; `undefined` otherwise. The first `define` asks for the `workflows.define` claim
      * in the user's grant ledger — no manifest request and no source-class gate — and it is decided
      * once `activate()` resolves: an ungranted plugin does not start until the user allows it. A
@@ -4039,6 +4093,36 @@ export declare interface KayAppPluginEvents {
     publish(localId: string, input: PluginEventPublishInput): void;
 }
 
+export declare interface KayAppPollerEvent {
+    readonly localId: string;
+    readonly input: PluginEventPublishInput;
+}
+
+export declare interface KayAppPollerOptions<Cursor extends JsonValue> {
+    readonly name: string;
+    readonly description: string;
+    /** Interval in milliseconds; the workflow engine enforces its scheduling floor. */
+    readonly every: number;
+    readonly serviceId: string;
+    readonly schemeId?: string;
+    readonly resolveCredential: (account: KayAppAccountSummary, runId: string) => Promise<KayAppBackgroundCredentialResult>;
+    /** Cursor, events, and summary must contain no credentials or other secrets. */
+    readonly poll: (input: {
+        readonly account: KayAppAccountSummary;
+        readonly cursor: Cursor | undefined;
+        readonly credential: Extract<KayAppBackgroundCredentialResult, {
+            readonly status: "resolved";
+        }>;
+        readonly runId: string;
+    }) => Promise<KayAppPollResult<Cursor>>;
+}
+
+export declare interface KayAppPollResult<Cursor extends JsonValue> {
+    readonly cursor: Cursor;
+    readonly events?: readonly KayAppPollerEvent[];
+    readonly summary?: string;
+}
+
 export declare type KayAppProcessingSpeed = "standard" | "fast";
 
 /**
@@ -4482,6 +4566,17 @@ export declare type KayAppSessionRunCompletion = {
 /** Provider-neutral recorded classification; an unclassified failure omits the field. */
 export declare type KayAppSessionRunFailureReason = Exclude<RunFailureReason, "unknown">;
 
+/**
+ * The identity of a failed run's retained failure: the same ref the runtime keeps on the
+ * session and the automation run. A workflow that fails BECAUSE this run failed passes it as
+ * its error's `cause` (`{ cause: { failureRef } }`), and the host reports that failure, not a
+ * guess from whichever run settled last.
+ */
+export declare interface KayAppSessionRunFailureRef {
+    readonly authority: string;
+    readonly id: string;
+}
+
 /** One host-tool name in a one-shot system run's explicit ceiling. */
 export declare type KayAppSessionRunHostToolName = string;
 
@@ -4568,6 +4663,8 @@ export declare interface KayAppSessionRunInput {
 
 export declare type KayAppSessionRunOutcome = (KayAppSessionRunBase & {
     readonly state: "failed";
+    /** The retained failure's identity, when the runtime kept one for this run. */
+    readonly failureRef?: KayAppSessionRunFailureRef | undefined;
     /** Present when the runtime could classify the failure. */
     readonly failureReason?: KayAppSessionRunFailureReason | undefined;
     /** Bounded provider-suggested delay before retrying this terminal failure. */
@@ -6009,14 +6106,13 @@ export declare interface KayAppWhiteboardTypes {
  * - **Do not hold state in module scope and expect it to survive.** A recovery may happen in a
  *   different process. Anything you need later belongs in a step's return value.
  */
-export declare interface KayAppWorkflowContext {
+export declare interface KayAppWorkflowContext<Trigger extends KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger> {
     /** State from the last successful run; undefined until a run saves it. */
     readonly state: JsonValue | undefined;
     readonly automationId: string;
     readonly runId: string;
-    readonly match: Extract<KayAppAutomationMatch, {
-        readonly kind: "time" | "manual";
-    }>;
+    /** What started this run; see {@link KayAppWorkflowMatch}. */
+    readonly match: KayAppWorkflowMatch<Trigger>;
     /**
      * Record a step's result for replay.
      *
@@ -6074,17 +6170,23 @@ export declare interface KayAppWorkflowContext {
     runAgent(agent: KayAppAgentDefinitionRef, input: Omit<KayAppSessionRunInput, "agent">): Promise<KayAppSessionRunOutcome>;
 }
 
-export declare interface KayAppWorkflowDefinition {
+export declare interface KayAppWorkflowDefinition<Trigger extends KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger> {
     readonly name: string;
     /** Plain-text purpose, at most 280 characters. */
     readonly description: string;
     readonly instructions?: readonly KayAppWorkflowInstruction[];
     readonly perRunNote?: string;
-    readonly trigger: Extract<KayAppAutomationConditionInput, {
-        readonly kind: "time";
-    }>;
-    readonly run: (context: KayAppWorkflowContext) => Promise<{
-        /** Replacement JSON state, at most 64 KiB; omission keeps the previous value. */
+    readonly trigger: Trigger;
+    /**
+     * How many runs may be in progress at once. Absent means `sequential`. A `parallel` workflow
+     * suits an event trigger whose runs each handle their own event; it cannot return `state`.
+     */
+    readonly concurrency?: KayAppAutomationConcurrency;
+    readonly run: (context: KayAppWorkflowContext<Trigger>) => Promise<{
+        /**
+         * Replacement JSON state, at most 64 KiB; omission keeps the previous value. Only a
+         * sequential workflow may return it: a `parallel` run that does fails.
+         */
         readonly state?: JsonValue | undefined;
         readonly summary: KayAppRunSummary;
         readonly produced?: KayAppRunProduced;
@@ -6092,6 +6194,16 @@ export declare interface KayAppWorkflowDefinition {
     }>;
 }
 
+/**
+ * The event that started a run, as the publisher sent it. The publishing session is withheld.
+ * This is the run's private input, so it carries `payload`, `related` and `key`, which the
+ * public run history's event identity leaves out.
+ */
+export declare type KayAppWorkflowEvent = Readonly<Omit<PluginEventEnvelope, "related" | "source">> & {
+    readonly related?: Readonly<Record<string, string | readonly string[]>> | undefined;
+    readonly source: Readonly<Omit<PluginEventEnvelope["source"], "sessionId">>;
+};
+
 /** Fail a workflow while retaining its own explanation beside this attempt. */
 export declare class KayAppWorkflowFailure extends Error {
     readonly summary: KayAppRunSummary;
@@ -6123,11 +6235,43 @@ export declare type KayAppWorkflowInstruction = {
     readonly ref: KayAppAutomationScriptRef;
 };
 
+/**
+ * What started a run, by trigger: a time workflow sees `time`, an event workflow sees
+ * `plugin-event`, and either sees `manual` for Run now and retries. A retry, even of an event run,
+ * arrives as `manual` without the event.
+ */
+export declare type KayAppWorkflowMatch<Trigger extends KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger> = Extract<KayAppAutomationMatch, {
+    readonly kind: "manual";
+}> | (Trigger extends {
+    readonly kind: "plugin-event";
+} ? {
+    readonly kind: "plugin-event";
+    readonly event: KayAppWorkflowEvent;
+} : Extract<KayAppAutomationMatch, {
+    readonly kind: "time";
+}>);
+
 export declare interface KayAppWorkflows {
-    define(localId: string, definition: KayAppWorkflowDefinition): void;
+    define<Trigger extends KayAppWorkflowTrigger>(localId: string, definition: KayAppWorkflowDefinition<Trigger>): void;
     inspect(localId: string, options?: KayAppWorkflowInspectOptions): Promise<KayAppWorkflowInspection>;
 }
 
+export declare type KayAppWorkflowTimeTrigger = Extract<KayAppAutomationConditionInput, {
+    readonly kind: "time";
+}>;
+
+/**
+ * What starts a workflow: a time schedule, or one or more of this plugin's own declared events.
+ *
+ * An event trigger names full event types (`google.gmail.message.received`) and takes the same
+ * filters as a `plugin-event` automation. Each matching event starts one run. Only events this
+ * plugin declares are accepted; another plugin's events are refused at `define`.
+ *
+ * A run is not started by an event that one of this workflow's own runs published, as long as the
+ * publish names the run: pass `source: { runId: ctx.runId }` (the Poller helper does).
+ */
+export declare type KayAppWorkflowTrigger = KayAppWorkflowTimeTrigger | KayAppAutomationPluginEventCondition;
+
 /**
  * Read/arrange access to the live desktop workspace (tabs, panes, the shell chrome). Always
  * present. `snapshot` is ungated; `execute` is checked per call against the `workspace.command`
@@ -6534,13 +6678,7 @@ declare interface MessageEntry extends EntryBase {
 /** TypeBox instantiation metrics */
 declare const Metrics: TMetrics;
 
-/**
- * A hidden kernel statement delivered before resuming a tool-requested compaction stop.
- *
- * Module-local, unlike every sibling above it: this message is never rendered and never matched
- * by name outside this file, so exporting the string would only publish something no surface
- * consumes. It earns an export the day one needs to recognise it.
- */
+/** A hidden kernel statement delivered before resuming a tool-requested compaction stop. */
 declare const MID_TURN_COMPACTION_OUTCOME_CUSTOM_TYPE = "mid_turn_compaction_outcome";
 
 /**
@@ -7705,9 +7843,37 @@ declare function ReturnType_2<Type extends TSchema>(type: Type, options?: TSchem
 /** Creates a deferred ReturnType action. */
 declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TReturnTypeDeferred<Type>;
 
+/**
+ * The hidden message a continued run rides as its admission ticket (a mid-turn compaction
+ * resume, a run-recovery re-drive). The engine writes it; this package's placement rows keep it
+ * out of the canonical transcript.
+ */
+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"];
 
+/**
+ * What a {@link RUN_CONTINUATION_CARRIER_CUSTOM_TYPE} carrier records about the failed turns it
+ * continues.
+ */
+declare interface RunContinuationCarrierDetails {
+    readonly provenance: {
+        readonly source: "core";
+    };
+    /**
+     * Visible text the failed turns since the previous carrier streamed before they died. Absent
+     * when they showed none (thinking, an unexecuted tool call, or a thrown attempt): such a
+     * carrier is plain.
+     */
+    readonly shownText?: string;
+}
+
+declare type RunContinuationCarrierMessage = CustomMessage<RunContinuationCarrierDetails> & {
+    readonly customType: typeof RUN_CONTINUATION_CARRIER_CUSTOM_TYPE;
+    readonly display: false;
+};
+
 declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
 
 /**