@sema-agent/core 7.55.0 → 7.57.0

package/dist/engine/llm/types.d.ts

@@ -5,6 +5,7 @@ import type { ProviderCondition, ProviderConditionSource } from "../../brain/pro
 import type { RequestRoute, RouteCarrierBag, RouteCredentialSource } from "../../brain/request-route.js";
 export type { RouteCredentialSource } from "../../brain/request-route.js";
 import type { ModelOutputInvalidCause } from "./tool-turns.js";
+import type { PromptTraitName, TraitCondition } from "../../prompt-assembly/catalog/schema.js";
 export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-chatgpt-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex";
 export type Api = KnownApi | (string & {});
 export type KnownImagesApi = "openrouter-images";
@@ -697,11 +698,24 @@ export interface Tool<TParameters extends TSchema = TSchema> {
     /** VENDORED EDIT (design/115 P0): canonical tool renames keep old model/SDK wire names as aliases. */
     aliases?: string[];
     description: string;
-    /** R2 双形轴 — classic-profile description variant (see ToolSpec.descriptionClassic). Swapped in
-     *  for `description` at mount time when the run's promptProfile is "classic"; absent = one form. */
-    descriptionClassic?: string;
+    /** The description's conditional variants (see ToolSpec.descriptionVariants): at mount, the first whose traits
+     *  condition holds over the run's traits replaces `description`; none holds ⇒ `description`. */
+    descriptionVariants?: readonly ToolDescriptionVariant[];
     parameters: TParameters;
 }
+/**
+ * One conditional variant of a tool's description — the tool card's variant table is these, first match wins, with
+ * `description` as the unconditional last entry. Chosen by the run's prompt traits through the same trait reading the
+ * prompt catalog's variants use; the variant chosen is reported in the tool's `cardId` (`<card>#<id>`).
+ */
+export interface ToolDescriptionVariant {
+    /** The variant's name in the tool's card id: non-empty, at most 64 characters of `[A-Za-z0-9._-]`, unique per tool. */
+    readonly id: string;
+    /** The trait condition (`allOf` / `noneOf`, trait names) under which this text replaces `description`. */
+    readonly traits: TraitCondition;
+    /** The description text (non-blank). */
+    readonly text: string;
+}
 export interface Context {
     systemPrompt?: string;
     /**
@@ -924,7 +938,9 @@ export interface Model<TApi extends Api = Api> {
     api: TApi;
     provider: Provider;
     baseUrl: string;
-    reasoning: boolean;
+    /** Declares reasoning (thinking keys): `true` / `false`, absent = not declared. Read only through `capabilityOf`
+     *  (`brain/model-capability.ts`), which also says what an undeclared capability means. */
+    reasoning?: boolean;
     /**
      * design/111 — this model's DEFAULT thinking level (per-model preset). The thinking-resolution chain is
      * `spec.thinking ?? role.thinking ?? model.defaultThinking` (prepare-task) — a caller/role still overrides, but
@@ -940,7 +956,8 @@ export interface Model<TApi extends Api = Api> {
      * Missing keys use provider defaults. null marks a level as unsupported.
      */
     thinkingLevelMap?: ThinkingLevelMap;
-    input: ("text" | "image")[];
+    /** Declares image input: a list with `"image"` = on, without = off, absent = not declared (same reader as `reasoning`). */
+    input?: ("text" | "image")[];
     cost?: {
         input: number;
         output: number;
@@ -996,13 +1013,13 @@ export interface Model<TApi extends Api = Api> {
     /** Extra request HEADERS merged into the provider call. Cannot override auth / content-type / version. */
     headers?: Record<string, string>;
     /**
-     * design/119 S3: model-declared system-prompt guidance sections, appended to
-     * the assembled system prompt. This is the declarative home for per-model behavioral patches (CC
-     * ships Fable-5 "mitigations" baked behind model-name checks; sema keeps the MECHANISM generic —
-     * any Model can carry guidance — and the CONTENT as preset data, zero model-name matching in core).
-     * Each entry is one section; joined with blank lines.
+     * The prompt traits this model has: the reference's capability names that gate prompt text (`PROMPT_TRAITS`), its
+     * bundle names (`PROMPT_TRAIT_BUNDLES`, expanded to their members), or a deployment's own `x-<namespace>-<name>`.
+     * The prompt catalog and every overlay's `when.traits` select on them; the engine never derives them from `id`. An
+     * EXACT set — nothing is added to what it lists (declare `lean_prompt` for the lean shape). Absent ⇒
+     * `["lean_prompt"]`. A name that is none of these refuses the task (`config.prompt_trait_unknown`).
      */
-    promptGuidance?: string[];
+    promptTraits?: readonly PromptTraitName[];
     /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
     compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : never;
 }

package/dist/engine/loop/agent-loop.d.ts

@@ -129,12 +129,9 @@ export interface TrailingToolBatchSettlement {
         aborted: boolean;
     }) => void;
 }
-/** The caller-facing seams of a prompt run beyond the prompts themselves: an optional trailing-batch
- *  settlement, and the moment the prompts enter the loop transcript, before their frames are emitted
- *  — delivery accounts precede the carrying messages' commits. */
+/** A prompt run's seam beyond its prompts (the trailing-batch settlement); a prompt is delivered at its `message_end`. */
 export interface RunAgentLoopSeams {
     settle?: TrailingToolBatchSettlement;
-    onPromptsDelivered?: () => void;
 }
 /** The last assistant message of `messages` when at least one of its tool calls has no tool result after it. */
 export declare function findUnansweredToolBatch(messages: readonly AgentMessage[]): AssistantMessage | undefined;
@@ -154,11 +151,33 @@ type ExecutedToolCallBatch = {
     messages: ToolResultMessage[];
     terminate: boolean;
 };
+/**
+ * ONE call through the loop's per-call pipeline — announced, prepared (the gate included), executed through the execution
+ * seat, finalized, closed. The sequential lane runs each call through it and adds the call's tool-result message; a host's
+ * own call (`AgentHarness.callTool`) runs it with no model message and adds nothing. The partitioned and streaming lanes run
+ * the same steps in two phases.
+ */
+export declare function runToolCall(currentContext: AgentContext, assistantMessage: AssistantMessage | undefined, toolCall: AgentToolCall, config: AgentLoopConfig, signal: AbortSignal | undefined, emit: AgentEventSink): Promise<{
+    finalized: FinalizedToolCallOutcome;
+    halt?: HaltRemainingDirective;
+}>;
+/**
+ * Partition rule: a call is batch-safe ONLY if its arguments
+ * VALIDATE against the tool's schema (CC `safeParse` — a malformed call never rides a parallel batch;
+ * it stays a singleton and surfaces its validation error at execution) AND the tool/hook opts in.
+ * The hook sees the validated+coerced args — same as CC handing `parsed.data` to `isConcurrencySafe`.
+ */
+export declare function isBatchSafeToolCall(tool: AgentTool | undefined, toolCall: AgentToolCall): boolean;
 /** An executed call's raw outcome, before (and, from {@link finalizeToolOutcome}, after) the post-execution half. */
 export type ExecutedToolCallOutcome = {
     result: AgentToolResult<unknown>;
     isError: boolean;
 };
+type FinalizedToolCallOutcome = {
+    toolCall: AgentToolCall;
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+};
 /**
  * THE reading a value gets on its way to becoming a call's arguments: the tool's own preparation (`prepareArguments` —
  * a default filled in, an alias folded), then the schema's coercions ({@link validateToolArguments}). The loop reads the

package/dist/engine/loop/agent-loop.js

@@ -3,8 +3,10 @@ import { truncateError } from "../../core/tool-errors.js";
 import { judgeToolNameMiss, mountedToolNames } from "../../core/tool-name-aliases.js";
 import { INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER, INTERRUPTED_BY_USER_MARKER, } from "../../core/session-reconcile.js";
 import { resolveAgentCoreStreamFn } from "./runtime-deps.js";
-import { isErrorLike, readMember, thrownMarksOf } from "../../core/thrown-value.js";
+import { isErrorLike, readMember, readOwnMembers, thrownMarksOf } from "../../core/thrown-value.js";
 import { egressThrownText, egressValue } from "../../core/untrusted-egress.js";
+import { remoteWords } from "../../core/protocol-http-auth.js";
+import { types } from "node:util";
 import { admitToolResultMedia } from "../../core/image-admission.js";
 function appendTextDeltaToAssistantMessage(message, contentIndex, delta) {
     const content = [...message.content];
@@ -75,7 +77,6 @@ export async function runAgentLoop(prompts, context, config, emit, signal, strea
         state.hasMoreToolCalls = true;
     state.context.messages.push(...delivered);
     state.newMessages.push(...delivered);
-    seams?.onPromptsDelivered?.();
     for (const prompt of delivered) {
         await emit({ type: "message_start", message: prompt });
         await emit({ type: "message_end", message: prompt });
@@ -756,7 +757,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
                 break;
             case "done":
             case "error": {
-                const finalMessage = await response.result();
+                const finalMessage = receivedFinal(await response.result());
                 const cutAtSettle = signal?.aborted === true;
                 if (executor && (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
                     mergeBackAdmittedCalls(finalMessage, executor);
@@ -775,7 +776,7 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
             }
         }
     }
-    const finalMessage = await response.result();
+    const finalMessage = receivedFinal(await response.result());
     const cutAtSettle = signal?.aborted === true;
     if (executor && (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
         mergeBackAdmittedCalls(finalMessage, executor);
@@ -802,27 +803,7 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
     const messages = [];
     for (let i = 0; i < toolCalls.length; i++) {
         const toolCall = toolCalls[i];
-        await emit({
-            type: "tool_execution_start",
-            toolCallId: toolCall.id,
-            toolName: toolCall.name,
-            args: toolCall.arguments,
-        });
-        const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
-        let finalized;
-        let halt;
-        if (preparation.kind === "immediate") {
-            finalized = {
-                toolCall,
-                result: preparation.result,
-                isError: preparation.isError,
-            };
-            halt = preparation.halt;
-        }
-        else {
-            finalized = await executePreparedWithDisclosure(currentContext, assistantMessage, preparation, config, signal, emit);
-        }
-        await emitToolExecutionEnd(finalized, emit);
+        const { finalized, halt } = await runToolCall(currentContext, assistantMessage, toolCall, config, signal, emit);
         const toolResultMessage = createToolResultMessage(finalized);
         await emitToolResultMessage(toolResultMessage, emit);
         finalizedCalls.push(finalized);
@@ -846,6 +827,15 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         terminate: shouldTerminateToolBatch(finalizedCalls),
     };
 }
+export async function runToolCall(currentContext, assistantMessage, toolCall, config, signal, emit) {
+    await emit({ type: "tool_execution_start", toolCallId: toolCall.id, toolName: toolCall.name, args: toolCall.arguments });
+    const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+    const finalized = preparation.kind === "immediate"
+        ? { toolCall, result: preparation.result, isError: preparation.isError }
+        : await executePreparedWithDisclosure(currentContext, assistantMessage, preparation, config, signal, emit);
+    await emitToolExecutionEnd(finalized, emit);
+    return { finalized, ...(preparation.kind === "immediate" && preparation.halt !== undefined ? { halt: preparation.halt } : {}) };
+}
 async function settleHaltedToolCall(toolCall, halt, emit) {
     await emit({
         type: "tool_execution_start",
@@ -887,7 +877,7 @@ function isCallConcurrencySafe(tool, args) {
         return false;
     }
 }
-function isBatchSafeToolCall(tool, toolCall) {
+export function isBatchSafeToolCall(tool, toolCall) {
     if (!tool)
         return false;
     let args;
@@ -1108,7 +1098,7 @@ class StreamToolExecutor {
                 return;
             }
             entry.prepared = preparation;
-            entry.executed = await executePreparedToolCall(preparation, this.signal, this.emit, this.config.abortResultDetails, (error) => this.retainCancellation(error));
+            entry.executed = await executePreparedToolCall(preparation, this.signal, this.emit, this.config.executeTool, this.config.abortResultDetails, (error) => this.retainCancellation(error));
         }
         catch (error) {
             if (isAbortSemanticsError(error))
@@ -1190,6 +1180,27 @@ async function harvestExecutorOnErrorFinal(executor, state, finalMessage, signal
     }
     return results;
 }
+function receivedFinal(message) {
+    const words = readMember(message, "errorMessage");
+    const minted = typeof words === "string" ? remoteWords(words, []) : undefined;
+    if (minted === words && readsTheSame(message, "errorMessage", words))
+        return message;
+    const copy = {};
+    for (const [key, value] of Object.entries(readOwnMembers(message) ?? {}))
+        if (key !== "errorMessage")
+            Object.defineProperty(copy, key, { value, enumerable: true, writable: true, configurable: true });
+    if (minted !== undefined)
+        copy.errorMessage = minted;
+    return copy;
+}
+function readsTheSame(o, key, value) {
+    if (types.isProxy(o))
+        return false;
+    const d = Reflect.getOwnPropertyDescriptor(o, key);
+    if (d === undefined)
+        return value === undefined && !(key in o);
+    return "value" in d && d.value === value;
+}
 function mergeBackAdmittedCalls(finalMessage, executor) {
     const admitted = executor.admittedToolCalls();
     if (admitted.length === 0)
@@ -1395,7 +1406,7 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
         };
     }
 }
-async function executePreparedToolCall(prepared, signal, emit, abortResultDetails, onLateCancellation) {
+async function executePreparedToolCall(prepared, signal, emit, executeTool, abortResultDetails, onLateCancellation) {
     const updateEvents = [];
     let acceptingUpdates = true;
     if (signal?.aborted) {
@@ -1404,7 +1415,7 @@ async function executePreparedToolCall(prepared, signal, emit, abortResultDetail
     const work = (async () => {
         let outcome;
         try {
-            const result = await prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
+            const body = () => prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
                 if (!acceptingUpdates) {
                     return;
                 }
@@ -1427,6 +1438,7 @@ async function executePreparedToolCall(prepared, signal, emit, abortResultDetail
                 });
                 updateEvents.push(delivery);
             });
+            const result = executeTool !== undefined ? await executeTool({ toolCall: prepared.toolCall, tool: prepared.tool, args: prepared.args }, body, signal) : await body();
             outcome = { result, isError: result.isError === true };
         }
         catch (error) {
@@ -1507,7 +1519,7 @@ function raiseFatalCancellation(executor) {
 async function executePreparedWithDisclosure(currentContext, assistantMessage, prepared, config, signal, emit) {
     let executed;
     try {
-        executed = await executePreparedToolCall(prepared, signal, emit, config.abortResultDetails);
+        executed = await executePreparedToolCall(prepared, signal, emit, config.executeTool, config.abortResultDetails);
     }
     catch (error) {
         if (isAbortSemanticsError(error))

package/dist/engine/loop/types.d.ts

@@ -127,9 +127,9 @@ export interface AfterToolCallResult {
 }
 /** Context passed to `beforeToolCall`. */
 export interface BeforeToolCallContext {
-    /** The assistant message that requested the tool call. */
-    assistantMessage: AssistantMessage;
-    /** The raw tool call block from `assistantMessage.content`. */
+    /** The assistant message that requested the tool call — absent for a host's own call (an extension's `$.tool.call`), which no model message carried. */
+    assistantMessage?: AssistantMessage;
+    /** The raw tool call block (from `assistantMessage.content` when a model message carried it). */
     toolCall: AgentToolCall;
     /** Validated tool arguments for the target tool schema. */
     args: unknown;
@@ -142,9 +142,9 @@ export interface BeforeToolCallContext {
 }
 /** Context passed to `afterToolCall`. */
 export interface AfterToolCallContext {
-    /** The assistant message that requested the tool call. */
-    assistantMessage: AssistantMessage;
-    /** The raw tool call block from `assistantMessage.content`. */
+    /** The assistant message that requested the tool call — absent for a host's own call (an extension's `$.tool.call`), which no model message carried. */
+    assistantMessage?: AssistantMessage;
+    /** The raw tool call block (from `assistantMessage.content` when a model message carried it). */
     toolCall: AgentToolCall;
     /** Validated tool arguments for the target tool schema. */
     args: unknown;
@@ -564,6 +564,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * signal re-check, which has always minted its abort result with no details.
      */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /**
+     * The host's station around every tool execution, between the gate's allow and the body: `run` runs the body as the loop
+     * would (at most once), and what the station returns is the result the loop finalizes — it may answer without running it,
+     * and honors `signal`. Absent ⇒ the loop runs the body itself.
+     */
+    executeTool?: (call: {
+        readonly toolCall: AgentToolCall;
+        readonly tool: AgentTool;
+        readonly args: unknown;
+    }, run: () => Promise<AgentToolResult<unknown>>, signal: AbortSignal | undefined) => Promise<AgentToolResult<unknown>>;
     /**
      * Fault seat for a THROWING {@link AgentTool.validateInput}: the loop reads the throw as "no
      * verdict" (the call proceeds to the gate as if the tool had no validator) and reports the fault

package/dist/engine/session/memory-repo.d.ts

@@ -1,12 +1,19 @@
-import { type Session, type SessionCreateOptions, type SessionForkOptions, type SessionHead, type SessionMetadata, type SessionRepo, type SessionTreeEntry } from "../harness/types.js";
+import { type Session, type SessionCreateOptions, type SessionForkOptions, type SessionHead, type SessionMetadata, type SessionRepo, type SessionRow, type SessionTreeEntry } from "../harness/types.js";
 export declare class InMemorySessionRepo implements SessionRepo<SessionMetadata, SessionCreateOptions> {
     private sessions;
+    /** Each row's last touch (epoch ms). */
+    private touched;
     create(options?: SessionCreateOptions): Promise<Session>;
     open(metadata: SessionMetadata): Promise<Session>;
     /** The row's head off the one session object that IS the row: every cell comes from that object, so a delete and re-create of the
      *  id while this reads cannot mix two generations. */
     headOf(sessionId: string): Promise<SessionHead | undefined>;
-    list(): Promise<SessionMetadata[]>;
+    /** Every row, with its last {@link touch} as its activity time where it has one. This repo hands its sessions' storages out and never
+     *  sees their writes (an entry's own `timestamp` is the writer's data, not the time of the write), so a row never touched carries none
+     *  and a reader takes its `createdAt`. */
+    list(): Promise<SessionRow[]>;
+    /** Record activity on the row now (a missing row: nothing to record). The time lives and dies with the row: `delete` drops it. */
+    touch(sessionId: string): Promise<void>;
     delete(metadata: SessionMetadata): Promise<void>;
     fork(sourceMetadata: SessionMetadata, options: SessionForkOptions & SessionCreateOptions): Promise<Session>;
     /** 2c session-sync: the FULL log for export. InMemory holds everything (no F3 floor), so

package/dist/engine/session/memory-repo.js

@@ -4,6 +4,7 @@ import { InMemorySessionStorage } from "./memory-storage.js";
 import { assertForkTarget, createSessionId, createTimestamp, forkRowCells, frozenRow, getEntriesToFork, headOfSession, importRowCells, incarnationCell, ownerCell, toSession } from "./repo-utils.js";
 export class InMemorySessionRepo {
     sessions = new Map();
+    touched = new Map();
     async create(options = {}) {
         if (options.id !== undefined) {
             const existing = this.sessions.get(options.id);
@@ -33,10 +34,19 @@ export class InMemorySessionRepo {
         return row === undefined ? undefined : headOfSession(row);
     }
     async list() {
-        return Promise.all([...this.sessions.values()].map((session) => session.getMetadata()));
+        return Promise.all([...this.sessions.entries()].map(async ([id, session]) => {
+            const meta = await session.getMetadata();
+            const touched = this.touched.get(id);
+            return touched !== undefined ? { ...meta, lastActiveAt: touched } : meta;
+        }));
+    }
+    async touch(sessionId) {
+        if (this.sessions.has(sessionId))
+            this.touched.set(sessionId, Date.now());
     }
     async delete(metadata) {
         this.sessions.delete(metadata.id);
+        this.touched.delete(metadata.id);
     }
     async fork(sourceMetadata, options) {
         assertForkTarget(sourceMetadata.id, options.id);

package/dist/engine/session/repo-utils.d.ts

@@ -22,16 +22,17 @@ export declare function compareOccupants(before: {
 } | undefined): "same" | "different" | "unknown";
 /** The {@link SessionHead} a session object shows: its metadata's owner and occupant and its storage's leaf, off that one object. */
 export declare function headOfSession(session: Session): Promise<SessionHead>;
-/** The {@link SessionMetadata.owner} cell the write creating a row records: `owner` (a string, or `null`; `undefined` = none named =
- *  `null`). An `owner` that is neither is refused before the write, so no row ever holds an owner cell that reads as neither. */
+/** The {@link SessionMetadata.owner} cell the write creating a row records: `owner` (a principal name, or `null`; `undefined` = none
+ *  named = `null`). An `owner` that is neither is refused before the write, so no row ever holds an owner cell that reads as neither
+ *  — a blank string included: it names nobody, so it is no owner and not anonymous either. */
 export declare function ownerCell(owner: unknown): Pick<SessionMetadata, "owner">;
 /** The metadata an import lays down. An import replaces the log, never the row: an existing row keeps its metadata whole (its creation
  *  time, lineage, placement, occupant and owner were recorded by the write that created it); an absent id is a new row recording `owner`
  *  and a fresh occupant. `owner` is judged either way. */
 export declare function importRowCells(sessionId: string, owner: unknown, existing: SessionMetadata | undefined, createdAt: string): SessionMetadata;
-/** The one decoding of a stored owner cell: a string is the owner; absence (`undefined`, `null`) is anonymous. A cell that is there
- *  but is neither cannot be read as anyone's, and reading it as anonymous would admit every principal — the row is refused as
- *  `corrupt_session` instead (a read fault, never an answer). */
+/** The one decoding of a stored owner cell: a principal name is the owner; absence (`undefined`, `null`) is anonymous. A cell that is
+ *  there but is neither (a blank string included) cannot be read as anyone's, and reading it as anonymous would admit every
+ *  principal — the row is refused as `corrupt_session` instead (a read fault, never an answer). */
 export declare function readOwnerCell(raw: unknown, sessionId: string): string | null;
 /** A fork lands on a row OTHER than its source: onto its own id it would mint a new occupant over the source's transcript and erase the lineage that carries the source's records. */
 export declare function assertForkTarget(sourceId: string, targetId: string | undefined): void;

package/dist/engine/session/repo-utils.js

@@ -1,6 +1,7 @@
 import { SessionError, } from "../harness/types.js";
 import { StoredSession } from "./session.js";
 import { uuidv7 } from "./uuid.js";
+import { principalNameFault, principalNameOf } from "../../core/principal-name.js";
 import { randomUUID } from "node:crypto";
 export function createSessionId() {
     return uuidv7();
@@ -35,21 +36,28 @@ export async function headOfSession(session) {
     const meta = await session.getMetadata();
     return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: await session.getStorage().getLeafId() };
 }
+function notAnOwnerShape(raw) {
+    return typeof raw === "string" ? principalNameFault(raw) : nonStringShape(raw);
+}
 export function ownerCell(owner) {
-    if (owner !== undefined && owner !== null && typeof owner !== "string")
-        throw new TypeError(`session owner must be a string (owned) or null (anonymous), got ${nonStringShape(owner)}`);
-    return { owner: owner ?? null };
+    if (owner === undefined || owner === null)
+        return { owner: null };
+    const name = principalNameOf(owner);
+    if (name === undefined)
+        throw new TypeError(`session owner must be a principal name (a string with a visible character, no control or separator character, and no format character but a joiner) or null (anonymous), got ${notAnOwnerShape(owner)}`);
+    return { owner: name };
 }
 export function importRowCells(sessionId, owner, existing, createdAt) {
     const named = ownerCell(owner);
     return existing ?? { id: sessionId, createdAt, ...incarnationCell(undefined), ...named };
 }
 export function readOwnerCell(raw, sessionId) {
-    if (typeof raw === "string")
-        return raw;
     if (raw === undefined || raw === null)
         return null;
-    throw new SessionError("corrupt_session", `session ${sessionId}'s owner cell holds ${nonStringShape(raw)} — neither an owner nor anonymous; refusing to read the row`);
+    const name = principalNameOf(raw);
+    if (name !== undefined)
+        return name;
+    throw new SessionError("corrupt_session", `session ${sessionId}'s owner cell holds ${notAnOwnerShape(raw)} — neither an owner nor anonymous; refusing to read the row`);
 }
 export function assertForkTarget(sourceId, targetId) {
     if (targetId === sourceId)