@sema-agent/server 1.316.0 → 1.317.0

package/dist/http/routes/fleet.js

@@ -0,0 +1,147 @@
+import { taskNotificationFoldKey } from "../../orchestration/workflow-completion-inbox.js";
+import { sendJson, sendError, sseHeaders } from "../send.js";
+import { gatedPrincipal } from "../principal-gate.js";
+export async function handleFleet(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleFleetBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleFleetBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { sessionOwnerScope } = ctx.helpers;
+    void url;
+    if (req.method === "GET" && new URL(req.url ?? "", "http://x").pathname === "/v1/fleet/stream") {
+        if (!deps.fleetBus) {
+            sendError(res, 501, "capability.self_orchestration_required", "fleet stream requires self-orchestration / fleet wiring");
+            return;
+        }
+        const { fleetWide } = sessionOwnerScope(req);
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && !principal && !fleetWide) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const fleetParams = new URL(req.url ?? "", "http://x").searchParams;
+        const callerSession = fleetParams.get("session");
+        const observeOnly = fleetParams.get("observe") === "1";
+        await streamFleet(req, res, deps.fleetBus, fleetWide ? null : (principal ?? "default"), callerSession || null, observeOnly ? undefined : deps.workflowCompletionInbox);
+        return;
+    }
+    miss.fell = true;
+}
+function streamFleet(req, res, bus, callerScope, callerSession = null, completionInbox) {
+    return new Promise((resolve) => {
+        sseHeaders(res);
+        res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, scoped: callerScope !== null, sessionScoped: callerSession !== null, bgNotifyFailClosed: true })}\n\n`);
+        const seenTasks = new Set();
+        const seenWf = new Set();
+        const sessionOk = (rowSession) => callerSession === null || rowSession === undefined || rowSession === callerSession;
+        const visT = (r) => (callerScope === null || r.scope === callerScope) && sessionOk(r.sessionId);
+        const visW = (r) => (callerScope === null || r.scope === callerScope) && sessionOk(r.sessionId);
+        const stripT = (r) => {
+            const { scope: _s, sessionId: _sid, ...rest } = r;
+            if (callerSession !== null && r.sessionId === undefined) {
+                const { description: _d, agentType: _at, agentName: _an, currentAction: _ca, ...keep } = rest;
+                return { ...keep, name: "(unattributed)" };
+            }
+            return rest;
+        };
+        const stripW = (r) => {
+            const { scope: _s, sessionId: _sid, ...rest } = r;
+            if (callerSession !== null && r.sessionId === undefined) {
+                const { description: _d, ...keep } = rest;
+                return { ...keep, name: "(unattributed)" };
+            }
+            return rest;
+        };
+        const send = (event, data) => { if (!res.writableEnded)
+            res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); };
+        const snap = bus.snapshot();
+        const tasks = snap.tasks.filter(visT);
+        const workflows = snap.workflows.filter(visW);
+        tasks.forEach((r) => seenTasks.add(r.id));
+        workflows.forEach((r) => seenWf.add(r.id));
+        send("snapshot", { tasks: tasks.map(stripT), workflows: workflows.map(stripW), ts: snap.ts });
+        const unsubscribe = bus.subscribe((frame) => {
+            switch (frame.type) {
+                case "task":
+                    if (visT(frame.row)) {
+                        seenTasks.add(frame.row.id);
+                        send("task", { row: stripT(frame.row), ts: frame.ts });
+                    }
+                    break;
+                case "workflow":
+                    if (visW(frame.row)) {
+                        seenWf.add(frame.row.id);
+                        send("workflow", { row: stripW(frame.row), ts: frame.ts });
+                    }
+                    break;
+                case "task_remove":
+                    if (seenTasks.delete(frame.id))
+                        send("task_remove", { id: frame.id, ts: frame.ts });
+                    break;
+                case "workflow_remove":
+                    if (seenWf.delete(frame.id))
+                        send("workflow_remove", { id: frame.id, ts: frame.ts });
+                    break;
+                case "hook_notice": {
+                    const hn = frame.notice;
+                    const hScopeOk = callerScope === null || hn.ownerScope === callerScope;
+                    const hSessionOk = callerSession === null || hn.ownerSessionId === callerSession;
+                    if (hScopeOk && hSessionOk) {
+                        const { ownerScope: _hs, ownerSessionId: _hsid, ...wire } = hn;
+                        send("hook_notice", { type: "hook_notice", ...wire, ts: frame.ts });
+                    }
+                    break;
+                }
+                case "bg_notification": {
+                    const n = frame.notification;
+                    const scopeOk = callerScope === null || n.ownerScope === callerScope;
+                    const sessionInjectOk = callerSession === null || n.ownerSessionId === callerSession;
+                    if (scopeOk && sessionInjectOk) {
+                        const { ownerScope: _os, ownerSessionId: _osid, ...wire } = n;
+                        send("bg_notification", { type: "bg_notification", ...wire, ts: frame.ts });
+                        if (completionInbox && n.ownerSessionId && callerSession !== null && callerSession === n.ownerSessionId && !res.writableEnded) {
+                            const ownerSid = n.ownerSessionId;
+                            const family = taskNotificationFoldKey({ task_id: n.taskId, status: n.status, ...(n.seq !== undefined ? { seq: n.seq } : {}) });
+                            const familyUuid = n.sessionId !== undefined && n.sessionId !== n.taskId
+                                ? taskNotificationFoldKey({ task_id: n.sessionId, status: n.status, ...(n.seq !== undefined ? { seq: n.seq } : {}) })
+                                : undefined;
+                            const ackIfAlive = () => {
+                                if (res.writableEnded || res.socket?.destroyed)
+                                    return;
+                                void completionInbox.markTerminalServed(ownerSid, family).catch(() => undefined);
+                                if (familyUuid !== undefined)
+                                    void completionInbox.markTerminalServed(ownerSid, familyUuid).catch(() => undefined);
+                            };
+                            res.write(`: ack
+
+`, ackIfAlive);
+                        }
+                    }
+                    break;
+                }
+                default:
+                    break;
+            }
+        });
+        const hb = setInterval(() => { if (!res.writableEnded)
+            res.write(`event: heartbeat\ndata: {}\n\n`); }, 15_000);
+        if (typeof hb.unref === "function")
+            hb.unref();
+        let done = false;
+        const shutdown = () => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(hb);
+            unsubscribe();
+            if (!res.writableEnded)
+                res.end();
+            resolve();
+        };
+        req.on("close", shutdown);
+        res.on("close", shutdown);
+    });
+}
+//# sourceMappingURL=fleet.js.map

package/dist/http/routes/images.js

@@ -62,26 +62,26 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const isRunner = source !== undefined && source !== null && source === cfg.runnerPrincipal;
         if (req.method === "POST" && url === "/v1/images/bakes") {
             if (!explicitOperator) {
-                sendJson(res, 403, { error: "operator only" });
+                sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
             const rl = bakeSubmitLimiter.check(`bake:${principal}`);
             if (!rl.allowed) {
                 res.setHeader("retry-after", String(rl.retryAfterSec));
-                sendJson(res, 429, { error: "bake submission rate exceeded", retryAfterSec: rl.retryAfterSec });
+                sendError(res, 429, "limit.rate_exceeded", "bake submission rate exceeded", { retryAfterSec: rl.retryAfterSec });
                 return;
             }
             const body = (await readJson(req));
             const v = validateBake(body);
             if (!v.ok) {
-                sendJson(res, v.status, { error: v.error, ...(v.conflictBands ? { errorCode: "band-conflict", conflictBands: v.conflictBands } : {}) });
+                sendError(res, v.status, v.conflictBands ? "band-conflict" : v.status === 501 ? "capability.unavailable" : "request.field_invalid", v.error, { ...(v.conflictBands ? { conflictBands: v.conflictBands } : {}) });
                 return;
             }
             let effectiveBaseRef;
             if (v.baseRef) {
                 const baseEntry = idx ? await idx.getByDigest(v.baseRef) : null;
                 if (!baseEntry || baseEntry.status !== "published" || baseEntry.profile !== SANDBOX_BASE_PROFILE) {
-                    sendJson(res, 400, { error: "baseRef is not a known published sandbox-base digest" });
+                    sendError(res, 400, "request.unknown_reference", "baseRef is not a known published sandbox-base digest");
                     return;
                 }
                 effectiveBaseRef = v.baseRef;
@@ -90,7 +90,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 effectiveBaseRef = cfg.defaultBaseRef ?? (idx ? (await idx.latestPublished(SANDBOX_BASE_PROFILE, { operator: true }))?.digest ?? null : null);
             }
             if (!v.dryRun && !effectiveBaseRef) {
-                sendJson(res, 503, { error: "no sandbox-base available to build from (set SANDBOX_BASE_REF or publish a sandbox-base image)" });
+                sendError(res, 503, "state.no_sandbox_base", "no sandbox-base available to build from (set SANDBOX_BASE_REF or publish a sandbox-base image)");
                 return;
             }
             const argv = buildBakeArgv(v, { baseRef: effectiveBaseRef, cacheBase: cfg.cacheBase });
@@ -121,7 +121,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                         return;
                     }
                     const busy = await bakes.findActiveAny();
-                    sendJson(res, 409, { error: "a bake is already in progress", ...(busy ? { activeBakeId: busy.bakeId, eventsUrl: `/v1/images/bakes/${busy.bakeId}/events` } : {}) });
+                    sendError(res, 409, "conflict.bake_in_progress", "a bake is already in progress", { ...(busy ? { activeBakeId: busy.bakeId, eventsUrl: `/v1/images/bakes/${busy.bakeId}/events` } : {}) });
                     return;
                 }
                 sendJson(res, 202, { bakeId: r.bake.bakeId, eventsUrl: `/v1/images/bakes/${r.bake.bakeId}/events`, status: r.bake.status, state: r.bake.state });
@@ -134,13 +134,13 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const evMatch = req.method === "GET" ? BAKE_EVENTS_RE.exec(url) : null;
         if (evMatch) {
             if (!explicitOperator) {
-                sendJson(res, 403, { error: "operator only" });
+                sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
             const bakeId = decodeURIComponent(evMatch[1]);
             const bake = await bakes.getBake(bakeId);
             if (!bake) {
-                sendJson(res, 404, { error: "bake not found" });
+                sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
             await streamBakeEvents(req, res, bakes, bakeId, cfg.staleMs);
@@ -149,13 +149,13 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const cancelMatch = req.method === "POST" ? BAKE_CANCEL_RE.exec(url) : null;
         if (cancelMatch) {
             if (!explicitOperator) {
-                sendJson(res, 403, { error: "operator only" });
+                sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
             const bakeId = decodeURIComponent(cancelMatch[1]);
             const bake = await bakes.getBake(bakeId);
             if (!bake) {
-                sendJson(res, 404, { error: "bake not found" });
+                sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
             const flagged = await bakes.requestCancel(bakeId);
@@ -164,7 +164,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         }
         if (req.method === "POST" && url === "/v1/images/bakes/claim") {
             if (!isRunner) {
-                sendJson(res, 403, { error: "bake-runner only" });
+                sendError(res, 403, "auth.bake_runner_only", "bake-runner only");
                 return;
             }
             const body = (await readJson(req));
@@ -186,7 +186,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const claimMatch = req.method === "POST" ? BAKE_CLAIM_RE.exec(url) : null;
         if (claimMatch) {
             if (!isRunner) {
-                sendJson(res, 403, { error: "bake-runner only" });
+                sendError(res, 403, "auth.bake_runner_only", "bake-runner only");
                 return;
             }
             const bakeId = decodeURIComponent(claimMatch[1]);
@@ -194,7 +194,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             const runnerId = typeof body.runnerId === "string" && body.runnerId.length > 0 ? body.runnerId : (principal ?? source ?? cfg.runnerPrincipal);
             const claimed = await bakes.claimBake(bakeId, runnerId, cfg.leaseMs);
             if (!claimed) {
-                sendJson(res, 409, { error: "bake not claimable (already claimed or the build lease is held)" });
+                sendError(res, 409, "conflict.bake_not_claimable", "bake not claimable (already claimed or the build lease is held)");
                 return;
             }
             sendJson(res, 200, claimResponse(claimed));
@@ -203,30 +203,30 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const ingestMatch = req.method === "POST" ? BAKE_INGEST_RE.exec(url) : null;
         if (ingestMatch) {
             if (!isRunner) {
-                sendJson(res, 403, { error: "bake-runner only" });
+                sendError(res, 403, "auth.bake_runner_only", "bake-runner only");
                 return;
             }
             const bakeId = decodeURIComponent(ingestMatch[1]);
             const bake = await bakes.getBake(bakeId);
             if (!bake) {
-                sendJson(res, 404, { error: "bake not found" });
+                sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
             const presented = headerStr(req.headers["x-bake-ingest-secret"]);
             if (!bake.ingestSecret || !presented || !safeEqual(presented, bake.ingestSecret)) {
-                sendJson(res, 403, { error: "invalid ingest secret" });
+                sendError(res, 403, "auth.ingest_secret_invalid", "invalid ingest secret");
                 return;
             }
             const line = (await readJson(req));
             if (line.event === "heartbeat") {
                 const fresh = await bakes.getBake(bakeId);
                 if (!fresh || fresh.status !== "running") {
-                    sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh?.cancelRequested ?? false });
+                    sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh?.cancelRequested ?? false, errorCode: "conflict.bake_not_running" });
                     return;
                 }
                 const ok = bake.runnerId ? await bakes.heartbeatLease(bakeId, bake.runnerId, cfg.leaseMs) : false;
                 if (!ok) {
-                    sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh.cancelRequested });
+                    sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh.cancelRequested, errorCode: "conflict.bake_lease_lost" });
                     return;
                 }
                 sendJson(res, 200, { accepted: true, leaseValid: true, cancelRequested: fresh.cancelRequested });
@@ -234,7 +234,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             }
             const fresh = await bakes.getBake(bakeId);
             if (!fresh || fresh.status !== "running") {
-                sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh?.cancelRequested ?? false });
+                sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh?.cancelRequested ?? false, errorCode: "conflict.bake_not_running" });
                 return;
             }
             if (fresh.runnerId) {
@@ -248,19 +248,19 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         const idMatch = req.method === "GET" ? BAKE_ID_RE.exec(url) : null;
         if (idMatch) {
             if (!explicitOperator) {
-                sendJson(res, 403, { error: "operator only" });
+                sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
             const bakeId = decodeURIComponent(idMatch[1]);
             const bake = await bakes.getBake(bakeId);
             if (!bake) {
-                sendJson(res, 404, { error: "bake not found" });
+                sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
             sendJson(res, 200, { bake: bakeView(bake) });
             return;
         }
-        sendJson(res, 404, { error: "not found" });
+        sendError(res, 404, "not_found.route", "not found");
         return;
     }
     if (deps.imageIndex && url.startsWith("/v1/images")) {
@@ -287,12 +287,12 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             const body = (await readJson(req));
             const profile = typeof body.profile === "string" ? body.profile : "";
             if (!profile) {
-                sendJson(res, 400, { error: "profile is required" });
+                sendError(res, 400, "request.field_invalid", "profile is required");
                 return;
             }
             const entry = await idx.latestPublished(profile, viewer);
             if (!entry) {
-                sendJson(res, 404, { error: `no published image for profile '${profile}' visible to this principal` });
+                sendError(res, 404, "not_found.image", `no published image for profile '${profile}' visible to this principal`);
                 return;
             }
             const needed = Array.isArray(body.capabilitiesNeeded)
@@ -301,7 +301,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             const caps = entry.capabilities;
             const missing = needed.filter((c) => !caps[c]);
             if (missing.length > 0) {
-                sendJson(res, 409, { error: "capabilities not satisfied by the image", missing });
+                sendError(res, 409, "conflict.image_capabilities_unsatisfied", "capabilities not satisfied by the image", { missing });
                 return;
             }
             sendJson(res, 200, {
@@ -317,12 +317,12 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         }
         if (req.method === "POST" && url === "/v1/images/register") {
             if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
-                sendJson(res, 403, { error: "operator only" });
+                sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
             const b = (await readJson(req));
             if (typeof b.profile !== "string" || typeof b.repo !== "string" || typeof b.digest !== "string") {
-                sendJson(res, 400, { error: "profile, repo, digest are required" });
+                sendError(res, 400, "request.field_invalid", "profile, repo, digest are required");
                 return;
             }
             const id = await idx.registerBuilding({
@@ -352,7 +352,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         if (digMatch) {
             const entry = await idx.getByDigest(decodeURIComponent(digMatch[1]));
             if (!entry || (!viewer.operator && entry.visibility === "tenant" && entry.tenantId !== viewer.tenantId)) {
-                sendJson(res, 404, { error: "not found" });
+                sendError(res, 404, "not_found.image", "not found");
                 return;
             }
             sendJson(res, 200, { image: entry });
@@ -362,7 +362,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         if (profMatch) {
             const entry = await idx.latestPublished(decodeURIComponent(profMatch[1]), viewer);
             if (!entry) {
-                sendJson(res, 404, { error: "not found" });
+                sendError(res, 404, "not_found.image", "not found");
                 return;
             }
             sendJson(res, 200, { image: entry });

package/dist/http/routes/leader.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleLeader(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=leader.d.ts.map

package/dist/http/routes/leader.js

@@ -0,0 +1,48 @@
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal } from "../principal-gate.js";
+export async function handleLeader(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleLeaderBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleLeaderBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
+    if (deps.leaderEndpoint) {
+        const isLeaderPost = req.method === "POST" && url === "/v1/leader";
+        const isLeaderGet = req.method === "GET" && /^\/v1\/leader\/[^/]+$/.test(url);
+        if (isLeaderPost || isLeaderGet) {
+            if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
+                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                return;
+            }
+            const requester = gatedPrincipal(req, deps.config) ?? null;
+            if (isLeaderPost) {
+                if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+                    return;
+                let body;
+                try {
+                    body = await readJson(req);
+                }
+                catch {
+                    sendError(res, 400, "request.invalid_json", "invalid JSON body");
+                    return;
+                }
+                const r = deps.leaderEndpoint.handle("POST", url, body, requester);
+                if (r) {
+                    sendJson(res, r.status, r.body);
+                    return;
+                }
+            }
+            else {
+                const r = deps.leaderEndpoint.handle("GET", url, undefined, requester);
+                if (r) {
+                    sendJson(res, r.status, r.body);
+                    return;
+                }
+            }
+        }
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=leader.js.map

package/dist/http/routes/memory-policy.js

@@ -13,20 +13,20 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
     if (url === "/v1/memory/export" && req.method === "GET") {
         const principal = gatedPrincipal(req, deps.config);
         if (!principal) {
-            sendJson(res, 401, { error: "unauthorized" });
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
         }
         if (deps.config.memoryEngineBackend === "file" || !deps.memoryExport) {
-            sendJson(res, 501, { error: "memory export requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)" });
+            sendError(res, 501, "capability.memory_store_required", "memory export requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)");
             return;
         }
         const scope = new URL(req.url ?? "", "http://x").searchParams.get("scope");
         if (!scope) {
-            sendJson(res, 400, { error: "missing ?scope=<key>" });
+            sendError(res, 400, "request.query_invalid", "missing ?scope=<key>");
             return;
         }
         if (scope !== formatUserScope(principal) && !explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
-            sendJson(res, 404, { error: "not found" });
+            sendError(res, 404, "not_found.memory_scope", "not found");
             return;
         }
         try {
@@ -35,18 +35,18 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
         }
         catch (err) {
             deps.logger?.warn?.("memory_export_failed", { scope, err: String(err) });
-            sendJson(res, 500, { error: "memory export failed" });
+            sendError(res, 500, "internal.error", "memory export failed");
         }
         return;
     }
     if (req.method === "POST" && url.startsWith("/v1/memory/sync/")) {
         const principal = gatedPrincipal(req, deps.config);
         if (!principal) {
-            sendJson(res, 401, { error: "unauthorized" });
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
         }
         if (deps.config.memoryEngineBackend === "file" || !deps.memorySync) {
-            sendJson(res, 501, { error: "memory sync requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)" });
+            sendError(res, 501, "capability.memory_store_required", "memory sync requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)");
             return;
         }
         let scope;
@@ -62,7 +62,7 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
             return;
         }
         if (scope !== formatUserScope(principal) && !explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
-            sendJson(res, 404, { error: "not found" });
+            sendError(res, 404, "not_found.memory_scope", "not found");
             return;
         }
         const body = await readJson(req);
@@ -77,14 +77,14 @@ async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
         }
         catch (err) {
             deps.logger?.warn?.("memory_sync_failed", { scope, peer: parsed.value.peer, err: String(err) });
-            sendJson(res, 500, { error: "memory sync failed" });
+            sendError(res, 500, "internal.error", "memory sync failed");
         }
         return;
     }
     if (url === "/v1/policy" && req.method === "GET") {
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
-            sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
         }
         sendJson(res, 200, {

package/dist/http/routes/notify-wake.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare function handleNotifyWake(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=notify-wake.d.ts.map

package/dist/http/routes/notify-wake.js

@@ -0,0 +1,133 @@
+import { taskNotificationInboxEntry } from "../../orchestration/workflow-completion-inbox.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export async function handleNotifyWake(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleNotifyWakeBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleNotifyWakeBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { steerableRuns } = ctx.registry;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
+    const { resumeWake } = ctx.legs;
+    if (req.method === "POST" && /^\/v1\/sessions\/[^/]+\/notify$/.test(url)) {
+        if (rateLimited(req, res) || quotaExceeded(req, res))
+            return;
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && principal === undefined) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const notifySession = decodeURIComponent(url.split("/")[3]);
+        let nb;
+        try {
+            nb = (await readJson(req));
+        }
+        catch {
+            sendError(res, 400, "request.body_shape", "body must be JSON: { task_id, status, summary, result?, seq?, source? }");
+            return;
+        }
+        if (typeof nb.task_id !== "string" || nb.task_id.trim().length === 0 || nb.task_id.length > 190) {
+            sendError(res, 400, "request.field_invalid", "task_id must be a non-empty string of at most 190 characters");
+            return;
+        }
+        const NOTIFY_STATUSES = ["completed", "failed", "killed", "cancelled", "event"];
+        if (typeof nb.status !== "string" || !NOTIFY_STATUSES.includes(nb.status)) {
+            sendError(res, 400, "request.field_invalid", `status must be one of ${NOTIFY_STATUSES.join("/")}`);
+            return;
+        }
+        if (typeof nb.summary !== "string" || nb.summary.trim().length === 0) {
+            sendError(res, 400, "request.field_invalid", "summary must be a non-empty string");
+            return;
+        }
+        if (nb.result !== undefined && typeof nb.result !== "string") {
+            sendError(res, 400, "request.field_invalid", "result must be a string when present");
+            return;
+        }
+        if (nb.seq !== undefined && (typeof nb.seq !== "number" || !Number.isInteger(nb.seq) || nb.seq < 1)) {
+            sendError(res, 400, "request.field_invalid", "seq must be a positive integer when present");
+            return;
+        }
+        if (nb.source !== undefined && (typeof nb.source !== "string" || nb.source.length > 190)) {
+            sendError(res, 400, "request.field_invalid", "source must be a string of at most 190 characters when present");
+            return;
+        }
+        if (!deps.sessionStorage?.ownerOf) {
+            sendError(res, 501, "capability.session_ownership_required", "external notify requires the session-ownership face (sessionStorage.ownerOf)");
+            return;
+        }
+        const notifyOwner = await deps.sessionStorage.ownerOf(notifySession);
+        if (notifyOwner === undefined) {
+            sendError(res, 404, "not_found.session", "session not found");
+            return;
+        }
+        const notifyOperator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+        if (!notifyOperator && notifyOwner !== null && notifyOwner !== principal) {
+            sendError(res, 404, "not_found.session", "session not found");
+            return;
+        }
+        const payload = {
+            task_id: nb.task_id,
+            status: nb.status,
+            summary: nb.summary,
+            ...(nb.result !== undefined ? { result: nb.result } : {}),
+            ...(nb.seq !== undefined ? { seq: nb.seq } : {}),
+            ...(nb.source !== undefined ? { source: nb.source } : {}),
+        };
+        const liveTaskId = await deps.runStore?.getActiveTaskId?.(notifySession).catch(() => undefined);
+        const liveStream = liveTaskId !== undefined && liveTaskId !== null ? steerableRuns.get(liveTaskId) : undefined;
+        if (liveStream) {
+            try {
+                await liveStream.notify(payload);
+                sendJson(res, 200, { sessionId: notifySession, delivery: "live" });
+                return;
+            }
+            catch (e) {
+                const code = e.code;
+                if (typeof code === "string" && code.startsWith("notify.")) {
+                    sendError(res, 400, code, e instanceof Error ? e.message : "invalid notification");
+                    return;
+                }
+            }
+        }
+        if (!deps.workflowCompletionInbox) {
+            sendError(res, 501, "capability.workflow_store_required", "external notify park requires the workflow completion inbox (WORKFLOW_RUN_STORE)");
+            return;
+        }
+        await deps.workflowCompletionInbox.enqueue(taskNotificationInboxEntry(notifySession, notifyOwner ?? principal ?? null, { task_id: payload.task_id, task_type: "external", status: payload.status, summary: payload.summary, ...(payload.result !== undefined ? { result: payload.result } : {}), ...(payload.seq !== undefined ? { seq: payload.seq } : {}), ...(payload.source !== undefined ? { source: payload.source } : {}) }, Date.now()));
+        sendJson(res, 202, { sessionId: notifySession, delivery: "parked", note: "no live stream — parked in the session inbox; drained as a task_notification on the next stream open" });
+        return;
+    }
+    if (req.method === "POST" && /^\/v1\/sessions\/[^/]+\/wake$/.test(url)) {
+        if (!deps.checkpointStore) {
+            sendError(res, 501, "capability.checkpoint_store_required", "wake requires the checkpoint store");
+            return;
+        }
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+            return;
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && principal === undefined) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const wakeSession = decodeURIComponent(url.split("/")[3]);
+        let wakeBody;
+        try {
+            wakeBody = (await readJson(req));
+        }
+        catch {
+            sendError(res, 400, "request.body_shape", "body must be JSON: { message?: string }");
+            return;
+        }
+        if (wakeBody.message !== undefined && (typeof wakeBody.message !== "string" || wakeBody.message.length === 0)) {
+            sendError(res, 400, "request.field_invalid", "message must be a non-empty string when present");
+            return;
+        }
+        const out = await resumeWake(wakeSession, wakeBody.message, principal, req);
+        sendJson(res, out.status, out.body);
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=notify-wake.js.map