Complete TypeScript contracts

Generated from this release source. See the API guide for usage and defaults.

Core types

RcipJsonPrimitive

/** JSON primitive accepted at RCIP contract boundaries. */
export type RcipJsonPrimitive = boolean | null | number | string

RcipJsonValue

/** Serializable value accepted by capability inputs and outputs. */
export type RcipJsonValue =
  | RcipJsonPrimitive
  | RcipJsonObject
  | RcipJsonValue[]

RcipJsonObject

/** Serializable JSON object with recursively compatible values. */
export interface RcipJsonObject {
  [key: string]: RcipJsonValue
}

RcipJsonSchema

/** JSON Schema document used for runtime input and output validation. */
export type RcipJsonSchema = boolean | RcipJsonObject

RcipProtocolVersion

export type RcipProtocolVersion = typeof RCIP_PROTOCOL_VERSION

RcipCapabilityEffect

/** Host policy signal describing the class of application effect. */
export type RcipCapabilityEffect =
  | 'read'
  | 'write'
  | 'external'
  | 'destructive'

RcipApplicationMetadata

/** Stable, public metadata describing one RCIP-enabled application. */
export interface RcipApplicationMetadata {
  readonly id: string
  readonly name: string
  readonly description: string
  readonly version?: string
}

RcipScopeDefinition

/** Conceptual application area used to organize capability relevance. */
export interface RcipScopeDefinition {
  readonly id: string
  readonly title: string
  readonly description: string
  readonly parentId?: string
}

RcipCapabilityExample

/** One valid, tool-readable example for a capability input contract. */
export interface RcipCapabilityExample<
  Input extends RcipJsonValue = RcipJsonValue,
> {
  readonly description: string
  readonly input: Input
}

RcipCapabilityUsage

/** Optional provider-neutral guidance for capability consumers. */
export interface RcipCapabilityUsage<
  Input extends RcipJsonValue = RcipJsonValue,
> {
  readonly whenToUse: string
  readonly examples?: readonly RcipCapabilityExample<Input>[]
}

RcipCapabilityDefinition

/** Static semantic contract for one user-meaningful application operation. */
export interface RcipCapabilityDefinition<
  Input extends RcipJsonValue = RcipJsonValue,
  Output extends RcipJsonValue = RcipJsonValue,
> {
  readonly id: string
  readonly title: string
  readonly description: string
  readonly scopeIds: readonly string[]
  readonly effect: RcipCapabilityEffect
  readonly inputSchema: RcipJsonSchema
  readonly outputSchema: RcipJsonSchema
  readonly tags?: readonly string[]
  readonly usage?: RcipCapabilityUsage<Input>
  readonly __types?: {
    readonly input: Input
    readonly output: Output
  }
}

RcipApplicationDefinition

/** Static protocol catalog used to create an RCIP runtime. */
export interface RcipApplicationDefinition {
  readonly protocolVersion: RcipProtocolVersion
  readonly application: RcipApplicationMetadata
  readonly scopes: readonly RcipScopeDefinition[]
  readonly capabilities: readonly RcipCapabilityDefinition[]
}

RcipAvailability

/** Live host decision describing whether a bound capability can currently run. */
export interface RcipAvailability {
  readonly available: boolean
  readonly reasonCode?: string
  readonly reason?: string
}

RcipSemanticContext

/** Live semantic scopes relevant to the user's current application context. */
export interface RcipSemanticContext {
  readonly activeScopeIds: readonly string[]
  readonly primaryScopeId?: string
}

RcipCapabilityHandlerContext

/** Trusted execution metadata supplied to a bound capability handler. */
export interface RcipCapabilityHandlerContext {
  readonly signal?: AbortSignal
  readonly invocationId: string
  readonly requestedAt: number
  readonly semanticContext: RcipSemanticContext
}

RcipCapabilityBinding

/** Live application implementation for a declared capability contract. */
export interface RcipCapabilityBinding<
  Input extends RcipJsonValue = RcipJsonValue,
  Output extends RcipJsonValue = RcipJsonValue,
> {
  readonly execute: (
    input: Input,
    context: RcipCapabilityHandlerContext,
  ) => Output | Promise<Output>
  readonly getAvailability?: () => RcipAvailability
}

RcipCapabilitySnapshot

/** Serializable discovery record combining a contract with live host state. */
export interface RcipCapabilitySnapshot {
  readonly id: string
  readonly title: string
  readonly description: string
  readonly scopeIds: readonly string[]
  readonly effect: RcipCapabilityEffect
  readonly inputSchema: RcipJsonSchema
  readonly outputSchema: RcipJsonSchema
  readonly tags: readonly string[]
  readonly usage?: RcipCapabilityUsage
  readonly bound: boolean
  readonly available: boolean
  readonly availability?: RcipAvailability
  readonly relevance: 'current' | 'other'
}

RcipApplicationSnapshot

/** Complete serializable discovery view available to consumer tools. */
export interface RcipApplicationSnapshot {
  readonly protocolVersion: RcipProtocolVersion
  readonly revision: number
  readonly application: RcipApplicationMetadata
  readonly scopes: readonly RcipScopeDefinition[]
  readonly context: RcipSemanticContext
  readonly capabilities: readonly RcipCapabilitySnapshot[]
}

RcipCapabilityFilter

/** Optional filters supported by {@link RcipClient.listCapabilities}. */
export interface RcipCapabilityFilter {
  readonly context?: 'all' | 'current'
  readonly availableOnly?: boolean
  readonly scopeId?: string
  readonly effect?: RcipCapabilityEffect
}

RcipInvocationRequest

/** Request to invoke one capability through the validated client boundary. */
export interface RcipInvocationRequest {
  readonly capabilityId: string
  readonly input: RcipJsonValue
  readonly invocationId?: string
  readonly signal?: AbortSignal
}

RcipValidationIssue

/** Redacted JSON Schema validation issue safe for a consumer tool. */
export interface RcipValidationIssue {
  readonly instancePath: string
  readonly keyword: string
  readonly message: string
}

RcipErrorCode

/** Stable machine-readable failure codes returned by protocol 1.0. */
export type RcipErrorCode =
  | 'CAPABILITY_NOT_FOUND'
  | 'CAPABILITY_UNBOUND'
  | 'CAPABILITY_UNAVAILABLE'
  | 'INPUT_INVALID'
  | 'POLICY_DENIED'
  | 'POLICY_EVALUATION_FAILED'
  | 'CONFIRMATION_DECLINED'
  | 'CONFIRMATION_EXPIRED'
  | 'CONFIRMATION_NOT_FOUND'
  | 'EXECUTION_ABORTED'
  | 'EXECUTION_FAILED'
  | 'OUTPUT_INVALID'
  | 'INVOCATION_ALREADY_ACTIVE'

RcipInvocationError

/** Structured, non-sensitive invocation failure detail. */
export interface RcipInvocationError {
  readonly code: RcipErrorCode
  readonly message: string
  readonly validationIssues?: readonly RcipValidationIssue[]
}

RcipInvocationSucceeded

/** Terminal successful capability outcome with validated output. */
export interface RcipInvocationSucceeded {
  readonly status: 'succeeded'
  readonly invocationId: string
  readonly capabilityId: string
  readonly output: RcipJsonValue
}

RcipInvocationFailed

/** Terminal failed or host-denied capability outcome. */
export interface RcipInvocationFailed {
  readonly status: 'failed' | 'denied'
  readonly invocationId: string
  readonly capabilityId: string
  readonly error: RcipInvocationError
}

RcipInvocationConfirmationRequired

/** Non-terminal request for a fresh host-owned confirmation decision. */
export interface RcipInvocationConfirmationRequired {
  readonly status: 'confirmation_required'
  readonly invocationId: string
  readonly capabilityId: string
  readonly confirmation: {
    readonly id: string
    readonly title: string
    readonly description: string
    readonly effect: RcipCapabilityEffect
    readonly expiresAt: number
  }
}

RcipInvocationOutcome

/** Every outcome returned from invocation or confirmation resolution. */
export type RcipInvocationOutcome =
  | RcipInvocationSucceeded
  | RcipInvocationFailed
  | RcipInvocationConfirmationRequired

RcipPolicyContext

/** Current inputs supplied to the host's authoritative policy. */
export interface RcipPolicyContext {
  readonly capability: RcipCapabilitySnapshot
  readonly input: RcipJsonValue
  readonly semanticContext: RcipSemanticContext
  readonly confirmed: boolean
}

RcipPolicyDecision

/** Host policy response for one invocation attempt. */
export type RcipPolicyDecision =
  | { readonly decision: 'allow' }
  | { readonly decision: 'deny'; readonly reason?: string }
  | { readonly decision: 'confirm'; readonly reason?: string }

RcipInvocationPolicy

/** Host-owned policy callback that may synchronously or asynchronously decide. */
export type RcipInvocationPolicy = (
  context: RcipPolicyContext,
) => RcipPolicyDecision | Promise<RcipPolicyDecision>

RcipRuntimeEventPhase

/** Redacted lifecycle phase emitted for application observability. */
export type RcipRuntimeEventPhase =
  | 'requested'
  | 'confirmation_requested'
  | 'confirmation_declined'
  | 'started'
  | 'succeeded'
  | 'failed'
  | 'denied'

RcipRuntimeEvent

/** Redacted invocation lifecycle event supplied only to the host callback. */
export interface RcipRuntimeEvent {
  readonly timestamp: number
  readonly invocationId: string
  readonly capabilityId: string
  readonly phase: RcipRuntimeEventPhase
  readonly errorCode?: RcipErrorCode
}

RcipRuntimeOptions

/** Runtime configuration controlled by the host application. */
export interface RcipRuntimeOptions {
  readonly confirmationTtlMs?: number
  readonly createId?: (prefix: string) => string
  readonly onEvent?: (event: RcipRuntimeEvent) => void
  readonly policy?: RcipInvocationPolicy
}

RcipClient

/**
 * Narrow consumer surface for AI delegates, dashboards, and other tools.
 * Host-only binding and policy controls are intentionally excluded.
 */
export interface RcipClient {
  readonly getSnapshot: () => RcipApplicationSnapshot
  readonly listCapabilities: (
    filter?: RcipCapabilityFilter,
  ) => readonly RcipCapabilitySnapshot[]
  readonly invoke: (
    request: RcipInvocationRequest,
  ) => Promise<RcipInvocationOutcome>
  readonly subscribe: (listener: () => void) => () => void
}

RcipHostController

/** Trusted application surface for binding, context, and confirmation control. */
export interface RcipHostController {
  readonly bindCapability: <
    Input extends RcipJsonValue,
    Output extends RcipJsonValue,
  >(
    definition: RcipCapabilityDefinition<Input, Output>,
    binding: RcipCapabilityBinding<Input, Output>,
  ) => () => void
  readonly refresh: () => void
  readonly resolveConfirmation: (
    confirmationId: string,
    approved: boolean,
  ) => Promise<RcipInvocationOutcome>
  readonly setContext: (context: RcipSemanticContext) => void
}

RcipRuntime

/** Paired client and host surfaces for one application definition. */
export interface RcipRuntime {
  readonly client: RcipClient
  readonly host: RcipHostController
}

React types

RcipProviderProps

/** Props for the React provider that installs one host-owned runtime. */
export interface RcipProviderProps {
  readonly children: ReactNode
  readonly runtime: RcipRuntime
}

RcipReactCapabilityBinding

/**
 * A React capability binding with an optional revision used to refresh
 * availability when consumer state changes.
 */
export interface RcipReactCapabilityBinding<
  Input extends RcipJsonValue,
  Output extends RcipJsonValue,
> extends RcipCapabilityBinding<Input, Output> {
  readonly revision?: RcipJsonPrimitive
}

Assist types

RcipAssistMode

/** Capability effects exposed to an assist callback. */
export type RcipAssistMode = 'interactive' | 'read-only'

RcipAssistStatus

/** Visual and orchestration state exposed by the headless assist hook. */
export type RcipAssistStatus =
  | 'active'
  | 'attention'
  | 'error'
  | 'idle'
  | 'success'
  | 'working'

RcipAssistInputStatus

/** Lifecycle state for text and voice input before an Assist turn begins. */
export type RcipAssistInputStatus =
  | 'error'
  | 'idle'
  | 'listening'
  | 'processing'
  | 'starting'

RcipAssistInputOrigin

/** Origin of an input moving through the configured processor pipeline. */
export type RcipAssistInputOrigin = 'composer' | 'voice'

RcipAssistTextInput

/** Text input accepted by the Assist input pipeline. */
export interface RcipAssistTextInput {
  readonly text: string
  readonly type: 'text'
}

RcipAssistAudioInput

/** Browser audio input accepted by a transcription-style processor. */
export interface RcipAssistAudioInput {
  readonly data: Blob
  readonly mimeType: string
  readonly type: 'audio'
}

RcipAssistInput

/** Value transformed by ordered Assist input processors. */
export type RcipAssistInput = RcipAssistAudioInput | RcipAssistTextInput

RcipAssistInputContext

/** Cancellation and live application context supplied to an input processor. */
export interface RcipAssistInputContext {
  readonly origin: RcipAssistInputOrigin
  readonly signal: AbortSignal
  readonly snapshot: RcipApplicationSnapshot
}

RcipAssistInputProcessor

/** One ordered audio/text transformation in an Assist input pipeline. */
export interface RcipAssistInputProcessor {
  readonly id: string
  readonly process: (
    input: RcipAssistInput,
    context: RcipAssistInputContext,
  ) => Promise<RcipAssistInput | null>
}

RcipAssistVoiceContext

/** Cancellation context supplied to the consumer-owned voice adapter. */
export interface RcipAssistVoiceContext {
  readonly signal: AbortSignal
}

RcipAssistVoiceAdapter

/**
 * Consumer-owned voice capture boundary. RCIP ships a simulation by default;
 * a real adapter may request permission and return audio or text from stop().
 */
export interface RcipAssistVoiceAdapter {
  readonly cancel?: () => Promise<void> | void
  readonly start: (context: RcipAssistVoiceContext) => Promise<void> | void
  readonly stop: (
    context: RcipAssistVoiceContext,
  ) => Promise<RcipAssistInput | null>
}

RcipAssistInputPipeline

/** Ordered input processors and optional voice source used by Assist. */
export interface RcipAssistInputPipeline {
  readonly processors?: readonly RcipAssistInputProcessor[]
  readonly voice?: false | RcipAssistVoiceAdapter
}

RcipAssistInputFailure

/** Stable, user-safe failure from voice capture or input processing. */
export interface RcipAssistInputFailure {
  readonly code:
    | 'INPUT_PIPELINE_INCOMPLETE'
    | 'INPUT_PROCESSOR_FAILED'
    | 'VOICE_START_FAILED'
    | 'VOICE_STOP_FAILED'
  readonly message: string
}

RcipAssistDelay

/** The three bounded pacing choices an assist callback may request. */
export type RcipAssistDelay = 'long' | 'medium' | 'short'

RcipAssistDelayPresets

/** Milliseconds assigned to the callback's symbolic delay choices. */
export interface RcipAssistDelayPresets {
  readonly long: number
  readonly medium: number
  readonly short: number
}

RcipAssistMessage

/** One in-memory conversation message owned by an assist session. */
export interface RcipAssistMessage {
  readonly content: string
  readonly createdAt: number
  readonly id: string
  readonly role: 'assistant' | 'user'
}

RcipAssistAction

/** One capability invocation proposed by the consumer callback. */
export interface RcipAssistAction {
  readonly capabilityId: string
  readonly delayAfter: RcipAssistDelay
  readonly id?: string
  readonly input: RcipJsonValue
}

RcipAssistStep

/** A normalized proposed action paired with its authoritative RCIP outcome. */
export interface RcipAssistStep {
  readonly action: RcipAssistAction & { readonly id: string }
  readonly outcome: RcipInvocationOutcome
}

RcipAssistPhase

/** Bounded callback phase: decide once, then summarize without more actions. */
export type RcipAssistPhase = 'decide' | 'summarize'

RcipAssistRequest

/** Complete provider-neutral input supplied to the consumer callback. */
export interface RcipAssistRequest {
  readonly messages: readonly RcipAssistMessage[]
  readonly mode: RcipAssistMode
  readonly phase: RcipAssistPhase
  readonly snapshot: RcipApplicationSnapshot
  readonly steps: readonly RcipAssistStep[]
  readonly turnId: string
}

RcipAssistMessageResponse

/** Text response accepted in either callback phase. */
export interface RcipAssistMessageResponse {
  readonly message: string
  readonly type: 'message'
}

RcipAssistActionsResponse

/** One bounded action batch accepted only during the decide phase. */
export interface RcipAssistActionsResponse {
  readonly actions: readonly RcipAssistAction[]
  readonly type: 'actions'
}

RcipAssistResponse

/** Response contract implemented by deterministic, API, or model callbacks. */
export type RcipAssistResponse =
  | RcipAssistActionsResponse
  | RcipAssistMessageResponse

RcipAssistCallbackContext

/** Per-request callback context that supports cancellation. */
export interface RcipAssistCallbackContext {
  readonly signal: AbortSignal
}

RcipAssistDecide

/** Consumer-owned decision boundary; RCIP ships no provider or transport. */
export type RcipAssistDecide = (
  request: RcipAssistRequest,
  context: RcipAssistCallbackContext,
) => Promise<RcipAssistResponse>

RcipAssistPendingConfirmation

/** Confirmation waiting for a direct user decision in the trusted host UI. */
export interface RcipAssistPendingConfirmation {
  readonly action: RcipAssistAction & { readonly id: string }
  readonly outcome: RcipInvocationConfirmationRequired
}

Assist orchestration

UseRcipAssistOptions

/** Configuration for the provider-neutral assist orchestration hook. */
export interface UseRcipAssistOptions {
  readonly decide: RcipAssistDecide
  readonly delayPresets?: Partial<RcipAssistDelayPresets>
  readonly inputPipeline?: RcipAssistInputPipeline
  readonly maxBatchSize?: number
  readonly mode?: RcipAssistMode
  readonly runtime: RcipRuntime
  readonly welcomeMessage?: string
}

RcipAssistController

/** State and actions returned by the provider-neutral assist orchestration hook. */
export interface RcipAssistController {
  readonly busy: boolean
  readonly cancel: () => void
  readonly cancelInput: () => void
  readonly clear: () => void
  readonly inputError: RcipAssistInputFailure | null
  readonly inputStatus: RcipAssistInputStatus
  readonly messages: readonly RcipAssistMessage[]
  readonly mode: RcipAssistMode
  readonly pendingConfirmation: RcipAssistPendingConfirmation | null
  readonly resolveConfirmation: (approved: boolean) => Promise<void>
  readonly send: (message: string) => Promise<void>
  readonly snapshot: RcipApplicationSnapshot
  readonly startVoiceInput: () => Promise<void>
  readonly status: RcipAssistStatus
  readonly stopVoiceInput: () => Promise<void>
  readonly submitInput: (
    input: RcipAssistInput,
    origin?: RcipAssistInputOrigin,
  ) => Promise<void>
  readonly voiceEnabled: boolean
}

Assist UI

RcipAssistProps

/** Props for the SDK's collapsed-dot and floating-chat assist tool. */
export interface RcipAssistProps extends UseRcipAssistOptions {
  readonly className?: string
  readonly defaultOpen?: boolean
  readonly placeholder?: string
  readonly title?: string
}

Explorer

RcipCapabilityExplorerProps

/** Props for the SDK's read-only capability registry dashboard. */
export interface RcipCapabilityExplorerProps {
  /** Narrow RCIP client used for live, read-only registry discovery. */
  readonly client: RcipClient
  /** Optional class added to the explorer root for consumer-owned layout. */
  readonly className?: string
}