@relayflows/sdk 2.0.25 → 2.0.27

package/src/cloud-transcript-types.ts

@@ -0,0 +1,214 @@
+// The entry vocabulary `flows logs --step` renders, and the pure helpers both
+// provider parsers need.
+//
+// This module is a leaf: it imports nothing, so `cloud-transcript.ts` (the
+// public entry point and the Claude vocabulary) and `cloud-transcript-codex.ts`
+// can both depend on it without either depending on the other.
+//
+// The entry union is a public TypeScript API — `index.ts` re-exports it and
+// `flows logs --json` emits it. Everything added for Codex is either a new
+// member of the union or an optional field, so a Claude entry serializes to
+// exactly the bytes it serialized to before. A consumer switching
+// exhaustively over `kind` must still add the new members.
+
+export interface TranscriptAttempt {
+  kind: 'attempt';
+  attempt: number | null;
+  bytes: number | null;
+  truncated: boolean;
+}
+
+export interface TranscriptAttemptOmitted {
+  kind: 'attempt_omitted';
+  attempt: number | null;
+  bytes: number | null;
+}
+
+export interface TranscriptInit {
+  kind: 'init';
+  model: string | null;
+  version: string | null;
+  permission_mode: string | null;
+  tools: number | null;
+  mcp_servers: number | null;
+  session_id: string | null;
+}
+
+export interface TranscriptMessage {
+  kind: 'message';
+  role: 'assistant' | 'user';
+  text: string;
+  /** A frame carrying `parent_tool_use_id`: a subagent's turn, not the main one. */
+  nested: boolean;
+  /**
+   * Codex only, and only when false: the message was read off an
+   * `item.started`/`item.updated` snapshot that never completed, so the text
+   * is what had been written so far and not the whole of it.
+   */
+  complete?: boolean;
+}
+
+export interface TranscriptThinking {
+  kind: 'thinking';
+  /** The count only. A thinking block's text and signature never reach the page. */
+  chars: number;
+  nested: boolean;
+}
+
+/**
+ * The Codex half of a tool call. Present on an entry parsed from a Codex
+ * `command_execution` or `mcp_tool_call` item and absent on every Claude
+ * entry, which is what the renderer discriminates on: a Codex failure has to
+ * keep its exit code, its status and its result size on the same line, where
+ * Claude's renderer replaces the size with `ERROR`.
+ */
+export interface TranscriptToolCodex {
+  /** The call's position among the calls of its attempt, counted from 1. */
+  seq: number;
+  /** `in_progress`, `completed` or `failed`, as the item reported it. */
+  status: string | null;
+  /** Null when the item carried no exit code — not the same fact as exit 0. */
+  exit_code: number | null;
+  /** Redacted, then bounded. Null when the item carried no output field at all. */
+  output_excerpt: string | null;
+  /** True when a character or line bound cut the excerpt. */
+  output_truncated: boolean;
+  /** False when no `item.completed` ever arrived for this call. */
+  complete: boolean;
+  /** Redacted, then bounded. The item's own failure text. */
+  error: string | null;
+}
+
+export interface TranscriptTool {
+  kind: 'tool';
+  name: string;
+  /** What the call was aimed at: a path, a command, a pattern. Null when the input had no string. */
+  target: string | null;
+  /** Null when no `tool_result` answered it -- not the same fact as a zero-byte result. */
+  result_chars: number | null;
+  is_error: boolean;
+  nested: boolean;
+  /** Codex only. Its presence is what tells the renderer which shape to print. */
+  codex?: TranscriptToolCodex;
+}
+
+/** One `apply_patch` item: file activity, not a tool call, so it is not numbered. */
+export interface TranscriptFileChange {
+  kind: 'file_change';
+  changes: Array<{ path: string | null; change: string | null }>;
+  /** Change elements that were not objects. Counted rather than dropped. */
+  malformed: number;
+  status: string | null;
+  complete: boolean;
+}
+
+export interface TranscriptThread {
+  kind: 'thread';
+  thread_id: string | null;
+}
+
+export interface TranscriptTurn {
+  kind: 'turn';
+  phase: 'started' | 'completed' | 'failed';
+  tokens_in: number | null;
+  tokens_out: number | null;
+  cache_read: number | null;
+  cache_creation: number | null;
+  reasoning_out: number | null;
+}
+
+/** A `turn.failed`, a top-level `error` frame, or an `error` item. */
+export interface TranscriptError {
+  kind: 'error';
+  /** The frame this came from, so the reader knows what failed. */
+  source: string;
+  message: string;
+}
+
+export interface TranscriptResult {
+  kind: 'result';
+  is_error: boolean;
+  subtype: string | null;
+  duration_ms: number | null;
+  num_turns: number | null;
+  total_cost_usd: number | null;
+  tokens_in: number | null;
+  tokens_out: number | null;
+  cache_read: number | null;
+  cache_creation: number | null;
+}
+
+export interface TranscriptUnknown {
+  kind: 'unknown';
+  type: string;
+  chars: number;
+}
+
+export interface TranscriptUnparsed {
+  kind: 'unparsed';
+  text: string;
+}
+
+export type TranscriptEntry =
+  | TranscriptAttempt | TranscriptAttemptOmitted | TranscriptInit | TranscriptMessage
+  | TranscriptThinking | TranscriptTool | TranscriptFileChange | TranscriptThread
+  | TranscriptTurn | TranscriptError | TranscriptResult | TranscriptUnknown | TranscriptUnparsed;
+
+export interface ParsedTranscript {
+  entries: TranscriptEntry[];
+  /** How many attempts said their head was cut to fit the log cap. */
+  truncated_attempts: number;
+  /** How many attempts were dropped whole to fit the log cap. */
+  omitted_attempts: number;
+  /**
+   * False when the log carried no frame either vocabulary this module knows --
+   * a v1 plain-terminal sandbox log, say. The caller prints it raw rather than
+   * claiming an empty transcript.
+   */
+  stream_json: boolean;
+}
+
+/** A command, an argument list or a `server/tool` pair on one line. */
+export const TARGET_MAX_CHARS = 160;
+
+/** A command's or a tool's output excerpt: enough to read, bounded either way. */
+export const OUTPUT_MAX_CHARS = 1000;
+export const OUTPUT_MAX_LINES = 10;
+
+/** Provider-supplied failure text. Prose from the agent is the only uncapped string. */
+export const ERROR_MAX_CHARS = 1000;
+
+/** A path stays identifiable, so it is bounded far above a one-line target. */
+export const PATH_MAX_CHARS = 200;
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function str(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+export function num(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** Collapse to one line and bound it; a tool input can be a whole file body. */
+export function oneLine(text: string, limit = TARGET_MAX_CHARS): string {
+  const flat = text.replace(/\s+/gu, ' ').trim();
+  return flat.length <= limit ? flat : `${flat.slice(0, limit)}…`;
+}
+
+export function thousands(value: number): string {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
+}
+
+/** Terminal control characters never reach the page, wherever the text came from. */
+export function safe(text: string): string {
+  return text.replace(/[\u0000-\u0009\u000B-\u001F\u007F-\u009F]/gu, '?');
+}
+
+/** One rule with a label, the way an attempt boundary reads. */
+export function separator(label: string): string {
+  return `── ${label} ${'─'.repeat(Math.max(2, 68 - label.length))}`;
+}

package/src/cloud-transcript.ts

@@ -1,13 +1,16 @@
 // Rendering an agent step's transcript JSONL for a terminal.
 //
-// The frames are what the harness wrote (Claude Code's `stream-json`), wrapped
-// by the `relayflow.attempt` markers the v2 executor interleaves when it
-// assembles one log out of several attempts. The frame vocabulary read here is
-// the one Cloud's dashboard renderer reads (cloud#3847,
-// `packages/web/lib/workflows/agent-transcript.ts`) -- the same shapes, so the
-// CLI and the dashboard agree about what a run did. The implementation is not
-// shared: this package cannot import from the Cloud app, and a CLI that had to
-// be deployed in step with a dashboard would be worse than one that does not.
+// The frames are what the harness wrote -- Claude Code's `stream-json`, or
+// `codex exec --json` -- wrapped by the `relayflow.attempt` markers the v2
+// executor interleaves when it assembles one log out of several attempts.
+// The Claude frame vocabulary read here is the one Cloud's dashboard renderer
+// reads (cloud#3847, `packages/web/lib/workflows/agent-transcript.ts`) -- the
+// same shapes, so the CLI and the dashboard agree about what a run did. The
+// implementation is not shared: this package cannot import from the Cloud app,
+// and a CLI that had to be deployed in step with a dashboard would be worse
+// than one that does not. The Codex vocabulary lives in
+// `cloud-transcript-codex.ts`; dispatch is per frame, not per provider, so a
+// log that mixes them stays honest rather than being forced into a guess.
 //
 // Two rules the shapes do not give you:
 //
@@ -19,98 +22,21 @@
 //    the redactor `flows status` uses. Transcript text is whatever the agent
 //    printed, including anything it read out of its own environment.
 
+import {
+  CODEX_FRAME_TYPES, codexFrame, indexCodexItems, renderCodexEntry, type CodexState,
+} from './cloud-transcript-codex.js';
+import {
+  TARGET_MAX_CHARS, isRecord, num, oneLine, safe, separator, str, thousands,
+  type ParsedTranscript, type TranscriptEntry,
+} from './cloud-transcript-types.js';
 import { redact } from './redact.js';
 
-export interface TranscriptAttempt {
-  kind: 'attempt';
-  attempt: number | null;
-  bytes: number | null;
-  truncated: boolean;
-}
-
-export interface TranscriptAttemptOmitted {
-  kind: 'attempt_omitted';
-  attempt: number | null;
-  bytes: number | null;
-}
-
-export interface TranscriptInit {
-  kind: 'init';
-  model: string | null;
-  version: string | null;
-  permission_mode: string | null;
-  tools: number | null;
-  mcp_servers: number | null;
-  session_id: string | null;
-}
-
-export interface TranscriptMessage {
-  kind: 'message';
-  role: 'assistant' | 'user';
-  text: string;
-  /** A frame carrying `parent_tool_use_id`: a subagent's turn, not the main one. */
-  nested: boolean;
-}
-
-export interface TranscriptThinking {
-  kind: 'thinking';
-  /** The count only. A thinking block's text and signature never reach the page. */
-  chars: number;
-  nested: boolean;
-}
-
-export interface TranscriptTool {
-  kind: 'tool';
-  name: string;
-  /** What the call was aimed at: a path, a command, a pattern. Null when the input had no string. */
-  target: string | null;
-  /** Null when no `tool_result` answered it -- not the same fact as a zero-byte result. */
-  result_chars: number | null;
-  is_error: boolean;
-  nested: boolean;
-}
-
-export interface TranscriptResult {
-  kind: 'result';
-  is_error: boolean;
-  subtype: string | null;
-  duration_ms: number | null;
-  num_turns: number | null;
-  total_cost_usd: number | null;
-  tokens_in: number | null;
-  tokens_out: number | null;
-  cache_read: number | null;
-  cache_creation: number | null;
-}
-
-export interface TranscriptUnknown {
-  kind: 'unknown';
-  type: string;
-  chars: number;
-}
-
-export interface TranscriptUnparsed {
-  kind: 'unparsed';
-  text: string;
-}
-
-export type TranscriptEntry =
-  | TranscriptAttempt | TranscriptAttemptOmitted | TranscriptInit | TranscriptMessage
-  | TranscriptThinking | TranscriptTool | TranscriptResult | TranscriptUnknown | TranscriptUnparsed;
-
-export interface ParsedTranscript {
-  entries: TranscriptEntry[];
-  /** How many attempts said their head was cut to fit the log cap. */
-  truncated_attempts: number;
-  /** How many attempts were dropped whole to fit the log cap. */
-  omitted_attempts: number;
-  /**
-   * False when the log carried no frame this vocabulary knows -- a v1
-   * plain-terminal sandbox log, say. The caller prints it raw rather than
-   * claiming an empty transcript.
-   */
-  stream_json: boolean;
-}
+export type {
+  ParsedTranscript, TranscriptEntry, TranscriptAttempt, TranscriptAttemptOmitted, TranscriptError,
+  TranscriptFileChange, TranscriptInit, TranscriptMessage, TranscriptResult, TranscriptThinking,
+  TranscriptThread, TranscriptTool, TranscriptToolCodex, TranscriptTurn, TranscriptUnknown,
+  TranscriptUnparsed,
+} from './cloud-transcript-types.js';
 
 /**
  * Which input field names a tool call. Order matters: the first present
@@ -122,26 +48,6 @@ const TARGET_KEYS = [
   'prompt', 'description', 'subagent_type',
 ] as const;
 
-const TARGET_MAX_CHARS = 160;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function str(value: unknown): string | null {
-  return typeof value === 'string' && value.length > 0 ? value : null;
-}
-
-function num(value: unknown): number | null {
-  return typeof value === 'number' && Number.isFinite(value) ? value : null;
-}
-
-/** Collapse to one line and bound it; a tool input can be a whole file body. */
-function oneLine(text: string, limit = TARGET_MAX_CHARS): string {
-  const flat = text.replace(/\s+/gu, ' ').trim();
-  return flat.length <= limit ? flat : `${flat.slice(0, limit)}…`;
-}
-
 /**
  * `clean` runs before `oneLine`, not after, and the order is load-bearing.
  *
@@ -154,12 +60,12 @@ function toolTarget(input: unknown, clean: (text: string) => string): string | n
   if (!isRecord(input)) return null;
   for (const key of TARGET_KEYS) {
     const value = str(input[key]);
-    if (value !== null) return oneLine(clean(value));
+    if (value !== null) return oneLine(clean(value), TARGET_MAX_CHARS);
   }
   // An unfamiliar tool still shows something rather than nothing.
   for (const value of Object.values(input)) {
     const text = str(value);
-    if (text !== null) return oneLine(clean(text));
+    if (text !== null) return oneLine(clean(text), TARGET_MAX_CHARS);
   }
   return null;
 }
@@ -219,13 +125,15 @@ export function parseAgentTranscript(content: string, env: NodeJS.ProcessEnv = p
     }
   }
   const results = indexToolResults(frames);
+  const codexIndex = indexCodexItems(raw);
+  const codexState: CodexState = { seq: 0 };
   const entries: TranscriptEntry[] = [];
   let truncatedAttempts = 0;
   let omittedAttempts = 0;
   let streamJson = false;
   const clean = (text: string): string => redact(text, env);
 
-  for (const { frame, line } of raw) {
+  for (const [index, { frame, line }] of raw.entries()) {
     if (frame === undefined || !isRecord(frame)) {
       entries.push({ kind: 'unparsed', text: clean(line) });
       continue;
@@ -233,6 +141,8 @@ export function parseAgentTranscript(content: string, env: NodeJS.ProcessEnv = p
     const type = str(frame['type']);
     if (type === 'relayflow.attempt') {
       streamJson = true;
+      // Calls are numbered within an attempt, so a second attempt starts over.
+      codexState.seq = 0;
       const truncated = frame['truncated'] === true;
       if (truncated) truncatedAttempts += 1;
       entries.push({ kind: 'attempt', attempt: num(frame['attempt']), bytes: num(frame['bytes']), truncated });
@@ -240,10 +150,16 @@ export function parseAgentTranscript(content: string, env: NodeJS.ProcessEnv = p
     }
     if (type === 'relayflow.attempt.omitted') {
       streamJson = true;
+      codexState.seq = 0;
       omittedAttempts += 1;
       entries.push({ kind: 'attempt_omitted', attempt: num(frame['attempt']), bytes: num(frame['bytes']) });
       continue;
     }
+    if (type !== null && CODEX_FRAME_TYPES.has(type)) {
+      streamJson = true;
+      entries.push(...(codexFrame(frame, type, index, codexIndex, codexState, clean, line) ?? []));
+      continue;
+    }
     if (type === 'system' && frame['subtype'] === 'init') {
       streamJson = true;
       const tools = frame['tools'];
@@ -327,28 +243,14 @@ export function parseAgentTranscript(content: string, env: NodeJS.ProcessEnv = p
   return { entries, truncated_attempts: truncatedAttempts, omitted_attempts: omittedAttempts, stream_json: streamJson };
 }
 
-function thousands(value: number): string {
-  return String(value).replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
-}
-
 function seconds(ms: number): string {
   return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
 
-/** Terminal control characters never reach the page, wherever the text came from. */
-function safe(text: string): string {
-  return text.replace(/[\u0000-\u0009\u000B-\u001F\u007F-\u009F]/gu, '?');
-}
-
 function dollars(value: number): string {
   return `$${value.toFixed(6).replace(/0+$/u, '').replace(/\.$/u, '')}`;
 }
 
-/** One rule with a label, the way an attempt boundary reads. */
-function separator(label: string): string {
-  return `── ${label} ${'─'.repeat(Math.max(2, 68 - label.length))}`;
-}
-
 /**
  * Render a parsed transcript as terminal lines.
  *
@@ -359,6 +261,11 @@ function separator(label: string): string {
 export function renderAgentTranscript(parsed: ParsedTranscript): string[] {
   const lines: string[] = [];
   for (const entry of parsed.entries) {
+    // A Codex tool call carries its exit code, its status and its result size
+    // on one line, which the Claude shape below has no room for; everything
+    // the Codex vocabulary owns is rendered there.
+    const codex = renderCodexEntry(entry);
+    if (codex !== undefined) { lines.push(...codex); continue; }
     switch (entry.kind) {
       case 'attempt': {
         const size = entry.bytes === null ? '' : ` · ${thousands(entry.bytes)} bytes`;
@@ -380,7 +287,8 @@ export function renderAgentTranscript(parsed: ParsedTranscript): string[] {
         break;
       }
       case 'message': {
-        const who = `${entry.role}${entry.nested ? ' (subagent)' : ''}`;
+        const state = entry.complete === false ? ' (incomplete)' : '';
+        const who = `${entry.role}${entry.nested ? ' (subagent)' : ''}${state}`;
         const body = entry.text.split('\n');
         lines.push(`${who}:`);
         for (const line of body) lines.push(`  ${safe(line)}`);

package/src/flow-extension-loader.ts

@@ -99,6 +99,93 @@ function subscriptionOf(handler: TriggerHandler): { provider: string; event: str
   return action === undefined ? { provider, event: type } : { provider, event: type, action };
 }
 
+/**
+ * Server-authenticated integration delivery metadata. This is executor
+ * authority, not authored input: a caller must derive it from its verified
+ * delivery record and pass it out of band. User-controlled `input.event`
+ * objects never become this value.
+ */
+const HOSTED_EXTENSION_DISPATCH_AUTHORITY = Symbol('hosted-extension-dispatch-authority');
+
+export type HostedExtensionDispatch = {
+  readonly [HOSTED_EXTENSION_DISPATCH_AUTHORITY]: true;
+  readonly provenance: 'integration-watch';
+  readonly provider: string;
+  readonly eventType: string;
+  readonly deliveryId: string;
+};
+
+type HostedEventIdentity = { readonly provider: string; readonly event: string; readonly action?: string };
+const DISPATCH_PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const DISPATCH_EVENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DISPATCH_DELIVERY = /^[A-Za-z0-9_.:-]{1,200}$/;
+
+function hostedEventIdentity(dispatch: unknown): HostedEventIdentity {
+  if (typeof dispatch !== 'object' || dispatch === null || Array.isArray(dispatch)) {
+    throw new PluginError('plugin_event_unroutable', 'Hosted extension dispatch authority is malformed.');
+  }
+  const { provenance, provider, eventType, deliveryId } = dispatch as Partial<HostedExtensionDispatch>;
+  if ((dispatch as Partial<HostedExtensionDispatch>)[HOSTED_EXTENSION_DISPATCH_AUTHORITY] !== true
+    || provenance !== 'integration-watch'
+    || typeof provider !== 'string' || !DISPATCH_PROVIDER.test(provider)
+    || typeof deliveryId !== 'string' || !DISPATCH_DELIVERY.test(deliveryId)
+    || typeof eventType !== 'string') {
+    throw new PluginError('plugin_event_unroutable', 'Hosted extension dispatch authority is malformed.');
+  }
+  const parts = eventType.split('.');
+  if ((parts.length !== 1 && parts.length !== 2) || parts.some(part => !DISPATCH_EVENT.test(part))) {
+    throw new PluginError('plugin_event_unroutable', `Hosted extension event ${JSON.stringify(eventType)} is malformed.`);
+  }
+  return parts.length === 1
+    ? { provider, event: parts[0]! }
+    : { provider, event: parts[0]!, action: parts[1]! };
+}
+
+/**
+ * Brand metadata only after the host has authenticated the integration
+ * delivery. The symbol is deliberately not serializable, so copying a direct
+ * run's JSON into executor options cannot mint dispatch authority.
+ */
+export function hostedExtensionDispatchFromVerifiedDelivery(
+  delivery: Omit<HostedExtensionDispatch, typeof HOSTED_EXTENSION_DISPATCH_AUTHORITY | 'provenance'>,
+): HostedExtensionDispatch {
+  const dispatch = Object.freeze({
+    [HOSTED_EXTENSION_DISPATCH_AUTHORITY]: true as const,
+    provenance: 'integration-watch' as const,
+    ...delivery,
+  });
+  hostedEventIdentity(dispatch);
+  return dispatch;
+}
+
+/**
+ * Resolve a server-authenticated delivery to one extension handler. Authored
+ * input is deliberately absent from this API: direct runs may contain any
+ * JSON shape and cannot opt themselves into extension execution. Overlapping
+ * subscriptions fail closed, including a generic event handler overlapping
+ * an action-specific handler.
+ */
+export function extensionHandlerForHostedDispatch(
+  dispatch: unknown,
+  extensions: readonly Pick<LoadedFlowExtension, 'name' | 'handlers'>[],
+): { readonly extension: Pick<LoadedFlowExtension, 'name' | 'handlers'>; readonly handler: TriggerHandler } | undefined {
+  if (dispatch === undefined) return undefined;
+  const identity = hostedEventIdentity(dispatch);
+  const matches = extensions.flatMap(extension => extension.handlers.flatMap(handler => {
+    const subscription = subscriptionOf(handler);
+    if (subscription === undefined || subscription.provider !== identity.provider || subscription.event !== identity.event) return [];
+    if (subscription.action !== undefined && subscription.action !== identity.action) return [];
+    return [{ extension, handler }];
+  }));
+  if (matches.length > 1) {
+    throw new PluginError(
+      'plugin_event_ambiguous',
+      `Hosted event ${identity.provider}.${identity.event}${identity.action === undefined ? '' : `.${identity.action}`} matches multiple extension handlers (${matches.map(match => match.extension.name).join(', ')}).`,
+    );
+  }
+  return matches[0];
+}
+
 function assertDeclaredSubscription(name: string, manifest: FlowExtensionManifest, handler: TriggerHandler, index: number): void {
   const subscription = subscriptionOf(handler);
   if (handler.trigger.kind === 'schedule') unsupported(name, `handler ${index} (a schedule trigger)`);

package/src/plugin-manifest.ts

@@ -7,6 +7,7 @@ export const PLUGIN_FAILURE_KINDS = [
   'plugin_unsupported', 'plugin_credential_missing', 'plugin_server_unreachable',
   // schema 2 flow extensions (see flow-extension-manifest.ts, plugin-source.ts, plugin-github.ts)
   'plugin_kind_invalid', 'plugin_incompatible', 'plugin_event_unroutable', 'plugin_source_invalid',
+  'plugin_event_ambiguous',
   'plugin_source_unresolved', 'plugin_fetch_failed', 'plugin_path_invalid', 'plugin_too_large',
   'plugin_source_drift', 'plugin_lock_invalid',
 ] as const;