@linzumi/cli 0.0.1-beta → 0.0.2-beta

package/src/protocol.ts

@@ -0,0 +1,211 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-plan.md
+  Relationship: Defines the spec's first local runner protocol types for
+  Phoenix frames, Codex JSON-RPC envelopes, runner events, and controls.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Defines the channel-bound runner options used to bind one
+  local Codex process to a Kandan channel/thread and listener selector.
+
+- Date: 2026-04-25
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Defines the typed runner control that carries a Kandan
+  Approve/Deny decision back to the local Codex app-server approval request
+  without exposing a browser-to-runner socket.
+*/
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type JsonObject = { readonly [key: string]: JsonValue };
+
+export type JsonRpcId = string | number;
+
+export type JsonRpcRequest = {
+  readonly jsonrpc: "2.0";
+  readonly id: JsonRpcId;
+  readonly method: string;
+  readonly params?: JsonObject;
+};
+
+export type JsonRpcNotification = {
+  readonly jsonrpc: "2.0";
+  readonly method: string;
+  readonly params?: JsonObject;
+};
+
+export type JsonRpcResponse =
+  | {
+      readonly jsonrpc: "2.0";
+      readonly id: JsonRpcId;
+      readonly result: JsonValue;
+    }
+  | {
+      readonly jsonrpc: "2.0";
+      readonly id: JsonRpcId;
+      readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: JsonValue;
+      };
+    };
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+export type PhoenixFrame = readonly [
+  joinRef: string | null,
+  ref: string | null,
+  topic: string,
+  event: string,
+  payload: JsonValue
+];
+
+export type RunnerToKandanEvent =
+  | {
+      readonly kind: "instance_started";
+      readonly payload: JsonObject;
+    }
+  | {
+      readonly kind: "instance_stopped";
+      readonly payload: JsonObject;
+    }
+  | {
+      readonly kind: "codex_notification";
+      readonly payload: {
+        readonly instanceId: string;
+        readonly seq: number;
+        readonly method: string;
+        readonly params: JsonObject;
+        readonly receivedAt: string;
+      };
+    }
+  | {
+      readonly kind: "codex_request";
+      readonly payload: JsonObject;
+    }
+  | {
+      readonly kind: "codex_response";
+      readonly payload: JsonObject;
+    }
+  | {
+      readonly kind: "codex_error";
+      readonly payload: JsonObject;
+    }
+  | {
+      readonly kind: "heartbeat";
+      readonly payload: JsonObject;
+    };
+
+export type KandanControl =
+  | {
+      readonly type: "start_instance";
+      readonly instanceId?: string;
+      readonly cwd?: string;
+      readonly launchTui?: boolean;
+    }
+  | {
+      readonly type: "stop_instance";
+      readonly instanceId: string;
+    }
+  | {
+      readonly type: "kill_instance";
+      readonly instanceId: string;
+    }
+  | {
+      readonly type: "start_turn";
+      readonly instanceId: string;
+      readonly threadId: string;
+      readonly input: JsonValue[];
+    }
+  | {
+      readonly type: "steer_turn";
+      readonly instanceId: string;
+      readonly threadId: string;
+      readonly turnId: string;
+      readonly input: JsonValue[];
+    }
+  | {
+      readonly type: "interrupt_turn";
+      readonly instanceId: string;
+      readonly threadId: string;
+      readonly turnId?: string;
+    }
+  | {
+      readonly type: "interrupt_queued_messages";
+      readonly instanceId: string;
+      readonly threadId: string;
+      readonly throughSeq?: number;
+    }
+  | {
+      readonly type: "resolve_codex_approval_request";
+      readonly instanceId: string;
+      readonly threadId: string;
+      readonly sourceSeq: number;
+      readonly requestId: string;
+      readonly decision: "approve" | "deny";
+    }
+  | {
+      readonly type: "read_thread";
+      readonly instanceId: string;
+      readonly threadId: string;
+      readonly includeTurns?: boolean;
+    };
+
+export type KandanChannelSessionOptions = {
+  readonly workspaceSlug: string;
+  readonly channelSlug: string;
+  readonly kandanThreadId: string | undefined;
+  readonly listenUser: string;
+  readonly model?: string | undefined;
+  readonly reasoningEffort?: string | undefined;
+  readonly sandbox?: string | undefined;
+  readonly approvalPolicy?: string | undefined;
+};
+
+export function parseJsonObject(text: string): JsonObject {
+  const parsed = JSON.parse(text);
+
+  if (isJsonObject(parsed)) {
+    return parsed;
+  }
+
+  throw new Error("expected JSON object");
+}
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function requireString(value: unknown, label: string): string {
+  if (typeof value === "string" && value.trim() !== "") {
+    return value.trim();
+  }
+
+  throw new Error(`${label} must be a non-empty string`);
+}
+
+export function requirePositiveInteger(value: unknown, label: string): number {
+  if (Number.isInteger(value) && typeof value === "number" && value > 0) {
+    return value;
+  }
+
+  throw new Error(`${label} must be a positive integer`);
+}
+
+export function extractCodexIds(params: JsonObject): JsonObject {
+  const entries = [
+    ["threadId", params.threadId],
+    ["turnId", params.turnId],
+    ["itemId", params.itemId],
+    ["processId", params.processId],
+    ["requestId", params.requestId]
+  ].filter((entry): entry is [string, JsonValue] => entry[1] !== undefined);
+
+  return Object.fromEntries(entries) as JsonObject;
+}