@polka-codes/cli 0.9.79 → 0.9.80

package/dist/index.js

@@ -37660,7 +37660,7 @@ var {
   Help
 } = import__.default;
 // package.json
-var version = "0.9.79";
+var version = "0.9.80";
 
 // src/commands/code.ts
 import { readFile as readFile4 } from "node:fs/promises";
@@ -64205,7 +64205,8 @@ var WorkflowStepDefinitionSchema = exports_external.object({
   output: exports_external.string().nullish(),
   expected_outcome: exports_external.string().nullish(),
   code: exports_external.string().nullish(),
-  outputSchema: exports_external.any().nullish()
+  outputSchema: exports_external.any().nullish(),
+  timeout: exports_external.number().positive().nullish()
 });
 var WorkflowDefinitionSchema = exports_external.object({
   task: exports_external.string(),
@@ -64231,6 +64232,29 @@ function parseDynamicWorkflowDefinition(source) {
   }
 }
 var AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
+function validateAndApplyDefaults(workflowId, workflow, input) {
+  if (!workflow.inputs || workflow.inputs.length === 0) {
+    return input;
+  }
+  const validatedInput = {};
+  const errors4 = [];
+  for (const inputDef of workflow.inputs) {
+    const providedValue = input[inputDef.id];
+    if (providedValue !== undefined && providedValue !== null) {
+      validatedInput[inputDef.id] = providedValue;
+    } else if (inputDef.default !== undefined && inputDef.default !== null) {
+      validatedInput[inputDef.id] = inputDef.default;
+    } else {
+      errors4.push(`Missing required input '${inputDef.id}'${inputDef.description ? `: ${inputDef.description}` : ""}`);
+    }
+  }
+  if (errors4.length > 0) {
+    throw new Error(`Workflow '${workflowId}' input validation failed:
+${errors4.map((e) => `  - ${e}`).join(`
+`)}`);
+  }
+  return validatedInput;
+}
 function createRunWorkflowFn(args) {
   return async (subWorkflowId, subInput) => {
     const mergedInput = { ...args.input, ...args.state, ...subInput ?? {} };
@@ -64251,7 +64275,14 @@ function compileStep(stepDef, workflowId, compiledSteps) {
     compiledSteps.set(key, fn);
     return fn;
   } catch (error46) {
-    throw new Error(`Failed to compile code for step '${stepDef.id}' in workflow '${workflowId}': ${error46 instanceof Error ? error46.message : String(error46)}`);
+    const errorMsg = error46 instanceof Error ? error46.message : String(error46);
+    const codePreview = stepDef.code.length > 200 ? `${stepDef.code.substring(0, 200)}...` : stepDef.code;
+    throw new Error(`Failed to compile code for step '${stepDef.id}' in workflow '${workflowId}':
+` + `  Error: ${errorMsg}
+` + `  Code:
+${codePreview.split(`
+`).map((line) => `    ${line}`).join(`
+`)}`);
   }
 }
 async function executeStepWithAgent(stepDef, workflowId, input, state, context, options, runInternal) {
@@ -64278,6 +64309,7 @@ async function executeStepWithAgent(stepDef, workflowId, input, state, context,
     });
   }
   const allowedToolNameSet = new Set(toolsForAgent.map((t) => t.name));
+  context.logger.debug(`[Agent] Available tools for step '${stepDef.id}': ${toolsForAgent.map((t) => t.name).join(", ")}`);
   const systemPrompt = options.stepSystemPrompt?.({ workflowId, step: stepDef, input, state }) ?? [
     `You are an AI assistant executing a workflow step.`,
     "",
@@ -64346,28 +64378,82 @@ async function executeStepWithAgent(stepDef, workflowId, input, state, context,
     if (parsed.success) {
       return parsed.data;
     }
+    if (options.wrapAgentResultInObject) {
+      context.logger.warn(`[Agent] Step '${stepDef.id}' returned plain text instead of JSON. Wrapping in {result: ...}`);
+      return { result: result.message };
+    }
     return result.message;
   }
-  throw new Error(`Agent execution for step '${stepDef.id}' in workflow '${workflowId}' did not exit cleanly.`);
+  if (result.type === "Error") {
+    throw new Error(`Agent step '${stepDef.id}' in workflow '${workflowId}' failed: ${result.error?.message || "Unknown error"}`);
+  }
+  if (result.type === "UsageExceeded") {
+    throw new Error(`Agent step '${stepDef.id}' in workflow '${workflowId}' exceeded usage limits (tokens or rounds)`);
+  }
+  throw new Error(`Agent step '${stepDef.id}' in workflow '${workflowId}' exited unexpectedly with type: ${result.type}`);
+}
+async function executeStepWithTimeout(stepDef, workflowId, input, state, context, options, compiledSteps, runInternal) {
+  const executeStepLogic = async () => {
+    if (stepDef.code && options.allowUnsafeCodeExecution) {
+      context.logger.debug(`[Step] Executing step '${stepDef.id}' with compiled code`);
+      const fn = compileStep(stepDef, workflowId, compiledSteps);
+      const runWorkflow = createRunWorkflowFn({ input, state, context, runInternal });
+      const runtimeCtx = {
+        workflowId,
+        stepId: stepDef.id,
+        input,
+        state,
+        tools: context.tools,
+        logger: context.logger,
+        step: context.step,
+        runWorkflow,
+        toolInfo: options.toolInfo
+      };
+      const result2 = await fn(runtimeCtx);
+      context.logger.debug(`[Step] Compiled code execution completed for step '${stepDef.id}'`);
+      return result2;
+    }
+    context.logger.debug(`[Step] Executing step '${stepDef.id}' with agent`);
+    const result = await executeStepWithAgent(stepDef, workflowId, input, state, context, options, runInternal);
+    context.logger.debug(`[Step] Agent execution completed for step '${stepDef.id}'`);
+    return result;
+  };
+  if (stepDef.timeout && stepDef.timeout > 0) {
+    context.logger.debug(`[Step] Step '${stepDef.id}' has timeout of ${stepDef.timeout}ms`);
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error(`Step '${stepDef.id}' in workflow '${workflowId}' timed out after ${stepDef.timeout}ms`)), stepDef.timeout);
+    });
+    try {
+      return await Promise.race([executeStepLogic(), timeoutPromise]);
+    } finally {
+      if (timeoutId)
+        clearTimeout(timeoutId);
+    }
+  }
+  return await executeStepLogic();
 }
 async function executeStep(stepDef, workflowId, input, state, context, options, compiledSteps, runInternal) {
-  if (stepDef.code && options.allowUnsafeCodeExecution) {
-    const fn = compileStep(stepDef, workflowId, compiledSteps);
-    const runWorkflow = createRunWorkflowFn({ input, state, context, runInternal });
-    const runtimeCtx = {
-      workflowId,
-      stepId: stepDef.id,
-      input,
-      state,
-      tools: context.tools,
-      logger: context.logger,
-      step: context.step,
-      runWorkflow,
-      toolInfo: options.toolInfo
-    };
-    return await fn(runtimeCtx);
+  const result = await executeStepWithTimeout(stepDef, workflowId, input, state, context, options, compiledSteps, runInternal);
+  if (stepDef.outputSchema) {
+    try {
+      const _schema = exports_external.any();
+      if (typeof stepDef.outputSchema === "object") {
+        context.logger.debug(`[Step] Validating output for step '${stepDef.id}' against schema`);
+        if (stepDef.outputSchema.type === "object") {
+          if (typeof result !== "object" || result === null || Array.isArray(result)) {
+            throw new Error(`Expected object output, got ${Array.isArray(result) ? "array" : result === null ? "null" : typeof result}`);
+          }
+        }
+        if (stepDef.outputSchema.type === "array" && !Array.isArray(result)) {
+          throw new Error(`Expected array output, got ${typeof result}`);
+        }
+      }
+    } catch (error46) {
+      throw new Error(`Step '${stepDef.id}' in workflow '${workflowId}' output validation failed: ${error46 instanceof Error ? error46.message : String(error46)}`);
+    }
   }
-  return await executeStepWithAgent(stepDef, workflowId, input, state, context, options, runInternal);
+  return result;
 }
 function createDynamicWorkflow(definition, options = {}) {
   if (typeof definition === "string") {
@@ -64383,19 +64469,35 @@ function createDynamicWorkflow(definition, options = {}) {
     if (!workflow) {
       throw new Error(`Workflow '${workflowId}' not found`);
     }
+    const validatedInput = validateAndApplyDefaults(workflowId, workflow, input);
+    context.logger.info(`[Workflow] Starting workflow '${workflowId}'`);
+    context.logger.debug(`[Workflow] Input: ${JSON.stringify(validatedInput)}`);
+    context.logger.debug(`[Workflow] Inherited state: ${JSON.stringify(inheritedState)}`);
+    context.logger.debug(`[Workflow] Steps: ${workflow.steps.map((s) => s.id).join(", ")}`);
     const state = { ...inheritedState };
     let lastOutput;
-    for (const stepDef of workflow.steps) {
+    for (let i = 0;i < workflow.steps.length; i++) {
+      const stepDef = workflow.steps[i];
       const stepName = `${workflowId}.${stepDef.id}`;
+      context.logger.info(`[Workflow] Step ${i + 1}/${workflow.steps.length}: ${stepDef.id}`);
+      context.logger.debug(`[Workflow] Step task: ${stepDef.task}`);
+      if (stepDef.expected_outcome) {
+        context.logger.debug(`[Workflow] Expected outcome: ${stepDef.expected_outcome}`);
+      }
+      context.logger.debug(`[Workflow] Current state keys: ${Object.keys(state).join(", ")}`);
       lastOutput = await context.step(stepName, async () => {
-        return await executeStep(stepDef, workflowId, input, state, context, options, compiledSteps, runInternal);
+        return await executeStep(stepDef, workflowId, validatedInput, state, context, options, compiledSteps, runInternal);
       });
       const outputKey = stepDef.output ?? stepDef.id;
       state[outputKey] = lastOutput;
+      context.logger.debug(`[Workflow] Step output stored as '${outputKey}': ${typeof lastOutput === "object" ? JSON.stringify(lastOutput).substring(0, 200) : lastOutput}`);
     }
+    context.logger.info(`[Workflow] Completed workflow '${workflowId}'`);
     if (workflow.output) {
+      context.logger.debug(`[Workflow] Returning output field: ${workflow.output}`);
       return state[workflow.output];
     }
+    context.logger.debug(`[Workflow] Returning full state with keys: ${Object.keys(state).join(", ")}`);
     return state;
   };
   return async (workflowId, input, context) => {
@@ -64428,8 +64530,11 @@ The workflow definition must follow this structure:
         {
           "id": "stepId",
           "task": "Description of the step",
-          "tools": ["toolName1", "toolName2"], // Optional list of tools needed
-          "output": "outputVariableName", // Optional
+          "tools": ["toolName1", "toolName2"], // Optional: restrict which tools can be used
+          "output": "outputVariableName", // Optional: defaults to step id
+          "timeout": 30000, // Optional: timeout in milliseconds
+          "expected_outcome": "What this step produces", // Optional: documentation
+          "outputSchema": { "type": "object" } // Optional: validation schema
         }
       ],
       "output": "outputVariableName" // Optional
@@ -64443,6 +64548,15 @@ Constraints:
 - Break down complex tasks into logical steps.
 - Define clear inputs and outputs.
 
+Quality Guidelines:
+- Add "timeout" field (in milliseconds) for steps that might take long (file I/O, API calls, searches)
+- Use "expected_outcome" field to document what each step should produce
+- Use descriptive step IDs (e.g., "validateInput", "fetchUserData", not "step1", "step2")
+- Design steps to be focused - one responsibility per step
+- For steps that process multiple items, consider creating a sub-workflow
+- Add "outputSchema" with type information for validation-critical steps
+- Order steps logically with clear data flow
+
 Example 1:
 User: "Research a topic and summarize it."
 Output:
@@ -64530,70 +64644,407 @@ Your task is to implement the TypeScript code for the steps in the provided work
 You will receive a JSON workflow definition where the "code" field is null.
 You must fill in the "code" field for each step with valid TypeScript code.
 
-The code will be executed in an async function with the following signature:
-async (ctx) => {
-  // Your code here
-}
-
-The \`ctx\` object provides access to:
-- \`ctx.input\`: The workflow inputs.
-- \`ctx.state\`: A shared state object for passing data between steps.
-- \`ctx.tools\`: An object containing available tools.
-- \`ctx.runWorkflow\`: (workflowId: string, input?: any) => Promise<any>. Use this to run other workflows.
-
-Guidelines:
-- Use \`await\` for asynchronous operations.
-- Return the output value of the step.
-- Access inputs via \`ctx.input.inputName\`.
-- Access previous step outputs via \`ctx.state.stepOutputName\`.
-- Use \`ctx.tools.invokeTool({ toolName: 'name', input: { ... } })\` to call tools.
-- Use \`ctx.tools.generateText({ messages: [...] })\` for LLM calls.
-- Use \`ctx.tools.invokeTool({ toolName: 'runAgent', input: { prompt: '...' } })\` for complex sub-tasks that require multiple steps or tools. Prefer this over \`generateText\` for advanced tasks.
-
-Example Code for a step:
-\`\`\`typescript
-const searchResults = await ctx.tools.invokeTool({
-  toolName: 'search',
-  input: { query: ctx.input.topic }
-});
-return searchResults;
-\`\`\`
-
-Example Code for LLM step:
-\`\`\`typescript
-const summary = await ctx.tools.generateText({
-  messages: [
-    { role: 'system', content: 'Summarize the following text.' },
-    { role: 'user', content: ctx.state.searchResults }
-  ]
-});
-return summary;
-\`\`\`
-
-Example Code for runAgent:
-\`\`\`typescript
-const result = await ctx.tools.invokeTool({
-  toolName: 'runAgent',
-  input: {
-    prompt: 'Research the history of the internet and write a summary.',
-    tools: ['search', 'generateText']
-  }
-});
-return result;
-\`\`\`
-
-Example Code for invoking a sub-workflow:
-\`\`\`typescript
-const results = [];
-for (const pr of ctx.state.prs) {
-  const review = await ctx.runWorkflow('reviewPR', { prId: pr.id });
-  results.push(review);
-}
-return results;
-\`\`\`
-
-Return the complete workflow JSON with the "code" fields populated.
-`;
+CRITICAL: Each step "code" field must contain ONLY the function body statements (the code inside the curly braces).
+DO NOT include function declaration, arrow function syntax, async keyword, parameter list, or outer curly braces.
+
+The code will be wrapped automatically in: \`async (ctx) => { YOUR_CODE_HERE }\`
+
+Example of CORRECT code field:
+	\`\`\`ts
+	const result = await ctx.tools.readFile({ path: 'README.md' })
+	if (!result) throw new Error('File not found')
+	return result
+	\`\`\`
+
+Example of INCORRECT code field (DO NOT DO THIS):
+	\`\`\`ts
+	async (ctx) => {
+	  const result = await ctx.tools.readFile({ path: 'README.md' })
+	  return result
+	}
+	\`\`\`
+
+Example of INCORRECT code field (DO NOT DO THIS):
+	\`\`\`ts
+	(ctx) => {
+	  return 'hello'
+	}
+	\`\`\`
+
+	## Runtime context (ctx)
+	\`\`\`ts
+	// Runtime types (for reference)
+	type Logger = {
+	  debug: (...args: any[]) => void
+	  info: (...args: any[]) => void
+	  warn: (...args: any[]) => void
+	  error: (...args: any[]) => void
+	}
+
+	type StepFn = {
+	  <T>(name: string, fn: () => Promise<T>): Promise<T>
+	  <T>(name: string, options: { retry?: number }, fn: () => Promise<T>): Promise<T>
+	}
+
+	type JsonModelMessage = { role: 'system' | 'user' | 'assistant' | 'tool'; content: any }
+	type JsonResponseMessage = { role: 'assistant' | 'tool'; content: any }
+	type ToolSet = Record<string, any>
+
+	type ToolResponseResult =
+	  | { type: 'text'; value: string }
+	  | { type: 'json'; value: any }
+	  | { type: 'error-text'; value: string }
+	  | { type: 'error-json'; value: any }
+	  | { type: 'content'; value: any[] }
+
+	type AgentToolResponse =
+	  | { type: 'Reply'; message: ToolResponseResult }
+	  | { type: 'Exit'; message: string; object?: any }
+	  | { type: 'Error'; message: ToolResponseResult }
+
+	type ExitReason =
+	  | { type: 'UsageExceeded' }
+	  | { type: 'Exit'; message: string; object?: any }
+	  | { type: 'Error'; error: { message: string; stack?: string } }
+
+	type FullAgentToolInfo = { name: string; description: string; parameters: any; handler: any }
+
+	// Tools available on ctx.tools in dynamic steps
+	type DynamicWorkflowTools = {
+	  // LLM + agent helpers
+	  generateText: (input: { messages: JsonModelMessage[]; tools: ToolSet }) => Promise<JsonResponseMessage[]>
+	  runAgent: (input: {
+	    tools: Readonly<FullAgentToolInfo[]>
+	    maxToolRoundTrips?: number
+	    userMessage: readonly JsonModelMessage[]
+	  } & ({ messages: JsonModelMessage[] } | { systemPrompt: string })) => Promise<ExitReason>
+
+	  // Generic bridge to "agent tools" by name
+	  invokeTool: (input: { toolName: string; input: any }) => Promise<AgentToolResponse>
+
+	  // File + command helpers (direct)
+	  readFile: (input: { path: string }) => Promise<string | null>
+	  writeToFile: (input: { path: string; content: string }) => Promise<void>
+	  executeCommand: (input: { command: string; pipe?: boolean } & ({ args: string[]; shell?: false } | { shell: true })) => Promise<{
+	    exitCode: number
+	    stdout: string
+	    stderr: string
+	  }>
+
+	  // CLI UX helpers
+	  confirm: (input: { message: string }) => Promise<boolean>
+	  input: (input: { message: string; default?: string }) => Promise<string>
+	  select: (input: { message: string; choices: { name: string; value: string }[] }) => Promise<string>
+	}
+
+	type DynamicStepRuntimeContext = {
+	  workflowId: string
+	  stepId: string
+	  input: Record<string, any>
+	  state: Record<string, any>
+	  tools: DynamicWorkflowTools
+	  logger: Logger
+	  step: StepFn
+	  runWorkflow: (workflowId: string, input?: Record<string, any>) => Promise<any>
+	  toolInfo?: ReadonlyArray<FullAgentToolInfo>
+	}
+	\`\`\`
+
+- \`ctx.input\`: workflow inputs (read-only).
+- \`ctx.state\`: shared state between steps (previous step outputs are stored here).
+- \`ctx.tools\`: async tool functions. Call tools as \`await ctx.tools.someTool({ ... })\`.
+- \`ctx.runWorkflow\`: run a sub-workflow by id.
+
+	## Guidelines
+	- Use \`await\` for all async operations.
+	- Return the output value for the step (this becomes the step output).
+	- Access inputs via \`ctx.input.<inputId>\`.
+	- Access previous step outputs via \`ctx.state.<stepOutputKey>\` (defaults to the step \`output\` or \`id\`).
+
+	## Quality Guidelines for Code Implementation
+
+	### Error Handling
+	- ALWAYS validate inputs at the start of steps
+	- Use try-catch for operations that might fail (file I/O, parsing, API calls)
+	- Preserve stack traces: re-throw original errors rather than creating new ones
+	- Use error type guards: \`const err = error instanceof Error ? error : new Error(String(error))\`
+	- Check for null/undefined before using values
+	- Handle edge cases (empty arrays, missing files, invalid data)
+
+	### Logging
+	- Use \`ctx.logger.info()\` for important progress updates
+	- Use \`ctx.logger.debug()\` for detailed information
+	- Use \`ctx.logger.warn()\` for recoverable issues
+	- Use \`ctx.logger.error()\` before throwing errors
+	- Log when starting and completing significant operations
+	- Use template literals for readability: \`ctx.logger.info(\\\`Processing \${items.length} items...\\\`)\`
+
+	### User Experience
+	- Provide progress feedback for long operations
+	- Return structured data (objects/arrays), not strings when possible
+	- Include helpful metadata in results (counts, timestamps, status)
+	- For batch operations, report progress: \`Processed 5/10 items\`
+
+	### Data Validation
+	- Validate required fields exist before accessing
+	- Check data types match expectations
+	- Validate array lengths before iteration
+	- Example: \`if (!data?.users || !Array.isArray(data.users)) throw new Error('Invalid data format')\`
+
+	### Best Practices
+	- Use meaningful variable names
+	- Avoid nested callbacks - use async/await
+	- Clean up resources (close files, clear timeouts)
+	- Return consistent data structures across similar steps
+	- For iteration, consider batching or rate limiting
+
+	### When to Simplify
+	- Simple transformation steps (e.g., formatting strings) need only basic error handling
+	- Internal sub-workflow steps with validated inputs from parent can skip redundant validation
+	- Minimal logging is fine for fast steps (<100ms) that don't perform I/O or external calls
+	- Use judgment: match error handling complexity to the step's failure risk and impact
+
+	## Tool calling examples (every tool)
+
+	### Direct ctx.tools methods
+	\`\`\`ts
+	// readFile
+	const readme = await ctx.tools.readFile({ path: 'README.md' })
+	if (readme == null) throw new Error('README.md not found')
+
+	// writeToFile
+	await ctx.tools.writeToFile({ path: 'notes.txt', content: 'hello\\n' })
+
+	// executeCommand (args form)
+	const rg = await ctx.tools.executeCommand({ command: 'rg', args: ['-n', 'TODO', '.'] })
+	if (rg.exitCode !== 0) throw new Error(rg.stderr)
+
+	// executeCommand (shell form)
+	await ctx.tools.executeCommand({ command: 'ls -la', shell: true, pipe: true })
+
+	// generateText (LLM call; pass tools: {})
+	const msgs = await ctx.tools.generateText({
+	  messages: [
+	    { role: 'system', content: 'Summarize the following text.' },
+	    { role: 'user', content: readme },
+	  ],
+	  tools: {},
+	})
+	const last = msgs[msgs.length - 1]
+	const lastText = typeof last?.content === 'string' ? last.content : JSON.stringify(last?.content)
+
+	// runAgent (nested agent; use ctx.toolInfo as the tool list)
+	const agentRes = await ctx.tools.runAgent({
+	  systemPrompt: 'You are a helpful assistant.',
+	  userMessage: [{ role: 'user', content: 'Summarize README.md in 3 bullets.' }],
+	  tools: (ctx.toolInfo ?? []) as any,
+	})
+	if (agentRes.type !== 'Exit') throw new Error('runAgent failed')
+
+	// confirm / input / select (interactive)
+	const ok = await ctx.tools.confirm({ message: 'Proceed?' })
+	const name = await ctx.tools.input({ message: 'Name?', default: 'main' })
+	const flavor = await ctx.tools.select({
+	  message: 'Pick one',
+	  choices: [
+	    { name: 'A', value: 'a' },
+	    { name: 'B', value: 'b' },
+	  ],
+	})
+
+	\`\`\`
+
+	### Agent tools via ctx.tools.invokeTool (toolName examples)
+	\`\`\`ts
+	// Helper to unwrap a successful tool reply
+	function unwrapToolValue(resp: any) {
+	  if (!resp || resp.type !== 'Reply') {
+	    const msg = resp?.message?.value
+	    throw new Error(typeof msg === 'string' ? msg : JSON.stringify(resp))
+	  }
+	  return resp.message.value
+	}
+
+	// askFollowupQuestion
+	const answersText = unwrapToolValue(
+	  await ctx.tools.invokeTool({
+	    toolName: 'askFollowupQuestion',
+	    input: { questions: [{ prompt: 'Which directory?', options: ['src', 'packages'] }] },
+	  }),
+	)
+
+	// listFiles
+	const filesText = unwrapToolValue(
+	  await ctx.tools.invokeTool({
+	    toolName: 'listFiles',
+	    input: { path: 'src', recursive: true, maxCount: 2000, includeIgnored: false },
+	  }),
+	)
+
+	// searchFiles
+	const hitsText = unwrapToolValue(
+	  await ctx.tools.invokeTool({
+	    toolName: 'searchFiles',
+	    input: { path: '.', regex: 'generateWorkflowCodeWorkflow', filePattern: '*.ts' },
+	  }),
+	)
+
+	// fetchUrl
+	const pageText = unwrapToolValue(await ctx.tools.invokeTool({ toolName: 'fetchUrl', input: { url: 'https://example.com' } }))
+
+	// search (web search)
+	const webResults = unwrapToolValue(
+	  await ctx.tools.invokeTool({ toolName: 'search', input: { query: 'TypeScript zod schema examples' } }),
+	)
+
+	// executeCommand (provider-backed; may require approval in some environments)
+	const cmdText = unwrapToolValue(
+	  await ctx.tools.invokeTool({ toolName: 'executeCommand', input: { command: 'bun test', requiresApproval: false } }),
+	)
+
+	// readFile / writeToFile (provider-backed)
+	const fileText = unwrapToolValue(
+	  await ctx.tools.invokeTool({ toolName: 'readFile', input: { path: 'README.md', includeIgnored: false } }),
+	)
+	const writeText = unwrapToolValue(await ctx.tools.invokeTool({ toolName: 'writeToFile', input: { path: 'out.txt', content: 'hi' } }))
+
+	// replaceInFile
+	const diff = ['<<<<<<< SEARCH', 'old', '=======', 'new', '>>>>>>> REPLACE'].join('\\n')
+	const replaceText = unwrapToolValue(await ctx.tools.invokeTool({ toolName: 'replaceInFile', input: { path: 'out.txt', diff } }))
+
+	// removeFile / renameFile
+	const rmText = unwrapToolValue(await ctx.tools.invokeTool({ toolName: 'removeFile', input: { path: 'out.txt' } }))
+	const mvText = unwrapToolValue(
+	  await ctx.tools.invokeTool({ toolName: 'renameFile', input: { source_path: 'a.txt', target_path: 'b.txt' } }),
+	)
+
+	// readBinaryFile (returns { type: 'content', value: [...] } in resp.message)
+	const binResp = await ctx.tools.invokeTool({ toolName: 'readBinaryFile', input: { url: 'file://path/to/image.png' } })
+	\`\`\`
+
+	### Sub-workflow example (ctx.runWorkflow)
+	\`\`\`ts
+	const results: any[] = []
+	for (const pr of ctx.state.prs ?? []) {
+	  results.push(await ctx.runWorkflow('reviewPR', { prId: pr.id }))
+	}
+	return results
+	\`\`\`
+
+	## Complete Example: High-Quality Step Implementation
+
+	This example demonstrates all quality guidelines in a single step:
+
+	\`\`\`ts
+	// Step: processUserData
+	// Task: Read, validate, and process user data from a file
+
+	// Input validation
+	if (!ctx.input.dataFile) {
+	  throw new Error('Missing required input: dataFile')
+	}
+
+	ctx.logger.info(\`Starting user data processing for: \${ctx.input.dataFile}\`)
+
+	// Read file with error handling
+	let rawData
+	try {
+	  ctx.logger.debug(\`Reading file: \${ctx.input.dataFile}\`)
+	  rawData = await ctx.tools.readFile({ path: ctx.input.dataFile })
+
+	  if (!rawData) {
+	    throw new Error(\`File not found or empty: \${ctx.input.dataFile}\`)
+	  }
+	} catch (error) {
+	  const err = error instanceof Error ? error : new Error(String(error))
+	  ctx.logger.error(\`Failed to read file: \${err.message}\`)
+	  throw err  // Preserve original stack trace
+	}
+
+	// Parse and validate data
+	let users
+	try {
+	  ctx.logger.debug('Parsing JSON data')
+	  const parsed = JSON.parse(rawData)
+
+	  if (!parsed?.users || !Array.isArray(parsed.users)) {
+	    throw new Error('Invalid data format: expected {users: [...]}')
+	  }
+
+	  users = parsed.users
+	  ctx.logger.info(\`Found \${users.length} users to process\`)
+	} catch (error) {
+	  const err = error instanceof Error ? error : new Error(String(error))
+	  ctx.logger.error(\`Data parsing failed: \${err.message}\`)
+	  throw err  // Preserve original stack trace
+	}
+
+	// Process each user with progress reporting
+	const results = []
+	for (let i = 0; i < users.length; i++) {
+	  const user = users[i]
+
+	  // Validate each user object
+	  if (!user?.id || !user?.email) {
+	    ctx.logger.warn(\`Skipping invalid user at index \${i}: missing id or email\`)
+	    continue
+	  }
+
+	  // Process user
+	  const processed = {
+	    id: user.id,
+	    email: user.email.toLowerCase().trim(),
+	    name: user.name?.trim() || 'Unknown',
+	    processedAt: new Date().toISOString(),
+	    status: 'active'
+	  }
+
+	  results.push(processed)
+
+	  // Progress feedback every 10 items
+	  if ((i + 1) % 10 === 0) {
+	    ctx.logger.info(\`Processed \${i + 1}/\${users.length} users\`)
+	  }
+	}
+
+	ctx.logger.info(\`Successfully processed \${results.length}/\${users.length} users\`)
+
+	// Return structured result with metadata
+	return {
+	  users: results,
+	  metadata: {
+	    totalInput: users.length,
+	    totalProcessed: results.length,
+	    skipped: users.length - results.length,
+	    processedAt: new Date().toISOString()
+	  }
+	}
+	\`\`\`
+
+	Key features demonstrated:
+	- Input validation at start
+	- Comprehensive error handling with try-catch that preserves stack traces
+	- Logging at info, debug, warn, and error levels
+	- Progress reporting for long operations (every 10 items)
+	- Data validation throughout (null checks, type checks, array validation)
+	- Structured return value with metadata for observability
+	- Descriptive error messages with context
+	- Meaningful variable names (rawData, users, processed)
+	- Clean async/await usage
+	- Template literals for readable string interpolation
+	- Proper error type guards (error instanceof Error)
+
+	## Final Instructions
+
+	REMEMBER: The "code" field must be ONLY the function body statements.
+	- DO NOT wrap code in arrow functions: \`(ctx) => { ... }\`
+	- DO NOT wrap code in async functions: \`async (ctx) => { ... }\`
+	- DO NOT include outer curly braces
+	- DO include a return statement if the step should produce output
+	- Each "code" field should be a string containing multiple statements separated by newlines
+
+	Return the complete workflow JSON with the "code" fields populated.
+	`;
 var generateWorkflowDefinitionWorkflow = async (input, ctx) => {
   let systemPrompt = WORKFLOW_DEFINITION_SYSTEM_PROMPT;
   if (input.availableTools && input.availableTools.length > 0) {
@@ -84584,7 +85035,7 @@ function getProviderOptions(options) {
 
 // src/tool-implementations.ts
 import { spawn as spawn3, spawnSync as spawnSync2 } from "node:child_process";
-import fs3, { mkdir as mkdir2 } from "node:fs/promises";
+import fs4, { mkdir as mkdir2 } from "node:fs/promises";
 import { dirname as dirname2 } from "node:path";
 
 // src/tools/utils/diffLineNumbers.ts
@@ -84817,12 +85268,14 @@ async function getUserInput(message, options = {}) {
 
 // src/workflows/workflow.utils.ts
 import { execSync } from "node:child_process";
+import { promises as fs3 } from "node:fs";
+import path from "node:path";
 function parseGitDiffNameStatus(diffOutput) {
   const lines = diffOutput.split(`
 `).filter((line) => line.trim());
   return lines.map((line) => {
     const [status, ...pathParts] = line.split("\t");
-    const path = pathParts.join("\t");
+    const path2 = pathParts.join("\t");
     let statusDescription;
     switch (status[0]) {
       case "A":
@@ -84846,7 +85299,7 @@ function parseGitDiffNameStatus(diffOutput) {
       default:
         statusDescription = "Unknown";
     }
-    return { path, status: statusDescription };
+    return { path: path2, status: statusDescription };
   });
 }
 function printChangedFiles(logger, changedFiles) {
@@ -84873,21 +85326,21 @@ function parseGitDiffNumStat(output) {
     if (parts.length >= 3) {
       const insertions = parts[0] === "-" ? 0 : Number.parseInt(parts[0], 10);
       const deletions = parts[1] === "-" ? 0 : Number.parseInt(parts[1], 10);
-      const path = unquotePath(parts.slice(2).join("\t"));
-      stats[path] = { insertions, deletions };
+      const path2 = unquotePath(parts.slice(2).join("\t"));
+      stats[path2] = { insertions, deletions };
     }
   }
   return stats;
 }
-var unquotePath = (path) => {
-  if (path.startsWith('"') && path.endsWith('"')) {
+var unquotePath = (path2) => {
+  if (path2.startsWith('"') && path2.endsWith('"')) {
     try {
-      return JSON.parse(path);
+      return JSON.parse(path2);
     } catch {
-      return path;
+      return path2;
     }
   }
-  return path;
+  return path2;
 };
 function parseGitStatus(statusOutput) {
   const statusLines = statusOutput.split(`
@@ -84896,7 +85349,7 @@ function parseGitStatus(statusOutput) {
   for (const line of statusLines) {
     const indexStatus = line[0];
     const workingTreeStatus = line[1];
-    const path = line.length > 3 ? unquotePath(line.slice(3)) : line;
+    const path2 = line.length > 3 ? unquotePath(line.slice(3)) : line;
     const statuses = [];
     if (indexStatus !== " " && indexStatus !== "?") {
       switch (indexStatus) {
@@ -84935,7 +85388,7 @@ function parseGitStatus(statusOutput) {
       }
     }
     if (statuses.length > 0) {
-      files.push({ path, status: statuses.join(", ") });
+      files.push({ path: path2, status: statuses.join(", ") });
     }
   }
   return files;
@@ -85081,6 +85534,12 @@ ${fileList}
 </file_list>`,
     `<now_date>${new Date().toISOString()}</now_date>`
   ];
+  try {
+    const agentsMdContent = await fs3.readFile(path.join(cwd, "AGENTS.md"), "utf-8");
+    contextParts.push(`<agents_instructions>
+${agentsMdContent}
+</agents_instructions>`);
+  } catch {}
   if (config4?.rules) {
     contextParts.push(`<rules>
 ${config4.rules}
@@ -85205,12 +85664,12 @@ async function select(input2, context) {
 }
 async function writeToFile(input2) {
   await mkdir2(dirname2(input2.path), { recursive: true });
-  await fs3.writeFile(input2.path, input2.content);
+  await fs4.writeFile(input2.path, input2.content);
   return {};
 }
 async function readFile3(input2) {
   try {
-    const content = await fs3.readFile(input2.path, "utf8");
+    const content = await fs4.readFile(input2.path, "utf8");
     return content;
   } catch {}
   return null;
@@ -85620,6 +86079,9 @@ Memory is organized using topics, which are like named containers for different
 - Use the default topic for simple, single-context scenarios
 - Memory persists across all tool calls within the current workflow
 `;
+var AGENTS_INSTRUCTION = `## AGENTS.md Instructions
+
+If you are working in a subdirectory, check if there is an AGENTS.md file in that directory or parent directories for specific instructions. These files contain project-specific guidelines and conventions that you must follow.`;
 
 // src/workflows/prompts/coder.ts
 var CODER_SYSTEM_PROMPT = `Role: AI developer.
@@ -85631,6 +86093,8 @@ ${MEMORY_USAGE_SECTION}
 
 ${TOOL_USAGE_INSTRUCTION}
 
+${AGENTS_INSTRUCTION}
+
 ## Implementation Guidelines
 
 ### 1. Plan Analysis
@@ -86187,6 +86651,8 @@ ${MEMORY_USAGE_SECTION}
 
 ${TOOL_USAGE_INSTRUCTION}
 
+${AGENTS_INSTRUCTION}
+
 ## Your Role
 
 As a planner, your expertise lies in:
@@ -86709,10 +87175,10 @@ ${defaultContext}`;
     }
     const outputFiles = [];
     if (filePaths) {
-      for (const path of filePaths) {
-        const content = await tools2.readFile({ path });
+      for (const path2 of filePaths) {
+        const content = await tools2.readFile({ path: path2 });
         if (content) {
-          outputFiles.push({ path, content });
+          outputFiles.push({ path: path2, content });
         }
       }
     }
@@ -87473,7 +87939,7 @@ async function performReviewAndFixCycle(iterationCount, taskItem, highLevelPlan,
   const commitMessages = [];
   for (let i2 = 0;i2 < MAX_REVIEW_RETRIES; i2++) {
     const diffResult = await tools2.executeCommand({ command: "git", args: ["diff", "--name-status", "HEAD~1", "HEAD"] });
-    const changedFiles = parseGitDiffNameStatus(diffResult.stdout).filter(({ path }) => path !== ".epic.yml");
+    const changedFiles = parseGitDiffNameStatus(diffResult.stdout).filter(({ path: path2 }) => path2 !== ".epic.yml");
     if (changedFiles.length === 0) {
       logger.info(`No files were changed. Skipping review.
 `);
@@ -87682,7 +88148,7 @@ Phase 6: Final Review and Fixup...
   const commitRange = `${baseBranch}...${currentBranch}`;
   for (let i2 = 0;i2 < MAX_REVIEW_RETRIES; i2++) {
     const diffResult = await tools2.executeCommand({ command: "git", args: ["diff", "--name-status", commitRange] });
-    const changedFiles = parseGitDiffNameStatus(diffResult.stdout).filter(({ path }) => path !== ".epic.yml");
+    const changedFiles = parseGitDiffNameStatus(diffResult.stdout).filter(({ path: path2 }) => path2 !== ".epic.yml");
     if (changedFiles.length === 0) {
       logger.info(`No files have been changed in this branch. Skipping final review.
 `);
@@ -88228,7 +88694,7 @@ var commitCommand = new Command("commit").description("Create a commit with AI-g
 });
 
 // src/workflows/epic-context.ts
-import { promises as fs4 } from "node:fs";
+import { promises as fs5 } from "node:fs";
 var EPIC_CONTEXT_FILE = ".epic.yml";
 var EpicUsageSchema = exports_external.object({
   timestamp: exports_external.number(),
@@ -88257,12 +88723,12 @@ var saveEpicContext = async (context) => {
     memory: context.memory,
     usages: context.usages
   });
-  await fs4.writeFile(EPIC_CONTEXT_FILE, yamlString, "utf-8");
+  await fs5.writeFile(EPIC_CONTEXT_FILE, yamlString, "utf-8");
 };
 var loadEpicContext = async () => {
   let fileContent;
   try {
-    fileContent = await fs4.readFile(EPIC_CONTEXT_FILE, "utf-8");
+    fileContent = await fs5.readFile(EPIC_CONTEXT_FILE, "utf-8");
   } catch {
     return {};
   }
@@ -88792,9 +89258,9 @@ ${formattedReview}`;
 // src/commands/workflow.ts
 import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname3 } from "node:path";
-async function saveWorkflowFile(path, workflow3) {
-  await mkdir3(dirname3(path), { recursive: true });
-  await writeFile2(path, $stringify(workflow3));
+async function saveWorkflowFile(path2, workflow3) {
+  await mkdir3(dirname3(path2), { recursive: true });
+  await writeFile2(path2, $stringify(workflow3));
 }
 function clearWorkflowCode(workflowDef) {
   for (const wf of Object.values(workflowDef.workflows)) {
@@ -88906,12 +89372,15 @@ Return the updated workflow definition.`;
   }
   const workflowDef = parsedResult.definition;
   const workflowNames = Object.keys(workflowDef.workflows);
+  logger.info(`Available workflows: ${workflowNames.join(", ")}`);
   let workflowId = workflowName;
   if (!workflowId) {
     if (workflowNames.includes("main")) {
       workflowId = "main";
+      logger.info(`Using 'main' workflow`);
     } else if (workflowNames.length === 1) {
       workflowId = workflowNames[0];
+      logger.info(`Using workflow '${workflowId}'`);
     } else if (workflowNames.length > 1) {
       logger.error(`Multiple workflows found in file and no 'main' workflow. Please specify one using --workflow <name>. Available workflows: ${workflowNames.join(", ")}`);
       return;
@@ -88924,6 +89393,7 @@ Return the updated workflow definition.`;
       logger.error(`Workflow '${workflowId}' not found in file. Available workflows: ${workflowNames.join(", ")}`);
       return;
     }
+    logger.info(`Using workflow '${workflowId}'`);
   }
   let dynamicRunner;
   try {
@@ -88943,7 +89413,14 @@ Return the updated workflow definition.`;
   if (selectedWorkflow.inputs && selectedWorkflow.inputs.length > 0 && task2) {
     const firstInput = selectedWorkflow.inputs[0];
     workflowInput[firstInput.id] = task2;
+    logger.info(`Workflow input '${firstInput.id}': ${task2}`);
+  } else if (selectedWorkflow.inputs && selectedWorkflow.inputs.length > 0) {
+    logger.info(`Workflow expects inputs: ${selectedWorkflow.inputs.map((i2) => i2.id).join(", ")}`);
+  } else {
+    logger.info("Workflow has no inputs");
   }
+  logger.info(`Workflow has ${selectedWorkflow.steps.length} step(s)`);
+  logger.debug(`Steps: ${selectedWorkflow.steps.map((s2) => `${s2.id} (${s2.task})`).join(", ")}`);
   await runWorkflow(workflowFn, workflowInput, { commandName: "workflow", command, logger, yes });
 }
 var workflowCommand = new Command("workflow").description("Generate, manage, and run custom workflows.").argument("[task]", "The task description for generating the workflow.").option("-f, --file <path>", "Path to the workflow file").option("-w, --workflow <name>", "The name of the workflow to run").option("--create", "Create a new workflow").option("--regenerate", "Regenerate the code for the workflow").action(runWorkflowCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polka-codes/cli",
-  "version": "0.9.79",
+  "version": "0.9.80",
   "license": "AGPL-3.0",
   "author": "github@polka.codes",
   "type": "module",