@output.ai/cli 0.4.2 → 0.5.1

package/dist/templates/agent_instructions/skills/output-error-nondeterminism/SKILL.md.template

@@ -0,0 +1,252 @@
+---
+name: output-error-nondeterminism
+description: Fix non-determinism errors in Output SDK workflows. Use when seeing replay failures, inconsistent results between runs, "non-deterministic" error messages, or workflows behaving differently on retry.
+allowed-tools: [Bash, Read]
+---
+
+# Fix Non-Determinism Errors
+
+## Overview
+
+This skill helps diagnose and fix non-determinism errors in Output SDK workflows. Workflows must be deterministic because Temporal may replay them during recovery or retries, and the replay must produce identical results.
+
+## When to Use This Skill
+
+You're seeing:
+- "non-deterministic" error messages
+- Replay failures after workflow restart
+- Inconsistent results between runs with same input
+- Errors during workflow recovery
+- Warnings about determinism violations
+
+## Root Cause
+
+Temporal workflows must be deterministic: given the same input, they must always execute the same sequence of operations. This is because Temporal replays workflow history to recover state after crashes or restarts.
+
+Non-deterministic operations break this replay mechanism because they produce different values each time.
+
+## Common Causes and Solutions
+
+### 1. Math.random()
+
+**Problem**: Random values differ on each execution.
+
+```typescript
+// WRONG: Non-deterministic
+export default workflow({
+  fn: async (input) => {
+    const id = Math.random().toString(36);  // Different each time!
+    return await processWithId({ id });
+  }
+});
+```
+
+**Solution**: Pass random values as workflow input or generate in a step.
+
+```typescript
+// Option 1: Pass as input
+export default workflow({
+  inputSchema: z.object({
+    id: z.string()  // Generate ID before calling workflow
+  }),
+  fn: async (input) => {
+    return await processWithId({ id: input.id });
+  }
+});
+
+// Option 2: Generate in a step (steps can be non-deterministic)
+export const generateId = step({
+  name: 'generateId',
+  fn: async () => ({ id: Math.random().toString(36) })
+});
+
+export default workflow({
+  fn: async (input) => {
+    const { id } = await generateId({});
+    return await processWithId({ id });
+  }
+});
+```
+
+### 2. Date.now() / new Date()
+
+**Problem**: Timestamps change between executions.
+
+```typescript
+// WRONG: Non-deterministic
+export default workflow({
+  fn: async (input) => {
+    const timestamp = Date.now();  // Different each replay!
+    return await logEvent({ timestamp });
+  }
+});
+```
+
+**Solution**: Pass timestamps as input or use Temporal's time API.
+
+```typescript
+// Option 1: Pass as input
+export default workflow({
+  inputSchema: z.object({
+    timestamp: z.number()
+  }),
+  fn: async (input) => {
+    return await logEvent({ timestamp: input.timestamp });
+  }
+});
+
+// Option 2: Generate in a step
+export const getTimestamp = step({
+  name: 'getTimestamp',
+  fn: async () => ({ timestamp: Date.now() })
+});
+```
+
+### 3. crypto.randomUUID()
+
+**Problem**: UUIDs differ each execution.
+
+```typescript
+// WRONG: Non-deterministic
+import { randomUUID } from 'crypto';
+
+export default workflow({
+  fn: async (input) => {
+    const requestId = randomUUID();  // Different each time!
+    return await makeRequest({ requestId });
+  }
+});
+```
+
+**Solution**: Generate UUIDs as input or in steps.
+
+```typescript
+// Correct: Generate in step
+export const generateRequestId = step({
+  name: 'generateRequestId',
+  fn: async () => {
+    const { randomUUID } = await import('crypto');
+    return { requestId: randomUUID() };
+  }
+});
+```
+
+### 4. Dynamic Imports
+
+**Problem**: Dynamic imports may resolve differently.
+
+```typescript
+// WRONG: Non-deterministic import timing
+export default workflow({
+  fn: async (input) => {
+    const module = await import(`./handlers/${input.type}`);
+    return module.handle(input);
+  }
+});
+```
+
+**Solution**: Use static imports and conditional logic.
+
+```typescript
+// Correct: Static imports with conditional use
+import { handleTypeA } from './handlers/typeA';
+import { handleTypeB } from './handlers/typeB';
+
+export default workflow({
+  fn: async (input) => {
+    if (input.type === 'A') {
+      return await handleTypeA(input);
+    } else {
+      return await handleTypeB(input);
+    }
+  }
+});
+```
+
+### 5. Environment Variables
+
+**Problem**: Environment may differ between replays.
+
+```typescript
+// WRONG: Environment can change
+export default workflow({
+  fn: async (input) => {
+    const apiUrl = process.env.API_URL;  // May differ on different workers
+    return await callApi({ url: apiUrl });
+  }
+});
+```
+
+**Solution**: Pass configuration as input or use constants.
+
+```typescript
+// Correct: Pass as input
+export default workflow({
+  inputSchema: z.object({
+    apiUrl: z.string()
+  }),
+  fn: async (input) => {
+    return await callApi({ url: input.apiUrl });
+  }
+});
+```
+
+## How to Find Non-Deterministic Code
+
+### Search for Common Patterns
+
+```bash
+# Find Math.random usage
+grep -rn "Math.random" src/workflows/
+
+# Find Date.now or new Date
+grep -rn "Date.now\|new Date" src/workflows/
+
+# Find crypto random functions
+grep -rn "randomUUID\|randomBytes" src/workflows/
+
+# Find dynamic imports
+grep -rn "import(" src/workflows/
+```
+
+### Review Workflow Files
+
+Look at your workflow `fn` functions specifically. Non-deterministic code is only a problem **in workflow functions**, not in step functions.
+
+## Verification Steps
+
+1. **Fix the code** using solutions above
+2. **Run the workflow**: `npx output workflow run <name> '<input>'`
+3. **Run again with same input**: Result should be identical
+4. **Check for errors**: No "non-deterministic" messages
+
+## The Determinism Rule
+
+**Workflow functions must be deterministic:**
+- Same input = same execution path
+- No side effects (network, filesystem, random values)
+- Only orchestration logic and step calls
+
+**Step functions can be non-deterministic:**
+- Steps record their results in Temporal history
+- Replays use recorded results, not re-execution
+- All I/O should happen in steps
+
+## Debugging Tip
+
+If unsure whether code is causing issues:
+
+```bash
+# Run the workflow
+npx output workflow start my-workflow '{"input": "test"}'
+
+# Get the workflow ID and run debug to see replay behavior
+npx output workflow debug <workflowId> --format json
+```
+
+Look for errors or warnings about non-determinism in the trace.
+
+## Related Issues
+
+- For I/O in workflow code, see `output-error-direct-io`
+- For random values needed in logic, generate them in steps or pass as input

package/dist/templates/agent_instructions/skills/output-error-try-catch/SKILL.md.template

@@ -0,0 +1,226 @@
+---
+name: output-error-try-catch
+description: Fix try-catch anti-pattern in Output SDK workflows. Use when retries aren't working, errors are being swallowed, seeing unexpected FatalError wrapping, or when step failures don't trigger retry policies.
+allowed-tools: [Bash, Read]
+---
+
+# Fix Try-Catch Anti-Pattern
+
+## Overview
+
+This skill helps diagnose and fix a common anti-pattern where step calls are wrapped in try-catch blocks. This prevents Output SDK's retry mechanism from working properly and can lead to confusing error behavior.
+
+## When to Use This Skill
+
+You're seeing:
+- Retries not working as expected
+- Errors being swallowed silently
+- Unexpected FatalError wrapping
+- Step failures not triggering retry policies
+- Errors being caught and re-thrown incorrectly
+
+## Root Cause
+
+When you wrap step calls in try-catch blocks, you intercept errors before the Output SDK retry mechanism can handle them. This defeats the built-in retry logic and can cause:
+
+1. **Retries not happening**: The error is caught, so the framework doesn't know to retry
+2. **Wrong error classification**: Re-throwing as FatalError prevents retries entirely
+3. **Lost error context**: Original error details may be lost in the catch block
+
+## Symptoms
+
+### Pattern 1: Errors Swallowed
+
+```typescript
+// WRONG: Error is silently ignored
+try {
+  const result = await myStep(input);
+} catch (error) {
+  console.log('Step failed');  // Swallowed!
+  return { success: false };
+}
+```
+
+### Pattern 2: FatalError Wrapping
+
+```typescript
+// WRONG: Turns retryable errors into fatal errors
+try {
+  const result = await myStep(input);
+} catch (error) {
+  throw new FatalError(error.message);  // Prevents retries!
+}
+```
+
+### Pattern 3: Re-throwing Generic Errors
+
+```typescript
+// WRONG: Loses error context and may affect retry behavior
+try {
+  const result = await myStep(input);
+} catch (error) {
+  throw new Error(`Step failed: ${error.message}`);
+}
+```
+
+## Solution
+
+**Let failures propagate naturally.** Remove try-catch blocks around step calls and let the Output SDK handle errors:
+
+### Before (Wrong)
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    try {
+      const data = await fetchDataStep(input);
+      const result = await processDataStep(data);
+      return result;
+    } catch (error) {
+      throw new FatalError(error.message);
+    }
+  }
+});
+```
+
+### After (Correct)
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    const data = await fetchDataStep(input);
+    const result = await processDataStep(data);
+    return result;
+  }
+});
+```
+
+## When Try-Catch IS Appropriate
+
+There are limited cases where catching errors in workflows is valid:
+
+### 1. Optional/Fallback Steps
+
+When a step failure should trigger an alternative path:
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    let data;
+    try {
+      data = await fetchFromPrimarySource(input);
+    } catch {
+      // Fallback to secondary source
+      data = await fetchFromSecondarySource(input);
+    }
+    return await processData(data);
+  }
+});
+```
+
+### 2. Aggregate Results with Partial Failures
+
+When processing multiple items where some may fail:
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    const results = [];
+    for (const item of input.items) {
+      try {
+        const result = await processItem(item);
+        results.push({ item, result, success: true });
+      } catch (error) {
+        results.push({ item, error: error.message, success: false });
+      }
+    }
+    return results;  // Contains both successes and failures
+  }
+});
+```
+
+**Note**: Even in these cases, be careful not to swallow errors that should cause the whole workflow to fail.
+
+## Finding Try-Catch Around Steps
+
+Search for the pattern:
+
+```bash
+# Find try blocks in workflow files
+grep -rn "try {" src/workflows/
+
+# Look for FatalError usage
+grep -rn "FatalError" src/workflows/
+```
+
+Then review each match to see if it's wrapping step calls.
+
+## How Retries Work
+
+When you DON'T catch errors:
+
+1. Step throws an error
+2. Output SDK receives the error
+3. SDK checks retry policy (configured per step)
+4. If retries remain, step is re-executed
+5. If retries exhausted, workflow fails with full error context
+
+When you DO catch errors:
+
+1. Step throws an error
+2. Your catch block handles it
+3. Output SDK never sees the original error
+4. Retry logic is bypassed
+5. You control what happens (often incorrectly)
+
+## Configuring Retry Behavior
+
+Instead of try-catch, configure retry policies on steps:
+
+```typescript
+export const fetchData = step({
+  name: 'fetchData',
+  retry: {
+    maxAttempts: 3,
+    initialInterval: '1s',
+    maxInterval: '30s',
+    backoffCoefficient: 2
+  },
+  fn: async (input) => {
+    // If this fails, it will be retried according to policy
+    return await callApi(input);
+  }
+});
+```
+
+## Using FatalError Correctly
+
+FatalError is for errors that should NEVER be retried:
+
+```typescript
+export const validateInput = step({
+  name: 'validateInput',
+  fn: async (input) => {
+    if (!input.userId) {
+      // This will never succeed on retry
+      throw new FatalError('userId is required');
+    }
+    return input;
+  }
+});
+```
+
+Do NOT use FatalError to wrap other errors unless you're certain they shouldn't retry.
+
+## Verification
+
+After removing try-catch:
+
+1. **Test normal operation**: `npx output workflow run <name> '<valid-input>'`
+2. **Test failure scenarios**: Use input that causes step failures
+3. **Check retry behavior**: Look for retry attempts in `npx output workflow debug <id>`
+
+## Related Issues
+
+- For configuring retry policies, see step definition documentation
+- For handling expected failures gracefully, consider using conditional logic instead of try-catch

package/dist/templates/agent_instructions/skills/output-error-zod-import/SKILL.md.template

@@ -0,0 +1,209 @@
+---
+name: output-error-zod-import
+description: Fix Zod schema import issues in Output SDK workflows. Use when seeing "incompatible schema" errors, type errors at step boundaries, schema validation failures, or when schemas don't match between steps.
+allowed-tools: [Bash, Read]
+---
+
+# Fix Zod Import Source Issues
+
+## Overview
+
+This skill helps diagnose and fix a common issue where Zod schemas are imported from the wrong source. Output SDK requires schemas to be imported from `@output.ai/core`, not directly from `zod`.
+
+## When to Use This Skill
+
+You're seeing:
+- "incompatible schema" errors
+- Type errors at step boundaries
+- Schema validation failures when passing data between steps
+- Errors mentioning Zod types not matching
+- "Expected ZodObject but received..." errors
+
+## Root Cause
+
+The issue occurs when you import `z` from `zod` instead of `@output.ai/core`. While both provide Zod schemas, they create different schema instances that aren't compatible with each other within the Output SDK context.
+
+**Why this matters**: Output SDK uses a specific version of Zod internally for serialization and validation. When you use a different Zod instance, the schemas are technically different objects even if they define the same shape.
+
+## Symptoms
+
+### Error Messages
+
+```
+Error: Incompatible schema types
+Error: Schema validation failed: expected compatible Zod instance
+TypeError: Cannot read property 'parse' of undefined
+```
+
+### Code Patterns That Cause This
+
+```typescript
+// WRONG: Importing from 'zod' directly
+import { z } from 'zod';
+
+const inputSchema = z.object({
+  name: z.string(),
+});
+```
+
+## Solution
+
+### Step 1: Find All Zod Imports
+
+Search your codebase for incorrect imports:
+
+```bash
+grep -r "from 'zod'" src/
+grep -r 'from "zod"' src/
+```
+
+### Step 2: Update Imports
+
+Change all imports from:
+
+```typescript
+// Wrong
+import { z } from 'zod';
+```
+
+To:
+
+```typescript
+// Correct
+import { z } from '@output.ai/core';
+```
+
+### Step 3: Verify No Direct Zod Dependencies
+
+Check your imports don't accidentally use zod elsewhere:
+
+```bash
+grep -r "import.*zod" src/
+```
+
+All matches should show `@output.ai/core`, not `zod`.
+
+## Complete Example
+
+### Before (Wrong)
+
+```typescript
+// src/workflows/my-workflow/steps/process.ts
+import { z } from 'zod';  // Wrong!
+import { step } from '@output.ai/core';
+
+export const processStep = step({
+  name: 'processData',
+  inputSchema: z.object({
+    id: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  fn: async (input) => {
+    return { result: `Processed ${input.id}` };
+  },
+});
+```
+
+### After (Correct)
+
+```typescript
+// src/workflows/my-workflow/steps/process.ts
+import { z, step } from '@output.ai/core';  // Correct!
+
+export const processStep = step({
+  name: 'processData',
+  inputSchema: z.object({
+    id: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  fn: async (input) => {
+    return { result: `Processed ${input.id}` };
+  },
+});
+```
+
+## Verification Steps
+
+### 1. Check for remaining wrong imports
+
+```bash
+# Should return no results
+grep -r "from 'zod'" src/
+grep -r 'from "zod"' src/
+```
+
+### 2. Build the project
+
+```bash
+npm run build
+```
+
+### 3. Run the workflow
+
+```bash
+npx output workflow run <workflowName> '<input>'
+```
+
+## Prevention
+
+### ESLint Rule (if using ESLint)
+
+Add a rule to prevent direct zod imports:
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  rules: {
+    'no-restricted-imports': ['error', {
+      paths: [{
+        name: 'zod',
+        message: "Import { z } from '@output.ai/core' instead of 'zod'"
+      }]
+    }]
+  }
+};
+```
+
+### IDE Settings
+
+Configure your editor to auto-import from `@output.ai/core`:
+
+For VS Code, add to settings.json:
+```json
+{
+  "typescript.preferences.autoImportFileExcludePatterns": ["zod"]
+}
+```
+
+## Common Gotchas
+
+### Mixed Imports in Same File
+Even one wrong import can cause issues:
+```typescript
+import { z } from '@output.ai/core';
+import { z as zod } from 'zod';  // This causes problems!
+```
+
+### Indirect Dependencies
+If a utility file uses the wrong import and is shared:
+```typescript
+// utils/schemas.ts
+import { z } from 'zod';  // Wrong! This affects all files using these schemas
+export const idSchema = z.string().uuid();
+```
+
+### Third-Party Libraries
+If using external Zod schemas, you may need to recreate them:
+```typescript
+// Don't use: externalLibrary.schema
+// Instead: recreate the schema with @output.ai/core's z
+```
+
+## Related Issues
+
+- If schemas are correct but you still see type errors, check `output-error-missing-schemas`
+- For validation failures with correct imports, verify schema definitions match actual data