recoder-a2a-sdk 1.0.0

package/dist/state-mapping.d.mts

@@ -0,0 +1,139 @@
+import { TaskState } from '@recoder/shared/a2a/schemas';
+
+/**
+ * @module state-mapping
+ *
+ * Task state mapping helpers for connector adapters.
+ *
+ * Each external connector (Codex, Claude Code, etc.) has its own native state
+ * vocabulary. This module provides bidirectional mapping functions that
+ * translate between connector-specific states and the canonical
+ * `TaskState` enum defined in `@recoder/shared/a2a/schemas`.
+ *
+ * Adapter authors should use these mappers at the boundary where connector
+ * events enter (or leave) the Recoder A2A control plane, ensuring that all
+ * internal logic operates exclusively on canonical states.
+ *
+ * @example
+ * ```ts
+ * import { mapCodexState, mapClaudeState } from '@recoder/a2a-sdk/state-mapping';
+ *
+ * const canonical = mapCodexState('running');   // => 'working'
+ * const claude    = mapClaudeState('streaming'); // => 'working'
+ * ```
+ */
+
+/** Supported connector platforms for state mapping. */
+type ConnectorPlatform = 'codex' | 'claude_code';
+/**
+ * Native states reported by the OpenAI Codex CLI / API adapter.
+ * These are the raw status strings that appear in Codex task events.
+ */
+type CodexNativeState = 'queued' | 'running' | 'waiting_for_input' | 'completed' | 'failed' | 'error' | 'cancelled' | 'timeout';
+/**
+ * Map a Codex native state string to the canonical `TaskState`.
+ *
+ * @param nativeState - The raw state string from a Codex event.
+ * @returns The canonical `TaskState`, or `undefined` if the state is unknown.
+ */
+declare function mapCodexState(nativeState: string): TaskState | undefined;
+/**
+ * Map a Codex native state to canonical, throwing if the state is unknown.
+ *
+ * @param nativeState - The raw state string from a Codex event.
+ * @returns The canonical `TaskState`.
+ * @throws {Error} If the state cannot be mapped.
+ */
+declare function mapCodexStateStrict(nativeState: string): TaskState;
+/**
+ * Map a canonical `TaskState` back to the primary Codex native state.
+ *
+ * @param canonicalState - The canonical task state.
+ * @returns The Codex native state string.
+ */
+declare function canonicalToCodexState(canonicalState: TaskState): CodexNativeState;
+/**
+ * Native states reported by the Claude Code CLI / API adapter.
+ * These are the raw status strings that appear in Claude Code events.
+ */
+type ClaudeNativeState = 'pending' | 'streaming' | 'processing' | 'waiting_for_approval' | 'waiting_for_input' | 'done' | 'completed' | 'error' | 'failed' | 'aborted' | 'cancelled' | 'timeout';
+/**
+ * Map a Claude Code native state string to the canonical `TaskState`.
+ *
+ * @param nativeState - The raw state string from a Claude Code event.
+ * @returns The canonical `TaskState`, or `undefined` if the state is unknown.
+ */
+declare function mapClaudeState(nativeState: string): TaskState | undefined;
+/**
+ * Map a Claude Code native state to canonical, throwing if the state is unknown.
+ *
+ * @param nativeState - The raw state string from a Claude Code event.
+ * @returns The canonical `TaskState`.
+ * @throws {Error} If the state cannot be mapped.
+ */
+declare function mapClaudeStateStrict(nativeState: string): TaskState;
+/**
+ * Map a canonical `TaskState` back to the primary Claude Code native state.
+ *
+ * @param canonicalState - The canonical task state.
+ * @returns The Claude Code native state string.
+ */
+declare function canonicalToClaudeState(canonicalState: TaskState): ClaudeNativeState;
+/**
+ * Map a native state from any supported connector to canonical `TaskState`.
+ *
+ * @param platform - The connector platform identifier.
+ * @param nativeState - The raw state string from the connector.
+ * @returns The canonical `TaskState`, or `undefined` if unmappable.
+ */
+declare function mapConnectorState(platform: ConnectorPlatform, nativeState: string): TaskState | undefined;
+/**
+ * Map a native state from any supported connector to canonical `TaskState`,
+ * throwing if the mapping fails.
+ *
+ * @param platform - The connector platform identifier.
+ * @param nativeState - The raw state string from the connector.
+ * @returns The canonical `TaskState`.
+ * @throws {Error} If the platform or state is unknown.
+ */
+declare function mapConnectorStateStrict(platform: ConnectorPlatform, nativeState: string): TaskState;
+/**
+ * Map a canonical `TaskState` back to the primary native state for a given
+ * connector platform.
+ *
+ * @param platform - The connector platform identifier.
+ * @param canonicalState - The canonical task state.
+ * @returns The native state string, or `undefined` if the platform is unknown.
+ */
+declare function canonicalToConnectorState(platform: ConnectorPlatform, canonicalState: TaskState): string | undefined;
+/**
+ * Given the current canonical state and a new native state from a connector,
+ * determine whether the implied transition is valid according to the
+ * canonical lifecycle rules.
+ *
+ * This is the main "guard" function that adapters should call before
+ * applying a state update from a connector event.
+ *
+ * @param currentCanonical - The current canonical task state.
+ * @param platform - The connector platform identifier.
+ * @param newNativeState - The new native state reported by the connector.
+ * @returns An object indicating whether the transition is valid, the mapped
+ *          canonical state, and an error message if invalid.
+ */
+declare function checkConnectorTransition(currentCanonical: TaskState, platform: ConnectorPlatform, newNativeState: string): {
+    valid: boolean;
+    mappedState: TaskState | undefined;
+    error?: string;
+};
+/**
+ * Check whether a connector-reported native state maps to a terminal
+ * canonical state.
+ *
+ * @param platform - The connector platform identifier.
+ * @param nativeState - The native state to check.
+ * @returns `true` if the mapped canonical state is terminal; `false` if
+ *          non-terminal or unmappable.
+ */
+declare function isConnectorTerminalState(platform: ConnectorPlatform, nativeState: string): boolean;
+
+export { type ClaudeNativeState, type CodexNativeState, type ConnectorPlatform, canonicalToClaudeState, canonicalToCodexState, canonicalToConnectorState, checkConnectorTransition, isConnectorTerminalState, mapClaudeState, mapClaudeStateStrict, mapCodexState, mapCodexStateStrict, mapConnectorState, mapConnectorStateStrict };

package/dist/state-mapping.d.ts

@@ -0,0 +1,139 @@
+import { TaskState } from '@recoder/shared/a2a/schemas';
+
+/**
+ * @module state-mapping
+ *
+ * Task state mapping helpers for connector adapters.
+ *
+ * Each external connector (Codex, Claude Code, etc.) has its own native state
+ * vocabulary. This module provides bidirectional mapping functions that
+ * translate between connector-specific states and the canonical
+ * `TaskState` enum defined in `@recoder/shared/a2a/schemas`.
+ *
+ * Adapter authors should use these mappers at the boundary where connector
+ * events enter (or leave) the Recoder A2A control plane, ensuring that all
+ * internal logic operates exclusively on canonical states.
+ *
+ * @example
+ * ```ts
+ * import { mapCodexState, mapClaudeState } from '@recoder/a2a-sdk/state-mapping';
+ *
+ * const canonical = mapCodexState('running');   // => 'working'
+ * const claude    = mapClaudeState('streaming'); // => 'working'
+ * ```
+ */
+
+/** Supported connector platforms for state mapping. */
+type ConnectorPlatform = 'codex' | 'claude_code';
+/**
+ * Native states reported by the OpenAI Codex CLI / API adapter.
+ * These are the raw status strings that appear in Codex task events.
+ */
+type CodexNativeState = 'queued' | 'running' | 'waiting_for_input' | 'completed' | 'failed' | 'error' | 'cancelled' | 'timeout';
+/**
+ * Map a Codex native state string to the canonical `TaskState`.
+ *
+ * @param nativeState - The raw state string from a Codex event.
+ * @returns The canonical `TaskState`, or `undefined` if the state is unknown.
+ */
+declare function mapCodexState(nativeState: string): TaskState | undefined;
+/**
+ * Map a Codex native state to canonical, throwing if the state is unknown.
+ *
+ * @param nativeState - The raw state string from a Codex event.
+ * @returns The canonical `TaskState`.
+ * @throws {Error} If the state cannot be mapped.
+ */
+declare function mapCodexStateStrict(nativeState: string): TaskState;
+/**
+ * Map a canonical `TaskState` back to the primary Codex native state.
+ *
+ * @param canonicalState - The canonical task state.
+ * @returns The Codex native state string.
+ */
+declare function canonicalToCodexState(canonicalState: TaskState): CodexNativeState;
+/**
+ * Native states reported by the Claude Code CLI / API adapter.
+ * These are the raw status strings that appear in Claude Code events.
+ */
+type ClaudeNativeState = 'pending' | 'streaming' | 'processing' | 'waiting_for_approval' | 'waiting_for_input' | 'done' | 'completed' | 'error' | 'failed' | 'aborted' | 'cancelled' | 'timeout';
+/**
+ * Map a Claude Code native state string to the canonical `TaskState`.
+ *
+ * @param nativeState - The raw state string from a Claude Code event.
+ * @returns The canonical `TaskState`, or `undefined` if the state is unknown.
+ */
+declare function mapClaudeState(nativeState: string): TaskState | undefined;
+/**
+ * Map a Claude Code native state to canonical, throwing if the state is unknown.
+ *
+ * @param nativeState - The raw state string from a Claude Code event.
+ * @returns The canonical `TaskState`.
+ * @throws {Error} If the state cannot be mapped.
+ */
+declare function mapClaudeStateStrict(nativeState: string): TaskState;
+/**
+ * Map a canonical `TaskState` back to the primary Claude Code native state.
+ *
+ * @param canonicalState - The canonical task state.
+ * @returns The Claude Code native state string.
+ */
+declare function canonicalToClaudeState(canonicalState: TaskState): ClaudeNativeState;
+/**
+ * Map a native state from any supported connector to canonical `TaskState`.
+ *
+ * @param platform - The connector platform identifier.
+ * @param nativeState - The raw state string from the connector.
+ * @returns The canonical `TaskState`, or `undefined` if unmappable.
+ */
+declare function mapConnectorState(platform: ConnectorPlatform, nativeState: string): TaskState | undefined;
+/**
+ * Map a native state from any supported connector to canonical `TaskState`,
+ * throwing if the mapping fails.
+ *
+ * @param platform - The connector platform identifier.
+ * @param nativeState - The raw state string from the connector.
+ * @returns The canonical `TaskState`.
+ * @throws {Error} If the platform or state is unknown.
+ */
+declare function mapConnectorStateStrict(platform: ConnectorPlatform, nativeState: string): TaskState;
+/**
+ * Map a canonical `TaskState` back to the primary native state for a given
+ * connector platform.
+ *
+ * @param platform - The connector platform identifier.
+ * @param canonicalState - The canonical task state.
+ * @returns The native state string, or `undefined` if the platform is unknown.
+ */
+declare function canonicalToConnectorState(platform: ConnectorPlatform, canonicalState: TaskState): string | undefined;
+/**
+ * Given the current canonical state and a new native state from a connector,
+ * determine whether the implied transition is valid according to the
+ * canonical lifecycle rules.
+ *
+ * This is the main "guard" function that adapters should call before
+ * applying a state update from a connector event.
+ *
+ * @param currentCanonical - The current canonical task state.
+ * @param platform - The connector platform identifier.
+ * @param newNativeState - The new native state reported by the connector.
+ * @returns An object indicating whether the transition is valid, the mapped
+ *          canonical state, and an error message if invalid.
+ */
+declare function checkConnectorTransition(currentCanonical: TaskState, platform: ConnectorPlatform, newNativeState: string): {
+    valid: boolean;
+    mappedState: TaskState | undefined;
+    error?: string;
+};
+/**
+ * Check whether a connector-reported native state maps to a terminal
+ * canonical state.
+ *
+ * @param platform - The connector platform identifier.
+ * @param nativeState - The native state to check.
+ * @returns `true` if the mapped canonical state is terminal; `false` if
+ *          non-terminal or unmappable.
+ */
+declare function isConnectorTerminalState(platform: ConnectorPlatform, nativeState: string): boolean;
+
+export { type ClaudeNativeState, type CodexNativeState, type ConnectorPlatform, canonicalToClaudeState, canonicalToCodexState, canonicalToConnectorState, checkConnectorTransition, isConnectorTerminalState, mapClaudeState, mapClaudeStateStrict, mapCodexState, mapCodexStateStrict, mapConnectorState, mapConnectorStateStrict };