@lelouchhe/webagent 0.8.0 → 0.10.0

package/lib/mcp/task-history.js

@@ -0,0 +1,245 @@
+const MAX_RECORD_TEXT = 800;
+const MAX_TOOL_DETAIL = 400;
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function textValue(value) {
+    // Preserve message/code indentation; joinText only removes whitespace around
+    // the final record envelope, never from the text itself.
+    return stringValue(value) ?? "";
+}
+function clip(text, limit) {
+    if (text.length <= limit)
+        return { text, truncated: false };
+    // Keep the ellipsis inside the stated limit, including its separating newline.
+    return { text: `${text.slice(0, limit - 2)}\n…`, truncated: true };
+}
+function joinText(parts) {
+    const truncated = parts.some((part) => isObject(part) && part.truncated === true);
+    const text = parts
+        .map((part) => (typeof part === "string" ? part : (part?.text ?? "")))
+        .filter(Boolean)
+        .join("\n")
+        .trim();
+    const clipped = clip(text, MAX_RECORD_TEXT);
+    return { text: clipped.text, truncated: truncated || clipped.truncated };
+}
+function prefixed(label, value) {
+    return { text: `${label}${value.text}`, truncated: value.truncated };
+}
+function toolContentText(value) {
+    if (!Array.isArray(value))
+        return "";
+    return value
+        .map((item) => {
+        if (!isObject(item))
+            return "";
+        if (isObject(item.content))
+            return textValue(item.content.text);
+        if (Array.isArray(item.content)) {
+            return item.content
+                .map((nested) => (isObject(nested) ? textValue(nested.text) : ""))
+                .filter(Boolean)
+                .join("");
+        }
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function toolInputDetail(value) {
+    if (!isObject(value))
+        return undefined;
+    const command = textValue(value.command);
+    if (command)
+        return prefixed("$ ", clip(command, MAX_TOOL_DETAIL));
+    const path = textValue(value.path);
+    if (path)
+        return prefixed("Path: ", clip(path, MAX_TOOL_DETAIL));
+    return undefined;
+}
+function optionLabel(value) {
+    if (!isObject(value))
+        return "Unknown option";
+    return (textValue(value.label) ||
+        textValue(value.name) ||
+        textValue(value.optionId) ||
+        "Unknown option");
+}
+function planText(entries) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        return undefined;
+    return entries
+        .map((entry) => {
+        if (!isObject(entry))
+            return "- Unknown plan item";
+        const status = textValue(entry.status) || "pending";
+        const content = textValue(entry.content) || "Untitled plan item";
+        return `- [${status}] ${content}`;
+    })
+        .join("\n");
+}
+function malformedRecord(seq, type, createdAt, rawSize) {
+    return {
+        seq,
+        type,
+        createdAt,
+        text: `Unreadable ${type} event; raw payload omitted.`,
+        rawSize,
+    };
+}
+/**
+ * Produce a small deterministic, human-readable task-history record. Raw event
+ * payloads stay in SQLite and are deliberately never embedded in the MCP
+ * response: tool inputs and outputs commonly contain complete source files.
+ */
+// eslint-disable-next-line complexity -- maps the complete persisted event schema.
+export function compactTaskHistoryRecord(record) {
+    const rawSize = Buffer.byteLength(record.data, "utf8");
+    let data;
+    try {
+        data = JSON.parse(record.data);
+    }
+    catch {
+        return malformedRecord(record.seq, record.type, record.createdAt, rawSize);
+    }
+    if (!isObject(data)) {
+        return malformedRecord(record.seq, record.type, record.createdAt, rawSize);
+    }
+    let result;
+    switch (record.type) {
+        case "assistant_message":
+            result = joinText([
+                "Assistant:",
+                textValue(data.text) || "(empty message)",
+            ]);
+            break;
+        case "user_message": {
+            const attachments = Array.isArray(data.attachments)
+                ? `Attachments: ${data.attachments.length}`
+                : undefined;
+            result = joinText([
+                "User:",
+                textValue(data.text) || "(empty message)",
+                attachments,
+            ]);
+            break;
+        }
+        case "tool_call": {
+            const title = textValue(data.title) || "Unnamed tool";
+            const kind = textValue(data.kind);
+            result = joinText([
+                `Tool started: ${title}${kind ? ` (${kind})` : ""}`,
+                toolInputDetail(data.rawInput),
+            ]);
+            break;
+        }
+        case "tool_call_update": {
+            const title = textValue(data.title) || textValue(data.kind) || "Unnamed tool";
+            const status = textValue(data.status) || "updated";
+            const content = toolContentText(data.content);
+            result = joinText([
+                `Tool ${status}: ${title}`,
+                content
+                    ? prefixed("Result:\n", clip(content, MAX_TOOL_DETAIL))
+                    : undefined,
+                toolInputDetail(data.rawInput),
+            ]);
+            break;
+        }
+        case "plan":
+            result = joinText(["Plan:", planText(data.entries) ?? "(empty plan)"]);
+            break;
+        case "permission_request": {
+            const options = Array.isArray(data.options)
+                ? `Options: ${data.options.map(optionLabel).join(", ")}`
+                : undefined;
+            result = joinText([
+                `Permission requested: ${textValue(data.title) || "Unnamed request"}`,
+                options,
+            ]);
+            break;
+        }
+        case "permission_response":
+            result = joinText([
+                `Permission ${data.denied === true ? "denied" : "allowed"}: ${textValue(data.optionName) || "Unnamed option"}`,
+            ]);
+            break;
+        case "prompt_done": {
+            const stopReason = textValue(data.stopReason) || "unknown";
+            // Normal completions add no collaboration information: workflowStatus
+            // already communicates that the task is idle.
+            if (stopReason === "end_turn")
+                return null;
+            result = joinText([`Turn finished: ${stopReason}`]);
+            break;
+        }
+        case "error":
+            result = joinText(["Error:", textValue(data.message) || "Unknown error"]);
+            break;
+        case "system_message":
+            result = joinText([
+                textValue(data.title) || "(empty system message)",
+                textValue(data.body) || undefined,
+            ]);
+            break;
+        case "task_update":
+            result = joinText([
+                `Task ${textValue(data.status) || "updated"}:`,
+                textValue(data.body) || "(no details)",
+            ]);
+            break;
+        case "task_cancel":
+            result = joinText([
+                "Task cancellation requested:",
+                textValue(data.reason) || "(no reason)",
+            ]);
+            break;
+        case "message":
+            result = joinText([
+                `Message from ${textValue(data.from_label) || textValue(data.from_ref) || "unknown sender"}: ${textValue(data.title) || "Untitled"}`,
+                textValue(data.body) || "(empty message)",
+            ]);
+            break;
+        case "bash_command":
+            result = joinText([
+                "Shell command:",
+                `$ ${textValue(data.command) || "(empty command)"}`,
+            ]);
+            break;
+        case "bash_result": {
+            const code = typeof data.code === "number" || typeof data.code === "string"
+                ? String(data.code)
+                : "unknown";
+            const signal = textValue(data.signal);
+            const output = textValue(data.output);
+            result = joinText([
+                `Shell finished: exit ${code}${signal ? `, signal ${signal}` : ""}`,
+                output
+                    ? prefixed("Output:\n", clip(output, MAX_TOOL_DETAIL))
+                    : undefined,
+            ]);
+            break;
+        }
+        default:
+            // New event types are not treated as noise: make their occurrence
+            // visible without risking an arbitrary raw payload in agent context.
+            return {
+                seq: record.seq,
+                type: record.type,
+                createdAt: record.createdAt,
+                text: `Unrecognized ${record.type} event; raw payload omitted.`,
+                rawSize,
+            };
+    }
+    return {
+        seq: record.seq,
+        type: record.type,
+        createdAt: record.createdAt,
+        text: result.text,
+        ...(result.truncated ? { truncated: true, rawSize } : {}),
+    };
+}

package/lib/mcp/task-host.js

@@ -0,0 +1,253 @@
+import { randomUUID } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { isLocalCollaborationTarget, collaborationRelation, } from "../task-collaboration.js";
+import { expandHomePath } from "../home-path.js";
+import { formatTaskReference } from "../shared/task-reference.js";
+import { compactTaskHistoryRecord } from "./task-history.js";
+const DEFAULT_QUERY_LIMIT = 5;
+const MAX_QUERY_LIMIT = 100;
+function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeCursor(raw) {
+    try {
+        const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+        const beforeSeq = parsed.beforeSeq;
+        if (typeof parsed.taskId !== "string" ||
+            typeof beforeSeq !== "number" ||
+            !Number.isInteger(beforeSeq) ||
+            beforeSeq < 1 ||
+            (parsed.text !== undefined && typeof parsed.text !== "string")) {
+            throw new Error("invalid cursor");
+        }
+        return { taskId: parsed.taskId, beforeSeq, text: parsed.text };
+    }
+    catch {
+        throw new Error("invalid_cursor");
+    }
+}
+function relationOrder(relation) {
+    return { self: 0, parent: 1, child: 2, sibling: 3 }[relation];
+}
+export function createMcpTaskToolHost(deps) {
+    const { store, tasks, getBridge, broadcastCollaboration, broadcastTaskCreated, } = deps;
+    function requireTask(taskId) {
+        const task = store.getTask(taskId);
+        if (!task)
+            throw new Error("task_not_found");
+        return task;
+    }
+    function requireLocalTarget(sourceTaskId, targetTaskId) {
+        const source = requireTask(sourceTaskId);
+        const target = requireTask(targetTaskId);
+        if (!isLocalCollaborationTarget(source, target)) {
+            throw new Error("target_not_allowed");
+        }
+        return { source, target };
+    }
+    function requireChildTarget(sourceTaskId, targetTaskId) {
+        const source = requireTask(sourceTaskId);
+        const target = requireTask(targetTaskId);
+        if (target.parent_id !== source.id) {
+            throw new Error("target_not_allowed");
+        }
+        return { source, target };
+    }
+    return {
+        list(sourceTaskId) {
+            const source = requireTask(sourceTaskId);
+            return store
+                .listTasks()
+                .map((task) => {
+                const relation = collaborationRelation(source, task);
+                if (!relation)
+                    return null;
+                return {
+                    id: task.id,
+                    title: task.title ?? task.id,
+                    brief: task.brief || null,
+                    relation,
+                };
+            })
+                .filter((task) => task !== null)
+                .sort((a, b) => relationOrder(a.relation) - relationOrder(b.relation) ||
+                a.id.localeCompare(b.id));
+        },
+        query(sourceTaskId, input) {
+            const targetTaskId = input.taskId ?? sourceTaskId;
+            const { target } = targetTaskId === sourceTaskId
+                ? { target: requireTask(sourceTaskId) }
+                : requireLocalTarget(sourceTaskId, targetTaskId);
+            const cursor = input.cursor ? decodeCursor(input.cursor) : undefined;
+            if (cursor && cursor.taskId !== target.id) {
+                throw new Error("invalid_cursor");
+            }
+            if (cursor && input.text !== undefined && cursor.text !== input.text) {
+                throw new Error("invalid_cursor");
+            }
+            const text = input.text ?? cursor?.text;
+            const limit = Math.min(Math.max(1, input.limit ?? DEFAULT_QUERY_LIMIT), MAX_QUERY_LIMIT);
+            const beforeSeq = cursor?.beforeSeq;
+            const events = store.getEvents(target.id, {
+                excludeThinking: true,
+                beforeSeq,
+                limit,
+                text,
+            });
+            if (events.length === 0) {
+                return {
+                    workflowStatus: target.workflow_status,
+                    records: [],
+                    hasMore: false,
+                };
+            }
+            const firstSeq = events[0].seq;
+            const hasMore = store.getEvents(target.id, {
+                excludeThinking: true,
+                beforeSeq: firstSeq,
+                limit: 1,
+                text,
+            }).length > 0;
+            const records = events
+                .map((event) => compactTaskHistoryRecord({
+                seq: event.seq,
+                type: event.type,
+                data: event.data,
+                createdAt: event.created_at,
+            }))
+                .filter((record) => record !== null);
+            return {
+                workflowStatus: target.workflow_status,
+                records,
+                hasMore,
+                ...(hasMore
+                    ? {
+                        nextCursor: encodeCursor({
+                            taskId: target.id,
+                            beforeSeq: firstSeq,
+                            text,
+                        }),
+                    }
+                    : {}),
+            };
+        },
+        getRecord(sourceTaskId, input) {
+            const targetTaskId = input.taskId ?? sourceTaskId;
+            const { target } = targetTaskId === sourceTaskId
+                ? { target: requireTask(sourceTaskId) }
+                : requireLocalTarget(sourceTaskId, targetTaskId);
+            if (!Number.isInteger(input.seq) || input.seq < 1) {
+                throw new Error("invalid_seq");
+            }
+            const event = store.getEvent(target.id, input.seq);
+            // Thinking is deliberately excluded from task_query and must not be
+            // recoverable through the explicit raw-record escape hatch.
+            if (!event || event.type === "thinking") {
+                throw new Error("record_not_found");
+            }
+            return {
+                taskId: target.id,
+                record: {
+                    id: event.id,
+                    taskId: event.task_id,
+                    seq: event.seq,
+                    type: event.type,
+                    data: event.data,
+                    fromRef: event.from_ref,
+                    createdAt: event.created_at,
+                },
+            };
+        },
+        async create(sourceTaskId, input) {
+            const bridge = getBridge();
+            if (!bridge)
+                throw new Error("agent_not_ready");
+            const source = requireTask(sourceTaskId);
+            const requestedCwd = input.cwd ? expandHomePath(input.cwd) : source.cwd;
+            const cwd = isAbsolute(requestedCwd)
+                ? requestedCwd
+                : resolve(source.cwd, requestedCwd);
+            const created = await tasks.createTask(bridge, cwd, source.id, "agent", {
+                parentId: source.id,
+                title: input.title,
+                model: input.model,
+                thinking: input.thinking,
+            });
+            const taskCreatedMessageId = randomUUID();
+            const taskCreatedTitle = `Created task ${formatTaskReference(input.title)}`;
+            const taskCreatedBody = [
+                `Task ID: ${created.taskId}`,
+                `cwd: ${cwd}`,
+                input.model ? `model: ${input.model}` : "model: inherited",
+                input.thinking ? `thinking: ${input.thinking}` : "thinking: inherited",
+            ].join("\n");
+            store.saveEvent(source.id, "system_message", {
+                kind: "task_created",
+                taskId: created.taskId,
+                taskTitle: input.title,
+                cwd,
+                model: input.model ?? null,
+                thinking: input.thinking ?? null,
+                title: taskCreatedTitle,
+                body: taskCreatedBody,
+            }, { from_ref: "agent" });
+            broadcastTaskCreated?.({
+                messageId: taskCreatedMessageId,
+                sourceTaskId: source.id,
+                targetTaskId: created.taskId,
+                title: taskCreatedTitle,
+                body: taskCreatedBody,
+            });
+            return { taskId: created.taskId };
+        },
+        async cancel(sourceTaskId, targetTaskId, reason) {
+            const bridge = getBridge();
+            const { target } = requireChildTarget(sourceTaskId, targetTaskId);
+            const result = await tasks.cancelTaskExecution(target.id, bridge, deps.cancelTimeoutMs ?? 0);
+            store.saveEvent(target.id, "task_cancel", { sourceTaskId, reason, status: result.status }, { from_ref: "agent" });
+            return { accepted: true, taskId: target.id, status: result.status };
+        },
+        async send(sourceTaskId, targetTaskId, body) {
+            const bridge = getBridge();
+            const { source, target } = requireLocalTarget(sourceTaskId, targetTaskId);
+            const created = store.createCollaborationMessage({
+                id: randomUUID(),
+                deliveryId: randomUUID(),
+                sourceTaskId,
+                directTargetTaskId: target.id,
+                sourceActor: "agent",
+                body,
+            });
+            const sourceLabel = source.title ?? source.id.slice(0, 8);
+            const targetLabel = target.title ?? target.id.slice(0, 8);
+            broadcastCollaboration?.({
+                messageId: created.message.id,
+                sourceTaskId,
+                targetTaskId: target.id,
+                title: `${formatTaskReference(sourceLabel)} sent ${formatTaskReference(targetLabel)}`,
+                body: created.message.body,
+            });
+            if (bridge) {
+                void tasks.drainCollaborationDeliveries(bridge, target.id);
+            }
+        },
+        async update(sourceTaskId, status, body) {
+            const bridge = getBridge();
+            const { parentTaskId, collaborationMessageId } = store.recordAgentWorkflowUpdate(sourceTaskId, status, body);
+            if (collaborationMessageId && parentTaskId) {
+                const source = requireTask(sourceTaskId);
+                const target = requireTask(parentTaskId);
+                broadcastCollaboration?.({
+                    messageId: collaborationMessageId,
+                    sourceTaskId,
+                    targetTaskId: parentTaskId,
+                    title: `${formatTaskReference(source.title ?? source.id.slice(0, 8))} sent ${formatTaskReference(target.title ?? target.id.slice(0, 8))}`,
+                    body: `Task status: ${status}\n${body}`,
+                });
+            }
+            if (bridge && parentTaskId) {
+                void tasks.drainCollaborationDeliveries(bridge, parentTaskId);
+            }
+        },
+    };
+}

package/lib/mcp/tools.js

@@ -0,0 +1,168 @@
+import { z } from "zod";
+const TASK_ID = z.string().trim().min(1).max(256);
+const BODY = z
+    .string()
+    .max(64 * 1024)
+    .refine((value) => value.trim().length > 0, "Body must not be empty");
+function jsonContent(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value) }],
+    };
+}
+function accepted() {
+    return jsonContent({ accepted: true });
+}
+function unavailable() {
+    throw new Error("Task MCP tools are not configured");
+}
+/** Register the Agent-facing Task control-plane tools. */
+export function registerMcpTools(server, taskId, host) {
+    server.registerTool("task_list", {
+        description: "Discover Tasks available for coordination. " +
+            "Use this before choosing a Task to contact.",
+        inputSchema: {},
+    }, async () => jsonContent({ tasks: host?.list(taskId) ?? unavailable() }));
+    server.registerTool("task_query", {
+        description: "Inspect a Task's recorded turn history — what happened and what earlier " +
+            "turns decided. Turn events, including provider errors and attachment " +
+            "metadata, are recorded here. Do not use this tool to wait for work or " +
+            "poll for completion.",
+        inputSchema: {
+            task_id: TASK_ID.nullable()
+                .optional()
+                .describe("Visible Task ID; null or omission defaults to the current Task"),
+            text: z
+                .string()
+                .min(1)
+                .max(256)
+                .nullable()
+                .optional()
+                .describe("Literal text to find; null is treated as omitted"),
+            cursor: z
+                .string()
+                .min(1)
+                .max(512)
+                .nullable()
+                .optional()
+                .describe("Opaque cursor from a previous result; null is omitted"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .nullable()
+                .optional()
+                .describe("Maximum records to return; null uses the default"),
+        },
+    }, async ({ task_id, text, cursor, limit }) => jsonContent(host?.query(taskId, {
+        taskId: task_id ?? undefined,
+        text: text ?? undefined,
+        cursor: cursor ?? undefined,
+        limit: limit ?? undefined,
+    }) ?? unavailable()));
+    server.registerTool("task_get_record", {
+        description: "Inspect one full history record when the available history summary is insufficient. " +
+            "Use a sequence obtained from task_query.",
+        inputSchema: {
+            task_id: TASK_ID.nullable()
+                .optional()
+                .describe("Visible target task ID; null or omission defaults to the current task"),
+            seq: z
+                .number()
+                .int()
+                .min(1)
+                .describe("Stable event sequence within the target task"),
+        },
+    }, async ({ task_id, seq }) => jsonContent(host?.getRecord(taskId, {
+        taskId: task_id ?? undefined,
+        seq,
+    }) ?? unavailable()));
+    server.registerTool("task_create", {
+        description: "Create a direct child Task for independent work. " +
+            "Immediately use task_send to give it the first instruction, then end the dispatch turn without polling.",
+        inputSchema: {
+            title: z
+                .string()
+                .trim()
+                .min(1)
+                .max(256)
+                .refine((value) => !value.includes("/"), "Title must not contain '/'")
+                .describe("Task title"),
+            cwd: z
+                .string()
+                .trim()
+                .min(1)
+                .max(4096)
+                .nullable()
+                .optional()
+                .describe("Working directory; null or omission inherits the current Task"),
+            model: z
+                .string()
+                .trim()
+                .min(1)
+                .max(256)
+                .nullable()
+                .optional()
+                .describe("Model override; null or omission inherits the current Task"),
+            thinking: z
+                .string()
+                .trim()
+                .min(1)
+                .max(64)
+                .nullable()
+                .optional()
+                .describe("Thinking level override; null or omission inherits the current Task"),
+        },
+    }, async ({ title, cwd, model, thinking }) => {
+        if (!host)
+            return unavailable();
+        return jsonContent(await host.create(taskId, {
+            title,
+            cwd: cwd ?? undefined,
+            model: model ?? undefined,
+            thinking: thinking ?? undefined,
+        }));
+    });
+    server.registerTool("task_cancel", {
+        description: "Stop a child Task's current work when it should no longer continue. " +
+            "The Task and its history remain available.",
+        inputSchema: {
+            target: TASK_ID.describe("Stable child Task ID"),
+            reason: BODY.describe("Why the child Task should stop"),
+        },
+    }, async ({ target, reason }) => {
+        if (!host)
+            return unavailable();
+        return jsonContent(await host.cancel(taskId, target, reason));
+    });
+    server.registerTool("task_send", {
+        description: "Send a durable coordination message to another Task. " +
+            "Use it for instructions, questions, findings, progress, decisions, and follow-up. " +
+            "This is communication, not a lifecycle handoff; use task_update(done|blocked) for completion or blocking. " +
+            "Do not wait for or poll the recipient.",
+        inputSchema: {
+            target: TASK_ID.describe("Stable target Task ID"),
+            body: BODY.describe("Verbatim coordination or handoff message"),
+        },
+    }, async ({ target, body }) => {
+        if (!host)
+            return unavailable();
+        await host.send(taskId, target, body);
+        return accepted();
+    });
+    server.registerTool("task_update", {
+        description: "Send a typed lifecycle handoff for the current Task. " +
+            "Use blocked when work needs input or a decision, and done when the assignment is complete. " +
+            "The parent receives the handoff and decides the next step; this does not delete or permanently close the Task. " +
+            "Use task_send for normal communication.",
+        inputSchema: {
+            status: z.enum(["blocked", "done"]),
+            body: BODY.describe("Handoff body: explain the blocker or report the completed result"),
+        },
+    }, async ({ status, body }) => {
+        if (!host)
+            return unavailable();
+        await host.update(taskId, status, body);
+        return accepted();
+    });
+}

package/lib/mode-bucket.js

@@ -1,7 +1,7 @@
 // Cross-agent ACP mode classification.
 //
 // Different agents emit `currentModeId` in different forms:
-//   - Copilot CLI:   "https://agentclientprotocol.com/protocol/session-modes#autopilot"
+//   - Copilot CLI:   "https://agentclientprotocol.com/protocol/task-modes#autopilot"
 //   - Claude Code:   "bypassPermissions" (bare camelCase string)
 //   - Codex:         "read-only" / "auto" / "full-access" (bare hyphenated)
 //   - Gemini CLI:    "default" / "autoEdit" / "yolo" / "plan" (bare; enum-based)