forge-openclaw-plugin 0.2.26 → 0.2.27

package/dist/server/server/src/web.js

@@ -1,5 +1,8 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 const distDir = path.join(process.cwd(), "dist");
 const packagedRuntimeDistDir = path.join(process.cwd(), "plugins", "forge-codex", "runtime", "dist");
 const contentTypes = {
@@ -17,7 +20,9 @@ function normalizeBasePath(value) {
         return "/";
     }
     const withLeadingSlash = value.startsWith("/") ? value : `/${value}`;
-    return withLeadingSlash.endsWith("/") ? withLeadingSlash : `${withLeadingSlash}/`;
+    return withLeadingSlash.endsWith("/")
+        ? withLeadingSlash
+        : `${withLeadingSlash}/`;
 }
 function normalizeAbsoluteUrl(value) {
     const url = new URL(value);
@@ -31,6 +36,56 @@ function getDevWebOrigin() {
     const value = process.env.FORGE_DEV_WEB_ORIGIN?.trim();
     return value && value.length > 0 ? value : null;
 }
+function shouldAutostartDevWeb(env) {
+    const value = env.FORGE_DEV_WEB_AUTOSTART?.trim().toLowerCase();
+    return value !== "0" && value !== "false" && value !== "no";
+}
+function getDevWebCommand(env) {
+    const value = env.FORGE_DEV_WEB_COMMAND?.trim();
+    return value && value.length > 0 ? value : "npm run dev:web";
+}
+function getDefaultDevWebOriginPort(origin) {
+    if (origin?.port && origin.port.trim().length > 0) {
+        return origin.port;
+    }
+    if (origin?.protocol === "https:") {
+        return "443";
+    }
+    return "3027";
+}
+function getDefaultViteCliPath(cwd) {
+    const candidate = path.join(cwd, "node_modules", "vite", "bin", "vite.js");
+    return existsSync(candidate) ? candidate : null;
+}
+function buildManagedDevWebLaunch(input) {
+    const explicitCommand = input.env.FORGE_DEV_WEB_COMMAND?.trim();
+    if (explicitCommand && explicitCommand.length > 0) {
+        return {
+            command: explicitCommand,
+            env: input.env,
+            shell: true
+        };
+    }
+    const viteCliPath = getDefaultViteCliPath(input.cwd);
+    if (!viteCliPath) {
+        return {
+            command: getDevWebCommand(input.env),
+            env: input.env,
+            shell: true
+        };
+    }
+    const host = input.env.FORGE_DEV_WEB_HOST?.trim() || "127.0.0.1";
+    const port = input.env.FORGE_DEV_WEB_PORT?.trim() || getDefaultDevWebOriginPort(input.origin);
+    return {
+        command: process.execPath,
+        args: [viteCliPath, "--host", host, "--port", port],
+        env: {
+            ...input.env,
+            FORGE_BASE_PATH: getDefaultBasePath()
+        },
+        shell: false
+    };
+}
 function stripBasePath(requestPath, basePath) {
     const normalizedBasePath = normalizeBasePath(basePath);
     if (normalizedBasePath === "/") {
@@ -63,19 +118,174 @@ async function getClientDir() {
         return packagedRuntimeDistDir;
     }
 }
-async function serveAsset(requestPath, reply) {
-    if (requestPath.startsWith("/api")) {
+function parseRequestTarget(requestPath) {
+    return new URL(requestPath, "http://forge.local");
+}
+function copyProxyHeaders(response, reply) {
+    for (const [name, value] of response.headers) {
+        const lowerName = name.toLowerCase();
+        if (lowerName === "connection" ||
+            lowerName === "content-length" ||
+            lowerName === "keep-alive" ||
+            lowerName === "transfer-encoding") {
+            continue;
+        }
+        reply.header(name, value);
+    }
+}
+async function proxyDevAsset(input) {
+    const target = new URL(input.pathname.startsWith("/") ? input.pathname.slice(1) : input.pathname, input.origin);
+    target.search = input.search;
+    const response = await input.fetchImpl(target, { redirect: "manual" });
+    input.reply.code(response.status);
+    copyProxyHeaders(response, input.reply);
+    if (!response.headers.has("cache-control")) {
+        input.reply.header("Cache-Control", "no-store, max-age=0, must-revalidate");
+    }
+    if (!response.body) {
+        return "";
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+async function waitForProcessExit(child, timeoutMs = 5_000) {
+    if (child.exitCode !== null) {
+        return;
+    }
+    await Promise.race([
+        new Promise((resolve) => {
+            child.once("exit", () => resolve());
+            child.once("close", () => resolve());
+        }),
+        delay(timeoutMs).then(() => { })
+    ]);
+}
+export function createManagedDevWebRuntime(options = {}) {
+    const env = options.env ?? process.env;
+    const originValue = env.FORGE_DEV_WEB_ORIGIN?.trim();
+    const origin = originValue ? normalizeAbsoluteUrl(originValue) : null;
+    const cwd = options.cwd ?? process.cwd();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const autostart = shouldAutostartDevWeb(env);
+    const waitTimeoutMs = Number(env.FORGE_DEV_WEB_START_TIMEOUT_MS ?? 30_000);
+    const pollIntervalMs = 500;
+    let child = null;
+    let startupPromise = null;
+    async function probe() {
+        if (!origin) {
+            return null;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1_500);
+        try {
+            const response = await fetchImpl(origin, {
+                method: "GET",
+                redirect: "manual",
+                signal: controller.signal
+            });
+            return response.status < 500 ? origin : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async function waitUntilReady(processRef) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < waitTimeoutMs) {
+            const readyOrigin = await probe();
+            if (readyOrigin) {
+                return readyOrigin;
+            }
+            if (processRef.exitCode !== null) {
+                break;
+            }
+            await delay(pollIntervalMs);
+        }
+        return null;
+    }
+    async function ensureReady() {
+        if (!origin) {
+            return null;
+        }
+        const readyOrigin = await probe();
+        if (readyOrigin || !autostart) {
+            return readyOrigin;
+        }
+        if (!startupPromise) {
+            startupPromise = (async () => {
+                if (!child || child.exitCode !== null) {
+                    const launch = buildManagedDevWebLaunch({ cwd, env, origin });
+                    const nextChild = launch.shell
+                        ? spawnImpl(launch.command, {
+                            cwd,
+                            env: launch.env,
+                            shell: true,
+                            stdio: "inherit"
+                        })
+                        : spawnImpl(launch.command, launch.args ?? [], {
+                            cwd,
+                            env: launch.env,
+                            stdio: "inherit"
+                        });
+                    child = nextChild;
+                    nextChild.once("exit", () => {
+                        if (child === nextChild) {
+                            child = null;
+                        }
+                    });
+                }
+                const startedOrigin = await waitUntilReady(child);
+                startupPromise = null;
+                return startedOrigin;
+            })().catch((error) => {
+                startupPromise = null;
+                throw error;
+            });
+        }
+        return startupPromise;
+    }
+    async function stop() {
+        if (!child || child.exitCode !== null) {
+            return;
+        }
+        const childRef = child;
+        childRef.kill("SIGTERM");
+        await waitForProcessExit(childRef);
+        if (childRef.exitCode === null) {
+            childRef.kill("SIGKILL");
+            await waitForProcessExit(childRef, 1_000);
+        }
+        child = null;
+    }
+    return {
+        ensureReady,
+        stop
+    };
+}
+async function serveAsset(requestPath, reply, options) {
+    const requestTarget = parseRequestTarget(requestPath);
+    if (requestTarget.pathname.startsWith("/api")) {
         reply.code(404);
         return { error: "Not found" };
     }
-    const normalizedRequestPath = stripBasePath(requestPath, getDefaultBasePath());
-    const devWebOrigin = getDevWebOrigin();
+    const normalizedRequestPath = stripBasePath(requestTarget.pathname, getDefaultBasePath());
+    const devWebOrigin = await options.devWebRuntime.ensureReady();
     if (devWebOrigin) {
-        const target = new URL(normalizedRequestPath.startsWith("/")
-            ? normalizedRequestPath.slice(1)
-            : normalizedRequestPath, normalizeAbsoluteUrl(devWebOrigin));
-        reply.code(307).redirect(target.toString());
-        return reply;
+        try {
+            return await proxyDevAsset({
+                origin: devWebOrigin,
+                pathname: normalizedRequestPath,
+                search: requestTarget.search,
+                reply,
+                fetchImpl: options.fetchImpl
+            });
+        }
+        catch {
+            reply.header("X-Forge-Web-Fallback", "built");
+        }
     }
     const clientDir = await getClientDir();
     const assetPath = resolveAsset(clientDir, normalizedRequestPath);
@@ -111,7 +321,12 @@ async function serveAsset(requestPath, reply) {
         return { error: "Asset not found" };
     }
 }
-export async function registerWebRoutes(app) {
-    app.get("/", async (_request, reply) => serveAsset("/", reply));
-    app.get("/*", async (request, reply) => serveAsset(request.url, reply));
+export async function registerWebRoutes(app, options = {}) {
+    const devWebRuntime = options.devWebRuntime ?? createManagedDevWebRuntime();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    app.addHook("onClose", async () => {
+        await devWebRuntime.stop();
+    });
+    app.get("/", async (_request, reply) => serveAsset("/", reply, { devWebRuntime, fetchImpl }));
+    app.get("/*", async (request, reply) => serveAsset(request.url, reply, { devWebRuntime, fetchImpl }));
 }

package/dist/server/src/components/customization/utility-widgets.js

@@ -4,6 +4,7 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { CalendarDays, CloudSun, ExternalLink, Music4, NotebookPen, Save, TimerReset } from "lucide-react";
 import { createNote, createWikiPage } from "../../lib/api.js";
 import { buildStaticWorkbenchExecution } from "../../lib/workbench/runtime.js";
+import { createContextOutput, createNoteTool, createSummaryOutput } from "../../lib/workbench/contracts.js";
 import { cn } from "../../lib/utils.js";
 import { createGenericWorkbenchNodeView } from "../workbench-boxes/shared/generic-node-view.js";
 function formatMonthGrid(baseDate) {
@@ -175,19 +176,43 @@ const timeWidgetDefinition = {
     tags: ["utility", "clock"],
     inputs: [],
     params: [],
-    output: [{ key: "primary", label: "Current time", kind: "text" }],
+    output: [
+        createSummaryOutput({
+            label: "Current time",
+            description: "Formatted local time string published by the clock widget."
+        }),
+        createContextOutput({
+            key: "clock",
+            label: "Clock state",
+            description: "Structured clock state including the current ISO timestamp.",
+            modelName: "ForgeClockState"
+        })
+    ],
     tools: [],
     NodeView: createGenericWorkbenchNodeView({
         title: "Clock",
         description: "Live local time widget.",
         inputs: [],
         params: [],
-        output: [{ key: "primary", label: "Current time", kind: "text" }],
+        output: [
+            createSummaryOutput({
+                label: "Current time",
+                description: "Formatted local time string published by the clock widget."
+            }),
+            createContextOutput({
+                key: "clock",
+                label: "Clock state",
+                description: "Structured clock state including the current ISO timestamp.",
+                modelName: "ForgeClockState"
+            })
+        ],
         tools: []
     }),
     WebView: TimeWidget,
     execute: (input) => buildStaticWorkbenchExecution(input, {
-        now: input.context.now
+        clock: {
+            now: input.context.now
+        }
     }, new Intl.DateTimeFormat(undefined, {
         hour: "2-digit",
         minute: "2-digit"
@@ -205,19 +230,43 @@ const calendarWidgetDefinition = {
     tags: ["utility", "calendar"],
     inputs: [],
     params: [],
-    output: [{ key: "primary", label: "Month view", kind: "object" }],
+    output: [
+        createSummaryOutput({
+            label: "Month view",
+            description: "Summary of the compact month calendar widget."
+        }),
+        createContextOutput({
+            key: "calendarView",
+            label: "Calendar view",
+            description: "Structured mini-calendar state including the current month anchor.",
+            modelName: "ForgeMiniCalendarView"
+        })
+    ],
     tools: [],
     NodeView: createGenericWorkbenchNodeView({
         title: "Mini calendar",
         description: "Compact month calendar widget.",
         inputs: [],
         params: [],
-        output: [{ key: "primary", label: "Month view", kind: "object" }],
+        output: [
+            createSummaryOutput({
+                label: "Month view",
+                description: "Summary of the compact month calendar widget."
+            }),
+            createContextOutput({
+                key: "calendarView",
+                label: "Calendar view",
+                description: "Structured mini-calendar state including the current month anchor.",
+                modelName: "ForgeMiniCalendarView"
+            })
+        ],
         tools: []
     }),
     WebView: MiniCalendarWidget,
     execute: (input) => buildStaticWorkbenchExecution(input, {
-        now: input.context.now
+        calendarView: {
+            now: input.context.now
+        }
     }, "Compact month calendar")
 };
 MiniCalendarWidget.workbench = calendarWidgetDefinition;
@@ -239,19 +288,43 @@ const spotifyWidgetDefinition = {
         }
     ],
     params: [],
-    output: [{ key: "primary", label: "Spotify link", kind: "text" }],
+    output: [
+        createSummaryOutput({
+            label: "Spotify link",
+            description: "Summary of the pinned music link widget."
+        }),
+        createContextOutput({
+            key: "spotifyLink",
+            label: "Spotify state",
+            description: "Structured Spotify widget state and pinned surface context.",
+            modelName: "ForgeSpotifyWidgetState"
+        })
+    ],
     tools: [],
     NodeView: createGenericWorkbenchNodeView({
         title: "Spotify",
         description: "Pinned music link widget.",
         inputs: [{ key: "surfaceId", label: "Surface id", kind: "text" }],
         params: [],
-        output: [{ key: "primary", label: "Spotify link", kind: "text" }],
+        output: [
+            createSummaryOutput({
+                label: "Spotify link",
+                description: "Summary of the pinned music link widget."
+            }),
+            createContextOutput({
+                key: "spotifyLink",
+                label: "Spotify state",
+                description: "Structured Spotify widget state and pinned surface context.",
+                modelName: "ForgeSpotifyWidgetState"
+            })
+        ],
         tools: []
     }),
     WebView: SpotifyWidget,
     execute: (input) => buildStaticWorkbenchExecution(input, {
-        surfaceId: input.inputs.surfaceId ?? null
+        spotifyLink: {
+            surfaceId: input.inputs.surfaceId ?? null
+        }
     }, "Pinned Spotify link")
 };
 SpotifyWidget.workbench = spotifyWidgetDefinition;
@@ -266,18 +339,40 @@ const weatherWidgetDefinition = {
     tags: ["utility", "weather"],
     inputs: [],
     params: [],
-    output: [{ key: "primary", label: "Weather", kind: "object" }],
+    output: [
+        createSummaryOutput({
+            label: "Weather summary",
+            description: "Summary of the weather widget state."
+        }),
+        createContextOutput({
+            key: "weather",
+            label: "Weather payload",
+            description: "Structured weather widget payload.",
+            modelName: "ForgeWeatherWidgetState"
+        })
+    ],
     tools: [],
     NodeView: createGenericWorkbenchNodeView({
         title: "Weather",
         description: "Location-aware weather widget.",
         inputs: [],
         params: [],
-        output: [{ key: "primary", label: "Weather", kind: "object" }],
+        output: [
+            createSummaryOutput({
+                label: "Weather summary",
+                description: "Summary of the weather widget state."
+            }),
+            createContextOutput({
+                key: "weather",
+                label: "Weather payload",
+                description: "Structured weather widget payload.",
+                modelName: "ForgeWeatherWidgetState"
+            })
+        ],
         tools: []
     }),
     WebView: WeatherWidget,
-    execute: (input) => buildStaticWorkbenchExecution(input, null, "Weather widget")
+    execute: (input) => buildStaticWorkbenchExecution(input, { weather: null }, "Weather widget")
 };
 WeatherWidget.workbench = weatherWidgetDefinition;
 const quickCaptureWidgetDefinition = {
@@ -298,33 +393,47 @@ const quickCaptureWidgetDefinition = {
         }
     ],
     params: [],
-    output: [{ key: "primary", label: "Draft", kind: "content" }],
+    output: [
+        createSummaryOutput({
+            label: "Draft summary",
+            description: "Summary of the quick-capture draft state."
+        }),
+        createContextOutput({
+            key: "draft",
+            label: "Draft context",
+            description: "Structured quick-capture draft context.",
+            modelName: "ForgeQuickCaptureDraft"
+        })
+    ],
     tools: [
-        {
-            key: "forge.create_note",
-            label: "Create note",
-            description: "Create a Forge evidence note from captured markdown.",
-            accessMode: "write"
-        }
+        createNoteTool("Create a Forge evidence note from captured markdown.")
     ],
     NodeView: createGenericWorkbenchNodeView({
         title: "Quick capture",
         description: "Draft a quick note or wiki page.",
         inputs: [{ key: "defaultUserId", label: "Default user id", kind: "text" }],
         params: [],
-        output: [{ key: "primary", label: "Draft", kind: "content" }],
+        output: [
+            createSummaryOutput({
+                label: "Draft summary",
+                description: "Summary of the quick-capture draft state."
+            }),
+            createContextOutput({
+                key: "draft",
+                label: "Draft context",
+                description: "Structured quick-capture draft context.",
+                modelName: "ForgeQuickCaptureDraft"
+            })
+        ],
         tools: [
-            {
-                key: "forge.create_note",
-                label: "Create note",
-                description: "Create a Forge evidence note from captured markdown.",
-                accessMode: "write"
-            }
+            createNoteTool("Create a Forge evidence note from captured markdown.")
         ]
     }),
     WebView: QuickCaptureWidget,
     execute: (input) => buildStaticWorkbenchExecution(input, {
-        defaultUserId: input.inputs.defaultUserId ?? null
+        draft: {
+            defaultUserId: input.inputs.defaultUserId ?? null
+        }
     }, "Quick capture can draft notes and wiki pages.")
 };
 QuickCaptureWidget.workbench = quickCaptureWidgetDefinition;

package/dist/server/src/components/ui/info-tooltip.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { CircleHelp } from "lucide-react";
+import { cn } from "@/lib/utils";
+export function FieldHint({ children, className }) {
+    return _jsx("div", { className: cn("text-sm leading-6 text-white/50", className), children: children });
+}
+export function InfoTooltip({ content, label = "Explain this field", className }) {
+    const [open, setOpen] = useState(false);
+    const containerRef = useRef(null);
+    const tooltipId = useId();
+    useEffect(() => {
+        if (!open) {
+            return;
+        }
+        const handlePointerDown = (event) => {
+            if (!containerRef.current?.contains(event.target)) {
+                setOpen(false);
+            }
+        };
+        document.addEventListener("pointerdown", handlePointerDown);
+        return () => document.removeEventListener("pointerdown", handlePointerDown);
+    }, [open]);
+    return (_jsxs("span", { ref: containerRef, className: cn("relative inline-flex items-center", className), onMouseEnter: () => setOpen(true), onMouseLeave: () => setOpen(false), children: [_jsx("button", { type: "button", "aria-label": label, "aria-describedby": open ? tooltipId : undefined, "aria-expanded": open, className: "inline-flex size-5 items-center justify-center rounded-full text-white/42 transition hover:bg-white/[0.06] hover:text-white/78 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[rgba(192,193,255,0.35)]", onFocus: () => setOpen(true), onBlur: () => setOpen(false), onClick: () => setOpen((current) => !current), children: _jsx(CircleHelp, { className: "size-3.5" }) }), _jsx("span", { id: tooltipId, role: "tooltip", className: cn("pointer-events-none absolute right-0 top-[calc(100%+0.55rem)] z-40 w-[min(16rem,calc(100vw-2.5rem))] max-w-[calc(100vw-2.5rem)] rounded-[18px] border border-white/8 bg-[rgba(12,17,30,0.96)] px-3 py-2.5 text-sm leading-6 text-white/74 shadow-[0_18px_48px_rgba(3,8,18,0.42)] transition", open ? "translate-y-0 opacity-100" : "translate-y-1 opacity-0"), children: content })] }));
+}

package/dist/server/src/components/workbench-boxes/calendar/calendar-boxes.js

@@ -0,0 +1,78 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { buildSearchWorkbenchExecution, buildStaticWorkbenchExecution } from "../../../lib/workbench/runtime.js";
+import { createSearchEntitiesTool, createSearchInputs, createSearchOutputs, createSearchParams, createSummaryOutput } from "../../../lib/workbench/contracts.js";
+import { createGenericWorkbenchNodeView } from "../shared/generic-node-view.js";
+import { defineWorkbenchBox } from "../shared/define-workbench-box.js";
+function Slot({ children }) {
+    return _jsx(_Fragment, { children: children });
+}
+function defineCalendarBox(id, title, description, tags, execute, output, tools, options) {
+    const inputs = options?.inputs ?? [];
+    const params = options?.params ?? [];
+    return defineWorkbenchBox(Slot, {
+        id,
+        surfaceId: "calendar",
+        routePath: "/calendar",
+        title,
+        icon: "calendar",
+        description,
+        category: "Calendar",
+        tags,
+        inputs,
+        params,
+        output,
+        tools,
+        NodeView: createGenericWorkbenchNodeView({
+            title,
+            description,
+            inputs,
+            params,
+            output,
+            tools
+        }),
+        execute
+    });
+}
+export const CalendarOverviewBox = defineCalendarBox("surface:calendar:overview", "Calendar overview", "Main calendar surface for mirrored events, work blocks, and planned timeboxes.", ["calendar", "overview"], (input) => buildStaticWorkbenchExecution(input, {
+    surfaces: ["events", "work_blocks", "timeboxes"]
+}, "Calendar overview spanning mirrored events, work blocks, and timeboxes."), [createSummaryOutput({ label: "Calendar summary", description: "Summary of mirrored events, work blocks, and timeboxes." })], []);
+export const CalendarEventsBox = defineCalendarBox("surface:calendar:events", "Calendar events", "Mirrored calendar events and Forge-managed calendar records.", ["calendar", "events", "mirrored"], (input) => buildSearchWorkbenchExecution(input, {
+    query: "",
+    entityTypes: ["calendar_event"],
+    limit: 20
+}), createSearchOutputs({
+    itemKind: "calendar_event",
+    itemLabel: "Calendar event"
+}), [createSearchEntitiesTool("Search calendar-backed Forge entities and planning records.")], {
+    inputs: createSearchInputs({
+        itemKind: "calendar_event",
+        itemLabel: "Calendar event",
+        defaultEntityTypes: ["calendar_event"],
+        defaultLimit: 20
+    }),
+    params: createSearchParams({
+        itemKind: "calendar_event",
+        defaultEntityTypes: ["calendar_event"],
+        defaultLimit: 20
+    })
+});
+export const CalendarPlanningBox = defineCalendarBox("surface:calendar:planning", "Planning blocks", "Planned task timeboxes and reusable work block templates.", ["calendar", "planning", "timeboxes"], (input) => buildSearchWorkbenchExecution(input, {
+    query: "",
+    entityTypes: ["task_timebox", "work_block_template"],
+    limit: 20
+}), createSearchOutputs({
+    itemKind: "calendar_plan",
+    itemLabel: "Planning record"
+}), [createSearchEntitiesTool("Search calendar-backed Forge entities and planning records.")], {
+    inputs: createSearchInputs({
+        itemKind: "calendar_plan",
+        itemLabel: "Planning record",
+        defaultEntityTypes: ["task_timebox", "work_block_template"],
+        defaultLimit: 20
+    }),
+    params: createSearchParams({
+        itemKind: "calendar_plan",
+        defaultEntityTypes: ["task_timebox", "work_block_template"],
+        defaultLimit: 20
+    })
+});