keystone-cli 1.0.3 → 1.1.1

package/src/runner/quality-gate.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, mock, test } from 'bun:test';
+import type { Step, Workflow } from '../parser/schema';
+import { WorkflowRunner } from './workflow-runner';
+
+describe('WorkflowRunner qualityGate', () => {
+  test('should refine output until the quality gate approves', async () => {
+    const workflow: Workflow = {
+      name: 'quality-gate-test',
+      outputs: {
+        final: '${{ steps.generate.output }}',
+      },
+      steps: [
+        {
+          id: 'generate',
+          type: 'llm',
+          agent: 'test-agent',
+          prompt: 'draft the content',
+          qualityGate: {
+            agent: 'reviewer',
+            maxAttempts: 1,
+          },
+        } as Step,
+      ],
+    };
+
+    let draftAttempt = 0;
+    let reviewAttempt = 0;
+
+    const executeStepMock = mock(async (step: Step) => {
+      if (step.id === 'generate') {
+        draftAttempt += 1;
+        return {
+          status: 'success',
+          output: draftAttempt === 1 ? 'draft v1' : 'draft v2',
+        };
+      }
+
+      if (step.id === 'generate-quality-review') {
+        reviewAttempt += 1;
+        return {
+          status: 'success',
+          output: {
+            approved: reviewAttempt > 1,
+            issues: reviewAttempt > 1 ? [] : ['Needs more detail'],
+            suggestions: reviewAttempt > 1 ? [] : ['Expand the draft'],
+          },
+        };
+      }
+
+      return { status: 'failed', output: null, error: 'Unexpected step' };
+    });
+
+    const runner = new WorkflowRunner(workflow, {
+      dbPath: ':memory:',
+      executeStep: executeStepMock as unknown as typeof import('./step-executor').executeStep,
+      logger: {
+        log: () => {},
+        error: () => {},
+        warn: () => {},
+        info: () => {},
+      },
+    });
+
+    const outputs = await runner.run();
+
+    expect(outputs.final).toBe('draft v2');
+    expect(executeStepMock).toHaveBeenCalledTimes(4);
+  });
+});

package/src/runner/reflexion.test.ts

@@ -3,8 +3,6 @@ import type { Step, Workflow } from '../parser/schema';
 import * as StepExecutor from './step-executor';
 import { WorkflowRunner } from './workflow-runner';
 
-// Mock the LLM Adapter
-
 describe('WorkflowRunner Reflexion', () => {
   beforeEach(() => {
     jest.restoreAllMocks();
@@ -33,42 +31,36 @@ describe('WorkflowRunner Reflexion', () => {
             content: JSON.stringify({ run: 'echo "fixed"' }),
           },
         }),
-        // biome-ignore lint/suspicious/noExplicitAny: mock adapter
       } as any,
       resolvedModel: 'mock-model',
     });
 
+    const spy = jest.fn();
+
     const runner = new WorkflowRunner(workflow, {
       logger: { log: () => {}, error: () => {}, warn: () => {} },
       dbPath: ':memory:',
       getAdapter: mockGetAdapter,
+      executeStep: spy as any,
     });
 
-    // biome-ignore lint/suspicious/noExplicitAny: Accessing private property for testing
     const db = (runner as any).db;
     await db.createRun(runner.runId, workflow.name, {});
 
-    const spy = jest.spyOn(StepExecutor, 'executeStep');
-
     // First call fails, Reflexion logic kicks in (calling mocked getAdapter),
     // then it retries with corrected command.
-    spy.mockImplementation(async (step, _context) => {
-      // Original failing command
-      // biome-ignore lint/suspicious/noExplicitAny: Accessing run property dynamically
-      if ((step as any).run === 'exit 1') {
+    spy.mockImplementation(async (step: any) => {
+      if (step.run === 'exit 1') {
         return { status: 'failed', output: null, error: 'Command failed' };
       }
 
-      // Corrected command from mock
-      // biome-ignore lint/suspicious/noExplicitAny: Accessing run property dynamically
-      if ((step as any).run === 'echo "fixed"') {
+      if (step.run === 'echo "fixed"') {
         return { status: 'success', output: 'fixed' };
       }
 
       return { status: 'failed', output: null, error: 'Unknown step' };
     });
 
-    // biome-ignore lint/suspicious/noExplicitAny: Accessing private property for testing
     await (runner as any).executeStepWithForeach(workflow.steps[0]);
 
     // Expectations:
@@ -78,10 +70,7 @@ describe('WorkflowRunner Reflexion', () => {
     expect(spy).toHaveBeenCalledTimes(2);
 
     // Verify the second call had the corrected command
-    // biome-ignore lint/suspicious/noExplicitAny: mock call args typing
     const secondCallArg = spy.mock.calls[1][0] as any;
     expect(secondCallArg.run).toBe('echo "fixed"');
-
-    spy.mockRestore();
   });
 });

package/src/runner/resource-pool.ts

@@ -1,3 +1,4 @@
+import { LIMITS } from '../utils/constants.ts';
 import type { Logger } from '../utils/logger.ts';
 
 export type ReleaseFunction = () => void;
@@ -19,6 +20,12 @@ interface QueuedRequest {
   timestamp: number;
 }
 
+/** Default maximum queue size to prevent unbounded memory growth */
+const DEFAULT_MAX_QUEUE_SIZE = 1000;
+
+/** Default resource pool limit */
+const DEFAULT_POOL_LIMIT = 10;
+
 export class ResourcePoolManager {
   private pools = new Map<
     string,
@@ -31,12 +38,14 @@ export class ResourcePoolManager {
     }
   >();
   private globalLimit: number;
+  private maxQueueSize: number;
 
   constructor(
     private logger: Logger,
-    options: { defaultLimit?: number; pools?: Record<string, number> } = {}
+    options: { defaultLimit?: number; maxQueueSize?: number; pools?: Record<string, number> } = {}
   ) {
-    this.globalLimit = options.defaultLimit || 10;
+    this.globalLimit = options.defaultLimit || DEFAULT_POOL_LIMIT;
+    this.maxQueueSize = options.maxQueueSize || DEFAULT_MAX_QUEUE_SIZE;
     if (options.pools) {
       for (const [name, limit] of Object.entries(options.pools)) {
         this.pools.set(name, { limit, active: 0, queue: [], totalAcquired: 0, totalWaitTimeMs: 0 });
@@ -47,11 +56,30 @@ export class ResourcePoolManager {
   /**
    * Acquire a resource from a pool.
    * If the pool doesn't exist, it uses the global limit.
+   *
+   * @param poolName - Name of the pool to acquire from
+   * @param options.priority - Higher priority requests are processed first (default: 0)
+   * @param options.signal - AbortSignal for cancellation
+   * @param options.timeout - Maximum time to wait for a slot (ms), rejects with timeout error if exceeded
    */
   async acquire(
     poolName: string,
-    options: { priority?: number; signal?: AbortSignal } = {}
+    options: { priority?: number; signal?: AbortSignal; timeout?: number } = {}
   ): Promise<ReleaseFunction> {
+    // Validate timeout parameter - must be positive, finite, and within max bounds
+    if (options.timeout !== undefined) {
+      if (
+        typeof options.timeout !== 'number' ||
+        !Number.isFinite(options.timeout) ||
+        options.timeout <= 0 ||
+        options.timeout > LIMITS.MAX_RESOURCE_POOL_TIMEOUT_MS
+      ) {
+        throw new Error(
+          `Invalid timeout value: ${options.timeout}. Timeout must be a positive number <= ${LIMITS.MAX_RESOURCE_POOL_TIMEOUT_MS}ms.`
+        );
+      }
+    }
+
     let pool = this.pools.get(poolName);
     if (!pool) {
       // Create a pool for this name if it doesn't exist, using global limit
@@ -71,6 +99,13 @@ export class ResourcePoolManager {
       return this.createReleaseFn(poolName);
     }
 
+    // Check queue size limit
+    if (pool.queue.length >= this.maxQueueSize) {
+      throw new Error(
+        `Resource pool "${poolName}" queue is full (${this.maxQueueSize}). Consider increasing concurrency limits or reducing parallel work.`
+      );
+    }
+
     // Queue the request
     const timestamp = Date.now();
     const poolRef = pool;
@@ -90,19 +125,63 @@ export class ResourcePoolManager {
         return a.timestamp - b.timestamp;
       });
 
+      // Handle timeout
+      let timeoutId: Timer | undefined;
+      if (options.timeout && options.timeout > 0) {
+        timeoutId = setTimeout(() => {
+          const index = poolRef.queue.indexOf(request);
+          if (index !== -1) {
+            poolRef.queue.splice(index, 1);
+            reject(
+              new Error(`Resource pool "${poolName}" acquire timeout after ${options.timeout}ms`)
+            );
+          }
+        }, options.timeout);
+      }
+
       // Handle abort signal
+      const cleanup = () => {
+        if (timeoutId) clearTimeout(timeoutId);
+      };
+
       if (options.signal) {
-        options.signal.addEventListener(
-          'abort',
-          () => {
-            const index = poolRef.queue.indexOf(request);
-            if (index !== -1) {
-              poolRef.queue.splice(index, 1);
-              reject(new Error('Acquisition aborted'));
-            }
-          },
-          { once: true }
-        );
+        const onAbort = () => {
+          cleanup();
+          const index = poolRef.queue.indexOf(request);
+          if (index !== -1) {
+            poolRef.queue.splice(index, 1);
+            reject(new Error('Acquisition aborted'));
+          }
+        };
+        options.signal.addEventListener('abort', onAbort, { once: true });
+
+        // Wrap accessors to remove listener
+        const originalResolve = resolve;
+        const originalReject = reject;
+
+        request.resolve = (release) => {
+          cleanup();
+          options.signal?.removeEventListener('abort', onAbort);
+          originalResolve(release);
+        };
+        request.reject = (err) => {
+          cleanup();
+          options.signal?.removeEventListener('abort', onAbort);
+          originalReject(err);
+        };
+      } else {
+        // Still need to wrap for timeout cleanup
+        const originalResolve = resolve;
+        const originalReject = reject;
+
+        request.resolve = (release) => {
+          cleanup();
+          originalResolve(release);
+        };
+        request.reject = (err) => {
+          cleanup();
+          originalReject(err);
+        };
       }
     });
   }
@@ -161,4 +240,13 @@ export class ResourcePoolManager {
       totalWaitTimeMs: pool.totalWaitTimeMs,
     }));
   }
+
+  /**
+   * Check if a pool has capacity for another task.
+   */
+  hasCapacity(poolName: string): boolean {
+    const pool = this.pools.get(poolName);
+    if (!pool) return true; // Global limit will be checked on acquire
+    return pool.active < pool.limit;
+  }
 }

package/src/runner/services/context-builder.ts

@@ -0,0 +1,144 @@
+import type { ExpressionContext } from '../../expression/evaluator.ts';
+import { ExpressionEvaluator } from '../../expression/evaluator.ts';
+import type { Workflow } from '../../parser/schema.ts';
+import type { Logger } from '../../utils/logger.ts';
+import type { WorkflowState } from '../workflow-state.ts';
+
+/**
+ * Service for building the expression context for workflow steps.
+ */
+export class ContextBuilder {
+  constructor(
+    private workflow: Workflow,
+    private inputs: Record<string, unknown>,
+    private secretValues: string[],
+    private state: WorkflowState,
+    private logger: Logger
+  ) {}
+
+  /**
+   * Builds the context object used for expression evaluation.
+   */
+  public buildContext(
+    secrets: Record<string, string>,
+    envOverrides: Record<string, string> = {},
+    memory: Record<string, unknown> = {},
+    lastFailedStep?: string,
+    item?: unknown,
+    index?: number
+  ): ExpressionContext {
+    const stepsContext: Record<
+      string,
+      {
+        output?: unknown;
+        outputs?: Record<string, unknown>;
+        status?: string;
+        error?: string;
+        items?: any[];
+      }
+    > = {};
+
+    for (const [stepId, ctx] of this.state.entries()) {
+      stepsContext[stepId] = {
+        output: ctx.output,
+        outputs: ctx.outputs,
+        status: ctx.status,
+        error: ctx.error,
+        ...(ctx && 'items' in ctx ? { items: (ctx as any).items } : {}),
+      };
+    }
+
+    const baseContext: ExpressionContext = {
+      inputs: this.inputs,
+      secrets: secrets,
+      secretValues: this.secretValues,
+      steps: stepsContext,
+      item,
+      index,
+      env: {},
+      envOverrides: envOverrides,
+      memory: memory,
+      output: item
+        ? undefined
+        : this.state.get(this.workflow.steps.find((s) => !s.foreach)?.id || '')?.output,
+      last_failed_step: lastFailedStep ? { id: lastFailedStep, error: '' } : undefined,
+    };
+
+    const resolvedEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        resolvedEnv[key] = value;
+      }
+    }
+
+    if (this.workflow.env) {
+      for (const [key, value] of Object.entries(this.workflow.env)) {
+        try {
+          resolvedEnv[key] = ExpressionEvaluator.evaluateString(value, {
+            ...baseContext,
+            env: resolvedEnv,
+          });
+        } catch (error) {
+          this.logger.warn(
+            `Warning: Failed to evaluate workflow env "${key}": ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+    }
+
+    baseContext.env = { ...resolvedEnv, ...envOverrides };
+    return baseContext;
+  }
+  /**
+   * Builds input object for a specific step.
+   */
+  public buildStepInputs(step: any, context: ExpressionContext): Record<string, unknown> {
+    const stripUndefined = (value: Record<string, unknown>) => {
+      const result: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(value)) {
+        if (val !== undefined) {
+          result[key] = val;
+        }
+      }
+      return result;
+    };
+
+    switch (step.type) {
+      case 'shell': {
+        let env: Record<string, string> | undefined;
+        if (step.env) {
+          env = {};
+          for (const [key, value] of Object.entries(step.env)) {
+            env[key] = ExpressionEvaluator.evaluateString(value as string, context);
+          }
+        }
+        return stripUndefined({
+          run: ExpressionEvaluator.evaluateString((step as any).run, context),
+          env,
+        });
+      }
+      case 'file': {
+        return stripUndefined({
+          path: ExpressionEvaluator.evaluateString((step as any).path, context),
+          content: (step as any).content
+            ? ExpressionEvaluator.evaluateString((step as any).content, context)
+            : undefined,
+          op: (step as any).op,
+        });
+      }
+      default: {
+        // For most steps, we just pass through properties which might contain expressions
+        const inputs: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(step)) {
+          if (key === 'id' || key === 'type' || key === 'if' || key === 'foreach') continue;
+          if (typeof value === 'string' && value.includes('{{')) {
+            inputs[key] = ExpressionEvaluator.evaluateString(value, context);
+          } else {
+            inputs[key] = value;
+          }
+        }
+        return stripUndefined(inputs);
+      }
+    }
+  }
+}

package/src/runner/services/secret-manager.ts

@@ -0,0 +1,105 @@
+import { RedactionBuffer, Redactor } from '../../utils/redactor';
+
+export class SecretManager {
+  private secretValues: string[] = [];
+  private redactor: Redactor;
+
+  constructor(private initialSecrets: Record<string, string> = {}) {
+    this.redactor = new Redactor(initialSecrets, { forcedSecrets: [] });
+  }
+
+  public static collectSecretValues(
+    value: unknown,
+    sink: Set<string>,
+    seen: WeakSet<object> = new WeakSet()
+  ): void {
+    if (value === null || value === undefined) return;
+
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      sink.add(String(value));
+      return;
+    }
+
+    if (typeof value !== 'object') return;
+
+    if (seen.has(value)) return;
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        SecretManager.collectSecretValues(item, sink, seen);
+      }
+      return;
+    }
+
+    for (const item of Object.values(value as Record<string, unknown>)) {
+      SecretManager.collectSecretValues(item, sink, seen);
+    }
+  }
+
+  public loadSecrets(optionsSecrets: Record<string, string> = {}): Record<string, string> {
+    const secrets: Record<string, string> = { ...this.initialSecrets, ...optionsSecrets };
+
+    // Strict allowlist for safe system environment variables
+    const safeSystemVars = ['PATH', 'HOME', 'PWD', 'SHELL', 'LANG', 'TZ'];
+    for (const key of safeSystemVars) {
+      const value = process.env[key];
+      if (value) {
+        secrets[key] = value;
+      }
+    }
+
+    // Include pattern-matched secrets from Bun.env (safe-ish way to get common secrets)
+    const secretPatterns = [/token/i, /key/i, /secret/i, /password/i, /auth/i, /api/i];
+    for (const [key, value] of Object.entries(Bun.env)) {
+      if (value && secretPatterns.some((p) => p.test(key))) {
+        // Skip common system non-secret variables that might match patterns
+        if (safeSystemVars.includes(key)) continue;
+        secrets[key] = value;
+      }
+    }
+
+    return secrets;
+  }
+
+  public getSecrets(optionsSecrets: Record<string, string> = {}): Record<string, string> {
+    return this.loadSecrets(optionsSecrets);
+  }
+
+  public getRedactor(): Redactor {
+    return this.redactor;
+  }
+
+  public setSecretValues(values: string[]): void {
+    this.secretValues = values;
+    this.redactor = new Redactor(this.initialSecrets, { forcedSecrets: this.secretValues });
+  }
+
+  public getSecretValues(): string[] {
+    return this.secretValues;
+  }
+
+  public redact(content: string): string {
+    return this.redactor.redact(content);
+  }
+
+  public createRedactionBuffer(): RedactionBuffer {
+    return new RedactionBuffer(this.redactor);
+  }
+  public redactAtRest = true;
+
+  /**
+   * Redact secrets from a value for storage (if enabled)
+   */
+  public redactForStorage<T>(value: T): T {
+    if (!this.redactAtRest) return value;
+    return this.redactor.redactValue(value) as T;
+  }
+
+  /**
+   * Redact secrets from a value
+   */
+  public redactValue<T>(value: T): T {
+    return this.redactor.redactValue(value) as T;
+  }
+}

package/src/runner/services/workflow-validator.ts

@@ -0,0 +1,131 @@
+import type { Workflow, WorkflowInput } from '../../parser/schema.ts';
+import { validateJsonSchema } from '../../utils/schema-validator.ts';
+import { SecretManager } from './secret-manager.ts';
+
+/**
+ * Service for validating workflow inputs and applying defaults.
+ */
+export class WorkflowValidator {
+  public static readonly REDACTED_PLACEHOLDER = '[REDACTED]';
+
+  constructor(
+    private workflow: Workflow,
+    private inputs: Record<string, unknown>
+  ) {}
+
+  /**
+   * Apply workflow defaults to inputs and validate types.
+   * Returns the set of secret values found in the inputs.
+   */
+  public applyDefaultsAndValidate(): { secretValues: string[] } {
+    if (!this.workflow.inputs) return { secretValues: [] };
+
+    const secretValues = new Set<string>();
+
+    for (const [key, config] of Object.entries(this.workflow.inputs)) {
+      const inputConfig = config as WorkflowInput;
+
+      // Apply default if missing
+      if (this.inputs[key] === undefined && inputConfig.default !== undefined) {
+        this.inputs[key] = inputConfig.default;
+      }
+
+      if (inputConfig.secret) {
+        if (this.inputs[key] === WorkflowValidator.REDACTED_PLACEHOLDER) {
+          throw new Error(
+            `Secret input "${key}" was redacted at rest. Please provide it again to resume this run.`
+          );
+        }
+      }
+
+      // Validate required inputs
+      if (this.inputs[key] === undefined) {
+        throw new Error(`Missing required input: ${key}`);
+      }
+
+      // Basic type validation
+      const value = this.inputs[key];
+      const type = inputConfig.type.toLowerCase();
+
+      if (type === 'string' && typeof value !== 'string') {
+        throw new Error(`Input "${key}" must be a string, got ${typeof value}`);
+      }
+      if (type === 'number' && typeof value !== 'number') {
+        throw new Error(`Input "${key}" must be a number, got ${typeof value}`);
+      }
+      if (type === 'boolean' && typeof value !== 'boolean') {
+        throw new Error(`Input "${key}" must be a boolean, got ${typeof value}`);
+      }
+      if (type === 'array' && !Array.isArray(value)) {
+        throw new Error(`Input "${key}" must be an array, got ${typeof value}`);
+      }
+      if (
+        type === 'object' &&
+        (typeof value !== 'object' || value === null || Array.isArray(value))
+      ) {
+        throw new Error(`Input "${key}" must be an object, got ${typeof value}`);
+      }
+
+      if (inputConfig.values) {
+        if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+          throw new Error(`Input "${key}" cannot use enum values with type "${type}"`);
+        }
+        for (const allowed of inputConfig.values) {
+          const matchesType =
+            (type === 'string' && typeof allowed === 'string') ||
+            (type === 'number' && typeof allowed === 'number') ||
+            (type === 'boolean' && typeof allowed === 'boolean');
+          if (!matchesType) {
+            throw new Error(
+              `Input "${key}" enum value ${JSON.stringify(allowed)} must be a ${type}`
+            );
+          }
+        }
+        if (!inputConfig.values.includes(value as string | number | boolean)) {
+          throw new Error(
+            `Input "${key}" must be one of: ${inputConfig.values.map((v) => JSON.stringify(v)).join(', ')}`
+          );
+        }
+      }
+
+      if (
+        inputConfig.secret &&
+        value !== undefined &&
+        value !== WorkflowValidator.REDACTED_PLACEHOLDER
+      ) {
+        SecretManager.collectSecretValues(value, secretValues, new WeakSet());
+      }
+    }
+
+    return { secretValues: Array.from(secretValues) };
+  }
+
+  /**
+   * Validate data against a JSON schema.
+   */
+  public validateSchema(
+    kind: 'input' | 'output',
+    schema: unknown,
+    data: unknown,
+    stepId: string
+  ): void {
+    try {
+      const result = validateJsonSchema(schema, data);
+      if (result.valid) return;
+      const details = result.errors.map((line: string) => `  - ${line}`).join('\n');
+      throw new Error(
+        `${kind === 'input' ? 'Input' : 'Output'} schema validation failed for step "${stepId}":\n${details}`
+      );
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes('schema validation failed for step')) {
+          throw error;
+        }
+        throw new Error(
+          `${kind === 'input' ? 'Input' : 'Output'} schema error for step "${stepId}": ${error.message}`
+        );
+      }
+      throw error;
+    }
+  }
+}