@tianshu-ai/tianshu 0.3.0

package/plugins/workboard/dist/tools/index.js

@@ -0,0 +1,963 @@
+// Agent tools the workboard plugin contributes.
+//
+// Five tools cover the kanban surface from the agent's side:
+//
+//   - task_list   — read the board (status-grouped, optional project filter)
+//   - task_create — drop one or more new ready tasks on the board (batch)
+//   - task_update — patch title / description / priority / project
+//   - task_move   — move a task between status columns
+//   - task_delete — remove one or more tasks (batch)
+//
+// Worker-side helpers (claim / complete) intentionally do NOT live
+// here — workers don't run inside the agent loop, they live inside
+// the host process. The only "worker" the agent talks to is via the
+// task itself: drop a task on the board, watch the kanban panel, see
+// it flip to done.
+//
+// All tools require a database handle which the activator passes in
+// once and closes over via these factories. We don't capture the
+// AgentToolContext.userId from the call — we read it from the ctx
+// each invocation so that cross-user tool routing in v1 can change
+// the scope without rewriting the tools.
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { createTask, deleteTask, getTask, isEligible, listTasks, updateTask, isTaskStatus, INTERVENTION_LABEL, DEFAULT_TASK_TIMEOUT_MS, VISIBLE_STATUSES, } from "../db/tasks.js";
+import { appendContinuationHint, stripContinuationHint, } from "../worker/pool.js";
+import { loadWorkerAgents } from "../fs-worker-agents.js";
+/** PR-C2 replaces the listWorkerAgents() DB call with a fs scan.
+ *  Helper kept local so the existing call sites change as little
+ *  as possible. The tool surface still passes through `deps.db`
+ *  (some tools genuinely need it), so we don't bother routing
+ *  tenantHomeDir through ToolDeps; we just rebuild the path from
+ *  the tenant id we already have. */
+function listAgents(tenantId, tenantHomeDir) {
+    return loadWorkerAgents({ tenantId, tenantHomeDir }).agents;
+}
+import { readSessionHistory } from "../db/session-history.js";
+const STATUS_DESCRIPTION = 'One of "ready", "in_progress", "done". ' +
+    '"ready" tasks are picked up by the worker pool. ' +
+    'Tasks tagged with the "stalled" or "draft" label stay in "ready" ' +
+    'but are skipped by the pool until the label is removed.';
+function summarise(t, blocked) {
+    return {
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        project: t.projectSlug,
+        priority: t.priority,
+        workerRole: t.workerRole,
+        description: t.description,
+        resultSummary: t.resultSummary,
+        dependsOn: t.dependsOn,
+        labels: t.labels,
+        failureReason: t.failureReason,
+        attempts: t.attempts,
+        blocked,
+        createdAt: t.createdAt,
+        startedAt: t.startedAt,
+        endedAt: t.endedAt,
+    };
+}
+/** Filter caller-supplied depends_on against owner-scoped tasks.
+ *  Drops any id that doesn't belong to this user (silently — it's
+ *  the same forgiving behaviour the routes layer uses). */
+function sanitiseDepsForOwner(db, ownerUserId, raw, excludeId) {
+    if (!raw || raw.length === 0)
+        return [];
+    const cleaned = raw
+        .filter((x) => typeof x === "string" && x.trim().length > 0)
+        .map((x) => x.trim())
+        .filter((id) => id !== excludeId);
+    if (cleaned.length === 0)
+        return [];
+    const placeholders = cleaned.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT id FROM tasks WHERE owner_user_id = ? AND id IN (${placeholders})`)
+        .all(ownerUserId, ...cleaned);
+    return rows.map((r) => r.id);
+}
+function formatBoard(tasks, blockedSet) {
+    if (tasks.length === 0)
+        return "(no tasks)";
+    const groups = new Map();
+    for (const s of VISIBLE_STATUSES)
+        groups.set(s, []);
+    for (const t of tasks) {
+        let arr = groups.get(t.status);
+        if (!arr) {
+            arr = [];
+            groups.set(t.status, arr);
+        }
+        arr.push(t);
+    }
+    const lines = [];
+    for (const [status, list] of groups) {
+        if (list.length === 0)
+            continue;
+        lines.push(`${status} (${list.length}):`);
+        for (const t of list) {
+            const tag = t.priority > 0 ? ` [p${t.priority}]` : "";
+            const role = t.workerRole ? ` <${t.workerRole}>` : "";
+            const project = t.projectSlug && t.projectSlug !== "inbox" ? ` #${t.projectSlug}` : "";
+            const deps = t.dependsOn.length > 0
+                ? ` deps:${blockedSet.has(t.id) ? "🔒" : "✓"}${t.dependsOn.length}`
+                : "";
+            lines.push(`  ${t.id} — ${t.title}${tag}${role}${project}${deps}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function buildTaskListTool(deps) {
+    return {
+        schema: {
+            name: "task_list",
+            description: "List tasks on the workboard. Defaults to the four visible columns " +
+                "(ready / in_progress / done). Pass a project filter to scope " +
+                "to one slug, or status to override the default columns. Use this before " +
+                "task_create to avoid duplicates.",
+            parameters: Type.Object({
+                project: Type.Optional(Type.String({
+                    description: 'Project slug to filter on. Tasks without an explicit slug are filed under "inbox".',
+                })),
+                status: Type.Optional(Type.String({
+                    description: "Comma-separated statuses, e.g. \"todo,in_progress\". Overrides the default visible columns.",
+                })),
+                limit: Type.Optional(Type.Number({
+                    description: "Max rows. Default 200, hard cap 2000.",
+                })),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const statuses = [];
+            if (args.status) {
+                for (const piece of args.status.split(",")) {
+                    const trimmed = piece.trim();
+                    if (!trimmed)
+                        continue;
+                    if (!isTaskStatus(trimmed)) {
+                        return { ok: false, text: `unknown status: ${trimmed}` };
+                    }
+                    statuses.push(trimmed);
+                }
+            }
+            const tasks = listTasks(deps.db, {
+                ownerUserId: ctx.userId,
+                projectSlug: args.project ?? null,
+                statuses: statuses.length ? statuses : undefined,
+                limit: args.limit ?? 200,
+            });
+            const blocked = new Set();
+            for (const t of tasks) {
+                if (t.status === "ready" && !isEligible(deps.db, t)) {
+                    blocked.add(t.id);
+                }
+            }
+            return {
+                ok: true,
+                text: formatBoard(tasks, blocked),
+                data: {
+                    tasks: tasks.map((t) => summarise(t, blocked.has(t.id))),
+                },
+            };
+        },
+    };
+}
+/**
+ * Schema for one task inside a `task_create` batch. Kept as a
+ * named TypeBox object so the description renders cleanly inside
+ * the array's items schema.
+ */
+const TaskCreateItem = Type.Object({
+    title: Type.String({ description: "Short human-readable title." }),
+    description: Type.Optional(Type.String({ description: "Long-form notes / context for the worker." })),
+    project: Type.Optional(Type.String({ description: "Project slug. Default \"inbox\"." })),
+    priority: Type.Optional(Type.Number({
+        description: "Higher = picked up first. Range -10..10; default 0.",
+    })),
+    worker_agent_id: Type.Optional(Type.String({
+        description: "Slug of the worker that should pick this task up (e.g. \"coder\", \"llm-default\"). Use `tenant_config_list({path:\"workers\"})` to see what's registered. Omitting this leaves the task unpinned — any enabled worker can grab it, but you lose control over which one. Pinning by slug is the recommended path; kind-based dispatch is no longer exposed.",
+    })),
+    depends_on: Type.Optional(Type.Array(Type.String(), {
+        description: "Task ids that must reach status='done' before this task is eligible for a worker. Use this to express 'B starts after A'. Ids that don't belong to you are silently ignored.",
+    })),
+    labels: Type.Optional(Type.Array(Type.String(), {
+        description: "Free-form labels. Reserved values: 'stalled' (after MAX_ATTEMPTS pool failures, set automatically) and 'draft' (user opt-in: keeps the task in ready column but the pool skips it until cleared).",
+    })),
+});
+export function buildTaskCreateTool(deps) {
+    return {
+        schema: {
+            name: "task_create",
+            description: "Drop one or more new tasks on the workboard. Always pass a `tasks` array — " +
+                "single-task callers should send a 1-element array. Defaults are " +
+                "status=ready, project=inbox; workers in the pool will pick up ready " +
+                "tasks automatically. Per-row failures (e.g. an unknown worker_agent_id) do " +
+                "NOT abort the rest of the batch — each row reports independently in " +
+                "the response's `results` array.",
+            parameters: Type.Object({
+                tasks: Type.Array(TaskCreateItem, {
+                    minItems: 1,
+                    maxItems: 100,
+                    description: "Tasks to create, in the order they should appear in `results`.",
+                }),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const items = Array.isArray(args.tasks) ? args.tasks : [];
+            if (items.length === 0) {
+                return { ok: false, text: "tasks array must not be empty" };
+            }
+            // Cache the worker-agent list once for the whole batch —
+            // creating 50 tasks against the same role shouldn't hit the
+            // DB 50 times for the same lookup.
+            const agents = listAgents(ctx.tenantId, ctx.tenantHomeDir);
+            const results = items.map((item, index) => {
+                const title = item?.title?.trim();
+                if (!title) {
+                    return { ok: false, index, text: "title is required" };
+                }
+                if (title.length > 200) {
+                    return {
+                        ok: false,
+                        index,
+                        text: "title too long (max 200 chars)",
+                    };
+                }
+                const id = randomUUID();
+                const dependsOn = sanitiseDepsForOwner(deps.db, ctx.userId, item.depends_on, id);
+                const explicitAgentId = item.worker_agent_id?.trim() || null;
+                if (explicitAgentId) {
+                    const target = agents.find((a) => a.id === explicitAgentId);
+                    if (!target) {
+                        return {
+                            ok: false,
+                            index,
+                            text: `Worker agent "${explicitAgentId}" doesn't exist in this tenant. Use \`tenant_config_list({ path: "workers" })\` to see available slugs.`,
+                        };
+                    }
+                    if (!target.enabled) {
+                        return {
+                            ok: false,
+                            index,
+                            text: `Worker agent "${target.name}" (${explicitAgentId}) is disabled. Enable it (set agent.json enabled: true) or pick another worker.`,
+                        };
+                    }
+                }
+                const task = createTask(deps.db, id, {
+                    ownerUserId: ctx.userId,
+                    title,
+                    description: item.description,
+                    projectSlug: item.project,
+                    priority: item.priority,
+                    // workerRole no longer set from the tool surface —
+                    // dispatch is by worker_agent_id (slug) only. The DB
+                    // column stays for backwards compat with existing rows.
+                    workerRole: null,
+                    workerAgentId: explicitAgentId,
+                    dependsOn,
+                    labels: item.labels,
+                    // Stamp the asking session so the pool knows who to
+                    // notify when this task finishes. Tools called outside
+                    // an LLM context (none of these today, but possible
+                    // for an internal job) just leave it null.
+                    parentSessionId: ctx.sessionId ?? null,
+                });
+                const blocked = !isEligible(deps.db, task);
+                return {
+                    ok: true,
+                    index,
+                    task: summarise(task, blocked),
+                };
+            });
+            const okCount = results.filter((r) => r.ok).length;
+            if (okCount > 0)
+                deps.onTaskWrite();
+            const failCount = results.length - okCount;
+            const summary = failCount === 0
+                ? `Created ${okCount} task${okCount === 1 ? "" : "s"}.`
+                : `Created ${okCount}/${results.length} task${results.length === 1 ? "" : "s"}; ${failCount} failed.`;
+            return {
+                ok: okCount > 0,
+                text: summary,
+                data: { results },
+            };
+        },
+    };
+}
+export function buildTaskUpdateTool(deps) {
+    return {
+        schema: {
+            name: "task_update",
+            description: "Patch a task. Pass id + any subset of (title, description, project, " +
+                "priority, worker_agent_id, depends_on, labels). For status changes use task_move.",
+            parameters: Type.Object({
+                id: Type.String(),
+                title: Type.Optional(Type.String()),
+                description: Type.Optional(Type.String()),
+                project: Type.Optional(Type.String()),
+                priority: Type.Optional(Type.Number()),
+                worker_agent_id: Type.Optional(Type.Union([Type.String(), Type.Null()], {
+                    description: "Repin to a different worker by slug, or pass null to clear the pin (any enabled worker can grab it). Use `tenant_config_list({path:\"workers\"})` to see slugs.",
+                })),
+                depends_on: Type.Optional(Type.Array(Type.String(), {
+                    description: "Replace the dependency list. Pass [] to clear. Ids must belong to you; bogus ids are silently dropped.",
+                })),
+                labels: Type.Optional(Type.Array(Type.String(), {
+                    description: "Replace the labels list. Pass [] to clear. Reserved: 'stalled' (set automatically by the pool after MAX_ATTEMPTS failures), 'draft' (pool skip).",
+                })),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            if (!args.id)
+                return { ok: false, text: "id is required" };
+            const before = getTask(deps.db, args.id);
+            if (!before)
+                return { ok: false, text: `task not found: ${args.id}` };
+            if (before.ownerUserId !== ctx.userId) {
+                // v0 keeps the board single-user. Future: add an explicit
+                // share mechanism + relax this check.
+                return { ok: false, text: `task ${args.id} is not yours` };
+            }
+            // If the patch changes the pin, validate the slug exists
+            // and is enabled (same rule as on create). `undefined` =
+            // don't touch; explicit `null` = clear the pin.
+            if (args.worker_agent_id !== undefined && args.worker_agent_id !== null) {
+                const slug = args.worker_agent_id.trim();
+                if (!slug) {
+                    return {
+                        ok: false,
+                        text: "worker_agent_id is empty; pass null to clear the pin or a slug to pin.",
+                    };
+                }
+                const target = listAgents(ctx.tenantId, ctx.tenantHomeDir).find((a) => a.id === slug);
+                if (!target) {
+                    return {
+                        ok: false,
+                        text: `Worker agent "${slug}" doesn't exist. Use \`tenant_config_list({path:"workers"})\` for available slugs.`,
+                    };
+                }
+                if (!target.enabled) {
+                    return {
+                        ok: false,
+                        text: `Worker agent "${target.name}" (${slug}) is disabled. Enable it or pick another.`,
+                    };
+                }
+            }
+            const patch = {
+                title: args.title,
+                description: args.description,
+                projectSlug: args.project,
+                priority: args.priority,
+                workerAgentId: args.worker_agent_id,
+            };
+            if (args.depends_on !== undefined) {
+                patch.dependsOn = sanitiseDepsForOwner(deps.db, ctx.userId, args.depends_on, args.id);
+            }
+            if (args.labels !== undefined) {
+                patch.labels = args.labels;
+            }
+            const patched = updateTask(deps.db, args.id, patch);
+            // If the patch dropped the `stalled` / `draft` label the
+            // task may now be claimable; nudge so the pool re-considers.
+            if (patched &&
+                args.labels !== undefined &&
+                before.labels.some((l) => ["stalled", "draft"].includes(l)) &&
+                !patched.labels.some((l) => ["stalled", "draft"].includes(l)) &&
+                patched.status === "ready") {
+                deps.onTaskWrite();
+            }
+            const blocked = patched
+                ? patched.status === "ready" && !isEligible(deps.db, patched)
+                : false;
+            return {
+                ok: true,
+                text: `Updated task ${args.id}.`,
+                data: { task: patched ? summarise(patched, blocked) : null },
+            };
+        },
+    };
+}
+export function buildTaskMoveTool(deps) {
+    return {
+        schema: {
+            name: "task_move",
+            description: "Change a task's status column. Valid targets: ready, in_progress, done. " +
+                "Moving back to 'ready' re-queues the task for the worker pool.",
+            parameters: Type.Object({
+                id: Type.String(),
+                status: Type.String({ description: STATUS_DESCRIPTION }),
+                result_summary: Type.Optional(Type.String({
+                    description: "Optional one-line summary for the result column (typically used when moving to done).",
+                })),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            if (!args.id)
+                return { ok: false, text: "id is required" };
+            if (!args.status || !isTaskStatus(args.status)) {
+                return { ok: false, text: `unknown status: ${args.status}` };
+            }
+            const before = getTask(deps.db, args.id);
+            if (!before)
+                return { ok: false, text: `task not found: ${args.id}` };
+            if (before.ownerUserId !== ctx.userId) {
+                return { ok: false, text: `task ${args.id} is not yours` };
+            }
+            const status = args.status;
+            const now = Date.now();
+            const patch = { status };
+            if (args.result_summary !== undefined) {
+                patch.resultSummary = args.result_summary;
+            }
+            // Handy timestamp accounting so the UI doesn't have to guess.
+            if (status === "in_progress" && !before.startedAt)
+                patch.startedAt = now;
+            if (status === "done") {
+                patch.endedAt = now;
+            }
+            if (status === "ready") {
+                patch.startedAt = null;
+                patch.endedAt = null;
+                patch.resultSummary = null;
+                // Manual re-queue clears the failure trail too — the user
+                // is saying "this is fixed, try again".
+                patch.failureReason = null;
+                patch.attempts = 0;
+                // Drop the post-008 intervention labels so the pool's
+                // claim filter (POOL_SKIP_LABELS) lets the task through.
+                // Without this, task_move-back-to-ready leaves the row
+                // in a zombie state: status=ready (visible in the queue
+                // column) but skipped by every drain pass.
+                patch.labels = before.labels.filter((l) => l !== INTERVENTION_LABEL && l !== "stalled");
+                patch.interventionReason = null;
+                patch.interventionAt = null;
+            }
+            const after = updateTask(deps.db, args.id, patch);
+            // Re-queueing → kick the pool so the worker drains immediately.
+            // Nudge the pool when the move could create new claimable
+            // work: putting THIS task back to ready, OR marking it done
+            // and thereby unblocking any task that depended on it.
+            if (status === "ready" || status === "done")
+                deps.onTaskWrite();
+            const blocked = after
+                ? after.status === "ready" && !isEligible(deps.db, after)
+                : false;
+            return {
+                ok: true,
+                text: `Moved task ${args.id}: ${before.status} → ${status}`,
+                data: { task: after ? summarise(after, blocked) : null },
+            };
+        },
+    };
+}
+export function buildTaskDeleteTool(deps) {
+    return {
+        schema: {
+            name: "task_delete",
+            description: "Remove one or more tasks from the board. Always pass an `ids` array — " +
+                "single-task callers should send a 1-element array. Per-row failures " +
+                "(unknown id, not yours) do NOT abort the rest of the batch — each " +
+                "id reports independently in `results`. The deletion is permanent; " +
+                "add the 'stalled' label via task_update if you want to keep an audit " +
+                "trail instead.",
+            parameters: Type.Object({
+                ids: Type.Array(Type.String(), {
+                    minItems: 1,
+                    maxItems: 100,
+                    description: "Task ids to delete, order matches the `results`.",
+                }),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const ids = Array.isArray(args.ids) ? args.ids : [];
+            if (ids.length === 0) {
+                return { ok: false, text: "ids array must not be empty" };
+            }
+            const results = ids.map((id) => {
+                if (typeof id !== "string" || !id) {
+                    return {
+                        ok: false,
+                        id: String(id ?? ""),
+                        text: "id is required",
+                    };
+                }
+                const before = getTask(deps.db, id);
+                if (!before)
+                    return { ok: false, id, text: `task not found: ${id}` };
+                if (before.ownerUserId !== ctx.userId) {
+                    return { ok: false, id, text: `task ${id} is not yours` };
+                }
+                deleteTask(deps.db, id);
+                // Best-effort sandbox teardown. Errors are logged inside
+                // the pool implementation; we don't want a stop / remove
+                // glitch to surface as a deleted-task failure.
+                try {
+                    deps.onTaskDelete?.(id);
+                }
+                catch (err) {
+                    deps.log.warn("workboard: task sandbox cleanup failed", {
+                        taskId: id,
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                return { ok: true, id };
+            });
+            const okCount = results.filter((r) => r.ok).length;
+            if (okCount > 0)
+                deps.onTaskWrite();
+            const failCount = results.length - okCount;
+            const summary = failCount === 0
+                ? `Deleted ${okCount} task${okCount === 1 ? "" : "s"}.`
+                : `Deleted ${okCount}/${results.length} task${results.length === 1 ? "" : "s"}; ${failCount} failed.`;
+            return {
+                ok: okCount > 0,
+                text: summary,
+                data: { results },
+            };
+        },
+    };
+}
+/**
+ * Read a task's worker execution transcript.
+ *
+ * The chat-side orchestrator calls this when the user asks "why
+ * did T4 fail?" — the orchestrator gets the full assistant /
+ * tool-call / tool-result trail of the worker's most recent run
+ * and can reason about it directly. The same data backs the
+ * kanban Execution tab; both views go through this code path so
+ * the agent can never see anything the user can't.
+ *
+ * Empty `entries` is the normal response for a task that has
+ * never been claimed (`tasks.session_id IS NULL`).
+ */
+export function buildTaskGetHistoryTool(deps) {
+    return {
+        schema: {
+            name: "task_get_history",
+            description: "Fetch the worker's execution transcript for a task you own. " +
+                "Returns the chronological list of assistant / tool-call / " +
+                "tool-result rows from the worker's most recent run, plus " +
+                "attempts and failure_reason. Use this when the user wants " +
+                "to know why a task stalled or what the worker actually did.",
+            parameters: Type.Object({
+                id: Type.String({ description: "Task id." }),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            if (!args.id)
+                return { ok: false, text: "id is required" };
+            const task = getTask(deps.db, args.id);
+            if (!task)
+                return { ok: false, text: `task not found: ${args.id}` };
+            if (task.ownerUserId !== ctx.userId) {
+                return { ok: false, text: `task ${args.id} is not yours` };
+            }
+            const sessionId = task.sessionId;
+            if (!sessionId) {
+                return {
+                    ok: true,
+                    text: `Task ${args.id} has no execution history yet (never claimed by a worker).`,
+                    data: {
+                        taskId: task.id,
+                        sessionId: null,
+                        attempts: task.attempts,
+                        failureReason: task.failureReason,
+                        entries: [],
+                    },
+                };
+            }
+            const entries = readSessionHistory(deps.db, sessionId);
+            return {
+                ok: true,
+                text: `Found ${entries.length} entries from the worker session for task ${args.id}.`,
+                data: {
+                    taskId: task.id,
+                    sessionId,
+                    attempts: task.attempts,
+                    failureReason: task.failureReason,
+                    entries,
+                },
+            };
+        },
+    };
+}
+// ─── Intervention tools (008+) ─────────────────────────────────────
+//
+// Failed worker runs no longer auto-retry; they park the row in
+// awaiting-intervention and notify the parent (main) agent. The
+// main agent then picks one of these four to resolve:
+//
+//   - task_continue       resume the same session, optionally with
+//                         a hint about what changed.
+//   - task_retry_fresh    discard the prior session and start over,
+//                         optionally with a revised description.
+//   - task_extend_timeout add wall-clock budget. If the worker is
+//                         still running, the watchdog picks the
+//                         new value up on its next tick. If the
+//                         row is parked in intervention because of
+//                         a timeout, this also revives it.
+//   - task_abort          give up: mark the task done with a
+//                         failure summary so downstream deps stop
+//                         waiting.
+/**
+ * Validate task ownership + presence; return `{ task, error }`
+ * union so callers can write a flat error path.
+ */
+function loadOwnedTask(deps, ctx, id) {
+    if (!id) {
+        return { error: { ok: false, text: "task_id is required" } };
+    }
+    const task = getTask(deps.db, id);
+    if (!task) {
+        return { error: { ok: false, text: `task not found: ${id}` } };
+    }
+    if (task.ownerUserId !== ctx.userId) {
+        return { error: { ok: false, text: `task ${id} is not yours` } };
+    }
+    return { task };
+}
+export function buildTaskContinueTool(deps) {
+    return {
+        schema: {
+            name: "task_continue",
+            description: "Revive an awaiting-intervention task by resuming its prior " +
+                "worker session. The worker reuses its existing context (no " +
+                "re-paste of the brief), with an optional `hint` from you " +
+                "the orchestrator about what changed or what to try next " +
+                "(e.g. 'use the skeleton-then-fill pattern; previous attempt " +
+                "hit an output cap'). Use this when the prior transcript is " +
+                "useful and the task description is still right. For a hard " +
+                "reset use `task_retry_fresh`.",
+            parameters: Type.Object({
+                task_id: Type.String(),
+                hint: Type.Optional(Type.String({
+                    description: "One- or two-paragraph nudge surfaced to the worker on resume. " +
+                        "Optional but strongly recommended — a bare retry usually " +
+                        "reproduces the same failure.",
+                })),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const found = loadOwnedTask(deps, ctx, args.task_id);
+            if (found.error)
+                return found.error;
+            const task = found.task;
+            if (!task.sessionId) {
+                return {
+                    ok: false,
+                    text: `Task ${task.id} has no prior session to resume. ` +
+                        `Use task_retry_fresh instead.`,
+                };
+            }
+            const hint = typeof args.hint === "string" ? args.hint.trim() : "";
+            const nextDescription = hint
+                ? appendContinuationHint(task.description, hint)
+                : stripContinuationHint(task.description ?? "");
+            const cleanedLabels = task.labels.filter((l) => l !== INTERVENTION_LABEL && l !== "stalled");
+            updateTask(deps.db, task.id, {
+                labels: cleanedLabels,
+                description: nextDescription || null,
+                // Don't clear sessionId — LLMWorker.run keys off it +
+                // attempts>0 to pick up the prior transcript.
+                startedAt: null,
+                endedAt: null,
+                interventionReason: null,
+                interventionAt: null,
+            });
+            deps.onTaskWrite();
+            return {
+                ok: true,
+                text: `Resuming task ${task.id} on session ${task.sessionId}` +
+                    (hint ? ` with hint: ${hint.slice(0, 120)}` : "") +
+                    ".",
+            };
+        },
+    };
+}
+export function buildTaskRetryFreshTool(deps) {
+    return {
+        schema: {
+            name: "task_retry_fresh",
+            description: "Revive an awaiting-intervention task by starting a brand new " +
+                "worker session (the prior transcript is left in place but " +
+                "unused). Pass an optional `description` to rewrite the brief " +
+                "— useful when the original prompt itself was the problem. " +
+                "For resume-with-context use `task_continue` instead.",
+            parameters: Type.Object({
+                task_id: Type.String(),
+                description: Type.Optional(Type.String({
+                    description: "Replace the task description. Omit to keep the existing one. " +
+                        "Continuation hints from prior attempts are stripped — a " +
+                        "fresh retry shouldn't carry resume notes.",
+                })),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const found = loadOwnedTask(deps, ctx, args.task_id);
+            if (found.error)
+                return found.error;
+            const task = found.task;
+            const cleanedLabels = task.labels.filter((l) => l !== INTERVENTION_LABEL && l !== "stalled");
+            // Detach the prior session so LLMWorker.run takes the
+            // fresh-start branch (`shouldResume` false).
+            const patch = {
+                labels: cleanedLabels,
+                sessionId: null,
+                attempts: 0,
+                failureReason: null,
+                startedAt: null,
+                endedAt: null,
+                interventionReason: null,
+                interventionAt: null,
+            };
+            if (typeof args.description === "string") {
+                patch.description = args.description.trim() || null;
+            }
+            else {
+                // Even when not rewriting, drop any continuation-hint
+                // block left over from previous task_continue calls.
+                patch.description = stripContinuationHint(task.description ?? "") || null;
+            }
+            updateTask(deps.db, task.id, patch);
+            deps.onTaskWrite();
+            return {
+                ok: true,
+                text: `Reset task ${task.id} for a fresh worker session` +
+                    (typeof args.description === "string" ? " with revised description" : "") +
+                    ".",
+            };
+        },
+    };
+}
+export function buildTaskExtendTimeoutTool(deps) {
+    return {
+        schema: {
+            name: "task_extend_timeout",
+            description: "Grow a task's wall-clock budget. Pass `additional_ms` to add to " +
+                "the existing timeout, or `set_ms` to override absolutely. If " +
+                "the task is currently in_progress the watchdog picks the new " +
+                "value up on its next tick (no restart needed). If it's parked " +
+                "in awaiting-intervention specifically because of a watchdog " +
+                "timeout, this tool ALSO revives the row — you don't have to " +
+                "chain a separate task_continue.",
+            parameters: Type.Object({
+                task_id: Type.String(),
+                additional_ms: Type.Optional(Type.Number({
+                    description: "Milliseconds to add to the current timeout_ms. Either this " +
+                        "or `set_ms` must be present.",
+                })),
+                set_ms: Type.Optional(Type.Number({
+                    description: "Absolute new timeout_ms. Overrides additional_ms when both " +
+                        "are passed.",
+                })),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const found = loadOwnedTask(deps, ctx, args.task_id);
+            if (found.error)
+                return found.error;
+            const task = found.task;
+            let nextTimeout;
+            if (typeof args.set_ms === "number" && Number.isFinite(args.set_ms)) {
+                nextTimeout = Math.max(1000, Math.floor(args.set_ms));
+            }
+            else if (typeof args.additional_ms === "number" &&
+                Number.isFinite(args.additional_ms)) {
+                nextTimeout = Math.max(1000, Math.floor((task.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS) + args.additional_ms));
+            }
+            else {
+                return {
+                    ok: false,
+                    text: "pass either `additional_ms` or `set_ms`",
+                };
+            }
+            const patch = {
+                timeoutMs: nextTimeout,
+            };
+            // If the row is currently parked because of a timeout,
+            // revive it the same way task_continue would. We detect a
+            // timeout-parked row by the canonical reason prefix the
+            // watchdog writes.
+            const wasTimeoutParked = task.labels.includes(INTERVENTION_LABEL) &&
+                (task.interventionReason ?? "").startsWith("watchdog timeout");
+            if (wasTimeoutParked) {
+                patch.labels = task.labels.filter((l) => l !== INTERVENTION_LABEL && l !== "stalled");
+                patch.startedAt = null;
+                patch.endedAt = null;
+                patch.interventionReason = null;
+                patch.interventionAt = null;
+            }
+            updateTask(deps.db, task.id, patch);
+            if (wasTimeoutParked)
+                deps.onTaskWrite();
+            const summary = wasTimeoutParked
+                ? `Extended task ${task.id} timeout to ${nextTimeout}ms and resumed it.`
+                : `Extended task ${task.id} timeout to ${nextTimeout}ms.`;
+            return { ok: true, text: summary };
+        },
+    };
+}
+export function buildTaskAbortTool(deps) {
+    return {
+        schema: {
+            name: "task_abort",
+            description: "Give up on a task. Marks it `done` with a failure summary so " +
+                "any downstream dependents stop waiting, and cancels the " +
+                "in-flight worker run if one is still going. Use when retry / " +
+                "continue won't help (bad spec, blocked by missing data, " +
+                "infrastructure broken).",
+            parameters: Type.Object({
+                task_id: Type.String(),
+                reason: Type.String({
+                    description: "One- or two-sentence explanation. Stored as the task's " +
+                        "result_summary so the user / downstream tasks see why.",
+                }),
+            }),
+        },
+        execute: (raw, ctx) => {
+            const args = raw;
+            const found = loadOwnedTask(deps, ctx, args.task_id);
+            if (found.error)
+                return found.error;
+            const task = found.task;
+            const reason = (args.reason ?? "").trim();
+            if (!reason) {
+                return { ok: false, text: "reason is required" };
+            }
+            // Cancel any live runner first so it doesn't keep eating
+            // tokens past abort.
+            const cancelled = deps.onTaskCancel?.(task.id) ?? false;
+            const cleanedLabels = task.labels.filter((l) => l !== INTERVENTION_LABEL && l !== "stalled");
+            updateTask(deps.db, task.id, {
+                status: "done",
+                labels: cleanedLabels,
+                resultSummary: `[aborted] ${reason}`.slice(0, 800),
+                endedAt: Date.now(),
+                interventionReason: null,
+                interventionAt: null,
+            });
+            // Done unblocks dependents — nudge.
+            deps.onTaskWrite();
+            return {
+                ok: true,
+                text: `Aborted task ${task.id}: ${reason}` +
+                    (cancelled ? " (cancelled in-flight worker)" : "") +
+                    ".",
+            };
+        },
+    };
+}
+/**
+ * Special agent tool the LLM worker calls to wrap up the task it
+ * was assigned. The agent-loop's wrapper picks the structured
+ * `summary` / `files` fields off the return value and resolves the
+ * loop with `status=done`. Calling this tool is the *only* way for
+ * an LLM worker to mark its task complete — walking off without it
+ * leaves the loop stalled.
+ *
+ * The tool intentionally has no side-effect on the workboard's
+ * tasks table itself — the LLMWorker class writes the row using
+ * the captured summary/files, keeping the agent ignorant of the
+ * caller's task id. (An LLM that didn't know the task id couldn't
+ * forge a completion for someone else's task.)
+ */
+/**
+ * Read the host's LLM model catalog. Designed for the main
+ * (orchestrator) agent so it can pick a `modelId` for new
+ * worker bundles instead of guessing or asking the user. Workers
+ * can't see this tool (deny-listed in tool-policy.ts).
+ */
+export function buildModelListTool() {
+    return {
+        schema: {
+            name: "model_list",
+            description: "List the LLM models the host can use for worker bundles. " +
+                "Returns id (e.g. `anthropic/claude-sonnet-4-6`), provider, " +
+                "context window, reasoning flag, plus the host's default model. " +
+                "Use this when authoring `agent.json` so `modelId` points at a " +
+                "real entry rather than a guess.",
+            parameters: Type.Object({}),
+        },
+        available: (ctx) => ctx.capabilities.has("host.modelCatalog") && ctx.agentScope?.kind === "main",
+        execute: (_raw, ctx) => {
+            const cap = ctx.capabilities.get("host.modelCatalog");
+            if (!cap) {
+                return {
+                    ok: false,
+                    text: "host.modelCatalog capability not available on this host",
+                };
+            }
+            const { models, defaultModelId } = cap.list();
+            if (models.length === 0) {
+                return {
+                    ok: true,
+                    text: "No models registered. Host config has no `models.providers` " +
+                        "entries; ask the user to add a provider before pinning a worker.",
+                    data: { models: [], defaultModelId: null },
+                };
+            }
+            // One-line summary plus a structured payload so the agent
+            // can pick a model without re-parsing the text.
+            const lines = models.map((m) => {
+                const tag = m.id === defaultModelId ? " (default)" : "";
+                const reason = m.reasoning ? " reasoning" : "";
+                return `- ${m.id}${tag} — ${m.name} [${m.provider}, ctx=${m.contextWindow}${reason}]`;
+            });
+            return {
+                ok: true,
+                text: `Host offers ${models.length} model${models.length === 1 ? "" : "s"}` +
+                    (defaultModelId ? ` (default: ${defaultModelId})` : "") +
+                    `:\n${lines.join("\n")}`,
+                data: { models, defaultModelId },
+            };
+        },
+    };
+}
+export function buildTaskCompleteTool() {
+    return {
+        schema: {
+            name: "task_complete",
+            description: "Call this when you have finished the task you were assigned. " +
+                "Pass a one-line `summary` of what you produced and an optional " +
+                "list of `files` you wrote (paths under your home dir). After this " +
+                "call, the worker terminates and the orchestrator reads your summary.",
+            parameters: Type.Object({
+                summary: Type.String({
+                    description: "One-line summary of the result. Required.",
+                }),
+                files: Type.Optional(Type.Array(Type.String(), {
+                    description: "Optional list of output file paths the worker produced.",
+                })),
+            }),
+        },
+        execute: (raw) => {
+            const args = raw;
+            const summary = typeof args.summary === "string" ? args.summary.trim() : "";
+            if (!summary) {
+                return { ok: false, text: "summary is required" };
+            }
+            const files = Array.isArray(args.files)
+                ? args.files.filter((f) => typeof f === "string")
+                : [];
+            // The agent-loop wrapper picks up the canonical summary/files
+            // off the *arguments* the agent passed (see
+            // `wrappedExecutors[task_complete]` in chat/agent-loop.ts), so
+            // we don't need to thread them through the return shape.
+            return {
+                ok: true,
+                text: "Task marked complete. The worker will exit.",
+                data: { summary, files },
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map