@output.ai/cli 0.3.0-dev.pr156.c8e7f40 → 0.3.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/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', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/cli",
-  "version": "0.3.0-dev.pr156.c8e7f40",
+  "version": "0.3.0",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,6 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.1.19",
-    "@aws-sdk/client-s3": "^3.689.0",
     "@inquirer/prompts": "7.9.0",
     "@oclif/core": "4.5.6",
     "@oclif/plugin-help": "6.2.33",

package/dist/commands/workflow/debug.d.ts

@@ -1,15 +0,0 @@
-import { Command } from '@oclif/core';
-export default class WorkflowDebug extends Command {
-    static description: string;
-    static examples: string[];
-    static args: {
-        workflowId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    static flags: {
-        format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-    };
-    run(): Promise<void>;
-    private getTrace;
-    private outputJson;
-    private displayTextTrace;
-}

package/dist/commands/workflow/debug.js

@@ -1,55 +0,0 @@
-import { Args, Command, Flags } from '@oclif/core';
-import { OUTPUT_FORMAT } from '#utils/constants.js';
-import { traceFormatter } from '#utils/trace_formatter.js';
-import { findTraceFile, readTraceFile } from '#services/trace_reader.js';
-export default class WorkflowDebug extends Command {
-    static description = 'Get and display workflow execution trace for debugging';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> wf-12345',
-        '<%= config.bin %> <%= command.id %> wf-12345 --format json',
-        '<%= config.bin %> <%= command.id %> wf-12345 --format text'
-    ];
-    static args = {
-        workflowId: Args.string({
-            description: 'The workflow ID to debug',
-            required: true
-        })
-    };
-    static flags = {
-        format: Flags.string({
-            char: 'f',
-            description: 'Output format',
-            options: [OUTPUT_FORMAT.JSON, OUTPUT_FORMAT.TEXT],
-            default: OUTPUT_FORMAT.TEXT
-        })
-    };
-    async run() {
-        const { args, flags } = await this.parse(WorkflowDebug);
-        const isJsonFormat = flags.format === OUTPUT_FORMAT.JSON;
-        if (!isJsonFormat) {
-            this.log(`Fetching debug information for workflow: ${args.workflowId}...`);
-        }
-        const traceData = await this.getTrace(args.workflowId);
-        // Output based on format
-        if (isJsonFormat) {
-            this.outputJson(traceData);
-            return;
-        }
-        // Display text format
-        this.displayTextTrace(traceData);
-    }
-    async getTrace(workflowId) {
-        const tracePath = await findTraceFile(workflowId);
-        return readTraceFile(tracePath);
-    }
-    outputJson(data) {
-        this.log(JSON.stringify(data, null, 2));
-    }
-    displayTextTrace(traceData) {
-        this.log('\nTrace Log:');
-        this.log('─'.repeat(80));
-        this.log(traceFormatter.displayDebugTree(traceData));
-        this.log('\n' + '─'.repeat(80));
-        this.log('Tip: Use --format json for complete verbose output');
-    }
-}

package/dist/commands/workflow/debug.test.js

@@ -1,75 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-// Mock the TraceReader service
-vi.mock('../../services/trace_reader.js', () => ({
-    TraceReader: vi.fn().mockImplementation(() => ({
-        findTraceFile: vi.fn(),
-        readTraceFile: vi.fn()
-    }))
-}));
-// Mock the utilities
-vi.mock('../../utils/trace_formatter.js', () => ({
-    traceFormatter: {
-        displayDebugTree: vi.fn()
-    }
-}));
-describe('workflow debug command', () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-    describe('command definition', () => {
-        it('should export a valid OCLIF command', async () => {
-            const WorkflowDebug = (await import('./debug.js')).default;
-            expect(WorkflowDebug).toBeDefined();
-            expect(WorkflowDebug.description).toContain('Get and display workflow execution trace for debugging');
-            expect(WorkflowDebug.args).toHaveProperty('workflowId');
-            expect(WorkflowDebug.flags).toHaveProperty('format');
-        });
-        it('should have correct flag configuration', async () => {
-            const WorkflowDebug = (await import('./debug.js')).default;
-            // Format flag
-            expect(WorkflowDebug.flags.format.options).toEqual(['json', 'text']);
-            expect(WorkflowDebug.flags.format.default).toBe('text');
-        });
-        it('should have correct examples', async () => {
-            const WorkflowDebug = (await import('./debug.js')).default;
-            expect(WorkflowDebug.examples).toBeDefined();
-            expect(WorkflowDebug.examples.length).toBeGreaterThan(0);
-        });
-    });
-    describe('run method', () => {
-        beforeEach(() => {
-            // Clear mocks before each test
-            vi.clearAllMocks();
-        });
-        it('should fetch and display trace when available', async () => {
-            // This test requires OCLIF framework initialization which is complex to mock
-            // The functionality is tested through manual testing and the build process
-            expect(true).toBe(true);
-        });
-        it('should output JSON when --format json is set', async () => {
-            // This test requires OCLIF framework initialization which is complex to mock
-            // The functionality is tested through manual testing and the build process
-            expect(true).toBe(true);
-        });
-        it('should handle trace file not found error', async () => {
-            // This test requires mocking TraceReader instance methods
-            // The functionality is tested through manual testing and the build process
-            expect(true).toBe(true);
-        });
-        it('should handle file read errors', async () => {
-            // This test requires mocking TraceReader instance methods
-            // The functionality is tested through manual testing and the build process
-            expect(true).toBe(true);
-        });
-        it('should display trace in text format by default', async () => {
-            // This test requires OCLIF framework initialization which is complex to mock
-            // The functionality is tested through manual testing and the build process
-            expect(true).toBe(true);
-        });
-        it('should display tip message for verbose output', async () => {
-            // This test requires OCLIF framework initialization which is complex to mock
-            // The functionality is tested through manual testing and the build process
-            expect(true).toBe(true);
-        });
-    });
-});

package/dist/services/trace_reader.d.ts

@@ -1,8 +0,0 @@
-/**
- * Find trace file from workflow metadata
- */
-export declare function findTraceFile(workflowId: string): Promise<string>;
-/**
- * Read and parse trace file
- */
-export declare function readTraceFile(path: string): Promise<any>;

package/dist/services/trace_reader.js

@@ -1,51 +0,0 @@
-import { readFile, stat } from 'node:fs/promises';
-import { getWorkflowIdOutput } from '#api/generated/api.js';
-/**
- * Check if a file exists
- */
-async function fileExists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Find trace file from workflow metadata
- */
-export async function findTraceFile(workflowId) {
-    const response = await getWorkflowIdOutput(workflowId);
-    // Check if we got a successful response
-    if (response.status !== 200) {
-        throw new Error(`Failed to get workflow output for ${workflowId}`);
-    }
-    const tracePath = response.data.trace?.destinations?.local;
-    if (!tracePath) {
-        throw new Error(`No trace file path found for workflow ${workflowId}`);
-    }
-    if (!await fileExists(tracePath)) {
-        throw new Error(`Trace file not found at path: ${tracePath}`);
-    }
-    return tracePath;
-}
-/**
- * Read and parse trace file
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export async function readTraceFile(path) {
-    try {
-        const content = await readFile(path, 'utf-8');
-        return JSON.parse(content);
-    }
-    catch (error) {
-        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
-            throw new Error(`Trace file not found at path: ${path}`);
-        }
-        if (error instanceof SyntaxError) {
-            throw new Error(`Invalid JSON in trace file: ${path}`);
-        }
-        throw error;
-    }
-}

package/dist/services/trace_reader.test.d.ts

@@ -1 +0,0 @@
-export {};