@mycadet/cli 0.12.6-dev.202610082233.54244ee → 0.12.7

package/src/commands/client.ts

@@ -10,6 +10,7 @@ import {
   getActiveAssistant,
   lookupAssistantByIdentifier,
   resolveAssistant,
+  resolveConversationKey,
   saveAssistantEntry,
   type AssistantEntry,
 } from "../lib/assistant-config";
@@ -76,9 +77,47 @@ import { relaunchDetached } from "../lib/detached-process.js";
 import { probePort } from "../lib/port-probe.js";
 import { openBrowser } from "../lib/open-browser";
 import { findWebDistDir } from "../lib/web-dist.js";
+import { z } from "zod";
+
+const AssistantIdBodySchema = z.object({
+  assistantId: z.string().optional(),
+});
+
+const TokenBodySchema = z.object({ token: z.unknown() }).nullable();
+
+const SyncPlatformBodySchema = z.object({
+  syncPlatform: z.unknown().optional(),
+  platformAssistants: z.array(z.record(z.string(), z.unknown())).optional(),
+  organizationId: z.string().optional(),
+  rename: z
+    .object({ assistantId: z.string(), name: z.string() })
+    .optional(),
+  assistant: z.record(z.string(), z.unknown()).optional(),
+  activeAssistant: z.string().optional(),
+});
+
+const RemoteBodySchema = z.object({ remote: z.string().optional() });
+
+const UnpairBodySchema = z.object({
+  assistantId: z.unknown().optional(),
+  hashedDeviceId: z.unknown().optional(),
+});
+
+const DeviceBodySchema = z.object({
+  address: z.unknown().optional(),
+  handle: z.unknown().optional(),
+  name: z.unknown().optional(),
+});
+
+function errnoCode(error: unknown): string | undefined {
+  if (!(error instanceof Error)) return undefined;
+  if (!("code" in error) || typeof error.code !== "string") return undefined;
+  return error.code;
+}
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
+const SupportedInterfaceSchema = z.enum(SUPPORTED_INTERFACES);
 
 const ANSI = {
   reset: "\x1b[0m",
@@ -298,13 +337,14 @@ export function parseArgs(): ParsedArgs {
       assistantName = undefined;
     } else if ((flag === "--interface" || flag === "-i") && flagArgs[i + 1]) {
       const value = flagArgs[++i];
-      if (!(SUPPORTED_INTERFACES as readonly string[]).includes(value)) {
+      const parsedInterface = SupportedInterfaceSchema.safeParse(value);
+      if (!parsedInterface.success) {
         console.error(
           `Unknown interface '${value}'. Supported: ${SUPPORTED_INTERFACES.join(", ")}.`,
         );
         process.exit(1);
       }
-      interfaceId = value as SupportedInterface;
+      interfaceId = parsedInterface.data;
     }
   }
 
@@ -364,10 +404,6 @@ ${ANSI.bold}OPTIONS:${ANSI.reset}
     --disable-platform         Suppress all outbound platform API calls
     -h, --help                 Show this help message
 
-${ANSI.bold}DEFAULTS:${ANSI.reset}
-    Reads from ~/.cadet.lock.json (created by cadet hatch).
-    Override with flags above.
-
 ${ANSI.bold}EXAMPLES:${ANSI.reset}
     cadet client
     cadet client mycadet-foo
@@ -551,10 +587,11 @@ async function handleLocalEndpoints(
       return Response.json({ ok: true });
     }
     if (req.method === "POST") {
-      const body = (await req.json().catch(() => null)) as {
-        token?: unknown;
-      } | null;
-      const token = body?.token;
+      const parsed = TokenBodySchema.safeParse(
+        await req.json().catch(() => null),
+      );
+      const token =
+        parsed.success && parsed.data ? parsed.data.token : undefined;
       if (typeof token !== "string" || !/^[A-Za-z0-9]+$/.test(token)) {
         return Response.json(
           { ok: false, error: "Invalid token" },
@@ -578,9 +615,11 @@ async function handleLocalEndpoints(
       return new Response(null, { status: result.status });
     }
     if (req.method === "POST") {
-      let body: Record<string, unknown>;
+      let body: z.infer<typeof SyncPlatformBodySchema>;
       try {
-        body = (await req.json()) as Record<string, unknown>;
+        const parsed = SyncPlatformBodySchema.safeParse(await req.json());
+        if (!parsed.success) throw new Error("invalid body");
+        body = parsed.data;
       } catch {
         return Response.json(
           { ok: false, error: "Invalid JSON body" },
@@ -588,24 +627,23 @@ async function handleLocalEndpoints(
         );
       }
       let result;
-      if (body.syncPlatform && Array.isArray(body.platformAssistants)) {
+      if (body.syncPlatform && body.platformAssistants) {
         result = replacePlatformAssistants(
           lockfilePaths,
-          body.platformAssistants as Array<Record<string, unknown>>,
-          body.organizationId as string | undefined,
+          body.platformAssistants,
+          body.organizationId,
         );
-      } else if (body.rename && typeof body.rename === "object") {
-        const rename = body.rename as Record<string, unknown>;
+      } else if (body.rename) {
         result = renameLockfileAssistantIfPresent(
           lockfilePaths,
-          rename.assistantId as string,
-          rename.name as string,
+          body.rename.assistantId,
+          body.rename.name,
         );
       } else {
         result = upsertRendererLockfileAssistant(
           lockfilePaths,
-          body.assistant as Record<string, unknown>,
-          body.activeAssistant as string | undefined,
+          body.assistant ?? {},
+          body.activeAssistant,
         );
       }
       return Response.json(result, { status: result.ok ? 200 : result.status });
@@ -621,10 +659,8 @@ async function handleLocalEndpoints(
     const contentType = req.headers.get("content-type") ?? "";
     if (contentType.includes("json")) {
       try {
-        const body = (await req.json()) as {
-          remote?: string;
-        };
-        if (body.remote) remote = body.remote;
+        const parsed = RemoteBodySchema.safeParse(await req.json());
+        if (parsed.success && parsed.data.remote) remote = parsed.data.remote;
       } catch {
         return Response.json(
           { ok: false, error: "Invalid JSON body" },
@@ -659,8 +695,9 @@ async function handleLocalEndpoints(
 
     let assistantId: string | undefined;
     try {
-      const body = (await req.json()) as { assistantId?: string };
-      assistantId = body.assistantId;
+      const parsed = AssistantIdBodySchema.safeParse(await req.json());
+      if (!parsed.success) throw new Error("invalid body");
+      assistantId = parsed.data.assistantId;
     } catch {
       return Response.json(
         { ok: false, error: "Invalid JSON body" },
@@ -710,8 +747,9 @@ async function handleLocalEndpoints(
 
     let assistantId: string | undefined;
     try {
-      const body = (await req.json()) as { assistantId?: string };
-      assistantId = body.assistantId;
+      const parsed = AssistantIdBodySchema.safeParse(await req.json());
+      if (!parsed.success) throw new Error("invalid body");
+      assistantId = parsed.data.assistantId;
     } catch {
       return Response.json(
         { ok: false, error: "Invalid JSON body" },
@@ -746,7 +784,9 @@ async function handleLocalEndpoints(
 
     let body: { assistantId?: unknown; hashedDeviceId?: unknown };
     try {
-      body = (await req.json()) as typeof body;
+      const parsed = UnpairBodySchema.safeParse(await req.json());
+      if (!parsed.success) throw new Error("invalid body");
+      body = parsed.data;
     } catch {
       return Response.json(
         { ok: false, error: "Invalid JSON body" },
@@ -805,11 +845,9 @@ async function handleLocalEndpoints(
 
     let body: { address?: unknown; handle?: unknown; name?: unknown };
     try {
-      body = (await req.json()) as {
-        address?: unknown;
-        handle?: unknown;
-        name?: unknown;
-      };
+      const parsed = DeviceBodySchema.safeParse(await req.json());
+      if (!parsed.success) throw new Error("invalid body");
+      body = parsed.data;
     } catch {
       return Response.json(
         { ok: false, error: "Invalid JSON body" },
@@ -1047,10 +1085,11 @@ type WebFetchHandler = (
 ) => Promise<Response>;
 
 function isAddrInUse(err: unknown): boolean {
-  const e = err as { code?: string; message?: string } | undefined;
+  const code = errnoCode(err);
+  const message = err instanceof Error ? err.message : undefined;
   return (
-    e?.code === "EADDRINUSE" ||
-    /EADDRINUSE|address already in use/i.test(e?.message ?? "")
+    code === "EADDRINUSE" ||
+    /EADDRINUSE|address already in use/i.test(message ?? "")
   );
 }
 
@@ -1590,7 +1629,8 @@ export async function resolveFreshBearerToken(
   return refreshed?.accessToken ?? bearerToken;
 }
 
-export async function client(): Promise<void> {
+export const client = Object.assign(
+  async function client(): Promise<void> {
   const {
     runtimeUrl,
     assistantId,
@@ -1673,6 +1713,13 @@ export async function client(): Promise<void> {
     };
   }
 
+  // The CLI addresses its chat conversation by a client-minted uuid key
+  // (web's temp-client-id pattern) — resolve-or-mint once, persisted on the
+  // entry, so every session shares one conversation.
+  const lookup = lookupAssistantByIdentifier(assistantId);
+  const conversationKey =
+    lookup.status === "found" ? resolveConversationKey(lookup.entry) : undefined;
+
   const { renderChatApp } = await import("../components/DefaultMainScreen");
 
   process.stdout.write("\x1b[2J\x1b[H");
@@ -1688,6 +1735,9 @@ export async function client(): Promise<void> {
       console.log(`${ANSI.dim}Disconnected.${ANSI.reset}`);
       process.exit(0);
     },
-    { auth, assistantName, workspaceRoot },
+    { auth, assistantName, workspaceRoot, conversationKey },
   );
-}
+},
+  { description: "Connect to a hatched assistant" },
+);
+

package/src/commands/confirm.ts

@@ -103,7 +103,8 @@ function exitWithUsage(error: string): never {
   process.exit(1);
 }
 
-export async function confirm(): Promise<void> {
+export const confirm = Object.assign(
+  async function confirm(): Promise<void> {
   const rawArgs = process.argv.slice(3);
 
   if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
@@ -141,4 +142,7 @@ export async function confirm(): Promise<void> {
         : `Confirmation not accepted`,
     );
   }
-}
+},
+  { description: "Resolve a pending tool confirmation on an assistant" },
+);
+

package/src/commands/connect.ts

@@ -11,7 +11,8 @@ function printUsage(): void {
   );
 }
 
-export async function connect(): Promise<void> {
+export const connect = Object.assign(
+  async function connect(): Promise<void> {
   const args = process.argv.slice(3);
   const subcommand = args[0];
 
@@ -28,4 +29,7 @@ export async function connect(): Promise<void> {
   console.error(`Unknown subcommand: ${subcommand}`);
   printUsage();
   process.exit(1);
-}
+},
+  { description: "Pair with an assistant running on another machine [beta]" },
+);
+

package/src/commands/debug.ts

@@ -78,7 +78,8 @@ Examples:
 `);
 }
 
-export async function debugBundle(): Promise<void> {
+export const debug = Object.assign(
+  async function debug(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
     printHelp();
@@ -182,7 +183,10 @@ export async function debugBundle(): Promise<void> {
   console.log(
     "Debug bundle sent to Cadet. Staff can open it for the next 7 days.",
   );
-}
+},
+  { description: "Send Cadet staff a debug bundle of a self-hosted assistant" },
+);
+
 
 async function daemonAccessToken(
   entry: {

package/src/commands/devices.ts

@@ -279,7 +279,8 @@ async function revokeDevice(
   );
 }
 
-export async function devices(): Promise<void> {
+export const devices = Object.assign(
+  async function devices(): Promise<void> {
   const rawArgs = process.argv.slice(3);
 
   if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
@@ -311,4 +312,7 @@ export async function devices(): Promise<void> {
   const entry = resolveTargetAssistant(nameArg);
   const base = resolveLoopbackBase(entry);
   await listDevices(entry, base, jsonOutput);
-}
+},
+  { description: "List or revoke devices paired to a local assistant [beta]" },
+);
+

package/src/commands/events.ts

@@ -113,7 +113,8 @@ export function renderMarkdown(event: AssistantEvent): void {
   }
 }
 
-export async function events(): Promise<void> {
+export const events = Object.assign(
+  async function events(): Promise<void> {
   const rawArgs = process.argv.slice(3);
 
   if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
@@ -157,4 +158,7 @@ export async function events(): Promise<void> {
       renderMarkdown(event);
     }
   }
-}
+},
+  { description: "Stream events from a running assistant" },
+);
+

package/src/commands/exec.ts

@@ -1,5 +1,9 @@
+import { existsSync } from "fs";
+import { join } from "path";
+
 import { isManagedCloud } from "../lib/managed-cloud.js";
 import { spawn } from "child_process";
+import { red } from "../lib/color";
 
 import { resolveAssistant } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
@@ -26,7 +30,7 @@ function normalizeService(raw: string): ServiceName {
   const normalized = SERVICE_ALIASES[raw];
   if (!normalized) {
     console.error(
-      `Unknown service '${raw}'. Valid services: assistant, gateway, credential-executor`,
+      red(`Unknown service '${raw}'. Valid services: assistant, gateway, credential-executor`),
     );
     process.exit(1);
   }
@@ -48,7 +52,8 @@ function resolveDockerContainer(
   }
 }
 
-export async function exec(): Promise<void> {
+export const exec = Object.assign(
+  async function exec(): Promise<void> {
   const rawArgs = process.argv.slice(3);
 
   // Only check for help flags before the -- separator so that
@@ -103,8 +108,10 @@ export async function exec(): Promise<void> {
 
   if (dashDashIndex === -1) {
     console.error(
-      "Error: missing '--' separator before command.\n" +
-        "Usage: cadet exec [<name>] -- <command...>",
+      red(
+        "Error: missing '--' separator before command.\n" +
+          "Usage: cadet exec [<name>] -- <command...>",
+      ),
     );
     process.exit(1);
   }
@@ -112,7 +119,7 @@ export async function exec(): Promise<void> {
   const command = rawArgs.slice(dashDashIndex + 1);
 
   if (command.length === 0) {
-    console.error("Error: no command specified after '--'.");
+    console.error(red("Error: no command specified after '--'."));
     process.exit(1);
   }
 
@@ -130,7 +137,7 @@ export async function exec(): Promise<void> {
     } else if (preArgs[i] === "--timeout" && preArgs[i + 1]) {
       const secs = Number(preArgs[++i]);
       if (!Number.isFinite(secs) || secs < 0) {
-        console.error("Error: --timeout must be a non-negative number.");
+        console.error(red("Error: --timeout must be a non-negative number."));
         process.exit(1);
       }
       timeoutMs = secs === 0 ? 0 : secs * 1000;
@@ -147,9 +154,9 @@ export async function exec(): Promise<void> {
 
   if (!entry) {
     if (nameArg) {
-      console.error(`No assistant instance found with name '${nameArg}'.`);
+      console.error(red(`No assistant instance found with name '${nameArg}'.`));
     } else {
-      console.error("No assistant instance found. Run `cadet hatch` first.");
+      console.error(red("No assistant instance found. Run `cadet hatch` first."));
     }
     process.exit(1);
   }
@@ -157,9 +164,37 @@ export async function exec(): Promise<void> {
   const cloud = entry.cloud;
 
   if (cloud === "local") {
+    const instanceDir = entry.resources?.instanceDir;
+    if (!instanceDir) {
+      console.error(
+        red(
+          `Error: assistant '${entry.assistantId}' has no local instance directory recorded.`,
+        ),
+      );
+      process.exit(1);
+    }
+
+    const workspaceDir = join(instanceDir, "workspace");
+    const socketPath = join(workspaceDir, "assistant.sock");
+    if (!existsSync(socketPath)) {
+      console.error(
+        red(
+          `Error: the assistant runtime is not reachable (no socket at ${socketPath}).`,
+        ),
+      );
+      console.error(
+        red("Start it with `cadet wake`, or check `cadet ps` for its status."),
+      );
+      process.exit(1);
+    }
+
     const child = spawn(command[0], command.slice(1), {
       stdio: "inherit",
       windowsHide: true,
+      env: {
+        ...process.env,
+        CADET_WORKSPACE_DIR: workspaceDir,
+      },
     });
     await new Promise<void>((resolve) => {
       child.on("close", (code) => {
@@ -167,7 +202,7 @@ export async function exec(): Promise<void> {
         resolve();
       });
       child.on("error", (err) => {
-        console.error(`Error: ${err.message}`);
+        console.error(red(`Error: ${err.message}`));
         process.exitCode = 1;
         resolve();
       });
@@ -212,7 +247,7 @@ export async function exec(): Promise<void> {
     const token = readPlatformToken();
     if (!token) {
       console.error(
-        "Not logged in. Run `cadet login` first to authenticate with Cadet Cloud.",
+        red("Not logged in. Run `cadet login` first to authenticate with Cadet Cloud."),
       );
       process.exit(1);
     }
@@ -244,6 +279,9 @@ export async function exec(): Promise<void> {
     return;
   }
 
-  console.error(`Error: 'cadet exec' is not supported for ${cloud} instances.`);
+  console.error(red(`Error: 'cadet exec' is not supported for ${cloud} instances.`));
   process.exit(1);
-}
+},
+  { description: "Execute a command inside an assistant's container" },
+);
+

package/src/commands/flags.ts

@@ -203,7 +203,8 @@ async function setFlag(
   console.log(`Flag "${key}" set to ${value}`);
 }
 
-export async function flags(): Promise<void> {
+export const flags = Object.assign(
+  async function flags(): Promise<void> {
   const args = process.argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
@@ -248,4 +249,7 @@ export async function flags(): Promise<void> {
   console.error(`Unknown subcommand: ${subcommand}`);
   printHelp();
   process.exit(1);
-}
+},
+  { description: "Show and toggle feature flags" },
+);
+

package/src/commands/gateway.ts

@@ -9,7 +9,8 @@ function printUsage(): void {
   console.log("  token    Manage gateway authentication tokens");
 }
 
-export async function gateway(): Promise<void> {
+export const gateway = Object.assign(
+  async function gateway(): Promise<void> {
   const args = process.argv.slice(3);
   const subcommand = args[0];
 
@@ -26,4 +27,7 @@ export async function gateway(): Promise<void> {
   console.error(`Unknown subcommand: ${subcommand}`);
   printUsage();
   process.exit(1);
-}
+},
+  { description: "Gateway management commands" },
+);
+

package/src/commands/hatch.ts

@@ -222,7 +222,8 @@ function getCliVersion(): string {
   return cliPkg.version ?? "unknown";
 }
 
-export async function hatch(): Promise<void> {
+export const hatch = Object.assign(
+  async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@mycadet/cli v${cliVersion}`);
 
@@ -314,7 +315,10 @@ export async function hatch(): Promise<void> {
 
   console.error(`Error: Remote host '${remote}' is not yet supported.`);
   process.exit(1);
-}
+},
+  { description: "Create a new assistant instance" },
+);
+
 
 async function hatchCadetPlatform(): Promise<void> {
   const token = readPlatformToken();