@output.ai/cli 0.3.1-dev.pr156.0 → 0.4.0

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

@@ -0,0 +1,244 @@
+---
+name: workflow-quality
+description: Use this agent when you need expert guidance on Output SDK implementation patterns, code quality, and best practices. Invoke when writing or reviewing workflow code, troubleshooting implementation issues, or ensuring code follows SDK conventions.
+model: sonnet
+color: green
+---
+
+# Output SDK Best Practices Agent
+
+## Identity
+
+You are an Output SDK implementation expert who ensures workflow code follows best practices, avoids common pitfalls, and adheres to SDK conventions. You focus on code quality, correctness, and maintainability.
+
+## Context Retrieval
+
+Use the `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:
+- Creating new `.prompt` files
+- Reviewing or debugging prompt template syntax
+- Understanding Liquid.js syntax and YAML frontmatter
+
+## Core Expertise
+
+- **Workflow Implementation**: Correct patterns for workflow definitions and orchestration
+- **Step Design**: Proper step boundaries, I/O schemas, and retry policies
+- **LLM Integration**: Prompt file format, generation functions, template syntax
+- **HTTP Client**: Traced HTTP requests with proper error handling
+- **Type Safety**: Zod schemas and TypeScript integration
+- **Error Handling**: ValidationError, FatalError, and retry strategies
+
+## Critical Rules
+
+### Import Conventions
+
+**CRITICAL**: Always import `z` from `@output.ai/core`, NEVER from `zod` directly:
+```typescript
+// Wrong
+import { z } from 'zod';
+
+// Correct
+import { z } from '@output.ai/core';
+```
+
+### Workflow Determinism
+
+Workflows must be deterministic. They can ONLY:
+- Call steps and evaluators
+- Use control flow (if/else, loops)
+- Access input parameters
+
+Workflows must NOT contain:
+- Direct HTTP/API calls (wrap in steps)
+- `Math.random()`, `Date.now()`, `crypto.randomUUID()`
+- Dynamic imports
+- File system operations
+
+### Step Boundaries
+
+All I/O operations must be wrapped in steps:
+```typescript
+// Wrong - I/O in workflow
+export default workflow({
+  fn: async (input) => {
+    const data = await fetch('https://api.example.com'); // ❌
+    return { data };
+  }
+});
+
+// Correct - I/O in step
+export const fetchData = step({
+  name: 'fetchData',
+  fn: async (input) => {
+    const client = httpClient({ prefixUrl: 'https://api.example.com' });
+    return client.get('endpoint').json();
+  }
+});
+```
+
+### No Try-Catch Wrapping
+
+Don't wrap step calls in try-catch blocks. Allow failures to propagate:
+```typescript
+// Wrong
+fn: async (input) => {
+  try {
+    const result = await myStep(input);
+    return result;
+  } catch (error) {
+    throw new FatalError(error.message);
+  }
+}
+
+// Correct
+fn: async (input) => {
+  const result = await myStep(input);
+  return result;
+}
+```
+
+### HTTP Client Usage
+
+Never use axios directly. Use `@output.ai/http`:
+```typescript
+import { httpClient } from '@output.ai/http';
+
+const client = httpClient({
+  prefixUrl: 'https://api.example.com',
+  timeout: 30000,
+  retry: { limit: 3 }
+});
+
+// GET request
+const data = await client.get('endpoint').json();
+
+// POST request
+const result = await client.post('endpoint', { json: payload }).json();
+```
+
+### LLM Integration
+
+Never call LLM APIs directly. Use `@output.ai/llm`:
+```typescript
+import { generateText, generateObject, generateArray, generateEnum } from '@output.ai/llm';
+
+// Text generation
+const text = await generateText({
+  prompt: 'prompts/my_prompt@v1',
+  variables: { topic: 'AI' }
+});
+
+// Structured output
+const data = await generateObject({
+  prompt: 'prompts/extract@v1',
+  variables: { text },
+  schema: z.object({ title: z.string(), summary: z.string() })
+});
+```
+
+### Schema Definitions
+
+Define input/output schemas with Zod:
+```typescript
+import { step, z } from '@output.ai/core';
+
+export const processData = step({
+  name: 'processData',
+  inputSchema: z.object({
+    id: z.string(),
+    count: z.number().optional()
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+    processed: z.boolean()
+  }),
+  fn: async (input) => {
+    // input is typed as { id: string, count?: number }
+    return { result: input.id, processed: true };
+  }
+});
+```
+
+### Retry Policies
+
+Configure retry policies in step options:
+```typescript
+export const riskyStep = step({
+  name: 'riskyStep',
+  fn: async (input) => { /* ... */ },
+  options: {
+    retry: {
+      maximumAttempts: 3,
+      initialInterval: '1s',
+      maximumInterval: '10s',
+      backoffCoefficient: 2
+    },
+    startToCloseTimeout: '30s'
+  }
+});
+```
+
+### Error Types
+
+Use appropriate error types:
+```typescript
+import { FatalError, ValidationError } from '@output.ai/core';
+
+// Non-retryable error (workflow fails immediately)
+throw new FatalError('Critical failure - do not retry');
+
+// Validation error (schema/input validation)
+throw new ValidationError('Invalid input format');
+```
+
+## File Structure
+
+```
+src/workflows/{name}/
+  workflow.ts          # Workflow definition (orchestration only)
+  steps.ts             # Step definitions (all I/O here)
+  evaluators.ts        # Evaluators (optional)
+  types.ts             # Shared types and schemas (optional)
+  prompts/             # Prompt files directory
+    name@v1.prompt     # Versioned prompt templates
+  scenarios/           # Test scenarios directory
+    basic.json         # Common run case examples
+    edge_cases.json    # Edge case scenarios
+```
+
+### Allowed Imports in Workflows
+
+Workflows can only import from:
+- `steps.ts`, `evaluators.ts`, `shared_steps.ts`
+- Whitelisted: `types.ts`, `consts.ts`, `utils.ts`, `variables.ts`, `tools.ts`
+
+## Common Pitfalls
+
+### 1. Zod Import Source
+Always import `z` from `@output.ai/core`, never from `zod` directly. Different `z` instances create incompatible schemas.
+
+### 2. Direct API Calls
+Never make HTTP/LLM calls directly in workflows. Always wrap in steps.
+
+### 3. Non-Deterministic Operations
+No `Math.random()`, `Date.now()`, or `crypto` in workflows.
+
+### 4. Try-Catch Blocks
+Don't wrap step calls in try-catch. Let failures propagate for proper retry handling.
+
+### 5. Missing Schemas
+Always define inputSchema and outputSchema for type safety and validation.
+
+## Example Interaction
+
+**User**: "My workflow is failing with a type error on the schema"
+**Agent**: Check that you're importing `z` from `@output.ai/core`, not `zod`. Different `z` instances create incompatible schemas.
+
+**User**: "How do I make an HTTP request in my workflow?"
+**Agent**: Create a step that uses `@output.ai/http`. Never make HTTP calls directly in the workflow function.
+
+---
+*This agent specializes in Output SDK implementation best practices and code quality.*

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">
+<step number="1" name="plan_analysis" subagent="context-fetcher">
 
 ### Step 1: Plan Analysis
 
@@ -40,7 +40,7 @@ Read and understand the plan document.
 
 </step>
 
-<step number="2" name="workflow_implementation">
+<step number="2" name="workflow_implementation" subagent="workflow-quality">
 
 ### Step 2: Workflow Implementation
 
@@ -85,7 +85,7 @@ export default workflow( {
 
 </step>
 
-<step number="3" name="steps_implementation">
+<step number="3" name="steps_implementation" subagent="workflow-quality">
 
 ### Step 3: Steps Implementation
 
@@ -122,7 +122,7 @@ export const stepName = step( {
 
 </step>
 
-<step number="4" name="prompt_templates">
+<step number="4" name="prompt_templates" subagent="prompt-writer">
 
 ### Step 4: Prompt Templates (if needed)
 
@@ -133,7 +133,7 @@ If the plan includes LLM-based steps, create prompt templates in `$3/prompts/`.
     CREATE prompt_templates
     UPDATE steps.ts to use loadPrompt and generateText
   ELSE:
-    SKIP to step 5
+    SKIP to step 6
 </decision_tree>
 
 <llm_step_template>
@@ -197,9 +197,51 @@ Update `$3/README.md` with workflow-specific documentation.
 
 </step>
 
-<step number="6" name="validation">
+<step number="6" name="scenario_creation">
 
-### Step 6: Implementation Validation
+### Step 6: Scenario File Creation
+
+Create at least one scenario file in `$3/scenarios/` for testing the workflow.
+
+<scenario_requirements>
+  - Create `scenarios/` directory if it doesn't exist
+  - Create `test_input.json` with valid example input matching the inputSchema
+  - Input values should be realistic and demonstrate the workflow's purpose
+  - JSON must be valid and parseable
+</scenario_requirements>
+
+<scenario_template>
+```json
+{
+  // Populate with example values matching inputSchema
+  // Use realistic test data that demonstrates the workflow
+}
+```
+</scenario_template>
+
+<example>
+For a workflow with inputSchema:
+```typescript
+z.object({
+  topic: z.string(),
+  maxLength: z.number().optional()
+})
+```
+
+Create `scenarios/test_input.json`:
+```json
+{
+  "topic": "The history of artificial intelligence",
+  "maxLength": 500
+}
+```
+</example>
+
+</step>
+
+<step number="7" name="validation" subagent="workflow-quality">
+
+### Step 7: Implementation Validation
 
 Verify the implementation is complete and correct.
 
@@ -212,13 +254,14 @@ Verify the implementation is complete and correct.
   - README is updated with accurate information
   - Code follows Output SDK patterns
   - TypeScript types are properly defined
+  - Scenario file exists with valid example input
 </validation_checklist>
 
 </step>
 
-<step number="7" name="post_flight_check">
+<step number="8" name="post_flight_check">
 
-### Step 7: Post-Flight Check
+### Step 8: Post-Flight Check
 
 Verify the implementation is ready for use.
 

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">
+<step number="1" name="context_gathering" subagent="context-fetcher">
 
 ### Step 1: Context Gathering
 
@@ -63,7 +63,7 @@ Clarify scope boundaries and technical considerations by asking numbered questio
 </decision_tree>
 </step>
 
-<step number="3" name="workflow_design">
+<step number="3" name="workflow_design" subagent="workflow-quality">
 
 ### Step 3: Workflow Design
 
@@ -109,7 +109,7 @@ export default workflow( {
 ```
 </workflow_template>
 
-<step number="4" name="step_design">
+<step number="4" name="step_design" subagent="workflow-quality">
 ### Step 4: Step Design
 
 Design the steps with clear boundaries.
@@ -130,7 +130,7 @@ export const sumValues = step( {
 
 </step>
 
-<step number="5" name="prompt_engineering">
+<step number="5" name="prompt_engineering" subagent="prompt-writer">
 
 ### Step 5: Prompt Engineering
 

package/dist/templates/project/package.json.template

@@ -12,12 +12,12 @@
   "dependencies": {
     "@output.ai/core": "^{{coreVersion}}",
     "@output.ai/llm": "^{{llmVersion}}",
-    "@output.ai/http": "^{{httpVersion}}",
-    "copyfiles": "^{{cliVersion}}"
+    "@output.ai/http": "^{{httpVersion}}"
   },
   "devDependencies": {
     "@output.ai/cli": "latest",
     "@types/node": "^22.0.0",
+    "copyfiles": "^1.0.0",
     "typescript": "^5.7.0"
   },
   "engines": {

package/dist/templates/project/src/simple/scenarios/question_ada_lovelace.json.template

@@ -0,0 +1,3 @@
+{
+  "question": "who really is ada lovelace?"
+}

package/dist/templates/workflow/scenarios/test_input.json.template

@@ -0,0 +1,7 @@
+{
+  "prompt": "Tell me about the history of computing",
+  "data": {
+    "value": 42,
+    "type": "example"
+  }
+}

package/dist/types/trace.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Trace types for workflow execution data.
+ *
+ * These types represent the structure of trace files generated during workflow execution,
+ * used for debugging, visualization, and analysis of workflow runs.
+ */
+/** Node kind values for trace events */
+export type NodeKind = 'workflow' | 'activity' | 'step' | 'internal_step' | string;
+/** Phase of a trace event lifecycle */
+export type NodePhase = 'start' | 'end' | 'error' | string;
+/** Execution status of a node */
+export type NodeStatus = 'completed' | 'failed' | 'running' | string;
+/**
+ * Details associated with a trace event.
+ * Contains input/output data and identifying information for the event.
+ */
+export interface TraceDetails {
+    /** Input data passed to the step/activity */
+    input?: unknown;
+    /** Output data returned from the step/activity */
+    output?: unknown;
+    /** Name of the activity (for activity events) */
+    activityName?: string;
+    /** Name of the step (for step events) */
+    stepName?: string;
+    /** Generic name field */
+    name?: string;
+}
+/**
+ * A trace event representing a point in workflow execution.
+ * Used for timeline display and event-based analysis.
+ */
+export interface TraceEvent {
+    /** The type of event (workflow, activity, step, etc.) */
+    kind: NodeKind;
+    /** The lifecycle phase of the event */
+    phase: NodePhase;
+    /** Unix timestamp when the event occurred */
+    timestamp: number;
+    /** Unique identifier for the workflow run */
+    workflowId: string;
+    /** Name of the workflow being executed */
+    workflowName: string;
+    /** Additional event details including input/output */
+    details?: TraceDetails;
+    /** Child events for nested executions */
+    children?: TraceEvent[];
+    /** Error information if the event represents a failure */
+    error?: unknown;
+    /** Duration of the event in milliseconds */
+    duration?: number;
+}
+/**
+ * A node in the debug tree representation of workflow execution.
+ * Contains more detailed timing and state information than TraceEvent.
+ */
+export interface DebugNode {
+    /** The type of node (workflow, activity, step, internal_step) */
+    kind?: NodeKind;
+    /** Alternative type field */
+    type?: string;
+    /** The name of the step or activity */
+    name?: string;
+    /** Name of the workflow (for workflow nodes) */
+    workflowName?: string;
+    /** Name of the step (for step nodes) */
+    stepName?: string;
+    /** Name of the activity (for activity nodes) */
+    activityName?: string;
+    /** The lifecycle phase of the node */
+    phase?: NodePhase;
+    /** Execution status (completed, failed, running) */
+    status?: NodeStatus;
+    /** Unix timestamp or ISO string when execution started */
+    startedAt?: number | string;
+    /** Unix timestamp when the event occurred */
+    timestamp?: number | string;
+    /** Unix timestamp or ISO string when execution ended */
+    endedAt?: number | string;
+    /** Unix timestamp when execution started (alternative field) */
+    startTime?: number;
+    /** Unix timestamp when execution ended (alternative field) */
+    endTime?: number;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Input data passed to the step/activity */
+    input?: unknown;
+    /** Output data returned from the step/activity */
+    output?: unknown;
+    /** Additional execution details */
+    details?: Record<string, unknown>;
+    /** Error information if the node failed */
+    error?: unknown;
+    /** Child nodes representing nested executions */
+    children?: DebugNode[];
+}
+/**
+ * Root structure of a workflow trace.
+ * Contains the execution tree and optional flat event list.
+ */
+export interface TraceStructure {
+    /** Root node of the execution tree */
+    root?: TraceEvent | DebugNode;
+    /** Flat list of execution events for timeline display */
+    events?: TraceEvent[];
+    /** Hierarchical tree of execution nodes (alternative to root.children) */
+    children?: DebugNode[];
+}
+/**
+ * The structure of a workflow trace file generated by Output SDK workflow runs.
+ * This file is written to the local filesystem during workflow execution and contains
+ * the complete execution history including timing, inputs, outputs, and any errors.
+ */
+export interface TraceData {
+    /** Root workflow execution information */
+    root: {
+        /** The name of the workflow that was executed */
+        workflowName: string;
+        /** Unique identifier for this workflow run */
+        workflowId: string;
+        /** Unix timestamp when the workflow started */
+        startTime: number;
+        /** Unix timestamp when the workflow ended */
+        endTime?: number;
+        /** Total workflow duration in milliseconds */
+        duration?: number;
+        /** Final workflow status */
+        status?: string;
+        /** Error information if the workflow failed */
+        error?: unknown;
+    };
+    /** Flat list of execution events for timeline display */
+    events?: Array<{
+        name: string;
+        phase: string;
+        timestamp: number;
+        details?: unknown;
+    }>;
+    /** Hierarchical tree of execution nodes */
+    children?: DebugNode[];
+}
+/**
+ * Extracted node information for display formatting.
+ * Used internally by the trace formatter.
+ */
+export interface NodeInfo {
+    /** Display name for the node */
+    name: string;
+    /** Formatted phase indicator */
+    phase: string;
+    /** Formatted duration string */
+    duration: string;
+}
+/**
+ * Type guard to check if a node is a TraceEvent.
+ */
+export declare const isTraceEvent: (node: TraceEvent | DebugNode) => node is TraceEvent;
+/**
+ * Type guard to check if a value is a valid timestamp.
+ */
+export declare const isValidTimestamp: (value: unknown) => value is number | string;

package/dist/types/trace.js

@@ -0,0 +1,18 @@
+/**
+ * Trace types for workflow execution data.
+ *
+ * These types represent the structure of trace files generated during workflow execution,
+ * used for debugging, visualization, and analysis of workflow runs.
+ */
+/**
+ * Type guard to check if a node is a TraceEvent.
+ */
+export const isTraceEvent = (node) => {
+    return 'workflowId' in node && 'timestamp' in node;
+};
+/**
+ * Type guard to check if a value is a valid timestamp.
+ */
+export const isValidTimestamp = (value) => {
+    return typeof value === 'number' || typeof value === 'string';
+};

package/dist/utils/date_formatter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * Uses date-fns for durations >= 1 minute, custom formatting for shorter durations.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string (e.g., "150ms", "2.50s", "3 minutes 45 seconds")
+ */
+export declare function formatDuration(ms: number): string;

package/dist/utils/date_formatter.js

@@ -0,0 +1,19 @@
+import { formatDuration as formatDurationFns, intervalToDuration } from 'date-fns';
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * Uses date-fns for durations >= 1 minute, custom formatting for shorter durations.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string (e.g., "150ms", "2.50s", "3 minutes 45 seconds")
+ */
+export function formatDuration(ms) {
+    const duration = intervalToDuration({ start: 0, end: ms });
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60000) {
+        const seconds = ms / 1000;
+        return `${seconds.toFixed(2)}s`;
+    }
+    return formatDurationFns(duration, { format: ['minutes', 'seconds'] });
+}

package/dist/utils/template.spec.js

@@ -53,6 +53,12 @@ describe('Template Utilities', () => {
             expect(processTemplate(template, variables))
                 .toBe('myWorkflowName and MyWorkflowName');
         });
+        it('should preserve escaped curly braces for Liquid.js examples', () => {
+            const template = 'Use Liquid: \\{{ variable }} and {% if %}...{% endif %}';
+            const variables = {};
+            expect(processTemplate(template, variables))
+                .toBe('Use Liquid: {{ variable }} and {% if %}...{% endif %}');
+        });
     });
     describe('prepareTemplateVariables', () => {
         it('should prepare variables from workflow name and description', () => {