@zq-silk/yui 2.3.0 → 2.4.0

package/dist/web/webServer.js

@@ -3,7 +3,10 @@ import { createServer } from "node:http";
 import WebSocket, { WebSocketServer } from "ws";
 import { CliError, usageError } from "../errors/cliError.js";
 import { parseTaskCatalogOptions } from "../context/taskCatalog.js";
+import { parseTaskSearchOptions, searchTaskBodies } from "../context/taskSearch.js";
+import { readTaskUsage } from "../runtime/taskUsageQuery.js";
 import { WebRequestRejected } from "./webMutation.js";
+import { SETTINGS_HTML } from "./assets/shell/settings.js";
 import { TASK_SUBMISSION_INTENTS } from "../message/message.js";
 import { DASHBOARD_HTML, findWebAsset } from "./assets/assetManifest.js";
 import { buildWebTaskCatalog, buildWebPageSessions, buildWebTaskDetail } from "./webSnapshot.js";
@@ -39,13 +42,14 @@ export function parseWebCommandOptions(args) {
 export function createYuiWebServer(store, dependencies = {}) {
     const now = dependencies.now ?? (() => new Date());
     const token = dependencies.token ?? randomBytes(24).toString("base64url");
+    const httpDependencies = { ...dependencies, previews: dependencies.previews?.() };
     const webSocketServer = new WebSocketServer({
         noServer: true,
         perMessageDeflate: false,
         maxPayload: MAX_TERMINAL_MESSAGE_BYTES
     });
     const server = createServer((request, response) => {
-        void handleHttpRequest(request, response, store, dependencies, token, now).catch(() => {
+        void handleHttpRequest(request, response, store, httpDependencies, token, now).catch(() => {
             if (!response.headersSent)
                 setSecurityHeaders(response);
             if (!response.writableEnded) {
@@ -100,7 +104,229 @@ async function handleHttpRequest(request, response, store, dependencies, token,
         sendJson(response, 403, { error: "Invalid Yui web token.", disposition: "not-submitted" }, method === "HEAD");
         return;
     }
+    if (pathname.startsWith("/preview/") && dependencies.previews) {
+        await dependencies.previews.serve(request, response);
+        return;
+    }
+    const previewMatch = /^\/api\/tasks\/([A-Za-z0-9_-]+)\/previews(?:\/([A-Za-z0-9_-]+)\/stop)?$/.exec(pathname);
+    if (previewMatch && dependencies.previews) {
+        try {
+            if (method === "GET" && !previewMatch[2]) {
+                sendJson(response, 200, await dependencies.previews.list(previewMatch[1]), false);
+            }
+            else if (method === "POST" && previewMatch[2]) {
+                const body = await readMutationBody(request);
+                if (!body || typeof body !== "object" || Array.isArray(body) || Object.keys(body).length) {
+                    throw new WebRequestRejected("Stop accepts an empty object; the URL selects the exact service.");
+                }
+                sendJson(response, 200, dependencies.previews.stop(previewMatch[1], previewMatch[2]), false);
+            }
+            else
+                sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, false);
+        }
+        catch (error) {
+            sendJson(response, error instanceof WebRequestRejected ? 409 : 500, {
+                error: error instanceof Error ? error.message : "Preview request failed.",
+                disposition: error instanceof WebRequestRejected ? "not-submitted" : "unknown"
+            }, false);
+        }
+        return;
+    }
+    if ((pathname === "/api/tasks" || pathname === "/api/projects") && dependencies.surface) {
+        try {
+            if (pathname === "/api/projects" && method === "GET") {
+                const query = new URL(request.url, "http://localhost").searchParams;
+                if ([...query.keys()].some(key => key !== "after") || query.getAll("after").length > 1) {
+                    throw new WebRequestRejected("Project listing accepts only one after cursor.");
+                }
+                sendJson(response, 200, dependencies.surface.projects(query.get("after") ?? undefined), false);
+            }
+            else if (pathname === "/api/tasks" && method === "POST") {
+                const body = await readMutationBody(request);
+                if (!body || typeof body !== "object" || Array.isArray(body)
+                    || Object.keys(body).some(key => !["title", "requirements", "projectIds", "plan", "requestId"].includes(key))
+                    || !("title" in body) || typeof body.title !== "string" || !body.title.trim() || body.title.length > 200
+                    || !("requirements" in body) || typeof body.requirements !== "string" || !body.requirements.trim()
+                    || !("projectIds" in body) || !Array.isArray(body.projectIds) || body.projectIds.length > 32
+                    || body.projectIds.some(id => typeof id !== "string" || !/^project-[a-zA-Z0-9_-]+$/.test(id))
+                    || !("plan" in body) || typeof body.plan !== "boolean"
+                    || !("requestId" in body) || typeof body.requestId !== "string" || !body.requestId.trim()) {
+                    throw new WebRequestRejected("Expected title, requirements, projectIds, plan and requestId only.");
+                }
+                sendJson(response, 200, { ...dependencies.surface.create(body), requestId: body.requestId }, false);
+            }
+            else
+                sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, false);
+        }
+        catch (error) {
+            sendJson(response, 409, { error: error instanceof Error ? error.message : "Creation unavailable.",
+                disposition: error instanceof WebRequestRejected ? "not-submitted" : "unknown" }, false);
+        }
+        return;
+    }
+    if (pathname.startsWith("/api/skills/")) {
+        try {
+            const service = dependencies.skills;
+            if (!service)
+                throw new WebRequestRejected("Skill service unavailable.");
+            const q = new URL(request.url, "http://localhost").searchParams;
+            if ([...q.keys()].some(k => !["scope", "task", "role", "id", "resource", "frozen", "digest", "run", "q", "cursor"].includes(k)
+                || q.getAll(k).length !== 1))
+                throw new WebRequestRejected("Unknown or duplicate Skill query.");
+            if (q.has("frozen") && !["true", "false"].includes(q.get("frozen"))
+                || q.has("run") && q.get("frozen") !== "true")
+                throw new WebRequestRejected("A Run read requires an explicit frozen version.");
+            const selected = { scope: q.get("scope"), role: q.get("role"), ...(q.has("task") ? { task: q.get("task") } : {}) };
+            let value;
+            if (method === "GET" && pathname === "/api/skills/catalog")
+                value = service.catalog(q.get("q") ?? "", q.get("cursor") ?? "0");
+            else if (method === "GET" && pathname === "/api/skills/roles")
+                value = service.roles(q.get("scope") ?? "", q.get("task") ?? undefined);
+            else if (method === "GET" && pathname === "/api/skills/role")
+                value = service.role(selected);
+            else if (method === "GET" && pathname === "/api/skills/file")
+                value = service.file({
+                    id: q.get("id") ?? "", resource: q.get("resource") ?? undefined,
+                    frozen: q.get("frozen") === "true", digest: q.get("digest") ?? undefined, run: q.get("run") ?? undefined, target: selected
+                });
+            else if (method === "POST" && pathname === "/api/skills/role")
+                value = service.save(await readMutationBody(request));
+            else {
+                sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, false);
+                return;
+            }
+            sendJson(response, 200, value, false);
+        }
+        catch (error) {
+            sendJson(response, 409, { error: error instanceof Error ? error.message : "Skill operation unavailable.",
+                disposition: method === "GET" || error instanceof WebRequestRejected ? "not-submitted" : "unknown" }, false);
+        }
+        return;
+    }
+    if (pathname === "/api/settings" || pathname === "/api/settings/group" || pathname === "/api/settings/capabilities") {
+        try {
+            if (!dependencies.settings)
+                throw new WebRequestRejected("Settings service unavailable.");
+            const query = new URL(request.url, "http://localhost").searchParams;
+            if ([...query.keys()].some(k => !["id", "refresh", "q", "cursor"].includes(k)))
+                throw new WebRequestRejected("Unknown settings query.");
+            let value;
+            if (method === "GET" && pathname === "/api/settings")
+                value = dependencies.settings.index(query.get("q") ?? "", query.get("cursor") ?? "0");
+            else if (method === "GET" && pathname === "/api/settings/group")
+                value = dependencies.settings.read(query.get("id") ?? "");
+            else if (method === "GET" && pathname === "/api/settings/capabilities")
+                value = await dependencies.settings.capabilities(query.get("id") ?? "", query.get("refresh") === "true");
+            else if (method === "POST" && pathname === "/api/settings/group")
+                value = await dependencies.settings.save(await readMutationBody(request));
+            else {
+                sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, false);
+                return;
+            }
+            sendJson(response, 200, value, false);
+        }
+        catch (error) {
+            sendJson(response, 409, { error: error instanceof Error ? error.message : "Settings unavailable.",
+                disposition: error instanceof WebRequestRejected ? "not-submitted" : "unknown" }, false);
+        }
+        return;
+    }
     const artifactTarget = /^\/api\/tasks\/([^/]+)\/(artifacts|evidence)$/.exec(pathname);
+    if (["/api/conversation", "/api/conversation/material", "/api/conversation/model"].includes(pathname) && dependencies.conversation) {
+        try {
+            const q = new URL(request.url, "http://localhost").searchParams;
+            if ([...q.keys()].some(k => !["scope", "task", "role", "session", "cursor", "offset", "requestId"].includes(k))) {
+                throw new WebRequestRejected("Unknown conversation parameter.");
+            }
+            const roleName = safeIdentity(q.get("role"), "Role");
+            const owner = q.get("scope") === "task"
+                ? { scope: "task", taskId: safeIdentity(q.get("task"), "Task"), roleName }
+                : q.get("scope") === "global" && !q.has("task") ? { scope: "global", roleName }
+                    : (() => { throw new WebRequestRejected("Invalid conversation scope."); })();
+            let result;
+            if (pathname.endsWith("/model")) {
+                const id = safeIdentity(q.get("session"), "Session");
+                if (method === "GET")
+                    result = await dependencies.conversation.models(owner, id);
+                else if (method === "POST") {
+                    const body = await readMutationBody(request);
+                    if (!body || typeof body !== "object" || Array.isArray(body)
+                        || Object.keys(body).some(k => k !== "model")
+                        || typeof body.model !== "string") {
+                        throw new WebRequestRejected("Expected one native model selection.");
+                    }
+                    result = await dependencies.conversation.setModel(owner, id, body.model);
+                }
+                else
+                    throw new WebRequestRejected("Model access requires GET or POST.");
+            }
+            else if (pathname.endsWith("/material")) {
+                if (method !== "POST")
+                    throw new WebRequestRejected("Material upload requires POST.");
+                const body = await readMutationBody(request, 2 * 1024 * 1024);
+                if (!body || typeof body !== "object" || Array.isArray(body)
+                    || Object.keys(body).some(k => !["requestId", "name", "content"].includes(k))) {
+                    throw new WebRequestRejected("Expected material requestId, name and UTF-8 content only.");
+                }
+                const value = body;
+                if (typeof value.requestId !== "string" || typeof value.name !== "string" || typeof value.content !== "string") {
+                    throw new WebRequestRejected("Invalid material fields.");
+                }
+                result = await dependencies.conversation.material(owner, safeIdentity(q.get("session"), "Session"), value);
+            }
+            else if (method === "GET" && q.has("requestId")) {
+                result = dependencies.conversation.receipt(owner, safeIdentity(q.get("requestId"), "Request"));
+            }
+            else if (method === "GET" && q.has("session")) {
+                const cursor = q.get("cursor");
+                if (cursor !== null && cursor.length > 16000)
+                    throw new WebRequestRejected("Cursor too large.");
+                result = await dependencies.conversation.history(owner, safeIdentity(q.get("session"), "Session"), cursor ?? undefined);
+            }
+            else if (method === "GET") {
+                const offset = q.get("offset") ?? "0";
+                if (!/^\d{1,6}$/.test(offset))
+                    throw new WebRequestRejected("Invalid session offset.");
+                result = dependencies.conversation.state(owner, Number(offset));
+            }
+            else if (method === "POST") {
+                const body = await readMutationBody(request);
+                if (!body || typeof body !== "object" || Array.isArray(body)
+                    || Object.keys(body).some(k => !["action", "requestId", "body", "expectedTarget", "materials", "nativeRequestId", "result"].includes(k))) {
+                    throw new WebRequestRejected("Invalid conversation input.");
+                }
+                const value = body;
+                if (value.action === "native-respond") {
+                    if ((typeof value.nativeRequestId !== "string" && typeof value.nativeRequestId !== "number")
+                        || (typeof value.expectedTarget !== "string" && value.expectedTarget !== null)
+                        || !value.result || typeof value.result !== "object" || Array.isArray(value.result)) {
+                        throw new WebRequestRejected("Expected exact native request and Turn response.");
+                    }
+                    result = await dependencies.conversation.respond(owner, safeIdentity(q.get("session"), "Session"), value.nativeRequestId, value.expectedTarget, value.result);
+                    sendJson(response, 200, result, false);
+                    return;
+                }
+                if (!["queue", "steer", "interrupt"].includes(String(value.action))
+                    || typeof value.requestId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(value.requestId)
+                    || value.body !== undefined && typeof value.body !== "string"
+                    || value.expectedTarget !== undefined && typeof value.expectedTarget !== "string"
+                    || value.materials !== undefined && (!Array.isArray(value.materials) || value.materials.length > 8)) {
+                    throw new WebRequestRejected("Expected action, requestId, input and exact Turn.");
+                }
+                result = await dependencies.conversation.control(owner, safeIdentity(q.get("session"), "Session"), value);
+            }
+            else {
+                sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, false);
+                return;
+            }
+            sendJson(response, 200, result, false);
+        }
+        catch (error) {
+            sendJson(response, 409, { error: error instanceof Error ? error.message : "Conversation unavailable.",
+                disposition: error instanceof WebRequestRejected ? "not-submitted" : "unknown" }, false);
+        }
+        return;
+    }
     if (artifactTarget && dependencies.surface) {
         if (method !== "GET") {
             sendJson(response, 405, { error: "Artifacts are read-only." }, false);
@@ -115,15 +341,21 @@ async function handleHttpRequest(request, response, store, dependencies, token,
                 sendJson(response, 200, dependencies.surface.evidence(taskId), false);
                 return;
             }
-            if ([...query.keys()].some(key => !["path", "commit"].includes(key))) {
-                throw new WebRequestRejected("Artifact read accepts only path and commit.");
+            if ([...query.keys()].some(key => !["path", "commit", "before", "offset"].includes(key) || query.getAll(key).length !== 1)) {
+                throw new WebRequestRejected("Artifact read accepts path, fixed commits and offset only.");
             }
             const path = query.get("path");
             const commit = query.get("commit");
-            if ((path === null) !== (commit === null))
-                throw new WebRequestRejected("Select path and fixed commit together.");
-            const result = path === null ? await dependencies.surface.artifacts(taskId)
-                : await dependencies.surface.artifact(taskId, path, commit);
+            const before = query.get("before");
+            const offset = query.get("offset") ?? "0";
+            if (!/^\d{1,9}$/u.test(offset))
+                throw new WebRequestRejected("Invalid artifact offset.");
+            if (path !== null && commit === null || before !== null && path === null
+                || Number(offset) > 0 && commit === null)
+                throw new WebRequestRejected("Select a fixed commit for this read.");
+            const result = path === null ? await dependencies.surface.artifacts(taskId, commit ?? undefined, Number(offset))
+                : before === null ? await dependencies.surface.artifact(taskId, path, commit, Number(offset))
+                    : await dependencies.surface.artifactDiff(taskId, path, commit, before, Number(offset));
             sendJson(response, 200, result, false);
         }
         catch (error) {
@@ -194,7 +426,7 @@ async function handleHttpRequest(request, response, store, dependencies, token,
         }
         return;
     }
-    const surfaceTarget = /^\/api\/tasks\/([^/]+)\/(context|delta|inspect|list|metadata|messages|control)$/.exec(pathname);
+    const surfaceTarget = /^\/api\/tasks\/([^/]+)\/(workbench|context|delta|inspect|search-source|list|metadata|messages|control|activate|archive)$/.exec(pathname);
     if (surfaceTarget && dependencies.surface) {
         try {
             let taskId;
@@ -207,7 +439,21 @@ async function handleHttpRequest(request, response, store, dependencies, token,
             const action = surfaceTarget[2];
             const query = new URL(request.url, "http://localhost").searchParams;
             let value;
-            if (method === "GET" && action === "context") {
+            if (method === "POST" && (action === "activate" || action === "archive")) {
+                const body = await readMutationBody(request);
+                if (!body || typeof body !== "object" || Array.isArray(body)
+                    || Object.keys(body).some(key => key !== "requestId")
+                    || !("requestId" in body) || typeof body.requestId !== "string" || !body.requestId.trim()) {
+                    throw new WebRequestRejected("Expected requestId only.");
+                }
+                value = { requestId: body.requestId, result: action === "activate"
+                        ? dependencies.surface.activate(taskId, body.requestId)
+                        : await dependencies.surface.archive(taskId) };
+            }
+            else if (method === "GET" && action === "workbench") {
+                value = dependencies.surface.workbench(taskId);
+            }
+            else if (method === "GET" && action === "context") {
                 value = await dependencies.surface.read(taskId);
             }
             else if (method === "GET" && action === "delta") {
@@ -216,6 +462,15 @@ async function handleHttpRequest(request, response, store, dependencies, token,
                     ...(query.has("continuation") ? { continuation: query.get("continuation") } : {})
                 });
             }
+            else if (method === "GET" && action === "search-source") {
+                const offset = query.get("offset") ?? "0";
+                if (!/^\d{1,12}$/.test(offset))
+                    throw new WebRequestRejected("Invalid source offset.");
+                value = dependencies.surface.searchSource(taskId, {
+                    store: query.get("store") ?? "", refId: query.get("ref") ?? "",
+                    digest: query.get("digest") ?? "", field: query.get("field") ?? "", offset: Number(offset)
+                });
+            }
             else if (method === "GET" && action === "inspect") {
                 value = dependencies.surface.inspect(taskId, {
                     store: query.get("store") ?? "", refId: query.get("ref") ?? "",
@@ -273,12 +528,20 @@ async function handleHttpRequest(request, response, store, dependencies, token,
     if (method === "GET" || method === "HEAD") {
         try {
             const asset = findWebAsset(pathname);
-            if (pathname === "/" || pathname === "/index.html") {
-                sendText(response, 200, "text/html; charset=utf-8", dashboardHtml(token), method === "HEAD");
+            if (pathname === "/" || pathname === "/index.html" || pathname === "/settings") {
+                sendText(response, 200, "text/html; charset=utf-8", pathname === "/settings" ? SETTINGS_HTML.replace("__YUI_WEB_TOKEN__", token) : dashboardHtml(token), method === "HEAD");
             }
             else if (asset !== null) {
                 sendAsset(response, asset, method === "HEAD");
             }
+            else if (pathname === "/api/search") {
+                const query = new URL(request.url, "http://localhost").searchParams;
+                if (query.getAll("query").length !== 1)
+                    throw usageError("Search requires one query.");
+                const options = parseTaskSearchOptions([query.get("query"),
+                    ...[...query].filter(([key]) => key !== "query").flatMap(([key, value]) => [`--${key}`, value])]);
+                sendJson(response, 200, store.transaction(reader => searchTaskBodies(reader, options)), method === "HEAD");
+            }
             else if (pathname === "/api/dashboard" || pathname === "/api/dashboard/sessions") {
                 const query = new URL(request.url, "http://localhost").searchParams;
                 const options = parseTaskCatalogOptions([...query].flatMap(([key, value]) => key === "all"
@@ -289,11 +552,22 @@ async function handleHttpRequest(request, response, store, dependencies, token,
                     : buildWebTaskCatalog(store, options);
                 sendJson(response, 200, snapshot, method === "HEAD");
             }
+            else if (/^\/api\/tasks\/[^/]+\/usage$/u.test(pathname)) {
+                const taskId = decodeURIComponent(pathname.split("/")[3]);
+                const query = new URL(request.url, "http://localhost").searchParams;
+                const offset = Number(query.get("offset") ?? 0), limit = Number(query.get("limit") ?? 0);
+                if ([...query.keys()].some(key => key !== "offset" && key !== "limit")
+                    || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 0 || limit > 50) {
+                    throw usageError("Usage requires offset >= 0 and limit 0..50.");
+                }
+                const value = store.readTransaction(reader => readTaskUsage(reader, taskId, { offset, limit, now: now() }));
+                sendJson(response, value === null ? 404 : 200, value ?? { error: "Task not found." }, method === "HEAD");
+            }
             else if (pathname.startsWith("/api/tasks/")) {
                 const taskId = decodeURIComponent(pathname.slice("/api/tasks/".length));
                 const detail = taskId.length === 0 || taskId.includes("/")
                     ? null
-                    : buildWebTaskDetail(store, taskId, now());
+                    : buildWebTaskDetail(store, taskId, now(), new URL(request.url, "http://localhost").searchParams.get("compact") === "true");
                 sendJson(response, detail === null ? 404 : 200, detail ?? { error: "Task not found." }, method === "HEAD");
             }
             else {
@@ -466,10 +740,12 @@ function parseTerminalRequest(parameters) {
     const roleName = safeIdentity(parameters.get("role"), "Role");
     const columns = boundedInteger(parameters.get("cols"), 20, 400, "Terminal columns");
     const rows = boundedInteger(parameters.get("rows"), 5, 200, "Terminal rows");
+    const selection = parameters.has("session")
+        ? { nativeSessionId: safeIdentity(parameters.get("session"), "Session") } : {};
     if (scope === "global") {
         if (parameters.has("task"))
             throw new Error("Global terminal cannot include a Task.");
-        return { scope, roleName, columns, rows };
+        return { scope, roleName, columns, rows, ...selection };
     }
     if (scope === "task") {
         return {
@@ -477,7 +753,8 @@ function parseTerminalRequest(parameters) {
             taskId: safeIdentity(parameters.get("task"), "Task"),
             roleName,
             columns,
-            rows
+            rows,
+            ...selection
         };
     }
     throw new Error("Terminal scope is invalid.");
@@ -616,9 +893,9 @@ function parseWebInputAnswer(value) {
     }
     throw new Error("Exactly one non-empty choiceKey or text is required.");
 }
-async function readMutationBody(request) {
+async function readMutationBody(request, limit = MAX_JSON_BODY_BYTES) {
     try {
-        return await readJsonBody(request);
+        return await readJsonBody(request, limit);
     }
     catch (error) {
         throw new WebRequestRejected(error instanceof Error ? error.message : "Invalid request body.");
@@ -636,13 +913,13 @@ function webSubmissionIntent(body) {
     }
     throw new WebRequestRejected(`intent must be one of ${TASK_SUBMISSION_INTENTS.join(", ")}.`);
 }
-async function readJsonBody(request) {
+async function readJsonBody(request, limit = MAX_JSON_BODY_BYTES) {
     const chunks = [];
     let size = 0;
     for await (const chunk of request) {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         size += buffer.length;
-        if (size > MAX_JSON_BODY_BYTES)
+        if (size > limit)
             throw new Error("Request body is too large.");
         chunks.push(buffer);
     }