@sema-agent/server 1.315.0 → 1.317.0

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

@@ -0,0 +1,105 @@
+import { formatUserScope } from "@sema-agent/core";
+import { parseMemorySyncRequest } from "../../memory-sync.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+export async function handleMemoryPolicy(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleMemoryPolicyBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleMemoryPolicyBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const { readJson } = ctx.helpers;
+    if (url === "/v1/memory/export" && req.method === "GET") {
+        const principal = gatedPrincipal(req, deps.config);
+        if (!principal) {
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
+            return;
+        }
+        if (deps.config.memoryEngineBackend === "file" || !deps.memoryExport) {
+            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) {
+            sendError(res, 400, "request.query_invalid", "missing ?scope=<key>");
+            return;
+        }
+        if (scope !== formatUserScope(principal) && !explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+            sendError(res, 404, "not_found.memory_scope", "not found");
+            return;
+        }
+        try {
+            const entries = await deps.memoryExport(scope);
+            sendJson(res, 200, { scope, exportedAt: new Date().toISOString(), entries });
+        }
+        catch (err) {
+            deps.logger?.warn?.("memory_export_failed", { scope, err: String(err) });
+            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) {
+            sendError(res, 401, "auth.unauthorized", "unauthorized");
+            return;
+        }
+        if (deps.config.memoryEngineBackend === "file" || !deps.memorySync) {
+            sendError(res, 501, "capability.memory_store_required", "memory sync requires a DB memory backend (MEMORY_ENGINE_BACKEND=pg|tidb)");
+            return;
+        }
+        let scope;
+        try {
+            scope = decodeURIComponent(url.slice("/v1/memory/sync/".length));
+        }
+        catch {
+            sendError(res, 400, "memory_sync_invalid_scope", "malformed percent-encoding in :scope", { code: "memory_sync_invalid_scope" });
+            return;
+        }
+        if (scope.length === 0) {
+            sendError(res, 400, "memory_sync_invalid_scope", "missing :scope", { code: "memory_sync_invalid_scope" });
+            return;
+        }
+        if (scope !== formatUserScope(principal) && !explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+            sendError(res, 404, "not_found.memory_scope", "not found");
+            return;
+        }
+        const body = await readJson(req);
+        const parsed = parseMemorySyncRequest(body, scope);
+        if (!parsed.ok) {
+            sendError(res, 422, "memory_sync_invalid_body", parsed.error, { code: "memory_sync_invalid_body" });
+            return;
+        }
+        try {
+            const out = await deps.memorySync(scope, parsed.value);
+            sendJson(res, 200, out);
+        }
+        catch (err) {
+            deps.logger?.warn?.("memory_sync_failed", { scope, peer: parsed.value.peer, err: String(err) });
+            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) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        sendJson(res, 200, {
+            autonomy: deps.config.autonomy ?? null,
+            commandPolicy: deps.config.commandPolicy ?? [],
+            approvalRequire: deps.config.approvalRequire,
+            limits: {
+                maxTaskCostUsd: deps.config.maxTaskCostUsd,
+                maxTaskTokens: deps.config.maxTaskTokens,
+                maxPrincipalCostUsd: deps.config.maxPrincipalCostUsd,
+                costQuotaWindowSec: deps.config.costQuotaWindowSec,
+            },
+        });
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=memory-policy.js.map

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

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

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

package/dist/http/routes/observability.js

@@ -0,0 +1,63 @@
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, isOperator, explicitOperatorOk } from "../principal-gate.js";
+export async function handleObservability(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleObservabilityBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleObservabilityBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    if (url === "/v1/outcomes" && req.method === "GET") {
+        if (deps.config.requirePrincipal) {
+            const principal = gatedPrincipal(req, deps.config);
+            if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+                sendError(res, 403, "auth.operator_only", "outcomes view is operator-only on a multi-tenant worker");
+                return;
+            }
+        }
+        if (!deps.outcomeSink?.summary) {
+            sendError(res, 501, "capability.outcome_ledger_required", "no queryable outcome ledger on this worker (File sink — read the JSONL dataset directly)");
+            return;
+        }
+        const q = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const sig = q.get("signature") ?? undefined;
+        try {
+            const rows = await deps.outcomeSink.summary({ ...(sig ? { taskSignature: sig } : {}), includeAborted: q.get("includeAborted") === "true" });
+            sendJson(res, 200, { outcomes: rows });
+        }
+        catch (err) {
+            deps.logger?.warn?.("outcomes_summary_failed", { err: String(err) });
+            sendError(res, 500, "internal.error", "outcome summary failed");
+        }
+        return;
+    }
+    if (url === "/v1/usage" && req.method === "GET") {
+        const principal = gatedPrincipal(req, deps.config);
+        if (!principal) {
+            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            return;
+        }
+        const windowSec = deps.config.costQuotaWindowSec;
+        if (!deps.costQuota) {
+            sendJson(res, 200, { enabled: false, windowSec, maxTaskCostUsd: deps.config.maxTaskCostUsd, maxTaskTokens: deps.config.maxTaskTokens });
+            return;
+        }
+        const d = deps.costQuota.check(principal);
+        sendJson(res, 200, {
+            enabled: true,
+            windowSec,
+            usedMicroUsd: d.usedMicroUsd,
+            usedUsd: d.usedMicroUsd / 1_000_000,
+            limitMicroUsd: d.limitMicroUsd,
+            limitUsd: d.limitMicroUsd / 1_000_000,
+            remainingMicroUsd: Math.max(0, d.limitMicroUsd - d.usedMicroUsd),
+            overLimit: !d.allowed,
+            retryAfterSec: d.retryAfterSec,
+            maxTaskCostUsd: deps.config.maxTaskCostUsd,
+            maxTaskTokens: deps.config.maxTaskTokens,
+        });
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=observability.js.map

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

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare const RUN_ID_RE: RegExp;
+export declare const RUN_CANCEL_RE: RegExp;
+export declare const RUN_STEER_RE: RegExp;
+export declare const RUN_DETACH_RE: RegExp;
+export declare const RUN_COMPACT_RE: RegExp;
+export declare const ELICIT_RESPOND_RE: RegExp;
+export declare const QUESTION_RESPOND_RE: RegExp;
+export declare const TOOL_APPROVAL_RESPOND_RE: RegExp;
+export declare const RUN_SUBAGENT_STEER_RE: RegExp;
+export declare const RUN_SUBAGENT_RESUME_RE: RegExp;
+export declare const RUN_SUBAGENT_OUTPUT_RE: RegExp;
+export declare const RUN_SUBAGENT_STREAM_RE: RegExp;
+export declare const RUN_TASK_OUTPUT_RE: RegExp;
+export declare const RUN_TASK_STOP_RE: RegExp;
+export declare function handleRuns(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+export declare function handleRunVerbs(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=runs.d.ts.map