@excitedjs/dreamux-types 0.9.0-beta.179 → 0.9.0-beta.183

package/dist/agent-runtime.d.ts

@@ -1,28 +1,35 @@
 /**
  * Agent Runtime provider-authoring contracts (declaration-only).
  *
- * The complete, neutral Agent Runtime provider contract an external runtime
- * package (or a future built-in runtime package such as
- * `@excitedjs/agent-runtime-codex`) implements while importing only
- * `@excitedjs/dreamux-types`. The public create context, runtime handle, state
- * callbacks, and status are deliberately neutral: they never expose Dreamux
- * host-private types (`DispatcherRow`, `DispatcherStore`, `DispatcherConfig`,
- * config/state stores, or host path-helper implementations).
- * Dreamux core adapts its private objects into these public shapes.
+ * The complete, neutral Agent Runtime provider contract a runtime package
+ * implements while importing only `@excitedjs/dreamux-types`. The seam is
+ * deliberately minimal: a provider facade for selection, creation, and neutral
+ * recent Activity reads; a live handle with only `start`, `submit`, and `stop`;
+ * and a Core-owned leased state sink runtime facts are pushed into. It never
+ * exposes Dreamux host-private types (`DispatcherRow`, `DispatcherStore`,
+ * `DispatcherConfig`, config/state stores, or host path-helper
+ * implementations); Dreamux core adapts its private objects into these shapes.
  *
- * Note on sequencing: Dreamux core's own launcher still threads a host-coupled
- * create context internally; converging that launcher onto this neutral context
- * is the runtime-split slice's job (issue #209 slice 3). This package already
- * publishes the stable public target so external and built-in runtime packages
- * can be authored against it today.
+ * Recovery, session-bound structured output, and recent Activity Records are
+ * mandatory provider behavior rather than negotiated capability bits. Live
+ * activity emission stays optional because its absence changes only
+ * presentation.
  */
 import type { DreamuxLogger } from './logger.js';
-import type { AgentRuntimeProviderDescriptor, DreamuxEnvironment, ProviderBinCheck, ProviderDiagnosticRunner, ProviderDiagnosticScope, ProviderDiagnosticResult, ProviderFactory, ProviderOnboard } from './provider.js';
-import type { InboundTurnInput } from './turn.js';
+import type { JsonSchema, JsonValue } from './json.js';
+import type { DreamuxEnvironment, ProviderBinCheck, ProviderDiagnosticRunner, ProviderDiagnosticScope, ProviderDiagnosticResult, ProviderFactory, ProviderOnboard } from './provider.js';
+/** Runtime-specific alias of the shared public logger contract. */
+export type AgentRuntimeLogger = DreamuxLogger;
+/**
+ * One MCP server Core injects into a runtime. Core owns the whole list: a
+ * provider launches exactly these entries and never discovers, appends to, or
+ * mutates them.
+ */
 export interface AgentRuntimeMcpServer {
-    name: string;
-    command: string;
-    args: string[];
+    readonly name: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
 }
 /**
  * A skill root core hands to a runtime. Core composes required bundled roots
@@ -38,122 +45,37 @@ export interface AgentRuntimeSkillSource {
     path: string;
     source: 'dreamux-core' | string;
 }
-export interface AgentRuntimeResumeCheckpoint {
-    /** Runtime-owned checkpoint id persisted by Dreamux and interpreted by the runtime. */
-    id: string;
-    /**
-     * Provider-produced canonical native transcript locator. Dreamux persists
-     * this value atomically with {@link id} and never interprets it.
-     */
-    transcript_locator?: string | null;
-}
-export interface AgentRuntimeResumeCapability {
-    supported: boolean;
-}
-export interface AgentRuntimeStructuredOutputCapability {
-    supported: boolean;
-    /**
-     * How the schema is applied:
-     * - `'create-context'`: set once at spawn time (e.g. claude-code `--json-schema`).
-     * - `'per-turn'`: set on each turn (e.g. codex `turn/start.outputSchema`).
-     * When `supported` is false, `scope` is omitted.
-     */
-    scope?: 'create-context' | 'per-turn';
-}
-export interface AgentRuntimeCapabilities {
-    /** Whether this runtime can resume a prior checkpoint id from its create context. */
-    resume: AgentRuntimeResumeCapability;
-    /**
-     * Whether this runtime supports structured output (JSON Schema on the final
-     * assistant message). Optional: a provider that omits it is treated as
-     * unsupported so core can fail-loud before submitting a schema-constrained
-     * turn, instead of relying on the runtime to return a specific error.
-     */
-    structuredOutput?: AgentRuntimeStructuredOutputCapability;
-}
-export interface AgentRuntimeSystemPrompt {
-    /** Full role instructions for runtimes that replace their base prompt. */
-    replace?: string;
-    /**
-     * Ordered role deltas for runtimes that append to an existing native prompt.
-     * Runtime adapters preserve order and choose their native isolation mechanic.
-     */
-    append?: readonly string[];
-}
-export interface AgentRuntimeTextInput {
-    text: string;
-    /** Correlation/dedupe metadata; not part of the model-visible text. */
-    sourceId?: string;
-    /**
-     * Optional JSON Schema constraining the model's final assistant message for
-     * this turn. Provider-neutral: each runtime maps it to its native structured
-     * output mechanism (e.g. codex `turn/start.outputSchema`, claude-code
-     * `--json-schema`). Runtimes that do not support structured output MUST
-     * return `{ status: 'failed', error }` where `error` is an
-     * {@link UnsupportedAgentRuntimeFeatureError} with `feature: 'outputSchema'`
-     * when this is set — never silently ignore it, so callers never get
-     * unconstrained text when they asked for a schema. When set, the settled
-     * result text is expected to be valid JSON conforming to the schema; the
-     * caller parses it.
-     */
-    outputSchema?: Record<string, unknown>;
-}
 /**
- * Structural shape of an `Error` a runtime returns (as a `failed` turn
- * `error`) when the caller requested a neutral feature the runtime does not
- * support. Callers branch on `error.name === 'UnsupportedAgentRuntimeFeatureError'`
- * and `error.feature` rather than `instanceof`, keeping `@excitedjs/dreamux-types`
- * declaration-only (no runtime values). The `feature` field names the requested
- * capability (e.g. `'outputSchema'`).
+ * Provider-static selection metadata. Zero-argument and config-free: Core has
+ * no config-resolved consumer, so parsed config would widen the seam without a
+ * use case.
+ *
+ * `publicConfig` is optional, bounded, explicitly projected metadata. Raw
+ * provider config, environment variables, paths, credentials, and secrets are
+ * forbidden in it.
  */
-export interface UnsupportedAgentRuntimeFeatureError extends Error {
-    name: 'UnsupportedAgentRuntimeFeatureError';
-    feature: string;
-}
-export interface AgentRuntimeContextSnapshot {
-    usedTokens: number | null;
-    windowTokens: number | null;
-}
-export interface AgentRuntimeTranscriptQuery {
-    turns: number;
-    cursor?: string;
-    includeTools?: boolean;
-}
-export type AgentRuntimeTranscriptBlock = {
-    kind: 'message';
-    role: 'user' | 'assistant';
-    text: string;
-    truncated: boolean;
-} | {
-    kind: 'tool';
-    name: string;
-    input: string | null;
-    output: string | null;
-    status: 'ok' | 'error';
-    inputTruncated: boolean;
-    outputTruncated: boolean;
-};
-export interface AgentRuntimeTranscriptTurn {
-    startedAt: number | null;
-    endedAt: number | null;
-    blocks: readonly AgentRuntimeTranscriptBlock[];
+export interface AgentRuntimeProviderCapabilities {
+    readonly tags: readonly string[];
+    readonly publicConfig?: Readonly<Record<string, JsonValue>>;
 }
-export interface AgentRuntimeTranscriptPage {
-    turns: readonly AgentRuntimeTranscriptTurn[];
-    nextCursor: string | null;
-    truncated: boolean;
-}
-export interface AgentRuntimeTranscriptContext<TConfig = unknown> {
-    checkpoint: AgentRuntimeResumeCheckpoint | null;
-    config: TConfig;
-    cwd: string;
-    injectEnv?: Readonly<Record<string, string>>;
-    outputBudgetBytes: 262144;
-    logger?: DreamuxLogger;
+/**
+ * The shared base of every provider-owned session identity: `id` is the only
+ * field Dreamux core validates and the only one it may read.
+ */
+export interface AgentRuntimeSessionRef {
+    readonly id: string;
 }
-export interface AgentRuntimeTranscriptError extends Error {
-    name: 'AgentRuntimeTranscriptError';
-    reason: 'checkpoint_missing' | 'not_found' | 'unreadable' | 'invalid' | 'locator_outside_root' | 'session_mismatch' | 'cursor_invalid' | 'cursor_query_mismatch' | 'cursor_stale' | 'scan_unsupported';
+/**
+ * The neutral, Core-supplied identity of one runtime instance.
+ *
+ * `session` is the provider's own prior session object, or `null` for a fresh
+ * start. Core persists the complete JSON object atomically and returns it only
+ * to the same provider; it never interprets, indexes, or branches on the
+ * provider-specific fields an extended `TSession` adds.
+ */
+export interface AgentRuntimeIdentity<TSession extends AgentRuntimeSessionRef> {
+    readonly runtimeId: string;
+    readonly session: TSession | null;
 }
 export interface AgentRuntimePathContext {
     /**
@@ -179,58 +101,64 @@ export interface AgentRuntimePathContext {
      */
     runtimeSocketDirs(): readonly string[];
 }
-export interface AgentRuntimeProviderConfigReadContext {
-    providerRef: string;
-    /**
-     * The `agents[].id` whose config block is being parsed — a config-internal
-     * alias, not a dispatcher identity.
-     */
-    agentId: string;
-    file: string;
-    prefix: string;
-}
-/** Runtime-specific alias of the shared provider binary check. */
-export type AgentRuntimeBinCheck = ProviderBinCheck;
-/** Runtime-specific alias of the shared provider diagnostic result. */
-export type AgentRuntimeDiagnosticResult = ProviderDiagnosticResult;
-/** Runtime-specific alias of the shared provider diagnostic runner. */
-export type AgentRuntimeDiagnosticRunner = ProviderDiagnosticRunner;
 /**
  * Neutral runtime status. Mirrors the host's dispatcher lifecycle states without
  * importing the host enum, so a provider can report status without depending on
  * `@excitedjs/dreamux`.
  */
 export type AgentRuntimeStatus = 'declared' | 'starting' | 'ready' | 'degraded' | 'stopping' | 'stopped';
+/** One authoritative runtime fact pushed into the Core-owned state sink. */
+export type AgentRuntimeStateUpdate<TSession extends AgentRuntimeSessionRef> = {
+    readonly kind: 'status';
+    readonly status: AgentRuntimeStatus;
+    readonly lastError?: string;
+} | {
+    readonly kind: 'session';
+    readonly session: TSession;
+} | {
+    readonly kind: 'session_lost';
+    readonly reason: string;
+};
 /**
- * Neutral state sink the runtime writes status/thread transitions to. Dreamux
- * core adapts its own dispatcher store to this shape; the runtime never sees the
- * host store type.
+ * Push-only state sink, leased to exactly one runtime generation.
+ *
+ * Core creates a distinct sink per generation; the generation is not a public
+ * field and the provider supplies no sequence number. Core serializes updates
+ * in call-receipt order and resolves `publish` only after the authoritative
+ * state write is durable. There is no pull counterpart: awaiting the provider's
+ * own initial `publish` calls is the start fence.
+ *
+ * After Core revokes the lease (runtime replaced or stopped), `publish` rejects
+ * with an {@link AgentRuntimeStateLeaseRevokedError} so the provider terminates
+ * the stale writer. A persistence failure is a separate, fatal error.
  */
-export interface AgentRuntimeStateCallbacks {
-    setStatus(status: AgentRuntimeStatus, extras?: {
-        last_error?: string | null;
-        last_started_at?: number;
-        last_ready_at?: number;
-    }): Promise<void>;
-    setCheckpoint(checkpoint: AgentRuntimeResumeCheckpoint): Promise<void>;
-    recordLostCheckpoint?(lost: AgentRuntimeResumeCheckpoint, replacement: AgentRuntimeResumeCheckpoint, error: string): Promise<void>;
+export interface AgentRuntimeStateSink<TSession extends AgentRuntimeSessionRef> {
+    publish(update: AgentRuntimeStateUpdate<TSession>): Promise<void>;
 }
-export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
-    readonly [key: string]: JsonValue;
-};
+/**
+ * Structural shape of the `Error` {@link AgentRuntimeStateSink.publish} rejects
+ * with once Core has revoked that runtime generation's lease. Callers branch on
+ * `error.name` rather than `instanceof`, keeping this package declaration-only.
+ */
+export interface AgentRuntimeStateLeaseRevokedError extends Error {
+    name: 'AgentRuntimeStateLeaseRevokedError';
+}
+/**
+ * What a tool invocation does, classified by the runtime that owns the tool
+ * vocabulary. `null` means the runtime has no such classification for this call.
+ */
+export type RuntimeToolAction = 'read' | 'list_files' | 'search' | 'edit' | 'run';
 /** One accepted provider submission. Its identity never implies folding. */
 export interface RuntimeSubmission {
     readonly settled: Promise<RuntimeSubmissionSettlement>;
 }
-/** A provider-observed native result and the opaque completion identity. */
+/** A provider-observed native result. */
 export type RuntimeCompletion = {
     readonly status: 'completed';
-    readonly displaySubmission: RuntimeSubmission;
     readonly resultText: string | null;
     readonly truncated: boolean;
 } | {
     readonly status: 'failed';
-    readonly displaySubmission: RuntimeSubmission;
     readonly error: Error;
 };
 export type RuntimeSubmissionSettlement = {
@@ -242,11 +170,6 @@ export type RuntimeSubmissionSettlement = {
 } | {
     readonly kind: 'stopped';
 };
-/**
- * What a tool invocation does, classified by the runtime that owns the tool
- * vocabulary. `null` means the runtime has no such classification for this call.
- */
-export type RuntimeToolAction = 'read' | 'list_files' | 'search' | 'edit' | 'run';
 export type RuntimeActivity = {
     readonly kind: 'assistant.message';
     readonly id: string;
@@ -268,10 +191,31 @@ export interface RuntimeActivityEvent {
     readonly activity: RuntimeActivity;
     readonly occurredAt: number;
 }
-/** Synchronous, non-backpressuring sink invoked for native activity facts. */
-export interface RuntimeActivitySink {
+/**
+ * Optional, synchronous, non-backpressuring sink for live native activity. It
+ * is transient input to the Core conversation projection, not a progress view:
+ * Core drops writes from a revoked generation, and its absence changes only
+ * presentation. The stable progress view is
+ * {@link AgentRuntimeProvider.readRecentActivity}, which never replays this
+ * sink and is never replayed by it.
+ */
+export interface AgentRuntimeActivitySink {
     (event: RuntimeActivityEvent): void;
 }
+/**
+ * The single input shape a live runtime accepts.
+ *
+ * Deliberately nothing but text: it is already the complete model-facing
+ * message, so the seam carries no discriminator, no source enum, no source
+ * identity, and no rendering instruction. Every caller prepares its final text
+ * before submitting, so a runtime never renders an envelope and never branches
+ * on where a turn came from. Stable source identity, origin, intent, and
+ * display correlation stay on Core's own turn/admission state, and Core — not a
+ * Provider — deduplicates with them.
+ */
+export interface AgentRuntimeSubmissionInput {
+    readonly text: string;
+}
 /**
  * Admission is separate from the eventual outcome of an accepted turn.
  *
@@ -281,12 +225,17 @@ export interface RuntimeActivitySink {
  * boundary. Callers MUST NOT retry an ambiguous admission automatically.
  * A rejected/thrown input promise is likewise admission-ambiguous unless the
  * provider documents and returns the explicit `failed` result instead.
+ *
+ * `skipped` remains a provider-seam state; the Command boundary — not this
+ * seam — normalizes it to the public `stopped`.
+ *
+ * There is no `duplicate` admission: a Provider has no source identity to
+ * deduplicate with. Core's own admission ledger returns the public `duplicate`
+ * before it ever calls {@link AgentRuntime.submit}.
  */
 export type RuntimeAdmission = {
     status: 'submitted';
     submission: RuntimeSubmission;
-} | {
-    status: 'duplicate';
 } | {
     status: 'stopped';
 } | {
@@ -299,125 +248,176 @@ export type RuntimeAdmission = {
     error: Error;
 };
 /**
- * The neutral, launcher-supplied identity of the runtime instance. Replaces the
- * host's `DispatcherRow` in the public create context: a provider reads only the
- * fields it needs (its own id, an optional resumable checkpoint id) and never
- * the host row.
+ * Neutral system-prompt input. When both forms are present they are alternate
+ * representations of the same instructions, and a Provider applies at most one
+ * of them — whichever its runtime supports. `append` fragment order is
+ * significant. Dreamux re-supplies the reconstructed bundle on every
+ * runtime-context creation; a Provider must never become the authority for
+ * prompt state.
  */
-export interface AgentRuntimeIdentity {
-    /** The runtime instance id (the dispatcher/teammate id the launcher assigns). */
-    runtime_id: string;
-    /**
-     * A prior resumable checkpoint the launcher recovered, or null for a fresh
-     * start. The runtime interprets both the id and transcript locator.
-     */
-    checkpoint: AgentRuntimeResumeCheckpoint | null;
+export interface AgentRuntimeSystemPrompt {
+    readonly replace?: string;
+    readonly append?: readonly string[];
 }
 /**
- * The neutral create context a provider's `createRuntime` receives. Carries the
- * runtime identity, parsed provider config, cwd, optional system-prompt
- * content, MCP servers, bundled skill sources, and neutral logger/path/state
- * sinks. It never exposes host dispatcher rows, stores, or config models.
+ * The neutral facts required to launch one Dreamux role. Immutable: prior
+ * session identity reaches `start` only through this object.
  */
-export interface AgentRuntimeCreateContext<TConfig = unknown> {
-    identity: AgentRuntimeIdentity;
-    /** Provider-parsed config (the output of the provider's own `readConfig`). */
-    config: TConfig;
+export interface AgentRuntimeCreateContext<TConfig, TSession extends AgentRuntimeSessionRef> {
+    readonly identity: AgentRuntimeIdentity<TSession>;
+    /** Provider-parsed config (the output of the provider's own config capability). */
+    readonly config: TConfig;
     /**
      * The directory the runtime runs in. Always supplied by the launcher; never
      * derived inside the runtime.
      */
-    cwd: string;
-    /**
-     * Launcher-supplied role/system-prompt content. Core supplies both canonical
-     * forms; runtime adapters decide which native prompt mechanic to use.
-     */
-    systemPrompt?: AgentRuntimeSystemPrompt;
+    readonly cwd: string;
+    /** Core-supplied role instructions; see {@link AgentRuntimeSystemPrompt}. */
+    readonly systemPrompt?: AgentRuntimeSystemPrompt;
     /**
-     * MCP servers the launcher injects for this runtime instance. Already fully
-     * resolved by core: an empty array means "no MCP servers", and the provider
-     * must launch exactly these — it must not infer, append, or mutate the list.
+     * MCP servers Core injects for this runtime instance. Already fully resolved:
+     * an empty array means "no MCP servers", and the provider must launch exactly
+     * these — it must not infer, append, or mutate the list.
      */
-    mcpServers: readonly AgentRuntimeMcpServer[];
+    readonly mcpServers: readonly AgentRuntimeMcpServer[];
     /**
-     * Effective skill sources core selected for this runtime. This can include
-     * required bundled role roots and authorized custom roots.
+     * Effective skill sources core selected for this runtime, including required
+     * bundled role roots and authorized custom roots.
      */
-    skillSources?: readonly AgentRuntimeSkillSource[];
+    readonly skillSources: readonly AgentRuntimeSkillSource[];
     /**
      * Neutral feature names the host asks this runtime to disable. Core emits
      * only neutral names; each runtime maps the names it understands to its own
      * mechanism and ignores the rest.
      */
-    disableFeatures?: readonly string[];
+    readonly disabledFeatures: readonly string[];
     /**
-     * Optional JSON Schema constraining the model's final assistant message for
-     * the *entire resident session*. Provider-neutral: each runtime maps it to
-     * its native structured-output mechanism at spawn time (e.g. claude-code
-     * `--json-schema`, which is a CLI flag fixed for the process lifetime).
-     * Runtimes that support per-turn schema natively (e.g. codex
-     * `turn/start.outputSchema`) may ignore this create-context field and rely
-     * on the per-turn {@link AgentRuntimeTextInput.outputSchema} instead. When
-     * set, every settled turn's result text is expected to be valid JSON
-     * conforming to the schema; the caller parses it. Omitted/undefined means
-     * "no schema constraint" — the common case.
+     * Optional JSON Schema constraining the model's final assistant message, bound
+     * once to this runtime session. A provider that applies the schema natively
+     * per turn stores this fixed value and reapplies it; a later submit can never
+     * change it. When set, every settled turn's result text is expected to be
+     * valid JSON conforming to the schema; the caller parses it.
      */
-    outputSchema?: Record<string, unknown>;
-    /** Required live activity sink, installed before the runtime starts. */
-    activitySink: RuntimeActivitySink;
-    logger?: DreamuxLogger;
-    paths?: AgentRuntimePathContext;
-    state?: AgentRuntimeStateCallbacks;
+    readonly outputSchema?: JsonSchema;
     /**
      * Neutral process-env injection seam. Core merges these entries into the
      * runtime's spawn environment AFTER `process.env` and BEFORE the provider's
      * own `config.extra_env`, i.e. spawn env =
      * `{ ...process.env, ...injectEnv, ...config.extra_env }`. Core owns what (if
      * anything) it injects; `config.extra_env` is the provider's own config and is
-     * NOT routed through here. Empty/omitted means "inject nothing" — the common
-     * case today.
+     * NOT routed through here.
      */
-    injectEnv?: Record<string, string>;
+    readonly injectEnv?: Readonly<Record<string, string>>;
+    readonly paths: AgentRuntimePathContext;
+    /** Leased, push-only state sink for this runtime generation. */
+    readonly state: AgentRuntimeStateSink<TSession>;
+    readonly activity?: AgentRuntimeActivitySink;
+    readonly logger?: AgentRuntimeLogger;
+}
+/** What `start` restored. Core consumes it before admitting the first submission. */
+export interface AgentRuntimeStartOutcome {
+    readonly continuity: 'fresh' | 'resumed';
 }
 /**
- * The live runtime handle a provider's `createRuntime` returns. Neutral: its
- * status type is {@link AgentRuntimeStatus}, not a host enum.
+ * The live runtime handle. Nothing is pulled from it: every runtime fact flows
+ * out through the leased state and activity sinks.
  */
 export interface AgentRuntime {
-    readonly providerRef: string;
-    start(): Promise<void>;
-    resume(): Promise<void>;
     /**
-     * Fence new input synchronously, terminate the owned runtime, and converge
-     * every `channelInput`/`completionInput` call that started before the fence.
-     * This promise MUST NOT resolve while an already-started admission can still
-     * resolve to a newly accepted {@link RuntimeSubmission}.
+     * Launch or restore the native session. A non-null create-context session MUST
+     * restore continuous model context; failure rejects and never silently becomes
+     * fresh. The provider durably publishes its session and ready state before
+     * this resolves.
      */
-    stop(): Promise<void>;
+    start(): Promise<AgentRuntimeStartOutcome>;
+    submit(input: AgentRuntimeSubmissionInput): Promise<RuntimeAdmission>;
     /**
-     * Deliver a channel/user turn. The runtime owns rendering the neutral channel
-     * shape into its native input format.
-     */
-    channelInput(input: InboundTurnInput): Promise<RuntimeAdmission>;
-    /**
-     * Deliver a Dreamux-owned plain text turn. This is not channel input and must
-     * not receive channel/XML rendering.
-     */
-    completionInput(input: AgentRuntimeTextInput): Promise<RuntimeAdmission>;
-    /**
-     * Resolve when no turn is in progress. Optional: runtimes that omit it are
-     * treated by core as always idle.
+     * Fence new input synchronously, terminate the owned runtime, and converge
+     * every `submit` call that started before the fence. This promise MUST NOT
+     * resolve while an already-started admission can still resolve to a newly
+     * accepted {@link RuntimeSubmission}. A stop racing a still-pending start
+     * stops the runtime that appears later; a failed start rolls back all partial
+     * ownership.
      */
-    waitIdle?(): Promise<void>;
-    getStatus(): AgentRuntimeStatus;
-    getCheckpoint(): AgentRuntimeResumeCheckpoint | null;
-    wasCheckpointResumed(): boolean;
+    stop(): Promise<void>;
+}
+/**
+ * A bounded request for the recent tail of one session's activity. Cursors are
+ * opaque and provider-owned; pagination walks a stable recent tail without
+ * skipping or duplicating records as native history grows.
+ */
+export interface AgentActivityQuery<TSession extends AgentRuntimeSessionRef> {
+    readonly session: TSession;
+    readonly cursor?: string;
+    readonly limit?: number;
+    /** Tools are included by default and can only be hidden as a group. */
+    readonly includeTools?: boolean;
+}
+export interface AgentActivityReadContext<TConfig> {
+    readonly config: TConfig;
+    readonly cwd: string;
+    readonly injectEnv?: Readonly<Record<string, string>>;
+    readonly logger?: AgentRuntimeLogger;
+}
+/**
+ * One neutral activity fact. Tool arguments, tool results, provider-native
+ * lines, Core status, admission, and settlement never appear here.
+ */
+export type AgentActivityRecord = {
+    readonly kind: 'assistant_message';
+    readonly text: string;
+    readonly occurredAt?: string;
+} | {
+    readonly kind: 'tool';
+    readonly name: string;
+    readonly status: 'started' | 'completed' | 'failed';
+    readonly occurredAt?: string;
+};
+/** One chronological page of recent Activity Records. */
+export interface AgentActivityPage {
+    readonly records: readonly AgentActivityRecord[];
+    readonly nextCursor?: string;
+    /** Set by the provider when its own native read bounds truncated the page. */
+    readonly truncated: boolean;
+}
+/**
+ * Structural shape of the `Error` a provider rejects an Activity read with.
+ * Reasons describe neutral states only: never a filesystem path, native history
+ * layout, or scan mode. Callers branch on `error.name` rather than
+ * `instanceof`, keeping this package declaration-only.
+ */
+export interface AgentActivityError extends Error {
+    name: 'AgentActivityError';
+    reason: 'session_unavailable' | 'cursor_invalid' | 'activity_corrupt' | 'provider_failure';
+}
+export interface AgentRuntimeProviderConfigReadContext {
+    providerRef: string;
     /**
-     * Context-window usage, or `null` when unavailable.
+     * The `agents[].id` whose config block is being parsed — a config-internal
+     * alias, not a dispatcher identity.
      */
-    getContext(): Promise<AgentRuntimeContextSnapshot | null>;
-    getCapabilities(): AgentRuntimeCapabilities;
+    agentId: string;
+    file: string;
+    prefix: string;
+}
+/**
+ * Optional provider-owned config parsing. A parse/validation failure must throw
+ * (the host fails loud), never return a partially-valid config.
+ */
+export interface AgentRuntimeConfigCapability<TConfig> {
+    read(rawConfig: Record<string, unknown>, context: AgentRuntimeProviderConfigReadContext): TConfig | Promise<TConfig>;
 }
+/**
+ * Optional provider-owned onboarding. Core asks only for host envelope fields
+ * and delegates provider-specific raw config collection to this capability.
+ */
+export type AgentRuntimeOnboardCapability = ProviderOnboard<Record<string, unknown>>;
+/** Runtime-specific alias of the shared provider binary check. */
+export type AgentRuntimeBinCheck = ProviderBinCheck;
+/** Runtime-specific alias of the shared provider diagnostic result. */
+export type AgentRuntimeDiagnosticResult = ProviderDiagnosticResult;
+/** Runtime-specific alias of the shared provider diagnostic runner. */
+export type AgentRuntimeDiagnosticRunner = ProviderDiagnosticRunner;
 /**
  * Per-runtime diagnostic context. Neutral: it carries the runtime instance id,
  * the provider-parsed config, the resolved env, and the diagnostic `scope`,
@@ -438,54 +438,49 @@ export interface AgentRuntimeDiagnosticContext<TConfig = unknown> {
     paths?: AgentRuntimePathContext;
 }
 /**
- * A provider's self-reported diagnostics: it DECLARES the bin checks Dreamux
- * core should dedup + execute, and RUNS its own non-bin internal checks. The
- * core doctor command iterates providers and calls these instead of branching
- * on a builtin ref.
- *
- * Optional on {@link AgentRuntimeProvider}: a provider with no diagnostic surface
- * omits it. The host supplies the {@link AgentRuntimeDiagnosticRunner} to
- * `runDiagnostic`; the provider only implements the checks, never the runner.
+ * Optional provider-owned diagnostics: the provider DECLARES the bin checks
+ * Dreamux core should dedup + execute, and RUNS its own non-bin internal
+ * checks. The host supplies the {@link AgentRuntimeDiagnosticRunner}; the
+ * provider only implements the checks, never the runner.
  */
-export interface AgentRuntimeDiagnostic<TConfig = unknown> {
+export interface AgentRuntimeDiagnosticCapability<TConfig> {
     binChecks(context: AgentRuntimeDiagnosticContext<TConfig>): AgentRuntimeBinCheck[];
     runDiagnostic(context: AgentRuntimeDiagnosticContext<TConfig>, runner: AgentRuntimeDiagnosticRunner): Promise<AgentRuntimeDiagnosticResult>;
 }
 /**
- * The Agent Runtime provider contract. An external or built-in runtime package
- * implements this against `@excitedjs/dreamux-types` only.
+ * The Agent Runtime provider facade: selection, neutral recent Activity reads,
+ * and runtime creation, plus operational capabilities composed as optional
+ * objects rather than fake methods.
+ *
+ * Registration identity is absent by construction — Core owns the descriptor in
+ * its {@link RegisteredProvider} wrapper, so this interface has no `ref` or
+ * `descriptor` member and a live {@link AgentRuntime} echoes neither.
+ *
+ * Every provider defines its own JSON-serializable `TSession`. A provider that
+ * resumes from an id alone uses {@link AgentRuntimeSessionRef}; one that needs
+ * more native resume coordinates extends it.
  */
-export interface AgentRuntimeProvider<TConfig = unknown> {
-    readonly ref: string;
-    readonly descriptor: AgentRuntimeProviderDescriptor;
-    getCapabilities(): AgentRuntimeCapabilities;
-    /**
-     * Parse + validate this provider's own config block. May return synchronously
-     * or as a promise; Dreamux core awaits the result, mirroring
-     * `ChannelProvider.readConfig`. A parse/validation failure must throw (the host
-     * fails loud), never return a partially-valid config.
-     */
-    readConfig?(rawConfig: Record<string, unknown>, context: AgentRuntimeProviderConfigReadContext): TConfig | Promise<TConfig>;
-    /**
-     * Self-reported diagnostics. Optional: a provider with no diagnostic
-     * surface may omit it.
-     */
-    diagnostic?: AgentRuntimeDiagnostic<TConfig>;
+export interface AgentRuntimeProvider<TConfig, TSession extends AgentRuntimeSessionRef = AgentRuntimeSessionRef> {
+    getCapabilities(): AgentRuntimeProviderCapabilities;
     /**
-     * Provider-owned onboarding. Core asks only for host envelope fields and
-     * delegates provider-specific raw config collection to this capability.
+     * Read the recent tail of one session's activity. Mandatory: it must work
+     * against an actively growing session — producing useful records before any
+     * completion marker — and against the same session after the live runtime has
+     * closed. The provider enforces its own native read bounds and sets
+     * {@link AgentActivityPage.truncated}; Core independently validates record
+     * count, text size, page size, cursor size, and public errors.
      */
-    onboard?: ProviderOnboard<Record<string, unknown>>;
-    readTranscript(query: AgentRuntimeTranscriptQuery, context: AgentRuntimeTranscriptContext<TConfig>): Promise<AgentRuntimeTranscriptPage>;
-    createRuntime(context: AgentRuntimeCreateContext<TConfig>): AgentRuntime;
+    readRecentActivity(query: AgentActivityQuery<TSession>, context: AgentActivityReadContext<TConfig>): Promise<AgentActivityPage>;
+    createRuntime(context: AgentRuntimeCreateContext<TConfig, TSession>): Promise<AgentRuntime>;
+    readonly config?: AgentRuntimeConfigCapability<TConfig>;
+    readonly onboard?: AgentRuntimeOnboardCapability;
+    readonly diagnostic?: AgentRuntimeDiagnosticCapability<TConfig>;
 }
 /**
  * The default (or `npm:pkg#export`-selected) factory export an Agent Runtime
- * package ships. Its {@link ProviderFactoryContext} carries the already-narrowed
- * {@link AgentRuntimeProviderDescriptor}, so the package assigns
- * `provider.descriptor` from the seed without a cast.
+ * package ships.
  */
-export type AgentRuntimeProviderFactory<TConfig = unknown> = ProviderFactory<AgentRuntimeProvider<TConfig>, AgentRuntimeProviderDescriptor>;
+export type AgentRuntimeProviderFactory<TConfig, TSession extends AgentRuntimeSessionRef = AgentRuntimeSessionRef> = ProviderFactory<AgentRuntimeProvider<TConfig, TSession>>;
 /** Re-export so provider packages can take a logger in their own contexts. */
 export type { DreamuxLogger };
 //# sourceMappingURL=agent-runtime.d.ts.map