Runtime contract

The runtime contract supports opening or resuming a conversation, sending a message or structured interaction, receiving streamed output, and reconciling history after reconnecting.

Conversation attachments

Attachments are uploaded to an open conversation before sending the message. The send request refers to the returned attachment identifiers, and persisted history and realtime message events return the files linked to each turn.

Current supported formats are PNG, JPEG, PDF, TXT, and LOG, subject to the server's size and per-message limits. Clients must use the server MIME type and status rather than trusting local filename extensions. An unlinked attachment can be deleted; an attachment already linked to a sent turn is immutable.

When analysis is enabled, attachment responses can include a bounded summary, structured observations, and limitations. These are derived context, not confirmed workflow fields or instructions.

Structured interactions

Supported card kinds are:

• collect
• choice
• confirm

A submission identifies the card, active phase, kind, action, and submitted values. The server validates that the interaction belongs to the active conversation state so stale or mismatched submissions cannot advance a journey.

An input RuntimeInteraction can include optional initialValues: Record<string, unknown> for saved values in its declared fields, such as a collection step reopened to change details. Prefill from these values without submitting automatically. Preserve 0 and false; leave absent optional fields absent. Private agent context and its audit are not part of this public contract.

Streaming

All AI conversations share one runtime, whether the agent answers a question, uses tools, or invokes a capability. Sending a turn returns HTTP 202 after durable acceptance. Replies and progress arrive through ordered runtime events; message.upserted carries cumulative text with a stable ID and increasing revision. Capabilities stream through this same contract, not a separate chat transport.

When a capability is active, it owns the task until completion, failure, escalation, or explicit cancellation. Chat replies are delivered to its current checkpoint. A grounded side question can be answered without advancing the capability, after which the same checkpoint is restored. General tool discovery, unrelated tools, another capability, and goal steering do not run concurrently with the active capability. The capability's own authored actions continue to use the normal approval, receipt, and verification rules.

Clients must tolerate reconnects, reconcile snapshots and persisted history, and ignore already-applied revisions. Capability forms and tool approvals use the current task's interaction ID, version and revision; stale submissions fail without advancing the process.

Errors

Clients should treat authentication, authorization, validation, stale interaction, not-found, conflict, rate-limit, and temporary-service failures as distinct categories. The runtime SDK normalizes these failures for browser consumers.

For exact versioned request and response types, use @nambikk/sdk and the deployed OpenAPI document.