@kingsoftcloud/ksadk-web 0.3.1 → 0.3.3

package/dist-lib/core/conversation/renderer-registry.d.ts

@@ -0,0 +1,20 @@
+import type { ConversationItem, ConversationItemKind } from './types.js';
+/**
+ * A renderer declaration compiled into the trusted frontend bundle.
+ *
+ * This is deliberately an immutable catalog, not a runtime plugin API. A
+ * Provider may produce a schema only after the host frontend ships its
+ * matching renderer; Runtime payloads never supply executable renderer code.
+ */
+export type TrustedConversationRenderer = {
+    id: string;
+    schemaRef: string;
+    kinds: readonly ConversationItemKind[];
+};
+export type TrustedRendererCatalog = {
+    resolve(item: ConversationItem): TrustedConversationRenderer | undefined;
+    entries(): readonly TrustedConversationRenderer[];
+};
+/** Build and freeze the host's exact kind/schema dispatch table once. */
+export declare function createTrustedRendererCatalog(renderers: readonly TrustedConversationRenderer[]): TrustedRendererCatalog;
+//# sourceMappingURL=renderer-registry.d.ts.map

package/dist-lib/core/conversation/renderer-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-registry.d.ts","sourceRoot":"","sources":["../../../src/core/conversation/renderer-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,2BAA2B,GAAG,SAAS,CAAC;IACzE,OAAO,IAAI,SAAS,2BAA2B,EAAE,CAAC;CACnD,CAAC;AAMF,yEAAyE;AACzE,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,SAAS,2BAA2B,EAAE,GAChD,sBAAsB,CA0BxB"}

package/dist-lib/core/conversation/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Provider-neutral conversation presentation contracts.
+ *
+ * These types mirror the frozen `conversation.ksadk.io/v1` wire contracts.
+ * They contain no Studio state or provider-specific event names, so Hosted UI
+ * and custom frontends can share the same decoding and replay semantics.
+ */
+export type ConversationCapabilityMode = 'native' | 'translated' | 'degraded' | 'unavailable';
+export type ConversationCapability = {
+    name: string;
+    mode: ConversationCapabilityMode;
+    reason?: string | null;
+};
+export type ConversationSurface = {
+    apiVersion: 'conversation.ksadk.io/v1';
+    kind: 'ConversationSurface';
+    surfaceId: string;
+    sessionId: string;
+    providerRef: string;
+    inputs: ConversationCapability[];
+    outputs: ConversationCapability[];
+};
+export type ConversationTextPart = {
+    kind: 'text';
+    text: string;
+};
+export type ConversationAttachmentPart = {
+    kind: 'attachment';
+    attachmentRef: string;
+    mediaType: string;
+    name?: string | null;
+};
+export type ConversationInputPart = ConversationTextPart | ConversationAttachmentPart;
+export type ConversationInput = {
+    apiVersion: 'conversation.ksadk.io/v1';
+    kind: 'ConversationInput';
+    inputId: string;
+    sessionId: string;
+    idempotencyKey: string;
+    parts: ConversationInputPart[];
+    modelRef?: string | null;
+    reasoning?: string | null;
+    extensions?: Record<string, unknown>;
+};
+export type ConversationInputDraft = Omit<ConversationInput, 'apiVersion' | 'kind'> & {
+    apiVersion?: 'conversation.ksadk.io/v1';
+    kind?: 'ConversationInput';
+};
+export type ConversationSurfaceBootstrap = {
+    buildId: string;
+    surface: ConversationSurface;
+};
+export type ConversationItemKind = 'user_message' | 'assistant_text' | 'reasoning' | 'tool_call' | 'approval' | 'progress' | 'plan' | 'goal' | 'artifact' | 'a2ui' | 'error' | 'unknown';
+export type ConversationItemOperation = 'append' | 'replace' | 'completed';
+export type ConversationItemLifecycle = 'pending' | 'streaming' | 'completed' | 'failed';
+export type ConversationItemVisibility = 'public' | 'internal' | 'hidden';
+export type ConversationItem = {
+    apiVersion: 'conversation.ksadk.io/v1';
+    kindVersion: 1;
+    itemId: string;
+    parentItemId?: string | null;
+    sourceEventIds: string[];
+    sessionId: string;
+    runId: string;
+    kind: ConversationItemKind;
+    operation: ConversationItemOperation;
+    lifecycle: ConversationItemLifecycle;
+    visibility: ConversationItemVisibility;
+    payloadSchemaRef: string;
+    payload: Record<string, unknown>;
+    capabilityRef?: string | null;
+    nativeRef: Record<string, unknown>;
+};
+export type ConversationItemReducerState = {
+    /** Items remain in first-seen order. Equal text never collapses identities. */
+    items: ConversationItem[];
+    /** Serialized `(itemId, sourceEventId)` pairs used for reconnect replay. */
+    appliedSources: string[];
+};
+export type ConversationTextPresentation = {
+    id: string;
+    parentId: string | null;
+    runId: string;
+    kind: 'user_message' | 'assistant_text' | 'reasoning';
+    text: string;
+    lifecycle: ConversationItemLifecycle;
+};
+export type ConversationFallbackCard = {
+    id: string;
+    title: string;
+    detail: string;
+    failed: boolean;
+};
+export type ConversationArtifact = {
+    id: string;
+    name: string;
+    mimeType: string;
+    /** Only an absolute HTTP(S) URI without embedded credentials is clickable. */
+    uri: string | null;
+};
+/**
+ * One ordered renderer node. `key` is a presentation identity only: raw
+ * RuntimeEvent-derived items remain represented by `sourceItemIds` for replay
+ * and audit. A tool result may enrich the earlier tool-call node by callId.
+ */
+export type ConversationTimelineEntry = {
+    key: string;
+    item: ConversationItem;
+    sourceItemIds: string[];
+};
+/**
+ * Headless, renderer-ready data. This projection never executes item payloads
+ * and deliberately retains item identities for text and reasoning content.
+ */
+export type ConversationPresentation = {
+    /** Canonical visible order; renderers must not reconstruct it from groups. */
+    timeline: ConversationTimelineEntry[];
+    /**
+     * Compatibility summaries for consumers that have not yet moved to
+     * `timeline` / `textItems`. They never participate in identity reduction.
+     */
+    output: string;
+    reasoning: string;
+    textItems: ConversationTextPresentation[];
+    toolItems: ConversationItem[];
+    approvalItems: ConversationItem[];
+    structuredInputItems: ConversationItem[];
+    a2uiItems: ConversationItem[];
+    artifacts: ConversationArtifact[];
+    fallbacks: ConversationFallbackCard[];
+    runId: string;
+    terminalStatus?: 'completed' | 'failed';
+};
+export type ConversationProjectionOptions = {
+    /** Internal items are omitted from customer-facing surfaces by default. */
+    includeInternal?: boolean;
+};
+export type ConversationClientErrorCode = 'conversation_contract_mismatch' | 'conversation_input_unsupported' | 'conversation_session_mismatch' | 'conversation_http_error' | 'conversation_stream_error' | 'conversation_run_identity_missing' | 'conversation_reconnect_exhausted' | 'conversation_aborted';
+export type ConversationClientErrorDetails = {
+    status?: number;
+    capability?: string;
+    runId?: string;
+    cursor?: number;
+    cause?: unknown;
+};
+export type ConversationStreamResult = {
+    cursor: number;
+    runId: string;
+    state: ConversationItemReducerState;
+    presentation: ConversationPresentation;
+};
+export type ConversationStreamObserver = {
+    onItem?: (item: ConversationItem) => void;
+    onUpdate?: (result: ConversationStreamResult) => void;
+};
+export type ConversationFetch = (url: string, init?: RequestInit) => Promise<Response>;
+export type ConversationClientOptions = {
+    fetch?: ConversationFetch;
+    baseUrl?: string;
+    maxReconnects?: number;
+    sleep?: (delayMilliseconds: number) => Promise<void>;
+    retryDelayMs?: (attempt: number) => number;
+};
+export type ConversationStreamTurnOptions = ConversationStreamObserver & {
+    bootstrap: ConversationSurfaceBootstrap;
+    input: ConversationInput;
+    signal?: AbortSignal;
+};
+/** Minimal injectable transport used by Hosted UI and custom frontends. */
+export interface ConversationClient {
+    getSurface(agentId: string, sessionId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ConversationSurfaceBootstrap>;
+    streamTurn(options: ConversationStreamTurnOptions): Promise<ConversationStreamResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist-lib/core/conversation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/conversation/types.ts"],"names":[],"mappings":"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"}

package/dist-lib/core/interaction/a2ui-validate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A2UI v0.9.1 presentation validation with a safe fallback ladder.
+ *
+ * The production wire is locked to v0.9.1 with a pinned catalog digest.
+ * When the wire version or catalog digest does not match, the tray falls
+ * back to the canonical JSON schema form; when that is unsupported it
+ * falls back to plain approve/reject/text controls. A validation failure
+ * is never mapped to an approval.
+ */
+import type { A2uiPresentation } from './types.js';
+export declare const A2UI_WIRE_VERSION = "0.9.1";
+/** Deterministic digest of the local A2UI catalog. */
+export declare function computeA2uiCatalogDigest(catalog: unknown): string;
+export type A2uiRenderMode = 'a2ui' | 'json-schema-form' | 'basic-controls';
+/**
+ * Decide how an Interaction's presentation may render. Unknown components
+ * or a catalog mismatch never yield 'a2ui'; the safest usable fallback
+ * wins.
+ */
+export declare function validateA2uiPresentation(presentation: A2uiPresentation | null | undefined, localCatalog: unknown): A2uiRenderMode;
+//# sourceMappingURL=a2ui-validate.d.ts.map

package/dist-lib/core/interaction/a2ui-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2ui-validate.d.ts","sourceRoot":"","sources":["../../../src/core/interaction/a2ui-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAqBzC,sDAAsD;AACtD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAajE;AAED,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,kBAAkB,GAClB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EACjD,YAAY,EAAE,OAAO,GACpB,cAAc,CAiBhB"}

package/dist-lib/core/interaction/adapters/agui.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AG-UI transport adapter.
+ *
+ * Normalizes an AG-UI interrupt-driven approval request (RunEvent
+ * `approval_requested` with protocol `ag-ui`, or an AG-UI interrupt
+ * payload) into the shared Interaction shape. The original interrupt id
+ * is preserved in `extensions.interrupt_id` so the 0.3.1
+ * `resumeAguiInterrupt` fallback still works for servers that do not
+ * advertise `interaction_v1`.
+ */
+import type { Interaction } from '../types.js';
+export type AguiInterruptRequest = {
+    interruptId: string;
+    sessionId: string;
+    runId?: string | null;
+    toolCallId?: string | null;
+    name?: string;
+    message?: string;
+    reason?: string;
+    requestSchema?: Record<string, unknown> | null;
+};
+export declare function interactionFromAguiInterrupt(request: AguiInterruptRequest): Interaction | null;
+//# sourceMappingURL=agui.d.ts.map

package/dist-lib/core/interaction/adapters/agui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agui.d.ts","sourceRoot":"","sources":["../../../../src/core/interaction/adapters/agui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChD,CAAC;AAEF,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,WAAW,GAAG,IAAI,CAmBpB"}

package/dist-lib/core/interaction/adapters/normalize.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared normalization helpers for Interaction transport adapters.
+ *
+ * Every adapter produces the same Interaction shape so the store, tray,
+ * and submit path never branch on the transport protocol.
+ */
+import type { Interaction, InteractionSource } from './types.js';
+export type RawInteractionFields = {
+    interactionId: string;
+    sessionId: string;
+    runId?: string | null;
+    kind?: unknown;
+    title?: unknown;
+    message?: unknown;
+    requestSchema?: unknown;
+    presentation?: unknown;
+    status?: unknown;
+    revision?: unknown;
+    createdAt?: unknown;
+    expiresAt?: unknown;
+    resolvedAt?: unknown;
+    actor?: unknown;
+    outcome?: unknown;
+    responseSummary?: unknown;
+    extensions?: Record<string, unknown>;
+    source: InteractionSource;
+};
+export declare function normalizeInteraction(fields: RawInteractionFields): Interaction;
+//# sourceMappingURL=normalize.d.ts.map

package/dist-lib/core/interaction/adapters/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../../src/core/interaction/adapters/normalize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,WAAW,EAGX,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAoCF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,WAAW,CAyC9E"}

package/dist-lib/core/interaction/adapters/responses.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Responses transport adapter (`/v1/responses` official semantics).
+ *
+ * Normalizes the official `mcp_approval_request` item (delivered either
+ * as a stream action or as a SessionEvent record) into the shared
+ * Interaction shape. Responses-driven submissions keep the official
+ * `mcp_approval_response` path — the adapter marks the record
+ * `source: "responses"` so the submit path can route accordingly without
+ * components ever branching on protocol.
+ */
+import type { Interaction } from '../types.js';
+export type ResponsesApprovalRequest = {
+    approvalRequestId: string;
+    sessionId: string;
+    runId?: string | null;
+    name?: string;
+    message?: string;
+    approvalLevel?: string;
+    args?: string;
+    requestSchema?: Record<string, unknown> | null;
+};
+export declare function interactionFromResponsesApproval(request: ResponsesApprovalRequest): Interaction | null;
+/** Build the official Responses `mcp_approval_response` input item. */
+export declare function buildMcpApprovalResponse(approvalRequestId: string, approve: boolean): Record<string, unknown>;
+//# sourceMappingURL=responses.d.ts.map

package/dist-lib/core/interaction/adapters/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../../src/core/interaction/adapters/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,MAAM,MAAM,wBAAwB,GAAG;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChD,CAAC;AAEF,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,wBAAwB,GAChC,WAAW,GAAG,IAAI,CAiBpB;AAED,uEAAuE;AACvE,wBAAgB,wBAAwB,CACtC,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB"}

package/dist-lib/core/interaction/adapters/session-events.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AgentEngine Interaction/v1 SessionEvent adapter.
+ *
+ * `SessionEventEnvelope.payload` carries the public Interaction facts:
+ * event_type `interaction.requested` / `ksadk.interaction/v1.requested`
+ * creates a pending Interaction; `interaction.resolved` (outcome in
+ * payload) closes it. Rejection is `resolved.outcome="rejected"`, not a
+ * fifth terminal event type.
+ */
+import type { Interaction } from '../types.js';
+/**
+ * Normalize an Interaction/v1 SessionEvent payload (or envelope) into the
+ * shared Interaction shape. Returns null when the event is not an
+ * interaction event.
+ */
+export declare function interactionFromSessionEvent(raw: unknown, fallbackSessionId?: string): Interaction | null;
+//# sourceMappingURL=session-events.d.ts.map

package/dist-lib/core/interaction/adapters/session-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../../../../src/core/interaction/adapters/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA0B/C;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,iBAAiB,CAAC,EAAE,MAAM,GACzB,WAAW,GAAG,IAAI,CAgGpB"}

package/dist-lib/core/interaction/client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Headless InteractionClient implementation.
+ *
+ * One submit path per record source:
+ * - `interaction_v1` (AgentEngine Interaction/v1): every action is one
+ *   `POST /agentengine/api/v1/SubmitInteraction` call with revision CAS
+ *   and an idempotency key.
+ * - `responses`: official `/v1/responses` `mcp_approval_response` path
+ *   (0.3.1 fallback for servers without `interaction_v1`).
+ * - `agui`: `resumeAguiInterrupt` (0.3.1 fallback).
+ *
+ * Components never branch on the source — they call `respond()`.
+ */
+import { type Interaction, type InteractionAction, type InteractionClient, type InteractionEvent, type InteractionReceipt, type InteractionSubmitInput } from './types.js';
+import { InteractionStore } from './store.js';
+export type SubmitInteractionTransport = (params: {
+    AgentId: string;
+    SessionId: string;
+    RunId: string;
+    InteractionId: string;
+    ExpectedRevision: number;
+    Action: InteractionAction;
+    Response: Record<string, unknown>;
+    IdempotencyKey: string;
+}) => Promise<unknown>;
+export type InteractionClientDeps = {
+    agentId: string;
+    store?: InteractionStore;
+    submitInteraction: SubmitInteractionTransport;
+    /**
+     * When bootstrap advertises `interaction_v1`, every action goes through
+     * SubmitInteraction regardless of the transport that produced the
+     * pending record.
+     */
+    interactionV1Enabled?: boolean;
+    /** @deprecated 0.3.1 Responses `mcp_approval_response` fallback. */
+    legacyResponsesApproval?: (interactionId: string, approve: boolean) => void;
+    /** @deprecated 0.3.1 AG-UI `resumeAguiInterrupt` fallback. */
+    legacyAguiResume?: (interruptId: string, status: 'resolved' | 'cancelled', payload?: unknown) => boolean;
+};
+export declare class InteractionClientImpl implements InteractionClient {
+    readonly store: InteractionStore;
+    private deps;
+    /** interactionId -> in-flight idempotency key (double-submit guard). */
+    private inFlight;
+    constructor(deps: InteractionClientDeps);
+    listPending(sessionId: string): readonly Interaction[];
+    /** Update capability routing after bootstrap capabilities change. */
+    setInteractionV1Enabled(enabled: boolean): void;
+    subscribe(listener: (event: InteractionEvent) => void): () => void;
+    /** Normalize + persist an incoming Interaction (adapter output). */
+    ingest(interaction: Interaction): void;
+    /**
+     * Restore state from replayed history. Only upserts server facts —
+     * never issues a submit — so a refresh/replay restores a pending
+     * Interaction without creating a second request.
+     */
+    ingestHistory(interactions: readonly Interaction[]): void;
+    private findByInteractionId;
+    respond(input: InteractionSubmitInput): Promise<InteractionReceipt>;
+    private resolveLocal;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist-lib/core/interaction/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/core/interaction/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAErB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,MAAM,0BAA0B,GAAG,CAAC,MAAM,EAAE;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;CACxB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,iBAAiB,EAAE,0BAA0B,CAAC;IAC9C;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,oEAAoE;IACpE,uBAAuB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5E,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,CACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,UAAU,GAAG,WAAW,EAChC,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC;CACd,CAAC;AAyBF,qBAAa,qBAAsB,YAAW,iBAAiB;IAC7D,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,OAAO,CAAC,IAAI,CAAwB;IACpC,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAA6B;gBAEjC,IAAI,EAAE,qBAAqB;IAKvC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE;IAItD,qEAAqE;IACrE,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI/C,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAIlE,oEAAoE;IACpE,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAItC;;;;OAIG;IACH,aAAa,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI;IAczD,OAAO,CAAC,mBAAmB;IAQrB,OAAO,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0GzE,OAAO,CAAC,YAAY;CAuBrB"}

package/dist-lib/core/interaction/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Interaction/v1 headless module.
+ *
+ * One Interaction store, one submit path, three transport adapters
+ * (Interaction/v1 SessionEvents, Responses `mcp_approval_request`,
+ * AG-UI interrupts). Components consume `InteractionClient` /
+ * `useInteractions` and never branch on the approval protocol.
+ */
+export type { A2uiPresentation, Interaction, InteractionAction, InteractionClient, InteractionEvent, InteractionKind, InteractionOutcome, InteractionPresentation, InteractionReceipt, InteractionSource, InteractionStatus, InteractionSubmitInput, } from './types.js';
+export { interactionIdempotencyKey, isTerminalInteraction, summarizeResponse, } from './types.js';
+export { InteractionStore } from './store.js';
+export { InteractionClientImpl } from './client.js';
+export type { InteractionClientDeps, SubmitInteractionTransport } from './client.js';
+export { interactionFromSessionEvent } from './adapters/session-events.js';
+export { buildMcpApprovalResponse, interactionFromResponsesApproval, } from './adapters/responses.js';
+export type { ResponsesApprovalRequest } from './adapters/responses.js';
+export { interactionFromAguiInterrupt } from './adapters/agui.js';
+export type { AguiInterruptRequest } from './adapters/agui.js';
+export { A2UI_WIRE_VERSION, computeA2uiCatalogDigest, validateA2uiPresentation, } from './a2ui-validate.js';
+export type { A2uiRenderMode } from './a2ui-validate.js';
+import { InteractionStore } from './store.js';
+import type { Interaction } from './types.js';
+/**
+ * App-wide shared store. Transport ingestion points (run dispatcher,
+ * session lifecycle) write here; the app's `InteractionClient` reads and
+ * submits through the same store.
+ */
+export declare const sharedInteractionStore: InteractionStore;
+/** Ingest an Interaction/v1 (or legacy) SessionEvent record/envelope. */
+export declare function ingestSessionEventRecord(raw: unknown, fallbackSessionId?: string): Interaction | null;
+/** Ingest a RunEngine `approval_requested` event (Responses or AG-UI). */
+export declare function ingestApprovalRequestedEvent(event: {
+    approvalRequestId: string;
+    protocol: 'ag-ui' | 'responses';
+    name?: string;
+    message?: string;
+    args?: string;
+    approvalLevel?: string;
+    sessionId?: string | null;
+}): Interaction | null;
+//# sourceMappingURL=index.d.ts.map

package/dist-lib/core/interaction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/interaction/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EACL,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAI9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,kBAAyB,CAAC;AAE7D,yEAAyE;AACzE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EACZ,iBAAiB,CAAC,EAAE,MAAM,GACzB,WAAW,GAAG,IAAI,CAMpB;AAED,0EAA0E;AAC1E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,GAAG,WAAW,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,WAAW,GAAG,IAAI,CAuBrB"}

package/dist-lib/core/interaction/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/interaction/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAEzE,qBAAa,gBAAgB;IAC3B,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,SAAS,CAAuC;IAExD,OAAO,CAAC,GAAG;IAIX,SAAS,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI;IAKzD,OAAO,CAAC,IAAI;IAMZ,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAIjE,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE;IAMtD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE;IAMlD,GAAG,IAAI,SAAS,WAAW,EAAE;IAM7B;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB;IAuDlD,sEAAsE;IACtE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAa7D,0DAA0D;IAC1D,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAC,CAAC,GAChH,IAAI;IAaP,4EAA4E;IAC5E,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAWjF,4EAA4E;IAC5E,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,GAC3D,IAAI;IAYP,kFAAkF;IAClF,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAQ/D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAOtD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAKtC"}

package/dist-lib/core/interaction/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Interaction/v1 client-side types.
+ *
+ * Mirrors the canonical `contracts/agent-kernel/v1/interaction.schema.json`:
+ * one durable Interaction identity per human decision, revision-based
+ * optimistic concurrency, and first-wins terminal semantics. Responses
+ * approval requests and AG-UI interrupts are transport adapters that
+ * normalize into this single shape — components never branch on
+ * `approvalProtocol`.
+ */
+import type { AgentControlReceipt } from '../../types/agent-control.js';
+export type InteractionStatus = 'pending' | 'resolving' | 'failed' | 'resolved' | 'cancelled' | 'expired';
+export type InteractionAction = 'approve' | 'reject' | 'submit' | 'cancel';
+export type InteractionKind = 'approval' | 'structured_input' | 'plan_review' | 'custom';
+/** Which transport surface produced the normalized Interaction. */
+export type InteractionSource = 'interaction_v1' | 'responses' | 'agui';
+export type A2uiPresentation = {
+    /** Production wire is locked to "0.9.1". */
+    wireVersion: string;
+    /** Pinned catalog digest required before rendering A2UI. */
+    catalogDigest: string;
+    messages: Array<Record<string, unknown>>;
+};
+export type InteractionPresentation = {
+    a2ui?: A2uiPresentation;
+};
+export type InteractionOutcome = 'approved' | 'rejected' | 'submitted' | 'cancelled' | 'expired';
+/**
+ * The single normalized Interaction record. Internal provider fields
+ * (native targets, checkpoints, permits) never appear here — the server
+ * redacts them before emitting public events.
+ */
+export type Interaction = {
+    interactionId: string;
+    sessionId: string;
+    runId: string | null;
+    kind: InteractionKind;
+    title: string;
+    message: string;
+    requestSchema: Record<string, unknown> | null;
+    presentation: InteractionPresentation | null;
+    status: InteractionStatus;
+    revision: number;
+    createdAt: string;
+    expiresAt: string | null;
+    resolvedAt: string | null;
+    actor: string | null;
+    outcome: InteractionOutcome | null;
+    /** Redacted summary of the submitted response; never raw secrets. */
+    responseSummary: string | null;
+    source: InteractionSource;
+    extensions: Record<string, unknown>;
+};
+export type InteractionEvent = {
+    type: 'interaction_requested';
+    interaction: Interaction;
+} | {
+    type: 'interaction_updated';
+    interaction: Interaction;
+} | {
+    type: 'interaction_resolved';
+    interaction: Interaction;
+} | {
+    type: 'interaction_removed';
+    interactionId: string;
+};
+export type InteractionSubmitInput = {
+    interactionId: string;
+    expectedRevision: number;
+    action: InteractionAction;
+    response: Record<string, unknown>;
+    idempotencyKey: string;
+};
+export type InteractionReceipt = AgentControlReceipt;
+/**
+ * Headless public API. Transport-agnostic: every AgentEngine
+ * Interaction/v1 action goes through one `respond` call.
+ */
+export interface InteractionClient {
+    listPending(sessionId: string): readonly Interaction[];
+    subscribe(listener: (event: InteractionEvent) => void): () => void;
+    respond(input: InteractionSubmitInput): Promise<InteractionReceipt>;
+}
+/** Statuses that may only be set by an authoritative terminal SessionEvent. */
+export declare const TERMINAL_INTERACTION_STATUSES: ReadonlySet<InteractionStatus>;
+export declare function isTerminalInteraction(status: InteractionStatus): boolean;
+/** Default idempotency key derivation: stable per (id, revision). */
+export declare function interactionIdempotencyKey(interactionId: string, expectedRevision: number): string;
+/** Redact a response payload into a short human-readable summary. */
+export declare function summarizeResponse(action: InteractionAction, response: Record<string, unknown>): string;
+//# sourceMappingURL=types.d.ts.map

package/dist-lib/core/interaction/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/interaction/types.ts"],"names":[],"mappings":"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"}

package/dist-lib/core/run/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/core/run/dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkE3C,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,QAqhBvD;AAED,wBAAgB,oBAAoB,SAInC"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/core/run/dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA2E3C,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,QA4iBvD;AAED,wBAAgB,oBAAoB,SAInC"}

package/dist-lib/core/run/engine.d.ts

@@ -1,4 +1,4 @@
-import type { RunEngine, RunStage, RunEvent, RunEngineConfig } from './types.js';
+import type { RunControlState, RunEngine, RunStage, RunEvent, RunEngineConfig, RuntimeExecutionMode, SubmitControlCommand } from './types.js';
 import type { ApiFacade } from '../api/types.js';
 export declare class RunEngineImpl implements RunEngine {
     private _stage;
@@ -9,9 +9,22 @@ export declare class RunEngineImpl implements RunEngine {
     private aguiClient;
     private aguiThreadSessionId;
     private api;
+    private controlStateValue;
+    private lastControlCommand;
     private config;
     constructor(api: ApiFacade);
     get stage(): RunStage;
+    get controlState(): RunControlState;
+    /**
+     * Submit an agent-kernel/v1 control command. Receipt semantics:
+     * accepted/duplicate -> queued (never treated as completion), queue_full ->
+     * retryable with the same idempotency key, unsupported -> surfaces the
+     * capability reason, persistence_uncertain -> confirm status before retry.
+     */
+    submitControl(command: SubmitControlCommand): Promise<RunControlState>;
+    private controlStateFor;
+    /** Retry the last control command, reusing its idempotency key. */
+    retryControl(): Promise<RunControlState>;
     updateConfig(config: RunEngineConfig): void;
     private emit;
     private getAguiClient;
@@ -22,6 +35,7 @@ export declare class RunEngineImpl implements RunEngine {
         attachments: File[];
         responsesInput?: unknown;
         previousResponseId?: string;
+        executionMode?: RuntimeExecutionMode;
         sessionId?: string | null;
         onSessionCreated?: (sessionId: string) => void;
         onSessionUpsert?: (sessionId: string) => void;
@@ -51,9 +65,21 @@ export declare class RunEngineImpl implements RunEngine {
         onSettled?: (sessionId: string | null) => void;
     }): boolean;
     private createSession;
+    private getConversationBootstrap;
+    private buildCanonicalConversationInput;
+    private uploadCanonicalAttachments;
     private uploadFiles;
     private imageFileToDataUrl;
     private buildRequestBody;
+    private buildExecutionMetadata;
+    /**
+     * Consume an AgentKernel run: the receipt proved the durable enqueue; the
+     * run output arrives on SubscribeSessionEvents as raw kernel frames which
+     * are translated to legacy SessionEventRecords (dispatcher handles the
+     * message merge + interaction ingestion). Reconnects resume from the last
+     * observed kernel seq.
+     */
+    private consumeKernelRunEvents;
     private consumeStream;
     private isCompactionChunk;
     private dispatchAction;