groundswell 0.0.2 → 1.0.0

package/dist/types/providers.js

@@ -0,0 +1,14 @@
+// src/types/providers.ts — Backward-compatible deprecated alias shim (v1.2)
+//
+// Every Provider* symbol is either:
+//   Bucket A — @deprecated alias → structurally-identical Harness* counterpart (types/harnesses.ts)
+//   Bucket B — @deprecated superset union (ProviderId = HarnessId | legacy literals)
+//   Bucket C — KEPT CONCRETE (shape diverges or consumers depend on specifics)
+//
+// The ProviderResult family is already @deprecated → AgentResponse and is left byte-for-byte
+// unchanged.  ToolExecutionRequest / ToolExecutionResult are shared types re-exported from
+// harnesses.ts (NOT renamed, NOT deprecated).  ToolExecutor is a concrete util (not deprecated).
+//
+// NO runtime code.  NO edits to any consumer file.
+export {};
+//# sourceMappingURL=providers.js.map

package/dist/types/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/types/providers.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,oCAAoC;AACpC,oGAAoG;AACpG,qFAAqF;AACrF,+EAA+E;AAC/E,EAAE;AACF,6FAA6F;AAC7F,2FAA2F;AAC3F,iGAAiG;AACjG,EAAE;AACF,mDAAmD"}

package/dist/types/reflection.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Reflection types - Interfaces for multi-level reflection and self-correction
+ *
+ * Reflection allows agents to analyze errors and retry with modified approaches.
+ * Supports workflow, agent, and prompt level reflection with configurable limits.
+ */
+import type { WorkflowNode } from './workflow.js';
+/**
+ * Configuration for reflection behavior
+ */
+export interface ReflectionConfig {
+    /** Whether reflection is enabled */
+    enabled: boolean;
+    /** Maximum number of reflection attempts (default: 3) */
+    maxAttempts: number;
+    /** Delay between retry attempts in milliseconds (default: 0) */
+    retryDelayMs?: number;
+}
+/**
+ * Context provided to the reflection process
+ */
+export interface ReflectionContext {
+    /** Level at which reflection is occurring */
+    level: 'workflow' | 'agent' | 'prompt';
+    /** The workflow node that failed */
+    failedNode: WorkflowNode;
+    /** The error that triggered reflection */
+    error: Error;
+    /** Current attempt number (1-indexed) */
+    attemptNumber: number;
+    /** History of previous reflection attempts */
+    previousAttempts: ReflectionEntry[];
+}
+/**
+ * Result from a reflection analysis
+ */
+export interface ReflectionResult {
+    /** Whether to retry the operation */
+    shouldRetry: boolean;
+    /** Revised prompt data for retry */
+    revisedPromptData?: Record<string, unknown>;
+    /** Revised system prompt for retry */
+    revisedSystemPrompt?: string;
+    /** Explanation of the reflection decision */
+    reason: string;
+}
+/**
+ * Record of a single reflection attempt
+ */
+export interface ReflectionEntry {
+    /** Timestamp when reflection occurred */
+    timestamp: number;
+    /** Level at which reflection occurred */
+    level: 'workflow' | 'agent' | 'prompt';
+    /** Reason for the reflection */
+    reason: string;
+    /** Original error that triggered reflection */
+    error: Error;
+    /** Resolution action taken */
+    resolution: 'retry' | 'skip' | 'abort';
+    /** Whether the retry was successful */
+    success: boolean;
+}
+/**
+ * Full ReflectionAPI interface for workflow contexts
+ */
+export interface ReflectionAPI {
+    /**
+     * Check if reflection is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Trigger a reflection on the current context
+     * @param reason Optional reason for the reflection
+     */
+    triggerReflection(reason?: string): Promise<void>;
+    /**
+     * Get the history of reflection attempts
+     */
+    getReflectionHistory(): ReflectionEntry[];
+    /**
+     * Perform reflection analysis on an error
+     * @param context The reflection context with error details
+     * @returns Result indicating whether to retry
+     */
+    reflect(context: ReflectionContext): Promise<ReflectionResult>;
+}
+/**
+ * Default reflection configuration
+ */
+export declare const DEFAULT_REFLECTION_CONFIG: ReflectionConfig;
+/**
+ * Create a reflection config with defaults
+ */
+export declare function createReflectionConfig(partial?: Partial<ReflectionConfig>): ReflectionConfig;
+//# sourceMappingURL=reflection.d.ts.map

package/dist/types/reflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.d.ts","sourceRoot":"","sources":["../../src/types/reflection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,oCAAoC;IACpC,UAAU,EAAE,YAAY,CAAC;IACzB,0CAA0C;IAC1C,KAAK,EAAE,KAAK,CAAC;IACb,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,sCAAsC;IACtC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,KAAK,CAAC;IACb,8BAA8B;IAC9B,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACvC,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,oBAAoB,IAAI,eAAe,EAAE,CAAC;IAE1C;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAClC,gBAAgB,CAKlB"}

package/dist/types/reflection.js

@@ -0,0 +1,24 @@
+/**
+ * Reflection types - Interfaces for multi-level reflection and self-correction
+ *
+ * Reflection allows agents to analyze errors and retry with modified approaches.
+ * Supports workflow, agent, and prompt level reflection with configurable limits.
+ */
+/**
+ * Default reflection configuration
+ */
+export const DEFAULT_REFLECTION_CONFIG = {
+    enabled: false,
+    maxAttempts: 3,
+    retryDelayMs: 0,
+};
+/**
+ * Create a reflection config with defaults
+ */
+export function createReflectionConfig(partial) {
+    return {
+        ...DEFAULT_REFLECTION_CONFIG,
+        ...partial,
+    };
+}
+//# sourceMappingURL=reflection.js.map

package/dist/types/reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.js","sourceRoot":"","sources":["../../src/types/reflection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4FH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,OAAO,EAAE,KAAK;IACd,WAAW,EAAE,CAAC;IACd,YAAY,EAAE,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAmC;IAEnC,OAAO;QACL,GAAG,yBAAyB;QAC5B,GAAG,OAAO;KACX,CAAC;AACJ,CAAC"}

package/dist/types/restart.d.ts

@@ -0,0 +1,132 @@
+import type { WorkflowError } from './error.js';
+/**
+ * Restart analysis result
+ *
+ * Provides error classification and restart recommendations for step retry logic.
+ * This interface encapsulates the decision-making process for determining whether
+ * a failed step should be retried, aborted, or require plan rebuilding.
+ *
+ * **Probability Interpretation**:
+ * - `0.0 - 0.3`: Low success probability - consider abort or rebuild
+ * - `0.4 - 0.6`: Moderate probability - retry with caution
+ * - `0.7 - 1.0`: High probability - safe to retry
+ *
+ * @example Transient error - safe to retry
+ * ```ts
+ * const analysis: RestartAnalysis = {
+ *   shouldRestart: true,
+ *   reason: 'Network timeout - likely transient',
+ *   suggestedAction: 'retry',
+ *   estimatedSuccessProbability: 0.8
+ * };
+ * ```
+ *
+ * @example Permanent error - should abort
+ * ```ts
+ * const analysis: RestartAnalysis = {
+ *   shouldRestart: false,
+ *   reason: 'Invalid API key - authentication will never succeed',
+ *   suggestedAction: 'abort',
+ *   estimatedSuccessProbability: 0.0
+ * };
+ * ```
+ *
+ * @example Recoverable but requires intervention
+ * ```ts
+ * const analysis: RestartAnalysis = {
+ *   shouldRestart: true,
+ *   reason: 'Rate limit exceeded - retry after backoff',
+ *   suggestedAction: 'retry',
+ *   estimatedSuccessProbability: 0.6
+ * };
+ * ```
+ *
+ * @see {@link ErrorCriterion} - For defining error matching criteria
+ * @remarks Used in stepRetry events and error analysis utilities
+ */
+export interface RestartAnalysis {
+    /** Whether the step should be restarted */
+    shouldRestart: boolean;
+    /** Human-readable reason for the restart decision */
+    reason: string;
+    /** Suggested action to take */
+    suggestedAction: 'retry' | 'abort' | 'rebuild';
+    /** Estimated probability of success (0-1) */
+    estimatedSuccessProbability: number;
+}
+/**
+ * Error matching criterion for step restart decisions
+ *
+ * Supports three patterns for error matching:
+ * 1. **By error code** - Exact string match or regex pattern matching
+ * 2. **By recoverable flag** - Match recoverable vs non-recoverable errors
+ * 3. **Custom predicate** - Function for complex matching logic
+ *
+ * @example Match by exact error code
+ * ```ts
+ * const criterion: ErrorCriterion = { code: 'RATE_LIMIT_EXCEEDED' };
+ * ```
+ *
+ * @example Match by regex pattern
+ * ```ts
+ * const criterion: ErrorCriterion = { code: /TIMEOUT|NETWORK_ERROR/ };
+ * ```
+ *
+ * @example Match by recoverable flag
+ * ```ts
+ * const criterion: ErrorCriterion = { recoverable: true };
+ * ```
+ *
+ * @example Custom predicate with complex logic
+ * ```ts
+ * const criterion: ErrorCriterion = (error) => {
+ *   const isTemporary = error.message.includes('temporary');
+ *   const isTimeout = error.code === 'TIMEOUT';
+ *   const hasRetryableStatus = error.original?.status >= 500;
+ *   return isTemporary || isTimeout || hasRetryableStatus;
+ * };
+ * ```
+ *
+ * @remarks
+ * **IMPORTANT**: Function types must come last in the discriminated union for proper
+ * TypeScript type narrowing. When checking criteria at runtime, always check
+ * `typeof criterion === 'function'` first before discriminant property checks.
+ *
+ * **Why functions must be last**:
+ * In JavaScript, functions can have properties. If a function has a `code` property,
+ * the discriminant check `'code' in criterion` would return `true`, causing TypeScript
+ * to incorrectly narrow the type. By placing functions last and checking them first
+ * at runtime, we ensure type safety.
+ *
+ * **Runtime checking pattern**:
+ * ```ts
+ * function matchesCriterion(
+ *   criterion: ErrorCriterion,
+ *   error: WorkflowError
+ * ): boolean {
+ *   // Check function FIRST
+ *   if (typeof criterion === 'function') {
+ *     return criterion(error);
+ *   }
+ *   // Now safe to use discriminant checks
+ *   if ('code' in criterion) {
+ *     const codeMatch = criterion.code instanceof RegExp
+ *       ? criterion.code.test(error.code || '')
+ *       : error.code === criterion.code;
+ *     return codeMatch;
+ *   }
+ *   if ('recoverable' in criterion) {
+ *     return error.original?.recoverable === criterion.recoverable;
+ *   }
+ *   return false;
+ * }
+ * ```
+ *
+ * @see {@link RestartAnalysis} - For restart decision result type
+ */
+export type ErrorCriterion = {
+    code: string | RegExp;
+} | {
+    recoverable: boolean;
+} | ((error: WorkflowError) => boolean);
+//# sourceMappingURL=restart.d.ts.map

package/dist/types/restart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.d.ts","sourceRoot":"","sources":["../../src/types/restart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,aAAa,EAAE,OAAO,CAAC;IAEvB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IAEf,+BAA+B;IAC/B,eAAe,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAE/C,6CAA6C;IAC7C,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GACzB;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,GACxB,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC"}

package/dist/types/restart.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=restart.js.map

package/dist/types/restart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.js","sourceRoot":"","sources":["../../src/types/restart.ts"],"names":[],"mappings":""}

package/dist/types/sdk-primitives.d.ts

@@ -0,0 +1,118 @@
+/**
+ * SDK primitive types that mirror Anthropic SDK structures
+ * These types pass through unchanged to the SDK
+ */
+/**
+ * Tool definition for Anthropic SDK
+ * Maps directly to Anthropic.Tool
+ */
+export interface Tool {
+    /** Tool name (must be unique within an agent) */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** JSON Schema describing the tool's input parameters */
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Tool result returned from tool execution
+ */
+export interface ToolResult {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | unknown;
+    is_error?: boolean;
+}
+/**
+ * MCP Server configuration
+ * Supports stdio and inprocess transports
+ */
+export interface MCPServer {
+    /** Server name for identification */
+    name: string;
+    /** Server version (optional) */
+    version?: string;
+    /** Transport type */
+    transport: 'stdio' | 'inprocess';
+    /** Command to run for stdio transport */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** Tools provided by this MCP server */
+    tools?: Tool[];
+    /** Environment variables for the MCP process */
+    env?: Record<string, string>;
+}
+/**
+ * Skill definition
+ * Skills are loaded from directories containing SKILL.md
+ */
+export interface Skill {
+    /** Skill name for identification */
+    name: string;
+    /** Path to skill directory containing SKILL.md */
+    path: string;
+}
+/**
+ * Hook handler function type
+ */
+export type HookHandler<T = unknown> = (context: T) => Promise<void> | void;
+/**
+ * Pre-tool use hook context
+ */
+export interface PreToolUseContext {
+    toolName: string;
+    toolInput: unknown;
+    agentId: string;
+}
+/**
+ * Post-tool use hook context
+ */
+export interface PostToolUseContext {
+    toolName: string;
+    toolInput: unknown;
+    toolOutput: unknown;
+    agentId: string;
+    duration: number;
+}
+/**
+ * Session start hook context
+ */
+export interface SessionStartContext {
+    agentId: string;
+    agentName?: string;
+}
+/**
+ * Session end hook context
+ */
+export interface SessionEndContext {
+    agentId: string;
+    agentName?: string;
+    totalDuration: number;
+}
+/**
+ * Agent lifecycle hooks
+ * Maps to Anthropic SDK hook conventions
+ */
+export interface AgentHooks {
+    /** Called before each tool invocation */
+    preToolUse?: HookHandler<PreToolUseContext>[];
+    /** Called after each tool invocation */
+    postToolUse?: HookHandler<PostToolUseContext>[];
+    /** Called when agent session starts */
+    sessionStart?: HookHandler<SessionStartContext>[];
+    /** Called when agent session ends */
+    sessionEnd?: HookHandler<SessionEndContext>[];
+}
+/**
+ * Token usage information from API response
+ */
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+//# sourceMappingURL=sdk-primitives.d.ts.map

package/dist/types/sdk-primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-primitives.d.ts","sourceRoot":"","sources":["../../src/types/sdk-primitives.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,SAAS,EAAE,OAAO,GAAG,WAAW,CAAC;IACjC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,UAAU,CAAC,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAC9C,wCAAwC;IACxC,WAAW,CAAC,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAAE,CAAC;IAChD,uCAAuC;IACvC,YAAY,CAAC,EAAE,WAAW,CAAC,mBAAmB,CAAC,EAAE,CAAC;IAClD,qCAAqC;IACrC,UAAU,CAAC,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/types/sdk-primitives.js

@@ -0,0 +1,6 @@
+/**
+ * SDK primitive types that mirror Anthropic SDK structures
+ * These types pass through unchanged to the SDK
+ */
+export {};
+//# sourceMappingURL=sdk-primitives.js.map

package/dist/types/sdk-primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-primitives.js","sourceRoot":"","sources":["../../src/types/sdk-primitives.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/{src/types/snapshot.ts → dist/types/snapshot.d.ts}

@@ -2,13 +2,13 @@
  * Serialized workflow state as key-value pairs
  */
 export type SerializedWorkflowState = Record<string, unknown>;
-
 /**
  * Metadata for observed state fields
  */
 export interface StateFieldMetadata {
-  /** If true, field is not included in snapshots */
-  hidden?: boolean;
-  /** If true, value is shown as '***' in snapshots */
-  redact?: boolean;
+    /** If true, field is not included in snapshots */
+    hidden?: boolean;
+    /** If true, value is shown as '***' in snapshots */
+    redact?: boolean;
 }
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/types/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/types/snapshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/types/snapshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot.js.map

package/dist/types/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/types/snapshot.ts"],"names":[],"mappings":""}

package/dist/types/streaming.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Streaming types for LLM streaming responses
+ *
+ * Provides types and utilities for streaming responses from LLM providers.
+ * Uses TypeScript's built-in AsyncGenerator for efficient streaming.
+ */
+import type { AgentResponse } from './agent.js';
+/**
+ * Stream event types for LLM streaming responses
+ *
+ * Discriminated union for type-safe event handling during streaming.
+ * Each event type has a unique `type` field for TypeScript narrowing.
+ *
+ * @example
+ * ```ts
+ * for await (const event of streamResult.stream) {
+ *   switch (event.type) {
+ *     case 'text_delta':
+ *       console.log(event.delta); // Type-safe access to delta
+ *       break;
+ *     case 'tool_call_start':
+ *       console.log(event.name); // Type-safe access to name
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamEvent = {
+    type: 'text_delta';
+    delta: string;
+    index: number;
+} | {
+    type: 'text_done';
+    text: string;
+    index: number;
+} | {
+    type: 'tool_call_start';
+    id: string;
+    name: string;
+    index: number;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_call_done';
+    id: string;
+    result: unknown;
+} | {
+    type: 'metadata';
+    metadata: {
+        requestId?: string;
+        model?: string;
+        provider: string;
+    };
+} | {
+    type: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    cacheTokens?: number;
+} | {
+    type: 'done';
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'error';
+} | {
+    type: 'error';
+    error: Error;
+    code?: string;
+    retryable?: boolean;
+};
+/**
+ * AsyncStream interface for streaming responses
+ *
+ * Wraps AsyncGenerator with additional metadata and cancellation support.
+ * Designed for for-await...of consumption.
+ *
+ * @template T - The type of the final response data (from AsyncGenerator return)
+ *
+ * @example
+ * ```ts
+ * const streamResult = agent.stream(prompt);
+ *
+ * for await (const event of streamResult.stream) {
+ *   if (event.type === 'text_delta') {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ *
+ * // Cancel stream if needed
+ * streamResult.controller?.abort();
+ * ```
+ */
+export interface AsyncStream<T> {
+    /**
+     * Async generator yielding stream events
+     *
+     * Consume with for await...of loop. The generator yields StreamEvent
+     * objects and returns the final AgentResponse<T> when complete.
+     *
+     * @example
+     * ```ts
+     * for await (const event of streamResult.stream) {
+     *   switch (event.type) {
+     *     case 'text_delta':
+     *       console.log(event.delta);
+     *       break;
+     *     case 'done':
+     *       console.log('Complete!');
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    stream: AsyncGenerator<StreamEvent, AgentResponse<T>, unknown>;
+    /**
+     * Optional abort controller for cancellation
+     *
+     * Use to cancel an in-progress stream. The stream generator should
+     * check controller.signal.aborted and yield an error event or break.
+     *
+     * @example
+     * ```ts
+     * let eventCount = 0;
+     * for await (const event of streamResult.stream) {
+     *   eventCount++;
+     *   if (eventCount >= 10) {
+     *     streamResult.controller?.abort();
+     *     break;
+     *   }
+     * }
+     * ```
+     */
+    controller?: AbortController;
+}
+/**
+ * Type guard for text delta events
+ *
+ * Narrows StreamEvent to text_delta type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a text_delta event
+ *
+ * @example
+ * ```ts
+ * if (isTextDeltaEvent(event)) {
+ *   console.log(event.delta); // TypeScript knows delta exists
+ *   console.log(event.index); // TypeScript knows index exists
+ * }
+ * ```
+ */
+export declare function isTextDeltaEvent(event: StreamEvent): event is Extract<StreamEvent, {
+    type: 'text_delta';
+}>;
+/**
+ * Type guard for tool call events
+ *
+ * Narrows StreamEvent to any tool call event type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a tool_call_start, tool_call_delta, or tool_call_done event
+ *
+ * @example
+ * ```ts
+ * if (isToolCallEvent(event)) {
+ *   if (event.type === 'tool_call_start') {
+ *     console.log(event.name); // TypeScript knows name exists
+ *   }
+ * }
+ * ```
+ */
+export declare function isToolCallEvent(event: StreamEvent): event is Extract<StreamEvent, {
+    type: 'tool_call_start' | 'tool_call_delta' | 'tool_call_done';
+}>;
+/**
+ * Type guard for error events
+ *
+ * Narrows StreamEvent to error type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is an error event
+ *
+ * @example
+ * ```ts
+ * if (isErrorEvent(event)) {
+ *   console.error(event.error.message); // TypeScript knows error exists
+ *   if (event.retryable) {
+ *     // Retry logic
+ *   }
+ * }
+ * ```
+ */
+export declare function isErrorEvent(event: StreamEvent): event is Extract<StreamEvent, {
+    type: 'error';
+}>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/types/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/types/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,GAEnB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAGlD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAGvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAGxF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAGlF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAA;CAAE,GAG1E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,EAAE,cAAc,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAE/D;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAE1G;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;CAAE,CAAC,CAErJ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAEjG"}