@zuoyehaoduoa/wire 0.1.0

package/src/remote-protocol.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import {
+  RemoteMachineDescriptionSchema,
+  RemoteRpcEnvelopeSchema,
+  RemoteRpcResultEnvelopeSchema,
+} from "./remote-protocol";
+
+describe("remote-protocol", () => {
+  it("parses remote RPC envelopes", () => {
+    const parsed = RemoteRpcEnvelopeSchema.parse({
+      requestId: "req-1",
+      body: {
+        method: "GET",
+        path: "/api/projects",
+      },
+    });
+
+    expect(parsed.requestId).toBe("req-1");
+  });
+
+  it("parses success and error RPC results", () => {
+    const success = RemoteRpcResultEnvelopeSchema.parse({
+      ok: true,
+      requestId: "req-1",
+      body: { status: 200 },
+    });
+    const failure = RemoteRpcResultEnvelopeSchema.parse({
+      ok: false,
+      requestId: "req-2",
+      error: "boom",
+    });
+
+    expect(success.ok).toBe(true);
+    expect(failure.ok).toBe(false);
+  });
+
+  it("parses remote machine descriptions", () => {
+    const parsed = RemoteMachineDescriptionSchema.parse({
+      id: "machine-a",
+      metadata: {
+        machineId: "machine-a",
+        label: "MacBook",
+        host: "macbook.local",
+        platform: "darwin",
+        codexDir: "/Users/test/.codex",
+        cliVersion: "0.3.0",
+        rpcSigningPublicKey: "pk",
+      },
+      state: {
+        status: "running",
+        connectedAt: 1,
+        lastHeartbeatAt: 2,
+        localWebUrl: null,
+      },
+      active: true,
+      activeAt: 2,
+    });
+
+    expect(parsed.metadata.platform).toBe("darwin");
+  });
+});

package/src/remote-protocol.ts

@@ -0,0 +1,53 @@
+import * as z from "zod";
+
+export const RemoteRpcEnvelopeSchema = z.object({
+  requestId: z.string(),
+  body: z.unknown(),
+});
+export type RemoteRpcEnvelope = z.infer<typeof RemoteRpcEnvelopeSchema>;
+
+export const RemoteRpcResultEnvelopeSchema = z.discriminatedUnion("ok", [
+  z.object({
+    ok: z.literal(true),
+    requestId: z.string(),
+    body: z.unknown(),
+  }),
+  z.object({
+    ok: z.literal(false),
+    requestId: z.string(),
+    error: z.string(),
+  }),
+]);
+export type RemoteRpcResultEnvelope = z.infer<
+  typeof RemoteRpcResultEnvelopeSchema
+>;
+
+export const RemoteMachineMetadataSchema = z.object({
+  machineId: z.string(),
+  label: z.string(),
+  host: z.string(),
+  platform: z.string(),
+  codexDir: z.string(),
+  cliVersion: z.string(),
+  rpcSigningPublicKey: z.string().min(1),
+});
+export type RemoteMachineMetadata = z.infer<typeof RemoteMachineMetadataSchema>;
+
+export const RemoteMachineStateSchema = z.object({
+  status: z.enum(["running", "offline", "error"]),
+  connectedAt: z.number(),
+  lastHeartbeatAt: z.number(),
+  localWebUrl: z.string().nullable().optional(),
+});
+export type RemoteMachineState = z.infer<typeof RemoteMachineStateSchema>;
+
+export const RemoteMachineDescriptionSchema = z.object({
+  id: z.string(),
+  metadata: RemoteMachineMetadataSchema,
+  state: RemoteMachineStateSchema.nullable(),
+  active: z.boolean(),
+  activeAt: z.number(),
+});
+export type RemoteMachineDescription = z.infer<
+  typeof RemoteMachineDescriptionSchema
+>;

package/src/sessionProtocol.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from "vitest";
+import { createId } from "@paralleldrive/cuid2";
+import {
+  createEnvelope,
+  sessionEnvelopeSchema,
+  sessionEventSchema,
+  type SessionEvent,
+} from "./sessionProtocol";
+
+describe("session protocol schemas", () => {
+  it("accepts all supported event types", () => {
+    const events: SessionEvent[] = [
+      { t: "text", text: "hello" },
+      { t: "text", text: "thinking", thinking: true },
+      { t: "service", text: "**Service:** restarting MCP bridge" },
+      {
+        t: "tool-call-start",
+        call: "call-1",
+        name: "CodexBash",
+        title: "Run `ls`",
+        description: "Run `ls -la` in the repo root",
+        args: { command: "ls -la" },
+      },
+      { t: "tool-call-end", call: "call-1" },
+      { t: "file", ref: "upload-1", name: "report.txt", size: 1024 },
+      {
+        t: "file",
+        ref: "upload-2",
+        name: "image.png",
+        size: 2048,
+        image: { thumbhash: "abc", width: 100, height: 80 },
+      },
+      { t: "turn-start" },
+      { t: "start", title: "Research agent" },
+      { t: "turn-end", status: "completed" },
+      { t: "stop" },
+    ];
+
+    for (const event of events) {
+      expect(sessionEventSchema.safeParse(event).success).toBe(true);
+    }
+  });
+
+  it("rejects malformed events", () => {
+    expect(
+      sessionEventSchema.safeParse({ t: "tool-call-start", call: "1" }).success,
+    ).toBe(false);
+    expect(
+      sessionEventSchema.safeParse({ t: "file", ref: "x", name: "x" }).success,
+    ).toBe(false);
+    expect(
+      sessionEventSchema.safeParse({
+        t: "file",
+        ref: "x",
+        name: "x",
+        size: 1,
+        image: { width: 10, height: 10 },
+      }).success,
+    ).toBe(false);
+    expect(sessionEventSchema.safeParse({ t: "turn-end" }).success).toBe(false);
+    expect(
+      sessionEventSchema.safeParse({ t: "turn-end", status: "canceled" })
+        .success,
+    ).toBe(false);
+    expect(sessionEventSchema.safeParse({ t: "start", title: 1 }).success).toBe(
+      false,
+    );
+    expect(sessionEventSchema.safeParse({ t: "service" }).success).toBe(false);
+    expect(sessionEventSchema.safeParse({ t: "not-real" }).success).toBe(false);
+  });
+
+  it("validates envelopes that include turn/subagent", () => {
+    const subagent = createId();
+    const envelope = {
+      id: "msg-1",
+      time: 1234,
+      role: "agent" as const,
+      turn: "turn-1",
+      subagent,
+      ev: { t: "text", text: "hello" } as const,
+    };
+
+    const parsed = sessionEnvelopeSchema.safeParse(envelope);
+    expect(parsed.success).toBe(true);
+  });
+
+  it("rejects session role envelopes for text events", () => {
+    const parsed = sessionEnvelopeSchema.safeParse({
+      id: "msg-session-1",
+      role: "session",
+      ev: { t: "text", text: "shadow copy of user message" },
+    });
+
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects service from non-agent role", () => {
+    const parsed = sessionEnvelopeSchema.safeParse({
+      id: "msg-2",
+      role: "user",
+      ev: { t: "service", text: "internal event" },
+    });
+
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects start from non-agent role", () => {
+    const subagent = createId();
+    const parsed = sessionEnvelopeSchema.safeParse({
+      id: "msg-3",
+      role: "user",
+      subagent,
+      ev: { t: "start", title: "Research agent" },
+    });
+
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects non-cuid subagent values", () => {
+    const parsed = sessionEnvelopeSchema.safeParse({
+      id: "msg-4",
+      role: "agent",
+      turn: "turn-1",
+      subagent: "provider-tool-id",
+      ev: { t: "text", text: "hello" },
+    });
+
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe("createEnvelope", () => {
+  it("creates id by default", () => {
+    const envelope = createEnvelope("agent", { t: "turn-start" });
+    expect(typeof envelope.id).toBe("string");
+    expect(typeof envelope.time).toBe("number");
+    expect(envelope.id.length).toBeGreaterThan(0);
+    expect(envelope.role).toBe("agent");
+    expect(envelope.ev.t).toBe("turn-start");
+  });
+
+  it("respects explicit options", () => {
+    const subagent = createId();
+    const envelope = createEnvelope(
+      "agent",
+      { t: "tool-call-end", call: "call-1" },
+      {
+        id: "fixed-id",
+        time: 12345,
+        turn: "turn-1",
+        subagent,
+      },
+    );
+
+    expect(envelope).toEqual({
+      id: "fixed-id",
+      time: 12345,
+      role: "agent",
+      turn: "turn-1",
+      subagent,
+      ev: { t: "tool-call-end", call: "call-1" },
+    });
+  });
+
+  it("validates role/event compatibility", () => {
+    expect(() =>
+      createEnvelope("user", { t: "service", text: "internal event" }),
+    ).toThrow();
+  });
+});

package/src/sessionProtocol.ts

@@ -0,0 +1,141 @@
+import { createId, isCuid } from "@paralleldrive/cuid2";
+import * as z from "zod";
+
+export const sessionRoleSchema = z.enum(["user", "agent"]);
+export type SessionRole = z.infer<typeof sessionRoleSchema>;
+
+export const sessionTextEventSchema = z.object({
+  t: z.literal("text"),
+  text: z.string(),
+  thinking: z.boolean().optional(),
+});
+
+export const sessionServiceMessageEventSchema = z.object({
+  t: z.literal("service"),
+  text: z.string(),
+});
+
+export const sessionToolCallStartEventSchema = z.object({
+  t: z.literal("tool-call-start"),
+  call: z.string(),
+  name: z.string(),
+  title: z.string(),
+  description: z.string(),
+  args: z.record(z.string(), z.unknown()),
+});
+
+export const sessionToolCallEndEventSchema = z.object({
+  t: z.literal("tool-call-end"),
+  call: z.string(),
+});
+
+export const sessionFileEventSchema = z.object({
+  t: z.literal("file"),
+  ref: z.string(),
+  name: z.string(),
+  size: z.number(),
+  image: z
+    .object({
+      width: z.number(),
+      height: z.number(),
+      thumbhash: z.string(),
+    })
+    .optional(),
+});
+
+export const sessionTurnStartEventSchema = z.object({
+  t: z.literal("turn-start"),
+});
+
+export const sessionStartEventSchema = z.object({
+  t: z.literal("start"),
+  title: z.string().optional(),
+});
+
+export const sessionTurnEndStatusSchema = z.enum([
+  "completed",
+  "failed",
+  "cancelled",
+]);
+export type SessionTurnEndStatus = z.infer<typeof sessionTurnEndStatusSchema>;
+
+export const sessionTurnEndEventSchema = z.object({
+  t: z.literal("turn-end"),
+  status: sessionTurnEndStatusSchema,
+});
+
+export const sessionStopEventSchema = z.object({
+  t: z.literal("stop"),
+});
+
+export const sessionEventSchema = z.discriminatedUnion("t", [
+  sessionTextEventSchema,
+  sessionServiceMessageEventSchema,
+  sessionToolCallStartEventSchema,
+  sessionToolCallEndEventSchema,
+  sessionFileEventSchema,
+  sessionTurnStartEventSchema,
+  sessionStartEventSchema,
+  sessionTurnEndEventSchema,
+  sessionStopEventSchema,
+]);
+
+export type SessionEvent = z.infer<typeof sessionEventSchema>;
+
+export const sessionEnvelopeSchema = z
+  .object({
+    id: z.string(),
+    time: z.number(),
+    role: sessionRoleSchema,
+    turn: z.string().optional(),
+    subagent: z
+      .string()
+      .refine((value) => isCuid(value), {
+        message: "subagent must be a cuid2 value",
+      })
+      .optional(),
+    ev: sessionEventSchema,
+  })
+  .superRefine((envelope, ctx) => {
+    if (envelope.ev.t === "service" && envelope.role !== "agent") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'service events must use role "agent"',
+        path: ["role"],
+      });
+    }
+    if (
+      (envelope.ev.t === "start" || envelope.ev.t === "stop") &&
+      envelope.role !== "agent"
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${envelope.ev.t} events must use role "agent"`,
+        path: ["role"],
+      });
+    }
+  });
+
+export type SessionEnvelope = z.infer<typeof sessionEnvelopeSchema>;
+
+export type CreateEnvelopeOptions = {
+  id?: string;
+  time?: number;
+  turn?: string;
+  subagent?: string;
+};
+
+export function createEnvelope(
+  role: SessionRole,
+  ev: SessionEvent,
+  opts: CreateEnvelopeOptions = {},
+): SessionEnvelope {
+  return sessionEnvelopeSchema.parse({
+    id: opts.id ?? createId(),
+    time: opts.time ?? Date.now(),
+    role,
+    ...(opts.turn ? { turn: opts.turn } : {}),
+    ...(opts.subagent ? { subagent: opts.subagent } : {}),
+    ev,
+  });
+}