recoder-a2a-sdk 1.0.0

package/dist/envelope-builders.d.mts

@@ -0,0 +1,189 @@
+import { TaskAgentRef, TaskState, TaskEnvelope, TaskResult, TaskErrorInfo } from '@recoder/shared/a2a/schemas';
+import { RecoderPayload } from '@recoder/shared/a2a';
+
+/**
+ * @module envelope-builders
+ *
+ * Convenience factory functions for creating `TaskEnvelope` instances
+ * pre-configured for specific connector platforms.
+ *
+ * These builders reduce boilerplate in adapter code by pre-filling the
+ * `connector`, `requester`, and `assignee` fields with sensible defaults
+ * for each platform while still allowing full override.
+ *
+ * @example
+ * ```ts
+ * import { buildCodexEnvelope, buildClaudeEnvelope } from '@recoder/a2a-sdk/envelope-builders';
+ *
+ * const codexEnv = buildCodexEnvelope({
+ *   id: 'task_01',
+ *   workspace_id: 'ws_abc',
+ *   thread_id: 'thr_def',
+ *   trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',
+ *   requester: { agent_id: 'agent-pm', platform: 'recoder_pm' },
+ *   payload: { kind: 'text', text: 'Implement auth flow' },
+ * });
+ * ```
+ */
+
+/**
+ * Minimal input for a connector-specific envelope builder.
+ * Fields that can be derived from the connector context are optional.
+ */
+interface ConnectorEnvelopeInput {
+    /** Unique task ID. */
+    id: string;
+    /** Workspace ID. */
+    workspace_id: string;
+    /** Thread ID. */
+    thread_id: string;
+    /** Trace ID (W3C Trace Context compatible). */
+    trace_id: string;
+    /** Optional parent span ID. */
+    parent_id?: string;
+    /** The requester agent reference. */
+    requester: TaskAgentRef;
+    /** Optional override for the assignee (defaults to the connector agent). */
+    assignee?: TaskAgentRef;
+    /** The task payload. */
+    payload: RecoderPayload | RecoderPayload[];
+    /** Optional metadata. */
+    metadata?: Record<string, unknown>;
+    /** Optional tags. */
+    tags?: string[];
+    /** Override the initial state (defaults to 'submitted'). */
+    initial_state?: TaskState;
+    /** Override the creation timestamp. */
+    now?: string;
+}
+/**
+ * Optional overrides specific to Codex envelopes.
+ */
+interface CodexEnvelopeOptions {
+    /** Override the Codex connector ID (defaults to 'codex-v1'). */
+    connector_id?: string;
+    /** Codex model name (stored in connector metadata). */
+    model?: string;
+    /** Codex API endpoint (stored in connector metadata). */
+    endpoint?: string;
+    /** Additional connector metadata. */
+    connector_metadata?: Record<string, unknown>;
+}
+/**
+ * Build a `TaskEnvelope` pre-configured for the Codex connector.
+ *
+ * Defaults:
+ * - `connector.platform`: `'codex'`
+ * - `connector.protocol`: `'jsonrpc'`
+ * - `connector.connector_id`: `'codex-v1'`
+ * - `assignee.platform`: `'codex'`
+ *
+ * @param input - The core envelope fields.
+ * @param options - Optional Codex-specific overrides.
+ * @returns A fully populated `TaskEnvelope`.
+ */
+declare function buildCodexEnvelope(input: ConnectorEnvelopeInput, options?: CodexEnvelopeOptions): TaskEnvelope;
+/**
+ * Optional overrides specific to Claude Code envelopes.
+ */
+interface ClaudeEnvelopeOptions {
+    /** Override the Claude connector ID (defaults to 'claude-code-v1'). */
+    connector_id?: string;
+    /** Claude model name (stored in connector metadata). */
+    model?: string;
+    /** Claude API endpoint (stored in connector metadata). */
+    endpoint?: string;
+    /** Maximum tokens for the Claude session. */
+    max_tokens?: number;
+    /** Additional connector metadata. */
+    connector_metadata?: Record<string, unknown>;
+}
+/**
+ * Build a `TaskEnvelope` pre-configured for the Claude Code connector.
+ *
+ * Defaults:
+ * - `connector.platform`: `'claude_code'`
+ * - `connector.protocol`: `'jsonrpc'`
+ * - `connector.connector_id`: `'claude-code-v1'`
+ * - `assignee.platform`: `'claude_code'`
+ *
+ * @param input - The core envelope fields.
+ * @param options - Optional Claude-specific overrides.
+ * @returns A fully populated `TaskEnvelope`.
+ */
+declare function buildClaudeEnvelope(input: ConnectorEnvelopeInput, options?: ClaudeEnvelopeOptions): TaskEnvelope;
+/**
+ * Apply a result to a completed task envelope.
+ *
+ * Transitions the envelope to `completed` and attaches the result payload.
+ *
+ * @param envelope - The current task envelope (must be in a non-terminal state).
+ * @param result - The result data.
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `completed` and the result attached.
+ */
+declare function completeEnvelope(envelope: TaskEnvelope, result: TaskResult, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Apply an error to a failed task envelope.
+ *
+ * Transitions the envelope to `failed` and attaches the error info.
+ *
+ * @param envelope - The current task envelope (must be in a non-terminal state).
+ * @param error - The error information.
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `failed` and the error attached.
+ */
+declare function failEnvelope(envelope: TaskEnvelope, error: TaskErrorInfo, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Cancel a task envelope.
+ *
+ * Transitions the envelope to `cancelled`.
+ *
+ * @param envelope - The current task envelope.
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `cancelled`.
+ */
+declare function cancelEnvelope(envelope: TaskEnvelope, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Start working on a task envelope.
+ *
+ * Transitions the envelope from `submitted` to `working`.
+ *
+ * @param envelope - The current task envelope (must be in `submitted` state).
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `working`.
+ */
+declare function startEnvelope(envelope: TaskEnvelope, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Convert a canonical `A2AError` to the `TaskErrorInfo` shape expected
+ * by the `TaskEnvelope.error` field.
+ *
+ * @param a2aError - The source A2AError.
+ * @returns A `TaskErrorInfo` suitable for embedding in an envelope.
+ */
+declare function a2aErrorToTaskErrorInfo(a2aError: {
+    code: string;
+    category: string;
+    message: string;
+    severity: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}): TaskErrorInfo;
+
+export { type ClaudeEnvelopeOptions, type CodexEnvelopeOptions, type ConnectorEnvelopeInput, a2aErrorToTaskErrorInfo, buildClaudeEnvelope, buildCodexEnvelope, cancelEnvelope, completeEnvelope, failEnvelope, startEnvelope };

package/dist/envelope-builders.d.ts

@@ -0,0 +1,189 @@
+import { TaskAgentRef, TaskState, TaskEnvelope, TaskResult, TaskErrorInfo } from '@recoder/shared/a2a/schemas';
+import { RecoderPayload } from '@recoder/shared/a2a';
+
+/**
+ * @module envelope-builders
+ *
+ * Convenience factory functions for creating `TaskEnvelope` instances
+ * pre-configured for specific connector platforms.
+ *
+ * These builders reduce boilerplate in adapter code by pre-filling the
+ * `connector`, `requester`, and `assignee` fields with sensible defaults
+ * for each platform while still allowing full override.
+ *
+ * @example
+ * ```ts
+ * import { buildCodexEnvelope, buildClaudeEnvelope } from '@recoder/a2a-sdk/envelope-builders';
+ *
+ * const codexEnv = buildCodexEnvelope({
+ *   id: 'task_01',
+ *   workspace_id: 'ws_abc',
+ *   thread_id: 'thr_def',
+ *   trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',
+ *   requester: { agent_id: 'agent-pm', platform: 'recoder_pm' },
+ *   payload: { kind: 'text', text: 'Implement auth flow' },
+ * });
+ * ```
+ */
+
+/**
+ * Minimal input for a connector-specific envelope builder.
+ * Fields that can be derived from the connector context are optional.
+ */
+interface ConnectorEnvelopeInput {
+    /** Unique task ID. */
+    id: string;
+    /** Workspace ID. */
+    workspace_id: string;
+    /** Thread ID. */
+    thread_id: string;
+    /** Trace ID (W3C Trace Context compatible). */
+    trace_id: string;
+    /** Optional parent span ID. */
+    parent_id?: string;
+    /** The requester agent reference. */
+    requester: TaskAgentRef;
+    /** Optional override for the assignee (defaults to the connector agent). */
+    assignee?: TaskAgentRef;
+    /** The task payload. */
+    payload: RecoderPayload | RecoderPayload[];
+    /** Optional metadata. */
+    metadata?: Record<string, unknown>;
+    /** Optional tags. */
+    tags?: string[];
+    /** Override the initial state (defaults to 'submitted'). */
+    initial_state?: TaskState;
+    /** Override the creation timestamp. */
+    now?: string;
+}
+/**
+ * Optional overrides specific to Codex envelopes.
+ */
+interface CodexEnvelopeOptions {
+    /** Override the Codex connector ID (defaults to 'codex-v1'). */
+    connector_id?: string;
+    /** Codex model name (stored in connector metadata). */
+    model?: string;
+    /** Codex API endpoint (stored in connector metadata). */
+    endpoint?: string;
+    /** Additional connector metadata. */
+    connector_metadata?: Record<string, unknown>;
+}
+/**
+ * Build a `TaskEnvelope` pre-configured for the Codex connector.
+ *
+ * Defaults:
+ * - `connector.platform`: `'codex'`
+ * - `connector.protocol`: `'jsonrpc'`
+ * - `connector.connector_id`: `'codex-v1'`
+ * - `assignee.platform`: `'codex'`
+ *
+ * @param input - The core envelope fields.
+ * @param options - Optional Codex-specific overrides.
+ * @returns A fully populated `TaskEnvelope`.
+ */
+declare function buildCodexEnvelope(input: ConnectorEnvelopeInput, options?: CodexEnvelopeOptions): TaskEnvelope;
+/**
+ * Optional overrides specific to Claude Code envelopes.
+ */
+interface ClaudeEnvelopeOptions {
+    /** Override the Claude connector ID (defaults to 'claude-code-v1'). */
+    connector_id?: string;
+    /** Claude model name (stored in connector metadata). */
+    model?: string;
+    /** Claude API endpoint (stored in connector metadata). */
+    endpoint?: string;
+    /** Maximum tokens for the Claude session. */
+    max_tokens?: number;
+    /** Additional connector metadata. */
+    connector_metadata?: Record<string, unknown>;
+}
+/**
+ * Build a `TaskEnvelope` pre-configured for the Claude Code connector.
+ *
+ * Defaults:
+ * - `connector.platform`: `'claude_code'`
+ * - `connector.protocol`: `'jsonrpc'`
+ * - `connector.connector_id`: `'claude-code-v1'`
+ * - `assignee.platform`: `'claude_code'`
+ *
+ * @param input - The core envelope fields.
+ * @param options - Optional Claude-specific overrides.
+ * @returns A fully populated `TaskEnvelope`.
+ */
+declare function buildClaudeEnvelope(input: ConnectorEnvelopeInput, options?: ClaudeEnvelopeOptions): TaskEnvelope;
+/**
+ * Apply a result to a completed task envelope.
+ *
+ * Transitions the envelope to `completed` and attaches the result payload.
+ *
+ * @param envelope - The current task envelope (must be in a non-terminal state).
+ * @param result - The result data.
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `completed` and the result attached.
+ */
+declare function completeEnvelope(envelope: TaskEnvelope, result: TaskResult, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Apply an error to a failed task envelope.
+ *
+ * Transitions the envelope to `failed` and attaches the error info.
+ *
+ * @param envelope - The current task envelope (must be in a non-terminal state).
+ * @param error - The error information.
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `failed` and the error attached.
+ */
+declare function failEnvelope(envelope: TaskEnvelope, error: TaskErrorInfo, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Cancel a task envelope.
+ *
+ * Transitions the envelope to `cancelled`.
+ *
+ * @param envelope - The current task envelope.
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `cancelled`.
+ */
+declare function cancelEnvelope(envelope: TaskEnvelope, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Start working on a task envelope.
+ *
+ * Transitions the envelope from `submitted` to `working`.
+ *
+ * @param envelope - The current task envelope (must be in `submitted` state).
+ * @param options - Optional reason and actor for the transition.
+ * @returns The updated envelope with state `working`.
+ */
+declare function startEnvelope(envelope: TaskEnvelope, options?: {
+    reason?: string;
+    triggered_by?: string;
+    now?: string;
+}): TaskEnvelope;
+/**
+ * Convert a canonical `A2AError` to the `TaskErrorInfo` shape expected
+ * by the `TaskEnvelope.error` field.
+ *
+ * @param a2aError - The source A2AError.
+ * @returns A `TaskErrorInfo` suitable for embedding in an envelope.
+ */
+declare function a2aErrorToTaskErrorInfo(a2aError: {
+    code: string;
+    category: string;
+    message: string;
+    severity: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}): TaskErrorInfo;
+
+export { type ClaudeEnvelopeOptions, type CodexEnvelopeOptions, type ConnectorEnvelopeInput, a2aErrorToTaskErrorInfo, buildClaudeEnvelope, buildCodexEnvelope, cancelEnvelope, completeEnvelope, failEnvelope, startEnvelope };