@sema-agent/server 7.147.0 → 7.148.0

package/dist/http/routes/session-memory-sync.d.ts

@@ -28,7 +28,7 @@
  *  2. 多租户部署上没有验过的身份 ⇒ 401/403(`sendPrincipalRefusal`,会话面同一只)。
  *  3. 限流(本口会向远端发请求)。
  *  4. 会话 id 段解码不了 ⇒ 400 `request.path_malformed`。
- *  5. 一次头读:没有这只会话 / 不是你的 ⇒ 404 `not_found.session`(同码同串,无存在性 oracle;属主判据 = 会话面唯一谓词 `sessionOwnerOk`);
+ *  5. 一次头读:没有这只会话 / 不是你的 ⇒ 404 `not_found.session`(同码同串,无存在性 oracle;属主判据 = 会话面唯一谓词 `admitSessionRow`);
  *     同一次头读的叶子 = `sourceRevision`(与 `GET /v1/sessions/:id/head` 的 `leafId` 同一读法)。
  *  6. 体:闭集一键 `{ target }`,否则 400 `request.body_shape`;`target` 不是声明的同步身份 ⇒ 400 `request.field_invalid`(`field` / `reason`,不回显值)。
  *  7. 读集(上一节)。
@@ -50,7 +50,7 @@
  * 零模型工作(不 billable、不吃 drain 503);写的是调用方自己的记忆到它自己配置的中心 ⇒ 属主门兜底,不进无凭据改写门(会话自助抹除同判)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 import { type SettledLegMemoryObservation } from "../../plugins/store-contracts.js";
 /** 收割栅栏的句(本服务铸;码 `session_active` 是引擎报告闭集的成员)。 */
 export declare const SESSION_ACTIVE_SYNC_MESSAGE = "a run in this session is in flight, or the session moved on after the memory it reads was observed (a run was admitted or its transcript advanced) \u2014 wait for it to finish on its own, then sync again (do not cancel it to sync sooner)";

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

@@ -1,10 +1,8 @@
 import { memorySyncReportOf } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
-import {} from "../route-ctx.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { admitSessionById, enter } from "../owner-access.js";
+import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
-import { sessionOwnerCellOf } from "../../security.js";
 import { leafOfAdmittedHead } from "../../session-incarnation.js";
 import { declaredMemorySyncIdentityFlaw, memorySyncIdentityRule } from "../../memory-sync-identity.js";
 import { MEMORY_OBSERVATION_ABSENT_REASONS } from "../../plugins/store-contracts.js";
@@ -86,10 +84,9 @@ export async function handleSessionMemorySync(req, res, match, ctx) {
                 }
             }
             const { leg, runStore, sessionStorage } = fact;
-            if (deps.config.requirePrincipal && gatedPrincipal(req, deps.config) === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const entry = enter(req, res, deps, match.decl.id);
+            if (entry === undefined)
                 return;
-            }
             if (ctx.helpers.rateLimited(req, res))
                 return;
             const sessionId = ctx.helpers.safeDecode(match.params.sessionId);
@@ -98,13 +95,10 @@ export async function handleSessionMemorySync(req, res, match, ctx) {
                 return;
             }
             const readHead = () => sessionStorage.headOf(sessionId);
-            const head = await readHead();
-            if (head === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-                return;
-            }
-            if (!ctx.helpers.sessionOwnerOk(req, res, await sessionOwnerCellOf(sessionStorage, sessionId, head.owner)))
+            const admitted = await admitSessionById(entry, res, sessionStorage, sessionId);
+            if (admitted === undefined)
                 return;
+            const head = admitted.row;
             const sourceRevision = leafOfAdmittedHead(head);
             const body = await ctx.helpers.readJson(req);
             if (body === null || typeof body !== "object" || Array.isArray(body) || Object.keys(body).some((k) => k !== "target") || typeof body.target !== "string") {

package/dist/http/routes/session-sync.d.ts

@@ -10,6 +10,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionRulesRecord, type FileHistoryExport } from "@sema-agent/core";
 import { type ImportAnchor, type StagingHandle } from "../../session-sync-kernel.js";
+import type { DurableOwnerKey } from "../../owner-brands.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 import { type SessionRowPatch } from "../../session-row.js";
 export type PendingStaging = {
@@ -29,8 +30,9 @@ export type PendingStaging = {
      *  (a different tree under the same staging would otherwise commit while the parked snapshots/anchors
      *  still reference the DECLARED one). */
     declaredEntryIds: string[];
-    /** The principal that opened this staging — a different caller may not drive it (404, no oracle). */
-    openedBy: string | null;
+    /** The principal that opened this staging, kept as the handle's owner key (`null` = a fleet caller opened it) — a different caller may not drive it
+     *  (404, no oracle; compared through `owner-faces.ts` `sameKey` only). */
+    openedBy: DurableOwnerKey | null;
     /** The owner cell the gate judged when it opened this staging (head-read reading `headOf(id)?.owner`: `undefined` = no such session) — the commit lands only on
      *  this same cell (`StagedCommitOptions.expectedOwner`, `session-sync-kernel.ts`); `owner` above (the re-stamped importing principal) is derived from it for a fleet caller. */
     expectedOwner: string | null | undefined;

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

@@ -4,23 +4,24 @@ import { StringDecoder } from "node:string_decoder";
 import { FileHistoryUnreadableError, blobGetterOf, exportSessionManifest, exportedFileHistory, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, wipeSessionAttendants } from "../../session-sync.js";
 import * as facts from "../../capability-facts.js";
 import { classifySyncRelationshipByIds, createStagedLogFeed, MalformedImportEntryError, newStagingToken, readImportAnchors, SyncConflictError } from "../../session-sync-kernel.js";
-import { isUuidShape, legacyUnownedSessionOk, sessionOwnerCellOf } from "../../security.js";
+import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, logRequestError, msg } from "../send.js";
 import { StampedSessionArchiveError } from "../../session-error-wire.js";
 import { readSessionAgent } from "../../session-agent.js";
 import { buildDisplaySafeUrl } from "../../trace/redact.js";
 import { storeFaultClassOf } from "../../plugins/store-fault.js";
-import { fleetViewOf, gatedPrincipal, explicitOperatorOk, sendUnauthorized, sessionCallerOf } from "../principal-gate.js";
+import { enter, judgeSession, refuse } from "../owner-access.js";
+import { listFilterOf, ownerKeyOf, sameKey } from "../../owner-faces.js";
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
 import { SHA256_HEX_RE } from "../../digest-form.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { assertNever } 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 { probeSessionChildren, sessionTenantScope } from "../../session-children-retire.js";
 import { liveChildrenRefusal } from "./background.js";
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
@@ -65,11 +66,10 @@ export async function handleSessionSync(req, res, match, ctx) {
                 return;
             }
             const { backend, sessionStorage, historyStore } = sync;
-            const scope = fleetViewOf(req, deps, "write");
-            if (!scope.fleetWide && scope.gateOwner === null) {
-                sendUnauthorized(res, "identity");
+            const syncEntry = enter(req, res, deps, match.decl.id);
+            if (syncEntry === undefined)
                 return;
-            }
+            const scope = listFilterOf(syncEntry.face, syncEntry.caller);
             const sessionId = safeDecode(match.params.sessionId);
             if (sessionId === null || !isUuidShape(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
@@ -77,7 +77,7 @@ export async function handleSessionSync(req, res, match, ctx) {
             }
             const judgeSessionGate = async () => {
                 const face = sessionFaceOfHead(sessionId, await sessionStorage.headOf(sessionId));
-                const mayTouch = face !== undefined && (scope.fleetWide || face.owner === scope.gateOwner || legacyUnownedSessionOk(deps.config, sessionCallerOf(req, deps), await sessionOwnerCellOf(sessionStorage, sessionId, face.owner)));
+                const mayTouch = face !== undefined && (await judgeSession(syncEntry, sessionStorage, sessionId, face)) !== undefined;
                 return { face, mayPull: mayTouch, mayPush: face === undefined || mayTouch };
             };
             let gate;
@@ -91,17 +91,17 @@ export async function handleSessionSync(req, res, match, ctx) {
             }
             const gateFace = gate.face;
             const owner = gateFace === undefined ? undefined : gateFace.owner;
-            const sendSessionAbsent = () => sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            const sendSessionAbsent = (reason) => refuse(syncEntry, res, reason);
             const pullGateOk = () => {
                 if (!gate.mayPull) {
-                    sendSessionAbsent();
+                    sendSessionAbsent(gate.face === undefined ? "missing" : "not_visible");
                     return false;
                 }
                 return true;
             };
             const pushGateOk = () => {
                 if (!gate.mayPush) {
-                    sendSessionAbsent();
+                    sendSessionAbsent("not_visible");
                     return false;
                 }
                 return true;
@@ -125,7 +125,7 @@ export async function handleSessionSync(req, res, match, ctx) {
             };
             const liveChildrenOf = async (face) => face === undefined
                 ? []
-                : (await probeSessionChildren({ agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry }, sessionId, sessionChildrenScope(face.owner))).liveChildren;
+                : (await probeSessionChildren({ agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry }, sessionId, sessionTenantScope(face.owner))).liveChildren;
             const activityOf = async (face) => {
                 const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
                 if (activeTaskId)
@@ -168,7 +168,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     throw e;
                 }
                 if (out === null) {
-                    sendSessionAbsent();
+                    sendSessionAbsent("missing");
                     return;
                 }
                 sendJson(res, 200, { manifest: out.manifest });
@@ -197,7 +197,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     throw e;
                 }
                 if (it === null) {
-                    sendSessionAbsent();
+                    sendSessionAbsent("missing");
                     return;
                 }
                 res.writeHead(200, { "content-type": "application/x-ndjson", "transfer-encoding": "chunked" });
@@ -464,7 +464,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                             return;
                         }
                     }
-                    const opOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config);
+                    const opOk = syncEntry.caller.operator;
                     if (deps.sessionPolicyStore) {
                         try {
                             await replayPolicyRecords(deps.sessionPolicyStore, sessionId, policy, opOk);
@@ -509,14 +509,14 @@ export async function handleSessionSync(req, res, match, ctx) {
                     }
                 }
                 const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
-                const operatorOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config);
+                const operatorOk = syncEntry.caller.operator;
                 const token = newStagingToken();
                 const handle = sessionStorage.beginImportStaging(sessionId, token);
                 const stagingId = handle.stagingId;
                 importLeases.set(sessionId, { at: Date.now(), stagingId });
                 pendingStagings.set(stagingId, {
                     handle, realSessionId: sessionId, owner: importingPrincipal, ...(resolution ? { resolution } : {}), operatorOk,
-                    fileHistory, policy, anchors, row, declaredEntryIds: entryIds, openedBy: scope.gateOwner, expectedOwner: owner,
+                    fileHistory, policy, anchors, row, declaredEntryIds: entryIds, openedBy: ownerKeyOf(scope.gateOwner), expectedOwner: owner,
                 });
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
@@ -532,7 +532,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                if (!scope.fleetWide && pending.openedBy !== scope.gateOwner) {
+                if (!scope.fleetWide && !sameKey(scope.gateOwner, pending.openedBy)) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
@@ -617,7 +617,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 if (!mayPushAtCommit) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
-                    sendSessionAbsent();
+                    sendSessionAbsent("not_visible");
                     return;
                 }
                 if (activeAtCommit !== undefined) {
@@ -740,6 +740,7 @@ function sendPullUnreadable(req, res, logger, e) {
             sendError(res, 503, "state.file_history_unreadable", "this session's stored state cannot be read: the store does not match what this deployment requires (a table is missing or the database account lacks a privilege), so nothing was exported — retrying will not help until an operator repairs the store", { permanence: "terminal" });
             return true;
         case "corrupt":
+        case "defect":
         case "unclassified":
             return false;
         default: {

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

@@ -2,7 +2,7 @@
  * [ref] A9 域模块 —— 会话列表 / 发件链接列表。
  *
  * 路由:`GET /v1/sessions`(CC /resume picker,keyset 分页)、`GET /v1/sendfile-links`。
- * owner-scope 与 trace 列表同一权威模型(`fleetViewOf` 读档:service 凭据不报主体〔部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时不算〕/ 只读 trace 凭据 / dev-open = fleet-wide;带验过的主体 = 钉住那位主体)。本域零可变状态。
+ * owner-scope 与 trace 列表同一权威模型(列表面 `list.read` 读档(`listFilterOf`):service 凭据不报主体〔部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时不算〕/ 只读 trace 凭据 / dev-open = fleet-wide;带验过的主体 = 钉住那位主体)。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionListItem } from "../../security.js";
@@ -14,9 +14,9 @@ import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare function handleSessionsList(req: IncomingMessage, res: ServerResponse, match: RouteMatch<SessionsListRouteId>, ctx: RouteCtx): Promise<void>;
 /**
  * 会话列表行的 **wire 投影** —— `GET /v1/sessions` 的每一行与 `PATCH /v1/sessions/:id` 的 200 回执是**同一只**(店行 → wire 行只有这一处)。
- *  · 预览:店行读的是 run 行预览列的事实位(`""` = 有记录、剥完没有用户正文;NULL = 没记录);本面只说「有没有可显示的预览」⇒ 两者都是 `null`。
  *  · `tempo`:见上方 [ref] 注(由 `lastStatus` 经唯一一张表派生;omit-when-absent)。
- *  · 其余键(含 `title` / `pinned` / `rowTag` / `unreadable`)零投影透传 —— 店行是唯一铸点(`unreadable` 的码出自 `session-error-wire.ts` 的那一张表,
+ *  · 其余键(含 `objectivePreview` / `title` / `pinned` / `rowTag` / `unreadable`)零投影透传 —— 店行是唯一铸点(预览的规则在店层:最近一条预览列
+ *    按字符长度非空的 run 的那一列,没有 ⇒ `null`,店恒不交 `""`;`store-contracts.ts` 的 `SessionRunRollup`)(`unreadable` 的码出自 `session-error-wire.ts` 的那一张表,
  *    与全局兜底对同一只会话答的码同读;SQL 孪生的叶子是行上一列 ⇒ 恒缺席)。
  */
 export declare function projectSessionListRow(r: SessionListItem): SessionListItem & {

package/dist/http/routes/sessions-list.js

@@ -1,15 +1,17 @@
-import { isUuidV7, legacyUnownedAmnestyOpen } from "../../security.js";
+import { isUuidV7 } from "../../security.js";
 import { sendJson, sendError } from "../send.js";
-import { fleetViewOf, sendUnauthorized } from "../principal-gate.js";
+import { sendUnauthorized } from "../principal-gate.js";
+import { routeListFilter } from "../owner-access.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
 import { sessionTempoOfRunStatus } from "../../plugins/store-contracts.js";
 import { assertNever } from "../route-ctx.js";
+import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
 import * as facts from "../../capability-facts.js";
 export async function handleSessionsList(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "sessions-list": {
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner, includeUnowned } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -20,12 +22,11 @@ export async function handleSessionsList(req, res, match, ctx) {
                 return;
             }
             const lister = listing.lister;
-            const includeUnowned = !fleetWide && legacyUnownedAmnestyOpen(deps.config, gateOwner);
             await handleSessionList(res, lister, new URLSearchParams(match.search), gateOwner, includeUnowned);
             return;
         }
         case "sendfile-links": {
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -59,8 +60,8 @@ export async function handleSessionsList(req, res, match, ctx) {
                 }
                 else {
                     const s = scopeRaw.trim();
-                    if (s === "" || s.length > 190) {
-                        sendError(res, 400, "request.query_invalid", "scope must be a non-blank tenant principal of at most 190 characters (the sendfile_link.scope column width)");
+                    if (s === "" || Buffer.byteLength(s, "utf8") > PRINCIPAL_MAX_BYTES) {
+                        sendError(res, 400, "request.query_invalid", `scope must be a non-blank tenant principal of at most ${PRINCIPAL_MAX_BYTES} UTF-8 bytes (the principal length every identity column holds)`);
                         return;
                     }
                     scope = s;
@@ -128,8 +129,7 @@ async function handleSessionList(res, lister, query, forceOwner, includeUnowned
 }
 export function projectSessionListRow(r) {
     const tempo = sessionTempoOfRunStatus(r.lastStatus);
-    const row = r.objectivePreview === "" ? { ...r, objectivePreview: null } : r;
-    return tempo === undefined ? row : { ...row, tempo };
+    return tempo === undefined ? r : { ...r, tempo };
 }
 export const SESSIONS_LIST_ROUTES = [
     { id: "sessions-list", path: "/v1/sessions", methods: ["GET"] },