harness-mix 0.1.0

package/src/native-ui/shared-contracts/src/thread-harness-switch.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+import { hostThreadIdSchema } from "./ids.js";
+
+/**
+ * 原地切换 Harness：线程（会话历史/文件现场）保留在 Host 侧，仅更换底层原生会话。
+ * 切换后首轮发送由 Host 自动附带一次性上下文信封；note 会并入该信封。
+ */
+export const threadHarnessSwitchParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    harnessId: z.string().min(1),
+    note: z.string().max(2000).optional(),
+  })
+  .strict();
+
+export type ThreadHarnessSwitchParams = z.infer<typeof threadHarnessSwitchParamsSchema>;
+
+export const threadHarnessSwitchResultSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+  })
+  .strict();
+
+export type ThreadHarnessSwitchResult = z.infer<typeof threadHarnessSwitchResultSchema>;

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

@@ -0,0 +1,126 @@
+import { z } from "zod";
+
+import { hostThreadIdSchema } from "./ids.js";
+
+const nonNegativeSafeIntegerSchema = z.number().int().safe().nonnegative();
+const finiteNonNegativeNumberSchema = z.number().finite().nonnegative();
+const cacheHitRatePercentSchema = z.number().finite().min(0).max(100);
+
+export const threadUsageSnapshotSchema = z
+  .object({
+    inputTokens: nonNegativeSafeIntegerSchema.optional(),
+    cachedInputTokens: nonNegativeSafeIntegerSchema.optional(),
+    cacheWriteInputTokens: nonNegativeSafeIntegerSchema.optional(),
+    outputTokens: nonNegativeSafeIntegerSchema.optional(),
+    outputTokensPerSecond: finiteNonNegativeNumberSchema.optional(),
+    reasoningOutputTokens: nonNegativeSafeIntegerSchema.optional(),
+    totalTokens: nonNegativeSafeIntegerSchema.optional(),
+    totalCostUsd: finiteNonNegativeNumberSchema.optional(),
+    totalCredits: finiteNonNegativeNumberSchema.optional(),
+    contextUsagePercent: finiteNonNegativeNumberSchema.optional(),
+    cacheHitRatePercent: cacheHitRatePercentSchema.optional(),
+    contextWindowTokens: nonNegativeSafeIntegerSchema.optional(),
+    contextUsedTokens: nonNegativeSafeIntegerSchema.optional(),
+    planFiveHourUsedPercent: cacheHitRatePercentSchema.optional(),
+    planFiveHourResetsAtUnix: nonNegativeSafeIntegerSchema.optional(),
+    planSevenDayUsedPercent: cacheHitRatePercentSchema.optional(),
+    planSevenDayResetsAtUnix: nonNegativeSafeIntegerSchema.optional(),
+  })
+  .strict()
+  .superRefine((usage, context) => {
+    if (Object.keys(usage).length === 0) {
+      context.addIssue({ code: "custom", message: "Thread Usage must contain a reliable field" });
+    }
+    const hasContextUsed = usage.contextUsedTokens !== undefined;
+    const hasContextWindow = usage.contextWindowTokens !== undefined;
+    if (hasContextUsed !== hasContextWindow) {
+      context.addIssue({
+        code: "custom",
+        message: "Thread Usage context fields must be provided together",
+        path: [hasContextUsed ? "contextWindowTokens" : "contextUsedTokens"],
+      });
+    }
+    if (usage.contextWindowTokens === 0) {
+      context.addIssue({
+        code: "custom",
+        message: "Thread Usage contextWindowTokens must be greater than zero",
+        path: ["contextWindowTokens"],
+      });
+    }
+    if (
+      usage.planFiveHourResetsAtUnix !== undefined &&
+      usage.planFiveHourUsedPercent === undefined
+    ) {
+      context.addIssue({
+        code: "custom",
+        message:
+          "Thread Usage planFiveHourResetsAtUnix must be provided with planFiveHourUsedPercent",
+        path: ["planFiveHourResetsAtUnix"],
+      });
+    }
+    if (
+      usage.planSevenDayResetsAtUnix !== undefined &&
+      usage.planSevenDayUsedPercent === undefined
+    ) {
+      context.addIssue({
+        code: "custom",
+        message:
+          "Thread Usage planSevenDayResetsAtUnix must be provided with planSevenDayUsedPercent",
+        path: ["planSevenDayResetsAtUnix"],
+      });
+    }
+  });
+
+export type ThreadUsageSnapshot = z.infer<typeof threadUsageSnapshotSchema>;
+
+const usagePercentSchema = z.number().finite().min(0).max(100);
+
+export const accountCreditsProductUsageSchema = z
+  .object({
+    product: z.string().min(1),
+    usagePercent: usagePercentSchema,
+    resetsAt: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const accountResetCreditsSchema = z
+  .object({
+    availableCount: z.number().int().safe().positive(),
+    nextExpiresAt: z.string().min(1).optional(),
+    expiresAt: z.array(z.string().min(1)).min(1).max(32).optional(),
+  })
+  .strict();
+
+export const accountCreditsSnapshotSchema = z
+  .object({
+    /** Native label when the primary limit is scoped to a model or product group. */
+    label: z.string().min(1).optional(),
+    usedPercent: usagePercentSchema,
+    resetsAt: z.string().min(1).optional(),
+    periodType: z.enum(["weekly", "monthly", "five_hour", "seven_day", "unknown"]),
+    productUsage: z.array(accountCreditsProductUsageSchema).min(1).optional(),
+    resetCredits: accountResetCreditsSchema.optional(),
+  })
+  .strict();
+
+export type AccountResetCredits = z.infer<typeof accountResetCreditsSchema>;
+export type AccountCreditsSnapshot = z.infer<typeof accountCreditsSnapshotSchema>;
+
+export const threadUsageInspectionParamsSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    refresh: z.literal("exact").optional(),
+  })
+  .strict();
+
+export type ThreadUsageInspectionParams = z.infer<typeof threadUsageInspectionParamsSchema>;
+
+export const threadUsageInspectionSchema = z
+  .object({
+    threadId: hostThreadIdSchema,
+    usage: threadUsageSnapshotSchema.nullable(),
+    accountCredits: accountCreditsSnapshotSchema.optional(),
+  })
+  .strict();
+
+export type ThreadUsageInspection = z.infer<typeof threadUsageInspectionSchema>;

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+export const UPDATE_ERROR_MAX_LENGTH = 500;
+export const UPDATE_SEMVER_PATTERN =
+  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+
+export const updateSemanticVersionSchema = z.string().regex(UPDATE_SEMVER_PATTERN);
+export const updateInstallationSchema = z.enum(["npm", "windows-installer", "macos-dmg"]);
+export const updatePhaseSchema = z.enum([
+  "prepared",
+  "downloading",
+  "waiting-for-exit",
+  "installing",
+  "restarting",
+  "succeeded",
+  "failed",
+]);
+
+export const updateStatusSchema = z
+  .strictObject({
+    version: updateSemanticVersionSchema,
+    installation: updateInstallationSchema,
+    phase: updatePhaseSchema,
+    updatedAt: z.number().int().nonnegative(),
+    downloadedBytes: z.number().int().nonnegative().optional(),
+    totalBytes: z.number().int().positive().optional(),
+    error: z.string().min(1).max(UPDATE_ERROR_MAX_LENGTH).nullable(),
+  })
+  .superRefine((status, context) => {
+    if (
+      status.downloadedBytes !== undefined &&
+      status.totalBytes !== undefined &&
+      status.downloadedBytes > status.totalBytes
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["downloadedBytes"],
+        message: "downloadedBytes must not exceed totalBytes",
+      });
+    }
+  });
+
+export const updateEmptyParamsSchema = z.strictObject({});
+
+const githubReleaseNotesUrlSchema = z
+  .string()
+  .max(300)
+  .regex(
+    /^https:\/\/github\.com\/BytePioneer-AI\/codex-host\/releases\/tag\/v[0-9A-Za-z.+-]+$/u,
+    "release notes URL must identify a codexhost GitHub Release",
+  );
+
+export const updateCheckResultSchema = z.strictObject({
+  currentVersion: updateSemanticVersionSchema,
+  installation: updateInstallationSchema.nullable(),
+  latestVersion: updateSemanticVersionSchema.nullable(),
+  updateAvailable: z.boolean(),
+  installationAvailable: z.boolean(),
+  releaseNotes: z.string().min(1).max(20_000).nullable(),
+  releaseNotesUrl: githubReleaseNotesUrlSchema.nullable(),
+  status: updateStatusSchema.nullable(),
+  error: z.string().min(1).max(UPDATE_ERROR_MAX_LENGTH).nullable(),
+});
+
+export const updateStartResultSchema = z.strictObject({
+  status: updateStatusSchema,
+});
+
+export const updateStatusResultSchema = z.strictObject({
+  status: updateStatusSchema.nullable(),
+});
+
+export type UpdateInstallation = z.infer<typeof updateInstallationSchema>;
+export type UpdatePhase = z.infer<typeof updatePhaseSchema>;
+export type UpdateStatus = z.infer<typeof updateStatusSchema>;
+export type UpdateCheckResult = z.infer<typeof updateCheckResultSchema>;
+export type UpdateStartResult = z.infer<typeof updateStartResultSchema>;
+export type UpdateStatusResult = z.infer<typeof updateStatusResultSchema>;

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

@@ -0,0 +1 @@
+export const WORKSPACE_CONTRACT_VERSION = 1 as const;

package/src/native-ui/shared-contracts/test/browser-bundle.test.ts

@@ -0,0 +1,36 @@
+import { resolve } from "node:path";
+
+import { build } from "esbuild";
+import { describe, expect, it } from "vitest";
+
+describe("shared-contracts browser bundle", () => {
+  it("bundles representative public runtime contracts for a browser target", async () => {
+    const result = await build({
+      bundle: true,
+      format: "esm",
+      logLevel: "silent",
+      metafile: true,
+      platform: "browser",
+      target: "es2024",
+      write: false,
+      stdin: {
+        contents: [
+          'import { codexhostErrorSchema, deepSeekModernSessionImportParamsSchema, deepSeekModernSessionListResultSchema, harnessCommandDescriptorSchema, harnessInspectionSchema, harnessSessionImportCandidateSchema, harnessThinkingOptionSchema, hostThreadIdSchema, jsonRpcEnvelopeSchema, nativeSessionRefSchema, threadModelSelectParamsSchema, threadThinkingSelectParamsSchema } from "@codexhost/shared-contracts";',
+          "export const schemas = { codexhostErrorSchema, deepSeekModernSessionImportParamsSchema, deepSeekModernSessionListResultSchema, harnessCommandDescriptorSchema, harnessInspectionSchema, harnessSessionImportCandidateSchema, harnessThinkingOptionSchema, hostThreadIdSchema, jsonRpcEnvelopeSchema, nativeSessionRefSchema, threadModelSelectParamsSchema, threadThinkingSelectParamsSchema };",
+          'export { decodeHarnessPluginRoute, encodeHarnessPluginRoute, harnessPluginManifestSchema, harnessPluginListResultSchema } from "@codexhost/shared-contracts";',
+        ].join("\n"),
+        loader: "ts",
+        resolveDir: resolve(import.meta.dirname, "../../.."),
+        sourcefile: "shared-contracts-browser-smoke.ts",
+      },
+    });
+
+    expect(result.outputFiles).toHaveLength(1);
+    expect(result.outputFiles[0]?.text.length).toBeGreaterThan(0);
+
+    for (const inputPath of Object.keys(result.metafile.inputs)) {
+      expect(inputPath).not.toMatch(/(^|[/\\])node:/u);
+      expect(inputPath).not.toMatch(/electron|codex-sdk|claude-agent-sdk|pi-coding-agent/iu);
+    }
+  });
+});

package/src/native-ui/shared-contracts/test/deepseek-modern-sessions.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  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 "@codexhost/shared-contracts";
+
+const candidate = {
+  nativeSessionId: "session-1",
+  title: "Imported session",
+  updatedAt: 1_777_777_777_777,
+  cwd: "C:\\work\\project",
+  running: false,
+};
+
+describe("DeepSeek Modern Session import contracts", () => {
+  it("accepts only the fixed browser-safe request and result shapes", () => {
+    expect(deepSeekModernSessionListParamsSchema.parse({})).toEqual({});
+    expect(deepSeekModernSessionListResultSchema.parse({ candidates: [candidate] })).toEqual({
+      candidates: [candidate],
+    });
+    expect(deepSeekModernSessionImportParamsSchema.parse({ nativeSessionId: "session-1" })).toEqual(
+      { nativeSessionId: "session-1" },
+    );
+    expect(deepSeekModernSessionImportResultSchema.parse({ threadId: "thread-1" })).toEqual({
+      threadId: "thread-1",
+    });
+  });
+
+  it("rejects undeclared Native metadata, wire payloads, and credentials", () => {
+    for (const [schema, value] of [
+      [deepSeekModernSessionListParamsSchema, { cursor: "native-cursor" }],
+      [deepSeekModernSessionListResultSchema, { items: [candidate] }],
+      [deepSeekModernSessionCandidateSchema, { ...candidate, transcript: [] }],
+      [deepSeekModernSessionCandidateSchema, { ...candidate, token: "secret" }],
+      [deepSeekModernSessionImportParamsSchema, candidate],
+      [
+        deepSeekModernSessionImportResultSchema,
+        { threadId: "thread-1", nativeSessionId: "secret" },
+      ],
+    ] as const) {
+      expect(schema.safeParse(value).success).toBe(false);
+    }
+  });
+
+  it("enforces finite candidate and field bounds", () => {
+    for (const invalid of [
+      { ...candidate, nativeSessionId: " " },
+      { ...candidate, nativeSessionId: "session\0secret" },
+      { ...candidate, nativeSessionId: "s".repeat(DEEPSEEK_MODERN_SESSION_ID_MAX_LENGTH + 1) },
+      { ...candidate, title: " " },
+      { ...candidate, title: "t".repeat(DEEPSEEK_MODERN_SESSION_TITLE_MAX_LENGTH + 1) },
+      { ...candidate, cwd: " " },
+      { ...candidate, cwd: "C:\\work\0secret" },
+      { ...candidate, cwd: "c".repeat(DEEPSEEK_MODERN_SESSION_CWD_MAX_LENGTH + 1) },
+      { ...candidate, updatedAt: -1 },
+      { ...candidate, updatedAt: 1.5 },
+      { ...candidate, updatedAt: DEEPSEEK_MODERN_SESSION_UPDATED_AT_MAX + 1 },
+    ]) {
+      expect(deepSeekModernSessionCandidateSchema.safeParse(invalid).success).toBe(false);
+    }
+
+    expect(
+      deepSeekModernSessionListResultSchema.safeParse({
+        candidates: Array.from(
+          { length: DEEPSEEK_MODERN_SESSION_LIST_MAX_LENGTH + 1 },
+          (_, index) => ({ ...candidate, nativeSessionId: `session-${index}` }),
+        ),
+      }).success,
+    ).toBe(false);
+    expect(deepSeekModernSessionCandidateSchema.parse({ ...candidate, title: null })).toMatchObject(
+      {
+        title: null,
+      },
+    );
+  });
+
+  it("accepts no display metadata from an import caller", () => {
+    for (const key of [
+      "cwd",
+      "title",
+      "updatedAt",
+      "running",
+      "model",
+      "thinking",
+      "permission",
+      "preview",
+    ]) {
+      expect(
+        deepSeekModernSessionImportParamsSchema.safeParse({
+          nativeSessionId: "session-1",
+          [key]: "untrusted",
+        }).success,
+      ).toBe(false);
+    }
+    expect(
+      deepSeekModernSessionImportParamsSchema.safeParse({ nativeSessionId: " " }).success,
+    ).toBe(false);
+    expect(deepSeekModernSessionImportResultSchema.safeParse({ threadId: " " }).success).toBe(
+      false,
+    );
+    expect(
+      deepSeekModernSessionImportResultSchema.safeParse({ threadId: "thread\0secret" }).success,
+    ).toBe(false);
+    expect(
+      deepSeekModernSessionImportResultSchema.safeParse({
+        threadId: "t".repeat(DEEPSEEK_MODERN_HOST_THREAD_ID_MAX_LENGTH + 1),
+      }).success,
+    ).toBe(false);
+  });
+});

package/src/native-ui/shared-contracts/test/errors.test.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { describe, expect, it } from "vitest";
+
+import { codexhostErrorSchema } from "../src/index.js";
+import type { CodexhostError } from "../src/index.js";
+
+const mappingStoreErrorSchema = codexhostErrorSchema.safeExtend({
+  code: z.enum(["IO_ERROR", "MAPPING_CONFLICT"]),
+});
+
+function assertExactOptionalDiagnostic(error: CodexhostError): void {
+  // @ts-expect-error Explicit undefined is not an optional diagnostic.
+  const invalidError: CodexhostError = { ...error, diagnostic: undefined };
+  void invalidError;
+}
+
+void assertExactOptionalDiagnostic;
+
+describe("codexhost cross-boundary error contract", () => {
+  it("accepts the minimal shared structure without fixing a global code enum", () => {
+    const error = {
+      code: "adapterSpecificFailure",
+      message: "The operation could not be completed.",
+      retryable: true,
+      diagnostic: "Synthetic bounded diagnostic.",
+    };
+
+    expect(codexhostErrorSchema.parse(error)).toEqual(error);
+  });
+
+  it.each([
+    { message: "missing code", retryable: false },
+    { code: "", message: "empty code", retryable: false },
+    { code: "INVALID", message: "", retryable: false },
+    { code: "INVALID", message: "missing retryable" },
+    { code: "INVALID", message: "wrong retryable", retryable: "no" },
+    { code: "INVALID", message: "empty diagnostic", retryable: false, diagnostic: "" },
+    { code: "INVALID", message: "undefined diagnostic", retryable: false, diagnostic: undefined },
+    { code: "INVALID", message: "extended", retryable: false, extra: true },
+  ])("rejects incomplete or extended errors %#", (value) => {
+    expect(codexhostErrorSchema.safeParse(value).success).toBe(false);
+  });
+
+  it("allows owning packages to narrow code without changing the shared schema", () => {
+    const storeError = {
+      code: "IO_ERROR",
+      message: "The mapping could not be saved.",
+      retryable: true,
+    } as const;
+
+    expect(mappingStoreErrorSchema.parse(storeError)).toEqual(storeError);
+    expect(
+      mappingStoreErrorSchema.safeParse({ ...storeError, code: "adapterSpecificFailure" }).success,
+    ).toBe(false);
+    expect(
+      codexhostErrorSchema.safeParse({ ...storeError, code: "adapterSpecificFailure" }).success,
+    ).toBe(true);
+  });
+
+  it("uses only synthetic, bounded diagnostics", () => {
+    const serialized = JSON.stringify({
+      code: "SYNTHETIC",
+      message: "The synthetic operation failed.",
+      retryable: false,
+      diagnostic: "No external process was used.",
+    });
+
+    expect(serialized).not.toMatch(
+      /transcript|prompt|tool.?output|diff|access.?token|api.?key|oauth|[A-Z]:\\|\/Users\//iu,
+    );
+  });
+});

package/src/native-ui/shared-contracts/test/harness-commands.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  harnessCommandDescriptorSchema,
+  threadCommandExecuteParamsSchema,
+  threadCommandExecuteResultSchema,
+} from "@codexhost/shared-contracts";
+
+describe("Harness Command runtime contracts", () => {
+  it("round-trips strict text command input", () => {
+    const params = {
+      threadId: "thread-1",
+      commandId: "dsh.goal",
+      arguments: { text: "ship it" },
+    };
+
+    expect(threadCommandExecuteParamsSchema.parse(params)).toEqual(params);
+    expect(JSON.parse(JSON.stringify(threadCommandExecuteParamsSchema.parse(params)))).toEqual(
+      params,
+    );
+    expect(
+      harnessCommandDescriptorSchema.parse({
+        id: "dsh.goal",
+        invocation: "/dsh-goal",
+        label: "Goal",
+        argumentMode: "text",
+      }),
+    ).toEqual({
+      id: "dsh.goal",
+      invocation: "/dsh-goal",
+      label: "Goal",
+      argumentMode: "text",
+    });
+  });
+
+  it("rejects command image fields and capability declarations", () => {
+    expect(
+      threadCommandExecuteParamsSchema.safeParse({
+        threadId: "thread-1",
+        commandId: "dsh.goal",
+        images: [{ type: "image", url: "data:image/png;base64,AA==" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      harnessCommandDescriptorSchema.safeParse({
+        id: "dsh.goal",
+        invocation: "/dsh-goal",
+        label: "Goal",
+        argumentMode: "text",
+        acceptsImages: true,
+      }).success,
+    ).toBe(false);
+  });
+
+  it("keeps completion promises out of the RPC result", () => {
+    expect(
+      threadCommandExecuteResultSchema.safeParse({
+        accepted: true,
+        turnId: "turn-1",
+        completion: Promise.resolve({ status: "succeeded" }),
+      }).success,
+    ).toBe(false);
+  });
+});