@sema-agent/server 7.138.0 → 7.139.0

package/dist/http/routes/session-sync.js

@@ -18,6 +18,10 @@ import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
 import { readSessionRulesRecords, describeSessionRulesRecordProblem } from "../../session-policy-wire.js";
 import { readSessionPinned, readSessionTitle } from "../../session-row.js";
 import { sessionFaceOfHead } from "../../session-incarnation.js";
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { SessionActiveRunError, SessionForkInProgressError, SessionWriterPresentError } from "../../execution-placement.js";
+import { probeSessionChildren, sessionChildrenScope } from "../../session-children-retire.js";
+import { liveChildrenRefusal } from "./background.js";
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
     const importLeases = new Map();
@@ -90,7 +94,46 @@ export async function handleSessionSync(req, res, match, ctx) {
             const replaySessionRow = async (row, face) => {
                 if (Object.keys(row).length === 0)
                     return true;
-                return face !== undefined && (await sessionStorage.patchSessionMeta(sessionId, row, face)) !== undefined;
+                if (face === undefined)
+                    return false;
+                const replayed = await sessionStorage.writeSessionRowCells(sessionId, row, { writer: "replay", row: { row: face } });
+                switch (replayed.kind) {
+                    case "written":
+                        return true;
+                    case "absent":
+                        return false;
+                    default: {
+                        const unreachable = replayed;
+                        throw new Error(`session-sync row replay: no answer for the row write outcome ${JSON.stringify(unreachable)}`);
+                    }
+                }
+            };
+            const liveChildrenOf = async (face) => face === undefined
+                ? []
+                : (await probeSessionChildren({ agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry }, sessionId, sessionChildrenScope(face.owner))).liveChildren;
+            const activityOf = async (face) => {
+                const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
+                if (activeTaskId)
+                    return { kind: "run", activeTaskId };
+                const liveChildren = await liveChildrenOf(face);
+                return liveChildren.length > 0 ? { kind: "children", liveChildren } : undefined;
+            };
+            const sendActivity = (activity, moment) => {
+                switch (activity.kind) {
+                    case "run":
+                        if (moment === "open")
+                            sendError(res, 409, "session_active", "session has an active run; sync after it settles", { activeTaskId: activity.activeTaskId });
+                        else
+                            sendError(res, 409, "session_active", "session started an active run while the import streamed; sync after it settles", { activeTaskId: activity.activeTaskId });
+                        return;
+                    case "children":
+                        sendError(res, 409, "session_active", "session still has background agents running or waiting on an approval under it; retire them (POST retirePath) or let them finish, then sync", liveChildrenRefusal(sessionId, activity.liveChildren));
+                        return;
+                    default: {
+                        const unhandled = activity;
+                        throw new Error(`session sync: unknown session activity ${JSON.stringify(unhandled)}`);
+                    }
+                }
             };
             const canReplayHistory = fileHistoryImportFace(historyStore) !== undefined;
             const replayHistory = async (envelope, allowReplace) => {
@@ -339,15 +382,56 @@ export async function handleSessionSync(req, res, match, ctx) {
                     if (!payloadVerified)
                         digestSaysDiffer = true;
                 }
+                const placed = gateFace === undefined ? undefined : await sessionStorage.executionPlacement?.read(sessionId);
+                if (placed !== undefined) {
+                    switch (placed.cell.role) {
+                        case "absent":
+                        case "mirror":
+                            break;
+                        case "writer":
+                            sendSessionWriter(res);
+                            return;
+                        case "forking":
+                            sendError(res, 409, "conflict.fork_in_progress", new SessionForkInProgressError(sessionId).message);
+                            return;
+                        default: {
+                            const unknownRole = placed.cell;
+                            throw new Error(`session sync: unknown execution placement ${JSON.stringify(unknownRole)}`);
+                        }
+                    }
+                }
+                const activeNow = await activityOf(gateFace);
+                if (activeNow !== undefined) {
+                    sendActivity(activeNow, "open");
+                    return;
+                }
                 if (relA.relation === "identical" && !digestSaysDiffer) {
-                    if (fileHistory !== null && canReplayHistory) {
-                        if (resolution === "overwrite-dst") {
-                            const activeNow = await deps.runStore?.getActiveTaskId(sessionId);
-                            if (activeNow) {
-                                sendError(res, 409, "session_active", "session has an active run; sync after it settles", { activeTaskId: activeNow });
+                    const seat = sessionStorage.executionPlacement;
+                    if (seat !== undefined) {
+                        if (gateFace === undefined) {
+                            sendError(res, 409, "conflict", "sync conflict");
+                            return;
+                        }
+                        const mirrored = await seat.markMirror(sessionId, gateFace);
+                        switch (mirrored.outcome) {
+                            case "mirrored":
+                                break;
+                            case "writer":
+                                sendSessionWriter(res);
+                                return;
+                            case "gone":
+                                sendError(res, 409, "conflict", "sync conflict");
+                                return;
+                            case "active":
+                                sendActivity({ kind: "run", activeTaskId: mirrored.activeTaskId }, "open");
                                 return;
+                            default: {
+                                const unhandled = mirrored;
+                                throw new Error(`session sync: unknown mirror outcome ${JSON.stringify(unhandled)}`);
                             }
                         }
+                    }
+                    if (fileHistory !== null && canReplayHistory) {
                         const failed = await replayHistory(fileHistory, resolution === "overwrite-dst");
                         if (failed !== undefined) {
                             sendFileHistoryReplayFailure(res, failed);
@@ -380,11 +464,6 @@ export async function handleSessionSync(req, res, match, ctx) {
                     });
                     return;
                 }
-                const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
-                if (activeTaskId) {
-                    sendError(res, 409, "session_active", "session has an active run; sync after it settles", { activeTaskId });
-                    return;
-                }
                 const heldLease = importLeases.get(sessionId);
                 if (heldLease) {
                     const staleSecRaw = deps.config.syncImportLeaseStaleSec;
@@ -511,8 +590,9 @@ export async function handleSessionSync(req, res, match, ctx) {
                 let mayPushAtCommit;
                 let activeAtCommit;
                 try {
-                    mayPushAtCommit = (await judgeSessionGate()).mayPush;
-                    activeAtCommit = mayPushAtCommit ? await deps.runStore?.getActiveTaskId(sessionId) : undefined;
+                    const gateAtCommit = await judgeSessionGate();
+                    mayPushAtCommit = gateAtCommit.mayPush;
+                    activeAtCommit = mayPushAtCommit ? await activityOf(gateAtCommit.face) : undefined;
                 }
                 catch (e) {
                     await pending.handle.abort().catch(() => undefined);
@@ -525,10 +605,10 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendSessionAbsent();
                     return;
                 }
-                if (activeAtCommit) {
+                if (activeAtCommit !== undefined) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
-                    sendError(res, 409, "session_active", "session started an active run while the import streamed; sync after it settles", { activeTaskId: activeAtCommit });
+                    sendActivity(activeAtCommit, "streamed");
                     return;
                 }
                 try {
@@ -567,6 +647,18 @@ export async function handleSessionSync(req, res, match, ctx) {
                         sendError(res, 409, "conflict", "sync conflict", { relation: e.relation });
                         return;
                     }
+                    if (e instanceof SessionWriterPresentError) {
+                        sendSessionWriter(res);
+                        return;
+                    }
+                    if (e instanceof SessionForkInProgressError) {
+                        sendError(res, 409, "conflict.fork_in_progress", e.message);
+                        return;
+                    }
+                    if (e instanceof SessionActiveRunError) {
+                        sendActivity({ kind: "run", activeTaskId: e.activeTaskId }, "streamed");
+                        return;
+                    }
                     if (sendSessionPolicyError(res, e))
                         return;
                     if (sendSessionError(res, e, "import")) {
@@ -635,6 +727,9 @@ function sendPullUnreadable(req, res, logger, e) {
         }
     }
 }
+function sendSessionWriter(res) {
+    sendError(res, 409, "conflict.session_writer", "this session is written on this deployment (its execution placement is a writer here) — an import cannot turn it into a read-only mirror; fork it to push your copy, or pull instead; nothing was written");
+}
 function sendMissingBlob(res) {
     sendError(res, 422, "missing_blob", "missing blob; PUT all referenced blobs before import");
 }

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

@@ -74,6 +74,12 @@ export declare const SESSIONS_ROUTES: readonly [{
     readonly pattern: RegExp;
     readonly label: "/v1/sessions/:id/$verb";
     readonly methods: readonly ["GET"];
+}, {
+    readonly id: "session-execution-placement";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id/execution-placement";
+    readonly credentialGated: readonly ["GET"];
+    readonly methods: readonly ["GET"];
 }, {
     readonly id: "session-events";
     readonly pattern: RegExp;

package/dist/http/routes/sessions.js

@@ -18,6 +18,10 @@ import * as facts from "../../capability-facts.js";
 import { rosterAgentId } from "./agents-roster.js";
 import { projectSessionListRow } from "./sessions-list.js";
 import { readSessionRowPatch } from "../../session-row.js";
+import { forkPathOf } from "../execution-context.js";
+import { executionPlacementView } from "../../execution-placement.js";
+import { ForkTargetUnsettledError, forkKeyOf } from "../../plugins/session-fork.js";
+import { fieldConflictFacts } from "../../field-conflict.js";
 import { buildBoundedToolNames } from "../../panel-tool-names.js";
 import { projectMcpAuthorization } from "../../mcp-authorization-face.js";
 const MCP_STATUS_TTL_MS = 5_000;
@@ -172,7 +176,7 @@ export async function handleSessions(req, res, match, ctx) {
                     mcpStatusCache.clear();
                 const panel = (async () => {
                     const stopDial = new AbortController();
-                    const matP = materializeMcpTools(specs, principal, undefined, undefined, undefined, deps.mcpRevocations, undefined, undefined, undefined, stopDial.signal, undefined, deps.peerDesk.seat.answer);
+                    const matP = materializeMcpTools(specs, principal, undefined, undefined, undefined, deps.mcpRevocations, undefined, undefined, undefined, stopDial.signal, undefined, deps.peerDesk.seat);
                     const mat = await raceDeadline(matP, MCP_DIAL_DEADLINE_MS).catch(() => null);
                     if (!mat) {
                         stopDial.abort();
@@ -221,7 +225,7 @@ export async function handleSessions(req, res, match, ctx) {
                 if (a2aStatusCache.size > 1024)
                     a2aStatusCache.clear();
                 const panel = (async () => {
-                    const matP = materializeA2aTools(specs, principal, undefined, undefined, deps.peerDesk.seat.answer);
+                    const matP = materializeA2aTools(specs, principal, undefined, undefined, deps.peerDesk.seat);
                     let timer;
                     const mat = await Promise.race([matP.catch(() => null), new Promise((r) => { timer = setTimeout(() => r(null), A2A_MATERIALIZE_TIMEOUT_MS); })]);
                     if (timer)
@@ -286,6 +290,29 @@ export async function handleSessions(req, res, match, ctx) {
             return;
         }
     }
+    {
+        if (match.decl.id === "session-execution-placement") {
+            const placementFact = facts.executionPlacementRead(deps);
+            if (!placementFact.available) {
+                sendError(res, 501, "capability.session_store_required", "the execution placement read requires a durable session store (DB_BACKEND=mysql|pg|local)");
+                return;
+            }
+            const placementSession = safeDecode(match.params.sessionId);
+            if (placementSession === null) {
+                sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
+                return;
+            }
+            const reading = await placementFact.seat.read(placementSession);
+            if (reading === undefined) {
+                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                return;
+            }
+            if (!explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config) && !sessionOwnerOk(req, res, await sessionOwnerCellOf(deps.sessionStorage, placementSession, reading.occupant.owner)))
+                return;
+            sendJson(res, 200, executionPlacementView(reading.cell));
+            return;
+        }
+    }
     {
         if (match.decl.id === "session-events") {
             const evFact = facts.sessionEventStream(deps);
@@ -675,13 +702,25 @@ export async function handleSessions(req, res, match, ctx) {
             sendError(res, 400, read.problem.code, read.problem.message);
             return;
         }
-        const row = await store.patchSessionMeta(sessionId, read.patch, face);
-        if (row === undefined) {
-            sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-            return;
+        const outcome = await store.writeSessionRowCells(sessionId, read.patch, { writer: "client", row: { row: face }, ...(read.expectedRowTag !== undefined ? { rowTag: read.expectedRowTag } : {}) });
+        switch (outcome.kind) {
+            case "written":
+                sendJson(res, 200, projectSessionListRow(outcome.row));
+                return;
+            case "changed":
+                sendError(res, 409, "conflict.session_row_changed", "the session row changed since the rowTag you sent was read — nothing was written; currentRow is the row as it stands now: decide again, then send its rowTag", { currentRow: projectSessionListRow(outcome.row) });
+                return;
+            case "mirror":
+                sendError(res, 409, "conflict.session_mirror", "this session is a read-only mirror of a session whose writer is elsewhere — it cannot be renamed or pinned here; fork it (forkPath) to continue here; nothing was written", { forkPath: forkPathOf(sessionId) });
+                return;
+            case "absent":
+                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                return;
+            default: {
+                const unknownOutcome = outcome;
+                throw new Error(`PATCH /v1/sessions/:id: no answer for the row write outcome ${JSON.stringify(unknownOutcome)}`);
+            }
         }
-        sendJson(res, 200, projectSessionListRow(row));
-        return;
     }
     {
         if (match.decl.id === "session-fork") {
@@ -712,12 +751,57 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const newOwner = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
-            const newId = await fork(sourceId, newOwner);
-            if (newId === null) {
+            const keyed = readForkTarget(await readJson(req), sourceId);
+            if (keyed.kind === "refused") {
+                sendError(res, 400, keyed.errorCode, keyed.message, keyed.facts);
+                return;
+            }
+            if (keyed.kind === "none") {
+                const newId = await fork(sourceId, newOwner);
+                if (newId === null) {
+                    sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                    return;
+                }
+                sendJson(res, 200, { sessionId: newId });
+                return;
+            }
+            const forkTo = forkFact.sessionStorage.forkTo?.bind(forkFact.sessionStorage);
+            if (forkTo === undefined) {
+                sendError(res, 501, "capability.session_store_required", "a keyed fork (forkId + forkNonce) requires a session store that creates the target row atomically (DB_BACKEND=mysql|pg|local)");
+                return;
+            }
+            let outcome;
+            try {
+                outcome = await forkTo(sourceId, newOwner, { id: keyed.forkId, key: forkKeyOf(sourceId, keyed.forkNonce) });
+            }
+            catch (e) {
+                if (e instanceof ForkTargetUnsettledError) {
+                    sendError(res, 503, "state.fork_target_unsettled", e.message, { permanence: "transient" });
+                    return;
+                }
+                throw e;
+            }
+            if (outcome === null) {
                 sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
                 return;
             }
-            sendJson(res, 200, { sessionId: newId });
+            switch (outcome.outcome) {
+                case "created":
+                    sendJson(res, 200, { sessionId: outcome.id });
+                    return;
+                case "replayed":
+                    sendJson(res, 200, { sessionId: outcome.id, replayed: true });
+                    return;
+                case "occupied":
+                    if (!outcome.sameOwner) {
+                        sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                        return;
+                    }
+                    sendError(res, 409, "conflict.fork_id_taken", "forkId already names another session of yours (a different fork, or a session that was not created by this fork request) — pick a new forkId and forkNonce; nothing was forked", { forkId: keyed.forkId });
+                    return;
+                default:
+                    assertNever(outcome);
+            }
             return;
         }
     }
@@ -853,6 +937,7 @@ export const SESSIONS_ROUTES = [
     { id: "session-mcp", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/mcp$/, label: "/v1/sessions/:id/$verb", methods: ["GET"] },
     { id: "session-a2a", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/a2a$/, label: "/v1/sessions/:id/$verb", methods: ["GET"] },
     { id: "session-head", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/head$/, label: "/v1/sessions/:id/$verb", methods: ["GET"] },
+    { id: "session-execution-placement", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/execution-placement$/, label: "/v1/sessions/:id/execution-placement", credentialGated: ["GET"], methods: ["GET"] },
     { id: "session-events", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/events$/, label: "/v1/sessions/:id/$verb", methods: ["GET"], subscription: true },
     { id: "session-fork", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/fork$/, label: "/v1/sessions/:id/$verb", methods: ["POST"] },
     { id: "session-policy-get", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/policy$/, label: "/v1/sessions/:id/$verb", methods: ["GET"] },
@@ -864,4 +949,23 @@ export const SESSIONS_ROUTES = [
     { id: "session-patch", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["PATCH"] },
     { id: "session-delete", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["DELETE"] },
 ];
+function readForkTarget(raw, sourceId) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { kind: "refused", errorCode: "request.field_invalid", message: "the fork body must be an object { forkId?, forkNonce? }" };
+    const { forkId, forkNonce } = raw;
+    if (forkId === undefined && forkNonce === undefined)
+        return { kind: "none" };
+    if (forkId === undefined || forkNonce === undefined) {
+        return { kind: "refused", errorCode: "request.field_conflict", message: "forkId and forkNonce come together — send both (a keyed, retryable fork) or neither (a fork under a freshly minted id)", facts: fieldConflictFacts("fork_target", ["forkId", "forkNonce"]) };
+    }
+    if (typeof forkId !== "string" || !isUuidShape(forkId))
+        return { kind: "refused", errorCode: "request.id_invalid", message: "forkId must be a canonical uuid (the id the forked session will have)" };
+    if (forkId === sourceId)
+        return { kind: "refused", errorCode: "request.field_invalid", message: "forkId must name a new session — it equals the session being forked" };
+    if (typeof forkNonce !== "string" || forkNonce.length === 0 || forkNonce.length > FORK_NONCE_MAX_CHARS) {
+        return { kind: "refused", errorCode: "request.field_invalid", message: `forkNonce must be a non-empty string of at most ${FORK_NONCE_MAX_CHARS} characters (the caller's key for this fork request; a retry sends the same one)` };
+    }
+    return { kind: "keyed", forkId, forkNonce };
+}
+const FORK_NONCE_MAX_CHARS = 255;
 //# sourceMappingURL=sessions.js.map

package/dist/http/routes/side-query.d.ts

@@ -8,10 +8,18 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
-/** 表内=core 的前置校验形(客户端可改请求)⇒ 400;表外一律 500。 */
-export declare function isCorePreflightValidationError(message: string): boolean;
-/** 供跨仓锚门读:门要拿这张表去装机的 core 里逐条对账(见上方 doc)。 */
-export declare const CORE_PREFLIGHT_VALIDATION_ANCHORS: readonly string[];
+/**
+ * [ref] —— core 前置校验异常的分类(400 客户端可改 / 500 我方缺陷):**只读引擎的码**。
+ * 引擎角色族的拒(未知模型引用 / 不是模型引用 / 角色词出表 / 角色链给不出模型)一律带码 `config.unknown_role`(`detail.reason` 分臂;
+ * core 7.60.0 [ref] 起最后一臂也带码)—— 这是引擎写明的判别位,本路由的 400 只认它;句子不读(修前是一张按英文开头匹配的两行前缀表,
+ * 引擎改一个字就会把客户端错误静默翻成 500)。失败方向:别的码 / 没有码一律 500(响亮、可告警、可重试),绝不把不认识的异常猜成客户端错误。
+ * 跨仓锚:test/side-query-http.test.ts 调装机 core 的两个导出解析器真抛,拿真错误过本谓词。
+ *
+ * 🪦 原表还有第三臂 `requires a non-empty messages array`(core `core/side-query.js`)—— 不可达(本路由在调 core 之前就有
+ * `!Array.isArray(body.messages) || body.messages.length === 0 ⇒ 400 request.body_shape` 的前拦),已删;前拦一旦被摘,
+ * side-query-http 的「空/非数组 messages → 400 request.body_shape」两格先红。
+ */
+export declare function isCorePreflightValidationError(err: unknown): boolean;
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。 */
 export declare function handleSideQuery(req: IncomingMessage, res: ServerResponse, match: RouteMatch<SideQueryRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const SIDE_QUERY_ROUTES: readonly [{

package/dist/http/routes/side-query.js

@@ -4,15 +4,14 @@ import { echoCallerText } from "../../caller-text-echo.js";
 import { isAtMentionable, matchCatalogModel, refusedCatalogEntry, selectableCatalog } from "../../model-select.js";
 import { echoModelRef, modelUnavailableMessage } from "../../model-entry-refusal.js";
 import { redactSecrets } from "../../trace/redact.js";
+import { errorCodeOf } from "../../observability/err-text.js";
 import { admitProviderEcho, redactErrorMessage } from "../../observability/run-terminal.js";
 import { sendJson, sendError, sendHttpError, msg } from "../send.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
-const CORE_PREFLIGHT_VALIDATION_PREFIXES = ["Unknown model ref ", "No model for role "];
-export function isCorePreflightValidationError(message) {
-    return CORE_PREFLIGHT_VALIDATION_PREFIXES.some((prefix) => message.startsWith(prefix));
+export function isCorePreflightValidationError(err) {
+    return errorCodeOf(err) === "config.unknown_role";
 }
-export const CORE_PREFLIGHT_VALIDATION_ANCHORS = CORE_PREFLIGHT_VALIDATION_PREFIXES;
 const MODEL_ROLE_ECHO_CHARS = 80;
 function isModelRole(value) {
     return typeof value === "string" && MODEL_ROLES.includes(value);
@@ -105,7 +104,7 @@ export async function handleSideQuery(req, res, match, ctx) {
                     deps.metrics?.inc?.("side_query_total", { result: "error" });
                     if (!res.writableEnded && !ac.signal.aborted) {
                         const m = msg(e);
-                        const isValidation = isCorePreflightValidationError(m);
+                        const isValidation = isCorePreflightValidationError(e);
                         sendError(res, isValidation ? 400 : 500, isValidation ? "request.field_invalid" : "internal.error", redactSecrets(m));
                     }
                 }