opencara 0.110.0 → 0.112.1

package/dist/bin.js

@@ -152,6 +152,8 @@ var PairingStatusResponseSchema = z4.union([
 var PairingConfirmRequestSchema = z4.object({
   device_name: z4.string().min(1)
 });
+var HOST_PROTOCOL_VERSION = 1;
+var WS_CLOSE_PROTOCOL_TOO_OLD = 4400;
 var SystemInfoSchema = z4.object({
   os: z4.string(),
   // os.platform()
@@ -181,6 +183,12 @@ var HelloMessageSchema = z4.object({
   type: z4.literal("hello"),
   platform: z4.string(),
   version: z4.string(),
+  /**
+   * HOST_PROTOCOL_VERSION the device speaks. Absent from CLIs published
+   * before versioning existed — the server treats absent as 0 and gates
+   * on MIN_HOST_PROTOCOL_VERSION.
+   */
+  protocolVersion: z4.number().int().nonnegative().optional(),
   capabilities: z4.array(z4.string()).default([]),
   systemInfo: SystemInfoSchema.optional()
 });
@@ -212,12 +220,22 @@ var RunDoneSchema = z4.object({
 var HelloAckSchema = z4.object({
   type: z4.literal("hello-ack"),
   agentHostId: z4.string(),
-  deviceName: z4.string()
+  deviceName: z4.string(),
+  /**
+   * Server's HOST_PROTOCOL_VERSION. Optional so old servers (which don't
+   * send it) still satisfy new clients' parse; clients use it only to log
+   * a version-skew warning, never to gate.
+   */
+  protocolVersion: z4.number().int().nonnegative().optional()
 });
 var CancelJobSchema = z4.object({
   type: z4.literal("cancel"),
   runId: z4.string(),
-  reason: z4.enum(["user_stopped", "wave_cancelled"])
+  // `.catch()` — not a bare enum — so a future server that grows a new
+  // reason (e.g. "timeout") degrades on THIS client to "user_stopped"
+  // instead of failing the whole frame's parse and silently dropping the
+  // cancel, which left the job unkillable on pre-versioning CLIs.
+  reason: z4.enum(["user_stopped", "wave_cancelled"]).catch("user_stopped")
 });
 var PingSchema = z4.object({ type: z4.literal("ping") });
 var PongSchema = z4.object({ type: z4.literal("pong") });
@@ -318,6 +336,13 @@ var DeviceToServerMessageSchema = z4.union([
   PongSchema,
   AgentCallRequestSchema
 ]);
+var SERVER_TO_DEVICE_TYPES = /* @__PURE__ */ new Set([
+  "job",
+  "hello-ack",
+  "ping",
+  "agent-call-result",
+  "cancel"
+]);
 var HostRegisterRequestSchema = z4.object({
   hostId: z4.string(),
   hostName: z4.string(),
@@ -434,6 +459,23 @@ function sleep(ms) {
 
 // src/transport/ws-client.ts
 import WebSocket from "ws";
+function classifyServerFrame(raw) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return { kind: "malformed", error: "not JSON" };
+  }
+  const type = typeof json === "object" && json !== null && "type" in json ? json.type : void 0;
+  if (typeof type === "string" && !SERVER_TO_DEVICE_TYPES.has(type)) {
+    return { kind: "unknown-type", type };
+  }
+  const parsed = ServerToDeviceMessageSchema.safeParse(json);
+  if (!parsed.success) {
+    return { kind: "malformed", error: parsed.error.message };
+  }
+  return { kind: "ok", msg: parsed.data };
+}
 var HEARTBEAT_MS = 3e4;
 var WsClient = class {
   constructor(opts) {
@@ -445,6 +487,8 @@ var WsClient = class {
   backoff;
   heartbeat = null;
   stopped = false;
+  /** Unknown frame types already warned about (once per type, not per frame). */
+  warnedUnknownTypes = /* @__PURE__ */ new Set();
   start() {
     this.connect();
   }
@@ -473,18 +517,28 @@ var WsClient = class {
       this.opts.onOpen?.();
     });
     ws.on("message", (raw) => {
-      let parsed;
-      try {
-        parsed = ServerToDeviceMessageSchema.parse(JSON.parse(raw.toString()));
-      } catch (err) {
-        console.error("[ws] invalid frame", err);
+      const frame = classifyServerFrame(raw.toString());
+      if (frame.kind === "unknown-type") {
+        if (!this.warnedUnknownTypes.has(frame.type)) {
+          this.warnedUnknownTypes.add(frame.type);
+          console.warn(
+            `[ws] ignoring unknown frame type "${frame.type}" \u2014 the server is likely newer than this CLI; consider \`npm i -g opencara\``
+          );
+        }
+        return;
+      }
+      if (frame.kind === "malformed") {
+        console.error("[ws] invalid frame:", frame.error);
         return;
       }
-      this.opts.onMessage(parsed);
+      this.opts.onMessage(frame.msg);
     });
     ws.on("close", (code, reasonBuf) => {
       const reason = reasonBuf.toString();
       if (this.heartbeat) clearInterval(this.heartbeat);
+      if (code === WS_CLOSE_PROTOCOL_TOO_OLD) {
+        this.stopped = true;
+      }
       this.opts.onClose?.(code, reason);
       if (!this.stopped) this.scheduleReconnect();
     });
@@ -1302,11 +1356,21 @@ async function selectAcpModel(client, sessionId, requested, configOptions, onLog
   const values = (modelOption.options ?? []).map((o) => o.value);
   const target = matchModelValue(requested, values);
   if (!target) {
-    onLog(
-      "stderr",
-      `[acp] model "${requested}" not among available models [${values.join(", ")}]; using the default
+    try {
+      await client.setConfigOption({
+        sessionId,
+        configId: modelOption.id,
+        value: requested.trim()
+      });
+      onLog("stderr", `[acp] selected model ${requested.trim()} (freeform)
+`);
+    } catch {
+      onLog(
+        "stderr",
+        `[acp] model "${requested}" not among available models [${values.join(", ")}]; using the default
 `
-    );
+      );
+    }
     return;
   }
   if (modelOption.currentValue === target) return;
@@ -1402,7 +1466,7 @@ function resolveLocalAcpAdapter(command, args) {
 }
 
 // src/commands/run.ts
-var PKG_VERSION = "0.110.0";
+var PKG_VERSION = "0.112.1";
 var LOG_FLUSH_MS = 800;
 var MAX_CHUNK_SIZE = 4 * 1024;
 async function run(opts = {}) {
@@ -1422,6 +1486,7 @@ async function run(opts = {}) {
         type: "hello",
         platform: platform(),
         version: PKG_VERSION,
+        protocolVersion: HOST_PROTOCOL_VERSION,
         // Advertise ACP transport support. Pre-v0.30 devices reported
         // "agent-call" (the fenced-stdout-block protocol); since the
         // legacy path was removed, this version reports "acp" so the
@@ -1432,6 +1497,14 @@ async function run(opts = {}) {
     },
     onMessage: (msg) => handleServerMessage(msg, client, cfg),
     onClose: (code, reason) => {
+      if (code === WS_CLOSE_PROTOCOL_TOO_OLD) {
+        console.error(
+          `[opencara] this CLI's protocol is too old for the orchestrator: ${reason}`
+        );
+        console.error("[opencara] upgrade with: npm i -g opencara");
+        process.exitCode = 1;
+        return;
+      }
       console.log(`[opencara] disconnected (code=${code} reason="${reason}")`);
     }
   });
@@ -1442,6 +1515,11 @@ var acpControllers = /* @__PURE__ */ new Map();
 function handleServerMessage(msg, client, _cfg) {
   if (msg.type === "hello-ack") {
     console.log(`[opencara] acked as ${msg.deviceName} (${msg.agentHostId})`);
+    if (msg.protocolVersion !== void 0 && msg.protocolVersion !== HOST_PROTOCOL_VERSION) {
+      console.warn(
+        `[opencara] protocol skew: server v${msg.protocolVersion}, CLI v${HOST_PROTOCOL_VERSION}` + (msg.protocolVersion > HOST_PROTOCOL_VERSION ? " \u2014 consider `npm i -g opencara`" : "")
+      );
+    }
     return;
   }
   if (msg.type === "ping") return;

package/dist/claude-acp.js

@@ -102,6 +102,57 @@ function buildClaudeMcpConfig(servers) {
 }
 var sessions = /* @__PURE__ */ new Map();
 var extraClaudeArgs = [];
+function _setExtraClaudeArgsForTest(args) {
+  extraClaudeArgs = args;
+}
+function parseModelFromArgs(args) {
+  let model;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const eq = /^(?:--model|-m)=(.*)$/.exec(a);
+    if (eq && eq[1]) {
+      model = eq[1];
+      continue;
+    }
+    if ((a === "--model" || a === "-m") && args[i + 1] !== void 0) {
+      model = args[i + 1];
+      i++;
+    }
+  }
+  return model;
+}
+function modelConfigOptions(state) {
+  const effective = state.modelOverride ?? parseModelFromArgs(extraClaudeArgs);
+  if (!effective) return void 0;
+  return [
+    {
+      type: "select",
+      id: "model",
+      category: "model",
+      name: "Model",
+      currentValue: effective,
+      options: [{ value: effective }]
+    }
+  ];
+}
+function handleSetConfigOption(params) {
+  const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
+  const state = sessions.get(sessionId);
+  if (!state) {
+    throw new Error(`session/set_config_option: unknown session '${sessionId}'`);
+  }
+  if (params.configId !== "model") {
+    throw new Error(
+      `session/set_config_option: unknown configId '${String(params.configId)}'`
+    );
+  }
+  const value = typeof params.value === "string" ? params.value.trim() : "";
+  if (!value) {
+    throw new Error("session/set_config_option: value must be a non-empty string");
+  }
+  state.modelOverride = value;
+  return {};
+}
 var INSTRUCTIONS_FILE_MAX_BYTES = 64 * 1024;
 function resolveInstructionsFile(cwd, relative) {
   if (!relative || typeof relative !== "string" || relative.length === 0) {
@@ -260,6 +311,9 @@ async function runClaudeTurn(sessionId, state, promptText, images, permissionMod
     if (extraClaudeArgs.length > 0) {
       args.push(...extraClaudeArgs);
     }
+    if (state.modelOverride) {
+      args.push("--model", state.modelOverride);
+    }
     const child = spawn("claude", args, {
       cwd: state.cwd,
       env: process.env,
@@ -486,13 +540,15 @@ function handleNewSession(params) {
   const sessionId = randomUUID();
   const mcpServers = normalizeMcpServers(params.mcpServers);
   const instructionsFile = normalizeInstructionsFile(params.instructionsFile);
-  sessions.set(sessionId, {
+  const state = {
     cwd: params.cwd ?? process.cwd(),
     resume: false,
     ...mcpServers.length > 0 ? { mcpServers } : {},
     ...instructionsFile ? { instructionsFile } : {}
-  });
-  return { sessionId };
+  };
+  sessions.set(sessionId, state);
+  const configOptions = modelConfigOptions(state);
+  return { sessionId, ...configOptions ? { configOptions } : {} };
 }
 function handleLoadSession(params) {
   if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
@@ -500,13 +556,15 @@ function handleLoadSession(params) {
   }
   const mcpServers = normalizeMcpServers(params.mcpServers);
   const instructionsFile = normalizeInstructionsFile(params.instructionsFile);
-  sessions.set(params.sessionId, {
+  const state = {
     cwd: params.cwd ?? process.cwd(),
     resume: true,
     ...mcpServers.length > 0 ? { mcpServers } : {},
     ...instructionsFile ? { instructionsFile } : {}
-  });
-  return {};
+  };
+  sessions.set(params.sessionId, state);
+  const configOptions = modelConfigOptions(state);
+  return configOptions ? { configOptions } : {};
 }
 function normalizeInstructionsFile(raw) {
   if (typeof raw !== "string") return void 0;
@@ -591,6 +649,14 @@ async function dispatch(msg) {
       case "session/load":
         reply(req.id, handleLoadSession(req.params));
         return;
+      case "session/set_config_option":
+        reply(
+          req.id,
+          handleSetConfigOption(
+            req.params
+          )
+        );
+        return;
       case "session/prompt": {
         const result = await handlePrompt(req.params);
         reply(req.id, result);
@@ -605,7 +671,7 @@ async function dispatch(msg) {
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    const isParamsError = err instanceof Error && (message.startsWith("session/prompt:") || message.startsWith("session/load:"));
+    const isParamsError = err instanceof Error && (message.startsWith("session/prompt:") || message.startsWith("session/load:") || message.startsWith("session/set_config_option:"));
     replyError(
       req.id,
       isParamsError ? JSON_RPC_ERROR_INVALID_PARAMS : JSON_RPC_ERROR_INTERNAL,
@@ -614,11 +680,15 @@ async function dispatch(msg) {
   }
 }
 export {
+  _setExtraClaudeArgsForTest,
   buildStreamJsonInput,
   extraClaudeArgs,
   handleInitialize,
   handleLoadSession,
   handleNewSession,
+  handleSetConfigOption,
+  modelConfigOptions,
+  parseModelFromArgs,
   resolveInstructionsFile,
   sessions,
   translateClaudeEvent

package/dist/opencara-mcp.js

@@ -222,6 +222,12 @@ var HelloMessageSchema = z3.object({
   type: z3.literal("hello"),
   platform: z3.string(),
   version: z3.string(),
+  /**
+   * HOST_PROTOCOL_VERSION the device speaks. Absent from CLIs published
+   * before versioning existed — the server treats absent as 0 and gates
+   * on MIN_HOST_PROTOCOL_VERSION.
+   */
+  protocolVersion: z3.number().int().nonnegative().optional(),
   capabilities: z3.array(z3.string()).default([]),
   systemInfo: SystemInfoSchema.optional()
 });
@@ -253,12 +259,22 @@ var RunDoneSchema = z3.object({
 var HelloAckSchema = z3.object({
   type: z3.literal("hello-ack"),
   agentHostId: z3.string(),
-  deviceName: z3.string()
+  deviceName: z3.string(),
+  /**
+   * Server's HOST_PROTOCOL_VERSION. Optional so old servers (which don't
+   * send it) still satisfy new clients' parse; clients use it only to log
+   * a version-skew warning, never to gate.
+   */
+  protocolVersion: z3.number().int().nonnegative().optional()
 });
 var CancelJobSchema = z3.object({
   type: z3.literal("cancel"),
   runId: z3.string(),
-  reason: z3.enum(["user_stopped", "wave_cancelled"])
+  // `.catch()` — not a bare enum — so a future server that grows a new
+  // reason (e.g. "timeout") degrades on THIS client to "user_stopped"
+  // instead of failing the whole frame's parse and silently dropping the
+  // cancel, which left the job unkillable on pre-versioning CLIs.
+  reason: z3.enum(["user_stopped", "wave_cancelled"]).catch("user_stopped")
 });
 var PingSchema = z3.object({ type: z3.literal("ping") });
 var PongSchema = z3.object({ type: z3.literal("pong") });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencara",
-  "version": "0.110.0",
+  "version": "0.112.1",
   "description": "OpenCara agent-host CLI: register a machine as an agent host and run dispatched agents.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "dev": "tsx watch src/bin.ts",
     "start": "node dist/bin.js",
     "typecheck": "tsc -b",
-    "test": "node --import tsx --test --test-reporter=spec src/acp/__tests__/*.test.ts src/mcp/__tests__/*.test.ts src/runner/__tests__/*.test.ts src/bin/__tests__/*.test.ts src/commands/__tests__/*.test.ts",
+    "test": "node --import tsx --test --test-reporter=spec src/acp/__tests__/*.test.ts src/mcp/__tests__/*.test.ts src/runner/__tests__/*.test.ts src/bin/__tests__/*.test.ts src/commands/__tests__/*.test.ts src/transport/__tests__/*.test.ts",
     "acp:spike": "tsx src/acp/spike.ts",
     "mcp:smoke": "tsx src/mcp/smoke.ts",
     "clean": "rm -rf dist *.tsbuildinfo"