@zq-silk/yui 2.0.0 → 2.1.0

package/dist/nativeAgent/validation.js

@@ -0,0 +1,95 @@
+// JSON escaping can expand a 64 KiB text result to almost 384 KiB.
+export const limits = { messageBytes: 512 * 1024, argumentBytes: 64 * 1024, historyBytes: 1024 * 1024, callsPerStep: 8 };
+export class AgentFault extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function snapshot(value) {
+    const copy = structuredClone(value);
+    const freeze = (item) => {
+        if (item && typeof item === 'object') {
+            for (const child of Object.values(item))
+                freeze(child);
+            Object.freeze(item);
+        }
+    };
+    freeze(copy);
+    return copy;
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) { return typeof value === 'string'; }
+function id(value) { return text(value) && value.trim().length > 0; }
+function json(value, depth = 0) {
+    if (depth > 32)
+        return false;
+    if (value === null || text(value) || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return Array.from(value).every(v => json(v, depth + 1));
+    return object(value) && Object.getPrototypeOf(value) === Object.prototype
+        && Object.values(value).every(v => json(v, depth + 1));
+}
+export function size(value) { return Buffer.byteLength(JSON.stringify(value), 'utf8'); }
+function bounded(value) { return json(value) && size(value) <= limits.messageBytes; }
+function calls(value) {
+    return Array.isArray(value) && value.length <= limits.callsPerStep
+        && value.every(c => object(c) && id(c.id) && id(c.name) && bounded(c.arguments)
+            && size(c.arguments) <= limits.argumentBytes)
+        && new Set(value.map(c => c.id)).size === value.length;
+}
+export function validOutcome(value) {
+    return object(value) && bounded(value) && (value.ok === true ? text(value.content)
+        : value.ok === false && object(value.error) && id(value.error.code) && text(value.error.message)
+            && (value.error.effect === 'none' || value.error.effect === 'unknown'));
+}
+export function response(value, usedIds) {
+    if (!object(value) || !bounded(value) || !text(value.content)
+        || !(value.kind === 'final' || (value.kind === 'tool_calls' && calls(value.calls)
+            && value.calls.length > 0 && value.calls.every(c => !usedIds.has(c.id))))) {
+        throw new AgentFault('provider_protocol', 'Invalid, oversized or duplicate model response');
+    }
+    return snapshot(value);
+}
+export function history(value) {
+    const pending = new Map();
+    const used = new Set();
+    if (!Array.isArray(value) || !json(value) || size(value) > limits.historyBytes) {
+        throw new AgentFault('invalid_history', 'History must be bounded JSON messages');
+    }
+    for (const m of value) {
+        if (!object(m) || !bounded(m))
+            throw new AgentFault('invalid_history', 'Invalid history message');
+        if (m.role === 'tool') {
+            if (!id(m.toolCallId) || !id(m.name) || !validOutcome(m.outcome)
+                || pending.get(m.toolCallId) !== m.name || !pending.has(m.toolCallId)) {
+                throw new AgentFault('invalid_history', 'Tool results must match exactly one pending call');
+            }
+            pending.delete(m.toolCallId);
+        }
+        else {
+            if (pending.size || !text(m.content))
+                throw new AgentFault('invalid_history', 'Unsettled calls or invalid content');
+            if (m.role === 'assistant' && calls(m.toolCalls)) {
+                for (const c of m.toolCalls) {
+                    if (used.has(c.id))
+                        throw new AgentFault('invalid_history', 'Duplicate tool call identity');
+                    used.add(c.id);
+                    pending.set(c.id, c.name);
+                }
+            }
+            else if (m.role !== 'system' && m.role !== 'user') {
+                throw new AgentFault('invalid_history', 'Invalid message role or assistant calls');
+            }
+        }
+    }
+    if (pending.size)
+        throw new AgentFault('invalid_history', 'History contains unsettled calls');
+    return snapshot([...value]);
+}

package/dist/plugins/pluginService.js

@@ -98,24 +98,39 @@ export function createPluginService(store, host, registry) {
         source: `plugin:${pkg.manifest.id}@${pkg.digest}`, required: pkg.manifest.required
     }));
     const refFor = (taskId, pkg) => ({ id: keyFor(taskId, pkg.manifest.id), generation: randomUUID() });
+    const executionParams = (taskId, preparationId, pkg, phase) => ({
+        pluginId: pkg.manifest.id, digest: pkg.digest,
+        environmentRef: `${taskId}/${preparationId}`, trust: "trusted-local", phase
+    });
+    const executionGrant = (taskId, params, path, plannedUses = new Map()) => store.listCapabilityGrants(taskId).find(candidate => Object.entries(params).every(([key, value]) => candidate.parameterBounds[key]?.includes(value))
+        && (candidate.scope.taskId === undefined || candidate.scope.taskId === taskId)
+        && candidate.scope.projectIds === undefined && candidate.scope.repositories === undefined
+        && candidate.scope.packages === undefined
+        && (candidate.scope.homePath === undefined || candidate.scope.homePath === path)
+        && checkGrant({ ...candidate, usesUsed: candidate.usesUsed + (plannedUses.get(candidate.id) ?? 0) }, { action: "plugin.execute", params, irreversibility: "irreversible" }, new Date()).allowed);
+    const environmentAccess = (taskId, preparationId, via) => {
+        const prepared = store.getEnvironmentPreparation(taskId, preparationId);
+        if (!prepared)
+            throw new Error("Plugin environment preparation is missing.");
+        for (const resourceId of prepared.resourceRefs) {
+            const access = resources.assessLocalAccess(taskId, resourceId, prepared.access, via, prepared.id, true);
+            if (access.state !== "authorized")
+                return access;
+        }
+        return { state: "authorized" };
+    };
     /** Each execution consumes one use. A live call's bound closure carries its
      * admission; it is never resumed from a durable reservation or sent to code.
      * Subsequent actions still check current authority, not cached permission. */
     const execution = (taskId, preparationId, pkg, phase) => {
-        const params = { pluginId: pkg.manifest.id, digest: pkg.digest,
-            environmentRef: `${taskId}/${preparationId}`, trust: "trusted-local", phase };
+        const params = executionParams(taskId, preparationId, pkg, phase);
         // This grants the capability to run code without OS effect confinement;
         // it does not claim that every invocation actually has irreversible effects.
         const request = { action: "plugin.execute", params, irreversibility: "irreversible" };
         const reservation = phase === "call" ? undefined : `plugin/${randomUUID()}`;
         const grantId = store.transaction((tx) => {
             const env = environment(taskId, preparationId);
-            const grant = tx.listCapabilityGrants(taskId).find((candidate) => Object.entries(params).every(([key, value]) => candidate.parameterBounds[key]?.includes(value))
-                && (candidate.scope.taskId === undefined || candidate.scope.taskId === taskId)
-                && candidate.scope.projectIds === undefined && candidate.scope.repositories === undefined
-                && candidate.scope.packages === undefined
-                && (candidate.scope.homePath === undefined || candidate.scope.homePath === env.directory.path)
-                && checkGrant(candidate, request, new Date()).allowed);
+            const grant = executionGrant(taskId, params, env.directory.path);
             if (!grant)
                 throw new Error(`Explicit trusted-local execution grant unavailable (${phase}); pluginId=${params.pluginId}, digest=${params.digest}, environmentRef=${params.environmentRef}.`);
             tx.saveCapabilityGrant(taskId, recordGrantUse(grant, new Date(), reservation));
@@ -173,6 +188,81 @@ export function createPluginService(store, host, registry) {
         }
     };
     return {
+        assess(taskId, descriptor, input, via) {
+            let validationId;
+            let phase;
+            let pkg;
+            let preparationId;
+            let path;
+            if (descriptor.name === "plugin.validate") {
+                if (input === undefined)
+                    return undefined;
+                const params = input;
+                const prepared = store.getEnvironmentPreparation(taskId, params.preparationId);
+                if (!prepared?.directory)
+                    throw new Error("Plugin validation needs an existing directory preparation.");
+                const access = environmentAccess(taskId, prepared.id, via);
+                if (access.state !== "authorized")
+                    return access;
+                const directory = resolve(prepared.directory.path, params.directory);
+                packagePath(relative(prepared.directory.path, directory));
+                // Capture data only. Never run a build, prepare an environment or
+                // initialize a Provider just to assess the source's exact grant.
+                pkg = readPluginPackage(directory, false);
+                preparationId = prepared.id;
+                path = prepared.directory.path;
+                phase = "validate";
+            }
+            else if (descriptor.name === "plugin.activate") {
+                if (input === undefined)
+                    return undefined;
+                validationId = input.validationId;
+                phase = "activate";
+            }
+            else {
+                const selected = active.get(descriptor.provider.id);
+                if (!selected || selected.ref.generation !== descriptor.provider.generation)
+                    return undefined;
+                validationId = selected.validationId;
+                phase = "call";
+            }
+            // Inspect captured authorization parameters, not Host availability,
+            // filesystem readiness or author code. Execution owns those checks.
+            if (validationId !== undefined) {
+                const report = store.getPluginValidation(taskId, validationId);
+                if (!report)
+                    throw new Error("Plugin validation not found in this Task.");
+                pkg = report.package;
+                preparationId = report.preparationId;
+                path = report.environment.path;
+            }
+            if (phase !== "validate") {
+                const access = environmentAccess(taskId, preparationId, via);
+                if (access.state !== "authorized")
+                    return access;
+            }
+            if (pkg.manifest.kind === "declarative")
+                return { state: "authorized" };
+            const params = executionParams(taskId, preparationId, pkg, phase);
+            const phases = phase === "validate" && pkg.manifest.build ? ["build", "validate"] : [phase];
+            // Simulate the same ordered selection as execution, without persisting
+            // uses. A broad Grant may fund multiple phases only if it has capacity.
+            const plannedUses = new Map();
+            const missing = phases.filter(value => {
+                const grant = executionGrant(taskId, { ...params, phase: value }, path, plannedUses);
+                if (!grant)
+                    return true;
+                plannedUses.set(grant.id, (plannedUses.get(grant.id) ?? 0) + 1);
+                return false;
+            });
+            if (!missing.length)
+                return { state: "authorized" };
+            return { state: "requestable", request: {
+                    action: "plugin.execute", taskId,
+                    bounds: { ...Object.fromEntries(Object.entries(params).map(([key, value]) => [key, [value]])), phase: missing },
+                    via, explanation: "Trusted-local author code needs an exact, irreversible execution Grant. Use the existing authorization source and Grant path; discovery consumes no uses."
+                } };
+        },
         current: inspect,
         list(taskId) {
             return store.transaction(() => store.listPluginIntents(taskId)

package/dist/resources/projectResourceService.js

@@ -42,7 +42,7 @@ export function createProjectResources(store, now = () => new Date()) {
             throw new Error(`Local resource not found: ${resourceId}.`);
         return value;
     };
-    const grantFor = (taskId, resourceId, access, reservation, reservedOnly = false) => {
+    const findGrant = (taskId, resourceId, access, reservation, reservedOnly = false) => {
         const target = resource(resourceId);
         const grant = store.listCapabilityGrants(taskId).find((candidate) => {
             // A Project scope is visibility, not an exhaustive Resource grant. A
@@ -57,6 +57,10 @@ export function createProjectResources(store, now = () => new Date()) {
                 return false;
             return checkGrant(candidate, { action: `resource.local.${access}`, params: { resourceId } }, now(), { skipUsesCheck: reservation !== undefined && candidate.useReservations.includes(reservation) }).allowed;
         });
+        return grant;
+    };
+    const grantFor = (taskId, resourceId, access, reservation, reservedOnly = false) => {
+        const grant = findGrant(taskId, resourceId, access, reservation, reservedOnly);
         if (!grant)
             throw new Error(`Resource grant unavailable: ${resourceId}/${access}.`);
         return grant;
@@ -109,6 +113,24 @@ export function createProjectResources(store, now = () => new Date()) {
         });
     };
     return {
+        assessLocalAccess(taskId, resourceId, access, via, reservation, reservedOnly = false) {
+            const current = task(taskId);
+            // Only already-discoverable references may receive request guidance.
+            // Do not resolve an arbitrary global ID merely to confirm its existence.
+            const known = current.projectBindings.some(({ projectId }) => store.getProject(projectId)?.resourceRefs?.includes(resourceId))
+                || store.listCapabilityGrants(taskId).some(grant => grant.parameterBounds.resourceId?.includes(resourceId))
+                || store.listEnvironmentPreparations(taskId).some(value => value.resourceRefs.includes(resourceId))
+                || store.listEvents(taskId).some(event => event.type === "resource.local.registered" && event.payload.resourceId === resourceId);
+            if (!known)
+                return { state: "hidden" };
+            if (findGrant(taskId, resourceId, access, reservation, reservedOnly))
+                return { state: "authorized" };
+            return { state: "requestable", request: {
+                    action: `resource.local.${access}`, taskId, bounds: { resourceId: [resourceId] }, via,
+                    explanation: "Request this exact resource and access through existing Message/InputRequest and Grant authority. A response alone is not a Grant."
+                        + (reservedOnly ? " This environment's adoption reservation is no longer valid; inspect preparation/adoption before reusing it." : "")
+                } };
+        },
         resolveExecutionEnvironment,
         bindEnvironment(taskId, roleName, preparationId, source = { source: "environment.bind" }) {
             return store.transaction((tx) => {

package/dist/runtime/managedIdentity.js

@@ -0,0 +1,6 @@
+/** Presence is not authentication. Even partial transport identity must not
+ * silently acquire the authority of an unbound public caller. */
+export function hasManagedIdentity(environment) {
+    return ["YUI_SESSION_SCOPE", "YUI_ROLE", "YUI_AGENT_ID", "YUI_NATIVE_SESSION_ID",
+        "YUI_TASK_ID", "YUI_SESSION_MANIFEST"].some(key => environment[key] !== undefined);
+}

package/dist/surface/surfaceContributions.js

@@ -10,11 +10,14 @@ export class SurfaceContributions {
         return this.registry.search(context).map((entry) => ({
             ...reference(entry), name: entry.surfaces?.cli?.name ?? entry.name,
             help: entry.surfaces?.cli?.help ?? entry.summary, effect: entry.effect,
+            ...(entry.access === undefined ? {} : { access: entry.access }),
             ...(entry.unavailable === undefined ? {} : { unavailable: entry.unavailable })
         }));
     }
     listPanels(context) {
         return this.registry.search(context).flatMap((entry) => {
+            if (entry.access?.state === "requestable")
+                return [];
             const panel = entry.surfaces?.panel
                 ?? (entry.effect === "query" ? { kind: "data", title: entry.summary, renderer: "json" } : undefined);
             return panel ? [{

package/dist/task/taskAuthority.js

@@ -1,5 +1,6 @@
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { usageError } from "../errors/cliError.js";
-import { MANAGED_NATIVE_SESSION_ENV, currentManagedRuntime } from "../runtime/managedCaller.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
 const LEADER_ROLE = "leader";
 export function taskActor(environment, taskId) {
     const env = environment ?? {};
@@ -16,9 +17,7 @@ export function taskActor(environment, taskId) {
             return "operator";
         throw usageError("A managed global Session may perform this action only as Operator.");
     }
-    if (env.YUI_ROLE !== undefined
-        || env.YUI_AGENT_ID !== undefined
-        || env[MANAGED_NATIVE_SESSION_ENV] !== undefined) {
+    if (hasManagedIdentity(env)) {
         throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
     }
     return "user";
@@ -86,9 +85,7 @@ export function projectActor(environment) {
             return "operator";
         throw usageError("A managed global Session may manage Project Knowledge only as Operator.");
     }
-    if (env.YUI_ROLE !== undefined
-        || env.YUI_AGENT_ID !== undefined
-        || env[MANAGED_NATIVE_SESSION_ENV] !== undefined) {
+    if (hasManagedIdentity(env)) {
         throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
     }
     return "user";
@@ -124,9 +121,7 @@ export function resolveJobCaller(environment, taskId) {
             nativeSessionId: env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID
         };
     }
-    if (env.YUI_ROLE !== undefined
-        || env.YUI_AGENT_ID !== undefined
-        || env[MANAGED_NATIVE_SESSION_ENV] !== undefined) {
+    if (hasManagedIdentity(env)) {
         throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
     }
     return { scope: "user" };

package/dist/web/assets/assetManifest.js

@@ -1,43 +1,59 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { API_SCRIPT } from "./client/api.js";
 import { APP_SCRIPT } from "./client/app.js";
 import { COMPONENTS_SCRIPT } from "./client/components.js";
+import { DETAIL_SCRIPT } from "./client/detail.js";
+import { DOCK_SCRIPT } from "./client/dock.js";
 import { DOM_SCRIPT } from "./client/dom.js";
+import { EVIDENCE_SCRIPT } from "./client/evidence.js";
 import { FORMAT_SCRIPT } from "./client/format.js";
+import { FORMS_SCRIPT } from "./client/forms.js";
 import { I18N_SCRIPT } from "./client/i18n.js";
 import { MARKDOWN_SCRIPT } from "./client/markdown.js";
+import { OVERVIEW_SCRIPT } from "./client/overview.js";
+import { RECORDS_SCRIPT } from "./client/records.js";
+import { SECTIONS_SCRIPT } from "./client/sections.js";
+import { SIDEBAR_SCRIPT } from "./client/sidebar.js";
 import { THEME_SCRIPT } from "./client/theme.js";
-import { VIEW_SCRIPT } from "./client/view.js";
-import { TASK_SURFACE_SCRIPT } from "./client/taskSurface.js";
-import { TASK_SUMMARY_SCRIPT } from "./client/taskSummary.js";
 import { DASHBOARD_HTML } from "./shell.js";
 import { FONT_FACE_STYLES } from "./fonts.js";
 import { FONT_WOFF2_BASE64 } from "./fontData.js";
-import { CARD_STYLES } from "./styles/cards.js";
+import { BASE_STYLES } from "./styles/base.js";
+import { COMPONENT_STYLES } from "./styles/components.js";
 import { LAYOUT_STYLES } from "./styles/layout.js";
 import { MARKDOWN_STYLES } from "./styles/markdown.js";
 import { RESPONSIVE_STYLES } from "./styles/responsive.js";
 import { TOKEN_STYLES } from "./styles/tokens.js";
-import { WIDGET_STYLES } from "./styles/widgets.js";
+import { VIEW_STYLES } from "./styles/views.js";
 const require = createRequire(import.meta.url);
+const CSS = "text/css; charset=utf-8";
+const JS = "text/javascript; charset=utf-8";
 export const WEB_ASSETS = Object.freeze({
-    "/assets/css/tokens.css": { contentType: "text/css; charset=utf-8", body: TOKEN_STYLES },
-    "/assets/css/fonts.css": { contentType: "text/css; charset=utf-8", body: FONT_FACE_STYLES },
-    "/assets/css/layout.css": { contentType: "text/css; charset=utf-8", body: LAYOUT_STYLES },
-    "/assets/css/widgets.css": { contentType: "text/css; charset=utf-8", body: WIDGET_STYLES },
-    "/assets/css/cards.css": { contentType: "text/css; charset=utf-8", body: CARD_STYLES },
-    "/assets/css/markdown.css": { contentType: "text/css; charset=utf-8", body: MARKDOWN_STYLES },
-    "/assets/css/responsive.css": { contentType: "text/css; charset=utf-8", body: RESPONSIVE_STYLES },
-    "/assets/js/dom.js": { contentType: "text/javascript; charset=utf-8", body: DOM_SCRIPT },
-    "/assets/js/format.js": { contentType: "text/javascript; charset=utf-8", body: FORMAT_SCRIPT },
-    "/assets/js/i18n.js": { contentType: "text/javascript; charset=utf-8", body: I18N_SCRIPT },
-    "/assets/js/markdown.js": { contentType: "text/javascript; charset=utf-8", body: MARKDOWN_SCRIPT },
-    "/assets/js/theme.js": { contentType: "text/javascript; charset=utf-8", body: THEME_SCRIPT },
-    "/assets/js/components.js": { contentType: "text/javascript; charset=utf-8", body: COMPONENTS_SCRIPT },
-    "/assets/js/view.js": { contentType: "text/javascript; charset=utf-8", body: VIEW_SCRIPT },
-    "/assets/js/task-surface.js": { contentType: "text/javascript; charset=utf-8", body: TASK_SURFACE_SCRIPT },
-    "/assets/js/task-summary.js": { contentType: "text/javascript; charset=utf-8", body: TASK_SUMMARY_SCRIPT },
-    "/assets/app.js": { contentType: "text/javascript; charset=utf-8", body: APP_SCRIPT },
+    "/assets/css/fonts.css": { contentType: CSS, body: FONT_FACE_STYLES },
+    "/assets/css/tokens.css": { contentType: CSS, body: TOKEN_STYLES },
+    "/assets/css/base.css": { contentType: CSS, body: BASE_STYLES },
+    "/assets/css/layout.css": { contentType: CSS, body: LAYOUT_STYLES },
+    "/assets/css/components.css": { contentType: CSS, body: COMPONENT_STYLES },
+    "/assets/css/views.css": { contentType: CSS, body: VIEW_STYLES },
+    "/assets/css/markdown.css": { contentType: CSS, body: MARKDOWN_STYLES },
+    "/assets/css/responsive.css": { contentType: CSS, body: RESPONSIVE_STYLES },
+    "/assets/js/dom.js": { contentType: JS, body: DOM_SCRIPT },
+    "/assets/js/format.js": { contentType: JS, body: FORMAT_SCRIPT },
+    "/assets/js/i18n.js": { contentType: JS, body: I18N_SCRIPT },
+    "/assets/js/markdown.js": { contentType: JS, body: MARKDOWN_SCRIPT },
+    "/assets/js/theme.js": { contentType: JS, body: THEME_SCRIPT },
+    "/assets/js/api.js": { contentType: JS, body: API_SCRIPT },
+    "/assets/js/components.js": { contentType: JS, body: COMPONENTS_SCRIPT },
+    "/assets/js/records.js": { contentType: JS, body: RECORDS_SCRIPT },
+    "/assets/js/forms.js": { contentType: JS, body: FORMS_SCRIPT },
+    "/assets/js/evidence.js": { contentType: JS, body: EVIDENCE_SCRIPT },
+    "/assets/js/sidebar.js": { contentType: JS, body: SIDEBAR_SCRIPT },
+    "/assets/js/overview.js": { contentType: JS, body: OVERVIEW_SCRIPT },
+    "/assets/js/sections.js": { contentType: JS, body: SECTIONS_SCRIPT },
+    "/assets/js/detail.js": { contentType: JS, body: DETAIL_SCRIPT },
+    "/assets/js/dock.js": { contentType: JS, body: DOCK_SCRIPT },
+    "/assets/app.js": { contentType: JS, body: APP_SCRIPT },
     ...fontAssets(),
     "/assets/vendor/xterm.mjs": vendorAsset("@xterm/xterm/lib/xterm.mjs", "text/javascript; charset=utf-8"),
     "/assets/vendor/addon-fit.mjs": vendorAsset("@xterm/addon-fit/lib/addon-fit.mjs", "text/javascript; charset=utf-8"),

package/dist/web/assets/client/api.js

@@ -0,0 +1,115 @@
+export const API_SCRIPT = String.raw `
+// Loopback API client. Every request carries the page token; a write is keyed
+// so an unresolved submission can never be silently replayed from this page.
+const token = document.querySelector('meta[name="yui-web-token"]').content;
+const unresolved = new Set();
+
+export function pageToken() { return token; }
+
+export async function requestJson(path, options) {
+  const response = await fetch(path, {
+    ...options,
+    headers: {
+      accept: "application/json",
+      "x-yui-web-token": token,
+      ...(options && options.headers ? options.headers : {})
+    }
+  });
+  if (!response.ok) {
+    let message = "HTTP " + response.status;
+    let disposition = "unknown";
+    try {
+      const body = await response.json();
+      if (body && body.error) message = body.error;
+      if (body && body.disposition === "not-submitted") disposition = "not-submitted";
+    } catch {}
+    throw Object.assign(new Error(message), { disposition, status: response.status });
+  }
+  return response.json();
+}
+
+function postJson(path, body, signal) {
+  return requestJson(path, {
+    method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+    ...(signal ? { signal } : {})
+  });
+}
+
+// A key stays blocked until the server either answers or proves the request
+// was not submitted; an unknown outcome must be inspected, not resent.
+export async function submitMutation(key, path, body) {
+  if (unresolved.has(key)) {
+    throw Object.assign(new Error("An earlier submission is unresolved; read current facts first."), { disposition: "blocked" });
+  }
+  unresolved.add(key);
+  try {
+    const receipt = await postJson(path, body);
+    unresolved.delete(key);
+    return receipt;
+  } catch (error) {
+    if (error.disposition === "not-submitted") unresolved.delete(key);
+    throw error;
+  }
+}
+
+export function releaseMutation(key) { unresolved.delete(key); }
+
+const task = function (taskId) { return "/api/tasks/" + encodeURIComponent(taskId); };
+
+export const api = {
+  dashboard: function (query) { return requestJson("/api/dashboard?" + query); },
+  pageSessions: function (query) {
+    return requestJson("/api/dashboard/sessions?" + query, { signal: AbortSignal.timeout(5000) });
+  },
+  context: function (taskId) { return requestJson(task(taskId) + "/context"); },
+  observation: function (taskId) { return requestJson(task(taskId), { signal: AbortSignal.timeout(1500) }); },
+  inspect: async function (taskId, ref) {
+    const query = new URLSearchParams({ store: ref.store, ref: ref.refId });
+    if (ref.digest) query.set("digest", ref.digest);
+    let result = await requestJson(task(taskId) + "/inspect?" + query);
+    if (!result.contentPage) return result;
+    const source = result.contentPage.source;
+    const digest = result.contentPage.digest;
+    let text = "";
+    while (true) {
+      const page = result.contentPage;
+      if (!page || page.source !== source || page.digest !== digest || page.encoding !== "json"
+        || page.offset !== text.length || typeof page.text !== "string" || !page.text.length) {
+        throw new Error("Original read changed or returned an invalid page; refresh its Context reference.");
+      }
+      text += page.text;
+      if (page.complete) return JSON.parse(text);
+      if (!page.nextCursor) throw new Error("Original read is incomplete; refresh its Context reference.");
+      query.set("cursor", page.nextCursor);
+      result = await requestJson(task(taskId) + "/inspect?" + query);
+    }
+  },
+  artifacts: function (taskId) { return requestJson(task(taskId) + "/artifacts"); },
+  artifact: function (taskId, path, commit) {
+    return requestJson(task(taskId) + "/artifacts?" + new URLSearchParams({ path, commit }));
+  },
+  evidence: function (taskId) { return requestJson(task(taskId) + "/evidence"); },
+  panels: function (taskId) { return requestJson(task(taskId) + "/panels", { signal: AbortSignal.timeout(3000) }); },
+  readPanel: function (taskId, ref, input) {
+    return postJson(task(taskId) + "/panels", { ref, input }, AbortSignal.timeout(3000));
+  },
+  sendMessage: function (taskId, body, requestId, intent) {
+    return submitMutation(taskId + "/messages", task(taskId) + "/messages",
+      { body, requestId, ...(intent === undefined ? {} : { intent }) });
+  },
+  control: function (taskId, payload) {
+    return submitMutation(taskId + "/control/" + payload.requestId, task(taskId) + "/control", payload);
+  },
+  updateTask: function (taskId, patch, requestId) {
+    return submitMutation(taskId + "/metadata", task(taskId) + "/metadata", { patch, requestId });
+  },
+  answerInput: function (taskId, inputId, answer) {
+    return submitMutation(taskId + "/input/" + inputId,
+      task(taskId) + "/inputs/" + encodeURIComponent(inputId) + "/answer", answer);
+  },
+  globalState: function (role) { return requestJson("/api/roles/" + encodeURIComponent(role) + "/control"); },
+  globalControl: function (role, input) {
+    return submitMutation("global/" + role, "/api/roles/" + encodeURIComponent(role) + "/control", input);
+  }
+};
+`;