Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # apps/web/tests/markdown-images.e2e.ts # docs/cordis-catalog/services.md # docs/core-data-structures/session.i18n.yaml # docs/event-producer-consumer.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/compact/compact-basic/tests/compact-basic.spec.ts # packages/context/time-context/tests/invariant.spec.ts # packages/context/time-context/tests/time-context.spec.ts # packages/core/agent-loop/src/invariant.ts # packages/core/agent-loop/tests/contract-regressions.spec.ts # packages/core/agent-loop/tests/request-reconstruction.spec.ts # packages/core/agent/tests/agent.spec.ts # packages/core/session/README.i18n.yaml # packages/core/session/src/index.ts # packages/core/session/tests/derived-cache.spec.ts # packages/core/session/tests/request-header.spec.ts # packages/core/session/tests/session.spec.ts # packages/core/session/tests/surface.spec.ts # packages/fs/tool-str-replace-editor/tests/tools.spec.ts # packages/goal/goal/tests/goal.spec.ts # packages/plan/plan-mode/tests/plan-mode.spec.ts # packages/pty/pty-local/tests/index.spec.ts # packages/pty/pty-local/tests/local.spec.ts # packages/pty/pty/tests/service.spec.ts # packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts # packages/pty/tool-bash-persistent/tests/tools.spec.ts # packages/pty/tool-pty/tests/loader-composition.spec.ts # packages/pty/tool-pty/tests/tools.spec.ts # packages/session-title/session-title-all-messages-llm/tests/provider.spec.ts # packages/tasks/tasks-local/tests/tasks.spec.ts # packages/ui/user-approval/tests/approval.spec.ts
2026-08-05 13:53:35 +08:00
parent 02efe3ccea b5da33c9ac
commit b76543cc1c
75 changed files with 1087 additions and 358 deletions
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -103,17 +103,12 @@ declare module 'cordis' {
  }
 }

-/** Detach, validate, and freeze the creation metadata published by a session. */
-function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHeader {
-  const input: unknown = source === undefined
-    ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
-    : source
-  const snapshot = snapshotJsonValue(input)
-  if (snapshot === undefined) throw new Error('session header is not losslessly JSON-serializable')
-  if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+/** Validate and freeze one detached creation header in place. */
+function validateSessionHeader(id: SessionId, input: unknown): SessionHeader {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
    throw new Error('session header is not a plain JSON record')
  }
-  const record = snapshot as Record<string, unknown>
+  const record = input as Record<string, unknown>
  if (record.version !== SESSION_FORMAT_VERSION) {
    throw new Error(`session header version must be ${SESSION_FORMAT_VERSION}, got ${String(record.version)}`)
  }
@@ -148,30 +143,51 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe
  return deepFreeze(record as unknown as SessionHeader)
 }

+/** Detach, validate, and freeze the creation metadata published by a session. */
+function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHeader {
+  const input: unknown = source === undefined
+    ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
+    : source
+  const snapshot = snapshotJsonValue(input)
+  if (snapshot === undefined) throw new Error('session header is not losslessly JSON-serializable')
+  return validateSessionHeader(id, snapshot)
+}
+
+/**
+ * Validate an exclusively owned event and deeply freeze its identified message
+ * without copying the event. The caller transfers an object graph that no
+ * producer retains and that shares no mutable children with another event.
+ * Use {@link snapshotSessionEvent} when exclusive ownership is not guaranteed.
+ * @param event - exclusively owned event imported across a trusted boundary.
+ * @returns the same event object with a validated, deeply frozen message.
+ */
+export function adoptSessionEvent<T extends SessionEvent>(event: T): T {
+  assertMessageEventShape(
+    event,
+    `session event at seq ${event.seq}`,
+  )
+  switch (event.type) {
+    case 'user/message':
+      deepFreeze(event.data)
+      break
+    case 'assistant/message':
+    case 'tool/result':
+      deepFreeze(event.data.message)
+      break
+    default:
+      // SessionEventMap is merge-extensible; plugin-owned events carry no core message.
+      break
+  }
+  return event
+}
+
 /**
 * Detach one event while preserving deep immutability for its identified message.
 * @param event - event imported across a query or persistence boundary.
 * @returns a detached event snapshot with a validated, deeply frozen message.
 */
 export function snapshotSessionEvent<T extends SessionEvent>(event: T): T {
-  const snapshot = structuredClone(event)
-  assertMessageEventShape(
-    snapshot,
-    `session event at seq ${snapshot.seq}`,
-  )
-  switch (snapshot.type) {
-    case 'user/message':
-      deepFreeze(snapshot.data)
-      break
-    case 'assistant/message':
-    case 'tool/result':
-      deepFreeze(snapshot.data.message)
-      break
-    default:
-      // SessionEventMap is merge-extensible; plugin-owned events carry no core message.
-      break
-  }
-  return snapshot
+  return adoptSessionEvent(structuredClone(event))
 }

 /** Validate the fixed event envelope after one-pass JSON materialization. */
@@ -360,7 +376,8 @@ const attachments = new WeakMap<Session, SessionEntry>()
 /**
 * An event-sourced session: an append-only log of {@link SessionEvent}s.
 *
- * Plain class (not a Service) — create instances via `ctx.sessions.create()`.
+ * Plain class (not a Service) — create live instances via
+ * `ctx.sessions.create()` and detached instances via {@link create}.
 * Seeding with an existing event log replays/forks a session.
 * @typert object
 */
@@ -413,7 +430,19 @@ export class Session {
   */
  readonly firstLiveSeq: number

-  constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader) {
+  /**
+   * Create a detached session by validating and snapshotting borrowed seed
+   * events and storage metadata.
+   * @param id - session identity.
+   * @param seed - optional borrowed replay or fork events.
+   * @param header - optional borrowed storage metadata.
+   * @returns a detached session.
+   */
+  static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session {
+    return new Session(id, seed, header)
+  }
+
+  private constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader) {
    if (seed !== undefined) {
      // Validate the seed to the SAME invariants `append` enforces, so a
      // replay/fork (`ctx.sessions.create(id, { seed })`) cannot construct a
@@ -814,7 +843,7 @@ export class SessionStore extends Service {
      ...meta?.origin === undefined ? {} : { origin: meta.origin },
      ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
    }
-    return new Session(sessionId, seed, header)
+    return Session.create(sessionId, seed, header)
  }

  /**