keystone-cli 0.4.3 → 0.5.0

package/src/runner/step-executor.test.ts

@@ -49,13 +49,17 @@ describe('step-executor', () => {
   beforeAll(() => {
     try {
       mkdirSync(tempDir, { recursive: true });
-    } catch (e) {}
+    } catch (e) {
+      // Ignore error
+    }
   });
 
   afterAll(() => {
     try {
       rmSync(tempDir, { recursive: true, force: true });
-    } catch (e) {}
+    } catch (e) {
+      // Ignore error
+    }
   });
 
   beforeEach(() => {
@@ -70,6 +74,7 @@ describe('step-executor', () => {
       const step: ShellStep = {
         id: 's1',
         type: 'shell',
+        needs: [],
         run: 'echo "hello"',
       };
       const result = await executeStep(step, context);
@@ -81,6 +86,7 @@ describe('step-executor', () => {
       const step: ShellStep = {
         id: 's1',
         type: 'shell',
+        needs: [],
         run: 'exit 1',
       };
       const result = await executeStep(step, context);
@@ -95,6 +101,7 @@ describe('step-executor', () => {
       const writeStep: FileStep = {
         id: 'w1',
         type: 'file',
+        needs: [],
         op: 'write',
         path: filePath,
         content: 'hello file',
@@ -105,6 +112,7 @@ describe('step-executor', () => {
       const readStep: FileStep = {
         id: 'r1',
         type: 'file',
+        needs: [],
         op: 'read',
         path: filePath,
       };
@@ -119,6 +127,7 @@ describe('step-executor', () => {
         {
           id: 'w1',
           type: 'file',
+          needs: [],
           op: 'write',
           path: filePath,
           content: 'line 1\n',
@@ -130,6 +139,7 @@ describe('step-executor', () => {
         {
           id: 'a1',
           type: 'file',
+          needs: [],
           op: 'append',
           path: filePath,
           content: 'line 2',
@@ -145,6 +155,7 @@ describe('step-executor', () => {
       const readStep: FileStep = {
         id: 'r1',
         type: 'file',
+        needs: [],
         op: 'read',
         path: join(tempDir, 'non-existent.txt'),
       };
@@ -183,6 +194,7 @@ describe('step-executor', () => {
       const step: SleepStep = {
         id: 'sl1',
         type: 'sleep',
+        needs: [],
         duration: 10,
       };
       const start = Date.now();
@@ -217,6 +229,7 @@ describe('step-executor', () => {
       const step: RequestStep = {
         id: 'req1',
         type: 'request',
+        needs: [],
         url: 'https://api.example.com/test',
         method: 'GET',
       };
@@ -233,6 +246,7 @@ describe('step-executor', () => {
       const step: RequestStep = {
         id: 'req1',
         type: 'request',
+        needs: [],
         url: 'https://api.example.com/post',
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
@@ -253,6 +267,7 @@ describe('step-executor', () => {
       const step: RequestStep = {
         id: 'req1',
         type: 'request',
+        needs: [],
         url: 'https://api.example.com/post',
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
@@ -273,6 +288,7 @@ describe('step-executor', () => {
       const step: RequestStep = {
         id: 'req1',
         type: 'request',
+        needs: [],
         url: 'https://api.example.com/post',
         method: 'POST',
         body: { foo: 'bar' },
@@ -298,6 +314,7 @@ describe('step-executor', () => {
       const step: RequestStep = {
         id: 'req1',
         type: 'request',
+        needs: [],
         url: 'https://api.example.com/text',
         method: 'GET',
       };
@@ -320,6 +337,7 @@ describe('step-executor', () => {
       const step: RequestStep = {
         id: 'req1',
         type: 'request',
+        needs: [],
         url: 'https://api.example.com/fail',
         method: 'POST',
       };
@@ -348,6 +366,7 @@ describe('step-executor', () => {
       const step: HumanStep = {
         id: 'h1',
         type: 'human',
+        needs: [],
         message: 'Proceed?',
         inputType: 'confirm',
       };
@@ -365,6 +384,7 @@ describe('step-executor', () => {
       const step: HumanStep = {
         id: 'h1',
         type: 'human',
+        needs: [],
         message: 'What is your name?',
         inputType: 'text',
       };
@@ -379,6 +399,7 @@ describe('step-executor', () => {
       const step: HumanStep = {
         id: 'h1',
         type: 'human',
+        needs: [],
         message: 'Proceed?',
         inputType: 'confirm',
       };
@@ -408,6 +429,7 @@ describe('step-executor', () => {
       const step: HumanStep = {
         id: 'h1',
         type: 'human',
+        needs: [],
         message: 'Proceed?',
         inputType: 'confirm',
       };
@@ -424,6 +446,7 @@ describe('step-executor', () => {
       const step: HumanStep = {
         id: 'h1',
         type: 'human',
+        needs: [],
         message: 'Proceed?',
         inputType: 'confirm',
       };
@@ -440,6 +463,7 @@ describe('step-executor', () => {
       const step: WorkflowStep = {
         id: 'w1',
         type: 'workflow',
+        needs: [],
         path: 'child.yaml',
       };
       // @ts-ignore
@@ -458,6 +482,7 @@ describe('step-executor', () => {
       const step: WorkflowStep = {
         id: 'w1',
         type: 'workflow',
+        needs: [],
         path: 'child.yaml',
       };
       const result = await executeStep(step, context);
@@ -485,6 +510,7 @@ describe('step-executor', () => {
       const step: ShellStep = {
         id: 's1',
         type: 'shell',
+        needs: [],
         run: 'echo "json string"',
         transform: 'output.stdout.toUpperCase().trim()',
       };
@@ -497,6 +523,7 @@ describe('step-executor', () => {
       const step: ShellStep = {
         id: 's1',
         type: 'shell',
+        needs: [],
         run: 'echo "hello"',
         transform: '${{ output.stdout.trim() + " world" }}',
       };
@@ -509,6 +536,7 @@ describe('step-executor', () => {
       const step: ShellStep = {
         id: 's1',
         type: 'shell',
+        needs: [],
         run: 'echo "hello"',
         transform: 'nonexistent.property',
       };

package/src/runner/timeout.ts

@@ -14,7 +14,7 @@ export async function withTimeout<T>(
   timeoutMs: number,
   operation = 'Operation'
 ): Promise<T> {
-  let timeoutId: Timer;
+  let timeoutId: Timer | undefined;
 
   const timeoutPromise = new Promise<never>((_, reject) => {
     timeoutId = setTimeout(() => {
@@ -25,6 +25,6 @@ export async function withTimeout<T>(
   try {
     return await Promise.race([promise, timeoutPromise]);
   } finally {
-    clearTimeout(timeoutId);
+    if (timeoutId) clearTimeout(timeoutId);
   }
 }

package/src/runner/tool-integration.test.ts

@@ -28,7 +28,9 @@ describe('llm-executor with tools and MCP', () => {
   beforeAll(() => {
     try {
       mkdirSync(agentsDir, { recursive: true });
-    } catch (e) {}
+    } catch (e) {
+      // Ignore error
+    }
     const agentContent = `---
 name: tool-test-agent
 tools:
@@ -45,7 +47,9 @@ Test system prompt`;
   afterAll(() => {
     try {
       unlinkSync(agentPath);
-    } catch (e) {}
+    } catch (e) {
+      // Ignore error
+    }
   });
 
   it('should merge tools from agent, step and MCP', async () => {
@@ -90,6 +94,7 @@ Test system prompt`;
       agent: 'tool-test-agent',
       prompt: 'test',
       needs: [],
+      maxIterations: 10,
       tools: [
         {
           name: 'step-tool',
@@ -179,6 +184,7 @@ Test system prompt`;
       agent: 'tool-test-agent',
       prompt: 'test',
       needs: [],
+      maxIterations: 10,
       mcpServers: [{ name: 'test-mcp', command: 'node', args: ['-e', ''] }],
     };
 

package/src/runner/workflow-runner.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
-import { WorkflowDb } from '../db/workflow-db.ts';
+import { type RunStatus, WorkflowDb } from '../db/workflow-db.ts';
 import type { ExpressionContext } from '../expression/evaluator.ts';
 import { ExpressionEvaluator } from '../expression/evaluator.ts';
 import type { Step, Workflow, WorkflowStep } from '../parser/schema.ts';
@@ -89,6 +89,9 @@ export class WorkflowRunner {
   private mcpManager: MCPManager;
   private options: RunOptions;
   private signalHandler?: (signal: string) => void;
+  private isStopping = false;
+  private hasWarnedMemory = false;
+  private static readonly MEMORY_WARNING_THRESHOLD = 1000;
 
   constructor(workflow: Workflow, options: RunOptions = {}) {
     this.workflow = workflow;
@@ -144,9 +147,11 @@ export class WorkflowRunner {
       const storedInputs = JSON.parse(run.inputs);
       this.inputs = { ...storedInputs, ...this.inputs };
     } catch (error) {
-      throw new Error(
-        `Failed to parse inputs from run: ${error instanceof Error ? error.message : String(error)}`
+      // Log warning but continue with default empty inputs instead of crashing
+      this.logger.warn(
+        `Failed to parse inputs from run ${this.runId}, using defaults: ${error instanceof Error ? error.message : String(error)}`
       );
+      // Keep existing inputs (from resumeInputs or empty)
     }
 
     // Load all step executions for this run
@@ -190,7 +195,15 @@ export class WorkflowRunner {
           if (exec.iteration_index === null) continue; // Skip parent step record
 
           if (exec.status === 'success' || exec.status === 'skipped') {
-            const output = exec.output ? JSON.parse(exec.output) : null;
+            let output: unknown = null;
+            try {
+              output = exec.output ? JSON.parse(exec.output) : null;
+            } catch (error) {
+              this.logger.warn(
+                `Failed to parse output for step ${stepId} iteration ${exec.iteration_index}: ${error}`
+              );
+              output = { error: 'Failed to parse output' };
+            }
             items[exec.iteration_index] = {
               output,
               outputs:
@@ -211,21 +224,36 @@ export class WorkflowRunner {
           }
         }
 
-        // We need to know the total expected items to decide if the whole step is complete
-        // Evaluate the foreach expression again
+        // Use persisted foreach items from parent step for deterministic resume
+        // This ensures the resume uses the same array as the initial run
         let expectedCount = -1;
-        try {
-          const baseContext = this.buildContext();
-          const foreachExpr = stepDef.foreach;
-          if (foreachExpr) {
-            const foreachItems = ExpressionEvaluator.evaluate(foreachExpr, baseContext);
-            if (Array.isArray(foreachItems)) {
-              expectedCount = foreachItems.length;
+        const parentExec = stepExecutions.find((e) => e.iteration_index === null);
+        if (parentExec?.output) {
+          try {
+            const parsed = JSON.parse(parentExec.output);
+            if (parsed.__foreachItems && Array.isArray(parsed.__foreachItems)) {
+              expectedCount = parsed.__foreachItems.length;
+            }
+          } catch {
+            // Parse error, fall through to expression evaluation
+          }
+        }
+
+        // Fallback to expression evaluation if persisted items not found
+        if (expectedCount === -1) {
+          try {
+            const baseContext = this.buildContext();
+            const foreachExpr = stepDef.foreach;
+            if (foreachExpr) {
+              const foreachItems = ExpressionEvaluator.evaluate(foreachExpr, baseContext);
+              if (Array.isArray(foreachItems)) {
+                expectedCount = foreachItems.length;
+              }
             }
+          } catch (e) {
+            // If we can't evaluate yet (dependencies not met?), we can't be sure it's complete
+            allSuccess = false;
           }
-        } catch (e) {
-          // If we can't evaluate yet (dependencies not met?), we can't be sure it's complete
-          allSuccess = false;
         }
 
         // Check if we have all items (no gaps)
@@ -261,7 +289,13 @@ export class WorkflowRunner {
         // Single execution step
         const exec = stepExecutions[0];
         if (exec.status === 'success' || exec.status === 'skipped' || exec.status === 'suspended') {
-          const output = exec.output ? JSON.parse(exec.output) : null;
+          let output: unknown = null;
+          try {
+            output = exec.output ? JSON.parse(exec.output) : null;
+          } catch (error) {
+            this.logger.warn(`Failed to parse output for step ${stepId}: ${error}`);
+            output = { error: 'Failed to parse output' };
+          }
           this.stepContexts.set(stepId, {
             output,
             outputs:
@@ -286,18 +320,9 @@ export class WorkflowRunner {
    */
   private setupSignalHandlers(): void {
     const handler = async (signal: string) => {
+      if (this.isStopping) return;
       this.logger.log(`\n\n🛑 Received ${signal}. Cleaning up...`);
-      try {
-        await this.db.updateRunStatus(
-          this.runId,
-          'failed',
-          undefined,
-          `Cancelled by user (${signal})`
-        );
-        this.logger.log('✓ Run status updated to failed');
-      } catch (error) {
-        this.logger.error(`Error during cleanup: ${error}`);
-      }
+      await this.stop('failed', `Cancelled by user (${signal})`);
 
       // Only exit if not embedded
       if (!this.options.preventExit) {
@@ -311,6 +336,28 @@ export class WorkflowRunner {
     process.on('SIGTERM', handler);
   }
 
+  /**
+   * Stop the runner and cleanup resources
+   */
+  public async stop(status: RunStatus = 'failed', error?: string): Promise<void> {
+    if (this.isStopping) return;
+    this.isStopping = true;
+
+    try {
+      this.removeSignalHandlers();
+
+      // Update run status in DB
+      await this.db.updateRunStatus(this.runId, status, undefined, error);
+
+      // Stop all MCP clients
+      await this.mcpManager.stopAll();
+
+      this.db.close();
+    } catch (err) {
+      this.logger.error(`Error during stop/cleanup: ${err}`);
+    }
+  }
+
   /**
    * Remove signal handlers
    */
@@ -611,6 +658,13 @@ export class WorkflowRunner {
 
       this.logger.log(`  ⤷ Executing step ${step.id} for ${items.length} items`);
 
+      if (items.length > WorkflowRunner.MEMORY_WARNING_THRESHOLD && !this.hasWarnedMemory) {
+        this.logger.warn(
+          `  ⚠️  Warning: Large foreach loop detected (${items.length} items). This may consume significant memory and lead to instability.`
+        );
+        this.hasWarnedMemory = true;
+      }
+
       // Evaluate concurrency if it's an expression, otherwise use the number directly
       let concurrencyLimit = items.length;
       if (step.concurrency !== undefined) {
@@ -631,6 +685,10 @@ export class WorkflowRunner {
       await this.db.createStep(parentStepExecId, this.runId, step.id);
       await this.db.startStep(parentStepExecId);
 
+      // Persist the foreach items in parent step for deterministic resume
+      // This ensures resume uses the same array even if expression would evaluate differently
+      await this.db.completeStep(parentStepExecId, 'pending', { __foreachItems: items });
+
       try {
         // Initialize results array with existing context or empty slots
         const existingContext = this.stepContexts.get(step.id) as ForeachStepContext;
@@ -667,7 +725,15 @@ export class WorkflowRunner {
                 existingExec &&
                 (existingExec.status === 'success' || existingExec.status === 'skipped')
               ) {
-                const output = existingExec.output ? JSON.parse(existingExec.output) : null;
+                let output: unknown = null;
+                try {
+                  output = existingExec.output ? JSON.parse(existingExec.output) : null;
+                } catch (error) {
+                  this.logger.warn(
+                    `Failed to parse output for step ${step.id} iteration ${i}: ${error}`
+                  );
+                  output = { error: 'Failed to parse output' };
+                }
                 itemResults[i] = {
                   output,
                   outputs:

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

@@ -12,7 +12,7 @@ You are the Keystone Architect. Your goal is to design and generate high-quality
 ## Workflow Schema (.yaml)
 - **name**: Unique identifier for the workflow.
 - **description**: (Optional) Description of the workflow.
-- **inputs**: Map of `{ type: string, default: any, description: string }` under the `inputs` key.
+- **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.
 - **env**: (Optional) Map of workflow-level environment variables.
 - **concurrency**: (Optional) Global concurrency limit for the workflow (number or expression).
@@ -25,7 +25,7 @@ You are the Keystone Architect. Your goal is to design and generate high-quality
   - **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)
-- **Common Step Fields**: `needs` (array of IDs), `if` (expression), `timeout` (ms), `retry`, `foreach`, `concurrency`, `transform`.
+- **Common Step Fields**: `needs` (array of IDs), `if` (expression), `timeout` (ms), `retry` (`{ count, backoff: 'linear'|'exponential', baseDelay }`), `foreach`, `concurrency`, `transform`.
 - **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.
 
@@ -52,7 +52,9 @@ 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 `{ name, command, args, env }`.
+- **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 }`
+  - Remote: `{ name, type: 'remote', url, headers, timeout }`
 
 # Seeking Clarification
 If you have access to an `ask` tool and the user requirements are unclear, **use it** before generating output. Ask about:

package/src/types/status.ts

@@ -0,0 +1,25 @@
+/**
+ * Centralized status constants for workflow and step execution
+ */
+
+export const StepStatus = {
+  PENDING: 'pending',
+  SUCCESS: 'success',
+  FAILED: 'failed',
+  PAUSED: 'paused',
+  SUSPENDED: 'suspended',
+  SKIPPED: 'skipped',
+  RUNNING: 'running',
+} as const;
+
+export type StepStatusType = (typeof StepStatus)[keyof typeof StepStatus];
+
+export const WorkflowStatus = {
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  PAUSED: 'paused',
+  SUSPENDED: 'suspended',
+  RUNNING: 'running',
+} as const;
+
+export type WorkflowStatusType = (typeof WorkflowStatus)[keyof typeof WorkflowStatus];

package/src/ui/dashboard.tsx

@@ -34,7 +34,9 @@ const Dashboard = () => {
             }
             return sum;
           }, 0);
-        } catch (e) {}
+        } catch (e) {
+          // Ignore write error
+        }
         return { ...run, total_tokens };
       });
       setRuns(runsWithUsage);

package/src/utils/auth-manager.test.ts

@@ -28,7 +28,9 @@ describe('AuthManager', () => {
     if (fs.existsSync(TEMP_AUTH_FILE)) {
       try {
         fs.rmSync(TEMP_AUTH_FILE);
-      } catch (e) {}
+      } catch (e) {
+        // Ignore likely missing file error
+      }
     }
     global.fetch = originalFetch;
     // Set environment variable for EACH test to be safe

package/src/utils/auth-manager.ts

@@ -26,6 +26,9 @@ export const COPILOT_HEADERS = {
 
 const GITHUB_CLIENT_ID = '013444988716b5155f4c'; // GitHub CLI Client ID
 
+/** Buffer time in seconds before token expiry to trigger refresh (5 minutes) */
+const TOKEN_REFRESH_BUFFER_SECONDS = 300;
+
 export class AuthManager {
   private static getAuthPath(): string {
     if (process.env.KEYSTONE_AUTH_PATH) {
@@ -53,7 +56,14 @@ export class AuthManager {
   static save(data: AuthData): void {
     const path = AuthManager.getAuthPath();
     const current = AuthManager.load();
-    writeFileSync(path, JSON.stringify({ ...current, ...data }, null, 2));
+    try {
+      writeFileSync(path, JSON.stringify({ ...current, ...data }, null, 2));
+    } catch (error) {
+      console.error(
+        'Failed to save auth data:',
+        error instanceof Error ? error.message : String(error)
+      );
+    }
   }
 
   static async initGitHubDeviceLogin(): Promise<{
@@ -156,7 +166,7 @@ export class AuthManager {
     if (
       auth.copilot_token &&
       auth.copilot_expires_at &&
-      auth.copilot_expires_at > Date.now() / 1000 + 300
+      auth.copilot_expires_at > Date.now() / 1000 + TOKEN_REFRESH_BUFFER_SECONDS
     ) {
       return auth.copilot_token;
     }

package/src/utils/config-loader.test.ts

@@ -1,27 +1,10 @@
 import { afterEach, describe, expect, it } from 'bun:test';
-import { existsSync, mkdirSync, rmdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
 import type { Config } from '../parser/config-schema';
 import { ConfigLoader } from './config-loader';
 
 describe('ConfigLoader', () => {
-  const tempDir = join(process.cwd(), '.keystone-test');
-
   afterEach(() => {
     ConfigLoader.clear();
-    if (existsSync(tempDir)) {
-      try {
-        // Simple recursive delete
-        const files = ['config.yaml', 'config.yml'];
-        for (const file of files) {
-          const path = join(tempDir, file);
-          if (existsSync(path)) {
-            // fs.unlinkSync(path);
-          }
-        }
-        // rmdirSync(tempDir);
-      } catch (e) {}
-    }
   });
 
   it('should allow setting and clearing config', () => {
@@ -33,6 +16,7 @@ describe('ConfigLoader', () => {
       model_mappings: {},
       storage: { retention_days: 30 },
       workflows_directory: 'workflows',
+      mcp_servers: {},
     };
 
     ConfigLoader.setConfig(mockConfig);
@@ -58,6 +42,7 @@ describe('ConfigLoader', () => {
       },
       storage: { retention_days: 30 },
       workflows_directory: 'workflows',
+      mcp_servers: {},
     };
     ConfigLoader.setConfig(mockConfig);
 

package/src/utils/mermaid.ts

@@ -71,14 +71,6 @@ export function generateMermaidGraph(workflow: Workflow): string {
   return lines.join('\n');
 }
 
-/**
- * Renders a workflow as a local ASCII graph using dagre for layout.
- */
-export async function renderMermaidAsAscii(_mermaid: string): Promise<string | null> {
-  // We no longer use the mermaid string for ASCII, we use the workflow object directly.
-  return null;
-}
-
 export function renderWorkflowAsAscii(workflow: Workflow): string {
   const g = new dagre.graphlib.Graph();
   g.setGraph({ rankdir: 'LR', nodesep: 2, edgesep: 1, ranksep: 4 });