@polka-codes/core 0.9.78 → 0.9.80

package/dist/index.js

@@ -1904,6 +1904,935 @@ var agentWorkflow = async (input, { step, tools, logger }) => {
   throw new Error("Maximum number of tool round trips reached.");
 };
 
+// src/workflow/dynamic.ts
+import { parse } from "yaml";
+import { z as z22 } from "zod";
+
+// src/workflow/dynamic-types.ts
+import { z as z21 } from "zod";
+var WorkflowInputDefinitionSchema = z21.object({
+  id: z21.string(),
+  description: z21.string().nullish(),
+  default: z21.any().nullish()
+});
+var WorkflowStepDefinitionSchema = z21.object({
+  id: z21.string(),
+  tools: z21.array(z21.string()).nullish(),
+  task: z21.string(),
+  output: z21.string().nullish(),
+  expected_outcome: z21.string().nullish(),
+  /**
+   * Persisted JavaScript/TypeScript (JS-compatible) async function body.
+   * The code is wrapped as: `async (ctx) => { <code> }`.
+   */
+  code: z21.string().nullish(),
+  /**
+   * Optional JSON schema or other metadata for future structured outputs.
+   * Not interpreted by core today.
+   */
+  outputSchema: z21.any().nullish(),
+  /**
+   * Optional timeout in milliseconds. Step execution will be aborted if it exceeds this duration.
+   */
+  timeout: z21.number().positive().nullish()
+});
+var WorkflowDefinitionSchema = z21.object({
+  task: z21.string(),
+  inputs: z21.array(WorkflowInputDefinitionSchema).nullish(),
+  steps: z21.array(WorkflowStepDefinitionSchema),
+  output: z21.string().nullish()
+});
+var WorkflowFileSchema = z21.object({
+  workflows: z21.record(z21.string(), WorkflowDefinitionSchema)
+});
+
+// src/workflow/dynamic.ts
+function parseDynamicWorkflowDefinition(source) {
+  try {
+    const raw = parse(source);
+    const validated = WorkflowFileSchema.safeParse(raw);
+    if (!validated.success) {
+      return { success: false, error: z22.prettifyError(validated.error) };
+    }
+    return { success: true, definition: validated.data };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+var AsyncFunction = Object.getPrototypeOf(async () => {
+}).constructor;
+function validateAndApplyDefaults(workflowId, workflow, input) {
+  if (!workflow.inputs || workflow.inputs.length === 0) {
+    return input;
+  }
+  const validatedInput = {};
+  const errors = [];
+  for (const inputDef of workflow.inputs) {
+    const providedValue = input[inputDef.id];
+    if (providedValue !== void 0 && providedValue !== null) {
+      validatedInput[inputDef.id] = providedValue;
+    } else if (inputDef.default !== void 0 && inputDef.default !== null) {
+      validatedInput[inputDef.id] = inputDef.default;
+    } else {
+      errors.push(`Missing required input '${inputDef.id}'${inputDef.description ? `: ${inputDef.description}` : ""}`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(`Workflow '${workflowId}' input validation failed:
+${errors.map((e) => `  - ${e}`).join("\n")}`);
+  }
+  return validatedInput;
+}
+function createRunWorkflowFn(args) {
+  return async (subWorkflowId, subInput) => {
+    const mergedInput = { ...args.input, ...args.state, ...subInput ?? {} };
+    return await args.runInternal(subWorkflowId, mergedInput, args.context, args.state);
+  };
+}
+function compileStep(stepDef, workflowId, compiledSteps) {
+  const key = `${workflowId}.${stepDef.id}`;
+  const existing = compiledSteps.get(key);
+  if (existing) {
+    return existing;
+  }
+  if (!stepDef.code) {
+    throw new Error(`Step '${stepDef.id}' in workflow '${workflowId}' has no code`);
+  }
+  try {
+    const fn = new AsyncFunction("ctx", stepDef.code);
+    compiledSteps.set(key, fn);
+    return fn;
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    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("\n").map((line) => `    ${line}`).join("\n")}`
+    );
+  }
+}
+async function executeStepWithAgent(stepDef, workflowId, input, state, context, options, runInternal) {
+  const tools = context.tools;
+  if (typeof tools.generateText !== "function" || typeof tools.invokeTool !== "function" || typeof tools.taskEvent !== "function") {
+    throw new Error(
+      `Step '${stepDef.id}' in workflow '${workflowId}' requires agent execution, but AgentToolRegistry tools are not available.`
+    );
+  }
+  if (!options.toolInfo) {
+    throw new Error(
+      `Step '${stepDef.id}' in workflow '${workflowId}' requires agent execution, but no toolInfo was provided to DynamicWorkflowRunner.`
+    );
+  }
+  const allowedToolNames = stepDef.tools;
+  const toolsForAgent = allowedToolNames ? options.toolInfo.filter((t) => allowedToolNames.includes(t.name)) : [...options.toolInfo];
+  if (!allowedToolNames || allowedToolNames.includes("runWorkflow")) {
+    toolsForAgent.push({
+      name: "runWorkflow",
+      description: "Run a named sub-workflow defined in the current workflow file.",
+      parameters: z22.object({
+        workflowId: z22.string().describe("Sub-workflow id to run"),
+        input: z22.any().nullish().describe("Optional input object for the sub-workflow")
+      }),
+      handler: async () => {
+        return { type: "Error" /* Error */, message: { type: "error-text", value: "runWorkflow is virtual." } };
+      }
+    });
+  }
+  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.`,
+    "",
+    "# Instructions",
+    "- Execute the task defined in the user message.",
+    "- Use the provided tools to accomplish the task.",
+    "- Return the step output as valid JSON in markdown.",
+    "- Do not ask for user input. If information is missing, make a reasonable assumption or fail."
+  ].filter(Boolean).join("\n");
+  const userContent = [
+    `Workflow: ${workflowId}`,
+    `Step: ${stepDef.id}`,
+    `Task: ${stepDef.task}`,
+    stepDef.expected_outcome ? `Expected outcome: ${stepDef.expected_outcome}` : "",
+    `Workflow Input: ${JSON.stringify(input)}`,
+    `Current State: ${JSON.stringify(state)}`
+  ].filter(Boolean).join("\n");
+  const runWorkflow = createRunWorkflowFn({ input, state, context, runInternal });
+  const agentTools = {
+    generateText: tools.generateText.bind(tools),
+    taskEvent: tools.taskEvent.bind(tools),
+    invokeTool: async ({ toolName, input: toolInput }) => {
+      if (!allowedToolNameSet.has(toolName)) {
+        return {
+          type: "Error" /* Error */,
+          message: { type: "error-text", value: `Tool '${toolName}' is not allowed in this step.` }
+        };
+      }
+      if (toolName === "runWorkflow") {
+        const subWorkflowId = toolInput?.workflowId;
+        const subInput = toolInput?.input;
+        if (typeof subWorkflowId !== "string") {
+          return {
+            type: "Error" /* Error */,
+            message: { type: "error-text", value: "runWorkflow.workflowId must be a string." }
+          };
+        }
+        try {
+          const output = await runWorkflow(subWorkflowId, subInput);
+          const jsonResult = { type: "json", value: output };
+          return { type: "Reply" /* Reply */, message: jsonResult };
+        } catch (error) {
+          return {
+            type: "Error" /* Error */,
+            message: { type: "error-text", value: error instanceof Error ? error.message : String(error) }
+          };
+        }
+      }
+      return await tools.invokeTool({ toolName, input: toolInput });
+    }
+  };
+  const result = await agentWorkflow(
+    {
+      tools: toolsForAgent,
+      systemPrompt,
+      userMessage: [{ role: "user", content: userContent }],
+      maxToolRoundTrips: options.maxToolRoundTrips,
+      model: options.model
+    },
+    { ...context, tools: agentTools }
+  );
+  if (result.type === "Exit") {
+    if (result.object !== void 0) {
+      return result.object;
+    }
+    const parsed = parseJsonFromMarkdown(result.message);
+    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;
+  }
+  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) {
+  const result = await executeStepWithTimeout(stepDef, workflowId, input, state, context, options, compiledSteps, runInternal);
+  if (stepDef.outputSchema) {
+    try {
+      const _schema = z22.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 (error) {
+      throw new Error(
+        `Step '${stepDef.id}' in workflow '${workflowId}' output validation failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return result;
+}
+function createDynamicWorkflow(definition, options = {}) {
+  if (typeof definition === "string") {
+    const res = parseDynamicWorkflowDefinition(definition);
+    if (!res.success) {
+      throw new Error(res.error);
+    }
+    definition = res.definition;
+  }
+  const compiledSteps = /* @__PURE__ */ new Map();
+  const runInternal = async (workflowId, input, context, inheritedState) => {
+    const workflow = definition.workflows[workflowId];
+    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 (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, 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) => {
+    return await runInternal(workflowId, input, context, {});
+  };
+}
+
+// src/workflow/dynamic-generator.workflow.ts
+import { z as z23 } from "zod";
+var GenerateWorkflowDefinitionInputSchema = z23.object({
+  prompt: z23.string(),
+  availableTools: z23.array(
+    z23.object({
+      name: z23.string(),
+      description: z23.string()
+    })
+  ).optional()
+});
+var GenerateWorkflowCodeInputSchema = z23.object({
+  workflow: WorkflowFileSchema
+});
+var WORKFLOW_DEFINITION_SYSTEM_PROMPT = `You are an expert workflow architect.
+Your task is to create a JSON workflow definition based on the user's request.
+
+The workflow definition must follow this structure:
+{
+  "workflows": {
+    "workflowName": {
+      "task": "Description of the workflow",
+      "inputs": [
+        { "id": "inputName", "description": "Description", "default": "optionalDefault" }
+      ],
+      "steps": [
+        {
+          "id": "stepId",
+          "task": "Description of the step",
+          "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
+    }
+  }
+}
+
+Constraints:
+- You MUST always include a workflow named 'main'. This is the entry point.
+- The 'main' workflow input must be either empty (no input) or a single string input.
+- 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:
+\`\`\`json
+{
+  "workflows": {
+    "main": {
+      "task": "Research a topic and provide a summary",
+      "inputs": [
+        { "id": "topic", "description": "The topic to research" }
+      ],
+      "steps": [
+        {
+          "id": "search",
+          "task": "Search for information about the topic",
+          "tools": ["search"],
+          "output": "searchResults"
+        },
+        {
+          "id": "summarize",
+          "task": "Summarize the search results",
+          "tools": ["generateText"],
+          "output": "summary"
+        }
+      ],
+      "output": "summary"
+    }
+  }
+}
+\`\`\`
+
+Example 2:
+User: "Review urgent PRs. For each PR, run the review workflow."
+Output:
+\`\`\`json
+{
+  "workflows": {
+    "main": {
+      "task": "Fetch urgent PRs and review them",
+      "inputs": [],
+      "steps": [
+        {
+          "id": "fetchPRs",
+          "task": "Fetch list of urgent PRs",
+          "tools": ["github_list_prs"],
+          "output": "prs"
+        },
+        {
+          "id": "reviewEachPR",
+          "task": "Run review workflow for each PR",
+          "tools": [],
+          "output": "reviews"
+        }
+      ],
+      "output": "reviews"
+    },
+    "reviewPR": {
+      "task": "Review a single PR",
+      "inputs": [
+        { "id": "prId", "description": "ID of the PR to review" }
+      ],
+      "steps": [
+        {
+          "id": "getDiff",
+          "task": "Get PR diff",
+          "tools": ["github_get_diff"],
+          "output": "diff"
+        },
+        {
+          "id": "analyze",
+          "task": "Analyze the diff",
+          "tools": ["generateText"],
+          "output": "analysis"
+        }
+      ],
+      "output": "analysis"
+    }
+  }
+}
+\`\`\`
+`;
+var WORKFLOW_CODE_SYSTEM_PROMPT = `You are an expert TypeScript developer.
+Your task is to implement the TypeScript code for the steps in the provided workflow definition.
+
+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.
+
+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) {
+    const toolsList = input.availableTools.map((t) => `- ${t.name}: ${t.description}`).join("\n");
+    systemPrompt += `
+
+Available Tools:
+${toolsList}
+
+Use these tools when appropriate.`;
+  }
+  const result = await ctx.step("generate-workflow-definition", async () => {
+    return agentWorkflow(
+      {
+        systemPrompt,
+        userMessage: [{ role: "user", content: input.prompt }],
+        tools: [],
+        outputSchema: WorkflowFileSchema
+      },
+      ctx
+    );
+  });
+  if (result.type === "Exit" && result.object) {
+    return result.object;
+  }
+  throw new Error("Failed to generate workflow definition");
+};
+var generateWorkflowCodeWorkflow = async (input, ctx) => {
+  const result = await ctx.step("generate-workflow-code", async () => {
+    return agentWorkflow(
+      {
+        systemPrompt: WORKFLOW_CODE_SYSTEM_PROMPT,
+        userMessage: [{ role: "user", content: JSON.stringify(input.workflow, null, 2) }],
+        tools: [],
+        outputSchema: WorkflowFileSchema
+      },
+      ctx
+    );
+  });
+  if (result.type === "Exit" && result.object) {
+    return result.object;
+  }
+  throw new Error("Failed to generate workflow code");
+};
+
 // src/workflow/json-ai-types.ts
 var toJsonDataContent = (data) => {
   if (data instanceof URL) {
@@ -2102,6 +3031,8 @@ var makeStepFn = () => {
   };
 };
 export {
+  GenerateWorkflowCodeInputSchema,
+  GenerateWorkflowDefinitionInputSchema,
   MockProvider,
   TaskEventKind,
   TodoItemSchema,
@@ -2110,19 +3041,27 @@ export {
   UpdateTodoItemInputSchema,
   UpdateTodoItemOutputSchema,
   UsageMeter,
+  WorkflowDefinitionSchema,
+  WorkflowFileSchema,
+  WorkflowInputDefinitionSchema,
+  WorkflowStepDefinitionSchema,
   agentWorkflow,
   askFollowupQuestion_default as askFollowupQuestion,
   computeRateLimitBackoffSeconds,
   configSchema,
   createContext,
+  createDynamicWorkflow,
   executeCommand_default as executeCommand,
   fetchUrl_default as fetchUrl,
   fromJsonModelMessage,
+  generateWorkflowCodeWorkflow,
+  generateWorkflowDefinitionWorkflow,
   getTodoItem_default as getTodoItem,
   listFiles_default as listFiles,
   listMemoryTopics_default as listMemoryTopics,
   listTodoItems_default as listTodoItems,
   makeStepFn,
+  parseDynamicWorkflowDefinition,
   parseJsonFromMarkdown,
   providerModelSchema,
   readBinaryFile_default as readBinaryFile,