keystone-cli 0.7.2 → 1.0.0

package/src/runner/workflow-subflows.test.ts

@@ -0,0 +1,255 @@
+import { afterAll, describe, expect, it } from 'bun:test';
+import { existsSync, rmSync } from 'node:fs';
+import { WorkflowDb } from '../db/workflow-db';
+import type { Workflow } from '../parser/schema';
+import type { Logger } from '../utils/logger';
+import { WorkflowRunner } from './workflow-runner';
+
+describe('WorkflowRunner - Subflows & Compensations', () => {
+  const dbPath = ':memory:';
+
+  it('should execute parallel branches and join with "all" condition', async () => {
+    const workflow: Workflow = {
+      name: 'fan-out-in-all',
+      steps: [
+        { id: 'branch1', type: 'shell', run: 'echo "b1"', needs: [] },
+        { id: 'branch2', type: 'shell', run: 'echo "b2"', needs: [] },
+        {
+          id: 'join',
+          type: 'join',
+          target: 'steps',
+          condition: 'all',
+          needs: ['branch1', 'branch2'],
+        },
+      ],
+      outputs: {
+        b1: '${{ steps.join.output.inputs.branch1.stdout.trim() }}',
+        b2: '${{ steps.join.output.inputs.branch2.stdout.trim() }}',
+      },
+    } as unknown as Workflow;
+
+    const runner = new WorkflowRunner(workflow, { dbPath });
+    const outputs = await runner.run();
+    expect(outputs.b1).toBe('b1');
+    expect(outputs.b2).toBe('b2');
+  });
+
+  it('should fail join step if condition "all" is not met (due to allowFailure error)', async () => {
+    // Branch2 fails but allows failure. Join "all" should strictly fail because Branch2 is not a "real" success.
+    const workflow: Workflow = {
+      name: 'fan-out-in-fail',
+      steps: [
+        { id: 'branch1', type: 'shell', run: 'echo "b1"', needs: [] },
+        { id: 'branch2', type: 'shell', run: 'exit 1', needs: [], allowFailure: true },
+        {
+          id: 'join',
+          type: 'join',
+          condition: 'all',
+          needs: ['branch1', 'branch2'],
+        },
+      ],
+    } as unknown as Workflow;
+
+    const runner = new WorkflowRunner(workflow, { dbPath });
+    await expect(runner.run()).rejects.toThrow(/Join condition 'all' not met/);
+  });
+
+  it('should pass join step with "any" condition if one branch succeeds', async () => {
+    const workflow: Workflow = {
+      name: 'fan-out-in-any',
+      steps: [
+        { id: 'branch1', type: 'shell', run: 'echo "b1"', needs: [] },
+        { id: 'branch2', type: 'shell', run: 'exit 1', needs: [], allowFailure: true },
+        {
+          id: 'join',
+          type: 'join',
+          condition: 'any',
+          needs: ['branch1', 'branch2'],
+        },
+      ],
+      outputs: {
+        status1: '${{ steps.join.output.status.branch1 }}',
+        status2: '${{ steps.join.output.status.branch2 }}',
+      },
+    } as unknown as Workflow;
+
+    const runner = new WorkflowRunner(workflow, { dbPath });
+    const outputs = await runner.run();
+    expect(outputs.status1).toBe('success');
+    // status2 might be undefined or 'success' depending on race, but shouldn't fail the test
+    const status2 = typeof outputs.status2 === 'string' ? outputs.status2 : undefined;
+    expect(status2 === undefined || status2 === 'success').toBe(true);
+  });
+
+  it('should register and execute compensations on failure', async () => {
+    const compDbPath = 'test-compensation.db';
+    if (existsSync(compDbPath)) rmSync(compDbPath);
+
+    const workflow: Workflow = {
+      name: 'comp-wf',
+      steps: [
+        {
+          id: 'step1',
+          type: 'shell',
+          run: 'echo "step1"',
+          needs: [],
+          compensate: {
+            id: 'undo1',
+            type: 'shell',
+            run: 'echo "undoing step1"',
+          },
+        },
+        {
+          id: 'step2',
+          type: 'shell',
+          run: 'echo "step2"',
+          needs: ['step1'],
+          compensate: {
+            id: 'undo2',
+            type: 'shell',
+            run: 'echo "undoing step2"',
+          },
+        },
+        {
+          id: 'fail',
+          type: 'shell',
+          run: 'exit 1',
+          needs: ['step2'],
+        },
+      ],
+    } as unknown as Workflow;
+
+    const logs: string[] = [];
+    const logger: Logger = {
+      log: (msg: string) => logs.push(msg),
+      error: (msg: string) => logs.push(msg),
+      warn: (msg: string) => logs.push(`WARN: ${msg}`),
+      info: (msg: string) => logs.push(`INFO: ${msg}`),
+      debug: (msg: string) => logs.push(`DEBUG: ${msg}`),
+    };
+
+    const runner = new WorkflowRunner(workflow, { dbPath: compDbPath, logger });
+
+    try {
+      await runner.run();
+    } catch (e) {
+      // Expected failure
+    }
+
+    // Verify compensations ran in reverse order
+    const undo2Index = logs.findIndex((l) => l.includes('undoing step2'));
+    const undo1Index = logs.findIndex((l) => l.includes('undoing step1'));
+
+    if (undo2Index === -1 || undo1Index === -1 || undo2Index >= undo1Index) {
+      console.log('--- COMPENSATION LOGS ---');
+      console.log(logs.filter((l) => l.includes('undoing') || l.includes('rollback')).join('\n'));
+      console.log('--- END ---');
+    }
+
+    expect(undo2Index).toBeGreaterThan(-1);
+    expect(undo1Index).toBeGreaterThan(-1);
+    expect(undo2Index).toBeLessThan(undo1Index); // undo2 before undo1
+
+    // Verify DB records
+    const db = new WorkflowDb(compDbPath);
+    const runId = runner.runId;
+    const comps = await db.getAllCompensations(runId);
+    expect(comps.length).toBe(2);
+    db.close();
+
+    if (existsSync(compDbPath)) rmSync(compDbPath);
+  });
+  it('should execute join step early if condition is "any" and one branch finishes', async () => {
+    // This is hard to test deterministically without timing, but we can verify it executes
+    const workflow: Workflow = {
+      name: 'early-join',
+      steps: [
+        { id: 'slow', type: 'shell', run: 'sleep 0.1 && echo "slow"', needs: [] },
+        { id: 'fast', type: 'shell', run: 'echo "fast"', needs: [] },
+        {
+          id: 'early_join',
+          type: 'join',
+          condition: 'any',
+          needs: ['slow', 'fast'],
+        },
+        {
+          id: 'after_join',
+          type: 'shell',
+          run: 'echo "after_join"',
+          needs: ['early_join'],
+        },
+      ],
+      outputs: {
+        order: '${{ steps }}',
+      },
+    } as unknown as Workflow;
+
+    const logs: string[] = [];
+    const logger: Logger = {
+      log: (msg: string) => logs.push(msg),
+      error: (msg: string) => logs.push(msg),
+      warn: () => {},
+      info: () => {},
+      debug: () => {},
+    };
+
+    const runner = new WorkflowRunner(workflow, { dbPath, logger });
+    await runner.run();
+
+    // Verify after_join started BEFORE slow finished
+    const afterJoinStart = logs.findIndex((l) => l.includes('Executing step: after_join'));
+    const slowFinished = logs.findIndex((l) => l.includes('Step slow completed'));
+
+    expect(afterJoinStart).toBeGreaterThan(-1);
+    expect(slowFinished).toBeGreaterThan(-1);
+    expect(afterJoinStart).toBeLessThan(slowFinished);
+  });
+
+  it('should execute top-level workflow compensation on failure', async () => {
+    const wfCompDbPath = 'test-wf-compensation.db';
+    if (existsSync(wfCompDbPath)) rmSync(wfCompDbPath);
+
+    const workflow: Workflow = {
+      name: 'wf-comp',
+      compensate: {
+        id: 'wf-undo',
+        type: 'shell',
+        run: 'echo "undoing workflow"',
+      },
+      steps: [
+        {
+          id: 'step1',
+          type: 'shell',
+          run: 'exit 1',
+          needs: [],
+        },
+      ],
+    } as unknown as Workflow;
+
+    const logs: string[] = [];
+    const logger: Logger = {
+      log: (msg: string) => logs.push(msg),
+      error: (msg: string) => logs.push(msg),
+      warn: () => {},
+      info: () => {},
+      debug: () => {},
+    };
+
+    const runner = new WorkflowRunner(workflow, { dbPath: wfCompDbPath, logger });
+    try {
+      await runner.run();
+    } catch (e) {
+      // Expected failure
+    }
+
+    const wfUndoIndex = logs.findIndex((l) => l.includes('undoing workflow'));
+    if (wfUndoIndex === -1) {
+      console.log('--- WF COMP LOGS ---');
+      console.log(logs.join('\n'));
+      console.log('--- END ---');
+    }
+    expect(wfUndoIndex).toBeGreaterThan(-1);
+
+    if (existsSync(wfCompDbPath)) rmSync(wfCompDbPath);
+  });
+});

package/src/templates/agents/keystone-architect.md

@@ -14,20 +14,25 @@ You are the Keystone Architect. Your goal is to design and generate high-quality
 - **description**: (Optional) Description of the workflow.
 - **inputs**: Map of `{ type: 'string'|'number'|'boolean'|'array'|'object', default: any, description: string }` under the `inputs` key.
 - **outputs**: Map of expressions (e.g., `${{ steps.id.output }}`) under the `outputs` key.
+- **outputSchema**: (Optional) JSON Schema for final workflow outputs.
 - **env**: (Optional) Map of workflow-level environment variables.
-- **concurrency**: (Optional) Global concurrency limit for the workflow (must be a positive integer or expression resolving to one).
-- **eval**: (Optional) Configuration for prompt optimization `{ scorer: 'llm'|'script', agent, prompt, run }`.
+- **concurrency**: (Optional) Global concurrency limit for the workflow.
+- **pools**: (Optional) Map of resource pools `{ pool_name: limit }`.
+- **compensate**: (Optional) Workflow-level compensation step.
+- **eval**: (Optional) Configuration for prompt optimization `{ scorer: 'llm'|'script', agent, prompt, run, allowInsecure, allowSecrets }`.
 - **steps**: Array of step objects. Each step MUST have an `id` and a `type`:
-  - **shell**: `{ id, type: 'shell', run, dir, env, allowInsecure, transform }` (Set `allowInsecure: true` to bypass risky command checks)
-  - **llm**: `{ id, type: 'llm', agent, prompt, schema, provider, model, tools, maxIterations, useGlobalMcp, allowClarification, useStandardTools, allowOutsideCwd, allowInsecure, mcpServers }`
-  - **workflow**: `{ id, type: 'workflow', path, inputs }`
+  - **shell**: `{ id, type: 'shell', run, dir, env, allowInsecure, transform }`
+  - **llm**: `{ id, type: 'llm', agent, prompt, outputSchema, provider, model, tools, maxIterations, maxMessageHistory, useGlobalMcp, allowClarification, useStandardTools, allowOutsideCwd, allowInsecure, mcpServers, handoff }`
+  - **workflow**: `{ id, type: 'workflow', path, inputs, outputMapping }`
   - **file**: `{ id, type: 'file', path, op: 'read'|'write'|'append', content, allowOutsideCwd }`
-  - **request**: `{ id, type: 'request', url, method, body, headers }`
-  - **human**: `{ id, type: 'human', message, inputType: 'confirm'|'text' }` (Note: 'confirm' returns boolean but automatically fallbacks to text if input is not yes/no)
-  - **sleep**: `{ id, type: 'sleep', duration }` (duration can be a number or expression string)
-  - **script**: `{ id, type: 'script', run, allowInsecure }` (Executes JS in a secure sandbox; set allowInsecure to true to allow fallback to insecure VM)
+  - **request**: `{ id, type: 'request', url, method, body, headers, allowInsecure }`
+  - **human**: `{ id, type: 'human', message, inputType: 'confirm'|'text' }`
+  - **sleep**: `{ id, type: 'sleep', duration, durable }` (use `durable: true` for sleeps >= 60s)
+  - **script**: `{ id, type: 'script', run, allowInsecure }`
+  - **engine**: `{ id, type: 'engine', command, args, input, env, cwd, outputSchema }`
   - **memory**: `{ id, type: 'memory', op: 'search'|'store', query, text, model, metadata, limit }`
-- **Common Step Fields**: `needs` (array of IDs), `if` (expression), `timeout` (ms), `retry` (`{ count, backoff: 'linear'|'exponential', baseDelay }`), `auto_heal` (`{ agent, maxAttempts, model }`), `reflexion` (`{ limit, hint }`), `learn` (boolean, auto-index for few-shot), `foreach`, `concurrency` (positive integer), `transform`.
+  - **join**: `{ id, type: 'join', target: 'steps'|'branches', condition: 'all'|'any'|number }`
+- **Common Step Fields**: `needs` (array), `if` (expr), `timeout` (ms), `retry` (`{ count, backoff, baseDelay }`), `auto_heal`, `reflexion`, `learn`, `foreach`, `concurrency`, `pool`, `compensate`, `transform`, `inputSchema`, `outputSchema`, `outputRetries`, `repairStrategy`.
 - **finally**: Optional array of steps to run at the end of the workflow, regardless of success or failure.
 - **IMPORTANT**: Steps run in **parallel** by default. To ensure sequential execution, a step must explicitly list the previous step's ID in its `needs` array.
 
@@ -68,8 +73,8 @@ Markdown files with YAML frontmatter:
 - **Custom Logic**: Use `script` steps for data manipulation that is too complex for expressions.
 - **Agent Collaboration**: Create specialized agents for complex sub-tasks and coordinate them via `llm` steps.
 - **Clarification**: Enable `allowClarification` in `llm` steps if the agent should be able to ask the user for missing info.
-- **Discovery**: Use `mcpServers` in `llm` steps when the agent needs access to external tools or systems. `mcpServers` can be a list of server names or configuration objects:
-  - Local: `{ name, command, args, env, timeout }`
+- **Discovery**: Use `mcpServers` in `llm` steps. `mcpServers` can be a list of server names or configuration objects:
+  - Local: `{ name, type: 'local', command, args, env, timeout }`
   - Remote: `{ name, type: 'remote', url, headers, timeout }`
 
 # Seeking Clarification

package/src/templates/agents/tester.md

@@ -0,0 +1,21 @@
+---
+name: tester
+description: "Expert at writing and running tests for Keystone CLI"
+model: gpt-4o
+---
+
+# Role
+You are the Keystone Tester. Your goal is to ensure the reliability and correctness of the Keystone CLI by writing comprehensive tests and verifying that changes do not introduce regressions.
+
+# Guidelines
+- Use `run_command` to execute tests (e.g., `bun test`, `bun test <file>`).
+- Use `list_files` and `read_file` to examine existing tests for patterns.
+- When a test fails, analyze the output to identify the cause.
+- Use `write_file` to create new test files or update existing ones.
+- Always use the `keystone test` command to verify workflow-level functionality if applicable.
+- Follow the project's testing conventions (using `bun:test` for unit tests and `TestHarness` for workflow tests).
+
+# Knowledge Base
+- **Unit Tests**: Located in `src/**/*.test.ts`. Use `bun test` to run.
+- **Workflow Tests**: Located in `.keystone/tests/`. Use `keystone test` to run.
+- **Test Harness**: Use `src/runner/test-harness.ts` for deterministic workflow testing.

package/src/templates/child-rollback.yaml

@@ -0,0 +1,11 @@
+name: nested-rollback-child
+description: Child workflow with a side effect and compensation
+
+steps:
+  - id: child_action
+    type: shell
+    run: echo "Child action executed"
+    compensate:
+      id: undo_child_action
+      type: shell
+      run: echo "Undoing child action..."

package/src/templates/decompose-implement.yaml

@@ -0,0 +1,53 @@
+name: decompose-implement
+description: "Implementation task sub-workflow for a decomposed problem"
+
+inputs:
+  problem: { type: string }
+  context: { type: string, default: "" }
+  constraints: { type: string, default: "" }
+  task: { type: object }
+  research: { type: object, default: {} }
+
+outputs:
+  summary: ${{ steps.implement.output.summary }}
+  files_changed: ${{ steps.implement.output.files_changed }}
+  open_questions: ${{ steps.implement.output.open_questions }}
+
+steps:
+  - id: implement
+    type: llm
+    agent: software-engineer
+    allowClarification: true
+    useStandardTools: true
+    prompt: |
+      You are implementing a task for a larger problem.
+
+      Problem:
+      ${{ inputs.problem }}
+
+      Context:
+      ${{ inputs.context }}
+
+      Constraints:
+      ${{ inputs.constraints }}
+
+      Task:
+      ${{ inputs.task }}
+
+      Research findings:
+      ${{ inputs.research }}
+
+      If code changes are needed, use available tools to make them.
+      Return only the structured JSON required by the schema.
+    outputSchema:
+      type: object
+      properties:
+        summary:
+          type: string
+        files_changed:
+          type: array
+          items: { type: string }
+        open_questions:
+          type: array
+          items: { type: string }
+      required: [summary]

package/src/templates/decompose-problem.yaml

@@ -0,0 +1,159 @@
+name: decompose-problem
+description: "Decompose a complex problem into research, implementation, and review sub-workflows"
+
+inputs:
+  problem: { type: string }
+  context: { type: string, default: "" }
+  constraints: { type: string, default: "" }
+  max_parallel: { type: number, default: 3 }
+
+outputs:
+  plan: ${{ steps.plan.output }}
+  research: ${{ steps.research.output }}
+  implementation: ${{ steps.implementation.output }}
+  review: ${{ steps.review.output }}
+  summary: ${{ steps.summary.output }}
+
+steps:
+  - id: plan
+    type: llm
+    agent: general
+    allowClarification: true
+    prompt: |
+      You are a planner. Decompose the problem into research, implementation,
+      and review tasks. Keep tasks small, specific, and measurable.
+
+      Problem:
+      ${{ inputs.problem }}
+
+      Context:
+      ${{ inputs.context }}
+
+      Constraints:
+      ${{ inputs.constraints }}
+
+      Return empty arrays if a category is not needed.
+      Return only the structured JSON required by the schema.
+    outputSchema:
+      type: object
+      properties:
+        research:
+          type: array
+          items:
+            type: object
+            properties:
+              id: { type: string }
+              title: { type: string }
+              details: { type: string }
+              acceptance:
+                type: array
+                items: { type: string }
+            required: [id, title, details]
+        implementation:
+          type: array
+          items:
+            type: object
+            properties:
+              id: { type: string }
+              title: { type: string }
+              details: { type: string }
+              acceptance:
+                type: array
+                items: { type: string }
+            required: [id, title, details]
+        review:
+          type: array
+          items:
+            type: object
+            properties:
+              id: { type: string }
+              title: { type: string }
+              details: { type: string }
+              acceptance:
+                type: array
+                items: { type: string }
+            required: [id, title, details]
+        success_criteria:
+          type: array
+          items: { type: string }
+        notes:
+          type: string
+      required: [research, implementation, review]
+
+  - id: approve_plan
+    type: human
+    needs: [plan]
+    inputType: confirm
+    message: "Approve the plan and run sub-workflows?"
+
+  - id: research
+    type: workflow
+    needs: [approve_plan]
+    foreach: ${{ steps.plan.output.research }}
+    concurrency: ${{ inputs.max_parallel }}
+    path: decompose-research
+    inputs:
+      problem: ${{ inputs.problem }}
+      context: ${{ inputs.context }}
+      constraints: ${{ inputs.constraints }}
+      task: ${{ item }}
+
+  - id: implementation
+    type: workflow
+    needs: [research]
+    foreach: ${{ steps.plan.output.implementation }}
+    concurrency: ${{ inputs.max_parallel }}
+    path: decompose-implement
+    inputs:
+      problem: ${{ inputs.problem }}
+      context: ${{ inputs.context }}
+      constraints: ${{ inputs.constraints }}
+      research: ${{ steps.research.outputs }}
+      task: ${{ item }}
+
+  - id: review
+    type: workflow
+    needs: [implementation]
+    foreach: ${{ steps.plan.output.review }}
+    concurrency: ${{ inputs.max_parallel }}
+    path: decompose-review
+    inputs:
+      problem: ${{ inputs.problem }}
+      context: ${{ inputs.context }}
+      constraints: ${{ inputs.constraints }}
+      implementation: ${{ steps.implementation.outputs }}
+      task: ${{ item }}
+
+  - id: summary
+    type: llm
+    agent: summarizer
+    needs: [review]
+    prompt: |
+      Summarize the results of the workflow.
+
+      Problem:
+      ${{ inputs.problem }}
+
+      Plan:
+      ${{ steps.plan.output }}
+
+      Research results:
+      ${{ steps.research.outputs }}
+
+      Implementation results:
+      ${{ steps.implementation.outputs }}
+
+      Review results:
+      ${{ steps.review.outputs }}
+    outputSchema:
+      type: object
+      properties:
+        summary:
+          type: string
+        open_questions:
+          type: array
+          items: { type: string }
+        risks:
+          type: array
+          items: { type: string }
+      required: [summary]

package/src/templates/decompose-research.yaml

@@ -0,0 +1,52 @@
+name: decompose-research
+description: "Research task sub-workflow for a decomposed problem"
+
+inputs:
+  problem: { type: string }
+  context: { type: string, default: "" }
+  constraints: { type: string, default: "" }
+  task: { type: object }
+
+outputs:
+  summary: ${{ steps.research.output.summary }}
+  findings: ${{ steps.research.output.findings }}
+  assumptions: ${{ steps.research.output.assumptions }}
+  open_questions: ${{ steps.research.output.open_questions }}
+
+steps:
+  - id: research
+    type: llm
+    agent: explore
+    useStandardTools: true
+    prompt: |
+      You are researching a task for a larger problem.
+
+      Problem:
+      ${{ inputs.problem }}
+
+      Context:
+      ${{ inputs.context }}
+
+      Constraints:
+      ${{ inputs.constraints }}
+
+      Task:
+      ${{ inputs.task }}
+
+      Provide concise, actionable research.
+      Return only the structured JSON required by the schema.
+    outputSchema:
+      type: object
+      properties:
+        summary:
+          type: string
+        findings:
+          type: array
+          items: { type: string }
+        assumptions:
+          type: array
+          items: { type: string }
+        open_questions:
+          type: array
+          items: { type: string }
+      required: [summary]

package/src/templates/decompose-review.yaml

@@ -0,0 +1,51 @@
+name: decompose-review
+description: "Review task sub-workflow for a decomposed problem"
+
+inputs:
+  problem: { type: string }
+  context: { type: string, default: "" }
+  constraints: { type: string, default: "" }
+  task: { type: object }
+  implementation: { type: object, default: {} }
+
+outputs:
+  approved: ${{ steps.review.output.approved }}
+  issues: ${{ steps.review.output.issues }}
+  suggestions: ${{ steps.review.output.suggestions }}
+
+steps:
+  - id: review
+    type: llm
+    agent: general
+    prompt: |
+      Review the implementation results for the task.
+
+      Problem:
+      ${{ inputs.problem }}
+
+      Context:
+      ${{ inputs.context }}
+
+      Constraints:
+      ${{ inputs.constraints }}
+
+      Task:
+      ${{ inputs.task }}
+
+      Implementation results:
+      ${{ inputs.implementation }}
+
+      Identify issues, risks, and missing tests. Be direct and specific.
+      Return only the structured JSON required by the schema.
+    outputSchema:
+      type: object
+      properties:
+        approved:
+          type: boolean
+        issues:
+          type: array
+          items: { type: string }
+        suggestions:
+          type: array
+          items: { type: string }
+      required: [approved]