@namzu/sdk 0.6.0 → 1.1.0

package/dist/tools/coordinator/__tests__/task-list.test.js

@@ -0,0 +1,162 @@
+/**
+ * Behavioural contract for the `agent_task_list` coordinator tool:
+ *
+ * - Returns every task the gateway knows about, with state + timing.
+ * - Filters by state when the input narrows it.
+ * - Emits a per-state summary in the data payload — what the supervisor
+ *   reads to decide "done vs not done" before calling verify_outputs.
+ * - Distinct from the plan-task store's `task_list` (subject/blockedBy);
+ *   listing them under different names avoids ToolRegistry collisions when
+ *   both surfaces are wired into the same agent.
+ */
+import { describe, expect, it } from 'vitest';
+import { buildCoordinatorTools } from '../index.js';
+function makeContext() {
+    return {
+        runId: 'run_test',
+        workingDirectory: '/tmp/test',
+        abortSignal: new AbortController().signal,
+        env: {},
+        log: () => { },
+    };
+}
+function gatewayWith(handles) {
+    return {
+        async createTask() {
+            throw new Error('not used');
+        },
+        async waitForTask() {
+            throw new Error('not used');
+        },
+        async continueTask() { },
+        cancelTask() { },
+        getTask(id) {
+            return handles.find((h) => h.taskId === id);
+        },
+        listTasks() {
+            return handles;
+        },
+        onTaskCompleted() {
+            return () => { };
+        },
+    };
+}
+function handle(input) {
+    return {
+        taskId: input.id,
+        agentId: input.agentId,
+        state: input.state,
+        createdAt: input.createdAt,
+        completedAt: input.completedAt,
+        result: input.lastError
+            ? {
+                runId: 'run_x',
+                status: input.state === 'failed' ? 'failed' : 'completed',
+                usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+                cost: { inputCostUsd: 0, outputCostUsd: 0, totalCostUsd: 0 },
+                iterations: 1,
+                durationMs: 0,
+                messages: [],
+                result: '',
+                lastError: input.lastError,
+            }
+            : undefined,
+    };
+}
+function findAgentTaskList(gateway) {
+    const tools = buildCoordinatorTools({
+        gateway,
+        workingDirectory: '/tmp/test',
+        allowedAgentIds: ['solution-architecture', 'enterprise-architecture'],
+    });
+    const t = tools.find((tool) => tool.name === 'agent_task_list');
+    if (!t)
+        throw new Error('agent_task_list tool missing from coordinator builder');
+    return t;
+}
+describe('coordinator agent_task_list tool', () => {
+    it('lists every task with state, agent, and timing', async () => {
+        const gateway = gatewayWith([
+            handle({
+                id: 'task_a',
+                agentId: 'solution-architecture',
+                state: 'completed',
+                createdAt: 0,
+                completedAt: 5000,
+            }),
+            handle({
+                id: 'task_b',
+                agentId: 'enterprise-architecture',
+                state: 'running',
+                createdAt: 1000,
+            }),
+            handle({
+                id: 'task_c',
+                agentId: 'solution-architecture',
+                state: 'failed',
+                createdAt: 2000,
+                completedAt: 4000,
+                lastError: 'bash exit 1',
+            }),
+        ]);
+        const tool = findAgentTaskList(gateway);
+        const result = await tool.execute({}, makeContext());
+        expect(result.success).toBe(true);
+        expect(result.output).toMatch(/Tasks: 3 total/);
+        expect(result.output).toMatch(/1 running/);
+        expect(result.output).toMatch(/1 completed/);
+        expect(result.output).toMatch(/1 failed/);
+        expect(result.output).toMatch(/task_a → solution-architecture \[completed\]/);
+        expect(result.output).toMatch(/task_c .* error: bash exit 1/);
+        const data = result.data;
+        expect(data.summary.total).toBe(3);
+        expect(data.items).toHaveLength(3);
+    });
+    it('filters by state', async () => {
+        const gateway = gatewayWith([
+            handle({
+                id: 'task_a',
+                agentId: 'solution-architecture',
+                state: 'completed',
+                createdAt: 0,
+                completedAt: 5000,
+            }),
+            handle({
+                id: 'task_b',
+                agentId: 'enterprise-architecture',
+                state: 'running',
+                createdAt: 1000,
+            }),
+        ]);
+        const tool = findAgentTaskList(gateway);
+        const result = await tool.execute({ state: 'running' }, makeContext());
+        expect(result.success).toBe(true);
+        const data = result.data;
+        expect(data.items).toHaveLength(1);
+        expect(data.items[0]?.task_id).toBe('task_b');
+        expect(result.output).not.toMatch(/task_a/);
+    });
+    it('handles an empty gateway', async () => {
+        const tool = findAgentTaskList(gatewayWith([]));
+        const result = await tool.execute({}, makeContext());
+        expect(result.success).toBe(true);
+        expect(result.output).toMatch(/Tasks: 0 total/);
+        expect(result.output).toMatch(/no tasks launched yet/);
+    });
+    it('does not collide with the plan-task store `task_list` tool name', async () => {
+        // Regression: an earlier cut registered the agent-task gateway
+        // inspector under the same `task_list` name as the plan-task store
+        // list tool, which would shadow one of them in any agent that wired
+        // both surfaces together. The agent inspector now lives under
+        // `agent_task_list`; this test guards the rename.
+        const coordinatorTools = buildCoordinatorTools({
+            gateway: gatewayWith([]),
+            workingDirectory: '/tmp/test',
+            allowedAgentIds: ['solution-architecture'],
+        });
+        const names = coordinatorTools.map((t) => t.name);
+        expect(names).toContain('agent_task_list');
+        expect(names).not.toContain('task_list');
+    });
+});
+//# sourceMappingURL=task-list.test.js.map

package/dist/tools/coordinator/__tests__/task-list.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-list.test.js","sourceRoot":"","sources":["../../../../src/tools/coordinator/__tests__/task-list.test.ts"],"names":[],"mappings":"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"}

package/dist/tools/coordinator/agent.d.ts

@@ -0,0 +1,34 @@
+import type { AgentRuntimeContext } from '../../types/agent/base.js';
+import type { TaskGateway } from '../../types/agent/gateway.js';
+import type { ToolDefinition } from '../../types/tool/index.js';
+import type { TaskLaunchedCallback } from './index.js';
+/**
+ * Build the canonical Claude Code `Agent` tool — synchronous subagent
+ * delegation that mirrors what Claude is trained against in
+ * `code.claude.com/docs/en/sub-agents`.
+ *
+ * Semantics: parent calls `Agent({ description, prompt, subagent_type })`,
+ * the runtime spawns the chosen subagent with its own context window,
+ * the parent's tool call BLOCKS until the subagent finishes, and the
+ * subagent's final text comes back as the tool result. Intermediate
+ * subagent tool calls are isolated — only the summary surfaces to
+ * the parent.
+ *
+ * This is **NOT** the same shape as the legacy `create_task` /
+ * `continue_task` / `cancel_task` trio that this package ships
+ * alongside it: those are non-blocking and use a `<task-notification>`
+ * callback model. The async pattern is useful for hosts that want a
+ * work-queue surface, but it is not what Claude Code trained against.
+ * For free agentic alignment, prefer the canonical `Agent` tool; keep
+ * the legacy coordinator tools only when you genuinely need
+ * fire-and-forget multi-task fan-out.
+ */
+export interface AgentToolOptions {
+    gateway: TaskGateway;
+    workingDirectory: string;
+    runtimeContext?: AgentRuntimeContext;
+    allowedAgentIds: string[];
+    onTaskLaunched?: TaskLaunchedCallback;
+}
+export declare function buildAgentTool(opts: AgentToolOptions): ToolDefinition;
+//# sourceMappingURL=agent.d.ts.map

package/dist/tools/coordinator/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/tools/coordinator/agent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAG/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,WAAW,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAA;IACpC,eAAe,EAAE,MAAM,EAAE,CAAA;IAEzB,cAAc,CAAC,EAAE,oBAAoB,CAAA;CACrC;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CAqHrE"}

package/dist/tools/coordinator/agent.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { defineTool } from '../defineTool.js';
+export function buildAgentTool(opts) {
+    const { gateway, allowedAgentIds: agentIds, onTaskLaunched } = opts;
+    const cwd = opts.workingDirectory;
+    const subagentTypeEnum = agentIds.length > 0 ? z.enum(agentIds) : z.string();
+    return defineTool({
+        name: 'Agent',
+        description: `Delegate a task to a specialized subagent. BLOCKING: returns when the subagent has finished, with the subagent's final text as the tool result. The subagent runs in its own context window and cannot see your conversation — include all necessary context in the prompt. Available subagents: ${agentIds.join(', ')}. To run multiple subagents in parallel, call this tool multiple times in a single response.`,
+        inputSchema: z.object({
+            description: z.string().describe('Short label for tracking (shown to the user)'),
+            prompt: z
+                .string()
+                .describe('Self-contained task description with all context the subagent needs'),
+            subagent_type: agentIds.length === 1
+                ? subagentTypeEnum
+                    .optional()
+                    .describe(`Which subagent to run (defaults to the only one: ${agentIds[0]})`)
+                : subagentTypeEnum.describe('Which subagent to run'),
+        }),
+        category: 'custom',
+        permissions: [],
+        readOnly: false,
+        destructive: false,
+        concurrencySafe: true,
+        async execute({ description, prompt, subagent_type }, context) {
+            // With a single registered subagent the type is optional — default to
+            // it so the model can't trip the "subagent_type required" validation.
+            const agentId = subagent_type ?? (agentIds.length === 1 ? agentIds[0] : undefined);
+            if (!agentId) {
+                return {
+                    success: false,
+                    output: '',
+                    error: `subagent_type is required — choose one of: ${agentIds.join(', ')}`,
+                };
+            }
+            const handle = await gateway.createTask({
+                agentId,
+                prompt,
+                workingDirectory: cwd,
+                runtimeContext: opts.runtimeContext,
+            });
+            onTaskLaunched?.(handle.taskId, {
+                agentId,
+                description,
+                // Same canonical-envelope plumbing as coordinator/index.ts
+                // (ses_009-task-notification-envelope). For Agent-tool path
+                // the subagent run is awaited synchronously below, so this
+                // id is only used if a probe / hook unexpectedly forks the
+                // completion to the background notification channel.
+                originalToolUseId: context.toolUseId,
+            });
+            const completed = await gateway.waitForTask(handle.taskId);
+            // Two layers can disagree on whether the subagent succeeded:
+            //
+            // 1. `TaskHandle.state` — the gateway's terminal task state.
+            //    Some gateways (e.g. vandal's) explicitly map
+            //    `result.status !== 'completed'` to `state = 'failed'`,
+            //    others (e.g. SDK's `LocalTaskGateway`) just forward
+            //    whatever the AgentManager set, which does not always
+            //    reflect run-level failure.
+            // 2. `BaseAgentResult.status` — the run's own status. The
+            //    canonical source of truth for whether the agent actually
+            //    finished its work; `lastError` carries the failure
+            //    message when set.
+            //
+            // Treat the subagent as successful only when BOTH agree.
+            // Reporting a failed subagent as successful would silently
+            // hand the parent garbage output and make debugging
+            // impossible, which is what Codex flagged on the first cut.
+            const runStatus = completed.result?.status;
+            const succeeded = completed.state === 'completed' && (runStatus === undefined || runStatus === 'completed');
+            const resultText = typeof completed.result?.result === 'string'
+                ? completed.result.result
+                : completed.result?.result !== undefined
+                    ? JSON.stringify(completed.result.result)
+                    : '';
+            if (!succeeded) {
+                const failureLabel = completed.state !== 'completed' ? completed.state : (runStatus ?? 'failed');
+                const detail = completed.result?.lastError ?? resultText ?? '(subagent provided no failure detail)';
+                return {
+                    success: false,
+                    output: '',
+                    error: `Subagent ${agentId} ${failureLabel}: ${detail}`,
+                    data: {
+                        task_id: handle.taskId,
+                        subagent_type: agentId,
+                        state: completed.state,
+                        status: runStatus,
+                        lastError: completed.result?.lastError,
+                    },
+                };
+            }
+            return {
+                success: true,
+                output: resultText || '(subagent returned no text)',
+                data: {
+                    task_id: handle.taskId,
+                    subagent_type: agentId,
+                    state: completed.state,
+                    status: runStatus,
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=agent.js.map

package/dist/tools/coordinator/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/tools/coordinator/agent.ts"],"names":[],"mappings":"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"}

package/dist/tools/coordinator/index.d.ts

@@ -1,6 +1,7 @@
 import type { PlanManager } from '../../manager/plan/lifecycle.js';
 import type { AgentRuntimeContext } from '../../types/agent/base.js';
 import type { TaskGateway } from '../../types/agent/gateway.js';
+import type { ResumeHandler } from '../../types/hitl/index.js';
 import type { RunId, TaskId } from '../../types/ids/index.js';
 import type { TaskStore } from '../../types/task/index.js';
 import type { ToolDefinition } from '../../types/tool/index.js';
@@ -8,6 +9,13 @@ export type TaskLaunchedCallback = (agentTaskId: TaskId, meta: {
     agentId: string;
     description: string;
     planTaskId?: string;
+    /**
+     * The assistant `tool_use_id` that dispatched this task.
+     * Threaded from `ToolContext.toolUseId` so the runtime can
+     * later emit a canonical `tool_result` content block bound
+     * to the same id when the background task completes.
+     */
+    originalToolUseId?: string;
 }) => void;
 export interface CoordinatorToolsOptions {
     gateway: TaskGateway;
@@ -18,6 +26,13 @@ export interface CoordinatorToolsOptions {
     runId?: RunId;
     getPlanManager?: () => PlanManager | undefined;
     onTaskLaunched?: TaskLaunchedCallback;
+    /**
+     * HITL park channel for `ask_user_question`. The tool is registered
+     * only when BOTH `resumeHandler` and `runId` are present — without a
+     * handler there is no one to route the question to, and without a
+     * runId the park request cannot be addressed.
+     */
+    resumeHandler?: ResumeHandler;
 }
 export declare function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[];
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/coordinator/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/coordinator/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAG/D,MAAM,MAAM,oBAAoB,GAAG,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IACL,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB,KACG,IAAI,CAAA;AAET,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,WAAW,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAA;IACpC,eAAe,EAAE,MAAM,EAAE,CAAA;IAEzB,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,cAAc,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAA;IAE9C,cAAc,CAAC,EAAE,oBAAoB,CAAA;CACrC;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,uBAAuB,GAAG,cAAc,EAAE,CAoNrF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/coordinator/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAG/D,MAAM,MAAM,oBAAoB,GAAG,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IACL,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B,KACG,IAAI,CAAA;AAET,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,WAAW,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAA;IACpC,eAAe,EAAE,MAAM,EAAE,CAAA;IAEzB,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,cAAc,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAA;IAE9C,cAAc,CAAC,EAAE,oBAAoB,CAAA;IAErC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC7B;AAwCD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,uBAAuB,GAAG,cAAc,EAAE,CA0drF"}