@openwop/openwop 1.2.0 → 1.4.0

package/src/types.ts

@@ -21,6 +21,10 @@ export type RunStatus =
   | 'waiting-external'
   | 'completed'
   | 'failed'
+  /** RFC 0094 §B — transitional state between a cancel request being
+   *  accepted and the terminal `cancelled`. Non-terminal: a snapshot
+   *  read during the cancel cascade carries it. */
+  | 'cancelling'
   | 'cancelled';
 
 export interface Capabilities {
@@ -36,6 +40,102 @@ export interface Capabilities {
     maxRunDurationMs?: number;
     /** RFC 0058. Engine-side agent-loop iteration ceiling; upper bound for `RunConfigurable.maxLoopIterations`. */
     maxLoopIterations?: number;
+    /** RFC 0094 §H. Maximum REST request body size (bytes) the host
+     *  accepts. Hosts that advertise it MUST enforce it. */
+    maxRequestBodyBytes?: number;
+  };
+  /** RFC 0094 §H. gRPC transport advertisement per `grpc-transport.md`
+   *  §"Capability advertisement". Absent ⇒ the host exposes no gRPC
+   *  transport. A host that exposes the gRPC surface advertises this
+   *  block AND includes `'grpc'` in `supportedTransports`. REST + SSE
+   *  remain exposed regardless. */
+  grpc?: {
+    /** Toggle — `true` when the gRPC surface is live. */
+    supported: boolean;
+    /** Full URI: `grpc://` (cleartext, intra-trusted-network only) OR
+     *  `grpcs://` (TLS). Hosts SHOULD require TLS in production. */
+    endpoint?: string;
+    /** Canonical service name. v1 hosts MUST use `openwop.v1.Engine`. */
+    service: 'openwop.v1.Engine';
+    /** TLS posture. Production hosts MUST set `'required'`. */
+    tls: 'required' | 'optional' | 'disabled';
+  };
+  /** RFC 0101. Multi-party group-conversation advertisement. Absent ⇒ the
+   *  host does not support N agents co-participating in one shared
+   *  transcript (the single user + single driving agent shape of RFC 0005
+   *  remains). When `supported: true`, the host honors the additive
+   *  `participants: AgentRef[]` roster on `conversation.opened` and the
+   *  conditionally-required per-turn `speakerId` on `role: 'agent'`
+   *  conversation turns — advertising `supported: true` without enforcing
+   *  both is a dishonest claim (`OPENWOP_REQUIRE_BEHAVIOR=true` fails it). */
+  multiPartyConversation?: {
+    /** Toggle — `true` when the host supports multi-party conversations. */
+    supported: boolean;
+    /** Upper bound on `participants[]` size the host accepts. Absent ⇒
+     *  host-defined / unbounded. */
+    maxParticipants?: number;
+  };
+  /** RFC 0100. Host exposes itself as an A2A (Agent2Agent) agent. `supported`
+   *  alone ⇒ the synchronous `message/send` → poll `tasks/get` round-trip
+   *  (`a2a-integration.md`). The optional flags gate the RFC 0100 async/durable
+   *  additions. Absent ⇒ no A2A advertisement. */
+  a2a?: {
+    /** Host exposes itself as an A2A agent. */
+    supported: boolean;
+    /** A2A 0.3 well-known agent card URL (`/.well-known/agent-card.json`). */
+    agentCardUrl: string;
+    /** `message/stream` + `tasks/resubscribe` (RFC 0100 §3 resubscribe re-attach). */
+    streaming?: boolean;
+    /** A2A push-notification config (RFC 0100 §4); a caller-supplied
+     *  `pushConfig.url` is SSRF-validated (`a2a-push-egress-ssrf`). */
+    pushNotifications?: boolean;
+    /** RFC 0100 §2. Host persists the projected `A2ATaskState` per backing run;
+     *  `tasks/get` returns live state after disconnect. Absent/false ⇒
+     *  synchronous round-trip only. */
+    durableTasks?: boolean;
+  };
+  /** RFC 0109. Host stamps the optional non-secret `agent.model`
+   *  (`{ provider, model }`) on `role:'agent'` conversation turns, recording
+   *  which model produced the turn (read verbatim on `:fork`). Absent ⇒ no
+   *  provenance; the host omits `agent.model`. */
+  conversationTurnModelProvenance?: {
+    /** Toggle — `true` when the host stamps `agent.model`. */
+    supported: boolean;
+  };
+  /** RFC 0110. Host emits the ephemeral `channel.presence` RunEvent (online +
+   *  per-member typing) for `type:'channel'` conversations. Presence is live
+   *  state — the host never persists it to the replayable event log and it
+   *  never affects replay / `:fork`. Membership-gated (default-deny, CTI-1).
+   *  Absent ⇒ no presence. */
+  channelPresence?: {
+    /** Toggle — `true` when the host emits `channel.presence`. */
+    supported: boolean;
+  };
+  /** Capability advertisement for the host AI-proxy (`aiProviders` in
+   *  `capabilities.md`). Absent ⇒ the host advertises no AI-proxy surface.
+   *  Carries BYOK policy plus the RFC 0105/0106/0108 self-hosted / speech /
+   *  real-time-voice flags. The wire object MAY carry additional fields
+   *  (`input`, `authModes`, `maxInlineMediaBytes`) not modeled here. */
+  aiProviders?: AIProvidersCapability;
+  /** RFC 0104. Portable HITL approver-routing advertisement. When
+   *  `approverRouting.supported`, the host honors the OPTIONAL, ADVISORY
+   *  `approverGroupRefs` / `approverRoleRefs` / `audience` fields on the
+   *  `kind:'approval'` interrupt payload (the SDK carries the interrupt
+   *  payload opaquely as `data`, so those advisory fields ride that opaque
+   *  object), resolves the advertised `refKinds` against its own RBAC, and
+   *  ENFORCES eligibility at resolve time. Absent ⇒ the host ignores them. */
+  interrupt?: {
+    approverRouting?: {
+      /** Host honors the RFC 0104 approver-routing fields. */
+      supported: boolean;
+      /** Ref kinds the host actually resolves: `'group'` ⇒ honors
+       *  `approverGroupRefs`, `'role'` ⇒ honors `approverRoleRefs`. Absent ⇒
+       *  advisory-only passthrough (the host resolves neither). */
+      refKinds?: readonly ('group' | 'role')[];
+      /** Host honors the `audience` notification-targeting override.
+       *  Absent/`false` ⇒ the host notifies the resolved eligible union. */
+      audience?: boolean;
+    };
   };
   extensions?: Record<string, unknown>;
   // Network-handshake superset (all `(future)` fields per capabilities.md)
@@ -402,7 +502,17 @@ export interface ResolveInterruptResponse {
  * (the `InterruptPayload` shape).
  */
 export interface InterruptByTokenInspection {
-  kind: 'approval' | 'clarification' | 'external-event' | 'custom';
+  kind:
+    | 'approval'
+    | 'clarification'
+    | 'external-event'
+    | 'custom'
+    // Multi-Agent Shift Phase 4 — multi-turn user interjections.
+    | 'conversation.start'
+    | 'conversation.exchange'
+    | 'conversation.close'
+    // Phase 1 — confidence-escalation contract.
+    | 'low-confidence';
   key: string;
   resumeSchema?: Record<string, unknown>;
   timeoutMs?: number;
@@ -472,16 +582,46 @@ export type AIPolicyDenyReason =
  * that don't enforce per-provider policies.
  */
 export interface AIProvidersCapability {
-  /** Provider ids the host's AI-proxy can route to. */
-  supported: readonly string[];
+  /** Provider ids the host's AI-proxy can route to. Optional per
+   *  `capabilities.schema.json` (the `aiProviders` block has no required
+   *  fields); a host advertising the block normally lists them. */
+  supported?: readonly string[];
   /** Subset of `supported` for which BYOK is permitted. */
-  byok: readonly string[];
+  byok?: readonly string[];
   /** Optional 4-mode policy enforcement advertisement. */
   policies?: {
     modes: readonly AIPolicyMode[];
     scopes?: readonly string[];
     errorCode?: string;
   };
+  /** RFC 0108. Subset of `supported` whose entries are operator-/tenant-
+   *  configured OpenAI-compatible endpoints (Ollama / vLLM / LM Studio / any
+   *  `/v1/chat/completions`-compatible server), as opposed to a host-managed
+   *  connection to a known public vendor. Each entry also appears in
+   *  `supported` and MAY also appear in `byok`. The id is an OPAQUE label that
+   *  MUST NOT encode the endpoint's network location (RFC 0108 §A.3), and a
+   *  client MUST NOT infer model capabilities from it (§B) — the authoritative
+   *  sources are `modelCapabilities.advertised[]` and `aiProviders.input`. */
+  selfHosted?: readonly string[];
+  /** RFC 0105. Present (value MUST be `'supported'`) ⇒ the host exposes speech
+   *  synthesis via the host-side `ctx.callSpeechSynthesizer`. Absent ⇒ no TTS
+   *  (a call is rejected with `speech_synthesis_unsupported`). */
+  speechSynthesis?: 'supported';
+  /** RFC 0106. Optional real-time voice profile. Absent ⇒ no live voice. The
+   *  sub-flags gate streaming STT / chunked TTS and turn-taking; the host
+   *  enforces that `turnDetection`/`bargeIn` require `transcription`. */
+  realtimeVoice?: {
+    /** Present (`'streaming'`) ⇒ host exposes streaming `ctx.callTranscriber`. */
+    transcription?: 'streaming';
+    /** Present (`'streaming'`) ⇒ `ctx.callSpeechSynthesizer` honors `stream:true`.
+     *  Requires `aiProviders.speechSynthesis: 'supported'`. */
+    synthesis?: 'streaming';
+    /** Endpointing sophistication; requires `transcription`. */
+    turnDetection?: 'vad' | 'semantic';
+    /** Present (`'supported'`) ⇒ host emits `voice.barge_in`/`voice.cancelled`
+     *  on overlapping speech; requires `transcription`. */
+    bargeIn?: 'supported';
+  };
 }
 
 /**
@@ -714,6 +854,129 @@ export interface MemoryWrittenPayload {
   [key: string]: unknown;
 }
 
+/** `output.chunk` / `ai.message.chunk` payload (RFC 0094 §D —
+ *  `run-event-payloads.schema.json#$defs/outputChunk`). Emitted for
+ *  streaming output (e.g., LLM token chunks); stream-mode `messages`
+ *  consumers see these. `runId` is required so multiplexed consumers
+ *  can route chunks without out-of-band context; `isLast` is required —
+ *  consumers rely on it for fold termination. `meta` carries the tiered
+ *  metadata per `stream-modes.md §messages` (Tier 1 typed slots + a
+ *  Tier 2 provider-pass-through escape hatch); kept loosely typed here
+ *  like the other extensible payload meta objects. */
+export interface OutputChunkPayload {
+  nodeId: string;
+  /** Run this chunk belongs to. */
+  runId: string;
+  chunk: string;
+  /** True for the final chunk of a given AI node call. */
+  isLast: boolean;
+  /** Optional sub-stream identifier when a node emits multiple
+   *  parallel streams. */
+  channel?: string;
+  /** Tiered chunk metadata (`finishReason`, `logprobs`, `toolCalls`,
+   *  `model`, `usage`, `provider` pass-through, …). */
+  meta?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// ─── RFC 0106 voice.* run-event payloads ────────────────────────────────
+// Mirror `run-event-payloads.schema.json`. These events are emitted on the
+// durable event log by the host-side `ctx.callTranscriber` /
+// `ctx.callSpeechSynthesizer(stream:true)` methods (out of client-SDK scope);
+// a client tails them off the run event stream.
+
+/** `voice.speech_start` (RFC 0106). Host detected start of speech. */
+export interface VoiceSpeechStartPayload {
+  /** Milliseconds since the turn/session epoch. */
+  atMs: number;
+  [key: string]: unknown;
+}
+
+/** `voice.transcript` (RFC 0106). An interim or final transcript fragment.
+ *  `contentTrust` is REQUIRED and always `'untrusted'` — live transcript is
+ *  untrusted ingress (`voice-transcript-untrusted`); consumers MUST NOT
+ *  promote it to higher authority. */
+export interface VoiceTranscriptPayload {
+  text: string;
+  /** `true` once the fragment is finalized (committed at `voice.turn_commit`). */
+  isFinal: boolean;
+  atMs: number;
+  /** Always `'untrusted'`. */
+  contentTrust: 'untrusted';
+  /** Stable prefix carried across interim revisions. */
+  committedPrefix?: string;
+  /** Provider-formatted variant (punctuation/casing). */
+  formatted?: string;
+  /** Provider stability score for an interim fragment. */
+  stability?: number;
+  [key: string]: unknown;
+}
+
+/** `voice.endpoint_candidate` (RFC 0106). A `semantic` turn detector's
+ *  candidate end-of-turn, distinct from the committed `voice.turn_commit`. */
+export interface VoiceEndpointCandidatePayload {
+  atMs: number;
+  /** Detector confidence in the candidate endpoint. */
+  confidence?: number;
+  [key: string]: unknown;
+}
+
+/** `voice.turn_commit` (RFC 0106). The turn is committed; `finalText` is the
+ *  settled transcript the `ctx.callTranscriber` Promise resolves with. */
+export interface VoiceTurnCommitPayload {
+  atMs: number;
+  finalText: string;
+  [key: string]: unknown;
+}
+
+/** `voice.synthesis_chunk` (RFC 0106). Metadata for a streamed-synthesis
+ *  clause-boundary chunk; bytes ride `url`/`streamRef` (or inline `base64`
+ *  only under the host cap), never inlined past the cap. */
+export interface VoiceSynthesisChunkPayload {
+  /** Monotonic chunk sequence within the synthesis. */
+  seq: number;
+  mimeType: string;
+  /** Host-served URL for the chunk bytes. */
+  url?: string;
+  /** Live-conduit handle for the chunk bytes. */
+  streamRef?: string;
+  /** Inline bytes — present only under the host's inline cap. */
+  base64?: string;
+  durationMs?: number;
+  /** `true` for the final chunk of the synthesis. */
+  final?: boolean;
+  [key: string]: unknown;
+}
+
+/** `voice.barge_in` (RFC 0106). Overlapping speech detected during playback. */
+export interface VoiceBargeInPayload {
+  atMs: number;
+  [key: string]: unknown;
+}
+
+/** `voice.cancelled` (RFC 0106). Downstream work cancelled (e.g. after a
+ *  barge-in); no synthesis chunk follows. */
+export interface VoiceCancelledPayload {
+  atMs: number;
+  /** Host-defined cancellation reason. */
+  reason?: string;
+  [key: string]: unknown;
+}
+
+/** `channel.presence` (RFC 0110). EPHEMERAL online + typing presence for a
+ *  `type:'channel'` conversation. Observable on the LIVE run-event stream
+ *  only — the host MUST NOT persist it to the replayable event log, so it is
+ *  ABSENT on replay / `POST /v1/runs/{runId}:fork`. Membership-gated: every
+ *  ref is a current participant (opaque RFC 0041 subject refs, non-PII). */
+export interface ChannelPresencePayload {
+  conversationId: string;
+  /** Subject refs of members currently present (subset of participants). */
+  present: readonly string[];
+  /** Subset of `present` currently typing (boolean-by-presence; no free text). */
+  typing?: readonly string[];
+  [key: string]: unknown;
+}
+
 /** A `RunEventDoc` narrowed to a specific event-type discriminator +
  *  payload shape. Returned by the `isAgent*` type guards in
  *  `event-helpers.ts`. */
@@ -869,6 +1132,39 @@ export interface AIEnvelopeErrorPayload {
   details?: Record<string, unknown>;
 }
 
+/**
+ * Payload of the core `ui.a2ui-surface` envelope kind (RFC 0102 — A2UI
+ * agent-authored interface surfaces, `schemas/envelopes/ui.a2ui-surface.schema.json`).
+ * An advertised, optional core kind beside the `media.*` family: a declarative
+ * interactive UI a consumer renders with native widgets, routing user actions
+ * back **without executing agent-supplied code**.
+ *
+ * `surface` is the closed component tree, kept loose here (`Record<string,
+ * unknown>`) — it is rendered by a dedicated A2UI renderer the SDK does not
+ * provide, and matches the SDK convention of keeping complex nested shapes
+ * structural (cf. `ClarificationRequestPayload.questions[].schema`).
+ *
+ * NOTE: the broader AI-envelope surface (`AIEnvelope`, `EnvelopeMeta`, the
+ * universal payloads) is currently modeled only in this TypeScript SDK; the
+ * Python and Go SDKs do not yet model AI envelopes. `A2UISurfacePayload`
+ * therefore lands here only; cross-SDK AI-envelope modeling is a separate
+ * follow-on (tracked in PARITY.md), not part of RFC 0102.
+ */
+export interface A2UISurfacePayload {
+  /** The A2UI catalog version the surface targets. A host-enumerated,
+   *  growing set (currently `'0.9.1'`); a consumer MUST refuse an unknown /
+   *  higher version with `unknown_schema_version`. Typed as `string` (not a
+   *  pinned literal) so the read-type stays forward-compatible as the host's
+   *  supported set grows; the consumer enforces refuse-unknown at runtime. */
+  catalogVersion: string;
+  /** The A2UI surface document — a closed component tree, self-contained and
+   *  renderable from the payload alone (never a live reference into an
+   *  external catalog). Kept structural; rendered by an A2UI renderer. */
+  surface: Record<string, unknown>;
+  /** OPTIONAL model reasoning (RFC 0030 §A), conventionally first. */
+  reasoning?: string;
+}
+
 // ── RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md) ──
 
 /**
@@ -1328,3 +1624,96 @@ export interface AgentDeploymentTransition {
   evalRunId?: string;
   reason?: string;
 }
+
+// ── RFC 0103 Localized content surface (spec/v1/localized-content.md) ──
+// Mirror schemas/localized-content-*.schema.json. Host-defined structured
+// content (`data`, `localizations`, `seo`) is kept open per the schemas
+// (additionalProperties: true) — it is the host's content model, not a
+// fixed wire shape.
+
+export type LocalizedContentStatus = 'draft' | 'published';
+
+/** A content page record (`schemas/localized-content-page.schema.json`). */
+export interface LocalizedContentPage {
+  pageId: string;
+  slug: string;
+  /** Human-facing page name (admin/authoring label). */
+  name: string;
+  status: LocalizedContentStatus;
+  /** Ordered section ids composing the page. */
+  sectionOrder: readonly string[];
+  /** Open SEO metadata object (host-defined). */
+  seo?: Record<string, unknown>;
+}
+
+/** A content section record (`schemas/localized-content-section.schema.json`).
+ *  A section is one record: a base `data` payload + a sparse `localizations`
+ *  map (BCP-47 keys, never the base locale). */
+export interface LocalizedContentSection {
+  sectionId: string;
+  sectionType: string;
+  /** Base-locale field payload (host-defined open shape). */
+  data: Record<string, unknown>;
+  /** Per-locale sparse field overlays, keyed by BCP-47 locale. */
+  localizations: Record<string, Record<string, unknown>>;
+  status: LocalizedContentStatus;
+  enabled: boolean;
+  order: number;
+}
+
+/** Public delivery response for `GET /v1/content/pages/{slug}` — the negotiated
+ *  locale's resolved page + sections (the RFC 0103 `resolveSection` merge is
+ *  applied host-side: exact → language-family → base). */
+export interface LocalizedContentPageResponse {
+  /** Response schema version marker (e.g. `"1"`). */
+  version: string;
+  generatedAt: string;
+  /** The negotiated locale this response was resolved for. */
+  locale: string;
+  slug: string;
+  page: LocalizedContentPage;
+  sections: readonly LocalizedContentSection[];
+}
+
+/** Language settings (`schemas/localized-content-language-settings.schema.json`). */
+export interface LocalizedContentLanguageSettings {
+  baseLocale: string;
+  supportedLocales: readonly string[];
+  autoTranslateOnPublish: boolean;
+}
+
+/** Request body for `PUT /v1/content/pages/{pageId}/sections/{sectionId}`. */
+export interface PutContentSectionRequest {
+  /** Target locale; the baseLocale upserts `data`, else `localizations[locale]`. */
+  locale: string;
+  /** The field overlay for the target locale (host-defined open shape). */
+  data: Record<string, unknown>;
+}
+
+// ── RFC 0099 Trigger subscription registration (spec/v1/trigger-bridge.md §F) ──
+
+/** Registration body for `POST /v1/trigger-subscriptions`
+ *  (`schemas/trigger-subscription-registration.schema.json`). */
+export interface TriggerSubscriptionRegistration {
+  /** External event source descriptor (host-defined: webhook / email / form …). */
+  source: Record<string, unknown>;
+  workflowId: string;
+  dedupEnabled?: boolean;
+  inputMapping?: Record<string, unknown>;
+  retryPolicy?: Record<string, unknown>;
+  verification?: Record<string, unknown>;
+}
+
+/** The persisted trigger subscription the host assigns
+ *  (`schemas/trigger-subscription.schema.json`). Kept open beyond the
+ *  registration fields the host echoes back. */
+export type TriggerSubscription = Record<string, unknown>;
+
+/** `201` response for `POST /v1/trigger-subscriptions`. `binding` carries the
+ *  source-specific wiring the caller needs (e.g. `{ ingestUrl,
+ *  secretFingerprint }` for webhook); the secret is returned ONCE at creation
+ *  (SR-1) — persist it, it is not retrievable again. */
+export interface CreateTriggerSubscriptionResponse {
+  subscription: TriggerSubscription;
+  binding: Record<string, unknown>;
+}