@sema-agent/server 1.185.0 → 1.187.0

package/dist/http/server.js

@@ -1,7 +1,7 @@
 import http from "node:http";
 import { once } from "node:events";
 import { timingSafeEqual, createHash, randomBytes } from "node:crypto";
-import { uuidv7, isThinkingLevel, DEFAULT_EFFORT_LEVELS, materializeMcpTools, runWithVerification, resumeWithVerification, runCascade, CheckpointError, SessionPolicyError, SessionError, HAND_TOOL_EFFECTS, canonicalToolName, formatUserScope, validatePendingSteer, StreamingImportValidator, listWorkflowRuns, getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus } from "@sema-agent/core";
+import { uuidv7, isThinkingLevel, DEFAULT_EFFORT_LEVELS, materializeMcpTools, runWithVerification, resumeWithVerification, runCascade, CheckpointError, mintCheckpointToken, SessionPolicyError, SessionError, HAND_TOOL_EFFECTS, canonicalToolName, formatUserScope, validatePendingSteer, StreamingImportValidator, listWorkflowRuns, getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus } from "@sema-agent/core";
 import { mcpForScenario } from "../sema-registry.js";
 import { HttpError, principalFrom, verifiedPrincipal, setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isUuidV7, isUuidShape, verifyDirectDoorProof } from "../security.js";
 import { exportSession, exportSessionManifest, importSession, classifySyncRelationshipByIds, SyncConflictError, stagingIdFor } from "../session-sync.js";
@@ -17,7 +17,7 @@ import { manifestToIndexEntry } from "../images/manifest.js";
 import { runInBackground, evictIfConflict, stripCheckpointToken, resumeAtHttpStatus, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
 import { looksLikeJwt } from "../auth-bridge.js";
 import { redactSteerIn } from "../orchestration/workflow-agent-steer.js";
-import { emitPendingWorkflowCompletions, taskNotificationInboxEntry } from "../orchestration/workflow-completion-inbox.js";
+import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationFoldKey } from "../orchestration/workflow-completion-inbox.js";
 import { fleetRunPublisher, fleetRunLabels } from "../fleet/fleet-bus.js";
 import { RateLimiter } from "../observability/rate-limit.js";
 import { withPrincipal } from "../observability/principal-context.js";
@@ -177,6 +177,7 @@ export function createHttpServer(deps) {
     const inflightRuns = new Map();
     const preemptableRuns = new Map();
     const steerableRuns = new Map();
+    const wakeParkMints = new Map();
     let uncountedBillableInflight = 0;
     if (deps.drainState)
         deps.drainState.inflight = () => new Set([...inflightRuns.keys(), ...steerableRuns.keys()]).size + uncountedBillableInflight + (deps.leaderEndpoint?.inflight?.() ?? 0);
@@ -590,6 +591,8 @@ export function createHttpServer(deps) {
                 rewindFilesTo: Boolean(deps.fileSnapshotStore && deps.resumeAnchorStore && deps.sessionStorage?.getLeafId),
                 scheduler: Boolean(deps.config.schedulerEnabled && deps.config.requirePrincipal !== true && deps.config.remoteExec?.provider === "host"),
                 sessionSync: Boolean(deps.backend && deps.sessionStorage?.exportEntries && deps.fileSnapshotStore),
+                sendUserFile: Boolean(deps.config.sendUserFile),
+                s3PublicEndpoint: deps.config.sendUserFile?.publicEndpoint ?? null,
                 workflows: deps.workflowsCapable ?? Boolean(deps.workflowRunStore),
                 workflowsList: Boolean(deps.workflowRunStore),
                 manualCompact: Boolean(deps.runStore),
@@ -847,9 +850,12 @@ export function createHttpServer(deps) {
                             const withElicit = deps.elicitation
                                 ? () => deps.elicitation.runWithContext({ taskId: askTaskId, owner: askOwner, emit: emitAsk, abortSignal: ac.signal }, streamBody)
                                 : streamBody;
-                            await (deps.question
+                            const withQuestion = () => deps.question
                                 ? deps.question.runWithContext({ taskId: askTaskId, owner: askOwner, emit: emitAsk, abortSignal: ac.signal }, withElicit)
-                                : withElicit());
+                                : withElicit();
+                            await (deps.sendUserFile
+                                ? deps.sendUserFile.runWithContext({ taskId: askTaskId, emit: async (f) => void (await emitAsk(f)) }, withQuestion)
+                                : withQuestion());
                             if (durableTaskId && deps.runStore) {
                                 if (finalResult?.status === "suspended" && deps.checkpointStore)
                                     await deps.runStore.setSuspended(durableTaskId);
@@ -1030,7 +1036,7 @@ export function createHttpServer(deps) {
                     rootTaskId: taskId,
                     ...fleetRunLabels(prepared.spec.objective),
                 });
-                void runInBackground(deps.runner, { ...prepared.spec, sessionId }, runStore, taskId, deps.metrics, prepared.auth?.principal, prepared.verify?.maxRounds, prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, prepared.spec.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, gatedPrincipal(req, deps.config) ?? null, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x));
+                void runInBackground(deps.runner, { ...prepared.spec, sessionId }, runStore, taskId, deps.metrics, prepared.auth?.principal, prepared.verify?.maxRounds, prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, prepared.spec.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, gatedPrincipal(req, deps.config) ?? null, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile);
                 return { status: 202, body: { taskId, sessionId, status: "running" } };
             }, (r) => r.status === 202);
             sendJson(res, resp.status, resp.body);
@@ -1240,7 +1246,66 @@ export function createHttpServer(deps) {
                 sendNotRunning("run is no longer suspended (resolved or expired)");
                 return;
             }
-            sendNotRunning(run.status === "running" ? "run is active on another replica — cross-replica live-steer is not yet supported" : `run is ${run.status} — not accepting steers`);
+            if (run.status === "running") {
+                sendNotRunning("run is active on another replica — cross-replica live-steer is not yet supported");
+                return;
+            }
+            if (deps.checkpointStore && deps.sessionStorage?.getLeafId) {
+                const activeTaskId = await deps.runStore.getActiveTaskId?.(run.sessionId).catch(() => undefined);
+                if (activeTaskId !== undefined && activeTaskId !== null && activeTaskId !== taskId) {
+                    sendNotRunning(`run is ${run.status} and its session has an ACTIVE run (${activeTaskId}) — steer that run instead`);
+                    return;
+                }
+                const prior = wakeParkMints.get(run.sessionId) ?? Promise.resolve();
+                const mintResult = { parked: false };
+                const job = prior.then(async () => {
+                    const cs = deps.checkpointStore;
+                    if (await tryPark() === "parked") {
+                        mintResult.parked = true;
+                        return;
+                    }
+                    const leafId = await Promise.resolve(deps.sessionStorage.getLeafId(run.sessionId)).catch(() => undefined);
+                    if (leafId === undefined || leafId === null)
+                        return;
+                    const cpScope = run.owner ?? "_";
+                    const wakeToken = mintCheckpointToken();
+                    await cs.put(wakeToken, {
+                        token: wakeToken,
+                        scope: cpScope,
+                        sessionId: run.sessionId,
+                        leafId,
+                        gate: { kind: "task_done" },
+                        pendingAction: { kind: "task_done" },
+                        state: { activeTools: [], nestedStats: { tokens: 0, turns: 0, tasks: 0, costUsd: 0, costMicroUsd: 0 } },
+                        status: "pending",
+                        createdAt: Date.now(),
+                        sourceTaskId: taskId,
+                    });
+                    const winner = await cs.findPendingTokenBySession(run.sessionId).catch(() => null);
+                    if (winner !== null && winner !== wakeToken) {
+                        await cs.expire(wakeToken, cpScope).catch(() => undefined);
+                        if (await cs.setPendingSteer(winner, cpScope, { text, trusted }))
+                            mintResult.parked = true;
+                        return;
+                    }
+                    if (await cs.setPendingSteer(wakeToken, cpScope, { text, trusted }))
+                        mintResult.parked = true;
+                });
+                const wrapped = job.catch(() => undefined);
+                wakeParkMints.set(run.sessionId, wrapped);
+                try {
+                    await job;
+                }
+                finally {
+                    if (wakeParkMints.get(run.sessionId) === wrapped)
+                        wakeParkMints.delete(run.sessionId);
+                }
+                if (mintResult.parked) {
+                    sendJson(res, 202, { taskId, status: run.status, delivery: "parked_for_wake", messageId, ...(priority ? { priority } : {}), note: "run already ended — steer parked on a task_done checkpoint; deliver it with POST /v1/sessions/:id/wake" });
+                    return;
+                }
+            }
+            sendNotRunning(`run is ${run.status} — not accepting steers`);
             return;
         }
         const compactMatch = req.method === "POST" ? RUN_COMPACT_RE.exec(url) : null;
@@ -3189,10 +3254,121 @@ export function createHttpServer(deps) {
                 return;
             }
         }
+        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) {
+                sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                return;
+            }
+            const notifySession = decodeURIComponent(url.split("/")[3]);
+            let nb;
+            try {
+                nb = (await readJson(req));
+            }
+            catch {
+                sendJson(res, 400, { error: "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) {
+                sendJson(res, 400, { error: "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)) {
+                sendJson(res, 400, { error: `status must be one of ${NOTIFY_STATUSES.join("/")}` });
+                return;
+            }
+            if (typeof nb.summary !== "string" || nb.summary.trim().length === 0) {
+                sendJson(res, 400, { error: "summary must be a non-empty string" });
+                return;
+            }
+            if (nb.result !== undefined && typeof nb.result !== "string") {
+                sendJson(res, 400, { error: "result must be a string when present" });
+                return;
+            }
+            if (nb.seq !== undefined && (typeof nb.seq !== "number" || !Number.isInteger(nb.seq) || nb.seq < 1)) {
+                sendJson(res, 400, { error: "seq must be a positive integer when present" });
+                return;
+            }
+            if (nb.source !== undefined && (typeof nb.source !== "string" || nb.source.length > 190)) {
+                sendJson(res, 400, { error: "source must be a string of at most 190 characters when present" });
+                return;
+            }
+            if (!deps.sessionStorage?.ownerOf) {
+                sendJson(res, 501, { error: "external notify requires the session-ownership face (sessionStorage.ownerOf)" });
+                return;
+            }
+            const notifyOwner = await deps.sessionStorage.ownerOf(notifySession);
+            if (notifyOwner === undefined) {
+                sendJson(res, 404, { error: "session not found" });
+                return;
+            }
+            const notifyOperator = explicitOperatorOk(principal, deps.config.operatorPrincipals);
+            if (!notifyOperator && notifyOwner !== null && notifyOwner !== principal) {
+                sendJson(res, 404, { error: "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.")) {
+                        sendJson(res, 400, { errorCode: code, error: e instanceof Error ? e.message : "invalid notification" });
+                        return;
+                    }
+                }
+            }
+            if (!deps.workflowCompletionInbox) {
+                sendJson(res, 501, { error: "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)) {
-            sendJson(res, 501, {
-                error: "explicit wake is unnecessary — re-issue a task/run with the same sessionId; the durable session resumes (and reconciles) automatically",
-            });
+            if (!deps.checkpointStore) {
+                sendJson(res, 501, { error: "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) {
+                sendJson(res, 401, { error: `missing principal header '${deps.config.principalHeader}'` });
+                return;
+            }
+            const wakeSession = decodeURIComponent(url.split("/")[3]);
+            let wakeBody;
+            try {
+                wakeBody = (await readJson(req));
+            }
+            catch {
+                sendJson(res, 400, { error: "body must be JSON: { message?: string }" });
+                return;
+            }
+            if (wakeBody.message !== undefined && (typeof wakeBody.message !== "string" || wakeBody.message.length === 0)) {
+                sendJson(res, 400, { error: "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;
         }
         sendJson(res, 404, { error: "not found" });
@@ -3799,7 +3975,8 @@ export function createHttpServer(deps) {
             if (e instanceof CheckpointError) {
                 const retriable = e.code === "checkpoint.invalid_outcome" ||
                     e.code === "checkpoint.reopen_revote" ||
-                    e.code === "checkpoint.reopened_concurrently";
+                    e.code === "checkpoint.reopened_concurrently" ||
+                    e.code.startsWith("wake.");
                 if (claimedRow && taskId && deps.runStore) {
                     if (retriable) {
                         await (outcome.gate === "plan_review" ? deps.runStore.setNeedsReview(taskId) : deps.runStore.setSuspended(taskId)).catch(() => undefined);
@@ -3894,6 +4071,63 @@ export function createHttpServer(deps) {
         const verifyRounds = ctx.body.verify === true ? clampVerifyRounds(ctx.body.verifyRounds) : undefined;
         return driveResumeIntoRunLog({ token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, verifyRounds });
     }
+    async function resumeWake(sessionId, message, caller, req) {
+        const cs = deps.checkpointStore;
+        const token = await cs.findPendingTokenBySession(sessionId);
+        if (!token)
+            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)" } };
+        const operator = explicitOperatorOk(caller, deps.config.operatorPrincipals);
+        if (!operator) {
+            const scope = await cs.peekPendingScope(sessionId).catch(() => undefined);
+            if (scope !== null && scope !== undefined && scope !== "_" && scope !== caller) {
+                return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)" } };
+            }
+        }
+        let cp;
+        try {
+            cp = await cs.get(token);
+        }
+        catch (e) {
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e) } };
+        }
+        if (!cp)
+            return { status: 404, body: { error: "checkpoint not found" } };
+        if (!operator && cp.scope !== "_" && cp.scope !== caller) {
+            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)" } };
+        }
+        const gateKind = cp.gate?.kind;
+        if (gateKind !== "task_done") {
+            return { status: 409, body: { error: `cannot wake: this checkpoint awaits a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry`, errorCode: "wake.gate_pending" } };
+        }
+        const trusted = operator;
+        if (message !== undefined) {
+            try {
+                validatePendingSteer({ text: message, trusted });
+            }
+            catch (e) {
+                if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
+                    return { status: 422, body: { errorCode: "steering.invalid_content", error: e.message } };
+                }
+                throw e;
+            }
+        }
+        const ctx = await cs.getCtx(sessionId).catch(() => null);
+        if (!ctx)
+            return { status: 409, body: { error: "resume context missing — cannot rebuild task config" } };
+        const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        const spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
+        const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        return driveResumeIntoRunLog({
+            token,
+            sessionId: cp.sessionId,
+            principal: auth.principal,
+            fleetScope: resumeFleetScope(req, auth),
+            taskConfig,
+            resumeObjective,
+            outcome: { gate: "wake", ...(message !== undefined ? { message: { text: message, trusted } } : {}) },
+            verifyRounds: undefined,
+        });
+    }
     async function resumePlanReview(sessionId, decision, editedPlan, reason, req) {
         const cs = deps.checkpointStore;
         const token = await cs.findPendingTokenBySession(sessionId);
@@ -4717,7 +4951,8 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                         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) {
-                            void completionInbox.markTerminalServed(n.ownerSessionId, n.taskId).catch(() => undefined);
+                            const family = taskNotificationFoldKey({ task_id: n.taskId, status: n.status });
+                            void completionInbox.markTerminalServed(n.ownerSessionId, family).catch(() => undefined);
                         }
                     }
                     break;