harness-mix 0.1.0

package/src/native-ui/shared-contracts/src/harness-session-import.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+
+import { harnessPluginIdSchema } from "./harness-plugins.js";
+import { hostThreadIdSchema } from "./ids.js";
+
+export const HARNESS_SESSION_IMPORT_ID_MAX_LENGTH = 1_024;
+export const HARNESS_SESSION_IMPORT_CWD_MAX_LENGTH = 16_384;
+export const HARNESS_SESSION_IMPORT_TITLE_MAX_LENGTH = 4_096;
+/** Per-response wire bound, not a storage or total-candidate limit. */
+export const HARNESS_SESSION_IMPORT_LIST_MAX_LENGTH = 1_000;
+export const HARNESS_SESSION_IMPORT_DEFAULT_PAGE_SIZE = 20;
+export const HARNESS_SESSION_IMPORT_UPDATED_AT_MAX = 8_640_000_000_000_000;
+
+const nonBlankTextSchema = z
+  .string()
+  .refine((value) => value.trim().length > 0, "Value must not be empty or whitespace")
+  .refine((value) => !value.includes("\0"), "Value must not contain NUL");
+
+export const harnessSessionImportIdSchema = nonBlankTextSchema.max(
+  HARNESS_SESSION_IMPORT_ID_MAX_LENGTH,
+);
+
+/** Browser-safe metadata required to map an existing Native Session into codexhost. */
+export const harnessSessionImportCandidateSchema = z
+  .object({
+    nativeSessionId: harnessSessionImportIdSchema,
+    title: nonBlankTextSchema.max(HARNESS_SESSION_IMPORT_TITLE_MAX_LENGTH).nullable(),
+    updatedAt: z.number().int().nonnegative().max(HARNESS_SESSION_IMPORT_UPDATED_AT_MAX),
+    cwd: nonBlankTextSchema.max(HARNESS_SESSION_IMPORT_CWD_MAX_LENGTH),
+    // Native file discovery cannot reliably observe another process's activity.
+    running: z.boolean().nullable(),
+  })
+  .strict();
+
+export type HarnessSessionImportCandidate = z.infer<typeof harnessSessionImportCandidateSchema>;
+
+export const harnessSessionImportSourcesParamsSchema = z.object({}).strict();
+export const harnessSessionImportSourcesResultSchema = z
+  .object({
+    harnesses: z
+      .array(
+        z
+          .object({
+            harnessId: harnessPluginIdSchema,
+            name: nonBlankTextSchema.max(128),
+          })
+          .strict(),
+      )
+      .max(128),
+  })
+  .strict();
+export const harnessSessionListParamsSchema = z
+  .object({
+    harnessId: harnessPluginIdSchema,
+    query: z
+      .string()
+      .trim()
+      .max(4_096)
+      .refine((value) => !value.includes("\0"))
+      .optional(),
+    offset: z.number().int().nonnegative().safe().optional(),
+    limit: z.number().int().min(1).max(HARNESS_SESSION_IMPORT_LIST_MAX_LENGTH).optional(),
+  })
+  .strict();
+export const harnessSessionListResultSchema = z
+  .object({
+    candidates: z
+      .array(harnessSessionImportCandidateSchema)
+      .max(HARNESS_SESSION_IMPORT_LIST_MAX_LENGTH),
+    total: z.number().int().nonnegative().safe(),
+  })
+  .strict();
+export const harnessSessionImportParamsSchema = z
+  .object({
+    harnessId: harnessPluginIdSchema,
+    nativeSessionId: harnessSessionImportIdSchema,
+  })
+  .strict();
+export const harnessSessionImportResultSchema = z
+  .object({
+    threadId: nonBlankTextSchema.max(1_024).pipe(hostThreadIdSchema),
+  })
+  .strict();
+export type HarnessSessionImportSourcesResult = z.infer<
+  typeof harnessSessionImportSourcesResultSchema
+>;
+export type HarnessSessionListParams = z.infer<typeof harnessSessionListParamsSchema>;
+export type HarnessSessionListResult = z.infer<typeof harnessSessionListResultSchema>;
+export type HarnessSessionImportParams = z.infer<typeof harnessSessionImportParamsSchema>;
+export type HarnessSessionImportResult = z.infer<typeof harnessSessionImportResultSchema>;

package/src/native-ui/shared-contracts/src/ids.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+const opaqueIdSchema = z.string().refine((value) => value.trim().length > 0, {
+  message: "Identifier must not be empty or whitespace",
+});
+
+export const harnessIdSchema = opaqueIdSchema.brand<"HarnessId">();
+export type HarnessId = z.infer<typeof harnessIdSchema>;
+
+export const hostThreadIdSchema = opaqueIdSchema.brand<"HostThreadId">();
+export type HostThreadId = z.infer<typeof hostThreadIdSchema>;
+
+export const hostTurnIdSchema = opaqueIdSchema.brand<"HostTurnId">();
+export type HostTurnId = z.infer<typeof hostTurnIdSchema>;
+
+export const hostItemIdSchema = opaqueIdSchema.brand<"HostItemId">();
+export type HostItemId = z.infer<typeof hostItemIdSchema>;
+
+export const hostInteractionIdSchema = opaqueIdSchema.brand<"HostInteractionId">();
+export type HostInteractionId = z.infer<typeof hostInteractionIdSchema>;

package/src/native-ui/shared-contracts/src/index.ts

@@ -0,0 +1,320 @@
+import { z } from "zod";
+import { WORKSPACE_CONTRACT_VERSION } from "./version.js";
+
+export {
+  harnessAccountSnapshotSchema,
+  harnessAccountListParamsSchema,
+  harnessAccountListResultSchema,
+} from "./harness-accounts.js";
+export type { HarnessAccountSnapshot, HarnessAccountListResult } from "./harness-accounts.js";
+
+export {
+  HARNESS_PLUGIN_ROUTE_PREFIX,
+  decodeHarnessPluginRoute,
+  encodeHarnessPluginRoute,
+  harnessPluginRouteSchema,
+} from "./harness-route.js";
+export type { HarnessPluginRoute } from "./harness-route.js";
+export {
+  HARNESS_PLUGIN_API_VERSION,
+  HARNESS_PLUGIN_ICON_MAX_BYTES,
+  HARNESS_PLUGIN_LIMIT,
+  HARNESS_PLUGIN_MANIFEST_MAX_BYTES,
+  harnessPluginConfigurationSchema,
+  harnessPluginDescriptorSchema,
+  harnessPluginIconSchema,
+  harnessPluginIdSchema,
+  harnessPluginListParamsSchema,
+  harnessPluginListResultSchema,
+  harnessPluginManifestSchema,
+} from "./harness-plugins.js";
+export type {
+  HarnessPluginConfiguration,
+  HarnessPluginDescriptor,
+  HarnessPluginListResult,
+  HarnessPluginManifest,
+} from "./harness-plugins.js";
+export { codexhostErrorSchema } from "./errors.js";
+export {
+  codexAccountUsageParamsSchema,
+  codexAccountUsageResultSchema,
+  codexAccountResetCreditConsumeParamsSchema,
+  codexAccountResetCreditConsumeOutcomeSchema,
+  codexAccountResetCreditConsumeResultSchema,
+  codexAccountActivateParamsSchema,
+  codexAccountCreateParamsSchema,
+  codexAccountDeleteParamsSchema,
+  codexAccountDeleteResultSchema,
+  codexAccountListResultSchema,
+  codexAccountLoginCancelParamsSchema,
+  codexAccountLoginCancelResultSchema,
+  codexAccountLoginCompletedSchema,
+  codexAccountLoginStartParamsSchema,
+  codexAccountLoginStartResultSchema,
+  codexAccountMutationResultSchema,
+  codexAccountPlanTypeSchema,
+  codexAccountSchema,
+} from "./codex-accounts.js";
+export type {
+  CodexAccountUsageParams,
+  CodexAccountUsageResult,
+  CodexAccountResetCreditConsumeParams,
+  CodexAccountResetCreditConsumeOutcome,
+  CodexAccountResetCreditConsumeResult,
+  CodexAccountActivateParams,
+  CodexAccountCreateParams,
+  CodexAccountDeleteParams,
+  CodexAccountDeleteResult,
+  CodexAccountListResult,
+  CodexAccountLoginCancelParams,
+  CodexAccountLoginCancelResult,
+  CodexAccountLoginCompleted,
+  CodexAccountLoginStartParams,
+  CodexAccountLoginStartResult,
+  CodexAccountMutationResult,
+  CodexAccountPlanType,
+  CodexAccountSummary,
+} from "./codex-accounts.js";
+export { REASONING_TRANSCRIPT_COMMAND } from "./reasoning-transcript.js";
+export type { CodexhostError } from "./errors.js";
+export {
+  HARNESS_SESSION_IMPORT_CWD_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_ID_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_LIST_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_TITLE_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_UPDATED_AT_MAX,
+  harnessSessionImportCandidateSchema,
+  HARNESS_SESSION_IMPORT_DEFAULT_PAGE_SIZE,
+  harnessSessionImportIdSchema,
+  harnessSessionImportSourcesParamsSchema,
+  harnessSessionImportSourcesResultSchema,
+  harnessSessionListParamsSchema,
+  harnessSessionListResultSchema,
+  harnessSessionImportParamsSchema,
+  harnessSessionImportResultSchema,
+} from "./harness-session-import.js";
+export type {
+  HarnessSessionImportCandidate,
+  HarnessSessionImportSourcesResult,
+  HarnessSessionListParams,
+  HarnessSessionListResult,
+  HarnessSessionImportParams,
+  HarnessSessionImportResult,
+} from "./harness-session-import.js";
+export {
+  DEEPSEEK_MODERN_HOST_THREAD_ID_MAX_LENGTH,
+  DEEPSEEK_MODERN_SESSION_CWD_MAX_LENGTH,
+  DEEPSEEK_MODERN_SESSION_ID_MAX_LENGTH,
+  DEEPSEEK_MODERN_SESSION_LIST_MAX_LENGTH,
+  DEEPSEEK_MODERN_SESSION_TITLE_MAX_LENGTH,
+  DEEPSEEK_MODERN_SESSION_UPDATED_AT_MAX,
+  deepSeekModernSessionCandidateSchema,
+  deepSeekModernSessionImportParamsSchema,
+  deepSeekModernSessionImportResultSchema,
+  deepSeekModernSessionListParamsSchema,
+  deepSeekModernSessionListResultSchema,
+} from "./deepseek-modern-sessions.js";
+export type {
+  DeepSeekModernSessionCandidate,
+  DeepSeekModernSessionImportParams,
+  DeepSeekModernSessionImportResult,
+  DeepSeekModernSessionListParams,
+  DeepSeekModernSessionListResult,
+} from "./deepseek-modern-sessions.js";
+export {
+  externalThreadForkParamsSchema,
+  externalThreadForkResultSchema,
+} from "./external-thread-fork.js";
+export type { ExternalThreadForkParams, ExternalThreadForkResult } from "./external-thread-fork.js";
+export {
+  threadHarnessSwitchParamsSchema,
+  threadHarnessSwitchResultSchema,
+} from "./thread-harness-switch.js";
+export type { ThreadHarnessSwitchParams, ThreadHarnessSwitchResult } from "./thread-harness-switch.js";
+export {
+  HARNESS_PERMISSION_MODE_CATALOG_MAX_LENGTH,
+  HARNESS_PERMISSION_MODE_DESCRIPTION_MAX_LENGTH,
+  HARNESS_PERMISSION_MODE_ID_MAX_LENGTH,
+  HARNESS_PERMISSION_MODE_LABEL_MAX_LENGTH,
+  harnessPermissionModeCatalogSchema,
+  harnessPermissionModeIdSchema,
+  harnessPermissionModeSchema,
+  threadPermissionModeSelectParamsSchema,
+} from "./harness-permission-modes.js";
+export type {
+  HarnessPermissionMode,
+  HarnessPermissionModeCatalog,
+  HarnessPermissionModeId,
+  ThreadPermissionModeSelectParams,
+} from "./harness-permission-modes.js";
+export {
+  HARNESS_MODEL_LABEL_MAX_LENGTH,
+  HARNESS_MODEL_REF_MAX_LENGTH,
+  HARNESS_THINKING_OPTION_ID_MAX_LENGTH,
+  THREAD_OWNERSHIP_LIST_MAX_LENGTH,
+  harnessConfigurationStateSchema,
+  harnessInspectParamsSchema,
+  harnessInspectionSchema,
+  harnessModelCatalogSchema,
+  harnessModelRefIdSchema,
+  harnessModelRefSchema,
+  harnessModelSchema,
+  harnessModelSelectionStateSchema,
+  harnessPermissionModeScopeSchema,
+  harnessResolvedModelLabelSchema,
+  harnessSessionCapabilitiesSchema,
+  harnessThinkingOptionIdSchema,
+  harnessThinkingOptionSchema,
+  harnessWebUiCapabilitySchema,
+  harnessWebUiOpenParamsSchema,
+  harnessWebUiOpenResultSchema,
+  permissionModeFixedAtCreate,
+  threadInspectionParamsSchema,
+  threadInspectionSchema,
+  threadModelSelectParamsSchema,
+  threadThinkingSelectParamsSchema,
+  threadOwnershipListParamsSchema,
+  threadOwnershipListResultSchema,
+  threadOwnershipSchema,
+} from "./harness-models.js";
+export type {
+  HarnessConfigurationState,
+  HarnessInspectParams,
+  HarnessInspection,
+  HarnessModel,
+  HarnessModelCatalog,
+  HarnessModelRef,
+  HarnessModelSelectionState,
+  HarnessPermissionModeScope,
+  HarnessSessionCapabilities,
+  HarnessThinkingOption,
+  HarnessThinkingOptionId,
+  HarnessWebUiCapability,
+  HarnessWebUiOpenParams,
+  HarnessWebUiOpenResult,
+  ThreadInspection,
+  ThreadInspectionParams,
+  ThreadModelSelectParams,
+  ThreadThinkingSelectParams,
+  ThreadOwnership,
+  ThreadOwnershipListParams,
+  ThreadOwnershipListResult,
+} from "./harness-models.js";
+export {
+  harnessCommandCatalogSchema,
+  harnessCommandDescriptorSchema,
+  harnessCommandsInspectParamsSchema,
+  threadCommandExecuteParamsSchema,
+  threadCommandExecuteResultSchema,
+  threadCommandsInspectParamsSchema,
+} from "./harness-commands.js";
+export type {
+  HarnessCommandCatalog,
+  HarnessCommandDescriptor,
+  HarnessCommandsInspectParams,
+  ThreadCommandExecuteParams,
+  ThreadCommandExecuteResult,
+  ThreadCommandsInspectParams,
+} from "./harness-commands.js";
+export {
+  accountCreditsProductUsageSchema,
+  accountResetCreditsSchema,
+  accountCreditsSnapshotSchema,
+  threadUsageInspectionParamsSchema,
+  threadUsageInspectionSchema,
+  threadUsageSnapshotSchema,
+} from "./thread-usage.js";
+export type {
+  AccountCreditsSnapshot,
+  AccountResetCredits,
+  ThreadUsageInspection,
+  ThreadUsageInspectionParams,
+  ThreadUsageSnapshot,
+} from "./thread-usage.js";
+export {
+  threadDelegateParamsSchema,
+  threadDelegationResultSchema,
+  threadMessageParamsSchema,
+} from "./thread-delegate.js";
+export type {
+  ThreadDelegateParams,
+  ThreadDelegationResult,
+  ThreadMessageParams,
+} from "./thread-delegate.js";
+export {
+  harnessIdSchema,
+  hostInteractionIdSchema,
+  hostItemIdSchema,
+  hostThreadIdSchema,
+  hostTurnIdSchema,
+} from "./ids.js";
+export type { HarnessId, HostInteractionId, HostItemId, HostThreadId, HostTurnId } from "./ids.js";
+export {
+  jsonRpcEnvelopeSchema,
+  jsonRpcErrorResponseSchema,
+  jsonRpcErrorSchema,
+  jsonRpcIdSchema,
+  jsonRpcNotificationSchema,
+  jsonRpcRequestSchema,
+  jsonRpcSuccessResponseSchema,
+} from "./json-rpc.js";
+export type {
+  JsonRpcEnvelope,
+  JsonRpcError,
+  JsonRpcErrorResponse,
+  JsonRpcId,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonRpcSuccessResponse,
+} from "./json-rpc.js";
+export {
+  jsonArraySchema,
+  jsonObjectSchema,
+  jsonPrimitiveSchema,
+  jsonValueSchema,
+} from "./json-value.js";
+export type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from "./json-value.js";
+export {
+  nativeCheckpointRefSchema,
+  nativeCheckpointRefV1Schema,
+  nativeSessionRefSchema,
+  nativeSessionRefV1Schema,
+  nativeTurnRefSchema,
+  nativeTurnRefV1Schema,
+} from "./native-refs.js";
+export type {
+  NativeCheckpointRef,
+  NativeCheckpointRefV1,
+  NativeSessionRef,
+  NativeSessionRefV1,
+  NativeTurnRef,
+  NativeTurnRefV1,
+} from "./native-refs.js";
+export {
+  UPDATE_ERROR_MAX_LENGTH,
+  UPDATE_SEMVER_PATTERN,
+  updateCheckResultSchema,
+  updateEmptyParamsSchema,
+  updateInstallationSchema,
+  updatePhaseSchema,
+  updateSemanticVersionSchema,
+  updateStartResultSchema,
+  updateStatusResultSchema,
+  updateStatusSchema,
+} from "./updates.js";
+export type {
+  UpdateCheckResult,
+  UpdateInstallation,
+  UpdatePhase,
+  UpdateStartResult,
+  UpdateStatus,
+  UpdateStatusResult,
+} from "./updates.js";
+export { WORKSPACE_CONTRACT_VERSION } from "./version.js";
+
+export const workspaceContractVersionSchema = z.literal(WORKSPACE_CONTRACT_VERSION);
+
+export const packageMetadata = {
+  name: "@codexhost/shared-contracts",
+  contractVersion: WORKSPACE_CONTRACT_VERSION,
+} as const;

package/src/native-ui/shared-contracts/src/json-rpc.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+
+import { jsonValueSchema, rejectExplicitUndefined } from "./json-value.js";
+
+const jsonRpcVersionSchema = z.literal("2.0").optional();
+const absentSchema = z.never().optional();
+const methodSchema = z.string().min(1);
+
+export const jsonRpcIdSchema = z.union([z.string(), z.number().int()]);
+export type JsonRpcId = z.infer<typeof jsonRpcIdSchema>;
+
+export const jsonRpcErrorSchema = z
+  .object({
+    code: z.number().int(),
+    message: z.string(),
+    data: jsonValueSchema.optional(),
+  })
+  .catchall(jsonValueSchema)
+  .superRefine(rejectExplicitUndefined(["data"]));
+export type JsonRpcError = z.infer<typeof jsonRpcErrorSchema>;
+
+export const jsonRpcRequestSchema = z
+  .object({
+    jsonrpc: jsonRpcVersionSchema,
+    id: jsonRpcIdSchema,
+    method: methodSchema,
+    params: jsonValueSchema.optional(),
+    result: absentSchema,
+    error: absentSchema,
+  })
+  .catchall(jsonValueSchema)
+  .superRefine(rejectExplicitUndefined(["jsonrpc", "params", "result", "error"]));
+export type JsonRpcRequest = z.infer<typeof jsonRpcRequestSchema>;
+
+export const jsonRpcNotificationSchema = z
+  .object({
+    jsonrpc: jsonRpcVersionSchema,
+    id: absentSchema,
+    method: methodSchema,
+    params: jsonValueSchema.optional(),
+    result: absentSchema,
+    error: absentSchema,
+  })
+  .catchall(jsonValueSchema)
+  .superRefine(rejectExplicitUndefined(["jsonrpc", "id", "params", "result", "error"]));
+export type JsonRpcNotification = z.infer<typeof jsonRpcNotificationSchema>;
+
+export const jsonRpcSuccessResponseSchema = z
+  .object({
+    jsonrpc: jsonRpcVersionSchema,
+    id: jsonRpcIdSchema,
+    method: absentSchema,
+    params: absentSchema,
+    result: jsonValueSchema,
+    error: absentSchema,
+  })
+  .catchall(jsonValueSchema)
+  .superRefine(rejectExplicitUndefined(["jsonrpc", "method", "params", "error"]));
+export type JsonRpcSuccessResponse = z.infer<typeof jsonRpcSuccessResponseSchema>;
+
+export const jsonRpcErrorResponseSchema = z
+  .object({
+    jsonrpc: jsonRpcVersionSchema,
+    id: jsonRpcIdSchema,
+    method: absentSchema,
+    params: absentSchema,
+    result: absentSchema,
+    error: jsonRpcErrorSchema,
+  })
+  .catchall(jsonValueSchema)
+  .superRefine(rejectExplicitUndefined(["jsonrpc", "method", "params", "result"]));
+export type JsonRpcErrorResponse = z.infer<typeof jsonRpcErrorResponseSchema>;
+
+export const jsonRpcEnvelopeSchema = z.union([
+  jsonRpcRequestSchema,
+  jsonRpcNotificationSchema,
+  jsonRpcSuccessResponseSchema,
+  jsonRpcErrorResponseSchema,
+]);
+export type JsonRpcEnvelope = z.infer<typeof jsonRpcEnvelopeSchema>;

package/src/native-ui/shared-contracts/src/json-value.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonValue[];
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+
+export function rejectExplicitUndefined(keys: readonly string[]) {
+  return (value: object, context: z.RefinementCtx): void => {
+    for (const key of keys) {
+      if (Object.hasOwn(value, key) && (value as Record<string, unknown>)[key] === undefined) {
+        context.addIssue({
+          code: "custom",
+          path: [key],
+          message: "Explicit undefined is not valid JSON",
+        });
+      }
+    }
+  };
+}
+
+export const jsonPrimitiveSchema: z.ZodType<JsonPrimitive> = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+
+function hasNoCircularReferences(value: unknown): boolean {
+  const ancestors = new WeakSet<object>();
+  const stack: Array<{ value: unknown; leaving: boolean }> = [{ value, leaving: false }];
+
+  try {
+    while (stack.length > 0) {
+      const frame = stack.pop();
+      if (!frame) break;
+
+      if (frame.leaving) {
+        ancestors.delete(frame.value as object);
+        continue;
+      }
+
+      if (typeof frame.value !== "object" || frame.value === null) continue;
+      if (ancestors.has(frame.value)) return false;
+
+      ancestors.add(frame.value);
+      stack.push({ value: frame.value, leaving: true });
+      for (const child of Object.values(frame.value)) {
+        stack.push({ value: child, leaving: false });
+      }
+    }
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+const nonCircularSchema = z.custom<unknown>(hasNoCircularReferences, {
+  message: "JSON value must not contain circular references",
+});
+
+const recursiveJsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    jsonPrimitiveSchema,
+    z.array(recursiveJsonValueSchema),
+    z.record(z.string(), recursiveJsonValueSchema),
+  ]),
+);
+
+export const jsonValueSchema: z.ZodType<JsonValue> =
+  nonCircularSchema.pipe(recursiveJsonValueSchema);
+export const jsonArraySchema: z.ZodType<JsonArray> = nonCircularSchema.pipe(
+  z.array(recursiveJsonValueSchema),
+);
+export const jsonObjectSchema: z.ZodType<JsonObject> = nonCircularSchema.pipe(
+  z.record(z.string(), recursiveJsonValueSchema),
+);

package/src/native-ui/shared-contracts/src/native-refs.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+import { harnessIdSchema } from "./ids.js";
+import { jsonValueSchema, rejectExplicitUndefined } from "./json-value.js";
+import type { JsonValue } from "./json-value.js";
+
+const nativeIdSchema = z.string().refine((value) => value.trim().length > 0, {
+  message: "Native identifier must not be empty or whitespace",
+});
+
+const nativeSessionRefV1RuntimeSchema = z
+  .strictObject({
+    harnessId: harnessIdSchema,
+    nativeSessionId: nativeIdSchema,
+    locator: jsonValueSchema.optional(),
+    formatVersion: z.literal(1),
+  })
+  .superRefine(rejectExplicitUndefined(["locator"]));
+export type NativeSessionRefV1 = Omit<
+  z.infer<typeof nativeSessionRefV1RuntimeSchema>,
+  "locator"
+> & {
+  locator?: JsonValue;
+};
+export const nativeSessionRefV1Schema =
+  nativeSessionRefV1RuntimeSchema as z.ZodType<NativeSessionRefV1>;
+export const nativeSessionRefSchema = nativeSessionRefV1Schema;
+export type NativeSessionRef = NativeSessionRefV1;
+
+export const nativeTurnRefV1Schema = z.strictObject({
+  harnessId: harnessIdSchema,
+  nativeSessionId: nativeIdSchema,
+  nativeTurnKey: nativeIdSchema,
+  formatVersion: z.literal(1),
+});
+export type NativeTurnRefV1 = z.infer<typeof nativeTurnRefV1Schema>;
+export const nativeTurnRefSchema = nativeTurnRefV1Schema;
+export type NativeTurnRef = NativeTurnRefV1;
+
+const nativeCheckpointRefV1RuntimeSchema = z
+  .strictObject({
+    harnessId: harnessIdSchema,
+    nativeSessionId: nativeIdSchema,
+    checkpointId: nativeIdSchema,
+    locator: jsonValueSchema.optional(),
+    formatVersion: z.literal(1),
+  })
+  .superRefine(rejectExplicitUndefined(["locator"]));
+export type NativeCheckpointRefV1 = Omit<
+  z.infer<typeof nativeCheckpointRefV1RuntimeSchema>,
+  "locator"
+> & {
+  locator?: JsonValue;
+};
+export const nativeCheckpointRefV1Schema =
+  nativeCheckpointRefV1RuntimeSchema as z.ZodType<NativeCheckpointRefV1>;
+export const nativeCheckpointRefSchema = nativeCheckpointRefV1Schema;
+export type NativeCheckpointRef = NativeCheckpointRefV1;

package/src/native-ui/shared-contracts/src/reasoning-transcript.ts

@@ -0,0 +1,6 @@
+/**
+ * PROTOTYPE: Codex Desktop renders text for the Command Execution lane only, so
+ * Reasoning is projected as a Command Execution carrying this sentinel command.
+ * Both the transcript projection and the Renderer summary surface key off it.
+ */
+export const REASONING_TRANSCRIPT_COMMAND = "thinking";

package/src/native-ui/shared-contracts/src/thread-delegate.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+import { harnessIdSchema, hostThreadIdSchema, hostTurnIdSchema } from "./ids.js";
+
+const delegationTaskSchema = z.string().trim().min(1).max(8000);
+
+export const threadDelegateParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    harnessId: harnessIdSchema,
+    task: delegationTaskSchema,
+  })
+  .strict();
+
+export type ThreadDelegateParams = z.infer<typeof threadDelegateParamsSchema>;
+
+export const threadMessageParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    childThreadId: hostThreadIdSchema,
+    task: delegationTaskSchema,
+  })
+  .strict();
+
+export type ThreadMessageParams = z.infer<typeof threadMessageParamsSchema>;
+
+// 协作 Turn 的完整投影由 turn/* 通知流承载；结果只需携带身份供客户端关联
+export const threadDelegationResultSchema = z
+  .object({
+    childThreadId: hostThreadIdSchema,
+    turn: z
+      .object({
+        id: hostTurnIdSchema,
+        status: z.string(),
+      })
+      .loose(),
+  })
+  .strict();
+
+export type ThreadDelegationResult = z.infer<typeof threadDelegationResultSchema>;