harness-mix 0.1.0

package/src/native-ui/shared-contracts/src/harness-models.ts

@@ -0,0 +1,401 @@
+import { z } from "zod";
+
+import { codexhostErrorSchema } from "./errors.js";
+import {
+  harnessPermissionModeCatalogSchema,
+  harnessPermissionModeIdSchema,
+} from "./harness-permission-modes.js";
+import { harnessIdSchema, hostThreadIdSchema } from "./ids.js";
+import { threadUsageSnapshotSchema } from "./thread-usage.js";
+
+export const HARNESS_MODEL_REF_MAX_LENGTH = 512;
+export const HARNESS_MODEL_LABEL_MAX_LENGTH = 256;
+export const HARNESS_THINKING_OPTION_ID_MAX_LENGTH = 128;
+export const THREAD_OWNERSHIP_LIST_MAX_LENGTH = 100;
+
+const nonBlankTextSchema = z.string().refine((value) => value.trim().length > 0, {
+  message: "Value must not be empty or whitespace",
+});
+
+export const harnessModelRefIdSchema = nonBlankTextSchema
+  .max(HARNESS_MODEL_REF_MAX_LENGTH)
+  .regex(/^[A-Za-z0-9._~-]+$/u, "Model Ref must use transport-safe opaque characters")
+  .brand<"HarnessModelRefId">();
+
+export const harnessModelRefSchema = z
+  .object({
+    id: harnessModelRefIdSchema,
+  })
+  .strict();
+
+export type HarnessModelRef = z.infer<typeof harnessModelRefSchema>;
+
+export const harnessThinkingOptionIdSchema = nonBlankTextSchema
+  .max(HARNESS_THINKING_OPTION_ID_MAX_LENGTH)
+  .regex(/^[A-Za-z0-9._~-]+$/u, "Thinking option ID must use transport-safe characters")
+  .brand<"HarnessThinkingOptionId">();
+
+export type HarnessThinkingOptionId = z.infer<typeof harnessThinkingOptionIdSchema>;
+
+export const harnessResolvedModelLabelSchema = nonBlankTextSchema.max(
+  HARNESS_MODEL_LABEL_MAX_LENGTH,
+);
+
+export const harnessThinkingOptionSchema = z
+  .object({
+    id: harnessThinkingOptionIdSchema,
+    label: nonBlankTextSchema.max(HARNESS_MODEL_LABEL_MAX_LENGTH),
+  })
+  .strict();
+
+export type HarnessThinkingOption = z.infer<typeof harnessThinkingOptionSchema>;
+
+export const harnessModelSchema = z
+  .object({
+    ref: harnessModelRefSchema,
+    label: nonBlankTextSchema.max(HARNESS_MODEL_LABEL_MAX_LENGTH),
+    resolvedModelLabel: harnessResolvedModelLabelSchema.optional(),
+    supportedThinkingOptionIds: z.array(harnessThinkingOptionIdSchema).optional(),
+  })
+  .strict();
+
+export type HarnessModel = z.infer<typeof harnessModelSchema>;
+
+const harnessThinkingOptionsSchema = z
+  .array(harnessThinkingOptionSchema)
+  .superRefine((options, context) => {
+    const ids = new Set<string>();
+    for (const [index, option] of options.entries()) {
+      if (ids.has(option.id)) {
+        context.addIssue({
+          code: "custom",
+          message: "Thinking option IDs must be unique",
+          path: [index, "id"],
+        });
+      }
+      ids.add(option.id);
+    }
+  });
+
+export const harnessModelCatalogSchema = z
+  .object({
+    models: z.array(harnessModelSchema),
+    defaultModel: harnessModelRefSchema.optional(),
+    thinkingOptions: harnessThinkingOptionsSchema,
+    defaultThinkingOptionId: harnessThinkingOptionIdSchema.optional(),
+  })
+  .strict()
+  .superRefine((catalog, context) => {
+    const refs = new Set<string>();
+    const thinkingIds = new Set(catalog.thinkingOptions.map(({ id }) => id));
+    for (const [index, model] of catalog.models.entries()) {
+      if (refs.has(model.ref.id)) {
+        context.addIssue({
+          code: "custom",
+          message: "Model Catalog refs must be unique",
+          path: ["models", index, "ref", "id"],
+        });
+      }
+      refs.add(model.ref.id);
+      const supportedThinkingIds = new Set<string>();
+      for (const [optionIndex, optionId] of (model.supportedThinkingOptionIds ?? []).entries()) {
+        if (supportedThinkingIds.has(optionId)) {
+          context.addIssue({
+            code: "custom",
+            message: "Supported Thinking option IDs must be unique per Model",
+            path: ["models", index, "supportedThinkingOptionIds", optionIndex],
+          });
+        }
+        supportedThinkingIds.add(optionId);
+        if (!thinkingIds.has(optionId)) {
+          context.addIssue({
+            code: "custom",
+            message: "Supported Thinking option must exist in the catalog",
+            path: ["models", index, "supportedThinkingOptionIds", optionIndex],
+          });
+        }
+      }
+    }
+    if (catalog.defaultModel && !refs.has(catalog.defaultModel.id)) {
+      context.addIssue({
+        code: "custom",
+        message: "Default Model must exist in the Model Catalog",
+        path: ["defaultModel", "id"],
+      });
+    }
+    if (catalog.defaultThinkingOptionId && !thinkingIds.has(catalog.defaultThinkingOptionId)) {
+      context.addIssue({
+        code: "custom",
+        message: "Default Thinking option must exist in the catalog",
+        path: ["defaultThinkingOptionId"],
+      });
+    }
+  });
+
+export type HarnessModelCatalog = z.infer<typeof harnessModelCatalogSchema>;
+
+const harnessHistoryCapabilitiesSchema = z
+  .object({
+    fork: z.boolean(),
+    forkAcrossCwd: z.boolean(),
+    rollbackLastTurn: z.boolean(),
+  })
+  .strict()
+  .refine((history) => history.fork || !history.forkAcrossCwd, {
+    path: ["forkAcrossCwd"],
+    message: "Cross-cwd Fork requires exact history Fork support",
+  });
+
+export const harnessPermissionModeScopeSchema = z.enum(["live", "atCreate"]);
+
+export type HarnessPermissionModeScope = z.infer<typeof harnessPermissionModeScopeSchema>;
+
+export function permissionModeFixedAtCreate(configuration: {
+  permissionModeScope?: HarnessPermissionModeScope;
+}): boolean {
+  return configuration.permissionModeScope === "atCreate";
+}
+
+export const harnessSessionCapabilitiesSchema = z
+  .object({
+    configuration: z
+      .object({
+        selectModel: z.boolean(),
+        selectThinkingOption: z.boolean(),
+        selectPermissionMode: z.boolean(),
+        permissionModeScope: harnessPermissionModeScopeSchema.default("live"),
+      })
+      .strict(),
+    history: harnessHistoryCapabilitiesSchema,
+    subagents: z
+      .object({
+        observe: z.boolean(),
+        readTranscript: z.boolean(),
+      })
+      .strict()
+      .optional(),
+    autonomousTurns: z
+      .object({
+        observe: z.boolean(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type HarnessSessionCapabilities = z.infer<typeof harnessSessionCapabilitiesSchema>;
+
+export const harnessConfigurationStateSchema = z
+  .object({
+    effectiveModel: harnessModelRefSchema.optional(),
+    resolvedModelLabel: harnessResolvedModelLabelSchema.optional(),
+    effectiveThinkingOptionId: harnessThinkingOptionIdSchema.optional(),
+    availableThinkingOptions: harnessThinkingOptionsSchema.optional(),
+    effectivePermissionModeId: harnessPermissionModeIdSchema.optional(),
+  })
+  .strict()
+  .superRefine((state, context) => {
+    if (
+      state.effectiveThinkingOptionId &&
+      state.availableThinkingOptions &&
+      !state.availableThinkingOptions.some(({ id }) => id === state.effectiveThinkingOptionId)
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Effective Thinking option must be currently available",
+        path: ["effectiveThinkingOptionId"],
+      });
+    }
+  });
+
+export type HarnessConfigurationState = z.infer<typeof harnessConfigurationStateSchema>;
+
+export const harnessModelSelectionStateSchema = harnessConfigurationStateSchema;
+export type HarnessModelSelectionState = HarnessConfigurationState;
+
+export const harnessWebUiCapabilitySchema = z
+  .object({
+    open: z.literal(true),
+  })
+  .strict();
+
+export type HarnessWebUiCapability = z.infer<typeof harnessWebUiCapabilitySchema>;
+
+const readyHarnessInspectionSchema = z
+  .object({
+    status: z.literal("ready"),
+    catalog: harnessModelCatalogSchema,
+    permissionModes: harnessPermissionModeCatalogSchema.optional(),
+    capabilities: harnessSessionCapabilitiesSchema,
+    webUi: harnessWebUiCapabilitySchema.optional(),
+  })
+  .strict()
+  .superRefine((inspection, context) => {
+    const selectable = inspection.capabilities.configuration.selectPermissionMode;
+    if (selectable !== Boolean(inspection.permissionModes)) {
+      context.addIssue({
+        code: "custom",
+        message: "Permission Mode catalog and capability must agree",
+        path: selectable
+          ? ["permissionModes"]
+          : ["capabilities", "configuration", "selectPermissionMode"],
+      });
+    }
+  });
+
+const failedHarnessInspectionSchema = z
+  .object({
+    status: z.enum(["notInstalled", "unavailable", "error"]),
+    error: codexhostErrorSchema,
+  })
+  .strict();
+
+export const harnessInspectionSchema = z.union([
+  readyHarnessInspectionSchema,
+  failedHarnessInspectionSchema,
+]);
+
+export type HarnessInspection = z.infer<typeof harnessInspectionSchema>;
+
+export const harnessInspectParamsSchema = z
+  .object({
+    harnessId: harnessIdSchema,
+    cwd: nonBlankTextSchema.max(16_384).optional(),
+    refresh: z.boolean().optional(),
+  })
+  .strict();
+
+export type HarnessInspectParams = z.infer<typeof harnessInspectParamsSchema>;
+
+export const harnessWebUiOpenParamsSchema = z
+  .object({
+    harnessId: harnessIdSchema,
+  })
+  .strict();
+
+export type HarnessWebUiOpenParams = z.infer<typeof harnessWebUiOpenParamsSchema>;
+
+export const harnessWebUiOpenResultSchema = z.object({}).strict();
+
+export type HarnessWebUiOpenResult = z.infer<typeof harnessWebUiOpenResultSchema>;
+
+export const threadModelSelectParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    model: harnessModelRefSchema,
+  })
+  .strict();
+
+export type ThreadModelSelectParams = z.infer<typeof threadModelSelectParamsSchema>;
+
+export const threadThinkingSelectParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    thinkingOptionId: harnessThinkingOptionIdSchema,
+  })
+  .strict();
+
+export type ThreadThinkingSelectParams = z.infer<typeof threadThinkingSelectParamsSchema>;
+
+export const threadInspectionParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+  })
+  .strict();
+
+export type ThreadInspectionParams = z.infer<typeof threadInspectionParamsSchema>;
+
+const codexThreadInspectionSchema = z
+  .object({
+    owner: z.literal("codex"),
+    accountId: nonBlankTextSchema.optional(),
+    locked: z.literal(true),
+  })
+  .strict();
+
+const externalThreadInspectionSchema = z
+  .object({
+    owner: z.literal("external"),
+    harnessId: nonBlankTextSchema.max(256),
+    transportModelId: nonBlankTextSchema.max(1_024),
+    effectiveModel: harnessModelRefSchema.optional(),
+    resolvedModelLabel: harnessResolvedModelLabelSchema.optional(),
+    effectiveThinkingOptionId: harnessThinkingOptionIdSchema.optional(),
+    availableThinkingOptions: harnessThinkingOptionsSchema.optional(),
+    effectivePermissionModeId: harnessPermissionModeIdSchema.optional(),
+    history: harnessHistoryCapabilitiesSchema,
+    usage: threadUsageSnapshotSchema.optional(),
+    locked: z.literal(true),
+  })
+  .strict();
+
+export const threadInspectionSchema = z.discriminatedUnion("owner", [
+  codexThreadInspectionSchema,
+  externalThreadInspectionSchema,
+]);
+
+export type ThreadInspection = z.infer<typeof threadInspectionSchema>;
+
+export const threadOwnershipListParamsSchema = z
+  .object({
+    threadIds: z.array(hostThreadIdSchema).min(1).max(THREAD_OWNERSHIP_LIST_MAX_LENGTH),
+  })
+  .strict()
+  .superRefine(({ threadIds }, context) => {
+    const seen = new Set<string>();
+    for (const [index, threadId] of threadIds.entries()) {
+      if (seen.has(threadId)) {
+        context.addIssue({
+          code: "custom",
+          message: "Thread ownership-list IDs must be unique",
+          path: ["threadIds", index],
+        });
+      }
+      seen.add(threadId);
+    }
+  });
+
+export type ThreadOwnershipListParams = z.infer<typeof threadOwnershipListParamsSchema>;
+
+const codexThreadOwnershipSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    owner: z.literal("codex"),
+  })
+  .strict();
+
+const externalThreadOwnershipSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    owner: z.literal("external"),
+    harnessId: z.string().max(256).pipe(harnessIdSchema),
+  })
+  .strict();
+
+export const threadOwnershipSchema = z.discriminatedUnion("owner", [
+  codexThreadOwnershipSchema,
+  externalThreadOwnershipSchema,
+]);
+
+export type ThreadOwnership = z.infer<typeof threadOwnershipSchema>;
+
+export const threadOwnershipListResultSchema = z
+  .object({
+    threads: z.array(threadOwnershipSchema).min(1).max(THREAD_OWNERSHIP_LIST_MAX_LENGTH),
+  })
+  .strict()
+  .superRefine(({ threads }, context) => {
+    const seen = new Set<string>();
+    for (const [index, thread] of threads.entries()) {
+      if (seen.has(thread.threadId)) {
+        context.addIssue({
+          code: "custom",
+          message: "Thread ownership-list results must be unique",
+          path: ["threads", index, "threadId"],
+        });
+      }
+      seen.add(thread.threadId);
+    }
+  });
+
+export type ThreadOwnershipListResult = z.infer<typeof threadOwnershipListResultSchema>;

package/src/native-ui/shared-contracts/src/harness-permission-modes.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+import { hostThreadIdSchema } from "./ids.js";
+
+export const HARNESS_PERMISSION_MODE_ID_MAX_LENGTH = 128;
+export const HARNESS_PERMISSION_MODE_LABEL_MAX_LENGTH = 256;
+export const HARNESS_PERMISSION_MODE_DESCRIPTION_MAX_LENGTH = 1_024;
+export const HARNESS_PERMISSION_MODE_CATALOG_MAX_LENGTH = 32;
+
+const nonBlankTextSchema = z.string().refine((value) => value.trim().length > 0, {
+  message: "Value must not be empty or whitespace",
+});
+
+export const harnessPermissionModeIdSchema = nonBlankTextSchema
+  .max(HARNESS_PERMISSION_MODE_ID_MAX_LENGTH)
+  .regex(/^[A-Za-z0-9._~-]+$/u, "Permission Mode ID must use transport-safe characters")
+  .brand<"HarnessPermissionModeId">();
+
+export type HarnessPermissionModeId = z.infer<typeof harnessPermissionModeIdSchema>;
+
+export const harnessPermissionModeSchema = z
+  .object({
+    id: harnessPermissionModeIdSchema,
+    label: nonBlankTextSchema.max(HARNESS_PERMISSION_MODE_LABEL_MAX_LENGTH),
+    description: nonBlankTextSchema.max(HARNESS_PERMISSION_MODE_DESCRIPTION_MAX_LENGTH).optional(),
+    dangerous: z.boolean().optional(),
+  })
+  .strict();
+
+export type HarnessPermissionMode = z.infer<typeof harnessPermissionModeSchema>;
+
+export const harnessPermissionModeCatalogSchema = z
+  .object({
+    modes: z
+      .array(harnessPermissionModeSchema)
+      .min(1)
+      .max(HARNESS_PERMISSION_MODE_CATALOG_MAX_LENGTH),
+    defaultModeId: harnessPermissionModeIdSchema,
+  })
+  .strict()
+  .superRefine((catalog, context) => {
+    const ids = new Set<string>();
+    for (const [index, mode] of catalog.modes.entries()) {
+      if (ids.has(mode.id)) {
+        context.addIssue({
+          code: "custom",
+          message: "Permission Mode IDs must be unique",
+          path: ["modes", index, "id"],
+        });
+      }
+      ids.add(mode.id);
+    }
+    if (!ids.has(catalog.defaultModeId)) {
+      context.addIssue({
+        code: "custom",
+        message: "Default Permission Mode must exist in the catalog",
+        path: ["defaultModeId"],
+      });
+    }
+  });
+
+export type HarnessPermissionModeCatalog = z.infer<typeof harnessPermissionModeCatalogSchema>;
+
+export const threadPermissionModeSelectParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    permissionModeId: harnessPermissionModeIdSchema,
+  })
+  .strict();
+
+export type ThreadPermissionModeSelectParams = z.infer<
+  typeof threadPermissionModeSelectParamsSchema
+>;

package/src/native-ui/shared-contracts/src/harness-plugins.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+
+import { harnessIdSchema } from "./ids.js";
+
+export const HARNESS_PLUGIN_API_VERSION = 1;
+export const HARNESS_PLUGIN_MANIFEST_MAX_BYTES = 32 * 1024;
+export const HARNESS_PLUGIN_ICON_MAX_BYTES = 128 * 1024;
+export const HARNESS_PLUGIN_LIMIT = 128;
+
+/** Plugin identities are portable directory/route keys, not arbitrary Native Session IDs. */
+export const harnessPluginIdSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/u)
+  .refine((id) => id !== "codex", "The official Codex identity is reserved")
+  .pipe(harnessIdSchema);
+
+const relativeResourceSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .refine(
+    (value) =>
+      !/[\\\u0000:#?]/u.test(value) &&
+      !value.startsWith("/") &&
+      !value.split("/").some((part) => part === ".." || part === ""),
+    "Plugin resources must be relative paths inside the plugin",
+  );
+
+const documentationUrlSchema = z
+  .url()
+  .refine(
+    (value) => /^https:\/\/[^/?#@]+(?:[/?#]|$)/iu.test(value),
+    "Plugin documentation links must be credential-free HTTPS URLs",
+  );
+
+const pluginPresentationShape = {
+  id: harnessPluginIdSchema,
+  name: z.string().trim().min(1).max(128),
+  version: z.string().min(1).max(128),
+  links: z
+    .object({
+      documentation: documentationUrlSchema.optional(),
+      installation: documentationUrlSchema.optional(),
+    })
+    .strict()
+    .optional(),
+};
+
+/** A manifest is data only. It must be validated before importing any plugin code. */
+export const harnessPluginManifestSchema = z
+  .object({
+    manifestVersion: z.literal(1),
+    ...pluginPresentationShape,
+    adapterApiVersion: z.number().int().positive(),
+    entry: relativeResourceSchema,
+    icon: relativeResourceSchema.optional(),
+  })
+  .strict();
+export type HarnessPluginManifest = z.infer<typeof harnessPluginManifestSchema>;
+
+/** Images are presentation data; consumers must use an img, never inline markup. */
+export const harnessPluginIconSchema = z
+  .string()
+  .max(Math.ceil(HARNESS_PLUGIN_ICON_MAX_BYTES / 3) * 4 + 64)
+  .regex(/^data:image\/(?:png|jpeg|webp|svg\+xml);base64,[A-Za-z0-9+/]+={0,2}$/u);
+
+export const harnessPluginDescriptorSchema = z
+  .object({
+    ...pluginPresentationShape,
+    icon: harnessPluginIconSchema.optional(),
+  })
+  .strict();
+export type HarnessPluginDescriptor = z.infer<typeof harnessPluginDescriptorSchema>;
+
+export const harnessPluginListParamsSchema = z.object({}).strict();
+export const harnessPluginListResultSchema = z
+  .object({
+    plugins: z.array(harnessPluginDescriptorSchema).max(HARNESS_PLUGIN_LIMIT),
+  })
+  .strict();
+export type HarnessPluginListResult = z.infer<typeof harnessPluginListResultSchema>;
+
+/** Entries are explicit trust grants. Discovery alone never enables a plugin. */
+export const harnessPluginConfigurationSchema = z
+  .object({
+    version: z.literal(1),
+    enabled: z.array(harnessPluginIdSchema).max(HARNESS_PLUGIN_LIMIT),
+  })
+  .strict()
+  .refine((value) => new Set(value.enabled).size === value.enabled.length, {
+    message: "Enabled plugin IDs must be unique",
+    path: ["enabled"],
+  });
+export type HarnessPluginConfiguration = z.infer<typeof harnessPluginConfigurationSchema>;

package/src/native-ui/shared-contracts/src/harness-route.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+import { harnessModelRefSchema, harnessThinkingOptionIdSchema } from "./harness-models.js";
+import { harnessPermissionModeIdSchema } from "./harness-permission-modes.js";
+import { harnessPluginIdSchema } from "./harness-plugins.js";
+
+export const HARNESS_PLUGIN_ROUTE_PREFIX = "codexhost/plugin-v1@";
+const MAX_ROUTE_LENGTH = 4096;
+
+export const harnessPluginRouteSchema = z
+  .object({
+    harnessId: harnessPluginIdSchema,
+    model: harnessModelRefSchema.optional(),
+    thinkingOptionId: harnessThinkingOptionIdSchema.optional(),
+    permissionModeId: harnessPermissionModeIdSchema.optional(),
+  })
+  .strict();
+export type HarnessPluginRoute = z.infer<typeof harnessPluginRouteSchema>;
+
+/** All identity fields are transport-safe ASCII; no Node.js Buffer dependency. */
+export function encodeHarnessPluginRoute(route: HarnessPluginRoute): string {
+  const parsed = harnessPluginRouteSchema.parse(route);
+  const payload = [...JSON.stringify(parsed)]
+    .map((character) => character.charCodeAt(0).toString(16).padStart(2, "0"))
+    .join("");
+  return `${HARNESS_PLUGIN_ROUTE_PREFIX}${payload}`;
+}
+
+/** null means another protocol, not an invalid or unavailable external Harness. */
+export function decodeHarnessPluginRoute(value: unknown): HarnessPluginRoute | null {
+  if (typeof value !== "string" || !value.startsWith(HARNESS_PLUGIN_ROUTE_PREFIX)) return null;
+  const payload = value.slice(HARNESS_PLUGIN_ROUTE_PREFIX.length);
+  if (value.length > MAX_ROUTE_LENGTH || !/^(?:[a-f0-9]{2})+$/u.test(payload)) {
+    throw new Error("Invalid Harness plugin route");
+  }
+  try {
+    const json = payload.replace(/[a-f0-9]{2}/gu, (byte) =>
+      String.fromCharCode(Number.parseInt(byte, 16)),
+    );
+    const decoded = harnessPluginRouteSchema.parse(JSON.parse(json));
+    if (encodeHarnessPluginRoute(decoded) !== value)
+      throw new Error("Noncanonical Harness plugin route");
+    return decoded;
+  } catch {
+    throw new Error("Invalid Harness plugin route");
+  }
+}