qlogicagent 2.13.4 → 2.13.5

package/dist/skills/tools/task-tool.js

@@ -0,0 +1,390 @@
+// ============================================================
+// Task Tool V2 — planning checklist + background task panel.
+//
+// Two surfaces under one tool:
+//
+// 1. Planning checklist (numeric ids): create / update / delete / list / get.
+//    In-memory dependency graph for tracking multi-step work.
+//
+// 2. Background task panel (string ids like "a1b2c3d4"): output / cancel.
+//    Queries the host's unified background task registry — agent forks
+//    started with agent(background=true), backgrounded shell commands,
+//    and dream consolidations. `list` also shows active background tasks.
+//
+// Features:
+// - Dependency graph: blocks/blockedBy with cascade delete
+// - Blocked enforcement: cannot set in-progress if blockers unresolved
+// - Owner binding: set owner to a background task id to link a checklist
+//   item to its running executor (live lifecycle shown in list)
+// - Verification nudge: after all 3+ tasks completed, prompts verify agent
+// - Parallelization nudge: multiple unblocked tasks → suggests background agents
+// - High water mark: prevents ID reuse after deletion
+//
+// Reference: CC TaskCreate/Update/List/Get (V2) + utils/tasks.ts
+// Category: system
+// ============================================================
+export const TASK_TOOL_NAME = "task";
+export const TASK_ACTIONS = ["create", "update", "delete", "list", "get", "output", "cancel"];
+/** Background task id shape: type prefix + 8 base36 chars (see generateTaskId). */
+const RUNTIME_TASK_ID_RE = /^[abdtrwm][a-z0-9]{8}$/;
+export const TASK_STATUS_VALUES = ["not-started", "in-progress", "completed"];
+export const TASK_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: [...TASK_ACTIONS],
+            description: "create — add a new checklist task (auto-assigns numeric id). " +
+                "update — modify a checklist task by id (partial, supports dependency wiring). " +
+                "delete — remove a checklist task by id (cascades block refs). " +
+                "list — read the checklist plus active background tasks. " +
+                "get — get a single checklist task by id. " +
+                "output — read a background task's status and output (requires taskId). " +
+                "cancel — stop a running background task (requires taskId).",
+        },
+        id: { type: "number", description: "[update|delete|get] Checklist task id to operate on." },
+        taskId: {
+            type: "string",
+            description: "[output|cancel] Background task id (returned by agent background=true / exec background=true).",
+        },
+        title: { type: "string", description: "[create|update] Task title (3-7 words, imperative form)." },
+        description: { type: "string", description: "[create|update] Detailed task description." },
+        status: {
+            type: "string",
+            enum: ["not-started", "in-progress", "completed"],
+            description: "[create|update] Task status. create defaults to not-started.",
+        },
+        owner: {
+            type: "string",
+            description: "[create|update] Executor label. Set this to a background task id " +
+                "(from agent background=true) to link the checklist item to its executor — " +
+                "list then shows the executor's live state.",
+        },
+        addBlocks: {
+            type: "array",
+            items: { type: "number" },
+            description: "[update] Task IDs that this task should block (they depend on this task).",
+        },
+        addBlockedBy: {
+            type: "array",
+            items: { type: "number" },
+            description: "[update] Task IDs that should block this task (this task depends on them).",
+        },
+    },
+    required: ["action"],
+};
+// ── Summary helper ──────────────────────────────────────────
+export function summarizeTaskList(items) {
+    const completedIds = new Set(items.filter((item) => item.status === "completed").map((item) => item.id));
+    return {
+        total: items.length,
+        completed: items.filter((item) => item.status === "completed").length,
+        inProgress: items.filter((item) => item.status === "in-progress").length,
+        notStarted: items.filter((item) => item.status === "not-started").length,
+        blocked: items.filter((item) => item.status !== "completed" &&
+            item.blockedBy?.some((id) => !completedIds.has(id))).length,
+    };
+}
+/**
+ * Create a stateful task tool instance (V2 — CC TaskCreate/Update/List/Get aligned).
+ */
+export function createTaskTool(options, hooks, runtimeDeps) {
+    let currentList = [];
+    let highWaterMark = 0;
+    const opts = options ?? {};
+    const enableVerifyNudge = opts.verificationNudge !== false;
+    const getRuntime = () => runtimeDeps?.getRuntime() ?? null;
+    // ── Helpers ────────────────────────────────────────────────
+    function nextId() {
+        const maxExisting = currentList.reduce((max, t) => Math.max(max, t.id), 0);
+        highWaterMark = Math.max(highWaterMark, maxExisting) + 1;
+        return highWaterMark;
+    }
+    function err(message) {
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            details: { type: "task", error: message },
+        };
+    }
+    function ok(extra) {
+        const summary = summarizeTaskList(currentList);
+        const completedIds = new Set(currentList.filter((t) => t.status === "completed").map((t) => t.id));
+        // For display: strip resolved blockers from blockedBy
+        const displayList = currentList.map((t) => {
+            const liveBlockedBy = t.blockedBy?.filter((id) => !completedIds.has(id));
+            return {
+                ...t,
+                ...(liveBlockedBy?.length ? { blockedBy: liveBlockedBy } : { blockedBy: undefined }),
+            };
+        });
+        // Plain-text result for LLM (CC-aligned: no JSON wrapping)
+        const lines = [];
+        lines.push(`Task list updated. ${summary.total} tasks: ${summary.completed} completed, ${summary.inProgress} in-progress, ${summary.notStarted} not-started.`);
+        if (summary.blocked > 0)
+            lines.push(`${summary.blocked} blocked.`);
+        if (extra?.created) {
+            const c = extra.created;
+            lines.push(`Created task #${c.id}: "${c.title}"`);
+        }
+        if (extra?.updated) {
+            const u = extra.updated;
+            lines.push(`Updated task #${u.id}: "${u.title}"`);
+        }
+        if (extra?.deleted != null)
+            lines.push(`Deleted task #${extra.deleted}`);
+        const runtime = getRuntime();
+        if (displayList.length > 0) {
+            lines.push("");
+            for (const t of displayList) {
+                const status = t.status === "completed" ? "✓" : t.status === "in-progress" ? "→" : "○";
+                const blocked = t.blockedBy?.length ? ` [blocked by #${t.blockedBy.join(", #")}]` : "";
+                // Owner binding: when owner is a background task id, show its live state
+                let owner = t.owner ? ` (${t.owner})` : "";
+                if (t.owner && runtime && RUNTIME_TASK_ID_RE.test(t.owner)) {
+                    const rt = runtime.getTask(t.owner);
+                    if (rt)
+                        owner = ` (${t.owner}: ${rt.lifecycle})`;
+                }
+                lines.push(`  ${status} #${t.id}: ${t.title} (${t.status})${owner}${blocked}`);
+            }
+        }
+        // Background task panel: active background work is part of the picture
+        const runtimeTasks = runtime?.listTasks() ?? [];
+        const activeRuntimeTasks = runtimeTasks.filter((t) => t.lifecycle === "running" || t.lifecycle === "pending");
+        if (activeRuntimeTasks.length > 0) {
+            lines.push("");
+            lines.push(`Background tasks (${activeRuntimeTasks.length} active):`);
+            for (const t of activeRuntimeTasks) {
+                const elapsed = Math.round((Date.now() - t.startedAt) / 1000);
+                lines.push(`  ⚙ ${t.taskId} [${t.type}] ${t.label} (${t.lifecycle}, ${elapsed}s)`);
+            }
+        }
+        // Parallelization nudge: several unblocked not-started tasks → suggest
+        // fanning out background agents instead of grinding through serially.
+        const actionable = currentList.filter((t) => {
+            if (t.status !== "not-started")
+                return false;
+            const unresolved = t.blockedBy?.filter((id) => !completedIds.has(id));
+            return !unresolved?.length;
+        });
+        const justCompleted = extra?.updated?.status === "completed";
+        if ((extra?.created || justCompleted) && actionable.length >= 2) {
+            lines.push("");
+            lines.push(`NOTE: ${actionable.length} tasks (#${actionable.map((t) => t.id).join(", #")}) are unblocked and not started. ` +
+                "If they are independent, launch them in parallel with agent(background=true) — one call per task in a single message — " +
+                "and set each task's owner to the returned task id.");
+        }
+        // Verification nudge: CC parity — when all tasks completed and total >= 3
+        // and none has "verif" in title, nudge to spawn verification agent
+        let verificationNudgeNeeded = false;
+        if (enableVerifyNudge && extra?.updated) {
+            const u = extra.updated;
+            if (u.status === "completed") {
+                const allCompleted = currentList.every((t) => t.status === "completed");
+                const totalTasks = currentList.length;
+                const hasVerificationTask = currentList.some((t) => /verif/i.test(t.title));
+                if (allCompleted && totalTasks >= 3 && !hasVerificationTask) {
+                    verificationNudgeNeeded = true;
+                    lines.push("");
+                    lines.push("NOTE: You just closed out " + totalTasks + " tasks and none of them was a verification step. " +
+                        "Before writing your final summary, spawn the verification agent " +
+                        '(agent tool with agent="verify"). You cannot self-assign PARTIAL by listing ' +
+                        "caveats in your summary — only the verifier issues a verdict.");
+                }
+            }
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            details: {
+                type: "task",
+                ...summary,
+                ...extra,
+                taskList: displayList,
+                agentId: opts.agentId,
+                ...(verificationNudgeNeeded && { verificationNudgeNeeded: true }),
+            },
+        };
+    }
+    function wireDeps(taskId, addBlocks, addBlockedBy) {
+        const task = currentList.find((t) => t.id === taskId);
+        if (!task)
+            return;
+        if (addBlocks?.length) {
+            task.blocks = [...new Set([...(task.blocks ?? []), ...addBlocks])];
+            for (const targetId of addBlocks) {
+                const target = currentList.find((t) => t.id === targetId);
+                if (target)
+                    target.blockedBy = [...new Set([...(target.blockedBy ?? []), taskId])];
+            }
+        }
+        if (addBlockedBy?.length) {
+            task.blockedBy = [...new Set([...(task.blockedBy ?? []), ...addBlockedBy])];
+            for (const blockerId of addBlockedBy) {
+                const blocker = currentList.find((t) => t.id === blockerId);
+                if (blocker)
+                    blocker.blocks = [...new Set([...(blocker.blocks ?? []), taskId])];
+            }
+        }
+    }
+    function cascadeDelete(deletedId) {
+        for (const t of currentList) {
+            if (t.blocks)
+                t.blocks = t.blocks.filter((id) => id !== deletedId);
+            if (t.blockedBy)
+                t.blockedBy = t.blockedBy.filter((id) => id !== deletedId);
+        }
+    }
+    // ── Action handlers ────────────────────────────────────────
+    function handleCreate(params) {
+        if (!params.title)
+            return err("title is required for create action.");
+        const newItem = {
+            id: nextId(),
+            title: params.title,
+            status: params.status ?? "not-started",
+            ...(params.description != null && { description: params.description }),
+            ...(params.owner != null && { owner: params.owner }),
+        };
+        currentList.push(newItem);
+        wireDeps(newItem.id, undefined, params.addBlockedBy);
+        hooks?.onTaskCreated?.(newItem);
+        return ok({ created: { id: newItem.id, title: newItem.title } });
+    }
+    function handleUpdate(params) {
+        if (params.id == null)
+            return err("id is required for update action.");
+        const task = currentList.find((t) => t.id === params.id);
+        if (!task)
+            return err(`Task #${params.id} not found.`);
+        // Blocked check: cannot move to in-progress if unresolved blockers exist
+        if (params.status === "in-progress") {
+            const completedIds = new Set(currentList.filter((t) => t.status === "completed").map((t) => t.id));
+            const unresolvedBlockers = task.blockedBy?.filter((id) => !completedIds.has(id));
+            if (unresolvedBlockers?.length) {
+                return err(`Cannot set #${params.id} to in-progress: blocked by unresolved task(s) #${unresolvedBlockers.join(", #")}.`);
+            }
+        }
+        if (params.title != null)
+            task.title = params.title;
+        if (params.description != null)
+            task.description = params.description;
+        if (params.owner != null)
+            task.owner = params.owner;
+        if (params.status != null) {
+            const prevStatus = task.status;
+            task.status = params.status;
+            if (prevStatus !== "completed" && params.status === "completed") {
+                hooks?.onTaskCompleted?.(task);
+            }
+        }
+        wireDeps(task.id, params.addBlocks, params.addBlockedBy);
+        return ok({ updated: { id: task.id, title: task.title, status: task.status } });
+    }
+    function handleDelete(params) {
+        if (params.id == null)
+            return err("id is required for delete action.");
+        const idx = currentList.findIndex((t) => t.id === params.id);
+        if (idx === -1)
+            return err(`Task #${params.id} not found.`);
+        highWaterMark = Math.max(highWaterMark, params.id);
+        currentList.splice(idx, 1);
+        cascadeDelete(params.id);
+        return ok({ deleted: params.id });
+    }
+    async function handleOutput(params) {
+        if (!params.taskId)
+            return err("taskId is required for output action.");
+        const runtime = getRuntime();
+        if (!runtime)
+            return err("No background task registry available in this host.");
+        const snapshot = await runtime.readOutput(params.taskId);
+        if (!snapshot)
+            return err(`Background task ${params.taskId} not found.`);
+        const { task, output, running } = snapshot;
+        const elapsed = Math.round(((task.endedAt ?? Date.now()) - task.startedAt) / 1000);
+        const lines = [
+            `Task ${task.taskId} [${task.type}] ${task.label}`,
+            `Status: ${task.lifecycle}${running ? ` (running for ${elapsed}s)` : ` (${elapsed}s)`}`,
+            task.error ? `Error: ${task.error}` : "",
+            "",
+            output || (running ? "(no output yet)" : "(no output)"),
+        ];
+        return {
+            content: [{ type: "text", text: lines.filter((l, i) => l !== "" || i === 3).join("\n") }],
+            details: {
+                type: "task",
+                action: "output",
+                taskId: task.taskId,
+                lifecycle: task.lifecycle,
+                running,
+            },
+        };
+    }
+    function handleCancel(params) {
+        if (!params.taskId)
+            return err("taskId is required for cancel action.");
+        const runtime = getRuntime();
+        if (!runtime)
+            return err("No background task registry available in this host.");
+        const cancelled = runtime.cancelTask(params.taskId);
+        if (!cancelled) {
+            const existing = runtime.getTask(params.taskId);
+            return err(existing
+                ? `Background task ${params.taskId} is already ${existing.lifecycle}.`
+                : `Background task ${params.taskId} not found.`);
+        }
+        return {
+            content: [{ type: "text", text: `Background task ${params.taskId} cancelled.` }],
+            details: { type: "task", action: "cancel", taskId: params.taskId },
+        };
+    }
+    function handleGet(params) {
+        if (params.id == null)
+            return err("id is required for get action.");
+        const task = currentList.find((t) => t.id === params.id);
+        if (!task)
+            return err(`Task #${params.id} not found.`);
+        const completedIds = new Set(currentList.filter((t) => t.status === "completed").map((t) => t.id));
+        const liveBlockedBy = task.blockedBy?.filter((id) => !completedIds.has(id));
+        const lines = [
+            `Task #${task.id}: ${task.title}`,
+            `Status: ${task.status}`,
+            task.description ? `Description: ${task.description}` : "",
+            task.owner ? `Owner: ${task.owner}` : "",
+            liveBlockedBy?.length ? `Blocked by: #${liveBlockedBy.join(", #")}` : "",
+            task.blocks?.length ? `Blocks: #${task.blocks.join(", #")}` : "",
+        ];
+        return {
+            content: [{ type: "text", text: lines.filter(Boolean).join("\n") }],
+            details: { type: "task", action: "get", task },
+        };
+    }
+    // ── Tool definition ────────────────────────────────────────
+    return {
+        name: TASK_TOOL_NAME,
+        label: "Task",
+        description: "Plan and track multi-step work, and monitor background tasks. " +
+            "Checklist actions (numeric id): create, update, delete, list, get — an in-session plan with " +
+            "dependency tracking (blocks/blockedBy); tasks cannot start until blockers complete. " +
+            "Background actions (string taskId): output (read status + output of a background agent/command), " +
+            "cancel (stop it). Background task ids come from agent(background=true) or exec(background=true); " +
+            "`list` also shows active background tasks. " +
+            "Use frequently during complex work to plan steps, fan out background agents, and show progress.",
+        parameters: TASK_TOOL_SCHEMA,
+        searchHint: "manage session task checklist progress tracking dependencies planning background output cancel poll",
+        maxResultSizeChars: 100_000,
+        execute: async (_toolCallId, params) => {
+            const action = params.action;
+            switch (action) {
+                case "create": return handleCreate(params);
+                case "update": return handleUpdate(params);
+                case "delete": return handleDelete(params);
+                case "list": return ok();
+                case "get": return handleGet(params);
+                case "output": return handleOutput(params);
+                case "cancel": return handleCancel(params);
+                default: return err(`Unknown action: ${action}. Valid: create, update, delete, list, get, output, cancel.`);
+            }
+        },
+    };
+}

package/dist/skills/tools/team-tool.d.ts

@@ -0,0 +1,156 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const TEAM_TOOL_NAME: "team";
+export type TeamAction = "create" | "delete" | "list" | "status" | "send";
+export interface TeamMember {
+    name: string;
+    role: string;
+    tools?: string[];
+    /** Working directory for this member (worktree path or inherited cwd). */
+    cwd?: string;
+    /** Git worktree path if auto-provisioned (CC TeamMember.worktreePath parity). */
+    worktreePath?: string;
+    /** Git worktree branch name (for cleanup). */
+    worktreeBranch?: string;
+    /** Whether the member is currently active. */
+    isActive?: boolean;
+}
+export interface TeamToolParams {
+    action: TeamAction;
+    /** Team name (required for create/delete) */
+    teamName?: string;
+    /** Team description */
+    description?: string;
+    /** Members to include (for create) */
+    members?: TeamMember[];
+    /** Target member name or '*' for broadcast (required for send) */
+    to?: string;
+    /** Message content (required for send) */
+    message?: string;
+    /** Optional short summary for logging/routing (send) */
+    summary?: string;
+}
+export declare const TEAM_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["create", "delete", "list", "status", "send"];
+            readonly description: "Team action: create (new team), delete (disband), list (all teams), status (team details), send (message a member and collect the reply).";
+        };
+        readonly teamName: {
+            readonly type: "string";
+            readonly description: "Team name. Required for create/delete/status.";
+        };
+        readonly to: {
+            readonly type: "string";
+            readonly description: "Target member name, full member id, or '*' to broadcast to all live members. Required for send.";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Message content to deliver to the member. Required for send.";
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly description: "Optional short summary (for logging/routing). Used by send.";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Team description/objective. Used for create.";
+        };
+        readonly members: {
+            readonly type: "array";
+            readonly description: "Team members with roles and tool restrictions.";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                        readonly description: "Agent name/role identifier.";
+                    };
+                    readonly role: {
+                        readonly type: "string";
+                        readonly description: "Role description (e.g. 'frontend developer').";
+                    };
+                    readonly tools: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Allowed tools for this member.";
+                    };
+                };
+                readonly required: readonly ["name", "role"];
+            };
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface Team {
+    name: string;
+    description?: string;
+    leadId: string;
+    members: TeamMember[];
+    createdAt: string;
+}
+export interface TeamResult {
+    success: boolean;
+    team?: Team;
+    teams?: Team[];
+    error?: string;
+    /** Members that failed to spawn (team still created with the survivors). */
+    partialFailures?: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+export interface TeamSendResult {
+    success: boolean;
+    recipients?: string[];
+    error?: string;
+    /** Replies collected from the recipient(s) — the message loop is synchronous. */
+    replies?: Array<{
+        memberId: string;
+        name: string;
+        reply: string;
+    }>;
+}
+/**
+ * Host-provided team management backend.
+ * Creates agent teams whose members are messaged via the send action.
+ */
+export interface TeamToolDeps {
+    createTeam(params: {
+        teamName: string;
+        description?: string;
+        members?: TeamMember[];
+    }): Promise<TeamResult>;
+    deleteTeam(teamName: string): Promise<TeamResult>;
+    listTeams(): Promise<TeamResult>;
+    getTeamStatus(teamName: string): Promise<TeamResult & {
+        memberProgress?: Record<string, {
+            mediaProgress?: {
+                taskId: string;
+                mediaType: string;
+                percent: number;
+                status: string;
+                provider?: string;
+                updatedAt: number;
+            };
+            lastToolCall?: string;
+            idleFor?: number;
+            runningFor?: number;
+        }>;
+    }>;
+    /** Deliver a message to member(s) and collect their replies (send action). */
+    sendMessage(params: {
+        to: string;
+        message: string;
+        summary?: string;
+        senderId: string;
+    }): Promise<TeamSendResult>;
+    /** Current agent's id (send action sender). */
+    getSenderId(): string;
+    /** Live teammate names (send action target validation). */
+    listTeammates(): string[];
+}
+export declare function createTeamTool(deps: TeamToolDeps): PortableTool<TeamToolParams>;