import type { SessionTokenBudgetSummary } from '../../store/budget/index.js';
import type { ActivityStatus, ActivityType } from '../activity/index.js';
import type { BaseAgentResult } from '../agent/base.js';
import type { CostInfo, PlatformError, TokenUsage } from '../common/index.js';
import type { CheckpointId, ToolCallSummary } from '../hitl/index.js';
import type { ActivityId, MessageId, PlanId, PluginId, SandboxId, SessionId, TaskId, ToolUseId, TurnId } from '../ids/index.js';
import type { Message } from '../message/index.js';
import type { PlanStep } from '../plan/index.js';
import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js';
import type { TaskStatus } from '../task/index.js';
import type { ToolResultView } from '../tool/presentation.js';
import type { CancelCause } from './cancel-cause.js';
import type { FencingToken } from './durable.js';
import type { Lineage } from './lineage.js';
import type { MessageStopReason, StopReason } from './stop-reason.js';
import type { SubSessionKind } from './sub-session.js';
import type { Origin, TurnBudgetBinding, TurnConfigSnapshot, TurnSettlement } from './turn.js';
/**
 * Live events of a session: the stream a host listens to while a turn runs.
 *
 * The model is session → turn → message. Every event names the session it
 * belongs to (`sessionId`) and, when it happened inside a turn, the turn
 * (`turnId`). Events that can only happen inside a turn declare `turnId`
 * required; the ones a host can cause between turns (a manual compaction, a
 * background job exiting, a policy swap, a session hook, task and sandbox
 * bookkeeping) declare it optional, and an absent `turnId` means "outside any
 * turn".
 *
 * Every event whose type {@link isEphemeralEvent} does not name is also
 * appended to the session log as a record of the same `type`, with its
 * payload minus `sessionId`, `turnId` and `lineage` (those live on the record
 * envelope, or follow from `session_started.parent`). The record schema is in
 * `./records.ts` and `docs/sdk/session-log.md`.
 */
export interface SessionEventEnvelope {
    /** Session record schema version; see `SESSION_RECORD_SCHEMA_VERSION`. */
    v?: 1;
    /**
     * Delegation linkage, present on events relayed from a child session to a
     * listener of its parent. `depth` is 0 at the root session.
     */
    lineage?: Lineage;
    /**
     * This event's position in its session's log, from 1.
     *
     * Present means recorded: the writer appends the record first and only then
     * hands the event to the live stream, so a `seq` a consumer sees is one the
     * log contains, and it works as a reconnect cursor. Absent means not
     * recoverable: an ephemeral event, an event whose append failed (still
     * delivered, because losing the news of a failure is worse than delivering
     * it without a cursor), or an event relayed from a child session, whose
     * position is in the child's own log.
     *
     * Per session, not per stream: a listener that also receives child events
     * keeps one cursor per `sessionId`.
     */
    seq?: number;
    /**
     * The lease fence the session log was written under (the record's `gen`).
     * A takeover raises it, which makes a cursor from before the takeover
     * detectable rather than silently wrong.
     */
    generation?: FencingToken;
}
type CoreSessionEvent = {
    type: 'tool_calls_admitted';
    sessionId: SessionId;
    turnId: TurnId;
    kind: 'initialize' | 'batch' | 'nested' | 'retry';
    /** Newly reserved attempts; zero only for ledger initialization. */
    count: number;
    /** Cumulative reserved attempts, including abandoned reservations. */
    used: number;
    limit: number;
}
/**
 * A turn began. The prompt that opened it is the `message` record named by
 * `userMessageId`, appended right after this one and inside the turn.
 */
 | {
    type: 'turn_started';
    sessionId: SessionId;
    turnId: TurnId;
    userMessageId: MessageId;
    systemPrompt?: string;
    config: TurnConfigSnapshot;
    /** Which protocol and which caller-side ids opened the turn. */
    origin?: Origin;
    /** The token ledger this turn spends from, keyed by the root turn. */
    budget?: TurnBudgetBinding;
} | {
    type: 'iteration_started';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
}
/**
 * Who answers when this turn asks a human, changed mid-turn.
 *
 * The policy used to be a closure captured at `query()` start, so
 * changing it meant ending the turn. Now it is a value a host can swap —
 * and a swap that left no trace would be the worst version of that: an
 * incident review would see approvals with no way to tell which rule
 * granted them.
 *
 * Names, not handlers. A durable log cannot hold a function, and
 * `[Function (anonymous)]` is what a log says when somebody tries.
 */
 | {
    type: 'approval_policy_changed';
    sessionId: SessionId;
    turnId?: TurnId;
    from: string;
    to: string;
    reason: string;
}
/**
 * What the model was actually asked, when it changed.
 *
 * `turn_started` records a system prompt once, and tool schemas never
 * reached the transcript at all — yet the effective envelope changes
 * mid-turn: `prepareStep` rewrites the system text, narrows the tool
 * list, or swaps the model, and a step's skills ride an ephemeral
 * trailing system message. So a transcript showed one prompt and a turn
 * that had asked several different questions.
 *
 * Emitted only when the tuple DIFFERS from the last one recorded. The
 * common case — nothing changed — costs one hash and no event, because
 * a per-iteration copy of an unchanged system prompt is the fastest way
 * to make a durable log too large to read.
 */
 | {
    type: 'request_envelope';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    model: string;
    /** Leading system messages plus this step's preamble, concatenated. */
    systemPrompt: string;
    toolNames: readonly string[];
    /**
     * Stable hash over the sorted tool schemas. A name list cannot see
     * a tool whose SCHEMA changed while its name did not — which is
     * the change most likely to alter what the model does and least
     * likely to be noticed.
     */
    toolSchemaDigest: string;
} | {
    type: 'iteration_completed';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    hasToolCalls: boolean;
}
/**
 * What a compaction pass removed, recorded before it is gone.
 *
 * Emitted BEFORE the context is replaced, and appended to the session log
 * with the pass's `compaction` record, so the shed messages stay in the log
 * for audit, search and undo even though the next request no longer
 * carries them. The fold that builds the context reads the `compaction`
 * record (its summary and kept message ids), not this event.
 *
 * Carries whole message bodies, tool output included, which is why both
 * external wire mappers decline it.
 */
 | {
    type: 'compaction_shed';
    sessionId: SessionId;
    turnId?: TurnId;
    iteration: number;
    /** Exactly the messages the pass removed, in their original order. */
    messages: Message[];
    /** Automatic threshold, provider rejection, or a host-requested pass. */
    reason: 'threshold' | 'overflow' | 'manual';
} | {
    type: 'compaction_completed';
    sessionId: SessionId;
    turnId?: TurnId;
    iteration: number;
    /** Messages before and after the pass. */
    messagesBefore: number;
    messagesAfter: number;
    /** Context size in tokens before and after. */
    tokensBefore: number;
    tokensAfter: number;
    /** Whether `tokensBefore` came from the provider or a heuristic. */
    measuredBy: 'provider' | 'estimate';
    /** The window the trigger measured against, and where it came from. */
    contextWindowTokens: number;
    windowSource: 'config' | 'provider' | 'model-table' | 'default';
    /**
     * False when the pass could not get the context below
     * `resetThreshold` — the trigger is still armed, and a host may
     * want to surface that the turn is running tight.
     */
    reachedResetThreshold?: boolean;
}
/**
 * Oversized tool results were emptied instead of the history being
 * summarized.
 *
 * This is the most common context-relief path and it was the only one
 * that emitted nothing. It edits the conversation the model sees —
 * `tool_result` bodies are replaced, irrecoverably — so a host reading
 * the session log saw results it no longer has and no record of why.
 * The two summarization outcomes were both on the wire; the cheap one
 * that runs far more often was not.
 *
 * Emitted on BOTH branches. `reliefWasEnough: false` means the clear
 * happened and was insufficient, so a full summarization followed and a
 * `compaction_completed` is coming — the history took two edits, not
 * one, and a reader that only saw the second would misattribute the
 * first.
 */
 | {
    type: 'compaction_tool_results_cleared';
    sessionId: SessionId;
    turnId?: TurnId;
    iteration: number;
    /** How many `tool_result` bodies were emptied. */
    clearedCount: number;
    /** Assistant narrations cut to their first sentence by the salience pass, when it ran. */
    stubbedCount?: number;
    /** Characters removed, summed across those results. */
    charsReclaimed: number;
    /** `charsReclaimed` as tokens, by the same estimate the trigger uses. */
    reclaimedTokens: number;
    /**
     * Whether the clear alone brought the context back under
     * `triggerThreshold`. `false` means summarization ran afterwards.
     */
    reliefWasEnough: boolean;
}
/**
 * A compaction pass ran and shed nothing, so the history is unchanged.
 *
 * A shed that did not happen is exactly as consequential as one that did,
 * and until this existed only one of them was on the wire. The three
 * decline paths all reached a log line — and a host that silences its
 * logger, which every command-line entry point does, made a failed
 * compaction invisible to the user, to the host AND to the model. The turn
 * then continued at full context toward a provider rejection several turns
 * later that named none of this.
 *
 * The history is guaranteed untouched on every one of these: the reducer's
 * result is installed whole or not at all, so there is no partial state to
 * reason about. That is the property that makes reporting sufficient and a
 * repair unnecessary.
 */
 | {
    type: 'compaction_failed';
    sessionId: SessionId;
    turnId?: TurnId;
    iteration: number;
    /**
     * Which decline path was taken. These want different responses, so
     * a single "it failed" would put the reader back where the silence
     * did:
     *
     * - `reducer_threw` — the reducer raised. Usually a bug or a failed
     *   model call inside a summarising reducer; the next pass may work.
     * - `shed_nothing` — it returned no fewer messages than it was
     *   given. The history is already at its floor, or the reducer's
     *   own threshold disagrees with the trigger's, and every later
     *   pass will decline identically.
     * - `split_tool_pair` — its result separated a `tool_use` from its
     *   `tool_result`, so it was refused wholesale rather than sent to
     *   a provider that rejects the pairing. A reducer bug, and one
     *   `findSafeTrimIndex` exists to prevent.
     */
    cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair';
    /** Unchanged, and stated so a reader need not infer it. */
    messages: number;
    /** Present only for `reducer_threw`. */
    error?: string;
} | {
    type: 'tool_executing';
    sessionId: SessionId;
    turnId: TurnId;
    toolUseId: ToolUseId;
    toolName: string;
    input: unknown;
    /**
     * Present when another TOOL dispatched this call, rather than the
     * model.
     *
     * `run_code` is the reason: a program it runs calls tools in a
     * loop, and those calls went through `registry.execute` directly —
     * so they reached the permission gate and reached the event stream
     * not at all. A turn whose transcript showed one `run_code` call and
     * nothing about the eleven writes it performed is a transcript
     * that cannot be audited.
     *
     * Named rather than merely present, and this is the load-bearing
     * part: without it a consumer counting tool calls double-counts —
     * the parent AND each child — and a consumer rendering a timeline
     * draws eleven siblings where there is one call with eleven
     * children.
     */
    via?: {
        readonly tool: string;
        readonly toolUseId: ToolUseId;
        /** The code runtime's request id, when that was the dispatch source. */
        readonly runtimeToolCallId?: string;
    };
}
/**
 * A tool saying how far along it is.
 *
 * Ephemeral — never appended to the session log, like `text_delta`. It is
 * for a host rendering a live view, not part of the conversation, and a
 * chatty tool must not be able to bloat the durable record.
 *
 * Tools get a deadline of up to two minutes by default, so before this
 * a build, a test run or a long fetch was simply silent for its whole
 * duration: the host could show that a tool had started and then nothing
 * at all until it either finished or timed out. The model never sees
 * these; they answer "is it still working?", which is a question only a
 * human asks. It is latest state rather than a lossless log: the executor
 * bounds each UTF-8 message and coalesces intermediate updates when the
 * live consumer falls behind. Complete output belongs to the terminal
 * `tool_completed` result.
 */
 | {
    type: 'tool_progress';
    sessionId: SessionId;
    turnId: TurnId;
    toolUseId: ToolUseId;
    toolName: string;
    /** Human-readable, e.g. "compiled 40/120 files". */
    message: string;
    /** Optional completion in [0,1] when the tool genuinely knows it. */
    fraction?: number;
}
/** Provider-executed activity, retained as evidence rather than a local tool request. */
 | {
    type: 'hosted_tool';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    tool: NonNullable<import('../provider/index.js').StreamChunk['delta']['hostedTool']>;
}
/**
 * A model call failed transiently and is being retried after a backoff.
 *
 * Answers the same question `tool_progress` answers — "is it still
 * working?" — for the other half of a turn's wall clock. With the default
 * policy, or a server-directed delay up to the cap, a turn can sit silent
 * for the better part of a minute between `iteration_started` and the
 * next event. A host saw literally nothing and no keepalive, so a
 * backoff was indistinguishable from a hang and a watchdog would cancel
 * a turn that was about to succeed.
 *
 * Emitted before the sleep, so the delay it names is the one still
 * ahead.
 */
 | {
    type: 'provider_retry';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    /** 1-based attempt that just failed. */
    attempt: number;
    maxRetries: number;
    delayMs: number;
    /** Classified failure code, as the boundary classifier reports it. */
    code: string;
    status?: number;
    /** The delay came from the server's own `Retry-After`. */
    serverDirected: boolean;
}
/**
 * A member of the provider chain could not serve, and a later member has
 * taken over. The turn continues from where it stopped.
 *
 * This event is the feature's honesty. A chain that swapped silently would
 * produce a turn that succeeded while quietly not doing what the operator
 * asked — served by a provider they did not choose, at a price and a
 * quality they did not agree to, with nothing in the transcript saying so.
 * A host is expected to SHOW this, not log it.
 *
 * Emitted at the moment of the swap, before the replacement request runs.
 */
 | {
    type: 'provider_fallback';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    /** 0-based position in the chain, as the host declared it. */
    fromIndex: number;
    fromProviderId: string;
    fromModel?: string;
    toIndex: number;
    toProviderId: string;
    toModel?: string;
    /** Classified failure code, as the boundary classifier reports it. */
    code: string;
    status?: number;
    /** The classified failure's own sentence. */
    reason: string;
} | {
    type: 'tool_completed';
    /** Bounded result view; omitted when output was overridden or truncated. */
    presentation?: ToolResultView;
    sessionId: SessionId;
    turnId: TurnId;
    toolUseId: ToolUseId;
    toolName: string;
    result: string;
    isError: boolean;
    /** See {@link tool_executing}'s `via`. Carried on both, so a
     * consumer can pair them without holding the start event. */
    via?: {
        readonly tool: string;
        readonly toolUseId: ToolUseId;
        readonly runtimeToolCallId?: string;
    };
    /**
     * Wall-clock the tool took. Computed since the first version of
     * the executor but only ever logged; a host asking "which tool
     * was slow" had to reconstruct it from event timestamps.
     */
    durationMs?: number;
    /**
     * Size of the tool's output BEFORE the model-visible budget was
     * applied, so a host can report "returned 2.1 MB" even though
     * `result` is a preview.
     */
    outputLength?: number;
    /** True when `result` is a preview rather than the whole output. */
    outputTruncated?: boolean;
    /** Where the full output was written, when it was spilled. */
    outputSpillPath?: string;
    /** SHA-256 of the chunk manifest captured with the retained text. */
    outputSpillIntegrity?: string;
}
/**
 * A tool asked the user a question and the turn is parked on it.
 *
 * The question used to park through the raw handler under a synthetic
 * checkpoint id that was never written, so a remote host could not
 * observe it at all — the in-process callback was the only channel, and
 * a tool review with the same shape had an event, a bridge mapping and
 * a durable record. This is that surface, for the other kind of park.
 */
 | {
    type: 'user_question_asked';
    sessionId: SessionId;
    turnId: TurnId;
    checkpointId: CheckpointId;
    /** The asking `tool_use_id`, so an answer can be matched back. */
    questionId: string;
    question: string;
}
/**
 * The question was resolved.
 *
 * `answered: false` covers a decline and a non-response. Distinguished
 * because the asking tool refuses to invent consent from either, and a
 * host rendering the card needs the same distinction.
 */
 | {
    type: 'user_question_answered';
    sessionId: SessionId;
    turnId: TurnId;
    checkpointId: CheckpointId;
    /**
     * Which question, when the resolution named one.
     *
     * Its sibling `user_question_asked` carries this and the answer
     * did not, so a client that keyed on the question id — the
     * natural key, since it is what routes an answer back on resume
     * — could not match the two halves without also having stored
     * the checkpoint id. Absent when the pause was resolved without
     * an answer.
     */
    questionId?: string;
    answered: boolean;
} | {
    type: 'tool_review_requested';
    sessionId: SessionId;
    turnId: TurnId;
    toolCalls: ToolCallSummary[];
    iteration: number;
} | {
    type: 'tool_review_completed';
    sessionId: SessionId;
    turnId: TurnId;
    decision: 'approved' | 'modified' | 'rejected';
} | {
    type: 'checkpoint_created';
    sessionId: SessionId;
    turnId: TurnId;
    checkpointId: CheckpointId;
    iteration: number;
}
/**
 * The turn parked at a checkpoint. This ends a segment of the turn and is
 * NOT terminal: the turn stays the session's active turn until
 * `resumeSession` continues it (same `turnId`) or `abandonTurn` closes it.
 */
 | {
    type: 'turn_paused';
    budget?: SessionTokenBudgetSummary;
    sessionId: SessionId;
    turnId: TurnId;
    checkpointId: CheckpointId;
    reason: string;
    /**
     * The same structured failure projection a terminal `turn_failed`
     * carries. A pause is a different verdict, not a less informative one:
     * the retryability and any provider-directed delay are what let a host
     * decide when and how to resume this checkpoint.
     */
    failure?: PlatformError;
    /** First-hand driver classification, when the provider produced one. */
    providerError?: import('../provider/error.js').ProviderErrorInfo;
    /** Curated operator copy, absent when no catalog rule matched. */
    explanation?: {
        id: string;
        message: string;
        hint: string;
    };
}
/** A paused turn continues from its checkpoint, under the same `turnId`. */
 | {
    type: 'turn_resuming';
    sessionId: SessionId;
    turnId: TurnId;
    fromCheckpointId: CheckpointId;
    /** The decision whose answer released the park, when one did. */
    resolvedDecisionId?: string;
}
/**
 * A guardrail blocked or rewrote the turn's input or answer.
 *
 * Emitted so a host can show WHY a turn refused, and — for a rewrite —
 * so a consumer that already rendered `text_delta` events knows the
 * text it displayed has been corrected.
 */
 | {
    type: 'guardrail_triggered';
    sessionId: SessionId;
    turnId: TurnId;
    stage: 'input' | 'output';
    action: 'block' | 'rewrite';
    guardrail?: string;
    reason?: string;
}
/**
 * A background job this session (or the owner it runs under) started has
 * ended. The model learns it from a notice on its next tool result;
 * the host learns it from this, whether or not a turn is running.
 */
 | {
    type: 'background_job_exited';
    sessionId: SessionId;
    turnId?: TurnId;
    jobId: string;
    command: string;
    status: 'exited' | 'killed';
    exitCode?: number;
    signal?: string;
}
/**
 * What the turn learned was written to the host's memory store: its
 * decisions, discoveries and failures as one entry a later session can
 * search for. Emitted only when a host asked (`consolidateInto`) and
 * the turn had something to say.
 */
 | {
    type: 'memory_consolidated';
    sessionId: SessionId;
    turnId?: TurnId;
    memoryId: string;
    title: string;
    decisions: number;
    discoveries: number;
    failures: number;
}
/**
 * The turn reached its end without throwing.
 *
 * `completed` is not `succeeded`. A turn stopped by its token budget, its
 * timeout, its iteration cap, a cancellation or a blocking output guardrail
 * all arrive here — `turn_failed` is emitted only from the throw path — so a
 * consumer that treated this event as success reported one for a turn whose
 * answer was refused. `stopReason` and `settlement.status` separate them.
 *
 * `result` is the authoritative answer, after guardrail, review,
 * outstanding-work and structured-output overrides. When it differs from the
 * text of the turn's last assistant message, a `message_replaced` record is
 * appended first, so every fold of the log shows this answer and never the
 * raw one (`settlement.resultSource` says which override applied).
 */
 | {
    type: 'turn_completed';
    budget?: SessionTokenBudgetSummary;
    sessionId: SessionId;
    turnId: TurnId;
    result: string;
    stopReason?: StopReason;
    /**
     * Present only on a cancellation whose origin was recorded. Absent
     * is a real answer: a cancellation nobody attributed is not a user
     * cancellation, and defaulting to one would put a confident wrong
     * value where an honest gap belongs.
     */
    cancelCause?: CancelCause;
    settlement: TurnSettlement;
}
/**
 * The turn failed. Terminal, like `turn_completed`.
 *
 * `failure.code` names machine-readable causes the session log itself
 * produces: `interrupted` (closed by `beginTurn({ abandonInterrupted })`
 * after a crash) and `abandoned` (closed by `abandonTurn`).
 *
 * `error` is the flattened message, kept for every consumer that only
 * ever rendered a string. `failure` is the structured projection, and
 * it is the point: namzu already classifies at the provider boundary —
 * over status, errno, `Retry-After` and the whole cause chain — so a
 * fully-populated error genuinely arrived here and was flattened one
 * line later, discarding `code`, `status`, `retryAfterMs`, `retryable`
 * and `details`.
 *
 * The damage was self-inflicted downstream: one consumer substring-
 * matched the flattened message to decide whether an error had
 * occurred, and the iteration loop re-ran the classifier to recover
 * structure that had already been computed upstream.
 */
 | {
    type: 'turn_failed';
    budget?: SessionTokenBudgetSummary;
    sessionId: SessionId;
    turnId: TurnId;
    error: string;
    failure?: PlatformError;
    /**
     * The driver's own classification, when it produced one. Carried
     * beside `failure` rather than folded into it: this is the
     * provider's first-hand statement, and a consumer deciding whether
     * to retry reads it directly.
     */
    providerError?: import('../provider/error.js').ProviderErrorInfo;
    /**
     * Operator-facing explanation, when a catalog rule claims this
     * failure: a stable `id` to grep for, and `hint` saying what to
     * change. Absent when no rule matched — inventing advice for an
     * uncharacterised failure is worse than saying nothing, because
     * it sends the reader somewhere specific and wrong.
     */
    explanation?: {
        id: string;
        message: string;
        hint: string;
    };
    settlement: TurnSettlement;
} | {
    type: 'capability_warning';
    sessionId: SessionId;
    turnId?: TurnId;
    capability: 'tools' | 'vision' | 'documents';
    /** Present when the mismatch was produced after a tool executed. */
    contentSource?: 'tool-result';
    providerId: string;
    message: string;
}
/**
 * Provider-invalid tool history was repaired before the first model call.
 *
 * Counts, not content: a host can surface and audit the rewrite without
 * copying tool output or conversation secrets into its event channel.
 * `fresh-history` names caller-supplied history. `abandoned-checkpoint`
 * excludes any incomplete turn still owned by a durable pending/recovered
 * resume plan; that turn is completed by its authority path instead.
 */
 | {
    type: 'message_history_repaired';
    sessionId: SessionId;
    turnId: TurnId;
    source: 'fresh-history' | 'abandoned-checkpoint' | 'provider-rejected-image';
    duplicateToolResultsRemoved: number;
    orphanedToolResultsRemoved: number;
    syntheticToolResultsInserted: number;
    /** Exact number of durable image occurrences withheld from later requests. */
    providerRejectedImagesSuppressed?: number;
} | {
    type: 'token_usage_updated';
    /** Aggregate tree spend, distinct from this turn's own usage. */
    budget?: SessionTokenBudgetSummary;
    sessionId: SessionId;
    turnId: TurnId;
    usage: TokenUsage;
    cost: CostInfo;
    /**
     * How large the CONTEXT is right now, and how large it may get.
     *
     * These are a different quantity from `usage` beside them and the
     * distinction is the whole reason they are named this explicitly.
     * `usage` is CUMULATIVE SPEND over the turn: prompt plus completion
     * tokens summed across every turn, monotonically increasing, and
     * untouched by compaction. `contextTokens` is the size of the
     * conversation being sent right now, which falls when a compaction
     * sheds.
     *
     * Dividing the first by a context window is a category error, and
     * it is one this estate shipped: a host did exactly that, so its
     * indicator climbed toward full on any long session no matter how much
     * room the conversation actually had — most wrong precisely when
     * someone needed it most. The numbers are here so nobody has to
     * reach for the wrong one, and named so reaching for it is a
     * visible mistake rather than a plausible guess.
     *
     * `contextMeasuredBy` says whether the provider counted the prompt
     * or we estimated it, and `windowSource` where the ceiling came
     * from. A fraction of two numbers is only as honest as the weaker
     * of them, and a surface rendering these owes a reader the same
     * distinction rather than presenting an estimate as a measurement.
     *
     * Absent when the turn has no compaction configuration, because
     * nothing then resolves a window and inventing one would be the
     * guess this exists to replace.
     *
     * This is a state snapshot, not merely a receipt for a model call.
     * It is also emitted immediately after an automatic context edit:
     * cumulative `usage`/`cost` may be unchanged (or may include a
     * verifier call) while `contextTokens` falls to its post-edit
     * estimate. Hosts therefore need not wait for another provider
     * response to learn that compaction made room.
     */
    contextTokens?: number;
    contextMeasuredBy?: 'provider' | 'estimate';
    contextWindowTokens?: number;
    windowSource?: 'config' | 'provider' | 'model-table' | 'default';
} | {
    type: 'activity_created';
    sessionId: SessionId;
    turnId: TurnId;
    activityId: ActivityId;
    activityType: ActivityType;
    description: string;
} | {
    type: 'activity_updated';
    sessionId: SessionId;
    turnId: TurnId;
    activityId: ActivityId;
    status: ActivityStatus;
    output?: unknown;
    error?: string;
} | {
    type: 'plan_ready';
    sessionId: SessionId;
    turnId: TurnId;
    planId: PlanId;
    title: string;
    steps: PlanStep[];
    summary?: string;
} | {
    type: 'plan_approved';
    sessionId: SessionId;
    turnId: TurnId;
    planId: PlanId;
} | {
    type: 'plan_rejected';
    sessionId: SessionId;
    turnId: TurnId;
    planId: PlanId;
    reason?: string;
} | {
    type: 'plan_step_updated';
    sessionId: SessionId;
    turnId: TurnId;
    planId: PlanId;
    stepId: string;
    status: PlanStep['status'];
}
/**
 * The plan is over, and it went the way it was supposed to.
 *
 * The plan events used to stop before the outcome: `plan_ready`,
 * `plan_approved`, `plan_rejected` and `plan_step_updated` all reached the
 * wire, and the two terminal ones were folded into a bare `break` in the
 * translator. So a host watching the stream saw the steps report and then
 * silence — it could tell a plan had been approved and never that it
 * closed, which leaves a plan rendered as in-flight forever.
 *
 * Found by the first live end-to-end run rather than by a test, and the
 * reason is worth keeping: the tests read the outcome off `PlanManager`
 * through `onContextCreated`, so they proved the plan settled without ever
 * asking whether a consumer of the EVENT STREAM could see it.
 */
 | {
    type: 'plan_completed';
    sessionId: SessionId;
    turnId: TurnId;
    planId: PlanId;
}
/**
 * The plan is over and it did not finish.
 *
 * `reason` is the text handed to `failPlan`, which used to be discarded —
 * an event that says "failed" without saying why puts the reader back
 * where the missing event did.
 */
 | {
    type: 'plan_failed';
    sessionId: SessionId;
    turnId: TurnId;
    planId: PlanId;
    reason?: string;
} | {
    type: 'agent_pending';
    sessionId: SessionId;
    turnId: TurnId;
    taskId: TaskId;
    parentAgentId: string;
    childAgentId: string;
    depth: number;
    /** Approved plan edge carried while the blocking tool is still live. */
    planId?: string;
    planStepId?: string;
    /**
     * How the host that delegated this child wants it GROUPED on screen —
     * a shared label over a set of related delegations, typically one
     * operator-visible piece of work several children are doing together.
     *
     * These fields are display annotations only; they do not create
     * dependencies, barriers, or serial execution. Nothing in the kernel
     * reads them: admission, ordering and concurrency come from the
     * scheduler and from {@link planId}/{@link planStepId}, which is the
     * field pair that DOES carry correlation a host may act on. A reader
     * who infers execution structure from a label here has inferred it
     * from a caption.
     *
     * Absent unless the delegating host supplied them, which is the
     * normal case — a host that groups nothing sends nothing, and a
     * consumer written before these existed reads the same event it
     * always did.
     *
     * They ride this event rather than staying in the delegating
     * process's memory for REACH: a consumer watching from outside
     * that process — another listener, or an SSE client — can rebuild
     * the same picture instead of seeing an undifferentiated list of
     * children.
     *
     * Reach is not durability, and this event buys only the first.
     * Like every delegation lifecycle event, it is handed straight to
     * a host's listener and never enters a session log — which is what
     * the absent `seq` on this variant says, and what the `seq` doc
     * above spells out. A label here is therefore written nowhere by
     * the kernel and does not survive a restart of the host that chose
     * it; a host wanting the grouping to outlive its process records it
     * from the listener.
     */
    workflow?: string;
    /**
     * Display group WITHIN {@link workflow} — a stage of that work, as
     * the delegating host labelled it. Display-only on the same terms as
     * {@link workflow}: it creates no dependencies, barriers or serial
     * execution, and two children naming the same phase are not thereby
     * sequenced or synchronised.
     */
    phase?: string;
    /**
     * Longer text explaining {@link phase}, for a surface that has room
     * to show it. Display-only on the same terms as {@link workflow}.
     */
    phaseDetail?: string;
    /**
     * Where {@link phase} sits in the host's intended DISPLAY order,
     * zero-based. Display-only on the same terms as {@link workflow}: it
     * orders a list on a screen and orders nothing that runs. Children in
     * one phase are expected to carry the same value; a consumer that
     * sees two disagree should keep the first rather than resequence,
     * because nothing here is authoritative enough to arbitrate.
     */
    phaseOrder?: number;
} | {
    type: 'agent_completed';
    sessionId: SessionId;
    turnId: TurnId;
    taskId: TaskId;
    result: BaseAgentResult;
} | {
    type: 'agent_failed';
    sessionId: SessionId;
    turnId: TurnId;
    taskId: TaskId;
    error: string;
} | {
    type: 'agent_canceled';
    sessionId: SessionId;
    turnId: TurnId;
    taskId: TaskId;
    /** Same value the child's own `turn_completed` carries, so the two
     *  sides of one cancellation agree rather than being correlated
     *  by timing. */
    cancelCause?: CancelCause;
} | {
    type: 'task_created';
    sessionId: SessionId;
    turnId?: TurnId;
    taskId: TaskId;
    subject: string;
    status: TaskStatus;
    /**
     * What this unit waits on, and who claims it.
     *
     * The store maintains a full dependency graph — `blocks` and
     * `blockedBy` are mirrored on both ends, written under a lock, and
     * deadlock-avoided — and none of it reached the wire. So a host
     * could show a flat list of units and nothing about their order,
     * while the model was already maintaining the order.
     *
     * Absent rather than empty when the unit depends on nothing, so a
     * reader can tell "no dependencies" from an emitter that predates
     * these fields.
     */
    blockedBy?: readonly TaskId[];
    owner?: string;
} | {
    type: 'task_updated';
    sessionId: SessionId;
    turnId?: TurnId;
    taskId: TaskId;
    subject: string;
    status: TaskStatus;
    owner?: string;
    /** See `task_created`. Carried on updates because an edge can be added later. */
    blockedBy?: readonly TaskId[];
} | {
    type: 'plugin_hook_executing';
    sessionId: SessionId;
    turnId?: TurnId;
    pluginId: PluginId;
    hookEvent: PluginHookEvent;
} | {
    type: 'plugin_hook_completed';
    sessionId: SessionId;
    turnId?: TurnId;
    pluginId: PluginId;
    hookEvent: PluginHookEvent;
    result: PluginHookResult;
} | {
    type: 'sandbox_created';
    sessionId: SessionId;
    turnId?: TurnId;
    sandboxId: SandboxId;
    environment: string;
} | {
    type: 'sandbox_exec';
    sessionId: SessionId;
    turnId?: TurnId;
    sandboxId: SandboxId;
    command: string;
    exitCode: number;
    durationMs: number;
} | {
    type: 'sandbox_destroyed';
    sessionId: SessionId;
    turnId?: TurnId;
    sandboxId: SandboxId;
} | {
    type: 'message_started';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
}
/**
 * The model began emitting a reasoning block.
 *
 * Without these, extended thinking looked to a streaming UI like a
 * multi-second stall with no events at all — the turn was working, and
 * the host had no way to say so.
 */
 | {
    type: 'reasoning_started';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
    blockIndex: number;
    reasoningType: 'thinking' | 'redacted_thinking';
}
/** Ephemeral — never appended to the session log, like `text_delta`. */
 | {
    type: 'reasoning_delta';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
    blockIndex: number;
    text: string;
} | {
    type: 'reasoning_completed';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
    blockIndex: number;
    /** Present only when the provider returned readable thinking. */
    text?: string;
    /** True when the block carried a signature that must be replayed. */
    signed: boolean;
} | {
    type: 'text_delta';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
    text: string;
    textPart?: Omit<import('../message/index.js').AssistantTextPart, 'text'>;
} | {
    type: 'message_completed';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
    stopReason: MessageStopReason;
    usage?: TokenUsage;
    /**
     * Settled assistant text. When the provider supplies public text
     * phases, this selects explicit final-answer items; concatenating
     * raw deltas would also include intermediate commentary. All items
     * remain available in textParts. Without phases, ordinary delta
     * concatenation is unchanged. Stop reason still determines whether
     * this message finished, was cancelled or hit an output limit.
     */
    content?: string;
    /** Ordered original items; content selects explicit final answers if supplied. */
    textParts?: readonly import('../message/index.js').AssistantTextPart[];
} | {
    type: 'tool_input_started';
    sessionId: SessionId;
    turnId: TurnId;
    iteration: number;
    messageId: MessageId;
    toolUseId: ToolUseId;
    toolName: string;
} | {
    type: 'tool_input_delta';
    sessionId: SessionId;
    turnId: TurnId;
    toolUseId: ToolUseId;
    partialJson: string;
} | {
    type: 'tool_input_completed';
    sessionId: SessionId;
    turnId: TurnId;
    toolUseId: ToolUseId;
    input: unknown;
    /**
     * True when the provider stream ended before the tool JSON
     * arguments closed. `input` stays a sanitized object so public
     * consumers never receive internal recovery sentinels.
     */
    inputTruncated?: boolean;
};
/**
 * A child session was created to do delegated work. Appended to the PARENT
 * session's log, inside the parent turn whose tool call spawned it.
 */
export interface ChildSessionSpawnedEvent {
    type: 'child_session_spawned';
    sessionId: SessionId;
    turnId: TurnId;
    childSessionId: SessionId;
    /** The parent's tool call that spawned the child. */
    toolCallId: ToolUseId;
    kind: SubSessionKind;
    description: string;
    /** The child's log, relative to the parent's session directory: `subagents/<child-id>.jsonl`. */
    path: string;
    /**
     * Display grouping a host asked for, for example one operator-visible piece
     * of work several children do together. Batches are derived from these
     * annotations; nothing executes differently because of them.
     */
    batch?: {
        batchId: string;
        name: string;
        phase?: string;
    };
    /** The token-budget account the child's turns spend from. */
    budgetAccountId?: string;
}
/**
 * The child session appended a message.
 *
 * A child can outlive the parent turn that spawned it (`Turn.abandonedTaskIds`
 * names such workers), so `turnId` is the spawning turn only while that turn
 * is still open, and absent once it has closed. It never names a later turn:
 * the child belongs to the turn in its `child_session_spawned` record.
 */
export interface ChildSessionMessagedEvent {
    type: 'child_session_messaged';
    sessionId: SessionId;
    /** The spawning turn while it is open; absent after it closed. */
    turnId?: TurnId;
    childSessionId: SessionId;
    messageId: MessageId;
}
/**
 * The child session went idle: its current turn ended and nothing is queued.
 * `turnId` follows the rule on {@link ChildSessionMessagedEvent}.
 */
export interface ChildSessionIdledEvent {
    type: 'child_session_idled';
    sessionId: SessionId;
    /** The spawning turn while it is open; absent after it closed. */
    turnId?: TurnId;
    childSessionId: SessionId;
}
export type ChildSessionLifecycleEvent = ChildSessionSpawnedEvent | ChildSessionMessagedEvent | ChildSessionIdledEvent;
/**
 * Discriminated union of every live session event: 62 type literals.
 *
 * `type` is the sole discriminator for exhaustive switches; envelope fields
 * are additive and never take part in discrimination.
 */
export type SessionEvent = (CoreSessionEvent & SessionEventEnvelope) | (ChildSessionLifecycleEvent & SessionEventEnvelope);
export type { CoreSessionEvent };
export type SessionEventType = SessionEvent['type'];
export type SessionEventListener = (event: SessionEvent) => void | Promise<void>;
/**
 * Event types whose volume makes durable persistence wasteful. They reach the
 * live stream and never the session log: the completed message, reasoning
 * block and tool input carry the same content once.
 */
export declare const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType>;
export declare function isEphemeralEvent(event: {
    readonly type: string;
}): boolean;
/** The event types a session log records: every literal except the ephemeral four. */
export type PersistedSessionEventType = Exclude<SessionEventType, 'text_delta' | 'tool_input_delta' | 'reasoning_delta' | 'tool_progress'>;
//# sourceMappingURL=events.d.ts.map