@openwop/openwop 1.2.0 → 1.4.0

package/src/client.ts

@@ -12,6 +12,13 @@ import { streamEvents, type EventsStreamOptions } from './sse.js';
 import {
   WopError,
   type AuditVerifyResult,
+  type CreateTriggerSubscriptionResponse,
+  type LocalizedContentLanguageSettings,
+  type LocalizedContentPage,
+  type LocalizedContentPageResponse,
+  type LocalizedContentSection,
+  type PutContentSectionRequest,
+  type TriggerSubscriptionRegistration,
   type BulkCancelRunsRequest,
   type BulkCancelRunsResponse,
   type Capabilities,
@@ -837,6 +844,108 @@ export class OpenwopClient {
     },
   };
 
+  // ── RFC 0103 Localized content surface (gated on capabilities.content) ──
+  readonly content = {
+    /** `GET /v1/content/pages` — list page records. Returns `null` when the
+     *  host doesn't advertise `capabilities.content` (501). */
+    listPages: async (): Promise<readonly LocalizedContentPage[] | null> => {
+      try {
+        return await this.#request<readonly LocalizedContentPage[]>({
+          method: 'GET',
+          path: '/v1/content/pages',
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 501) return null;
+        throw err;
+      }
+    },
+
+    /** `GET /v1/content/pages/{slug}` — the negotiated locale's resolved page +
+     *  sections. `acceptLanguage` rides the `Accept-Language` header (the Stable
+     *  `i18n.md` negotiation; no `?locale=`). Returns `null` on `404`
+     *  (no such published page) or `501` (uncapable). */
+    getPage: async (
+      slug: string,
+      acceptLanguage?: string,
+    ): Promise<LocalizedContentPageResponse | null> => {
+      try {
+        return await this.#request<LocalizedContentPageResponse>({
+          method: 'GET',
+          path: `/v1/content/pages/${encodeURIComponent(slug)}`,
+          ...(acceptLanguage
+            ? { headers: { 'Accept-Language': acceptLanguage } }
+            : {}),
+        });
+      } catch (err) {
+        if (err instanceof WopError && (err.status === 404 || err.status === 501))
+          return null;
+        throw err;
+      }
+    },
+
+    /** `POST /v1/content/pages` — create a page record (admin). Throws the
+     *  typed `WopError` on `400`/`401`/`403`. */
+    createPage: (body: LocalizedContentPage): Promise<LocalizedContentPage> =>
+      this.#request<LocalizedContentPage>({
+        method: 'POST',
+        path: '/v1/content/pages',
+        body,
+      }),
+
+    /** `PUT /v1/content/pages/{pageId}/sections/{sectionId}` — upsert a
+     *  section's field overlay for a locale (admin). */
+    putSection: (
+      pageId: string,
+      sectionId: string,
+      body: PutContentSectionRequest,
+    ): Promise<LocalizedContentSection> =>
+      this.#request<LocalizedContentSection>({
+        method: 'PUT',
+        path: `/v1/content/pages/${encodeURIComponent(pageId)}/sections/${encodeURIComponent(sectionId)}`,
+        body,
+      }),
+
+    /** `GET /v1/content/settings` — language settings. Returns `null` when the
+     *  host doesn't advertise `capabilities.content` (501). */
+    getSettings: async (): Promise<LocalizedContentLanguageSettings | null> => {
+      try {
+        return await this.#request<LocalizedContentLanguageSettings>({
+          method: 'GET',
+          path: '/v1/content/settings',
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 501) return null;
+        throw err;
+      }
+    },
+
+    /** `PUT /v1/content/settings` — replace language settings (admin). */
+    putSettings: (
+      body: LocalizedContentLanguageSettings,
+    ): Promise<LocalizedContentLanguageSettings> =>
+      this.#request<LocalizedContentLanguageSettings>({
+        method: 'PUT',
+        path: '/v1/content/settings',
+        body,
+      }),
+  };
+
+  // ── RFC 0099 Trigger subscriptions (gated on capabilities.triggerBridge) ──
+  readonly triggerSubscriptions = {
+    /** `POST /v1/trigger-subscriptions` — register an external-event trigger.
+     *  The `binding.secret*` is returned ONCE at creation (SR-1); persist it.
+     *  Throws the typed `WopError` on `400`/`401`/`403`, or `501` when the host
+     *  doesn't advertise the trigger-bridge ingestion surface. */
+    create: (
+      body: TriggerSubscriptionRegistration,
+    ): Promise<CreateTriggerSubscriptionResponse> =>
+      this.#request<CreateTriggerSubscriptionResponse>({
+        method: 'POST',
+        path: '/v1/trigger-subscriptions',
+        body,
+      }),
+  };
+
   // ── Agent workspace files (RFC 0059; gated on capabilities.workspace) ──
   readonly workspace = {
     /**

package/src/event-helpers.ts

@@ -36,8 +36,17 @@ import type {
   AgentToolCalledPayload,
   AgentToolReturnedPayload,
   MemoryWrittenPayload,
+  OutputChunkPayload,
   RunEventDoc,
   TypedRunEvent,
+  VoiceSpeechStartPayload,
+  VoiceTranscriptPayload,
+  VoiceEndpointCandidatePayload,
+  VoiceTurnCommitPayload,
+  VoiceSynthesisChunkPayload,
+  VoiceBargeInPayload,
+  VoiceCancelledPayload,
+  ChannelPresencePayload,
 } from './types.js';
 
 // ─── Type guards ────────────────────────────────────────────────────────
@@ -143,6 +152,113 @@ export function isMemoryWritten(
   );
 }
 
+/** `output.chunk` / `ai.message.chunk` (RFC 0094 §D). Accepts both
+ *  discriminators — `output.chunk` is the persisted run-event type;
+ *  `ai.message.chunk` is the stream-mode `messages` SSE event name
+ *  carrying the same payload per `stream-modes.md §messages`. Narrows
+ *  when the payload carries the required `nodeId` + `runId` + `chunk`
+ *  strings AND the boolean `isLast`. */
+export function isOutputChunk(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<OutputChunkPayload> {
+  if (ev.type !== 'output.chunk' && ev.type !== 'ai.message.chunk') return false;
+  if (!hasStringField(ev.payload, 'nodeId')) return false;
+  if (!hasStringField(ev.payload, 'runId')) return false;
+  if (!hasStringField(ev.payload, 'chunk')) return false;
+  return typeof (ev.payload as Record<string, unknown>).isLast === 'boolean';
+}
+
+function hasNumberField(payload: unknown, field: string): boolean {
+  return (
+    payload !== null &&
+    typeof payload === 'object' &&
+    typeof (payload as Record<string, unknown>)[field] === 'number'
+  );
+}
+
+/** `voice.speech_start` (RFC 0106). */
+export function isVoiceSpeechStart(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceSpeechStartPayload> {
+  return ev.type === 'voice.speech_start' && hasNumberField(ev.payload, 'atMs');
+}
+
+/** `voice.transcript` (RFC 0106). Narrows when `type` matches AND payload
+ *  carries the required `text` + `isFinal` + `atMs` + `contentTrust`. The
+ *  transcript is untrusted ingress (`voice-transcript-untrusted`). */
+export function isVoiceTranscript(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceTranscriptPayload> {
+  return (
+    ev.type === 'voice.transcript' &&
+    hasStringField(ev.payload, 'text') &&
+    typeof (ev.payload as Record<string, unknown>).isFinal === 'boolean' &&
+    hasNumberField(ev.payload, 'atMs') &&
+    (ev.payload as Record<string, unknown>).contentTrust === 'untrusted'
+  );
+}
+
+/** `voice.endpoint_candidate` (RFC 0106). */
+export function isVoiceEndpointCandidate(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceEndpointCandidatePayload> {
+  return (
+    ev.type === 'voice.endpoint_candidate' && hasNumberField(ev.payload, 'atMs')
+  );
+}
+
+/** `voice.turn_commit` (RFC 0106). Narrows when payload carries the required
+ *  `atMs` + `finalText` (the settled transcript). */
+export function isVoiceTurnCommit(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceTurnCommitPayload> {
+  return (
+    ev.type === 'voice.turn_commit' &&
+    hasNumberField(ev.payload, 'atMs') &&
+    hasStringField(ev.payload, 'finalText')
+  );
+}
+
+/** `voice.synthesis_chunk` (RFC 0106). Narrows when payload carries the
+ *  required `seq` (number) + `mimeType` (string). */
+export function isVoiceSynthesisChunk(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceSynthesisChunkPayload> {
+  return (
+    ev.type === 'voice.synthesis_chunk' &&
+    hasNumberField(ev.payload, 'seq') &&
+    hasStringField(ev.payload, 'mimeType')
+  );
+}
+
+/** `voice.barge_in` (RFC 0106). */
+export function isVoiceBargeIn(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceBargeInPayload> {
+  return ev.type === 'voice.barge_in' && hasNumberField(ev.payload, 'atMs');
+}
+
+/** `voice.cancelled` (RFC 0106). */
+export function isVoiceCancelled(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceCancelledPayload> {
+  return ev.type === 'voice.cancelled' && hasNumberField(ev.payload, 'atMs');
+}
+
+/** `channel.presence` (RFC 0110). EPHEMERAL — observable on the LIVE event
+ *  stream only; ABSENT on replay / `:fork` (the host never persists presence
+ *  to the replayable log). Narrows when payload carries `conversationId` +
+ *  a `present` array. */
+export function isChannelPresence(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<ChannelPresencePayload> {
+  return (
+    ev.type === 'channel.presence' &&
+    hasStringField(ev.payload, 'conversationId') &&
+    Array.isArray((ev.payload as Record<string, unknown>).present)
+  );
+}
+
 // ─── High-level subscription helper ─────────────────────────────────────
 
 /** Returned by {@link subscribeToAgentReasoning}. Call to cancel the

package/src/index.ts

@@ -59,6 +59,18 @@ export type {
   AgentHandoffPayload,
   AgentDecidedPayload,
   MemoryWrittenPayload,
+  // RFC 0094 §D — streaming output chunk (`output.chunk` / `ai.message.chunk`)
+  OutputChunkPayload,
+  // RFC 0106 — voice.* run-event payloads
+  VoiceSpeechStartPayload,
+  VoiceTranscriptPayload,
+  VoiceEndpointCandidatePayload,
+  VoiceTurnCommitPayload,
+  VoiceSynthesisChunkPayload,
+  VoiceBargeInPayload,
+  VoiceCancelledPayload,
+  // RFC 0110 — channel.presence run-event payload
+  ChannelPresencePayload,
   // RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md)
   GetPromptRequest,
   ListPromptsRequest,
@@ -113,6 +125,15 @@ export {
   isAgentHandoff,
   isAgentDecided,
   isMemoryWritten,
+  isOutputChunk,
+  isVoiceSpeechStart,
+  isVoiceTranscript,
+  isVoiceEndpointCandidate,
+  isVoiceTurnCommit,
+  isVoiceSynthesisChunk,
+  isVoiceBargeIn,
+  isVoiceCancelled,
+  isChannelPresence,
   subscribeToAgentReasoning,
 } from './event-helpers.js';
 export type {
@@ -180,6 +201,7 @@ export type {
 // AI Envelope types (DRAFT v1.x — spec/v1/ai-envelope.md). Inbound LLM-emission
 // envelope, distinct from RunEventDoc (outbound) and ErrorEnvelope (host HTTP).
 export type {
+  A2UISurfacePayload,
   AIEnvelope,
   AIEnvelopeErrorPayload,
   ClarificationRequestPayload,
@@ -193,6 +215,17 @@ export type {
   SchemaRequestPayload,
   SchemaResponsePayload,
   ValidationDetail,
+  // RFC 0103 — localized content surface
+  LocalizedContentStatus,
+  LocalizedContentPage,
+  LocalizedContentSection,
+  LocalizedContentPageResponse,
+  LocalizedContentLanguageSettings,
+  PutContentSectionRequest,
+  // RFC 0099 — trigger subscription registration
+  TriggerSubscriptionRegistration,
+  TriggerSubscription,
+  CreateTriggerSubscriptionResponse,
 } from './types.js';
 
 // RFC 0030 §A `reasoning` field prompt-directive helper. Hosts that

package/src/run-helpers.ts

@@ -18,11 +18,11 @@
  * the small known-non-terminal set is treated as terminal. This keeps
  * the helper correct against:
  *
- *   - the canonical 8-member spec union (`pending` / `running` / `paused`
- *     / `waiting-approval` / `waiting-input` / `completed` / `failed` /
- *     `cancelled`)
- *   - host extensions like `'planned'`, `'executing'`, `'waiting-external'`,
- *     `'timed-out'`, `'interrupted'` which the OpenWOP engine emits
+ *   - the canonical 10-member spec union (`pending` / `running` / `paused`
+ *     / `waiting-approval` / `waiting-input` / `waiting-external` /
+ *     `completed` / `failed` / `cancelling` / `cancelled`)
+ *   - host extensions like `'planned'`, `'executing'`, `'timed-out'`,
+ *     `'interrupted'` which the OpenWOP engine emits
  *   - any future spec additions before the SDK ships an updated minor
  *
  * @module @openwop/openwop/run-helpers
@@ -44,6 +44,10 @@ export const ACTIVE_RUN_STATUSES = [
   'paused',
   'waiting-approval',
   'waiting-input',
+  'waiting-external',
+  // RFC 0094 §B — transitional state during the cancel cascade; the run
+  // WILL still transition (to terminal `cancelled`), so it is active.
+  'cancelling',
 ] as const;
 
 /**