qcanvas-local-agent 0.1.0

package/dist/http-server.js

@@ -0,0 +1,275 @@
+import http from "node:http";
+import { CONFIG_FILE, ensureCanvasWorkspace, loadConfig, rememberOrigin, saveConfig, setCanvasActiveThread, VERSION, } from "./config.js";
+import { CanvasSession } from "./canvas-session.js";
+import { archiveCodexThread, listCodexThreads, LOCAL_AGENTS, readCodexThread, resumeCodexThread, runClaudeTurn, runCodexTurn, startCodexThread, summarizeCodexThread, verifyCodexThreadWorkspace, withAgentPrompt, } from "./agents.js";
+const MAX_BODY_BYTES = 30 * 1024 * 1024;
+function readOrigin(req) {
+    const value = req.headers.origin;
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function sendCors(res, origin) {
+    if (origin) {
+        res.setHeader("access-control-allow-origin", origin);
+        res.setHeader("vary", "origin");
+    }
+    res.setHeader("access-control-allow-methods", "GET,POST,OPTIONS");
+    res.setHeader("access-control-allow-headers", "content-type,x-qcanvas-agent-token,x-canvas-agent-token");
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function sendError(res, status, error) {
+    sendJson(res, status, { ok: false, error });
+}
+function readToken(req, url) {
+    const qToken = url.searchParams.get("token");
+    if (qToken && qToken.trim())
+        return qToken.trim();
+    const qcanvasHeader = req.headers["x-qcanvas-agent-token"];
+    if (typeof qcanvasHeader === "string" && qcanvasHeader.trim())
+        return qcanvasHeader.trim();
+    const legacyHeader = req.headers["x-canvas-agent-token"];
+    if (typeof legacyHeader === "string" && legacyHeader.trim())
+        return legacyHeader.trim();
+    return null;
+}
+function assertAuthorized(req, url, config) {
+    const token = readToken(req, url);
+    if (!token || token !== config.token)
+        throw new Error("invalid QCanvas local agent token");
+}
+function assertOrigin(config, origin) {
+    if (!origin || config.origins.length === 0 || config.origins.includes(origin))
+        return;
+    throw new Error(`origin is not allowed for this local agent: ${origin}`);
+}
+async function readBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.byteLength;
+        if (total > MAX_BODY_BYTES)
+            throw new Error("request body is too large");
+        chunks.push(buffer);
+    }
+    const text = Buffer.concat(chunks).toString("utf8").trim();
+    if (!text)
+        return {};
+    return JSON.parse(text);
+}
+function readClientId(ctx, body) {
+    const fromQuery = ctx.url.searchParams.get("clientId");
+    if (fromQuery && fromQuery.trim())
+        return fromQuery.trim();
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+        const fromBody = body.clientId;
+        if (typeof fromBody === "string" && fromBody.trim())
+            return fromBody.trim();
+    }
+    return null;
+}
+async function routeRequest(ctx, session, configRef) {
+    const { req, res, url, origin } = ctx;
+    sendCors(res, origin);
+    if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    if (req.method === "GET" && url.pathname === "/health") {
+        sendJson(res, 200, {
+            ok: true,
+            version: VERSION,
+            configFile: CONFIG_FILE,
+            ...session.health(),
+        });
+        return;
+    }
+    if (req.method === "GET" && url.pathname === "/config") {
+        sendJson(res, 200, {
+            ok: true,
+            url: configRef.current.url,
+            hasToken: true,
+            configFile: CONFIG_FILE,
+        });
+        return;
+    }
+    assertAuthorized(req, url, configRef.current);
+    assertOrigin(configRef.current, origin);
+    configRef.current = rememberOrigin(configRef.current, origin);
+    if (req.method === "GET" && url.pathname === "/events") {
+        session.openEvents(url.searchParams.get("clientId"), res);
+        return;
+    }
+    if (req.method === "POST" && url.pathname === "/canvas/state") {
+        const body = await readBody(req);
+        const clientId = readClientId(ctx, body);
+        if (!clientId)
+            throw new Error("canvas state missing clientId");
+        const snapshot = session.updateState(body, clientId);
+        sendJson(res, 200, { ok: true, updatedAt: snapshot.updatedAt });
+        return;
+    }
+    if (req.method === "POST" && url.pathname === "/canvas/result") {
+        const body = await readBody(req);
+        session.resolveResult(body && typeof body === "object" && !Array.isArray(body) ? body : {});
+        sendJson(res, 200, { ok: true });
+        return;
+    }
+    if (req.method === "POST" && url.pathname === "/api/tools") {
+        const body = await readBody(req);
+        const record = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+        const result = await session.callTool(record.name, record.input, readString(record.agent));
+        const envelope = { ok: true, result };
+        sendJson(res, 200, envelope);
+        return;
+    }
+    if (url.pathname.startsWith("/agent/")) {
+        await routeAgentRequest(ctx, session, configRef);
+        return;
+    }
+    sendError(res, 404, `unknown local agent route: ${req.method || "GET"} ${url.pathname}`);
+}
+function readRecordBody(body) {
+    return body && typeof body === "object" && !Array.isArray(body) ? body : {};
+}
+function readAttachments(value) {
+    return Array.isArray(value) ? value : [];
+}
+function readString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function isEmptySavedCodexThreadError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("no rollout found for thread id");
+}
+async function routeAgentRequest(ctx, session, configRef) {
+    const { req, res, url } = ctx;
+    const method = req.method || "GET";
+    const emit = (type, payload) => session.emitAll(type, payload);
+    const config = configRef.current;
+    if (method === "GET" && url.pathname === "/agent/list") {
+        sendJson(res, 200, { ok: true, agents: LOCAL_AGENTS });
+        return;
+    }
+    if (method === "GET" && url.pathname === "/agent/codex/workspace") {
+        const workspace = ensureCanvasWorkspace(config, url.searchParams.get("canvasId") || "");
+        sendJson(res, 200, { ok: true, workspace });
+        return;
+    }
+    if (method === "GET" && url.pathname === "/agent/codex/threads") {
+        const workspace = ensureCanvasWorkspace(config, url.searchParams.get("canvasId") || "");
+        const result = await listCodexThreads(emit, {
+            cwd: workspace.workspacePath,
+            searchTerm: url.searchParams.get("searchTerm") || "",
+        });
+        sendJson(res, 200, { ok: true, workspace, ...result });
+        return;
+    }
+    if (method === "POST" && url.pathname === "/agent/codex/threads/new") {
+        const body = readRecordBody(await readBody(req));
+        const workspace = ensureCanvasWorkspace(config, String(body.canvasId || ""));
+        const thread = await startCodexThread(emit, workspace.workspacePath);
+        const activeThreadId = String(thread.id || "");
+        const updated = setCanvasActiveThread(config, workspace.canvasId, "codex", activeThreadId);
+        sendJson(res, 200, { ok: true, workspace: updated, thread: summarizeCodexThread(thread), messages: [] });
+        return;
+    }
+    const threadMatch = url.pathname.match(/^\/agent\/codex\/threads\/([^/]+)(\/resume|\/delete)?$/);
+    if (threadMatch) {
+        const threadId = decodeURIComponent(threadMatch[1] || "");
+        const action = threadMatch[2] || "";
+        if (method === "GET" && !action) {
+            const workspace = ensureCanvasWorkspace(config, url.searchParams.get("canvasId") || "");
+            sendJson(res, 200, { ok: true, workspace, ...(await readCodexThread(emit, threadId, workspace.workspacePath)) });
+            return;
+        }
+        if (method === "POST" && action === "/resume") {
+            const body = readRecordBody(await readBody(req));
+            const workspace = ensureCanvasWorkspace(config, String(body.canvasId || ""));
+            const result = await resumeCodexThread(emit, threadId, workspace.workspacePath);
+            const updated = setCanvasActiveThread(config, workspace.canvasId, "codex", threadId);
+            sendJson(res, 200, { ok: true, workspace: updated, ...result });
+            return;
+        }
+        if (method === "POST" && action === "/delete") {
+            const body = readRecordBody(await readBody(req));
+            const workspace = ensureCanvasWorkspace(config, String(body.canvasId || ""));
+            await archiveCodexThread(emit, threadId, workspace.workspacePath);
+            if (workspace.activeThreadIds.codex === threadId)
+                setCanvasActiveThread(config, workspace.canvasId, "codex", "");
+            sendJson(res, 200, { ok: true });
+            return;
+        }
+    }
+    if (method === "POST" && url.pathname === "/agent/codex/turn") {
+        const body = readRecordBody(await readBody(req));
+        const attachments = readAttachments(body.attachments);
+        const workspace = ensureCanvasWorkspace(config, String(body.canvasId || ""));
+        const requestedThreadId = readString(body.threadId);
+        let threadId = requestedThreadId || workspace.activeThreadIds.codex || "";
+        if (!threadId) {
+            const thread = await startCodexThread(emit, workspace.workspacePath);
+            threadId = String(thread.id || "");
+            setCanvasActiveThread(config, workspace.canvasId, "codex", threadId);
+        }
+        else {
+            try {
+                await verifyCodexThreadWorkspace(emit, threadId, workspace.workspacePath);
+            }
+            catch (error) {
+                if (requestedThreadId || !isEmptySavedCodexThreadError(error))
+                    throw error;
+                emit("agent_log", { agent: "codex", text: `Saved Codex thread ${threadId} has no rollout; starting a new local thread.` });
+                const thread = await startCodexThread(emit, workspace.workspacePath);
+                threadId = String(thread.id || "");
+            }
+            setCanvasActiveThread(config, workspace.canvasId, "codex", threadId);
+        }
+        void runCodexTurn(withAgentPrompt(String(body.prompt || "")), emit, attachments, { threadId, cwd: workspace.workspacePath });
+        sendJson(res, 200, { ok: true, threadId });
+        return;
+    }
+    if (method === "POST" && url.pathname === "/agent/claude/turn") {
+        const body = readRecordBody(await readBody(req));
+        const attachments = readAttachments(body.attachments);
+        const workspace = ensureCanvasWorkspace(config, String(body.canvasId || ""));
+        const requestedThreadId = readString(body.threadId);
+        const threadId = requestedThreadId || workspace.activeThreadIds.claude || "";
+        void runClaudeTurn(withAgentPrompt(String(body.prompt || "")), emit, attachments, {
+            ...(threadId ? { threadId } : {}),
+            cwd: workspace.workspacePath,
+            command: config.claudeCommand,
+            allowFreshFallback: !requestedThreadId,
+            onThread: (sessionId) => {
+                setCanvasActiveThread(config, workspace.canvasId, "claude", sessionId);
+            },
+        });
+        sendJson(res, 200, { ok: true, threadId: threadId || null });
+        return;
+    }
+    sendError(res, 404, `unknown local agent route: ${method} ${url.pathname}`);
+}
+export async function startHttpServer() {
+    const configRef = { current: loadConfig(true) };
+    saveConfig(configRef.current);
+    const session = new CanvasSession();
+    const server = http.createServer((req, res) => {
+        const origin = readOrigin(req);
+        const url = new URL(req.url || "/", configRef.current.url);
+        void routeRequest({ req, res, url, origin }, session, configRef).catch((error) => {
+            sendCors(res, origin);
+            const message = error instanceof Error ? error.message : "QCanvas local agent request failed";
+            sendError(res, 500, message);
+        });
+    });
+    await new Promise((resolve) => {
+        server.listen(configRef.current.port, configRef.current.host, resolve);
+    });
+    console.log(`QCanvas Local Agent ${VERSION}`);
+    console.log(`Local URL: ${configRef.current.url}`);
+    console.log(`Connect token: ${configRef.current.token}`);
+    console.log(`Config: ${CONFIG_FILE}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { startHttpServer } from "./http-server.js";
+import { startMcpServer } from "./mcp-server.js";
+const mode = process.argv[2] || "http";
+if (mode === "mcp") {
+    await startMcpServer();
+}
+else {
+    await startHttpServer();
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): Promise<void>;

package/dist/mcp-server.js

@@ -0,0 +1,49 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig, VERSION } from "./config.js";
+import { localAgentToolDescriptions, localAgentToolInputSchemas, localAgentToolNames, } from "./schemas.js";
+const INSTRUCTIONS = [
+    "Use QCanvas local tools only for the connected live browser canvas.",
+    "Read tapcanvas_flow_get before writing.",
+    "Prefer tapcanvas_create_generation_flow over tapcanvas_flow_patch when creating a single generation node with reference wiring; it auto-computes placement, handles, and reference asset inputs. It only creates the node and never submits generation by itself.",
+    "All tapcanvas_flow_patch writes (including those issued by tapcanvas_create_generation_flow) are confirmed by the browser before they apply.",
+    "If no live browser tab is connected, report the error directly.",
+].join("\n");
+export async function startMcpServer() {
+    const config = loadConfig(true);
+    // 由启动方（codex/claude 驱动的 mcp 配置）注入，标记工具调用来自哪个智能体。
+    const agentId = (process.env.QCANVAS_AGENT_ID || "").trim();
+    const server = new McpServer({ name: "qcanvas-local-agent", version: VERSION }, { instructions: INSTRUCTIONS });
+    for (const toolName of localAgentToolNames) {
+        registerTool(server, config.url, config.token, toolName, agentId);
+    }
+    await server.connect(new StdioServerTransport());
+}
+function registerTool(server, url, token, name, agentId) {
+    const schema = localAgentToolInputSchemas[name];
+    server.registerTool(name, {
+        description: localAgentToolDescriptions[name],
+        inputSchema: schema.shape,
+    }, async (input) => {
+        const parsed = schema.parse(input);
+        const result = await postTool(url, token, name, parsed, agentId);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+async function postTool(url, token, name, input, agentId) {
+    const response = await fetch(`${url}/api/tools`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-qcanvas-agent-token": token,
+        },
+        body: JSON.stringify({ name, input, ...(agentId ? { agent: agentId } : {}) }),
+    });
+    const body = await response.json();
+    if (!response.ok || !body.ok) {
+        throw new Error(body.error || `QCanvas local tool failed: ${response.status}`);
+    }
+    return body.result;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,257 @@
+import { z } from "zod";
+export declare const localAgentToolNames: readonly ["tapcanvas_flow_get", "tapcanvas_create_generation_flow", "tapcanvas_flow_patch"];
+export type LocalAgentToolName = (typeof localAgentToolNames)[number];
+export declare const localAgentToolInputSchemas: {
+    tapcanvas_flow_get: z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>;
+    tapcanvas_create_generation_flow: z.ZodObject<{
+        kind: z.ZodString;
+        prompt: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>>;
+        referenceNodeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        referenceImageUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        model: z.ZodOptional<z.ZodString>;
+        aspect: z.ZodOptional<z.ZodString>;
+        groupId: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: string;
+        prompt: string;
+        position?: {
+            x: number;
+            y: number;
+        } | undefined;
+        label?: string | undefined;
+        referenceNodeIds?: string[] | undefined;
+        referenceImageUrls?: string[] | undefined;
+        model?: string | undefined;
+        aspect?: string | undefined;
+        groupId?: string | undefined;
+        nodeId?: string | undefined;
+    }, {
+        kind: string;
+        prompt: string;
+        position?: {
+            x: number;
+            y: number;
+        } | undefined;
+        label?: string | undefined;
+        referenceNodeIds?: string[] | undefined;
+        referenceImageUrls?: string[] | undefined;
+        model?: string | undefined;
+        aspect?: string | undefined;
+        groupId?: string | undefined;
+        nodeId?: string | undefined;
+    }>;
+    tapcanvas_flow_patch: z.ZodObject<{
+        allowOverwrite: z.ZodOptional<z.ZodBoolean>;
+        deleteNodeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deleteEdgeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        createNodes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodEnum<["taskNode", "groupNode"]>;
+            position: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            parentId: z.ZodOptional<z.ZodString>;
+            selected: z.ZodOptional<z.ZodBoolean>;
+            draggable: z.ZodOptional<z.ZodBoolean>;
+            selectable: z.ZodOptional<z.ZodBoolean>;
+            focusable: z.ZodOptional<z.ZodBoolean>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodEnum<["taskNode", "groupNode"]>;
+            position: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            parentId: z.ZodOptional<z.ZodString>;
+            selected: z.ZodOptional<z.ZodBoolean>;
+            draggable: z.ZodOptional<z.ZodBoolean>;
+            selectable: z.ZodOptional<z.ZodBoolean>;
+            focusable: z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodEnum<["taskNode", "groupNode"]>;
+            position: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            parentId: z.ZodOptional<z.ZodString>;
+            selected: z.ZodOptional<z.ZodBoolean>;
+            draggable: z.ZodOptional<z.ZodBoolean>;
+            selectable: z.ZodOptional<z.ZodBoolean>;
+            focusable: z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">>, "many">>;
+        createEdges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            source: z.ZodString;
+            target: z.ZodString;
+            sourceHandle: z.ZodOptional<z.ZodString>;
+            targetHandle: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodString;
+            source: z.ZodString;
+            target: z.ZodString;
+            sourceHandle: z.ZodOptional<z.ZodString>;
+            targetHandle: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodString;
+            source: z.ZodString;
+            target: z.ZodString;
+            sourceHandle: z.ZodOptional<z.ZodString>;
+            targetHandle: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.ZodTypeAny, "passthrough">>, "many">>;
+        patchNodeData: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            data: Record<string, unknown>;
+        }, {
+            id: string;
+            data: Record<string, unknown>;
+        }>, "many">>;
+        appendNodeArrays: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            key: z.ZodString;
+            items: z.ZodArray<z.ZodUnknown, "many">;
+        }, "strip", z.ZodTypeAny, {
+            key: string;
+            id: string;
+            items: unknown[];
+        }, {
+            key: string;
+            id: string;
+            items: unknown[];
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        allowOverwrite?: boolean | undefined;
+        deleteNodeIds?: string[] | undefined;
+        deleteEdgeIds?: string[] | undefined;
+        createNodes?: z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodEnum<["taskNode", "groupNode"]>;
+            position: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            parentId: z.ZodOptional<z.ZodString>;
+            selected: z.ZodOptional<z.ZodBoolean>;
+            draggable: z.ZodOptional<z.ZodBoolean>;
+            selectable: z.ZodOptional<z.ZodBoolean>;
+            focusable: z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        createEdges?: z.objectOutputType<{
+            id: z.ZodString;
+            source: z.ZodString;
+            target: z.ZodString;
+            sourceHandle: z.ZodOptional<z.ZodString>;
+            targetHandle: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        patchNodeData?: {
+            id: string;
+            data: Record<string, unknown>;
+        }[] | undefined;
+        appendNodeArrays?: {
+            key: string;
+            id: string;
+            items: unknown[];
+        }[] | undefined;
+    }, {
+        allowOverwrite?: boolean | undefined;
+        deleteNodeIds?: string[] | undefined;
+        deleteEdgeIds?: string[] | undefined;
+        createNodes?: z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodEnum<["taskNode", "groupNode"]>;
+            position: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                x: number;
+                y: number;
+            }, {
+                x: number;
+                y: number;
+            }>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            parentId: z.ZodOptional<z.ZodString>;
+            selected: z.ZodOptional<z.ZodBoolean>;
+            draggable: z.ZodOptional<z.ZodBoolean>;
+            selectable: z.ZodOptional<z.ZodBoolean>;
+            focusable: z.ZodOptional<z.ZodBoolean>;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        createEdges?: z.objectInputType<{
+            id: z.ZodString;
+            source: z.ZodString;
+            target: z.ZodString;
+            sourceHandle: z.ZodOptional<z.ZodString>;
+            targetHandle: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        patchNodeData?: {
+            id: string;
+            data: Record<string, unknown>;
+        }[] | undefined;
+        appendNodeArrays?: {
+            key: string;
+            id: string;
+            items: unknown[];
+        }[] | undefined;
+    }>;
+};
+export declare const localAgentToolDescriptions: Record<LocalAgentToolName, string>;
+export declare function isLocalAgentToolName(value: unknown): value is LocalAgentToolName;

package/dist/schemas.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+const recordSchema = z.record(z.unknown());
+const finitePositionSchema = z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+});
+const createNodeSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.enum(["taskNode", "groupNode"]),
+    position: finitePositionSchema,
+    data: recordSchema,
+    parentId: z.string().min(1).optional(),
+    selected: z.boolean().optional(),
+    draggable: z.boolean().optional(),
+    selectable: z.boolean().optional(),
+    focusable: z.boolean().optional(),
+})
+    .passthrough();
+const createEdgeSchema = z
+    .object({
+    id: z.string().min(1),
+    source: z.string().min(1),
+    target: z.string().min(1),
+    sourceHandle: z.string().min(1).optional(),
+    targetHandle: z.string().min(1).optional(),
+    type: z.string().min(1).optional(),
+    label: z.string().optional(),
+    data: recordSchema.optional(),
+})
+    .passthrough();
+const patchNodeDataSchema = z.object({
+    id: z.string().min(1),
+    data: recordSchema,
+});
+const appendNodeArraySchema = z.object({
+    id: z.string().min(1),
+    key: z.string().min(1),
+    items: z.array(z.unknown()).min(1),
+});
+const createGenerationFlowSchema = z.object({
+    kind: z.string().min(1),
+    prompt: z.string().min(1),
+    label: z.string().min(1).optional(),
+    position: finitePositionSchema.optional(),
+    referenceNodeIds: z.array(z.string().min(1)).optional(),
+    referenceImageUrls: z.array(z.string().min(1)).optional(),
+    model: z.string().min(1).optional(),
+    aspect: z.string().min(1).optional(),
+    groupId: z.string().min(1).optional(),
+    nodeId: z.string().min(1).optional(),
+});
+export const localAgentToolNames = [
+    "tapcanvas_flow_get",
+    "tapcanvas_create_generation_flow",
+    "tapcanvas_flow_patch",
+];
+export const localAgentToolInputSchemas = {
+    tapcanvas_flow_get: z.object({}).passthrough(),
+    tapcanvas_create_generation_flow: createGenerationFlowSchema,
+    tapcanvas_flow_patch: z.object({
+        allowOverwrite: z.boolean().optional(),
+        deleteNodeIds: z.array(z.string().min(1)).optional(),
+        deleteEdgeIds: z.array(z.string().min(1)).optional(),
+        createNodes: z.array(createNodeSchema).optional(),
+        createEdges: z.array(createEdgeSchema).optional(),
+        patchNodeData: z.array(patchNodeDataSchema).optional(),
+        appendNodeArrays: z.array(appendNodeArraySchema).optional(),
+    }),
+};
+export const localAgentToolDescriptions = {
+    tapcanvas_flow_get: "Read the live QCanvas graph from the connected browser tab. Use this before any patch.",
+    tapcanvas_create_generation_flow: "Create one runnable taskNode for a generation intent, auto-placed next to existing nodes and auto-wired to referenceNodeIds via real edges + assetInputs/referenceImages carrying those nodes' current output image. This only creates and wires the node; it does NOT submit generation. Call tapcanvas_flow_patch's browser-side runner (or ask the user to run the node) to actually generate.",
+    tapcanvas_flow_patch: "Request a browser-confirmed QCanvas graph patch. The browser must approve the write before it is applied.",
+};
+export function isLocalAgentToolName(value) {
+    return typeof value === "string" && localAgentToolNames.includes(value);
+}