@ai-agent-forge/plugin-sdk 0.85.0

package/dist/public-api.d.ts

@@ -0,0 +1,1977 @@
+/**
+ * Experimental, host-facing contracts for capability plugins.
+ *
+ * This module deliberately contains no product policy. It describes the
+ * capabilities a host may expose; policy plugins decide how to compose them.
+ *
+ * Authority: `@agent-forge/plugin-sdk` is the single authoring source for this
+ * surface (D-075 S2); the host (`@agent-forge/agent-forge`) re-exports it from
+ * its historical module path so existing imports keep resolving.
+ */
+import type { MemoryStorageComponentsV1 } from "./memory.ts";
+import type { ObservabilityHostAdapterV1, TraceSinkOptionsV1 } from "./observability.ts";
+/** @experimental Promoted out of draft only when a real consumer drives stabilization. */
+export declare const EXPERIMENTAL_PUBLIC_API_VERSION: "1-draft";
+/**
+ * Thinking/reasoning level for models that support it.
+ * Note: "xhigh" and "max" are only supported by selected model families. Use model
+ * thinking-level metadata from the host to detect support for a concrete model.
+ *
+ * Authority moved from `@agent-forge/agent-core` (D-075 S2); agent-core
+ * re-exports it from here.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type HostMode = "readonly" | "full-control";
+/** Estimated context usage for the active model; the session read face (`getContextUsage`) projects it. */
+export interface ContextUsage {
+    /** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
+    tokens: number | null;
+    contextWindow: number;
+    /** Context usage as percentage of context window, or null if tokens is unknown. */
+    percent: number | null;
+}
+export type PluginConfigValue = null | boolean | number | string | readonly PluginConfigValue[] | {
+    readonly [key: string]: PluginConfigValue;
+};
+/** JSON configuration declared by a plugin's own manifest. */
+export type PluginConfig = Readonly<Record<string, PluginConfigValue>>;
+/** Draft plugin-provided capability contract. Version is an exact integer schema version. */
+export interface PluginCapabilityDeclaration {
+    id: string;
+    version: number;
+    kind: "service" | "contribution" | "transform";
+}
+/** Draft plugin capability dependency. Requirements use exact version matching. */
+export interface PluginCapabilityRequirement {
+    id: string;
+    version: number;
+    optional?: boolean;
+}
+/** Roles that a plugin may expose through the experimental Agent composition facade. */
+export type PluginAgentRole = "root-agent-controller" | "child-agent-controller";
+/** Manifest declaration for an AgentDefinition that a plugin may register. */
+export interface AgentDefinitionDeclaration {
+    id: string;
+    version: number;
+    role: PluginAgentRole;
+    entry: string;
+}
+export interface PluginManifest {
+    id: string;
+    version: string;
+    /**
+     * Semver range of host (agent-forge application) versions this plugin
+     * supports, e.g. `">=0.84.0 <1.0.0"`. When declared and the running host
+     * version is outside the range, the plugin is rejected at discovery
+     * (D-073). Paired with the plugin's own `version` (the "two version
+     * numbers" contract).
+     */
+    hostVersion?: string;
+    apiVersion: typeof EXPERIMENTAL_PUBLIC_API_VERSION;
+    entry: string;
+    requiredCapabilities?: string[];
+    optionalCapabilities?: string[];
+    /** Plugin capabilities provided to the runtime directory. */
+    provides?: readonly PluginCapabilityDeclaration[];
+    /** Plugin capabilities required from other loaded plugins. */
+    requires?: readonly PluginCapabilityRequirement[];
+    /** Experimental Agent controller roles exposed by this plugin. */
+    roles?: readonly PluginAgentRole[];
+    /** Experimental Agent definitions that the plugin factory may register. */
+    agents?: readonly AgentDefinitionDeclaration[];
+    config?: PluginConfig;
+}
+/**
+ * 子↔子/子→父的有界信箱消息（D-060 S4）。第一方信箱实现（`@agent-forge/protocol`
+ * subagent mailbox）与宿主通信接线共用此形状。
+ */
+export interface SubagentInboxMessageV1 {
+    /** 发送方子会话 id。 */
+    readonly from: string;
+    readonly text: string;
+}
+/**
+ * 通信面的宿主接线（D-060 S4，与通信配置开关分离）：身份绑定与血缘校验都在宿主侧，
+ * capability 只暴露模型工具面。迁自宿主 `subagent-delegate.ts`（D-075 S4 第三批）。
+ */
+export interface SubagentCommunicationWiringV1 {
+    /** 父侧：取走某子会话的 escalation 队列（有界、取后即清）。 */
+    drainEscalations?(sessionId: string): string[];
+    /** 子侧：向父上抛一条有界消息（发送者身份由宿主绑定，调用方无法伪造）。 */
+    postEscalate?(text: string): void;
+    /** 子侧：向同父兄弟投递一条有界消息（宿主校验双方血缘，越界同型拒绝）。 */
+    sendSibling?(toSessionId: string, text: string): void;
+    /** 子侧：取走自己收件箱里最早的至多 `limit` 条（取后即清）。 */
+    drainInbox?(limit: number): SubagentInboxMessageV1[];
+}
+export interface HostCapabilities {
+    apiVersion: typeof EXPERIMENTAL_PUBLIC_API_VERSION;
+    mode: HostMode;
+    features: readonly string[];
+    transports: readonly ("in-process" | "stdio" | "http" | "rpc")[];
+    /**
+     * Host agent directory (D-075 S4 second batch). Present on hosts that own
+     * an on-disk agent dir; lets plugins that keep disk state locate their
+     * config files, e.g. `<agentDir>/capabilities/<id>.json` — the same
+     * channel the host's embedded builtins used before the package split.
+     * Absent on hosts without an agent dir; plugins must treat it as optional.
+     */
+    agentDir?: string;
+    /**
+     * Subagent communication wiring (D-075 S4 third batch, host service
+     * contract). Present on hosts that assemble a subagent mailbox for the
+     * session's delegation domain; the first-party subagent-delegate plugin
+     * binds its escalate/sibling tool faces to these callbacks (identity
+     * binding and lineage scoping stay host-side). Absent = communication
+     * tools stay unregistered (D-060 S4 default-off).
+     */
+    communication?: SubagentCommunicationWiringV1;
+    /**
+     * Turn-scoped host context (D-075 S4 third batch, host service contract).
+     * `backgroundDigestSink` receives one bounded JSON line per settled
+     * background delegation (taskId/sessionId/status/reasonCode) for the host
+     * to inject into the parent's next model turn; `getTurnCorrelationId`
+     * returns the correlation id of the parent turn at submission time — an
+     * absent getter or undefined return means the lineage key is not written
+     * and behavior falls back. Absent = background tasks still run, just
+     * without push notification or turn-lineage attribution.
+     */
+    turnContext?: {
+        backgroundDigestSink?: (line: string) => void;
+        getTurnCorrelationId?: () => string | undefined;
+    };
+    /**
+     * Role ids associated with the active suite (D-075 S4 third batch, host
+     * service contract). Roles are disk-only definitions
+     * (`<agentDir>/roles/<id>.json`); only associated ids surface in the
+     * delegation tool menu. Absent = the session exposes no roles (there is
+     * no built-in fallback — the engine ships none).
+     */
+    roleAssociations?: readonly string[];
+    /**
+     * Memory storage components (D-075 S4 fourth batch, host service
+     * contract). Runtime services, not just types: a host that assembles the
+     * memory capability passes the A1/A2 storage injection face here
+     * (store/ledger factories plus optional vector components) and the
+     * first-party memory plugin binds them in place of its built-in
+     * defaults. Absent = the plugin runs its default local implementation
+     * (in-memory store + JSONL ledger under `<agentDir>/memory/`); hosts
+     * without memory support leave it undefined and the plugin registers
+     * nothing when no agentDir is declared.
+     */
+    memoryStorage?: MemoryStorageComponentsV1;
+}
+export interface DisposableRegistration {
+    id: string;
+    kind: string;
+    dispose(): void | Promise<void>;
+}
+export type OperationStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "timed_out";
+export interface OperationHandle<TResult = unknown> {
+    id: string;
+    signal: AbortSignal;
+    status(): OperationStatus;
+    result: Promise<TResult>;
+    cancel(reason?: string): Promise<void>;
+}
+/** A detached, serializable progress fact emitted by a running operation. */
+export interface OperationProgress {
+    message?: string;
+    data?: PluginConfigValue;
+}
+/** Execution controls available to a registered Capability operation. */
+export interface OperationExecutionContext {
+    readonly operationId: string;
+    readonly signal: AbortSignal;
+    /** Returns false after cancellation, terminal settlement, or owner revoke. */
+    reportProgress(progress: OperationProgress): boolean;
+}
+export interface EventEnvelope<TData = unknown> {
+    id: string;
+    type: string;
+    version: number;
+    source: string;
+    timestamp: number;
+    correlationId: string;
+    causationId?: string;
+    data: TData;
+}
+/** @experimental Stage 1A draft data phase for a host lifecycle event. */
+export type LifecyclePhase = "raw" | "candidate" | "committed";
+/** @experimental Stage 1A draft registration kinds for the lifecycle directory. */
+export type LifecycleRegistrationKind = "observe" | "transform" | "execute" | "after-commit";
+/** Optional host-side buffering for an observation subscription. */
+export interface LifecycleDeliveryOptions {
+    /** Maximum in-flight plus queued events for this one subscription. */
+    maxPendingEvents: number;
+    /** Optional UTF-8 serialized-event budget for this one subscription. */
+    maxPendingBytes?: number;
+}
+export type LifecycleDeliveryMode = "inline" | "bounded-queue";
+/** Read-only subscription delivery state exposed by the runtime inspector. */
+export interface LifecycleDeliverySnapshot {
+    mode: LifecycleDeliveryMode;
+    maxPendingEvents?: number;
+    maxPendingBytes?: number;
+    status?: "active" | "overflowed" | "closed";
+    pendingEvents?: number;
+    pendingBytes?: number;
+    accepted?: number;
+    delivered?: number;
+    rejected?: number;
+}
+/** @experimental Stage 1A draft lifecycle event definition. */
+export interface LifecycleEventDefinition<TData = unknown> {
+    id: string;
+    version: number;
+    phase: LifecyclePhase;
+    /** Optional additional phases accepted by multi-phase events. */
+    allowedPhases?: readonly LifecyclePhase[];
+    schema: string;
+    /**
+     * Registration kinds permitted by this event contract. Omitted keeps the
+     * phase-compatible default for custom draft events; standard events should
+     * declare the narrowest set they support.
+     */
+    allowedRegistrationKinds?: readonly LifecycleRegistrationKind[];
+    validate(value: unknown): TData;
+}
+/** A reference accepted by lifecycle registration methods. */
+export interface LifecycleEventReference {
+    id: string;
+    version: number;
+}
+/** An immutable event delivered to a lifecycle handler. */
+export interface LifecycleEvent<TData = unknown> {
+    id: string;
+    deliveryId: string;
+    type: string;
+    version: number;
+    phase: LifecyclePhase;
+    source: string;
+    timestamp: number;
+    operationId?: string;
+    correlationId?: string;
+    causationId?: string;
+    data: TData;
+}
+/** Input accepted by the host lifecycle dispatcher. */
+export interface LifecycleDispatchRequest<TData = unknown> {
+    type: string;
+    version: number;
+    phase: LifecyclePhase;
+    data: TData;
+    /** Optional host cancellation fence for an in-flight lifecycle delivery. */
+    signal?: AbortSignal;
+    operationId?: string;
+    correlationId?: string;
+    causationId?: string;
+    source?: string;
+}
+export type LifecycleObserveHandler<TData = unknown> = (event: LifecycleEvent<TData>, signal?: AbortSignal) => void | Promise<void>;
+export type LifecycleTransformHandler<TData = unknown> = (event: LifecycleEvent<TData>, signal?: AbortSignal) => TData | Promise<TData>;
+/**
+ * An owner-side execution step. Execution is awaited for completion but does
+ * not replace the lifecycle event data; any owner result belongs to the
+ * operation facade that initiated the lifecycle dispatch.
+ */
+export type LifecycleExecuteHandler<TData = unknown> = (event: LifecycleEvent<TData>, signal?: AbortSignal) => unknown | Promise<unknown>;
+export type LifecycleAfterCommitHandler<TData = unknown> = LifecycleObserveHandler<TData>;
+/** A failed lifecycle delivery, retaining the original handler error. */
+export interface LifecycleDeliveryFailure {
+    pluginId: string;
+    registrationId: string;
+    kind: LifecycleRegistrationKind;
+    error: unknown;
+}
+/** The delivery result is separate from the underlying operation or commit result. */
+export interface LifecycleDeliveryReport {
+    eventId: string;
+    type: string;
+    version: number;
+    phase: LifecyclePhase;
+    status: "delivered" | "queued" | "transform-failed" | "execute-failed";
+    attempted: number;
+    succeeded: number;
+    /** Number accepted by detached subscriber queues, when non-zero. */
+    queued?: number;
+    failed: number;
+    failures: readonly LifecycleDeliveryFailure[];
+}
+export interface LifecycleDispatchResult<TData = unknown> {
+    event: LifecycleEvent<TData>;
+    data: TData;
+    executeResults: readonly unknown[];
+    report: LifecycleDeliveryReport;
+}
+/** @experimental Rejected candidate transform, with an independent delivery report. */
+export declare class LifecycleTransformError extends Error {
+    readonly report: LifecycleDeliveryReport;
+    readonly cause: unknown;
+    constructor(cause: unknown, report: LifecycleDeliveryReport);
+}
+/** @experimental Rejected owner execution, with an independent delivery report. */
+export declare class LifecycleExecuteError extends Error {
+    readonly report: LifecycleDeliveryReport;
+    readonly cause: unknown;
+    constructor(cause: unknown, report: LifecycleDeliveryReport);
+}
+/** @experimental Stage 1A draft lifecycle registration facade. */
+export interface LifecycleAPI {
+    define<TData>(definition: LifecycleEventDefinition<TData>): LifecycleEventDefinition<TData>;
+    get<TData = unknown>(id: string, version: number): LifecycleEventDefinition<TData>;
+    registerObserve<TData = unknown>(event: LifecycleEventDefinition<TData> | LifecycleEventReference | string, handler: LifecycleObserveHandler<TData>, version?: number, options?: LifecycleDeliveryOptions): DisposableRegistration;
+    registerTransform<TData = unknown>(event: LifecycleEventDefinition<TData> | LifecycleEventReference | string, handler: LifecycleTransformHandler<TData>, version?: number): DisposableRegistration;
+    registerExecute<TData = unknown>(event: LifecycleEventDefinition<TData> | LifecycleEventReference | string, handler: LifecycleExecuteHandler<TData>, version?: number): DisposableRegistration;
+    registerAfterCommit<TData = unknown>(event: LifecycleEventDefinition<TData> | LifecycleEventReference | string, handler: LifecycleAfterCommitHandler<TData>, version?: number, options?: LifecycleDeliveryOptions): DisposableRegistration;
+}
+/** @experimental Stage 1A draft lifecycle semantics for a generic contribution point. */
+export type ContributionLifecycle = "observe" | "transform" | "execute" | "after-commit";
+/** @experimental Stage 1A draft contribution point declaration. */
+export interface ContributionPointDefinition<TValue = unknown> {
+    id: string;
+    version: number;
+    schema: string;
+    lifecycle?: ContributionLifecycle;
+    validate(value: unknown): TValue;
+}
+/** @experimental Stage 1A draft contribution entry snapshot. */
+export interface ContributionEntry<TValue = unknown> {
+    id: string;
+    pointId: string;
+    version: number;
+    owner: string;
+    lifecycle: ContributionLifecycle;
+    value: TValue;
+}
+/** @experimental Stage 1A draft contribution change notification. */
+export interface ContributionChangeEvent<TValue = unknown> {
+    pointId: string;
+    version: number;
+    action: "added" | "removed";
+    contributionId: string;
+    owner: string;
+    entry?: ContributionEntry<TValue>;
+}
+/** @experimental Stage 1A draft contribution lifecycle handle. */
+export interface ContributionHandle {
+    readonly id: string;
+    readonly pointId: string;
+    readonly version: number;
+    readonly owner: string;
+    dispose(): void | Promise<void>;
+}
+/** @experimental Stage 1A draft contribution point facade. */
+export interface ContributionPoint<TValue = unknown> {
+    readonly id: string;
+    readonly version: number;
+    readonly schema: string;
+    readonly lifecycle: ContributionLifecycle;
+    add(input: {
+        id: string;
+        value: TValue;
+    }): Promise<ContributionHandle>;
+    remove(id: string): Promise<void>;
+    list(): readonly ContributionEntry<TValue>[];
+    subscribe(handler: (event: ContributionChangeEvent<TValue>) => void | Promise<void>): DisposableRegistration;
+}
+/** @experimental Stage 1A draft contribution registry facade. */
+export interface ContributionAPI {
+    define<TValue>(definition: ContributionPointDefinition<TValue>): ContributionPoint<TValue>;
+    get<TValue = unknown>(id: string, version: number): ContributionPoint<TValue>;
+    list(): readonly {
+        id: string;
+        version: number;
+        schema: string;
+        lifecycle: ContributionLifecycle;
+        owner: string;
+    }[];
+}
+export type LoggerLevel = "debug" | "info" | "warn" | "error";
+export interface LoggerRecord {
+    version: 1;
+    level: LoggerLevel;
+    message: string;
+    fields?: PluginConfigValue;
+    cause?: unknown;
+    pluginId: string;
+    timestamp: number;
+    sessionId?: string;
+    operationId?: string;
+    correlationId?: string;
+    phase?: string;
+}
+export interface LoggerAPI {
+    debug(message: string, fields?: PluginConfigValue): void;
+    info(message: string, fields?: PluginConfigValue): void;
+    warn(message: string, fields?: PluginConfigValue): void;
+    error(message: string, fields?: PluginConfigValue, cause?: unknown): void;
+}
+export interface DiagnosticsSpanEnd {
+    status: "ok" | "error" | "cancelled";
+    result?: PluginConfigValue;
+    cause?: unknown;
+}
+export interface DiagnosticsSpanSnapshot {
+    version: 1;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    pluginId: string;
+    sessionId?: string;
+    startedAt: number;
+    endedAt?: number;
+    status: "running" | "ok" | "error" | "cancelled";
+    attributes: PluginConfigValue;
+    result?: PluginConfigValue;
+    cause?: unknown;
+    operationId?: string;
+    correlationId?: string;
+    phase?: string;
+}
+export interface DiagnosticsSpan {
+    readonly traceId: string;
+    readonly spanId: string;
+    annotate(fields: PluginConfigValue): void;
+    end(outcome?: DiagnosticsSpanEnd): void;
+}
+export interface DiagnosticsAPI {
+    start(name: string, attributes?: PluginConfigValue, parentSpanId?: string): DiagnosticsSpan;
+}
+/** @experimental Read-only runtime plugin facts exposed by the inspector. */
+export interface RuntimeInspectorPluginSnapshot {
+    id: string;
+    version: string;
+    active: boolean;
+    manifest: PluginManifest;
+    provides: readonly PluginCapabilityDeclaration[];
+    requires: readonly PluginCapabilityRequirement[];
+}
+/** @experimental Read-only contribution entry facts exposed by the inspector. */
+export interface RuntimeInspectorContributionSnapshot {
+    id: string;
+    pointId: string;
+    version: number;
+    owner: string;
+    lifecycle: ContributionLifecycle;
+    value: unknown;
+}
+/** @experimental Read-only contribution point facts exposed by the inspector. */
+export interface RuntimeInspectorContributionPointSnapshot {
+    id: string;
+    version: number;
+    schema: string;
+    lifecycle: ContributionLifecycle;
+    owner: string;
+    active: boolean;
+}
+/** @experimental Read-only lifecycle registration facts exposed by the inspector. */
+export interface RuntimeInspectorLifecycleRegistrationSnapshot {
+    id: string;
+    kind: LifecycleRegistrationKind;
+    owner: string;
+    active: boolean;
+    delivery: LifecycleDeliverySnapshot;
+}
+/** @experimental Read-only lifecycle event facts exposed by the inspector. */
+export interface RuntimeInspectorLifecycleSnapshot {
+    id: string;
+    version: number;
+    phase: LifecyclePhase;
+    allowedPhases?: readonly LifecyclePhase[];
+    schema: string;
+    owner: string;
+    active: boolean;
+    registrations: readonly RuntimeInspectorLifecycleRegistrationSnapshot[];
+}
+/** Immutable error facts retained by the runtime inspector. */
+export interface RuntimeInspectorErrorSnapshot {
+    readonly name: string;
+    readonly message: string;
+    readonly cause?: RuntimeInspectorErrorSnapshot;
+    readonly code?: string;
+}
+/** A normalized lifecycle delivery failure suitable for an immutable inspector snapshot. */
+export interface RuntimeInspectorLifecycleDeliveryFailureSnapshot {
+    readonly pluginId: string;
+    readonly registrationId: string;
+    readonly kind: LifecycleRegistrationKind;
+    readonly error: RuntimeInspectorErrorSnapshot;
+}
+/** A bounded, immutable record of one completed lifecycle delivery. */
+export interface RuntimeInspectorLifecycleDeliveryReportSnapshot {
+    readonly eventId: string;
+    readonly type: string;
+    readonly version: number;
+    readonly phase: LifecyclePhase;
+    readonly status: LifecycleDeliveryReport["status"];
+    readonly attempted: number;
+    readonly succeeded: number;
+    readonly queued?: number;
+    readonly failed: number;
+    readonly completedAt: number;
+    readonly failures: readonly RuntimeInspectorLifecycleDeliveryFailureSnapshot[];
+}
+/**
+ * Reason a discovered capability plugin was rejected during session startup
+ * without preventing the remaining plugins from loading (D-028).
+ */
+export type PluginRejectionCode = "invalid_manifest" | "host_version_incompatible" | "duplicate_plugin_id" | "missing_dependency" | "plugin_load_failed";
+/** Structured, immutable record of one rejected capability plugin. */
+export interface PluginRejection {
+    readonly code: PluginRejectionCode;
+    readonly manifestPath: string;
+    readonly pluginId?: string;
+    readonly message: string;
+}
+export interface RuntimeInspectorSnapshot {
+    version: 1;
+    host: HostCapabilities;
+    plugins: readonly RuntimeInspectorPluginSnapshot[];
+    pluginRejections: readonly PluginRejection[];
+    registrations: readonly {
+        kind: string;
+        name: string;
+        owner: string;
+    }[];
+    contributionPoints: readonly RuntimeInspectorContributionPointSnapshot[];
+    contributions: readonly RuntimeInspectorContributionSnapshot[];
+    lifecycle: readonly RuntimeInspectorLifecycleSnapshot[];
+    lifecycleReports: readonly RuntimeInspectorLifecycleDeliveryReportSnapshot[];
+    subscriptions: readonly {
+        id: string;
+        type: string;
+        owner: string;
+    }[];
+    operations: readonly {
+        id: string;
+        status: OperationStatus;
+    }[];
+    logs: readonly LoggerRecord[];
+    spans: readonly DiagnosticsSpanSnapshot[];
+}
+export interface RuntimeInspectorAPI {
+    snapshot(): RuntimeInspectorSnapshot;
+}
+export interface StateEntry {
+    key: string;
+    revision: number;
+    value: PluginConfigValue;
+}
+export interface StateSetOptions {
+    expectedRevision?: number;
+    operationId?: string;
+    correlationId?: string;
+}
+export interface StateChange {
+    /** Stable owner namespace that produced this state transition. */
+    pluginId: string;
+    key: string;
+    revision: number;
+    value?: PluginConfigValue;
+    operationId?: string;
+    correlationId?: string;
+}
+export interface StateAPI {
+    get(key: string): StateEntry | undefined;
+    set(key: string, value: PluginConfigValue, options?: StateSetOptions): number;
+    delete(key: string, options?: StateSetOptions): number;
+    list(prefix?: string): readonly StateEntry[];
+    watch(prefix: string | undefined, handler: (change: StateChange) => void): DisposableRegistration;
+}
+/** A branch-local, append-only view for plugins that persist their own state. */
+export interface SessionEntryView {
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+    type: string;
+    /** Structured message view carried by `type: "message"` entries only. */
+    message?: SessionEntryMessageView;
+    customType?: string;
+    data?: unknown;
+}
+/**
+ * Minimal structured projection of a message entry: only the fields consumers
+ * actually branch on (role/content). The host projects these instead of the
+ * full internal message so the view stays a stable public contract.
+ */
+export interface SessionEntryMessageView {
+    role: string;
+    content?: unknown;
+}
+/** Snapshot of a tool/command registration source, mirroring the core SourceInfo fields. */
+export interface SourceInfoViewV1 {
+    path: string;
+    source: string;
+    scope: "user" | "project" | "temporary";
+    origin: "package" | "top-level";
+    baseDir?: string;
+}
+/** Tool enumeration entry: name, description, JSON-schema parameters, prompt guidelines, and source metadata. */
+export interface ToolInfoViewV1 {
+    name: string;
+    description: string;
+    /** Parameter schema as declared on the tool definition (TypeBox). */
+    parameters: unknown;
+    promptGuidelines?: readonly string[];
+    sourceInfo: SourceInfoViewV1;
+}
+export type CommandSourceViewV1 = "extension" | "prompt" | "skill";
+/** Slash command enumeration entry across extension, prompt-template, and skill sources. */
+export interface CommandInfoViewV1 {
+    name: string;
+    description?: string;
+    source: CommandSourceViewV1;
+    sourceInfo: SourceInfoViewV1;
+}
+/** Provider-agnostic facts about a model, mirroring the modelRuntime.getModelFacts projection. */
+export interface ModelFactsViewV1 {
+    provider: string;
+    id: string;
+    contextWindow: number;
+    maxTokens: number;
+    reasoning: boolean;
+}
+/** Scoped model entry: model facts plus the pattern's explicit thinking level, if any. */
+export interface ScopedModelFactsViewV1 {
+    model: ModelFactsViewV1;
+    thinkingLevel?: ThinkingLevel;
+}
+/** A versioned, in-memory export of the current session branch. */
+export interface SessionExportArtifact {
+    version: 1;
+    format: "jsonl";
+    mediaType: "application/x-ndjson";
+    fileName: string;
+    bytes: Uint8Array;
+}
+export interface SessionExportRequest {
+    format: SessionExportArtifact["format"];
+}
+/** Versioned, opaque session fact for optimistic host operations. */
+export interface SessionRevisionV1 {
+    version: 1;
+    sessionId: string;
+    sequence: number;
+    leafId: string | null;
+}
+/**
+ * One serializable, optimistic request to append a compaction entry.
+ *
+ * The host owns the commit decision. This value only carries the immutable
+ * facts that make retries and stale work observable to the host.
+ */
+export interface CompactionCommitRequestV1<TDetails = unknown> {
+    version: 1;
+    operationId: string;
+    expectedRevision: SessionRevisionV1;
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    details?: TDetails;
+    fromHook?: boolean;
+    usage?: unknown;
+}
+export interface CompactionCommitAppliedV1 {
+    version: 1;
+    status: "committed" | "replayed";
+    entryId: string;
+    /** The revision produced by the original successful commit. */
+    revision: SessionRevisionV1;
+}
+export interface CompactionCommitRevisionConflictV1 {
+    version: 1;
+    status: "revision_conflict";
+    currentRevision: SessionRevisionV1;
+}
+export type CompactionCommitResultV1 = CompactionCommitAppliedV1 | CompactionCommitRevisionConflictV1;
+/** A versioned execution boundary supplied by the host to an orchestration plugin. */
+export type ExecutionPhaseV1 = "agent" | "compaction" | "overflow" | "retry" | "branch_summary" | "reload" | "tree";
+/**
+ * Immutable input facts for a single host operation. These facts identify an
+ * optimistic commit boundary; they do not themselves grant commit authority.
+ */
+export interface ExecutionFactsV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly inputRevision: SessionRevisionV1;
+    readonly phase: ExecutionPhaseV1;
+}
+/** A validated retry outcome attached to one immutable execution boundary. */
+export interface RetryScheduleV1 extends ExecutionFactsV1 {
+    readonly action: "retry" | "stop";
+    /** `retry` is one-based; `stop` records the number of attempts already made. */
+    readonly attempt: number;
+    /** A `stop` action must not request a delay. */
+    readonly delayMs: number;
+}
+export type CapabilityProviderHandler<TInput = unknown, TResult = unknown> = (input: TInput, context: {
+    signal: AbortSignal;
+}) => TResult | Promise<TResult>;
+export interface CapabilityHandle<TResult = unknown> {
+    readonly declaration: PluginCapabilityDeclaration;
+    readonly owner: string;
+    call(input: unknown, options?: {
+        signal?: AbortSignal;
+    }): OperationHandle<TResult>;
+}
+export interface CapabilityDirectoryAPI {
+    provide<TInput = unknown, TResult = unknown>(declaration: PluginCapabilityDeclaration, handler: CapabilityProviderHandler<TInput, TResult>): DisposableRegistration;
+    require<TResult = unknown>(id: string, options?: {
+        version?: number;
+    }): CapabilityHandle<TResult>;
+    list(options?: {
+        kind?: PluginCapabilityDeclaration["kind"];
+    }): readonly {
+        declaration: PluginCapabilityDeclaration;
+        owner: string;
+    }[];
+}
+export interface OutputArtifactRef {
+    sessionId: string;
+    operationId: string;
+    artifactId: string;
+    kind: string;
+    mediaType: string;
+    sizeBytes?: number;
+    truncated: boolean;
+    createdAt: number;
+}
+export interface OutputArtifactChunk {
+    data: Uint8Array;
+    nextOffset?: number;
+    eof: boolean;
+}
+export type OutputArtifactErrorCode = "invalid_ref" | "not_found" | "cancelled";
+export type OutputArtifactPutInput = Omit<OutputArtifactRef, "artifactId" | "sizeBytes" | "createdAt"> & {
+    data: Uint8Array | AsyncIterable<Uint8Array>;
+};
+export interface OutputArtifactAPI {
+    put(input: OutputArtifactPutInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<OutputArtifactRef>;
+    stat(ref: OutputArtifactRef): Promise<OutputArtifactRef>;
+    read(ref: OutputArtifactRef, options?: {
+        offset?: number;
+        maxBytes?: number;
+    }): Promise<OutputArtifactChunk>;
+}
+export interface CredentialResolveRequest {
+    providerId: string;
+    minValidityMs?: number;
+    signal?: AbortSignal;
+}
+/** Resolved provider auth facts for a plugin's explicit request. */
+export interface CredentialResolution {
+    apiKey?: string;
+    headers: Readonly<Record<string, string | null>>;
+    baseUrl?: string;
+    source?: string;
+}
+export interface CredentialAPI {
+    resolve(request: CredentialResolveRequest): Promise<CredentialResolution | undefined>;
+}
+/**
+ * Structural skill shape accepted by {@link BuildSystemPromptOptions.skills}
+ * (D-075 S2). The host's full `Skill` type carries host-owned source facts;
+ * host skill objects are structurally assignable to this projection.
+ */
+export interface BuildSystemPromptSkill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    sourceInfo: unknown;
+    disableModelInvocation: boolean;
+}
+/**
+ * System prompt assembly options (authority moved from the host's
+ * `core/system-prompt.ts`, D-075 S2; the host re-exports it from here).
+ */
+export interface BuildSystemPromptOptions {
+    /** Custom system prompt (replaces default). */
+    customPrompt?: string;
+    /**
+     * Session-nature orientation text (suite persona, 设计 §6.2) injected right
+     * after the opening paragraph (customPrompt branch: right after the custom
+     * prompt body), before tools, guidelines, and context files.
+     */
+    orientationPrompt?: string;
+    /**
+     * Assistant preference card (统一修复轮 A 交付3, H2 接线): the durable
+     * user-profile card, injected immediately after the orientation section
+     * (same M2 pattern — it can also appear alone when no persona is set),
+     * before tools, guidelines, and context files.
+     */
+    preferenceCard?: string;
+    /** Tools to include in prompt. Default: [read, bash, edit, write] */
+    selectedTools?: string[];
+    /** Optional one-line tool snippets keyed by tool name. */
+    toolSnippets?: Record<string, string>;
+    /** Additional guideline bullets appended to the default system prompt guidelines. */
+    promptGuidelines?: string[];
+    /** Text to append to system prompt. */
+    appendSystemPrompt?: string;
+    /** Working directory. */
+    cwd: string;
+    /** Pre-loaded context files. */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Pre-loaded skills. */
+    skills?: readonly BuildSystemPromptSkill[];
+}
+/**
+ * Public session mechanism. Product state remains plugin-owned and is written
+ * as append-only custom entries, so a plugin never mutates SessionManager
+ * internals or another branch's history.
+ */
+/**
+ * Terminal outcome of a prompt run. User-initiated aborts are normal outcomes:
+ * the promise resolves with `status: "aborted"` instead of rejecting.
+ */
+export type PromptOutcome = {
+    status: "done";
+} | {
+    status: "aborted";
+    reason: "interrupted" | "replaced";
+};
+/**
+ * Content accepted by {@link SessionAPI.sendMessage}. Verbatim structural
+ * equivalent of the host's `sendCustomMessage` content type (`TextContent` /
+ * `ImageContent`), registered inline so this contract does not depend on
+ * `@agent-forge/ai`.
+ */
+export type SessionMessageContent = string | ({
+    type: "text";
+    text: string;
+    textSignature?: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+})[];
+export interface SessionAPI {
+    getSessionId(): string;
+    /**
+     * 会话**自身**的身份（D-060 S1）。当宿主可见的 `getSessionId()` 是一个宿主侧标识
+     * （池化 runner 下是 wire 任务 id）时，本成员给出底层 agent 会话的真实 id；缺省表示
+     * 两者相同（shared 模式即如此）。
+     */
+    getAgentSessionId?(): string;
+    /** Available on hosts that expose revision facts; required by future commit APIs. */
+    getRevision?: () => SessionRevisionV1;
+    /** Optional immutable context projection for operation-scoped Agent hosts. */
+    getContextSnapshot?: <TValue = unknown>() => AgentContextSnapshotV1<TValue>;
+    /** Optional revision-checked context commit for operation-scoped Agent hosts. */
+    commitContext?: <TValue = unknown>(request: AgentContextCommitRequestV1<TValue>) => Promise<AgentContextCommitResultV1<TValue>>;
+    getMessages(): readonly unknown[];
+    isIdle(): boolean;
+    prompt(text: string): Promise<PromptOutcome>;
+    /** Queue a steering message when the host session is running. */
+    steer?(text: string): Promise<void>;
+    /** Experimental: queue a follow-up message that waits for the active run instead of interrupting it. */
+    queueFollowUp?(text: string): Promise<void>;
+    abort(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    /** Current active (prompt-visible) tool names. Available on hosts that expose the tool registry. */
+    getActiveTools?(): string[];
+    /** Replace the active tool set by name; names not in the registry are ignored. */
+    setActiveTools?(toolNames: string[]): void;
+    /** Experimental (R3 tool-enumeration slice): all configured tools with name, description, parameter schema, prompt guidelines, and source metadata. */
+    getAllTools?(): readonly ToolInfoViewV1[];
+    /**
+     * Registers a GENERIC entry projection on the underlying session
+     * (see {@link EntryProjection}). Optional: hosts without session-entry
+     * projection support reject the registration with a visible error.
+     * Returns a disposer that removes the projection.
+     */
+    registerEntryProjection?(projection: EntryProjection): () => void;
+    /** Experimental (R3 tool-enumeration slice): slash command enumeration across extension, prompt-template, and skill sources. */
+    getCommands?(): readonly CommandInfoViewV1[];
+    /** Experimental (R3 model-domain slice): provider-agnostic facts about the current session model. */
+    getModel?(): ModelFactsViewV1 | undefined;
+    /** Experimental (R3 model-domain slice): scoped model facts with their explicit thinking levels. */
+    getScopedModels?(): readonly ScopedModelFactsViewV1[];
+    /** Experimental (R3 model-domain slice): current thinking level. */
+    getThinkingLevel?(): ThinkingLevel;
+    /** Experimental (R3 model-domain slice): set the thinking level. */
+    setThinkingLevel?(level: ThinkingLevel): void;
+    /** Experimental (R3 model-domain slice): set the session model by id (resolved against the scoped models). Resolves to false when the id is unknown or auth is not configured. */
+    setModel?(modelId: string): Promise<boolean>;
+    /** Experimental (R3 prompt-facts slice): the current system prompt. */
+    getSystemPrompt?(): string;
+    /** Experimental (R3 prompt-facts slice): the system prompt assembly options. */
+    getSystemPromptOptions?(): BuildSystemPromptOptions;
+    /** Experimental (context-facts slice): estimated usage of the current context; undefined when the host cannot measure it. */
+    getContextUsage?(): ContextUsage | undefined;
+    /**
+     * Experimental: inject a custom message into the session. Verbatim passthrough of
+     * AgentSession.sendCustomMessage (without deliverAs): streamed hosts steer with it,
+     * idle hosts append it, and `options.triggerTurn` starts a new turn.
+     */
+    sendMessage?(message: {
+        customType: string;
+        content: SessionMessageContent;
+        display: boolean;
+    }, options?: {
+        triggerTurn?: boolean;
+    }): Promise<void>;
+    compact?(customInstructions?: string): Promise<unknown>;
+    navigateTree?(targetId: string, options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+        replaceInstructions?: boolean;
+        label?: string;
+    }): Promise<unknown>;
+    appendEntry(customType: string, data?: unknown): string;
+    /** Experimental (R3 session-metadata slice): renames the session. Delegates to AgentSession.setSessionName. */
+    setSessionName?(name: string): void;
+    /** Experimental (R3 session-metadata slice): current session display name. */
+    getSessionName?(): string | undefined;
+    /** Experimental (R3 session-metadata slice): appends a label-change entry; returns the new entry id. Mirrors facade appendLabelChange. */
+    setLabel?(entryId: string, label: string | undefined): string;
+    /** Experimental (R3 session-metadata slice): current label of the branch entry. */
+    getLabel?(entryId: string): string | undefined;
+    getBranchEntries(): readonly SessionEntryView[];
+    /** Available when the host declares the `session-export` feature. */
+    exportArtifact?(request: SessionExportRequest): SessionExportArtifact;
+}
+/** A session view scoped to one AgentInstance execution. */
+export interface AgentSessionFacadeV1 {
+    readonly version: 1;
+    getSessionId(): string;
+    getRevision?(): SessionRevisionV1;
+    getMessages(): readonly unknown[];
+    getBranchEntries(): readonly SessionEntryView[];
+    isIdle(): boolean;
+    prompt?(text: string): Promise<PromptOutcome>;
+    /** Queue a steering message when the host session is running. */
+    steer?(text: string): Promise<void>;
+    abort?(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    appendEntry(customType: string, data?: unknown): string;
+}
+/** Immutable context value returned by an Agent host. */
+export interface AgentContextSnapshotV1<TValue = unknown> {
+    readonly version: 1;
+    readonly revision: number;
+    readonly value: TValue;
+}
+export interface AgentContextCommitRequestV1<TValue = unknown> {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly expectedRevision: number;
+    readonly value: TValue;
+    signal?: AbortSignal;
+}
+export interface AgentContextCommitResultV1<TValue = unknown> {
+    readonly version: 1;
+    readonly status: "committed" | "replayed";
+    readonly revision: number;
+    readonly value: TValue;
+}
+/** Per-instance context snapshot/commit boundary. */
+export interface AgentContextFacadeV1 {
+    readonly version: 1;
+    get<TValue = unknown>(): AgentContextSnapshotV1<TValue>;
+    commit<TValue = unknown>(request: AgentContextCommitRequestV1<TValue>): Promise<AgentContextCommitResultV1<TValue>>;
+}
+/** Operation facts and cancellation boundary visible to an AgentDefinition. */
+export interface AgentOperationFacadeV1 {
+    readonly version: 1;
+    readonly id: string;
+    readonly signal: AbortSignal;
+    status(): OperationStatus;
+    isActive(): boolean;
+    reportProgress(progress: OperationProgress): boolean;
+    onCancel(handler: (reason: unknown) => void | Promise<void>): DisposableRegistration;
+    cancel(reason?: string): Promise<void>;
+}
+/**
+ * Optional, host-injected primitives for one AgentDefinition execution.
+ * Implementations are scoped to the active operation and become revoked once
+ * that operation is cancelled, completes, or its controller lease is released.
+ */
+export interface AgentHostPrimitivesV1 {
+    readonly version: 1;
+    readonly session?: AgentSessionFacadeV1;
+    readonly context?: AgentContextFacadeV1;
+    readonly state?: StateAPI;
+    /**
+     * Instance-private StateAPI view for this Agent instance execution only.
+     * Same shape and semantics as `state` (CAS, detached snapshots, watchers),
+     * but scoped to `owner + instanceId`: invisible to sibling instances and to
+     * the owner namespace. Runtime-memory scoped; cleared on instance dispose;
+     * not restored on rebuild.
+     */
+    readonly instanceState?: StateAPI;
+    readonly artifact?: OutputArtifactAPI;
+    readonly operation?: AgentOperationFacadeV1;
+    /** Agent-only host model binding. */
+    readonly model?: AgentModelFacadeV1;
+    /** Agent-only host tool binding. */
+    readonly tool?: AgentToolFacadeV1;
+}
+/**
+ * Model facts and invoke surface bound to one Agent instance execution.
+ *
+ * `facts` carries provider-agnostic model metadata; `invocation` is a
+ * single-shot completion boundary — the host resolves auth, transport and
+ * cache routing, and provider internals never cross to the plugin. Each
+ * invoke is exactly one completion without tools or session state.
+ */
+export interface AgentModelFacadeV1 {
+    readonly version: 1;
+    /** Provider-agnostic facts about the current session model. */
+    readonly facts: AgentModelFactsV1;
+    /** Single-shot completion boundary. */
+    readonly invocation: AgentModelInvocationV1;
+}
+/** Provider-agnostic facts about the model the host will use for model calls. */
+export interface AgentModelFactsV1 {
+    readonly provider: string;
+    readonly id: string;
+    readonly contextWindow: number;
+    readonly maxTokens: number;
+    readonly reasoning: boolean;
+}
+export interface AgentModelInvocationRequestV1 {
+    readonly version: 1;
+    readonly systemPrompt?: string;
+    readonly prompt: string;
+    readonly maxTokens?: number;
+    readonly thinkingLevel?: ThinkingLevel;
+}
+export type AgentModelInvocationResultV1 = {
+    readonly version: 1;
+    readonly status: "completed";
+    readonly text: string;
+    readonly usage?: unknown;
+} | {
+    readonly version: 1;
+    readonly status: "aborted";
+} | {
+    readonly version: 1;
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface AgentModelInvocationV1 {
+    readonly invoke: (input: AgentModelInvocationRequestV1, signal: AbortSignal) => Promise<AgentModelInvocationResultV1>;
+}
+/**
+ * Tool invocation surface bound to one Agent instance execution. The plugin
+ * can list and invoke tools registered in the CapabilityRuntime without
+ * importing internal execution paths.
+ */
+export interface AgentToolFacadeV1 {
+    readonly version: 1;
+    /** Tool definitions keyed by name (definition + source per tool). */
+    readonly listTools: () => readonly {
+        readonly name: string;
+        readonly definition: unknown;
+        readonly source: string;
+        /** Owning-plugin readonly-mode declaration (宪法 §6), read off the definition. */
+        readonly readonlySafe: boolean;
+    }[];
+    /** Invoke a registered tool by name. */
+    invokeTool: (name: string, input: unknown, options?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<unknown>;
+}
+export interface AgentHostPrimitivesFactoryContext {
+    readonly instance: AgentInstanceSnapshot;
+    readonly operationId: string;
+    readonly signal: AbortSignal;
+    readonly leaseOwner: string;
+}
+export type AgentHostPrimitivesFactory = (context: AgentHostPrimitivesFactoryContext) => AgentHostPrimitivesV1 | undefined | Promise<AgentHostPrimitivesV1 | undefined>;
+/**
+ * A slash command declared by a capability plugin. Names omit the leading
+ * slash so every host can render and route the same command metadata.
+ */
+export interface CapabilityCommandDefinition {
+    name: string;
+    description: string;
+    argumentHint?: string;
+    execute(args: string, context: CapabilityCommandContext): CapabilityCommandResult | undefined | Promise<CapabilityCommandResult | undefined>;
+}
+export interface CapabilityCommandContext {
+    signal: AbortSignal;
+    /** Experimental: the session working directory, for commands that need cwd facts. */
+    cwd?: string;
+}
+/**
+ * Experimental: second argument the runtime invoke face passes to a capability
+ * tool's execute (additive; existing single-parameter tools are unaffected).
+ * The host injects the session working directory through
+ * CapabilityRuntimeOptions.toolExecutionContext; without that injection the
+ * argument stays undefined. Mirrors CapabilityCommandContext.cwd.
+ */
+export interface CapabilityToolContext {
+    /** Experimental: the session working directory, mirroring CapabilityCommandContext.cwd. */
+    cwd?: string;
+}
+export interface CapabilityCommandLink {
+    label: string;
+    url: string;
+}
+/** Host-independent, serializable result returned by a capability command. */
+export interface CapabilityCommandResult {
+    status: "success" | "error";
+    message: string;
+    links?: readonly CapabilityCommandLink[];
+    data?: PluginConfigValue;
+}
+export type AgentTaskStatus = "created" | "running" | "succeeded" | "failed" | "cancelled";
+export interface AgentTaskCreateRequest {
+    prompt: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 子任务档案（child task profile）——版本化的公共契约，经
+ * `AgentTaskCreateRequest.metadata[AGENT_TASK_CHILD_PROFILE_KEY]` 传递。
+ *
+ * 用途：调用方（如子代理角色）要求宿主在**创建子会话时**收窄它的模型 / 思考级别 /
+ * 工具面 / 会话模式，或给子会话追加一段系统提示词。所有字段都是"收窄"语义：工具面只会
+ * 被裁到更小（与宿主自身继承面求交），模式只能更严（`readonly` 不会被放宽）。
+ *
+ * 契约义务（宿主 adapter 侧）：
+ * - 支持的宿主必须落地这些字段，并在 `AgentTaskHandle.session` 上暴露可核验事实
+ *   （`getActiveTools` / `getModel`）——调用方据此确认"要求已生效"，而不是相信约定；
+ * - 不支持的宿主**不得静默忽略**：应让 `create` 失败（结构化错误指名字段），因为静默
+ *   忽略会让上层的"只读评审者"变成一句空话。
+ */
+export declare const AGENT_TASK_CHILD_PROFILE_KEY: "agent-forge.agentTaskChildProfile";
+/**
+ * metadata 键：发起 create 的**父 agent 会话 id**（D-060 S1 血缘）。宿主把它写进子会话文件头
+ * 的 `parentAgentSession`，池化下随协议 `create` 过线；读取方据此做父作用域校验与按父反查。
+ */
+export declare const AGENT_TASK_PARENT_SESSION_KEY: "agent-forge.agentTaskParentSession";
+/**
+ * metadata 键：创建子会话的父回合 correlationId（第 3 期第二批，委派提交时刻捕获）。
+ * 契约义务（宿主 adapter 侧）：**仅 create 新建子会话消费**——宿主 adapter 读取该键并传入
+ * `NewSessionOptions.parentTraceId`；resume 打开既有会话不适用（`SessionHeader.parentTraceId`
+ * 随头定格，不重写）。shared 模式 embedder adapter 不读取时行为安全降级（子轨迹缺
+ * parentTraceId，无回归）。
+ */
+export declare const AGENT_TASK_PARENT_TRACE_KEY: "agent-forge.agentTaskParentTrace";
+/**
+ * metadata 键：resume 目标的子会话 id（D-060 S4）。宿主据此**打开既有会话文件**继续跑
+ * （同一份 JSONL 续写，形成多轮子任务），而不是新建会话。宿主必须核验文件头
+ * `parentAgentSession` 等于发起方父会话 id，否则结构化拒绝——越界与不存在同型。
+ */
+export declare const AGENT_TASK_RESUME_SESSION_KEY: "agent-forge.agentTaskResumeSession";
+export interface AgentTaskChildProfileV1 {
+    readonly version: 1;
+    /** 目标模型 id：必须能在父会话的 scoped models 里解析，否则 create 失败并列出可用 id。 */
+    readonly model?: string;
+    /** 思考级别（minimal/low/medium/high/xhigh/max）；越界值 create 失败。 */
+    readonly thinkingLevel?: string;
+    /** 工具面白名单：与宿主继承面求交；空数组表示"一个工具都不给"。 */
+    readonly tools?: readonly string[];
+    /** 会话模式：`readonly` 只收窄不放宽（父会话已是 readonly 时保持 readonly）。 */
+    readonly mode?: "readonly" | "full-control";
+    /** 追加到子会话 system prompt 末尾的文本（不替换继承来的系统提示词）。 */
+    readonly systemPromptAppend?: string;
+    /**
+     * 创建该子会话的角色 id（血缘/审计用途，写进子会话文件头；**不是权限判据**，也不参与收窄）。
+     * 由子代理能力从角色定义注入；手工构造档案的调用方可以省略。
+     */
+    readonly roleId?: string;
+}
+/** 档案解析结果：合法则给出规范化副本，否则给出可直接回给调用方的原因。 */
+export type AgentTaskChildProfileParseResultV1 = {
+    readonly ok: true;
+    readonly profile: AgentTaskChildProfileV1;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * 解析并校验一份子任务档案：类型/取值范围/未知键都在这里拦下，错误文本指名键，
+ * 由调用方决定是本地失败还是回给上层（子代理能力把它变成条目级 rejected）。
+ */
+export declare function parseAgentTaskChildProfileV1(value: unknown): AgentTaskChildProfileParseResultV1;
+/** 便捷读取：从 metadata 里取出并校验档案；undefined 表示没带档案。 */
+export declare function readAgentTaskChildProfileV1(metadata: Record<string, unknown> | undefined): AgentTaskChildProfileParseResultV1 | undefined;
+export interface AgentTaskWaitResult {
+    sessionId: string;
+    messages: readonly unknown[];
+}
+/** Frozen terminal outcome of an agent task; the replay read survives dispose. */
+export interface AgentTaskResultV1 {
+    readonly taskId: string;
+    readonly parentSessionId: string;
+    /** Terminal only: succeeded | failed | cancelled. */
+    readonly status: AgentTaskStatus;
+    readonly sessionId: string;
+    readonly messages: readonly unknown[];
+}
+export interface AgentTaskHandle {
+    readonly id: string;
+    readonly parentSessionId: string;
+    readonly session: SessionAPI;
+    status(): AgentTaskStatus;
+    run(): Promise<void>;
+    wait(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentTaskWaitResult>;
+    /**
+     * Terminal replay read: undefined until the task settles; afterwards the
+     * frozen terminal outcome, even after dispose (no liveness assertion).
+     */
+    result(): AgentTaskResultV1 | undefined;
+    cancel(reason?: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Host adapter for isolated child sessions. It contains lifecycle mechanics, not scheduling policy. */
+export interface AgentTaskHost {
+    readonly session: SessionAPI;
+    run(prompt: string, signal: AbortSignal): Promise<void>;
+    cancel(reason?: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface AgentTaskAdapter {
+    create(request: AgentTaskCreateRequest): Promise<AgentTaskHost>;
+    dispose?(): Promise<void>;
+}
+/** 会话回读视图（D-060）：按 sessionId 读到的有界 transcript 片段。 */
+export interface AgentTaskSessionViewV1 {
+    readonly sessionId: string;
+    /** 血缘：父 agent 会话 id（子会话必有）。 */
+    readonly parentAgentSession?: string;
+    /** 血缘：创建该会话的角色 id（审计用途）。 */
+    readonly agentRole?: string;
+    readonly createdAt?: string;
+    /** 整份 transcript 的字节数（不是返回片段的）。 */
+    readonly bytes: number;
+    /** 返回的消息/entry 条数；`truncated` 为真时是已返回的条数。 */
+    readonly entryCount: number;
+    /** 达到返回上限、只给了前段时为 true。 */
+    readonly truncated: boolean;
+    readonly entries: readonly unknown[];
+}
+export interface AgentTaskAPI {
+    /**
+     * 创建子任务（宿主 adapter 驱动）。宿主只注入会话回读面（无任务 adapter）时该
+     * 成员不存在——此时 agents 只承载 `session`/`list` 回读面，不承载委派。
+     */
+    create?(request: AgentTaskCreateRequest): Promise<AgentTaskHandle>;
+    /**
+     * Durable replay read by task id: loads the terminal record persisted at
+     * settle from the host-injected durable store. Undefined when the store is
+     * absent, the task has not settled, or no record exists under the id.
+     *
+     * The store is host-owned and shared per runtime: any plugin holding the
+     * agents capability can read any task's record by id, including tasks of
+     * other owners. Unlike the handle's in-memory `result()` (deep-frozen
+     * projection), records reloaded from the durable backend are reparsed plain
+     * objects and carry no freeze guarantee.
+     */
+    /**
+     * Durable replay read（宿主 adapter 驱动）。宿主只注入会话回读面（无任务 adapter）
+     * 时该成员不存在。
+     */
+    result?(taskId: string): Promise<AgentTaskResultV1 | undefined>;
+    /**
+     * 父→子引导（D-060 S4，程序面）：对**运行中**的任务投递一条有界引导消息
+     * （≤2048 utf-8 字节，复用子会话自身 steer 语义，不新增队列）。只在发起方
+     * runtime 的活跃任务里定位：未启动/已终态的按 `subagent_not_running`、宿主
+     * 会话无 steer 面按 `subagent_steer_unsupported`、未知 id 按
+     * `subagent_unknown_task` 以带 code 的错误拒绝。父回合不被打断。
+     * runtime 桥接总是提供；宿主适配器自身无需实现。
+     */
+    steer?(request: {
+        readonly taskId: string;
+        readonly text: string;
+    }): Promise<void>;
+    /**
+     * 按 `sessionId` 回读子会话 transcript（有界）。宿主未注入会话读取器时该成员不存在；
+     * 作用域由宿主强制（默认宿主只放行本会话自己的子会话），越界与不存在同型返回 undefined。
+     */
+    session?(sessionId: string): Promise<AgentTaskSessionViewV1 | undefined>;
+    /**
+     * 列出本会话**自己的**子代理会话摘要（按最近活动倒序，D-060 模型面盘点通道）。
+     * 宿主未注入列举器时该成员不存在；作用域由宿主强制（只回本会话的子会话），
+     * 摘要不含消息正文。跨进程重启仍可列出（读的是落盘目录，不是内存）。
+     */
+    list?(): Promise<AgentTaskSessionSummaryV1[]>;
+}
+/**
+ * 子代理会话摘要（`agents.list()` 的条目）：只读头行信息，不含消息正文。
+ * `modifiedAt` 为最后活动时间（epoch 毫秒），按它倒序返回。
+ */
+export interface AgentTaskSessionSummaryV1 {
+    readonly sessionId: string;
+    /** 血缘：创建该会话的角色 id（审计用途）。 */
+    readonly agentRole?: string;
+    readonly createdAt?: string;
+    readonly modifiedAt: number;
+    /** 整份 transcript 的字节数。 */
+    readonly bytes: number;
+}
+export type InteractionNotifyLevel = "info" | "warning" | "error";
+export type InteractionRequestV1 = {
+    kind: "notify";
+    message: string;
+    level?: InteractionNotifyLevel;
+} | {
+    kind: "confirm";
+    title: string;
+    message: string;
+} | {
+    kind: "select";
+    title: string;
+    options: readonly string[];
+}
+/** `placeholder` and `defaultValue` are part of the frozen wire shape, but current TUI/RPC hosts have no prefill support and silently ignore both (plain free-text input only). */
+ | {
+    kind: "input";
+    title: string;
+    placeholder?: string;
+    defaultValue?: string;
+};
+/**
+ * Outcome production conditions (frozen 1A.8 semantics):
+ * - `delivered` — notify prompts only; the host accepted the fire-and-forget
+ *   notification.
+ * - `answered` — the user completed a confirm/select/input prompt.
+ * - `cancelled` — the user dismissed the prompt, `options.signal` aborted, or
+ *   the plugin's registration was disposed. Never produced by `timeoutMs`.
+ * - `timeout` — `options.timeoutMs` elapsed before settlement; only that
+ *   source produces it.
+ * - `unavailable` — the host's prompt implementation failed (including hosts
+ *   without an installed interaction UI settling "unavailable").
+ *
+ * The wrapper validates host-resolved outcomes against these conditions: an
+ * unknown status, a missing/invalid `answered` value, extra fields, a
+ * host-produced `timeout`, or a `delivered` outside a notify request makes
+ * request() reject instead of handing a malformed outcome to the plugin.
+ */
+export type InteractionOutcomeV1 = {
+    status: "delivered";
+} | {
+    status: "answered";
+    value: boolean | string;
+} | {
+    status: "cancelled";
+} | {
+    status: "timeout";
+} | {
+    status: "unavailable";
+};
+export interface InteractionPromptContextV1 {
+    readonly signal: AbortSignal;
+}
+/** Host-side implementation. Hosts MUST honor prompt ctx.signal and settle promptly when aborted. */
+/** Options for extension UI dialogs. */
+export interface InteractionDialogOptions {
+    /** AbortSignal to programmatically dismiss the dialog. */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds. Dialog auto-dismisses with live countdown display. */
+    timeout?: number;
+}
+export interface InteractionHostV1 {
+    notify(request: {
+        message: string;
+        level?: InteractionNotifyLevel;
+    }): void;
+    prompt(request: InteractionRequestV1, context: InteractionPromptContextV1): Promise<InteractionOutcomeV1>;
+    /**
+     * Implementations must be idempotent; the session dispose path and the
+     * per-plugin registration may each invoke it.
+     */
+    dispose?(): void | Promise<void>;
+}
+export interface InteractionAPI {
+    /**
+     * Fire-and-forget notification; mirrors the legacy sync void semantics.
+     * Info-level notifications surface as transient host state (a later status
+     * update may overwrite them) and persistent display is not guaranteed;
+     * plugins that need a persistent notice should render their own durable UI.
+     */
+    notify(request: {
+        message: string;
+        level?: InteractionNotifyLevel;
+    }): void;
+    /**
+     * Cancellable interaction task. Resolves with a structured outcome (see
+     * {@link InteractionOutcomeV1} for the per-outcome production conditions);
+     * user dismissal yields "cancelled", never a rejection. Rejections only for
+     * invalid input (thrown synchronously), a revoked API, or a malformed host
+     * outcome. Cancellation is per request: `options.signal` and `timeoutMs`
+     * affect only this request, never concurrent requests of the same plugin.
+     */
+    request(request: InteractionRequestV1, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<InteractionOutcomeV1>;
+}
+/** Experimental, host-independent Agent composition contract. */
+export type AgentInstanceStatus = "created" | "running" | "succeeded" | "failed" | "cancelled" | "disposed";
+export type AgentControllerRole = PluginAgentRole;
+export interface AgentInstanceSnapshot {
+    readonly id: string;
+    readonly definitionId: string;
+    readonly definitionVersion: number;
+    readonly role: AgentControllerRole;
+    readonly parentInstanceId?: string;
+    readonly status: AgentInstanceStatus;
+    readonly revision: number;
+    readonly leaseOwner?: string;
+}
+export interface AgentExecutionContext {
+    readonly instance: AgentInstanceSnapshot;
+    readonly signal: AbortSignal;
+    readonly inputRevision: number;
+    /** Optional host primitives; absent when the host did not negotiate them. */
+    readonly host?: AgentHostPrimitivesV1;
+}
+export interface AgentDefinition<TInput = unknown, TResult = unknown> {
+    readonly id: string;
+    readonly version: number;
+    readonly role: AgentControllerRole;
+    readonly owner?: string;
+    run(input: TInput, context: AgentExecutionContext): TResult | Promise<TResult>;
+}
+export interface AgentControllerLease {
+    readonly id: string;
+    readonly instanceId: string;
+    readonly owner: string;
+    readonly revision: number;
+    isActive(): boolean;
+    release(): Promise<void>;
+}
+export interface AgentInstanceResult<TResult = unknown> {
+    readonly status: "succeeded" | "failed" | "cancelled" | "disposed";
+    readonly output?: TResult;
+    readonly error?: unknown;
+    readonly revision: number;
+}
+export interface AgentInstance<TInput = unknown, TResult = unknown> {
+    readonly id: string;
+    readonly definition: AgentDefinition<TInput, TResult>;
+    snapshot(): AgentInstanceSnapshot;
+    acquireControllerLease(owner?: string): Promise<AgentControllerLease>;
+    run(input: TInput, options?: {
+        lease?: AgentControllerLease;
+        signal?: AbortSignal;
+    }): OperationHandle<TResult>;
+    wait(): Promise<AgentInstanceResult<TResult>>;
+    cancel(reason?: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface AgentCompositionAPI {
+    define<TInput = unknown, TResult = unknown>(definition: AgentDefinition<TInput, TResult>): AgentDefinition<TInput, TResult>;
+    get<TInput = unknown, TResult = unknown>(id: string, version: number): AgentDefinition<TInput, TResult>;
+    create<TInput = unknown, TResult = unknown>(definition: AgentDefinition<TInput, TResult> | {
+        id: string;
+        version: number;
+    }, options?: {
+        id?: string;
+        parentInstanceId?: string;
+    }): AgentInstance<TInput, TResult>;
+    listInstances(): readonly AgentInstanceSnapshot[];
+}
+/** Optional host binding implemented by the built-in composition runtime. */
+export interface AgentCompositionHostBinding {
+    setHostPrimitivesFactory(factory?: AgentHostPrimitivesFactory): void;
+}
+/** Optional owner-scoped cleanup implemented by the built-in composition runtime. */
+export interface AgentCompositionDefinitionBinding {
+    disposeDefinitions(definitions: readonly AgentDefinition[]): void;
+}
+/**
+ * Optional host-only binding for the built-in composition runtime. It lets a
+ * CapabilityRuntime add owner-scoped primitives without exposing that control
+ * to capability plugins.
+ */
+export interface AgentCompositionScopedHostBinding {
+    createWithHostPrimitives<TInput = unknown, TResult = unknown>(definition: AgentDefinition<TInput, TResult> | {
+        id: string;
+        version: number;
+    }, options: {
+        id?: string;
+        parentInstanceId?: string;
+    } | undefined, hostPrimitivesFactory: AgentHostPrimitivesFactory): AgentInstance<TInput, TResult>;
+}
+export interface ContextStrategy<TContext = unknown, TSnapshot = unknown> {
+    transform(context: TContext, options?: ContextOperationOptions): TContext | Promise<TContext>;
+    snapshot?(context: TContext, options?: ContextOperationOptions): TSnapshot | Promise<TSnapshot>;
+    restore?(snapshot: TSnapshot, options?: ContextOperationOptions): TContext | Promise<TContext>;
+    replace?(context: TContext, options?: ContextOperationOptions): TContext | Promise<TContext>;
+}
+export interface ContextOperationOptions {
+    signal?: AbortSignal;
+    reason?: "request" | "reload" | "session_replace" | "compaction" | "overflow_recovery" | "retry" | "tree";
+    sessionId?: string;
+}
+/**
+ * Generic transform over the projected session entry list, registered per
+ * session. The kernel applies registered projections verbatim; semantics
+ * belong to the registering plugin.
+ */
+export interface EntryProjection {
+    /** The plugin-owned custom entry type this projection is associated with. */
+    readonly customType: string;
+    readonly project: (entries: readonly unknown[]) => readonly unknown[];
+}
+export interface SkillDefinition {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    disableModelInvocation?: boolean;
+}
+/** Versioned, provider-agnostic facts shared by replaceable policy calls. */
+export interface PolicyInvocationContextV1 {
+    version: 1;
+    sessionId: string;
+    phase: "agent" | "compaction" | "overflow" | "retry" | "branch_summary";
+    operationId?: string;
+}
+export interface RetryPolicyRequest {
+    signal?: AbortSignal;
+    retryable: boolean;
+    enabled: boolean;
+    attempt: number;
+    maxAttempts: number;
+    baseDelayMs: number;
+    errorMessage?: string;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface RetryClassificationRequest {
+    signal?: AbortSignal;
+    message: unknown;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface RetryPolicyDecision {
+    retry: boolean;
+    delayMs?: number;
+}
+export interface RetryPolicy {
+    classify?(request: RetryClassificationRequest): boolean | Promise<boolean>;
+    decide(request: RetryPolicyRequest): RetryPolicyDecision | Promise<RetryPolicyDecision>;
+}
+export interface CompactionPolicyRequest {
+    signal?: AbortSignal;
+    enabled: boolean;
+    reason: "overflow" | "threshold";
+    contextOverflow: boolean;
+    recoverableLength: boolean;
+    /** Facts measured by the host; the policy owns the threshold decision. */
+    contextUsage?: CompactionContextUsage;
+    recoveryAttempted: boolean;
+    canContinue: boolean;
+    /**
+     * Branch path entry snapshot (threshold requests only). Provided so a
+     * policy can plan CHEAP RELIEF (see {@link CompactionPolicyDecision.relief})
+     * from real history facts instead of ordering a summarization run.
+     */
+    branchEntries?: readonly unknown[];
+    /** Recent-tail protection budget (settings fact) for relief planning. */
+    keepRecentTokens?: number;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface CompactionContextUsage {
+    contextTokens: number;
+    contextWindow: number;
+    reserveTokens: number;
+}
+export interface CompactionPreparationRequest {
+    signal?: AbortSignal;
+    entries: unknown;
+    settings: unknown;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface CompactionPolicyDecision {
+    compact: boolean;
+    retry?: boolean;
+    failureMessage?: string;
+    /**
+     * Cheap RELIEF plan: the host appends this custom entry (generic
+     * `appendCustomEntry`) and reprojects the context instead of running a
+     * summarization. The semantics of the entry belong entirely to the policy;
+     * the projection that interprets it is registered separately via
+     * {@link CapabilityAPI.registerEntryProjection}. When relief is present the
+     * host skips compaction, so `compact` must be false.
+     */
+    relief?: {
+        readonly customType: string;
+        readonly data?: unknown;
+    };
+}
+/** Provider-agnostic facts about the model the host will use for a summary call. */
+export interface SummaryModelFactsV1 {
+    readonly id: string;
+    readonly contextWindow: number;
+    readonly maxTokens: number;
+    readonly reasoning: boolean;
+}
+/**
+ * Host-owned, provider-agnostic single-shot completion boundary for summary
+ * policies. The host resolves the model, auth, transport, retry budget and
+ * cache routing; provider internals never cross to the plugin. Each invoke is
+ * exactly one completion without tools or session state, and never writes the
+ * prompt cache. A plugin that can read these types can implement a summary
+ * strategy without importing provider internals.
+ */
+export interface SummaryModelInvocationV1 {
+    readonly invoke: (input: SummaryModelInvocationRequestV1, signal: AbortSignal) => Promise<SummaryModelInvocationResultV1>;
+}
+/** One host-mediated summary completion request. */
+export interface SummaryModelInvocationRequestV1 {
+    readonly version: 1;
+    readonly systemPrompt?: string;
+    readonly prompt: string;
+    /** Requested output budget; the host clamps it to the summary model cap. */
+    readonly maxTokens?: number;
+    readonly thinkingLevel?: ThinkingLevel;
+}
+/** Stable failure codes reported through {@link SummaryModelInvocationResultV1} errors. */
+export declare const SUMMARY_MODEL_INVOCATION_ERROR_CODES: {
+    /** Provider returned an error stop; `message` mirrors the provider error text. */
+    readonly providerError: "summary_provider_error";
+    /** Generation hit the requested output cap and the summary is incomplete. */
+    readonly lengthCap: "summary_length_cap";
+    /** The model attempted a tool call in a tool-less completion. */
+    readonly toolCall: "summary_tool_call";
+    /** The transport threw; `message` mirrors the original error text. */
+    readonly transportError: "summary_transport_error";
+};
+/**
+ * One host-mediated summary completion outcome, as a discriminated union:
+ * `completed` always carries text, `failed` always carries structured error
+ * facts whose `code` is one of {@link SUMMARY_MODEL_INVOCATION_ERROR_CODES}.
+ */
+export type SummaryModelInvocationResultV1 = {
+    readonly version: 1;
+    readonly status: "completed";
+    readonly text: string;
+    readonly usage?: unknown;
+} | {
+    readonly version: 1;
+    readonly status: "aborted";
+} | {
+    readonly version: 1;
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface CompactionSummaryRequest {
+    preparation: unknown;
+    model: SummaryModelFactsV1;
+    invocation: SummaryModelInvocationV1;
+    customInstructions?: string;
+    signal: AbortSignal;
+    reason: "manual" | "threshold" | "overflow";
+    thinkingLevel?: ThinkingLevel;
+    sessionId?: string;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface CompactionSummaryResult {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    usage?: unknown;
+    details?: unknown;
+}
+export interface CompactionPolicy {
+    prepare?(request: CompactionPreparationRequest): unknown | Promise<unknown>;
+    decide(request: CompactionPolicyRequest): CompactionPolicyDecision | Promise<CompactionPolicyDecision>;
+    summarize?(request: CompactionSummaryRequest): CompactionSummaryResult | Promise<CompactionSummaryResult>;
+}
+/** Provider-agnostic overflow classification supplied by a capability plugin. */
+export interface OverflowPolicyRequest {
+    signal?: AbortSignal;
+    message: unknown;
+    contextWindow?: number;
+    desiredMaxOutput: number;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface OverflowPolicyDecision {
+    contextOverflow: boolean;
+    recoverableLength: boolean;
+}
+export interface OverflowPolicy {
+    decide(request: OverflowPolicyRequest): OverflowPolicyDecision | Promise<OverflowPolicyDecision>;
+}
+export interface BranchSummaryRequest {
+    entries: unknown;
+    model: SummaryModelFactsV1;
+    invocation: SummaryModelInvocationV1;
+    signal: AbortSignal;
+    customInstructions?: string;
+    replaceInstructions?: boolean;
+    reserveTokens?: number;
+    context?: PolicyInvocationContextV1;
+    execution?: ExecutionFactsV1;
+}
+export interface BranchSummaryResult {
+    summary?: string;
+    usage?: unknown;
+    readFiles?: string[];
+    modifiedFiles?: string[];
+    aborted?: boolean;
+    error?: string;
+}
+export interface BranchSummaryPolicy {
+    summarize(request: BranchSummaryRequest): BranchSummaryResult | Promise<BranchSummaryResult>;
+}
+/**
+ * Experimental provider request header boundary. `null` retains the provider
+ * header deletion semantics used by the host model runtime.
+ */
+export interface ProviderHeaderTransformRequest {
+    model: unknown;
+    sessionId?: string;
+    headers: Record<string, string | null>;
+}
+/**
+ * Experimental request-time hook for plugins that own provider header policy.
+ * Transforms run in registration order and receive the previous transform's
+ * result.
+ */
+export type ProviderHeaderTransform = (request: ProviderHeaderTransformRequest) => Record<string, string | null> | Promise<Record<string, string | null>>;
+/**
+ * Hook positions on the default agent loop. Links run in registration order
+ * after the host's legacy chain head.
+ */
+export type AgentLoopHookPositionV1 = "beforeInput" | "beforeToolCall" | "afterToolCall" | "transformContext" | "prepareNextTurn" | "shouldStopAfterTurn";
+/**
+ * One ordered link of the input gate chain (输入 gate，扩展位盘点 A3). Runs at
+ * prompt submission — before the input is accepted (`input.received@1` is the
+ * observe fact of an ACCEPTED input and never fires for blocked inputs) and
+ * before skill/template expansion. A `{ block: true, reason? }` result rejects
+ * the input: the session dispatches `input.gate.blocked@1` and the prompt call
+ * fails with the reason. A `{ text }` result rewrites the input for everything
+ * downstream (later gates, expansion, the turn). `undefined` keeps the input.
+ */
+export type AgentLoopBeforeInputHookV1 = (input: {
+    readonly text: string;
+    readonly source: string;
+    readonly signal?: AbortSignal;
+}) => Promise<AgentLoopBeforeInputOutputV1 | undefined>;
+export interface AgentLoopBeforeInputOutputV1 {
+    block?: boolean;
+    reason?: string;
+    text?: string;
+}
+export interface AgentLoopBeforeToolCallInputV1 {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * One ordered link of the default tool-call gating chain. Return
+ * `{ block: true, reason? }` to block, `{ args }` to replace the candidate
+ * arguments, or `undefined` to keep the input.
+ */
+export interface AgentLoopBeforeToolCallOutputV1 {
+    block?: boolean;
+    reason?: string;
+    args?: unknown;
+}
+export type AgentLoopBeforeToolCallHookV1 = (input: AgentLoopBeforeToolCallInputV1) => Promise<AgentLoopBeforeToolCallOutputV1 | undefined>;
+export interface AgentLoopAfterToolCallInputV1 {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    /** The result produced by the previous link, or the executed tool result for the first link. */
+    result: unknown;
+    isError: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * One ordered link of the post-execution chain. Return a partial tool-result
+ * override to rewrite the result, or `undefined` to keep the input.
+ */
+export type AgentLoopAfterToolCallHookV1 = (input: AgentLoopAfterToolCallInputV1) => Promise<unknown | undefined>;
+/**
+ * One ordered link of the request-time context transform chain. Receives and
+ * returns the message array; `undefined` keeps the input.
+ */
+export type AgentLoopTransformContextHookV1 = (messages: readonly unknown[], signal?: AbortSignal) => Promise<readonly unknown[] | undefined>;
+/**
+ * One ordered link of the next-turn preparation chain. Receives the turn
+ * snapshot, returns a revised snapshot or `undefined`.
+ */
+export type AgentLoopPrepareNextTurnHookV1 = (turn: unknown, signal?: AbortSignal) => Promise<unknown | undefined>;
+/**
+ * One ordered link of the post-turn stop chain. Receives the completed turn's
+ * stop context; return `true` to request stopping after the current turn. The
+ * host OR-composes the chain: the first link returning `true` stops the run
+ * without consulting later links.
+ *
+ * The stop context stays kernel-typed (`@agent-forge/agent-core`
+ * `ShouldStopAfterTurnContext`: its fields reference the provider message
+ * model, which must not cross into the SDK — D-075 S2). Hosts hand the same
+ * runtime object they hand the kernel callback; `context` is therefore typed
+ * `any` here so kernel-typed handlers remain assignable.
+ */
+export type AgentLoopShouldStopAfterTurnHookV1 = (context: any, signal?: AbortSignal) => boolean | Promise<boolean>;
+export type AgentLoopHookForV1<P extends AgentLoopHookPositionV1> = P extends "beforeInput" ? AgentLoopBeforeInputHookV1 : P extends "beforeToolCall" ? AgentLoopBeforeToolCallHookV1 : P extends "afterToolCall" ? AgentLoopAfterToolCallHookV1 : P extends "transformContext" ? AgentLoopTransformContextHookV1 : P extends "prepareNextTurn" ? AgentLoopPrepareNextTurnHookV1 : P extends "shouldStopAfterTurn" ? AgentLoopShouldStopAfterTurnHookV1 : never;
+export type AgentLoopHookHandlerV1 = AgentLoopBeforeInputHookV1 | AgentLoopBeforeToolCallHookV1 | AgentLoopAfterToolCallHookV1 | AgentLoopTransformContextHookV1 | AgentLoopPrepareNextTurnHookV1 | AgentLoopShouldStopAfterTurnHookV1;
+/**
+ * Post-run continuation facts for the default agent loop. The host evaluates
+ * its own candidate decision first; the strategy makes the final
+ * continue/stop call for the post-run loop.
+ */
+export interface AgentRunLoopStrategyRequestV1 {
+    /** The policy decision signal for the current prompt run. */
+    readonly signal?: AbortSignal;
+    /** The retry path fired: a retry was prepared and the host would continue into it. */
+    readonly willRetry: boolean;
+    /** The compaction path fired: compaction was prepared and the host would continue into it. */
+    readonly willCompact: boolean;
+    /** The agent still holds queued steering/follow-up messages. */
+    readonly queuedFollowUp: boolean;
+    /** The host's own continuation decision (the replaceable default behavior). */
+    readonly hostWillContinue: boolean;
+}
+export interface AgentRunLoopStrategyDecisionV1 {
+    readonly continueLoop: boolean;
+    readonly reason?: string;
+}
+/**
+ * Post-run continuation strategy for the default agent loop. The host proposes
+ * the continuation (retry, compaction, or queued input); the strategy may veto
+ * it per cycle. `continueLoop: true` without a host-proposed continuation is
+ * clamped to stop: the agent loop can only continue from pending retry,
+ * compaction, or queued input.
+ */
+export interface AgentRunLoopStrategyV1 {
+    decideNextCycle(request: AgentRunLoopStrategyRequestV1): AgentRunLoopStrategyDecisionV1 | Promise<AgentRunLoopStrategyDecisionV1>;
+}
+export interface CapabilityAPI {
+    readonly manifest: PluginManifest;
+    readonly host: HostCapabilities;
+    readonly config: PluginConfig;
+    readonly session?: SessionAPI;
+    /** Available when the host declares the `output-artifacts` feature. */
+    readonly output?: OutputArtifactAPI;
+    readonly credentials?: CredentialAPI;
+    readonly agents?: AgentTaskAPI;
+    /**
+     * 宿主会话取消栅栏（D-044 §4.2）：getter 形态，按调用时刻返回当前 epoch 的
+     * AbortSignal（用户中止/销毁会话时触发；epoch 刷新后旧信号不再影响新任务）。
+     * 宿主未注入 parentSignal 时为 undefined。插件编排（如 subagent delegate）用它级联取消。
+     */
+    sessionAbortSignal?: () => AbortSignal | undefined;
+    /** Available when the host declares `interaction` feature. */
+    readonly interaction?: InteractionAPI;
+    /** Available when the host declares `agent-composition-v1`. */
+    readonly composition?: AgentCompositionAPI;
+    /** Available when the host declares `logger-v1`. */
+    readonly logger?: LoggerAPI;
+    /** Available when the host declares `diagnostics-v1`. */
+    readonly diagnostics?: DiagnosticsAPI;
+    /** Available when the host declares `plugin-state-v1`. */
+    readonly state?: StateAPI;
+    /** Available when the host declares `runtime-inspector-v1`. */
+    readonly inspector?: RuntimeInspectorAPI;
+    /**
+     * Host trace adapter service (D-075 S4 second batch, observability host
+     * contract). Present when the host runs session trace collection; the
+     * first-party observability plugin binds it as its trace sink adapter.
+     * Optional probe: hosts without tracing (or third-party hosts) leave it
+     * undefined and the plugin stays trace-free.
+     */
+    readonly trace?: ObservabilityHostAdapterV1;
+    /**
+     * Trace-sink budget overrides accompanying {@link CapabilityAPI.trace}
+     * (host `traceOptions` face, design §6 control plane). Present only
+     * together with `trace`; omitted fields fall back to the plugin defaults.
+     */
+    readonly traceSinkOptions?: TraceSinkOptionsV1;
+    readonly contributions: ContributionAPI;
+    /** Draft host lifecycle event directory. */
+    readonly lifecycle: LifecycleAPI;
+    /** Draft plugin-to-plugin capability directory. */
+    readonly capabilities: CapabilityDirectoryAPI;
+    /**
+     * Register a tool. `definition` stays loosely typed (any `{ name, execute }`
+     * shape the host can normalize); when the host configures
+     * CapabilityRuntimeOptions.toolExecutionContext, `execute` receives a
+     * {@link CapabilityToolContext} as its second argument on the runtime invoke
+     * face. Re-registering an existing name replaces the current registration
+     * (last load wins) and it is restored when the replacing registration
+     * disposes. Experimental.
+     */
+    registerTool(definition: unknown): DisposableRegistration;
+    registerCommand(definition: CapabilityCommandDefinition): DisposableRegistration;
+    registerOperation(name: string, handler: (input: unknown, context: OperationExecutionContext) => unknown | Promise<unknown>): DisposableRegistration;
+    registerRpcMethod(name: string, handler: (input: unknown) => unknown | Promise<unknown>): DisposableRegistration;
+    registerContextStrategy(name: string, strategy: ContextStrategy): DisposableRegistration;
+    /**
+     * Registers a GENERIC entry projection for this session's context
+     * projection: `project` receives the projected session entry list and may
+     * replace entries. The kernel applies registered projections verbatim and
+     * knows nothing about their semantics — first-party and third-party plugins
+     * use the same channel for custom-entry-based context policies (e.g. a
+     * compaction policy eliding bulky old tool results). The returned disposer
+     * removes the projection.
+     */
+    registerEntryProjection(projection: EntryProjection): DisposableRegistration;
+    registerProviderHeaderTransform(name: string, transform: ProviderHeaderTransform): DisposableRegistration;
+    registerSkill(definition: SkillDefinition): DisposableRegistration;
+    registerRetryPolicy(name: string, policy: RetryPolicy): DisposableRegistration;
+    registerCompactionPolicy(name: string, policy: CompactionPolicy): DisposableRegistration;
+    registerOverflowPolicy(name: string, policy: OverflowPolicy): DisposableRegistration;
+    registerBranchSummaryPolicy(name: string, policy: BranchSummaryPolicy): DisposableRegistration;
+    registerLoopHook(position: "beforeInput", handler: AgentLoopBeforeInputHookV1): DisposableRegistration;
+    registerLoopHook(position: "beforeToolCall", handler: AgentLoopBeforeToolCallHookV1): DisposableRegistration;
+    registerLoopHook(position: "afterToolCall", handler: AgentLoopAfterToolCallHookV1): DisposableRegistration;
+    registerLoopHook(position: "transformContext", handler: AgentLoopTransformContextHookV1): DisposableRegistration;
+    registerLoopHook(position: "prepareNextTurn", handler: AgentLoopPrepareNextTurnHookV1): DisposableRegistration;
+    registerLoopHook(position: "shouldStopAfterTurn", handler: AgentLoopShouldStopAfterTurnHookV1): DisposableRegistration;
+    registerRunLoopStrategy(name: string, strategy: AgentRunLoopStrategyV1): DisposableRegistration;
+    subscribe<TEvent>(type: string, handler: (event: EventEnvelope<TEvent>) => void | Promise<void>): DisposableRegistration;
+    publish<TData>(event: Omit<EventEnvelope<TData>, "id" | "timestamp" | "source">): Promise<EventEnvelope<TData>>;
+    call<TResult = unknown>(operation: string, input: unknown, options?: {
+        signal?: AbortSignal;
+    }): OperationHandle<TResult>;
+}
+/** Resources owned by a capability plugin beyond runtime registrations. */
+export interface CapabilityPluginInstance {
+    dispose(): void | Promise<void>;
+}
+/** Resources returned by a synchronous embedded plugin factory. */
+export interface CapabilityPluginSyncInstance {
+    dispose(): void;
+}
+export type CapabilityPluginFactoryResult = void | CapabilityPluginInstance;
+export type CapabilityPluginFactory = (api: CapabilityAPI) => CapabilityPluginFactoryResult | Promise<CapabilityPluginFactoryResult>;
+export type CapabilityPluginSyncFactory = (api: CapabilityAPI) => void | CapabilityPluginSyncInstance;
+export declare function createDisposableRegistration(kind: string, dispose: () => void | Promise<void>, id: string): DisposableRegistration;
+export declare function createEventEnvelope<TData>(event: Omit<EventEnvelope<TData>, "id" | "timestamp">, options: {
+    id: string;
+    timestamp?: number;
+}): EventEnvelope<TData>;
+/**
+ * Detach a session value into a read-only projection: the value is deep-cloned
+ * via `structuredClone` and the clone is frozen recursively (ArrayBuffer views
+ * are cloned but not frozen). Lifecycle payload builders use this so handlers
+ * receive data that cannot be mutated in place and share no identity with live
+ * session state. Available to hosts and plugins alike through the public face;
+ * the default loop bootstrap uses it for tool-call inputs and tool-result
+ * content.
+ */
+export declare function detachedSessionSnapshot<T>(value: T): T;
+//# sourceMappingURL=public-api.d.ts.map