feat(orchestrator): enqueue_task, complete_task, read_handoffs tools with guards

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gewenyu99

src/lib/programs/orchestrator/__tests__/queue-tools.test.ts

@@ -0,0 +1,164 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { QueueStore, type QueuedTask } from '@lib/programs/orchestrator/queue';
+import {
+  applyComplete,
+  applyEnqueue,
+  applyReadHandoffs,
+  checkEnqueueGuards,
+  type OrchestratorToolsContext,
+} from '@lib/programs/orchestrator/queue-tools';
+
+function tmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'queue-tools-test-'));
+}
+
+const VALID = ['install', 'init', 'capture'];
+
+describe('checkEnqueueGuards', () => {
+  let dir: string;
+  let store: QueueStore;
+  let ctx: OrchestratorToolsContext;
+
+  beforeEach(() => {
+    dir = tmpDir();
+    store = new QueueStore(dir, 'run-1');
+    ctx = {
+      store,
+      validTypes: VALID,
+      getCurrentTaskId: () => undefined,
+      limits: { maxTasks: 3, maxDepth: 2, maxPerType: 1 },
+    };
+  });
+
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  it('rejects an unknown type', () => {
+    const r = checkEnqueueGuards(ctx, { type: 'nope', reason: 'x' }, undefined);
+    expect(r).toMatchObject({ ok: false, guard: 'unknown-type' });
+  });
+
+  it('rejects an unknown dependency', () => {
+    const r = checkEnqueueGuards(
+      ctx,
+      { type: 'init', dependsOn: ['ghost'], reason: 'x' },
+      undefined,
+    );
+    expect(r).toMatchObject({ ok: false, guard: 'unknown-dep' });
+  });
+
+  it('trips the depth guard past maxDepth', () => {
+    const parent = { depth: 2 } as QueuedTask;
+    const r = checkEnqueueGuards(ctx, { type: 'init', reason: 'x' }, parent);
+    expect(r).toMatchObject({ ok: false, guard: 'depth' });
+  });
+
+  it('trips dedup on the same type and inputs', async () => {
+    await store.enqueue({ type: 'install', inputs: { pkg: 'posthog-js' } });
+    const r = checkEnqueueGuards(
+      ctx,
+      { type: 'install', inputs: { pkg: 'posthog-js' }, reason: 'x' },
+      undefined,
+    );
+    expect(r).toMatchObject({ ok: false, guard: 'dedup' });
+  });
+
+  it('trips the per-type cap', async () => {
+    await store.enqueue({ type: 'capture', inputs: { a: 1 } });
+    const r = checkEnqueueGuards(
+      ctx,
+      { type: 'capture', inputs: { a: 2 }, reason: 'x' },
+      undefined,
+    );
+    expect(r).toMatchObject({ ok: false, guard: 'per-type' });
+  });
+
+  it('trips the total budget', async () => {
+    await store.enqueue({ type: 'install' });
+    await store.enqueue({ type: 'init' });
+    await store.enqueue({ type: 'capture' });
+    const r = checkEnqueueGuards(ctx, { type: 'init', reason: 'x' }, undefined);
+    expect(r).toMatchObject({ ok: false, guard: 'budget' });
+  });
+
+  it('allows a valid enqueue', () => {
+    const r = checkEnqueueGuards(ctx, { type: 'init', reason: 'x' }, undefined);
+    expect(r).toEqual({ ok: true });
+  });
+});
+
+describe('apply functions', () => {
+  let dir: string;
+  let store: QueueStore;
+  let currentId: string | undefined;
+  let ctx: OrchestratorToolsContext;
+
+  beforeEach(() => {
+    dir = tmpDir();
+    store = new QueueStore(dir, 'run-1');
+    currentId = undefined;
+    ctx = {
+      store,
+      validTypes: VALID,
+      getCurrentTaskId: () => currentId,
+    };
+  });
+
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  it('seeds at depth 0 by the orchestrator', async () => {
+    const r = await applyEnqueue(ctx, { type: 'install', reason: 'seed' });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.task.depth).toBe(0);
+    expect(r.task.enqueuedBy).toBe('orchestrator');
+  });
+
+  it('enqueues a child one level deeper, attributed to the running task', async () => {
+    const parent = await store.enqueue({ type: 'init' });
+    currentId = parent.id;
+    const r = await applyEnqueue(ctx, { type: 'capture', reason: 'follow-up' });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.task.depth).toBe(parent.depth + 1);
+    expect(r.task.enqueuedBy).toBe(parent.id);
+  });
+
+  it('complete_task fails when no task is running', async () => {
+    const r = await applyComplete(ctx, {
+      status: 'done',
+      handoff: { goals: 'g', did: 'd', forNextAgent: 'n' },
+    });
+    expect(r.ok).toBe(false);
+  });
+
+  it('complete_task marks the running task done and stores the handoff', async () => {
+    const t = await store.enqueue({ type: 'install' });
+    currentId = t.id;
+    await store.start(t.id);
+    const r = await applyComplete(ctx, {
+      status: 'done',
+      handoff: { goals: 'g', did: 'added sdk', forNextAgent: 'env next' },
+    });
+    expect(r.ok).toBe(true);
+    expect(store.get(t.id)?.status).toBe('done');
+    expect(store.readHandoff(t.id)?.did).toBe('added sdk');
+  });
+
+  it('read_handoffs returns a dependency handoff for the running task', async () => {
+    const dep = await store.enqueue({ type: 'install' });
+    await store.start(dep.id);
+    await store.complete(dep.id, {
+      goals: 'g',
+      did: 'installed',
+      forNextAgent: 'now init',
+    });
+    const t = await store.enqueue({ type: 'init', dependsOn: [dep.id] });
+    currentId = t.id;
+
+    const handoffs = applyReadHandoffs(ctx, {});
+    expect(handoffs).toHaveLength(1);
+    expect(handoffs[0].did).toBe('installed');
+  });
+});