harness-mix 0.1.0

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

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import {
+  HARNESS_SESSION_IMPORT_CWD_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_ID_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_TITLE_MAX_LENGTH,
+  HARNESS_SESSION_IMPORT_UPDATED_AT_MAX,
+  harnessSessionImportCandidateSchema,
+  harnessSessionImportSourcesParamsSchema,
+  harnessSessionImportSourcesResultSchema,
+  harnessSessionListParamsSchema,
+  harnessSessionListResultSchema,
+  harnessSessionImportParamsSchema,
+  harnessSessionImportResultSchema,
+} from "@codexhost/shared-contracts";
+
+const candidate = {
+  nativeSessionId: "pi-native",
+  title: null,
+  cwd: "/project",
+  updatedAt: 1,
+  running: null,
+};
+
+describe("Generic Harness Session import contracts", () => {
+  it("bounds individual pages and search inputs without limiting the total candidate count", () => {
+    expect(
+      harnessSessionListParamsSchema.parse({
+        harnessId: "pi",
+        query: " needle ",
+        offset: 100,
+        limit: 50,
+      }),
+    ).toEqual({ harnessId: "pi", query: "needle", offset: 100, limit: 50 });
+    expect(
+      harnessSessionListResultSchema.parse({ candidates: [candidate], total: 1_000_000 }),
+    ).toEqual({ candidates: [candidate], total: 1_000_000 });
+    for (const extra of [
+      { offset: -1 },
+      { offset: 0.5 },
+      { offset: Infinity },
+      { limit: 0 },
+      { limit: 1_001 },
+      { query: "a\0b" },
+      { query: "a".repeat(4097) },
+    ]) {
+      expect(harnessSessionListParamsSchema.safeParse({ harnessId: "pi", ...extra }).success).toBe(
+        false,
+      );
+    }
+    expect(harnessSessionListResultSchema.safeParse({ candidates: [candidate] }).success).toBe(
+      false,
+    );
+  });
+
+  it("accepts only bounded browser-safe Native Session metadata", () => {
+    const metadata = {
+      nativeSessionId: "native-session",
+      title: "Existing session",
+      updatedAt: 1_777_777_777_777,
+      cwd: "C:\\work\\project",
+      running: false,
+    };
+    expect(harnessSessionImportCandidateSchema.parse(metadata)).toEqual(metadata);
+    for (const invalid of [
+      { ...metadata, nativeSessionId: " " },
+      { ...metadata, nativeSessionId: "s".repeat(HARNESS_SESSION_IMPORT_ID_MAX_LENGTH + 1) },
+      { ...metadata, title: "t".repeat(HARNESS_SESSION_IMPORT_TITLE_MAX_LENGTH + 1) },
+      { ...metadata, cwd: "c".repeat(HARNESS_SESSION_IMPORT_CWD_MAX_LENGTH + 1) },
+      { ...metadata, updatedAt: HARNESS_SESSION_IMPORT_UPDATED_AT_MAX + 1 },
+      { ...metadata, transcript: [] },
+    ])
+      expect(harnessSessionImportCandidateSchema.safeParse(invalid).success).toBe(false);
+  });
+
+  it("supports unknown activity without inferring idle and uses explicit Harness-scoped requests", () => {
+    expect(harnessSessionImportCandidateSchema.parse(candidate).running).toBeNull();
+    expect(harnessSessionImportSourcesParamsSchema.parse({})).toEqual({});
+    expect(
+      harnessSessionImportSourcesResultSchema.parse({
+        harnesses: [{ harnessId: "pi", name: "Pi" }],
+      }),
+    ).toEqual({ harnesses: [{ harnessId: "pi", name: "Pi" }] });
+    expect(harnessSessionListParamsSchema.parse({ harnessId: "pi" })).toEqual({ harnessId: "pi" });
+    expect(
+      harnessSessionImportParamsSchema.parse({ harnessId: "pi", nativeSessionId: "pi-native" }),
+    ).toEqual({ harnessId: "pi", nativeSessionId: "pi-native" });
+    expect(harnessSessionImportResultSchema.parse({ threadId: "thread" })).toEqual({
+      threadId: "thread",
+    });
+  });
+
+  it("keeps native references, arbitrary actions and untrusted metadata out of the browser contract", () => {
+    for (const field of ["locator", "nativeRef", "transcript", "token", "sessionFile"]) {
+      expect(
+        harnessSessionImportCandidateSchema.safeParse({ ...candidate, [field]: "secret" }).success,
+      ).toBe(false);
+    }
+    for (const field of ["cwd", "locator", "title", "running", "environment", "command"]) {
+      expect(
+        harnessSessionImportParamsSchema.safeParse({
+          harnessId: "pi",
+          nativeSessionId: "pi-native",
+          [field]: "untrusted",
+        }).success,
+      ).toBe(false);
+    }
+    for (const params of [{}, { harnessId: "../pi" }, { harnessId: "pi", cwd: "/project" }]) {
+      expect(harnessSessionListParamsSchema.safeParse(params).success).toBe(false);
+    }
+    expect(harnessSessionImportSourcesParamsSchema.safeParse({ hostId: "remote" }).success).toBe(
+      false,
+    );
+    expect(
+      harnessSessionImportResultSchema.safeParse({ threadId: "thread", nativeRef: {} }).success,
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  harnessIdSchema,
+  hostInteractionIdSchema,
+  hostItemIdSchema,
+  hostThreadIdSchema,
+  hostTurnIdSchema,
+} from "../src/index.js";
+import type {
+  HarnessId,
+  HostInteractionId,
+  HostItemId,
+  HostThreadId,
+  HostTurnId,
+} from "../src/index.js";
+
+function assertBrandIsolation(
+  harnessId: HarnessId,
+  threadId: HostThreadId,
+  turnId: HostTurnId,
+  itemId: HostItemId,
+  interactionId: HostInteractionId,
+): void {
+  void harnessId;
+  void threadId;
+
+  // @ts-expect-error Host Turn IDs are not Host Thread IDs.
+  const invalidThreadId: HostThreadId = turnId;
+  // @ts-expect-error Host Turn IDs are not Host Item IDs.
+  const invalidItemId: HostItemId = turnId;
+  // @ts-expect-error Host Turn IDs are not Host Interaction IDs.
+  const invalidInteractionId: HostInteractionId = turnId;
+  // @ts-expect-error Harness IDs are not Host Thread IDs.
+  const invalidHarnessAssignment: HostThreadId = harnessId;
+
+  void invalidThreadId;
+  void invalidItemId;
+  void invalidInteractionId;
+  void invalidHarnessAssignment;
+  void itemId;
+  void interactionId;
+}
+
+void assertBrandIsolation;
+
+describe("opaque identifier contracts", () => {
+  const schemas = [
+    harnessIdSchema,
+    hostThreadIdSchema,
+    hostTurnIdSchema,
+    hostItemIdSchema,
+    hostInteractionIdSchema,
+  ] as const;
+
+  it("preserves opaque identifiers without assuming an encoding", () => {
+    const opaqueValue = "  Mixed Case/id:value  ";
+
+    for (const schema of schemas) {
+      expect(schema.parse(opaqueValue)).toBe(opaqueValue);
+    }
+  });
+
+  it.each(["", " ", "\t\r\n"])("rejects blank identifier %j", (value) => {
+    for (const schema of schemas) {
+      expect(schema.safeParse(value).success).toBe(false);
+    }
+  });
+});

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

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  codexhostErrorSchema,
+  harnessIdSchema,
+  harnessInspectionSchema,
+  harnessModelRefSchema,
+  harnessThinkingOptionSchema,
+  hostThreadIdSchema,
+  jsonRpcEnvelopeSchema,
+  jsonValueSchema,
+  nativeSessionRefSchema,
+  packageMetadata,
+  WORKSPACE_CONTRACT_VERSION,
+  workspaceContractVersionSchema,
+} from "@codexhost/shared-contracts";
+
+describe("shared-contracts public package", () => {
+  it("exports the unchanged workspace contract version", () => {
+    expect(WORKSPACE_CONTRACT_VERSION).toBe(1);
+    expect(workspaceContractVersionSchema.parse(1)).toBe(1);
+    expect(packageMetadata.contractVersion).toBe(1);
+  });
+
+  it("exports representative runtime contracts from the package root", () => {
+    expect(jsonValueSchema.parse({ public: true })).toEqual({ public: true });
+    expect(harnessIdSchema.parse("pi")).toBe("pi");
+    expect(harnessModelRefSchema.parse({ id: "pi-model-v1.synthetic" })).toEqual({
+      id: "pi-model-v1.synthetic",
+    });
+    expect(
+      harnessInspectionSchema.parse({
+        status: "ready",
+        catalog: {
+          models: [
+            {
+              ref: { id: "pi-model-v1.synthetic" },
+              label: "Synthetic",
+              supportedThinkingOptionIds: ["off", "high"],
+            },
+          ],
+          defaultModel: { id: "pi-model-v1.synthetic" },
+          thinkingOptions: [
+            { id: "off", label: "Off" },
+            { id: "high", label: "High" },
+          ],
+          defaultThinkingOptionId: "high",
+        },
+        capabilities: {
+          configuration: {
+            selectModel: true,
+            selectThinkingOption: true,
+            selectPermissionMode: false,
+          },
+          history: { fork: true, forkAcrossCwd: true, rollbackLastTurn: false },
+        },
+      }),
+    ).toMatchObject({ status: "ready" });
+    expect(harnessThinkingOptionSchema.parse({ id: "high", label: "High" })).toEqual({
+      id: "high",
+      label: "High",
+    });
+    expect(hostThreadIdSchema.parse("thread")).toBe("thread");
+    expect(jsonRpcEnvelopeSchema.parse({ id: 1, result: null })).toEqual({ id: 1, result: null });
+    expect(
+      nativeSessionRefSchema.parse({
+        harnessId: "pi",
+        nativeSessionId: "synthetic-session",
+        formatVersion: 1,
+      }),
+    ).toEqual({ harnessId: "pi", nativeSessionId: "synthetic-session", formatVersion: 1 });
+    expect(
+      codexhostErrorSchema.parse({
+        code: "SYNTHETIC",
+        message: "Synthetic error.",
+        retryable: false,
+      }),
+    ).toEqual({ code: "SYNTHETIC", message: "Synthetic error.", retryable: false });
+  });
+});

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

@@ -0,0 +1,177 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  jsonRpcEnvelopeSchema,
+  jsonRpcErrorResponseSchema,
+  jsonRpcNotificationSchema,
+  jsonRpcRequestSchema,
+  jsonRpcSuccessResponseSchema,
+} from "../src/index.js";
+import type { JsonRpcNotification, JsonRpcRequest } from "../src/index.js";
+
+interface GateAAppServerFixture {
+  requests: unknown[];
+  responseShapes: unknown[];
+}
+
+const fixturePath = resolve(
+  import.meta.dirname,
+  "../../../../fixtures/codex/official-app-server.fixture.json",
+);
+const gateAFixture = JSON.parse(readFileSync(fixturePath, "utf8")) as GateAAppServerFixture;
+
+function hasOwn(value: unknown, key: string): boolean {
+  return typeof value === "object" && value !== null && Object.hasOwn(value, key);
+}
+
+function assertExactEnvelopeFields(
+  notification: JsonRpcNotification,
+  request: JsonRpcRequest,
+): void {
+  // @ts-expect-error A Notification ID must be absent, not undefined.
+  const invalidNotification: JsonRpcNotification = { ...notification, id: undefined };
+  // @ts-expect-error A Request result must be absent, not undefined.
+  const invalidRequest: JsonRpcRequest = { ...request, result: undefined };
+
+  void invalidNotification;
+  void invalidRequest;
+}
+
+void assertExactEnvelopeFields;
+
+describe("Codex-compatible JSON-RPC envelope contracts", () => {
+  it("parses every reviewed Gate A envelope without requiring jsonrpc", () => {
+    for (const value of gateAFixture.requests) {
+      const parsed = hasOwn(value, "id")
+        ? jsonRpcRequestSchema.parse(value)
+        : jsonRpcNotificationSchema.parse(value);
+      expect(parsed).not.toHaveProperty("jsonrpc");
+      expect(jsonRpcEnvelopeSchema.parse(value)).toEqual(value);
+    }
+
+    for (const value of gateAFixture.responseShapes) {
+      const parsed = hasOwn(value, "result")
+        ? jsonRpcSuccessResponseSchema.parse(value)
+        : jsonRpcErrorResponseSchema.parse(value);
+      expect(parsed).not.toHaveProperty("jsonrpc");
+      expect(jsonRpcEnvelopeSchema.parse(value)).toEqual(value);
+    }
+  });
+
+  it("uses one request shape for both protocol directions and ID forms", () => {
+    const desktopRequest = {
+      jsonrpc: "2.0",
+      id: 7,
+      method: "desktop/request",
+      params: { source: "desktop" },
+    };
+    const serverRequest = {
+      id: "server-request-1",
+      method: "server/request",
+      params: ["opaque", 1],
+    };
+
+    expect(jsonRpcRequestSchema.parse(desktopRequest)).toEqual(desktopRequest);
+    expect(jsonRpcRequestSchema.parse(serverRequest)).toEqual(serverRequest);
+  });
+
+  it("accepts unknown methods and preserves envelope and error extensions", () => {
+    const request = {
+      id: "opaque-id",
+      method: "codexhost/future-method",
+      params: { supported: true },
+      traceContext: { sequence: 3 },
+    };
+    const errorResponse = {
+      id: 9,
+      error: {
+        code: -32_600,
+        message: "synthetic failure",
+        category: "future-category",
+      },
+      transportExtension: false,
+    };
+
+    expect(jsonRpcRequestSchema.parse(request)).toEqual(request);
+    expect(jsonRpcErrorResponseSchema.parse(errorResponse)).toEqual(errorResponse);
+  });
+
+  it("rejects non-JSON envelope and error extension values", () => {
+    const cyclicExtension: Record<string, unknown> = {};
+    cyclicExtension.self = cyclicExtension;
+    const requests = [
+      { id: 1, method: "bigint-extension", future: 1n },
+      { id: 2, method: "function-extension", future: () => 1 },
+      { id: 3, method: "cyclic-extension", future: cyclicExtension },
+    ];
+    const errorResponses = [
+      { id: 4, error: { code: -1, message: "bigint extension", future: 1n } },
+      { id: 5, error: { code: -1, message: "function extension", future: () => 1 } },
+      { id: 6, error: { code: -1, message: "cyclic extension", future: cyclicExtension } },
+    ];
+
+    for (const request of requests) {
+      expect(jsonRpcRequestSchema.safeParse(request).success).toBe(false);
+      expect(jsonRpcEnvelopeSchema.safeParse(request).success).toBe(false);
+    }
+    for (const response of errorResponses) {
+      expect(jsonRpcErrorResponseSchema.safeParse(response).success).toBe(false);
+      expect(jsonRpcEnvelopeSchema.safeParse(response).success).toBe(false);
+    }
+  });
+
+  it("preserves JSON round-trips for every envelope kind", () => {
+    const envelopes = [
+      { id: 1, method: "request", params: null },
+      { method: "notification", params: {} },
+      { id: "success", result: { values: [1, true, null] } },
+      { id: "failure", error: { code: -1, message: "failed", data: { retry: false } } },
+    ];
+
+    for (const envelope of envelopes) {
+      const parsed = jsonRpcEnvelopeSchema.parse(envelope);
+      expect(JSON.parse(JSON.stringify(parsed))).toEqual(parsed);
+    }
+  });
+
+  it("rejects explicit undefined in optional and forbidden fields", () => {
+    const values = [
+      { method: "notification", id: undefined },
+      { id: 1, method: "request", result: undefined },
+      { id: 2, method: "request", params: undefined },
+      { id: 3, result: null, error: undefined },
+      { id: 4, error: { code: -1, message: "failed", data: undefined } },
+    ];
+
+    expect(jsonRpcNotificationSchema.safeParse(values[0]).success).toBe(false);
+    expect(jsonRpcRequestSchema.safeParse(values[1]).success).toBe(false);
+    expect(jsonRpcRequestSchema.safeParse(values[2]).success).toBe(false);
+    expect(jsonRpcSuccessResponseSchema.safeParse(values[3]).success).toBe(false);
+    expect(jsonRpcErrorResponseSchema.safeParse(values[4]).success).toBe(false);
+    for (const value of values) {
+      expect(jsonRpcEnvelopeSchema.safeParse(value).success).toBe(false);
+    }
+  });
+
+  it.each([
+    { id: 1, result: {}, error: { code: -1, message: "conflict" } },
+    { id: 1, method: "response-cannot-have-method", result: {} },
+    { id: null, method: "null-id" },
+    { id: null, result: {} },
+    { id: 1, error: { message: "missing code" } },
+    { id: 1, error: { code: -1 } },
+    { id: 1, error: { code: -1.5, message: "fractional code" } },
+    { jsonrpc: "1.0", id: 1, method: "wrong-version" },
+  ])("rejects conflicting or malformed envelope %#", (value) => {
+    expect(jsonRpcEnvelopeSchema.safeParse(value).success).toBe(false);
+  });
+
+  it("rejects an ID on the notification-specific schema", () => {
+    expect(
+      jsonRpcNotificationSchema.safeParse({ id: 1, method: "not-a-notification" }).success,
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  jsonArraySchema,
+  jsonObjectSchema,
+  jsonPrimitiveSchema,
+  jsonValueSchema,
+} from "../src/index.js";
+
+describe("JSON value contracts", () => {
+  it("accepts nested JSON and preserves a JSON round-trip", () => {
+    const input = {
+      text: "value",
+      count: 3.5,
+      enabled: true,
+      empty: null,
+      nested: [1, { child: "ok" }, false],
+    };
+
+    const parsed = jsonValueSchema.parse(input);
+
+    expect(parsed).toEqual(input);
+    expect(JSON.parse(JSON.stringify(parsed))).toEqual(parsed);
+    expect(jsonPrimitiveSchema.parse(null)).toBeNull();
+    expect(jsonArraySchema.parse([1, "two"])).toEqual([1, "two"]);
+    expect(jsonObjectSchema.parse({ answer: 42 })).toEqual({ answer: 42 });
+  });
+
+  it("returns validation failures for circular objects and arrays", () => {
+    const cyclicObject: Record<string, unknown> = {};
+    cyclicObject.self = cyclicObject;
+    const cyclicArray: unknown[] = [];
+    cyclicArray.push(cyclicArray);
+
+    expect(jsonValueSchema.safeParse(cyclicObject).success).toBe(false);
+    expect(jsonObjectSchema.safeParse(cyclicObject).success).toBe(false);
+    expect(jsonValueSchema.safeParse(cyclicArray).success).toBe(false);
+    expect(jsonArraySchema.safeParse(cyclicArray).success).toBe(false);
+  });
+
+  it("accepts repeated references that do not form a cycle", () => {
+    const shared = { value: "shared" };
+    const input = { left: shared, right: shared };
+
+    expect(jsonValueSchema.parse(input)).toEqual(input);
+  });
+
+  it.each([
+    undefined,
+    1n,
+    () => "not JSON",
+    Symbol("not-json"),
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+    Number.NEGATIVE_INFINITY,
+    new Date(0),
+    new Map([["key", "value"]]),
+    { nested: undefined },
+  ])("rejects non-JSON runtime value %#", (value) => {
+    expect(jsonValueSchema.safeParse(value).success).toBe(false);
+  });
+});

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

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  nativeCheckpointRefSchema,
+  nativeSessionRefSchema,
+  nativeTurnRefSchema,
+} from "../src/index.js";
+import type { NativeCheckpointRef, NativeSessionRef, NativeTurnRef } from "../src/index.js";
+
+function assertNativeRefIsolation(
+  turnRef: NativeTurnRef,
+  checkpointRef: NativeCheckpointRef,
+): void {
+  // @ts-expect-error Stable Turn identity is not a fork Checkpoint.
+  const invalidCheckpoint: NativeCheckpointRef = turnRef;
+  // @ts-expect-error A fork Checkpoint is not stable Turn identity.
+  const invalidTurn: NativeTurnRef = checkpointRef;
+
+  void invalidCheckpoint;
+  void invalidTurn;
+}
+
+function assertExactOptionalLocators(
+  session: NativeSessionRef,
+  checkpoint: NativeCheckpointRef,
+): void {
+  // @ts-expect-error Explicit undefined is not an optional Session locator.
+  const invalidSession: NativeSessionRef = { ...session, locator: undefined };
+  // @ts-expect-error Explicit undefined is not an optional Checkpoint locator.
+  const invalidCheckpoint: NativeCheckpointRef = { ...checkpoint, locator: undefined };
+
+  void invalidSession;
+  void invalidCheckpoint;
+}
+
+void assertNativeRefIsolation;
+void assertExactOptionalLocators;
+
+const sessionRef = {
+  harnessId: "pi",
+  nativeSessionId: "synthetic-session",
+  locator: { storage: "adapter-managed", partition: 2 },
+  formatVersion: 1,
+} as const;
+const turnRef = {
+  harnessId: "pi",
+  nativeSessionId: "synthetic-session",
+  nativeTurnKey: "synthetic-turn",
+  formatVersion: 1,
+} as const;
+const checkpointRef = {
+  harnessId: "pi",
+  nativeSessionId: "synthetic-session",
+  checkpointId: "synthetic-checkpoint",
+  locator: ["adapter-managed", 3],
+  formatVersion: 1,
+} as const;
+
+describe("opaque native reference contracts", () => {
+  it("accepts and preserves all V1 reference kinds", () => {
+    expect(nativeSessionRefSchema.parse(sessionRef)).toEqual(sessionRef);
+    expect(nativeTurnRefSchema.parse(turnRef)).toEqual(turnRef);
+    expect(nativeCheckpointRefSchema.parse(checkpointRef)).toEqual(checkpointRef);
+  });
+
+  it("returns a validation failure for a circular locator", () => {
+    const locator: Record<string, unknown> = {};
+    locator.self = locator;
+
+    expect(nativeSessionRefSchema.safeParse({ ...sessionRef, locator }).success).toBe(false);
+  });
+
+  it.each([
+    [nativeSessionRefSchema, { ...sessionRef, formatVersion: 2 }],
+    [nativeSessionRefSchema, { ...sessionRef, nativeSessionId: "   " }],
+    [nativeSessionRefSchema, { ...sessionRef, extra: true }],
+    [nativeSessionRefSchema, { ...sessionRef, locator: undefined }],
+    [nativeSessionRefSchema, { ...sessionRef, locator: { invalid: undefined } }],
+    [nativeTurnRefSchema, { ...turnRef, nativeTurnKey: "\t" }],
+    [nativeTurnRefSchema, { ...turnRef, locator: {} }],
+    [nativeCheckpointRefSchema, { ...checkpointRef, checkpointId: "" }],
+    [nativeCheckpointRefSchema, { ...checkpointRef, locator: undefined }],
+    [nativeCheckpointRefSchema, { ...checkpointRef, locator: 1n }],
+  ])("rejects invalid or extended V1 reference %#", (schema, value) => {
+    expect(schema.safeParse(value).success).toBe(false);
+  });
+
+  it("uses only synthetic, non-sensitive reference examples", () => {
+    const serialized = JSON.stringify([sessionRef, turnRef, checkpointRef]);
+
+    expect(serialized).not.toMatch(
+      /transcript|prompt|tool.?output|diff|access.?token|api.?key|oauth|[A-Z]:\\|\/Users\//iu,
+    );
+  });
+});