opencastle 0.11.0 → 0.12.0

package/src/cli/run/schema.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { parseYaml, parseTimeout, validateSpec, applyDefaults } from './schema.js'
+import { parseYaml, parseTimeout, validateSpec, applyDefaults, isConvoySpec } from './schema.js'
 
 // ── parseYaml ──────────────────────────────────────────────────
 
@@ -590,3 +590,464 @@ describe('applyDefaults — loop mode', () => {
     expect(spec.mode).toBe('loop')
   })
 })
+
+// ── validateSpec — version field ───────────────────────────────
+
+describe('validateSpec — version field', () => {
+  const validSpec = {
+    name: 'test-run',
+    tasks: [{ id: 'task-1', prompt: 'Do something' }],
+  }
+
+  it('accepts version 1', () => {
+    const result = validateSpec({ ...validSpec, version: 1 })
+    expect(result.valid).toBe(true)
+    expect(result.errors).toHaveLength(0)
+  })
+
+  it('rejects version 2', () => {
+    const result = validateSpec({ ...validSpec, version: 2 })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('version'))
+  })
+
+  it('rejects non-integer version', () => {
+    const result = validateSpec({ ...validSpec, version: 1.5 })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('version'))
+  })
+
+  it('rejects string version', () => {
+    const result = validateSpec({ ...validSpec, version: '1' })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('version'))
+  })
+
+  it('omitting version is valid (legacy spec)', () => {
+    const result = validateSpec(validSpec)
+    expect(result.valid).toBe(true)
+  })
+})
+
+// ── validateSpec — defaults block ──────────────────────────────
+
+describe('validateSpec — defaults block', () => {
+  const validSpec = {
+    name: 'test-run',
+    version: 1,
+    tasks: [{ id: 'task-1', prompt: 'Do something' }],
+  }
+
+  it('accepts a fully specified defaults block', () => {
+    const result = validateSpec({
+      ...validSpec,
+      defaults: { timeout: '10m', model: 'gpt-4', max_retries: 2, agent: 'developer' },
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  it('accepts partial defaults block', () => {
+    const result = validateSpec({ ...validSpec, defaults: { timeout: '5m' } })
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects defaults as a non-object', () => {
+    const result = validateSpec({ ...validSpec, defaults: 'invalid' })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('defaults'))
+  })
+
+  it('rejects defaults as an array', () => {
+    const result = validateSpec({ ...validSpec, defaults: ['timeout', '10m'] })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('defaults'))
+  })
+
+  it('rejects defaults with invalid timeout format', () => {
+    const result = validateSpec({ ...validSpec, defaults: { timeout: 'bad' } })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(
+      expect.stringContaining('defaults.timeout')
+    )
+  })
+
+  it('rejects defaults with non-string model', () => {
+    const result = validateSpec({ ...validSpec, defaults: { model: 42 } })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(
+      expect.stringContaining('defaults.model')
+    )
+  })
+
+  it('rejects defaults with negative max_retries', () => {
+    const result = validateSpec({ ...validSpec, defaults: { max_retries: -1 } })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(
+      expect.stringContaining('defaults.max_retries')
+    )
+  })
+
+  it('rejects defaults with non-integer max_retries', () => {
+    const result = validateSpec({ ...validSpec, defaults: { max_retries: 1.5 } })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(
+      expect.stringContaining('defaults.max_retries')
+    )
+  })
+
+  it('accepts defaults.max_retries of 0', () => {
+    const result = validateSpec({ ...validSpec, defaults: { max_retries: 0 } })
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects defaults with non-string agent', () => {
+    const result = validateSpec({ ...validSpec, defaults: { agent: 99 } })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(
+      expect.stringContaining('defaults.agent')
+    )
+  })
+})
+
+// ── validateSpec — gates field ─────────────────────────────────
+
+describe('validateSpec — gates field', () => {
+  const validSpec = {
+    name: 'test-run',
+    tasks: [{ id: 'task-1', prompt: 'Do something' }],
+  }
+
+  it('accepts a valid gates array', () => {
+    const result = validateSpec({
+      ...validSpec,
+      gates: ['npm test', 'npx tsc --noEmit'],
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  it('accepts an empty gates array', () => {
+    const result = validateSpec({ ...validSpec, gates: [] })
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects gates as a string', () => {
+    const result = validateSpec({ ...validSpec, gates: 'npm test' })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('gates'))
+  })
+
+  it('rejects gates with non-string items', () => {
+    const result = validateSpec({ ...validSpec, gates: ['npm test', 42] })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('gates'))
+  })
+})
+
+// ── validateSpec — branch field ────────────────────────────────
+
+describe('validateSpec — branch field', () => {
+  const validSpec = {
+    name: 'test-run',
+    tasks: [{ id: 'task-1', prompt: 'Do something' }],
+  }
+
+  it('accepts a valid branch string', () => {
+    const result = validateSpec({ ...validSpec, branch: 'feat/my-feature' })
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects non-string branch', () => {
+    const result = validateSpec({ ...validSpec, branch: 123 })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('branch'))
+  })
+
+  it('rejects boolean branch', () => {
+    const result = validateSpec({ ...validSpec, branch: true })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('branch'))
+  })
+})
+
+// ── validateSpec — per-task model and max_retries ──────────────
+
+describe('validateSpec — per-task model and max_retries', () => {
+  it('accepts valid task model string', () => {
+    const result = validateSpec({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', model: 'claude-3.5-sonnet' }],
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects non-string task model', () => {
+    const result = validateSpec({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', model: 123 }],
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('model'))
+  })
+
+  it('accepts valid task max_retries', () => {
+    const result = validateSpec({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', max_retries: 3 }],
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  it('accepts zero max_retries', () => {
+    const result = validateSpec({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', max_retries: 0 }],
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  it('rejects negative max_retries', () => {
+    const result = validateSpec({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', max_retries: -1 }],
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('max_retries'))
+  })
+
+  it('rejects non-integer max_retries', () => {
+    const result = validateSpec({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', max_retries: 1.5 }],
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors).toContainEqual(expect.stringContaining('max_retries'))
+  })
+})
+
+// ── isConvoySpec ───────────────────────────────────────────────
+
+describe('isConvoySpec', () => {
+  it('returns true for version 1 spec', () => {
+    expect(
+      isConvoySpec({ name: 'test', version: 1, tasks: [{ id: 'a', prompt: 'x' }] })
+    ).toBe(true)
+  })
+
+  it('returns false for legacy spec without version', () => {
+    expect(
+      isConvoySpec({ name: 'test', tasks: [{ id: 'a', prompt: 'x' }] })
+    ).toBe(false)
+  })
+
+  it('returns false for version 2', () => {
+    expect(isConvoySpec({ name: 'test', version: 2 })).toBe(false)
+  })
+
+  it('returns false for null input', () => {
+    expect(isConvoySpec(null)).toBe(false)
+  })
+
+  it('returns false for non-object input', () => {
+    expect(isConvoySpec('string')).toBe(false)
+  })
+
+  it('returns false for undefined', () => {
+    expect(isConvoySpec(undefined)).toBe(false)
+  })
+})
+
+// ── applyDefaults — convoy spec (version: 1) ───────────────────
+
+describe('applyDefaults — convoy spec (version: 1)', () => {
+  it('merges defaults.agent into tasks when not specified', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { agent: 'ui-ux-expert' },
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].agent).toBe('ui-ux-expert')
+  })
+
+  it('task-level agent overrides default', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { agent: 'ui-ux-expert' },
+      tasks: [{ id: 'a', prompt: 'x', agent: 'api-designer' }],
+    })
+    expect(spec.tasks![0].agent).toBe('api-designer')
+  })
+
+  it('merges defaults.timeout into tasks', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { timeout: '15m' },
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].timeout).toBe('15m')
+  })
+
+  it('task-level timeout overrides defaults.timeout', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { timeout: '15m' },
+      tasks: [{ id: 'a', prompt: 'x', timeout: '5m' }],
+    })
+    expect(spec.tasks![0].timeout).toBe('5m')
+  })
+
+  it('merges defaults.model into tasks', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { model: 'gpt-4' },
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].model).toBe('gpt-4')
+  })
+
+  it('task-level model overrides defaults.model', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { model: 'gpt-4' },
+      tasks: [{ id: 'a', prompt: 'x', model: 'claude-3.5-sonnet' }],
+    })
+    expect(spec.tasks![0].model).toBe('claude-3.5-sonnet')
+  })
+
+  it('no model set when no defaults.model and no task model', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].model).toBeUndefined()
+  })
+
+  it('merges defaults.max_retries into tasks', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { max_retries: 3 },
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].max_retries).toBe(3)
+  })
+
+  it('task-level max_retries overrides defaults.max_retries', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { max_retries: 3 },
+      tasks: [{ id: 'a', prompt: 'x', max_retries: 0 }],
+    })
+    expect(spec.tasks![0].max_retries).toBe(0)
+  })
+
+  it('propagates version and defaults fields through to spec', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      defaults: { model: 'gpt-4' },
+      gates: ['npm test'],
+      branch: 'feat/convoy',
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.version).toBe(1)
+    expect(spec.gates).toEqual(['npm test'])
+    expect(spec.branch).toBe('feat/convoy')
+  })
+})
+
+// ── applyDefaults — max_retries default always applied ─────────
+
+describe('applyDefaults — max_retries always applied', () => {
+  it('applies max_retries default of 1 for legacy spec', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].max_retries).toBe(1)
+  })
+
+  it('applies max_retries default of 1 when version:1 has no defaults block', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      version: 1,
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    expect(spec.tasks![0].max_retries).toBe(1)
+  })
+
+  it('preserves explicit task max_retries in legacy spec', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x', max_retries: 5 }],
+    })
+    expect(spec.tasks![0].max_retries).toBe(5)
+  })
+})
+
+// ── backward compatibility ─────────────────────────────────────
+
+describe('backward compatibility — legacy specs', () => {
+  it('legacy spec validates identically without version field', () => {
+    const result = validateSpec({
+      name: 'test-run',
+      tasks: [
+        { id: 'task-1', prompt: 'Do something' },
+        { id: 'task-2', prompt: 'Do another thing', depends_on: ['task-1'] },
+      ],
+    })
+    expect(result.valid).toBe(true)
+    expect(result.errors).toHaveLength(0)
+  })
+
+  it('legacy spec applyDefaults produces same agent/timeout/depends_on/files as before', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    const task = spec.tasks![0]
+    expect(task.agent).toBe('developer')
+    expect(task.timeout).toBe('30m')
+    expect(task.depends_on).toEqual([])
+    expect(task.files).toEqual([])
+  })
+
+  it('user-specified legacy task values are preserved', () => {
+    const spec = applyDefaults({
+      name: 'test',
+      tasks: [{
+        id: 'a',
+        prompt: 'x',
+        agent: 'ui-ux-expert',
+        timeout: '5m',
+        depends_on: ['b'],
+        files: ['src/'],
+      }],
+    })
+    const task = spec.tasks![0]
+    expect(task.agent).toBe('ui-ux-expert')
+    expect(task.timeout).toBe('5m')
+    expect(task.depends_on).toEqual(['b'])
+    expect(task.files).toEqual(['src/'])
+  })
+
+  it('defaults block is ignored without version:1', () => {
+    // Without version:1, the defaults block should not be merged
+    const spec = applyDefaults({
+      name: 'test',
+      defaults: { agent: 'ui-ux-expert', model: 'gpt-4' },
+      tasks: [{ id: 'a', prompt: 'x' }],
+    })
+    // agent falls back to hardcoded 'developer', not defaults.agent
+    expect(spec.tasks![0].agent).toBe('developer')
+    // model is not set
+    expect(spec.tasks![0].model).toBeUndefined()
+  })
+})

package/src/cli/run/schema.ts

@@ -41,6 +41,10 @@ interface RawSpec {
   tasks?: unknown
   mode?: unknown
   loop?: unknown
+  version?: unknown
+  defaults?: unknown
+  gates?: unknown
+  branch?: unknown
 }
 
 interface RawTask {
@@ -51,6 +55,8 @@ interface RawTask {
   depends_on?: unknown
   files?: unknown
   description?: unknown
+  model?: unknown
+  max_retries?: unknown
 }
 
 /**
@@ -92,6 +98,54 @@ export function validateSpec(spec: unknown): ValidationResult {
     errors.push('`adapter` must be a string')
   }
 
+  // version
+  if (s.version !== undefined) {
+    if (typeof s.version !== 'number' || !Number.isInteger(s.version) || s.version !== 1) {
+      errors.push('`version` must be 1')
+    }
+  }
+
+  // defaults
+  if (s.defaults !== undefined) {
+    if (!s.defaults || typeof s.defaults !== 'object' || Array.isArray(s.defaults)) {
+      errors.push('`defaults` must be an object')
+    } else {
+      const d = s.defaults as Record<string, unknown>
+      if (d.timeout !== undefined && isNaN(parseTimeout(d.timeout as string))) {
+        errors.push(
+          '`defaults.timeout` must be in format: <number><s|m|h> (e.g. "10m")'
+        )
+      }
+      if (d.model !== undefined && typeof d.model !== 'string') {
+        errors.push('`defaults.model` must be a string')
+      }
+      if (d.max_retries !== undefined) {
+        const mr = Number(d.max_retries)
+        if (!Number.isInteger(mr) || mr < 0) {
+          errors.push('`defaults.max_retries` must be a non-negative integer')
+        }
+      }
+      if (d.agent !== undefined && typeof d.agent !== 'string') {
+        errors.push('`defaults.agent` must be a string')
+      }
+    }
+  }
+
+  // gates
+  if (s.gates !== undefined) {
+    if (
+      !Array.isArray(s.gates) ||
+      !(s.gates as unknown[]).every((g) => typeof g === 'string')
+    ) {
+      errors.push('`gates` must be an array of strings')
+    }
+  }
+
+  // branch
+  if (s.branch !== undefined && typeof s.branch !== 'string') {
+    errors.push('`branch` must be a string')
+  }
+
   // mode
   const mode = s.mode !== undefined ? s.mode : 'tasks'
   if (mode !== 'tasks' && mode !== 'loop') {
@@ -196,6 +250,21 @@ export function validateSpec(spec: unknown): ValidationResult {
       if (task.files !== undefined && !Array.isArray(task.files)) {
         errors.push(`${prefix}: \`files\` must be an array`)
       }
+
+      // model
+      if (task.model !== undefined && typeof task.model !== 'string') {
+        errors.push(`${prefix}: \`model\` must be a string`)
+      }
+
+      // max_retries
+      if (task.max_retries !== undefined) {
+        const mr = Number(task.max_retries)
+        if (!Number.isInteger(mr) || mr < 0) {
+          errors.push(
+            `${prefix}: \`max_retries\` must be a non-negative integer`
+          )
+        }
+      }
     }
 
     // DAG cycle detection
@@ -271,18 +340,43 @@ export function applyDefaults(spec: Record<string, unknown>): TaskSpec {
     s.loop = loop
   } else {
     const tasks = s.tasks as Array<Record<string, unknown>>
+    const d =
+      s.version === 1 && s.defaults
+        ? (s.defaults as Record<string, unknown>)
+        : {}
     for (const task of tasks) {
-      task.agent = (task.agent as string) || 'developer'
-      task.timeout = (task.timeout as string) || '30m'
+      task.agent =
+        (task.agent as string) || (d.agent as string | undefined) || 'developer'
+      task.timeout =
+        (task.timeout as string) ||
+        (d.timeout as string | undefined) ||
+        '30m'
       task.depends_on = (task.depends_on as string[]) || []
       task.files = (task.files as string[]) || []
       task.description = (task.description as string) || (task.id as string)
+      // model: task-level overrides defaults (no hardcoded fallback)
+      if (task.model === undefined && d.model !== undefined) {
+        task.model = d.model
+      }
+      // max_retries: task-level overrides defaults, fallback to 1
+      if (task.max_retries === undefined) {
+        task.max_retries =
+          d.max_retries !== undefined ? Number(d.max_retries) : 1
+      }
     }
   }
 
   return s as unknown as TaskSpec
 }
 
+/**
+ * Returns true if the spec uses the Convoy Engine enhanced format (version: 1).
+ */
+export function isConvoySpec(spec: unknown): boolean {
+  if (!spec || typeof spec !== 'object') return false
+  return (spec as Record<string, unknown>).version === 1
+}
+
 /**
  * Read, parse, validate, and return a typed task spec from a YAML file.
  * @throws If file cannot be read, parsed, or spec is invalid

package/src/cli/types.ts

@@ -126,6 +126,14 @@ export const IDE_LABELS: Record<IdeChoice, string> = {
 
 // ── Run command types ──────────────────────────────────────────
 
+/** Default values merged into each task for Convoy Engine (version: 1) specs. */
+export interface TaskDefaults {
+  timeout?: string;
+  model?: string;
+  max_retries?: number;
+  agent?: string;
+}
+
 /** Loop execution configuration. */
 export interface LoopConfig {
   /** Maximum number of agent iterations (default 20). */
@@ -152,6 +160,14 @@ export interface TaskSpec {
   mode?: 'tasks' | 'loop';
   loop?: LoopConfig;
   _verbose?: boolean;
+  /** Spec schema version (1 for Convoy Engine format). */
+  version?: number;
+  /** Worker defaults merged into each task (Convoy Engine). */
+  defaults?: TaskDefaults;
+  /** Shell commands run after all tasks complete; each must exit 0. */
+  gates?: string[];
+  /** Git feature branch name. */
+  branch?: string;
 }
 
 /** A single task in the spec. */
@@ -164,6 +180,10 @@ export interface Task {
   files: string[];
   description: string;
   _process?: ChildProcess;
+  /** Model override for this task. */
+  model?: string;
+  /** Max retry attempts (default: 1). */
+  max_retries: number;
 }
 
 /** Task execution status. */

package/src/dashboard/node_modules/.vite/deps/_metadata.json

@@ -1,25 +1,25 @@
 {
-  "hash": "87401706",
+  "hash": "7398c476",
   "configHash": "30f8ea04",
-  "lockfileHash": "56be8082",
-  "browserHash": "8ccc6e37",
+  "lockfileHash": "35ec1b3d",
+  "browserHash": "6a8b9ff7",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "7e157996",
+      "fileHash": "ca3e0c44",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "021f979d",
+      "fileHash": "9cd2129a",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "f1a04609",
+      "fileHash": "cba29d71",
       "needsInterop": true
     }
   },