@opengeni/contracts 0.44.1 → 1.0.0

package/src/sandbox-file-artifacts.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+import { RetainedArtifactReferenceSchema } from "./retained-output";
+
+/**
+ * Channel-A currently returns one bounded binary-safe read. Keep publication
+ * below that ceiling so an extra sentinel byte can distinguish an exact file
+ * from a truncated prefix.
+ */
+export const SANDBOX_FILE_ARTIFACT_MAX_BYTES = 25 * 1024 * 1024 - 1;
+
+export const PublishSandboxFileArtifactRequest = z
+  .object({
+    path: z.string().min(1).max(4_096),
+  })
+  .strict();
+export type PublishSandboxFileArtifactRequest = z.infer<typeof PublishSandboxFileArtifactRequest>;
+
+/**
+ * Closed model/UI receipt for one exact sandbox-file publication. Storage
+ * locators and signed URLs never cross this boundary.
+ */
+export const SandboxFileArtifactReceipt = z
+  .object({
+    type: z.literal("sandbox_file"),
+    sandboxPath: z.string().min(1).max(4_096),
+    filename: z.string().min(1).max(1_024),
+    artifact: RetainedArtifactReferenceSchema,
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const pathSegments = value.sandboxPath.split("/");
+    // This is a receipt, not read authority. The publisher confines the path
+    // against its resolved provider root; receipts preserve that native path.
+    const unc = value.sandboxPath.startsWith("//");
+    const absolute = unc
+      ? /^\/\/[^/]+\/[^/]+\/.+/u.test(value.sandboxPath) && !value.sandboxPath.startsWith("//?/")
+      : value.sandboxPath.startsWith("/") || /^[A-Z]:\//u.test(value.sandboxPath);
+    if (
+      !absolute ||
+      /[\\\u0000-\u001f\u007f]/u.test(value.sandboxPath) ||
+      pathSegments.some(
+        (segment, index) =>
+          index >= (unc ? 2 : 1) && (!segment || segment === "." || segment === ".."),
+      ) ||
+      pathSegments.at(-1) !== value.filename
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["sandboxPath"],
+        message:
+          "sandbox path must canonically identify the published filename at an absolute host path",
+      });
+    }
+    if (value.artifact.kind !== "file" || value.artifact.retention.policy !== "workspace_file") {
+      context.addIssue({
+        code: "custom",
+        path: ["artifact"],
+        message: "sandbox files require a permanent workspace-file artifact",
+      });
+    }
+    if (
+      value.artifact.originalBytes < 1 ||
+      value.artifact.originalBytes > SANDBOX_FILE_ARTIFACT_MAX_BYTES
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["artifact", "originalBytes"],
+        message: "sandbox file size is outside the publication byte limit",
+      });
+    }
+  });
+export type SandboxFileArtifactReceipt = z.infer<typeof SandboxFileArtifactReceipt>;

package/src/sandbox-provider-command.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+const ModalOutputCursor = z
+  .object({
+    batchIndex: z.number().int().nonnegative().safe(),
+    utf8Remainder: z
+      .string()
+      .max(8)
+      .regex(/^[A-Za-z0-9+/]*={0,2}$/u),
+    exitCode: z.number().int().nullable(),
+  })
+  .strict();
+
+/** Provider-owned execution identity and acknowledged output cursors. These
+ * values are retained by the control plane, never recovered from sandbox files. */
+export const ModalLegacyProviderCommand = z
+  .object({
+    kind: z.literal("modal-control-v1"),
+    sandboxId: z.string().min(1).max(200),
+    taskId: z.string().min(1).max(200),
+    execId: z.string().min(1).max(200),
+    pty: z.boolean().optional(),
+    streams: z.object({ stdout: ModalOutputCursor, stderr: ModalOutputCursor }).strict(),
+  })
+  .strict();
+export type ModalLegacyProviderCommand = z.infer<typeof ModalLegacyProviderCommand>;
+
+const ModalByteCursor = z
+  .object({
+    byteOffset: z.number().int().nonnegative().safe(),
+    utf8Remainder: z
+      .string()
+      .max(8)
+      .regex(/^[A-Za-z0-9+/]*={0,2}$/u),
+    eof: z.boolean(),
+    exitCode: z.number().int().nullable(),
+  })
+  .strict()
+  .refine((cursor) => cursor.exitCode === null || cursor.eof, {
+    message: "A terminal output cursor must have reached EOF",
+  });
+
+export const CommandSupervisionDescriptor = z
+  .object({
+    protocol: z.literal("native-subreaper-v1"),
+    invocationId: z.string().uuid(),
+    nonce: z.string().regex(/^[a-f0-9]{64}$/u),
+    controlPath: z.string().regex(/^\/tmp\/opengeni-supervision\/[a-f0-9-]{36}\.sock$/u),
+  })
+  .strict();
+export type CommandSupervisionDescriptor = z.infer<typeof CommandSupervisionDescriptor>;
+
+export const CommandSupervisionReceipt = z
+  .object({
+    protocol: z.literal("native-subreaper-v1"),
+    invocationId: z.string().uuid(),
+    receiptId: z.string().uuid(),
+    leaderExitCode: z.number().int(),
+  })
+  .strict();
+export type CommandSupervisionReceipt = z.infer<typeof CommandSupervisionReceipt>;
+
+export const ModalRouterProviderCommand = z
+  .object({
+    kind: z.literal("modal-router-v1"),
+    sandboxId: z.string().min(1).max(200),
+    taskId: z.string().min(1).max(200),
+    execId: z.string().uuid(),
+    pty: z.boolean().optional(),
+    supervision: CommandSupervisionDescriptor.optional(),
+    streams: z.object({ stdout: ModalByteCursor, stderr: ModalByteCursor }).strict(),
+  })
+  .strict();
+export type ModalRouterProviderCommand = z.infer<typeof ModalRouterProviderCommand>;
+
+/** Legacy locators are read-only compatibility for already launched commands;
+ * new starts use authenticated task-router byte offsets, never batch indices. */
+export const SandboxProviderCommand = z.discriminatedUnion("kind", [
+  ModalLegacyProviderCommand,
+  ModalRouterProviderCommand,
+]);
+export type SandboxProviderCommand = z.infer<typeof SandboxProviderCommand>;

package/src/sandbox-recovery.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+
+/** Public, content-free selection. Never include native provider bindings. */
+export const SandboxRecoverySelection = z
+  .object({
+    version: z.literal(1),
+    sessionId: z.string().uuid(),
+    sandboxGroupId: z.string().uuid(),
+    leaseId: z.string().uuid(),
+    routeEpoch: z.number().int().nonnegative(),
+    authorityEpoch: z.number().int().positive(),
+    leaseEpoch: z.number().int().nonnegative(),
+    workspaceGeneration: z.number().int().nonnegative(),
+    archiveGeneration: z.number().int().nonnegative(),
+    artifactId: z.string().uuid(),
+    revision: z.string().min(1).max(512),
+    capturedAt: z.string().datetime(),
+  })
+  .strict();
+export type SandboxRecoverySelection = z.infer<typeof SandboxRecoverySelection>;
+
+export const SandboxRecoveryProjection = z
+  .object({
+    version: z.literal(1),
+    status: z.enum([
+      "unsupported",
+      "blocked",
+      "eligible",
+      "consent_accepted",
+      "restoring",
+      "restored",
+    ]),
+    reason: z.string().max(128).nullable(),
+    checkpoint: SandboxRecoverySelection.nullable(),
+    operationId: z.string().uuid().nullable(),
+    /** Retry may elect a system-selected verified checkpoint; no consent POST. */
+    automaticAvailable: z.boolean().optional(),
+    /** What an automatic Retry will do: restore `checkpoint`, or continue on a
+     * new empty workspace because no usable checkpoint survived the loss. */
+    automaticLane: z.enum(["checkpoint", "fresh_workspace"]).optional(),
+    /** For a timed recovery wait: the earliest time a Retry or a new message
+     * can let OpenGeni decide again. Nothing proceeds by itself before then. */
+    availableAt: z.string().datetime().optional(),
+  })
+  .strict();
+export type SandboxRecoveryProjection = z.infer<typeof SandboxRecoveryProjection>;
+
+/** Why a definitively lost managed sandbox continues on an empty workspace. */
+export const SandboxFreshWorkspaceReason = z.enum([
+  "archive_unavailable",
+  "archive_unverified",
+  "checkpoint_unrestorable",
+  "checkpoint_restore_failed",
+]);
+export type SandboxFreshWorkspaceReason = z.infer<typeof SandboxFreshWorkspaceReason>;
+
+/** Durable, content-free fresh-workspace decision for one group member. */
+export const SandboxFreshWorkspaceRecovery = z
+  .object({
+    version: z.literal(1),
+    sessionId: z.string().uuid(),
+    sandboxGroupId: z.string().uuid(),
+    leaseId: z.string().uuid(),
+    leaseEpoch: z.number().int().nonnegative(),
+    workspaceGeneration: z.number().int().nonnegative(),
+    archiveGeneration: z.number().int().nonnegative().nullable(),
+    lostAt: z.string().datetime(),
+    reason: SandboxFreshWorkspaceReason,
+  })
+  .strict();
+export type SandboxFreshWorkspaceRecovery = z.infer<typeof SandboxFreshWorkspaceRecovery>;
+
+export const SandboxRecoveryRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    acceptHistoricalCheckpoint: z.literal(true),
+    selection: SandboxRecoverySelection,
+  })
+  .strict();
+export type SandboxRecoveryRequest = z.infer<typeof SandboxRecoveryRequest>;
+
+export const SandboxRecoveryResponse = z
+  .object({
+    outcome: z.enum(["accepted", "replayed"]),
+    operationId: z.string().uuid(),
+    recovery: SandboxRecoveryProjection,
+  })
+  .strict();
+export type SandboxRecoveryResponse = z.infer<typeof SandboxRecoveryResponse>;
+
+/** Re-injected from durable receipts on every attempt, not lossy transcript state. */
+export function sandboxRecoveryDiscontinuity(selection: SandboxRecoverySelection): string {
+  return `Filesystem discontinuity: the human explicitly consented to restoring this session's workspace from the checkpoint captured at ${selection.capturedAt} (archive generation ${selection.archiveGeneration}, pre-recovery workspace generation ${selection.workspaceGeneration}). Newer filesystem changes are unavailable. The generation gap is not a count of lost files or edits. Conversation and tool receipts remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the current filesystem before relying on previous work. Never automatically replay prior commands or operations with unknown outcomes to rebuild missing files. Consent alone is not proof that restoration succeeded.`;
+}
+
+/** Stable tail instructions, sourced from a durable system recovery receipt.
+ * `shared` names the sandbox this session shares with other sessions; every
+ * member of that group receives its own receipt for the same selection. */
+export function automaticSandboxRecoveryDiscontinuity(
+  selection: SandboxRecoverySelection,
+  scope: "session" | "shared" = "session",
+): string {
+  const subject =
+    scope === "shared"
+      ? "the latest verified checkpoint of the sandbox this session shares with other sessions"
+      : "this session's latest verified checkpoint";
+  return `Filesystem discontinuity: after the managed sandbox was lost, OpenGeni selected ${subject}, captured at ${selection.capturedAt} (archive generation ${selection.archiveGeneration}, pre-recovery workspace generation ${selection.workspaceGeneration}). Newer filesystem changes may be unavailable; the generation gap is not a count of lost files or edits. Conversation and tool receipts remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the restored filesystem before relying on previous work. Never automatically replay prior commands or operations with unknown outcomes. Checkpoint selection alone is not proof that restoration succeeded.`;
+}
+
+/** Stable tail instructions for continuing on a new empty workspace. The text
+ * is true on every later turn too: it names the loss, not the current tree. */
+export function freshWorkspaceSandboxRecoveryDiscontinuity(
+  recovery: SandboxFreshWorkspaceRecovery,
+): string {
+  return `Filesystem discontinuity: the previous managed sandbox was lost at ${recovery.lostAt} and there is no checkpoint OpenGeni can restore automatically, so OpenGeni continued this session on a new empty workspace. Files, repository clones, installed packages and running processes from before that time are not available in this workspace; do not assume they exist. Anything now in the workspace was created after that loss. Conversation and tool receipts from before it remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the current filesystem before relying on previous work, and recreate what you need deliberately. Never automatically replay prior commands or operations with unknown outcomes.`;
+}

package/src/sandbox-snapshots.ts

@@ -52,6 +52,148 @@ export type NativeSnapshotDescriptor = {
 
 export type WorkspaceArchiveDescriptor = TarWorkspaceArchiveDescriptor | NativeSnapshotDescriptor;
 
+export const WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA = "sandbox_archive_object_v1" as const;
+
+/** Compact object-storage locator for portable tar bytes. The SHA-256/size in
+ * `workspaceArchiveMeta` remain the verification authority. */
+export type WorkspaceArchiveObjectRef = {
+  schema: typeof WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA;
+  key: string;
+  sha256: string;
+  bytes: number;
+  backend: string;
+};
+
+// Keep legacy scope/key spelling readable. New physical upload identities must
+// be a complete RFC UUID (including version and variant), never arbitrary text.
+const UPLOAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const OBJECT_KEY =
+  /^sandbox-archives\/v1\/([0-9a-f-]{36})\/([0-9a-f-]{36})\/([0-9a-f-]{36})\/(wa1:[0-9]{13}:[0-9a-f]{64})(?:\.([0-9a-f-]+))?\.tar$/i;
+
+export type WorkspaceArchiveObjectKey = {
+  accountId: string;
+  workspaceId: string;
+  sandboxGroupId: string;
+  revision: string;
+  uploadId: string | null;
+};
+
+export function parseWorkspaceArchiveObjectKey(value: unknown): WorkspaceArchiveObjectKey | null {
+  if (typeof value !== "string") return null;
+  const match = OBJECT_KEY.exec(value);
+  // JS $ may match before a final newline; a locator must match in full.
+  if (!match || match[0] !== value || (match[5] !== undefined && !UPLOAD_ID.test(match[5]))) {
+    return null;
+  }
+  return {
+    accountId: match[1]!,
+    workspaceId: match[2]!,
+    sandboxGroupId: match[3]!,
+    revision: match[4]!,
+    uploadId: match[5] ?? null,
+  };
+}
+
+export function parseWorkspaceArchiveObjectRef(value: unknown): WorkspaceArchiveObjectRef | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const candidate = value as Partial<WorkspaceArchiveObjectRef>;
+  if (
+    candidate.schema !== WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA ||
+    typeof candidate.key !== "string" ||
+    !parseWorkspaceArchiveObjectKey(candidate.key) ||
+    typeof candidate.sha256 !== "string" ||
+    !SHA256.test(candidate.sha256) ||
+    !nonnegativeInteger(candidate.bytes) ||
+    candidate.bytes <= 0 ||
+    typeof candidate.backend !== "string" ||
+    candidate.backend.length === 0 ||
+    candidate.backend.length > 64
+  ) {
+    return null;
+  }
+  return {
+    schema: WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA,
+    key: candidate.key,
+    sha256: candidate.sha256,
+    bytes: candidate.bytes,
+    backend: candidate.backend,
+  };
+}
+
+export function workspaceArchiveObjectKey(input: {
+  accountId: string;
+  workspaceId: string;
+  sandboxGroupId: string;
+  revision: string;
+  /** New upload invocations supply a fresh randomUUID; omission is legacy-only. */
+  uploadId?: string;
+}): string {
+  if (
+    input.uploadId !== undefined &&
+    (!UPLOAD_ID.test(input.uploadId) || input.uploadId.length !== 36)
+  ) {
+    throw new Error("Invalid workspace archive upload UUID");
+  }
+  return `sandbox-archives/v1/${input.accountId}/${input.workspaceId}/${input.sandboxGroupId}/${input.revision}${input.uploadId === undefined ? "" : `.${input.uploadId}`}.tar`;
+}
+
+/** Bind a stored locator to its publication/restore scope and verified tar
+ * descriptor. A logical revision never substitutes for the exact physical key. */
+export function validateWorkspaceArchiveObjectRef(
+  value: unknown,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    descriptor: WorkspaceArchiveDescriptor;
+  },
+): WorkspaceArchiveObjectRef | null {
+  const ref = parseWorkspaceArchiveObjectRef(value);
+  const key = ref && parseWorkspaceArchiveObjectKey(ref.key);
+  const descriptor = parseWorkspaceArchiveDescriptor(input.descriptor);
+  if (
+    !ref ||
+    !key ||
+    descriptor?.version !== 1 ||
+    key.accountId.toLowerCase() !== input.accountId.toLowerCase() ||
+    key.workspaceId.toLowerCase() !== input.workspaceId.toLowerCase() ||
+    key.sandboxGroupId.toLowerCase() !== input.sandboxGroupId.toLowerCase() ||
+    key.revision !== descriptor.revision ||
+    ref.sha256 !== descriptor.archiveSha256 ||
+    ref.bytes !== descriptor.archiveBytes
+  )
+    return null;
+  return ref;
+}
+
+export function workspaceArchivePayloadPresent(
+  sessionState: Record<string, unknown> | null | undefined,
+): boolean {
+  if (!sessionState) return false;
+  if (
+    typeof sessionState.workspaceArchive === "string" &&
+    sessionState.workspaceArchive.length > 0
+  ) {
+    return true;
+  }
+  return parseWorkspaceArchiveObjectRef(sessionState.workspaceArchiveRef) !== null;
+}
+
+/** Restore may inline object bytes in memory for hydrate. That copy must never
+ *  be published onto a lease when a durable object-storage ref exists. */
+export function omitInlineWorkspaceArchiveWhenObjectRefPresent(
+  sessionState: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...sessionState };
+  if (parseWorkspaceArchiveObjectRef(next.workspaceArchiveRef)) {
+    delete next.workspaceArchive;
+  }
+  if (parseWorkspaceArchiveObjectRef(next.workspaceArchivePrevRef)) {
+    delete next.workspaceArchivePrev;
+  }
+  return next;
+}
+
 export const NATIVE_SNAPSHOT_PREFIXES: ReadonlyArray<{
   provider: NativeSnapshotProvider;
   prefix: string;

package/src/session-final-reply.ts

@@ -0,0 +1,16 @@
+/** A response-quality notice, not a failed turn or a completed deliverable. */
+export const EMPTY_FINAL_REPLY_NOTICE =
+  "The model returned no final reply after a reply reminder. Completed work is preserved; the goal and later updates are unaffected.";
+
+export type EmptyFinalReplyCompletion = {
+  emptyFinalReply: true;
+};
+
+export function turnCompletedWithEmptyFinalReply(payload: unknown): boolean {
+  return (
+    payload !== null &&
+    typeof payload === "object" &&
+    !Array.isArray(payload) &&
+    (payload as { emptyFinalReply?: unknown }).emptyFinalReply === true
+  );
+}

package/src/session-goal-reports.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+
+export const SessionGoalReportRequirement = z
+  .object({
+    id: z
+      .string()
+      .max(64)
+      .describe(
+        "Stable report requirement identifier, at most 64 ASCII characters; not a title or status.",
+      )
+      .regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/),
+    title: z
+      .string()
+      .trim()
+      .min(1)
+      .max(512)
+      .describe(
+        "Short human-readable report title, at most 512 UTF-8 bytes. Keep normal spaces; do not put the report or a progress transcript here.",
+      )
+      .refine(
+        (value) => new TextEncoder().encode(value).byteLength <= 512,
+        "Report title exceeds 512 UTF-8 bytes",
+      ),
+  })
+  .strict();
+export type SessionGoalReportRequirement = z.infer<typeof SessionGoalReportRequirement>;
+
+export const SessionGoalReportRequirements = z
+  .array(SessionGoalReportRequirement)
+  .max(16)
+  .superRefine((requirements, context) => {
+    if (new Set(requirements.map((item) => item.id)).size !== requirements.length) {
+      context.addIssue({ code: "custom", message: "Duplicate report requirement IDs" });
+    }
+  });
+
+export const SessionGoalReportDelivery = z
+  .object({
+    requirementId: SessionGoalReportRequirement.shape.id,
+    artifactId: z
+      .string()
+      .regex(/^[0-9a-f]{32}$/)
+      .refine((value) => !/^0+$/.test(value)),
+    inspectionReceiptId: z.string().uuid(),
+  })
+  .strict();
+export type SessionGoalReportDelivery = z.infer<typeof SessionGoalReportDelivery>;
+export const SessionGoalReportDeliveries = z
+  .array(SessionGoalReportDelivery)
+  .max(16)
+  .superRefine((deliveries, context) => {
+    if (new Set(deliveries.map((item) => item.requirementId)).size !== deliveries.length) {
+      context.addIssue({ code: "custom", message: "Duplicate report delivery requirement IDs" });
+    }
+  });

package/src/session-history-import.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import { Session } from "./index";
+import type { SessionEventType } from "./index";
+
+/** Import is a server-side migration boundary, not an execution/history API. */
+export const SESSION_HISTORY_IMPORT_MAX_EVENTS = 100;
+export const SESSION_HISTORY_IMPORT_MAX_BODY_BYTES = 1_048_576;
+export const SESSION_HISTORY_IMPORT_MAX_EVENT_BYTES = 262_144;
+
+/** Historical facts only: no approval, credential, control or execution inputs. */
+export const ARCHIVED_SESSION_IMPORT_EVENT_TYPES = [
+  "user.message",
+  "agent.message.delta",
+  "agent.message.completed",
+  "agent.reasoning.delta",
+  "agent.toolCall.created",
+  "agent.toolCall.output",
+  "artifact.created",
+  "turn.started",
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "turn.superseded",
+  "goal.set",
+  "goal.updated",
+  "goal.progress",
+  "goal.completed",
+  "goal.paused",
+  "goal.resumed",
+  "goal.cleared",
+] as const satisfies readonly SessionEventType[];
+
+export const SessionImportedArchive = /* @__PURE__ */ z
+  .object({
+    importId: z.string().min(1).max(200),
+    importedAt: z.iso.datetime({ offset: true }),
+    readOnly: z.literal(true),
+  })
+  .strict();
+export type SessionImportedArchive = z.infer<typeof SessionImportedArchive>;
+
+/** JS/SQL session seams preserve millisecond precision; never silently truncate. */
+const sourceTimestamp = /* @__PURE__ */ z.iso
+  .datetime({ offset: true })
+  .refine((value) => !/\.\d{4}/u.test(value), "Source timestamp supports at most milliseconds");
+
+/** Validate JSON without coercing dates, dropping undefined, or rewriting text. */
+function isImportJson(value: unknown): boolean {
+  const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }];
+  const seen = new Set<object>();
+  let nodes = 0;
+  while (pending.length > 0) {
+    const entry = pending.pop()!;
+    if (++nodes > 100_000 || entry.depth > 64) return false;
+    const current = entry.value;
+    if (current === null || typeof current === "string" || typeof current === "boolean") continue;
+    if (typeof current === "number") {
+      if (!Number.isFinite(current) || Object.is(current, -0)) return false;
+      continue;
+    }
+    if (typeof current !== "object" || seen.has(current)) return false;
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (let index = 0; index < current.length; index++) {
+        if (!Object.hasOwn(current, index)) return false;
+        pending.push({ value: current[index], depth: entry.depth + 1 });
+      }
+    } else {
+      const prototype = Object.getPrototypeOf(current);
+      if (prototype !== Object.prototype && prototype !== null) return false;
+      for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(current))) {
+        if (!descriptor.enumerable || !Object.hasOwn(descriptor, "value")) return false;
+        pending.push({ value: descriptor.value, depth: entry.depth + 1 });
+      }
+      if (Object.getOwnPropertySymbols(current).length > 0) return false;
+    }
+  }
+  return true;
+}
+
+function jsonBytes(value: unknown): number {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+export const ArchivedSessionImportEvent = /* @__PURE__ */ z
+  .object({
+    type: z.enum(ARCHIVED_SESSION_IMPORT_EVENT_TYPES),
+    createdAt: sourceTimestamp,
+    /** Source turn identity is presentation correlation; no execution row is created. */
+    turnId: z.string().uuid().nullable().optional(),
+    payload: z.record(z.string(), z.unknown()).refine(isImportJson, "Payload must be bounded JSON"),
+  })
+  .strict()
+  .refine(
+    (event) => isImportJson(event) && jsonBytes(event) <= SESSION_HISTORY_IMPORT_MAX_EVENT_BYTES,
+    "Imported event exceeds its JSON or byte limit",
+  );
+export type ArchivedSessionImportEvent = z.infer<typeof ArchivedSessionImportEvent>;
+
+const importEvents = /* @__PURE__ */ z
+  .array(ArchivedSessionImportEvent)
+  .max(SESSION_HISTORY_IMPORT_MAX_EVENTS);
+
+export const ImportArchivedSessionRequest = /* @__PURE__ */ z
+  .object({
+    importId: z.string().min(1).max(200),
+    title: z.string().min(1).max(200),
+    createdAt: sourceTimestamp,
+    /** The authenticated asUser actor supplies creator/owner, never a display label. */
+    visibility: z.enum(["workspace_shared", "user_private"]).optional(),
+    events: importEvents.default([]),
+  })
+  .strict()
+  .refine(
+    (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
+    "Import request exceeds its byte limit",
+  );
+export type ImportArchivedSessionRequest = z.input<typeof ImportArchivedSessionRequest>;
+
+export const AppendArchivedSessionEventsRequest = /* @__PURE__ */ z
+  .object({
+    batchId: z.string().min(1).max(200),
+    offset: z
+      .number()
+      .int()
+      .nonnegative()
+      .max(Number.MAX_SAFE_INTEGER)
+      .refine((value) => !Object.is(value, -0)),
+    events: importEvents.min(1),
+  })
+  .strict()
+  .refine(
+    (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
+    "Import batch exceeds its byte limit",
+  );
+export type AppendArchivedSessionEventsRequest = z.infer<typeof AppendArchivedSessionEventsRequest>;
+
+// Lazy to preserve the root contracts initialization order; SDK uses types only.
+export const ImportArchivedSessionResponse = /* @__PURE__ */ z.object({
+  session: /* @__PURE__ */ z.lazy(() => Session),
+  importId: z.string(),
+  created: z.boolean(),
+  nextOffset: z.number().int().nonnegative(),
+});
+export type ImportArchivedSessionResponse = z.infer<typeof ImportArchivedSessionResponse>;
+
+export const AppendArchivedSessionEventsResponse = /* @__PURE__ */ z.object({
+  sessionId: z.string().uuid(),
+  importId: z.string(),
+  nextOffset: z.number().int().nonnegative(),
+  replayed: z.boolean(),
+});
+export type AppendArchivedSessionEventsResponse = z.infer<
+  typeof AppendArchivedSessionEventsResponse
+>;