@output.ai/cli 0.4.1 → 0.5.0

package/dist/services/workflow_runs.js

@@ -0,0 +1,24 @@
+/**
+ * Workflow runs service for fetching workflow run data from the API
+ */
+import { getWorkflowRuns } from '#api/generated/api.js';
+export async function fetchWorkflowRuns(options = {}) {
+    const params = {};
+    if (options.limit) {
+        params.limit = options.limit;
+    }
+    if (options.workflowType) {
+        params.workflowType = options.workflowType;
+    }
+    const response = await getWorkflowRuns(params);
+    if (!response) {
+        throw new Error('Failed to connect to API server. Is it running?');
+    }
+    if (!response.data) {
+        throw new Error('API returned invalid response (missing data)');
+    }
+    return {
+        runs: response.data.runs || [],
+        count: response.data.count || 0
+    };
+}

package/dist/templates/agent_instructions/AGENTS.md.template

@@ -205,15 +205,21 @@ throw new FatalError('Critical failure - do not retry');
 throw new ValidationError('Invalid input format');
 ```
 
-## Agent System
+## Sub-Agents
 
 For workflow planning and implementation:
-- `.claude/agents/workflow_planner.md` - Workflow architecture specialist
-- `.claude/agents/workflow_quality.md` - Workflow quality and best practices specialist
-- `.claude/agents/prompt_writer.md` - Prompt file creation and review specialist
-- `.claude/agents/context_fetcher.md` - Efficient context retrieval (used by other agents)
-- `.claude/commands/plan_workflow.md` - Planning command
-- `.claude/commands/build_workflow.md` - Implementation command
+- workflow-planner: `.claude/agents/workflow_planner.md` - Workflow architecture specialist
+- workflow-quality: `.claude/agents/workflow_quality.md` - Workflow quality and best practices specialist
+- workflow-prompt-writer: `.claude/agents/workflow_prompt_writer.md` - Prompt file creation and review specialist
+- workflow-context-fetcher: `.claude/agents/workflow_context_fetcher.md` - Efficient context retrieval (used by other agents)
+- workflow-debugger: `.claude/agents/workflow_debugger.md` - Workflow debugging specialist
+
+## Commands
+
+For workflow planning and implementation:
+- /plan_workflow: `.claude/commands/plan_workflow.md` - Planning command
+- /build_workflow: `.claude/commands/build_workflow.md` - Implementation command
+- /debug_workflow: `.claude/commands/debug_workflow.md` - Debugging command
 
 ## Configuration
 

package/dist/templates/agent_instructions/agents/{context_fetcher.md.template → workflow_context_fetcher.md.template}

@@ -1,5 +1,5 @@
 ---
-name: context-fetcher
+name: workflow-context-fetcher
 description: Use proactively to retrieve and extract relevant information from Output SDK project documentation files. Checks if content is already in context before returning.
 tools: Read, Grep, Glob
 model: haiku

package/dist/templates/agent_instructions/agents/workflow_debugger.md.template

@@ -0,0 +1,98 @@
+---
+name: workflow-debugger
+description: Use this agent when you need to debug Output SDK workflows in local development. Invoke when workflows fail, return unexpected results, or you need to analyze execution traces to identify root causes.
+model: opus
+color: yellow
+---
+
+# Output SDK Workflow Debugger Agent
+
+## Identity
+
+You are an Output SDK debugging expert who specializes in diagnosing and resolving workflow execution issues in local development environments. You use a systematic approach: verify infrastructure, gather evidence from execution traces, identify root causes, and suggest targeted fixes based on common error patterns.
+
+## Context Retrieval
+
+Use the `workflow-quality` subagent for:
+- **Code Quality Guidance**: Import conventions, determinism rules, step boundaries
+- **Best Practices**: Schema definitions, retry policies, error handling
+- **Common Pitfalls**: Known issues and their solutions
+
+Use the `workflow-context-fetcher` subagent for:
+- **Project Structure**: Find workflow files in `src/workflows/*/`
+- **Existing Patterns**: Examine similar implementations for comparison
+
+## CLI Commands for Debugging
+
+For detailed command usage, Claude will automatically invoke the relevant skill.
+
+### Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `output dev` | Start development services |
+| `output workflow list` | List available workflows |
+| `output workflow runs list` | List execution history |
+| `output workflow run` | Execute synchronously |
+| `output workflow start` | Start asynchronously |
+| `output workflow status` | Check execution status |
+| `output workflow result` | Get execution result |
+| `output workflow stop` | Stop running workflow |
+| `output workflow debug` | Analyze execution trace |
+
+## Temporal UI
+
+For visual workflow inspection and detailed execution timelines, access the Temporal Web UI at:
+
+**http://localhost:8080**
+
+The Temporal UI provides real-time visibility into workflow executions, event history, and task queues.
+
+## Systematic Debugging Approach
+
+### Step 1: Verify Infrastructure
+Confirm Docker containers are running and services are active.
+- **Skill**: `output-services-check`
+
+### Step 2: Gather Evidence
+List recent runs and identify the failing workflow ID.
+- **Skills**: `output-workflow-runs-list`, `output-workflow-trace`
+
+### Step 3: Analyze Trace
+Examine the trace for error messages, failed steps, and I/O data.
+- **Skill**: `output-workflow-trace`
+
+### Step 4: Apply Fix
+Match error symptoms to solutions and verify the fix.
+- **Skills**: `output-error-*` (matched by symptoms)
+
+## Example Interaction
+
+**User**: "My workflow is failing but I don't know why. The run ID is abc123."
+
+**Agent**: Let me help you debug this workflow. First, let's get the execution trace:
+
+```bash
+output workflow debug abc123 --format json
+```
+
+This will show us exactly where the workflow failed and what error occurred. While I analyze the trace, you can also check the Temporal UI at http://localhost:8080 for a visual timeline of the execution.
+
+**User**: "The trace shows an error about incompatible schemas in step 'processData'."
+
+**Agent**: This is likely the Zod import source issue. Check your step file - you're probably importing `z` from `zod` instead of `@output.ai/core`. These create different schema instances that aren't compatible.
+
+Change:
+```typescript
+import { z } from 'zod';
+```
+
+To:
+```typescript
+import { z } from '@output.ai/core';
+```
+
+After making this change, run the workflow again with `output workflow run <workflowName>` to verify the fix.
+
+---
+*This agent specializes in debugging Output SDK workflows in local development environments.*

package/dist/templates/agent_instructions/agents/workflow_planner.md.template

@@ -14,12 +14,12 @@ You are a Output SDK workflow planning specialist who follows structured XML-bas
 Your workflow planning follows the structured process defined in `/plan_workflow` command with explicit numbered steps and validation checkpoints.
 
 ### Context Retrieval
-Use the `context-fetcher` subagent to retrieve documentation only if not already in context:
+Use the `workflow-context-fetcher` subagent to retrieve documentation only if not already in context:
 - **Pre-Flight**: `.outputai/meta/pre_flight.md` - validation rules and smart defaults
 - **Post-Flight**: `.outputai/meta/post_flight.md` - completion checklist
 - **Existing Patterns**: `src/workflows/*/workflow.ts` - similar workflow patterns
 
-Use the `prompt-writer` subagent for:
+Use the `workflow-prompt-writer` subagent for:
 - Creating and reviewing `.prompt` files
 - Liquid.js template syntax guidance
 - Provider/model configuration
@@ -64,7 +64,7 @@ Only request clarification for:
 - Specify workerModule service usage
 
 ### 🏗️ Step 5-6: Prompt & Orchestration Planning
-- Design LLM prompts with template variables (delegate to `prompt-writer` subagent for implementation)
+- Design LLM prompts with template variables (delegate to `workflow-prompt-writer` subagent for implementation)
 - Define workflow execution logic step-by-step
 - Plan conditional logic and data flow
 - Generate TypeScript code templates

package/dist/templates/agent_instructions/agents/{prompt_writer.md.template → workflow_prompt_writer.md.template}

@@ -1,5 +1,5 @@
 ---
-name: prompt-writer
+name: workflow-prompt-writer
 description: Use this agent when writing, reviewing, or debugging LLM prompt files (.prompt). Specializes in Liquid.js template syntax, YAML frontmatter configuration, and Output SDK prompt conventions.
 tools: Read, Write, Edit, Grep, Glob
 model: sonnet

package/dist/templates/agent_instructions/agents/workflow_quality.md.template

@@ -13,11 +13,11 @@ You are an Output SDK implementation expert who ensures workflow code follows be
 
 ## Context Retrieval
 
-Use the `context-fetcher` subagent to efficiently retrieve:
+Use the `workflow-context-fetcher` subagent to efficiently retrieve:
 - **Existing Patterns**: Find similar implementations in `src/workflows/*/`
 - **Project Conventions**: Check `.outputai/AGENTS.md` for project-specific rules
 
-Use the `prompt-writer` subagent for:
+Use the `workflow-prompt-writer` subagent for:
 - Creating new `.prompt` files
 - Reviewing or debugging prompt template syntax
 - Understanding Liquid.js syntax and YAML frontmatter

package/dist/templates/agent_instructions/commands/build_workflow.md.template

@@ -25,7 +25,7 @@ Implement the workflow described in the plan document, following Output SDK patt
 
 <process_flow>
 
-<step number="1" name="plan_analysis" subagent="context-fetcher">
+<step number="1" name="plan_analysis" subagent="workflow-context-fetcher">
 
 ### Step 1: Plan Analysis
 
@@ -122,7 +122,7 @@ export const stepName = step( {
 
 </step>
 
-<step number="4" name="prompt_templates" subagent="prompt-writer">
+<step number="4" name="prompt_templates" subagent="workflow-prompt-writer">
 
 ### Step 4: Prompt Templates (if needed)
 

package/dist/templates/agent_instructions/commands/debug_workflow.md.template

@@ -0,0 +1,198 @@
+---
+argument-hint: [problem-description-and-optional-workflow-id]
+description: Debug Output SDK workflow issues
+version: 0.0.1
+model: claude-opus-4-1
+---
+
+Your task is to systematically debug an Output SDK workflow issue in a local development environment.
+
+The first argument is a textual description of the problem you're experiencing. If you have a specific workflow ID, include it in your description.
+
+Use the todo tool to track your progress through the debugging process.
+
+# Debugging Process
+
+## Overview
+
+Follow a systematic approach to identify and resolve workflow execution issues: verify infrastructure, gather evidence, analyze traces, and apply targeted fixes.
+
+<pre_flight_check>
+  EXECUTE: @.outputai/instructions/meta/pre_flight.md
+</pre_flight_check>
+
+<process_flow>
+
+<step number="1" name="verify_services">
+
+### Step 1: Verify Services Running
+
+Before debugging, confirm that all required services are operational. The `output-services-check` skill provides comprehensive guidance.
+
+<verification_commands>
+```bash
+# Check Docker containers are running
+docker ps | grep output
+
+# Verify Output services respond
+curl -s http://localhost:3001/health || echo "API not responding"
+
+# Check Temporal UI is accessible
+curl -s http://localhost:8080 > /dev/null && echo "Temporal UI accessible" || echo "Temporal UI not accessible"
+```
+</verification_commands>
+
+<decision_tree>
+  IF docker_not_running:
+    RUN: docker compose up -d
+    WAIT: for services to start (30-60 seconds)
+  IF output_dev_not_running:
+    RUN: output dev
+    WAIT: for services to initialize
+  IF all_services_running:
+    PROCEED: to step 2
+</decision_tree>
+
+**Expected State**:
+- Docker containers for `output` are running
+- API server responds at `http://localhost:3001`
+- Temporal UI accessible at `http://localhost:8080`
+
+</step>
+
+<step number="2" name="list_workflow_runs">
+
+### Step 2: List Workflow Runs
+
+Identify the failing workflow execution by listing recent runs. The `output-workflow-runs-list` skill provides detailed filtering guidance.
+
+<list_commands>
+```bash
+# List all recent workflow runs
+output workflow runs list
+
+# Filter by specific workflow type (if known)
+output workflow runs list <workflowName>
+
+# Get detailed JSON output for analysis
+output workflow runs list --format json
+
+# Limit results to most recent
+output workflow runs list --limit 10
+```
+</list_commands>
+
+<identification_criteria>
+Look for:
+- Status: FAILED or TERMINATED
+- Recent timestamp matching when the issue occurred
+- Workflow type matching the problem description
+</identification_criteria>
+
+<decision_tree>
+  IF user_provided_workflow_id:
+    USE: provided workflow ID
+    PROCEED: to step 3
+  IF failed_runs_found:
+    SELECT: most recent failed run
+    NOTE: workflow ID from output
+    PROCEED: to step 3
+  IF no_runs_found:
+    CHECK: workflow exists with `output workflow list`
+    IF workflow_not_found:
+      REPORT: workflow doesn't exist
+      SUGGEST: verify workflow name and location
+    ELSE:
+      SUGGEST: run the workflow with `output workflow run <name>`
+</decision_tree>
+
+</step>
+
+<step number="3" name="debug_workflow" subagent="workflow-debugger">
+
+### Step 3: Debug Specific Workflow
+
+Retrieve and analyze the execution trace for the identified workflow. The `output-workflow-trace` skill provides analysis techniques.
+
+<debug_commands>
+```bash
+# Display execution trace (text format)
+output workflow debug <workflowId>
+
+# Display full untruncated trace (JSON format) - recommended for detailed analysis
+output workflow debug <workflowId> --format json
+```
+</debug_commands>
+
+**Tip**: Use `--format json` for complete trace data without truncation.
+
+<analysis_checklist>
+1. Identify which step failed
+2. Examine the error message and stack trace
+3. Check input data passed to the failing step
+4. Check output data from preceding steps
+5. Look for patterns matching common error types
+</analysis_checklist>
+
+<temporal_ui_guidance>
+For visual workflow inspection, open the Temporal Web UI at **http://localhost:8080**:
+- Find your workflow execution by ID
+- View the event history timeline
+- Inspect individual step inputs and outputs
+</temporal_ui_guidance>
+
+</step>
+
+<step number="4" name="suggest_fixes" subagent="workflow-quality">
+
+### Step 4: Suggest Fixes
+
+Based on the trace analysis, identify the error pattern and suggest targeted fixes. Claude will invoke the relevant error skill based on symptoms.
+
+<error_matching>
+
+| Symptom | Skill |
+|---------|-------|
+| "incompatible schema" errors, type errors | `output-error-zod-import` |
+| Replay failures, inconsistent results | `output-error-nondeterminism` |
+| Retries not working, errors swallowed | `output-error-try-catch` |
+| Type errors, undefined properties at step boundaries | `output-error-missing-schemas` |
+| Workflow hangs, determinism errors | `output-error-direct-io` |
+| Untraced requests, axios errors | `output-error-http-client` |
+
+</error_matching>
+
+<decision_tree>
+  IF error_matches_known_pattern:
+    INVOKE: relevant error skill for detailed fix
+  ELSE:
+    CONSULT: workflow-quality subagent for additional patterns
+    SUGGEST: Manual trace inspection in Temporal UI
+</decision_tree>
+
+<verification>
+After applying fix:
+```bash
+# Re-run the workflow to verify
+output workflow run <workflowName> <input>
+
+# Or start asynchronously and check result
+output workflow start <workflowName> <input>
+output workflow status <workflowId>
+output workflow result <workflowId>
+```
+</verification>
+
+</step>
+
+</process_flow>
+
+<post_flight_check>
+  EXECUTE: @.outputai/instructions/meta/post_flight.md
+</post_flight_check>
+
+---- START ----
+
+Problem Description and Optional Workflow ID:
+
+$ARGUMENTS

package/dist/templates/agent_instructions/commands/plan_workflow.md.template

@@ -25,7 +25,7 @@ Generate detailed specifications for implementation of a new workflow.
 
 <process_flow>
 
-<step number="1" name="context_gathering" subagent="context-fetcher">
+<step number="1" name="context_gathering" subagent="workflow-context-fetcher">
 
 ### Step 1: Context Gathering
 
@@ -130,7 +130,7 @@ export const sumValues = step( {
 
 </step>
 
-<step number="5" name="prompt_engineering" subagent="prompt-writer">
+<step number="5" name="prompt_engineering" subagent="workflow-prompt-writer">
 
 ### Step 5: Prompt Engineering
 

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

@@ -0,0 +1,249 @@
+---
+name: output-error-direct-io
+description: Fix direct I/O in Output SDK workflow functions. Use when workflow hangs, returns undefined, shows "workflow must be deterministic" errors, or when HTTP/API calls are made directly in workflow code.
+allowed-tools: [Bash, Read]
+---
+
+# Fix Direct I/O in Workflow Functions
+
+## Overview
+
+This skill helps diagnose and fix a critical error pattern where I/O operations (HTTP calls, database queries, file operations) are performed directly in workflow functions instead of in steps. This violates Temporal's determinism requirements.
+
+## When to Use This Skill
+
+You're seeing:
+- Workflow hangs indefinitely
+- Undefined or empty responses
+- "workflow must be deterministic" errors
+- Network operations failing silently
+- Timeouts without clear cause
+
+## Root Cause
+
+Workflow functions must be **deterministic** - they should only orchestrate steps, not perform I/O directly. When you make HTTP calls, database queries, or any external operations directly in a workflow function:
+
+1. **Hangs**: The workflow may hang because I/O isn't properly handled
+2. **Determinism violations**: Temporal replays workflows, and I/O results differ
+3. **No retry logic**: Direct calls bypass Output SDK's retry mechanisms
+4. **No tracing**: Operations aren't recorded in the workflow trace
+
+## Symptoms
+
+### Direct fetch/axios in Workflow
+
+```typescript
+// WRONG: I/O directly in workflow
+export default workflow({
+  fn: async (input) => {
+    const response = await fetch('https://api.example.com/data');  // BAD!
+    const data = await response.json();
+    return { data };
+  }
+});
+```
+
+### Direct Database Calls
+
+```typescript
+// WRONG: Database I/O in workflow
+export default workflow({
+  fn: async (input) => {
+    const user = await db.users.findById(input.userId);  // BAD!
+    return { user };
+  }
+});
+```
+
+### File System Operations
+
+```typescript
+// WRONG: File I/O in workflow
+import fs from 'fs/promises';
+
+export default workflow({
+  fn: async (input) => {
+    const data = await fs.readFile(input.path, 'utf-8');  // BAD!
+    return { data };
+  }
+});
+```
+
+## Solution
+
+Move ALL I/O operations to step functions. Steps are designed to handle non-deterministic operations.
+
+### Before (Wrong)
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    const response = await fetch('https://api.example.com/data');
+    const data = await response.json();
+    return { data };
+  }
+});
+```
+
+### After (Correct)
+
+```typescript
+import { z, step, workflow } from '@output.ai/core';
+import { httpClient } from '@output.ai/http';
+
+// Create a step for the I/O operation
+export const fetchData = step({
+  name: 'fetchData',
+  inputSchema: z.object({
+    endpoint: z.string(),
+  }),
+  outputSchema: z.object({
+    data: z.unknown(),
+  }),
+  fn: async (input) => {
+    const client = httpClient({ prefixUrl: 'https://api.example.com' });
+    const data = await client.get(input.endpoint).json();
+    return { data };
+  },
+});
+
+// Workflow only orchestrates steps
+export default workflow({
+  inputSchema: z.object({}),
+  outputSchema: z.object({ data: z.unknown() }),
+  fn: async (input) => {
+    const result = await fetchData({ endpoint: 'data' });
+    return result;
+  },
+});
+```
+
+## Complete Example: Database Operation
+
+### Before (Wrong)
+
+```typescript
+export default workflow({
+  fn: async (input) => {
+    const user = await prisma.user.findUnique({
+      where: { id: input.userId }
+    });
+    const orders = await prisma.order.findMany({
+      where: { userId: input.userId }
+    });
+    return { user, orders };
+  }
+});
+```
+
+### After (Correct)
+
+```typescript
+import { z, step, workflow } from '@output.ai/core';
+import { prisma } from '../lib/db';
+
+export const fetchUser = step({
+  name: 'fetchUser',
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }).nullable(),
+  }),
+  fn: async (input) => {
+    const user = await prisma.user.findUnique({
+      where: { id: input.userId }
+    });
+    return { user };
+  },
+});
+
+export const fetchOrders = step({
+  name: 'fetchOrders',
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    orders: z.array(z.object({
+      id: z.string(),
+      total: z.number(),
+    })),
+  }),
+  fn: async (input) => {
+    const orders = await prisma.order.findMany({
+      where: { userId: input.userId }
+    });
+    return { orders };
+  },
+});
+
+export default workflow({
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    user: z.unknown(),
+    orders: z.array(z.unknown()),
+  }),
+  fn: async (input) => {
+    const { user } = await fetchUser({ userId: input.userId });
+    const { orders } = await fetchOrders({ userId: input.userId });
+    return { user, orders };
+  },
+});
+```
+
+## Finding Direct I/O in Workflows
+
+Search for common I/O patterns in workflow files:
+
+```bash
+# Find fetch calls
+grep -rn "await fetch" src/workflows/
+
+# Find axios calls
+grep -rn "axios\." src/workflows/
+
+# Find database operations
+grep -rn "prisma\.\|db\.\|mongoose\." src/workflows/
+
+# Find file system operations
+grep -rn "fs\.\|readFile\|writeFile" src/workflows/
+```
+
+Then review each match to see if it's in a workflow function vs a step function.
+
+## What CAN Be in Workflow Functions
+
+Workflow functions should contain:
+- **Step calls**: `await myStep(input)`
+- **Orchestration logic**: conditionals, loops (over step calls)
+- **Data transformation**: Pure functions on step results
+- **Constants**: Static values and configuration
+
+Workflow functions should NOT contain:
+- HTTP/API calls
+- Database operations
+- File system operations
+- External service calls
+- Anything that talks to the network or filesystem
+
+## Verification
+
+After moving I/O to steps:
+
+1. **Run the workflow**: `output workflow run <name> '<input>'`
+2. **Check the trace**: `output workflow debug <id> --format json`
+3. **Verify steps appear**: Look for your I/O steps in the trace
+4. **Confirm no errors**: No determinism warnings or hangs
+
+## Benefits of Steps for I/O
+
+1. **Retry logic**: Steps can be retried on failure
+2. **Tracing**: I/O operations appear in workflow traces
+3. **Timeouts**: Steps can have individual timeouts
+4. **Determinism**: Replays use recorded results
+5. **Debugging**: Clear visibility into what happened
+
+## Related Issues
+
+- For HTTP client best practices, see `output-error-http-client`
+- For non-determinism from other causes, see `output-error-nondeterminism`