@ishlabs/cli 0.9.0 → 0.11.0

package/dist/commands/chat.js

@@ -0,0 +1,655 @@
+/**
+ * ish chat — Configure chatbot endpoints and run chat-modality studies.
+ *
+ * The CLI's primary user is autonomous AI agents. Every verb here is
+ * scriptable: deterministic JSON outputs, no interactive prompts, no
+ * REPLs. Endpoint editing matches the editor dialog's semantics
+ * (full-replace via PUT) plus client-side field-shorthand flags for
+ * common one-line edits.
+ *
+ * Chat-modality studies are reached via the existing `ish study create
+ * --modality chat --endpoint <id>` extension; this file does NOT
+ * fork a parallel `chat run` verb tree.
+ */
+import { withClient, runInline, createClient, resolveWorkspace, resolveChatEndpoint, readFileOrStdin, confirmDestructive, } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { loadConfig, saveConfig } from "../config.js";
+import { ApiError } from "../lib/api-client.js";
+import { output } from "../lib/output.js";
+import { formatChatEndpointList, formatChatEndpointDetail, envelopeFromRow, } from "../lib/chat-endpoint-formatters.js";
+import { getChatEndpointTemplate, TEMPLATE_NAMES, } from "../lib/chat-endpoint-templates.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseEndpointConfigFile(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`--endpoint-config is not valid JSON: ${message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("--endpoint-config must be a JSON object.");
+    }
+    const obj = parsed;
+    // Envelope form: { id?, name, config, isTunnelBacked? } — extract .config.
+    if (obj.config && typeof obj.config === "object" && !Array.isArray(obj.config)) {
+        return {
+            config: obj.config,
+            envelopeName: typeof obj.name === "string" ? obj.name : undefined,
+            envelopeIsTunnelBacked: typeof obj.isTunnelBacked === "boolean" ? obj.isTunnelBacked : undefined,
+        };
+    }
+    // Bare ChatbotEndpointConfig
+    return { config: obj };
+}
+function urlLooksLocal(url) {
+    if (!url)
+        return false;
+    try {
+        const u = new URL(url);
+        const host = u.hostname.toLowerCase();
+        return host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0";
+    }
+    catch {
+        return false;
+    }
+}
+function inferredToConfig(inferred) {
+    const cfg = {
+        transport: inferred.transport,
+        outgoing: {
+            url: inferred.outgoing.url ?? undefined,
+            method: inferred.outgoing.method,
+            headers: inferred.outgoing.headers ?? {},
+            bodyTemplate: inferred.outgoing.bodyTemplate ?? {},
+            mode: inferred.outgoing.mode,
+            roleAliases: inferred.outgoing.roleAliases ?? {},
+        },
+        incoming: inferred.incoming,
+        asyncPoll: inferred.asyncPoll ?? null,
+    };
+    if (inferred.streaming) {
+        cfg.streaming = inferred.streaming;
+    }
+    return cfg;
+}
+async function tunnelGuard(client) {
+    try {
+        await client.get("/connect/active");
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            const e = new Error("This endpoint is configured to use a local tunnel, but no active tunnel was found. Run `ish connect <port>` first, then retry.");
+            e.error_kind = "TunnelInactive";
+            throw e;
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// list / get / create / update / delete / use
+// ---------------------------------------------------------------------------
+function attachChatEndpointCommands(parent) {
+    parent
+        .command("list")
+        .description("List chatbot endpoints in the current workspace")
+        .option("--workspace <id>", "Workspace ID")
+        .addHelpText("after", "\nExamples:\n  $ ish chat endpoint list\n  $ ish chat endpoint list --json | jq '.[].alias'")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const ws = resolveWorkspace(opts.workspace);
+            const data = await client.get(`/products/${ws}/chatbot-endpoints`);
+            // Tag aliases for downstream resolveId on subsequent commands.
+            for (const row of data) {
+                if (row.id)
+                    tagAlias(ALIAS_PREFIX.chatEndpoint, row.id);
+            }
+            formatChatEndpointList(data, globals.json, globals.verbose);
+        });
+    });
+    parent
+        .command("get")
+        .description("Get a chatbot endpoint by id (or the active endpoint)")
+        .argument("[id]", "Endpoint alias or UUID; defaults to the active endpoint")
+        .option("--endpoint <id>", "Endpoint alias or UUID (alternative to positional)")
+        .addHelpText("after", `
+With --verbose (or piped), emits the round-trippable envelope
+{id, name, isTunnelBacked, config} that update --endpoint-config accepts.
+
+Examples:
+  $ ish chat endpoint get ep-abc
+  $ ish chat endpoint get ep-abc --verbose | jq '.config' | ish chat endpoint update ep-abc --endpoint-config -`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveChatEndpoint(id, opts.endpoint);
+            const row = await client.get(`/chatbot-endpoints/${rid}`);
+            if (row.id)
+                tagAlias(ALIAS_PREFIX.chatEndpoint, row.id);
+            formatChatEndpointDetail(row, globals.json, globals.verbose);
+        });
+    });
+    parent
+        .command("create")
+        .description("Create a chatbot endpoint from a config file or stdin")
+        .requiredOption("--endpoint-config <file>", 'Path to JSON file (or "-" for stdin)')
+        .option("--name <name>", "Override the name from the config file")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--tunnel-backed", "Mark this endpoint as tunnel-backed (overrides envelope/config)")
+        .option("--no-tunnel-backed", "Force tunnel-backed off (overrides envelope/config)")
+        .addHelpText("after", `
+Accepts either a bare ChatbotEndpointConfig or an envelope { name, config, isTunnelBacked }.
+With --name, the flag wins over any envelope name. With --tunnel-backed / --no-tunnel-backed,
+the flag wins over any envelope/config isTunnelBacked.
+
+Examples:
+  $ ish chat endpoint create --endpoint-config ./bot.json --name "Production"
+  $ cat ./bot.json | ish chat endpoint create --endpoint-config - --tunnel-backed`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const ws = resolveWorkspace(opts.workspace);
+            const raw = await readFileOrStdin(opts.endpointConfig);
+            const { config, envelopeName, envelopeIsTunnelBacked } = parseEndpointConfigFile(raw);
+            // Name resolution: --name > envelope.name. Required by the backend.
+            const name = opts.name ?? envelopeName;
+            if (!name || name.length === 0) {
+                throw new Error("Endpoint requires a name. Pass --name <name> or include name in the envelope.");
+            }
+            // Tunnel-backed resolution: explicit flag > envelope > config.isTunnelBacked > false.
+            let isTunnelBacked;
+            if (opts.tunnelBacked === true)
+                isTunnelBacked = true;
+            else if (opts.tunnelBacked === false)
+                isTunnelBacked = false;
+            else if (envelopeIsTunnelBacked !== undefined)
+                isTunnelBacked = envelopeIsTunnelBacked;
+            else if (typeof config.isTunnelBacked === "boolean")
+                isTunnelBacked = config.isTunnelBacked;
+            else
+                isTunnelBacked = false;
+            const body = { name, config, isTunnelBacked };
+            // 30 s tolerates dev-backend cold-start (JWKS round-trip + warm
+            // connection pool) which can occasionally push a simple insert
+            // past the 15 s default.
+            const created = await client.post(`/products/${ws}/chatbot-endpoints`, body, { timeout: 30_000 });
+            if (created.id) {
+                const alias = tagAlias(ALIAS_PREFIX.chatEndpoint, created.id);
+                if (!globals.quiet)
+                    console.error(`Created endpoint ${alias}`);
+            }
+            formatChatEndpointDetail(created, globals.json, globals.verbose);
+        });
+    });
+    parent
+        .command("update")
+        .description("Update a chatbot endpoint (full replace via --endpoint-config, or per-field shorthand)")
+        .argument("[id]", "Endpoint alias or UUID; defaults to the active endpoint")
+        .option("--endpoint <id>", "Endpoint alias or UUID (alternative to positional)")
+        .option("--endpoint-config <file>", 'Replace config from JSON file (or "-" for stdin)')
+        .option("--name <name>", "Rename the endpoint")
+        .option("--url <url>", "Replace outgoing.url")
+        .option("--method <method>", "Replace outgoing.method (POST | PUT)")
+        .option("--mode <mode>", "Replace outgoing.mode (stateful | stateless)")
+        .option("--tunnel-backed", "Set isTunnelBacked=true")
+        .option("--no-tunnel-backed", "Set isTunnelBacked=false")
+        .addHelpText("after", `
+The dialog persists via PUT (full replace); per-field flags fetch the current
+endpoint, apply the override, and PUT the merged result. Field flags win over
+--endpoint-config on conflict. Combine flags freely:
+
+  $ ish chat endpoint update ep-abc --name "Production"
+  $ ish chat endpoint update ep-abc --url https://api.example.com/v2/chat
+  $ ish chat endpoint get ep-abc --verbose \\
+      | jq '.config.incoming.slots += [{"containerPath": "response.options", "kind": "alternatives"}]' \\
+      | ish chat endpoint update ep-abc --endpoint-config -`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveChatEndpoint(id, opts.endpoint);
+            const fieldFlagsSet = opts.name !== undefined
+                || opts.url !== undefined
+                || opts.method !== undefined
+                || opts.mode !== undefined
+                || opts.tunnelBacked !== undefined;
+            if (!opts.endpointConfig && !fieldFlagsSet) {
+                throw new Error("Pass --endpoint-config <file> or at least one field flag (--name, --url, --method, --mode, --tunnel-backed).");
+            }
+            // Validate enum-ish field flags client-side so the agent gets a clear
+            // error rather than a 422 from the backend.
+            if (opts.method !== undefined && !["POST", "PUT"].includes(opts.method)) {
+                throw new Error(`--method must be POST or PUT (got "${opts.method}").`);
+            }
+            if (opts.mode !== undefined && !["stateful", "stateless"].includes(opts.mode)) {
+                throw new Error(`--mode must be stateful or stateless (got "${opts.mode}").`);
+            }
+            // Lazy memoised fetch of the current endpoint. PUT is full-replace, so
+            // backfill paths (per-field shorthand, or --endpoint-config without
+            // name / isTunnelBacked supplied by the envelope) need the live row;
+            // memoising guarantees a single GET no matter how many backfills are
+            // needed and avoids a torn payload from two independent reads.
+            let cached = null;
+            const fetchCurrent = async () => cached ?? (cached = await client.get(`/chatbot-endpoints/${rid}`));
+            let baseConfig;
+            let baseName;
+            let baseIsTunnelBacked;
+            if (opts.endpointConfig) {
+                const raw = await readFileOrStdin(opts.endpointConfig);
+                const parsed = parseEndpointConfigFile(raw);
+                baseConfig = parsed.config;
+                if (parsed.envelopeName !== undefined) {
+                    baseName = parsed.envelopeName;
+                }
+                else if (opts.name !== undefined) {
+                    baseName = opts.name;
+                }
+                else {
+                    baseName = (await fetchCurrent()).name ?? "";
+                }
+                if (parsed.envelopeIsTunnelBacked !== undefined) {
+                    baseIsTunnelBacked = parsed.envelopeIsTunnelBacked;
+                }
+                else if (typeof baseConfig.isTunnelBacked === "boolean") {
+                    baseIsTunnelBacked = baseConfig.isTunnelBacked;
+                }
+                else {
+                    baseIsTunnelBacked = Boolean((await fetchCurrent()).isTunnelBacked);
+                }
+            }
+            else {
+                // No bulk file — fetch and apply per-field overrides.
+                const current = await fetchCurrent();
+                baseConfig = current.config ?? {};
+                baseName = current.name ?? "";
+                baseIsTunnelBacked = Boolean(current.isTunnelBacked);
+            }
+            // Apply per-field overrides (these win over the bulk file contents).
+            if (opts.name !== undefined)
+                baseName = opts.name;
+            if (opts.tunnelBacked === true)
+                baseIsTunnelBacked = true;
+            else if (opts.tunnelBacked === false)
+                baseIsTunnelBacked = false;
+            const outgoing = { ...(baseConfig.outgoing ?? {}) };
+            if (opts.url !== undefined)
+                outgoing.url = opts.url;
+            if (opts.method !== undefined)
+                outgoing.method = opts.method;
+            if (opts.mode !== undefined)
+                outgoing.mode = opts.mode;
+            const mergedConfig = {
+                ...baseConfig,
+                outgoing,
+            };
+            const body = {
+                name: baseName,
+                config: mergedConfig,
+                isTunnelBacked: baseIsTunnelBacked,
+            };
+            const updated = await client.put(`/chatbot-endpoints/${rid}`, body);
+            if (updated.id) {
+                const alias = tagAlias(ALIAS_PREFIX.chatEndpoint, updated.id);
+                if (!globals.quiet)
+                    console.error(`Updated endpoint ${alias}`);
+            }
+            formatChatEndpointDetail(updated, globals.json, globals.verbose);
+        });
+    });
+    parent
+        .command("delete")
+        .description("Delete a chatbot endpoint")
+        .argument("[id]", "Endpoint alias or UUID; defaults to the active endpoint")
+        .option("--endpoint <id>", "Endpoint alias or UUID (alternative to positional)")
+        .option("-y, --yes", "Skip confirmation prompt (required in --json or non-TTY contexts)")
+        .addHelpText("after", "\nExamples:\n  $ ish chat endpoint delete ep-abc --yes\n  $ ish chat endpoint delete --endpoint ep-abc --yes --json")
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveChatEndpoint(id, opts.endpoint);
+            await confirmDestructive(`Delete chatbot endpoint ${tagAlias(ALIAS_PREFIX.chatEndpoint, rid)}? This cannot be undone.`, { yes: opts.yes, json: globals.json });
+            await client.del(`/chatbot-endpoints/${rid}`);
+            // If the deleted endpoint was the active one, clear it.
+            const config = loadConfig();
+            if (config.chat_endpoint === rid) {
+                delete config.chat_endpoint;
+                saveConfig(config);
+            }
+            output({
+                success: true,
+                deleted: true,
+                id: rid,
+                alias: tagAlias(ALIAS_PREFIX.chatEndpoint, rid),
+            }, globals.json, { writePath: true });
+        });
+    });
+    parent
+        .command("use")
+        .description("Set the active chat endpoint (saved to ~/.ish/config.json)")
+        .argument("[id]", "Endpoint alias or UUID")
+        .option("--clear", "Remove the active chat endpoint from config")
+        .addHelpText("after", "\nExamples:\n  $ ish chat endpoint use ep-abc\n  $ ish chat endpoint use --clear")
+        .action(async (id, opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            if (opts.clear) {
+                const config = loadConfig();
+                delete config.chat_endpoint;
+                saveConfig(config);
+                if (!globals.quiet)
+                    console.error("Cleared active chat endpoint.");
+                return;
+            }
+            if (!id) {
+                throw new Error("Provide a chat endpoint alias or UUID, or use --clear.");
+            }
+            const rid = resolveId(id);
+            // Verify the endpoint exists before persisting so `use` matches the
+            // contract of `study use` / `ask use` (active id is always valid).
+            // 30 s tolerates dev-backend cold-start; the GET itself is cheap.
+            const client = await createClient(globals);
+            const row = await client.get(`/chatbot-endpoints/${rid}`, undefined, { timeout: 30_000 });
+            const config = loadConfig();
+            config.chat_endpoint = rid;
+            saveConfig(config);
+            if (!globals.quiet)
+                console.error(`Active chat endpoint set to "${row.name || rid}".`);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// init — auto-detect-shape onboarding
+// ---------------------------------------------------------------------------
+function attachChatEndpointInit(parent) {
+    parent
+        .command("init")
+        .description("Author an endpoint from a curl/JSON sample via auto-detect-shape, or from a known-good template")
+        .option("--from-curl <file>", 'Path to a curl example file (or "-" for stdin)')
+        .option("--from-json <file>", 'Path to a JSON request/response sample (or "-" for stdin)')
+        .option("--template <name>", `Start from a known-good template (one of: ${TEMPLATE_NAMES.join(", ")})`)
+        .option("--name <name>", "Save the inferred config under this display name")
+        .option("--no-save", "Infer the shape without persisting it")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--tunnel-backed", "Force isTunnelBacked=true (overrides localhost auto-detect)")
+        .option("--no-tunnel-backed", "Force isTunnelBacked=false (overrides localhost auto-detect)")
+        .addHelpText("after", `
+Pass exactly one of --from-curl, --from-json, or --template. --from-curl and
+--from-json accept "-" for stdin. --template <name> emits a hand-curated
+ChatbotEndpointConfig from public docs (no LLM round-trip), substituting
+{{secret:NAME}} placeholders for auth tokens.
+
+Available templates:
+${TEMPLATE_NAMES.map((n) => `  ${n}`).join("\n")}
+
+isTunnelBacked decision: explicit flag wins; else true when the inferred URL
+points at localhost / 127.0.0.1 / 0.0.0.0 (templates always default to false).
+
+Examples:
+  $ ish chat endpoint init --from-curl ./bot.curl --name my-bot
+  $ ish chat endpoint init --from-json ./shape.json --no-save | jq '.config'
+  $ ish chat endpoint init --template openai --name "OpenAI"
+  $ ish chat endpoint init --template anthropic --no-save | jq '.config'`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const sources = [opts.fromCurl, opts.fromJson, opts.template].filter((s) => s !== undefined).length;
+            if (sources === 0) {
+                throw new Error("Pass exactly one of --from-curl <file>, --from-json <file>, or --template <name>.");
+            }
+            if (sources > 1) {
+                throw new Error("Pass exactly one of --from-curl, --from-json, or --template — not multiple.");
+            }
+            const ws = resolveWorkspace(opts.workspace);
+            // Template path — fully local, no auto-detect call.
+            if (opts.template !== undefined) {
+                const tmpl = getChatEndpointTemplate(opts.template);
+                if (!tmpl) {
+                    throw new Error(`Unknown template "${opts.template}". Available: ${TEMPLATE_NAMES.join(", ")}.`);
+                }
+                const config = JSON.parse(JSON.stringify(tmpl.config));
+                const inferredUrl = (typeof config.outgoing?.url === "string" ? config.outgoing.url : null) ?? null;
+                const detectedTunnel = urlLooksLocal(inferredUrl);
+                let tunnelBacked;
+                if (opts.tunnelBacked === true)
+                    tunnelBacked = true;
+                else if (opts.tunnelBacked === false)
+                    tunnelBacked = false;
+                else
+                    tunnelBacked = detectedTunnel;
+                config.isTunnelBacked = tunnelBacked;
+                let endpointId = null;
+                let endpointAlias = null;
+                let saved = false;
+                const saveExplicitlyDisabled = opts.save === false;
+                const proposedName = opts.name ?? `template:${tmpl.name}`;
+                if (!saveExplicitlyDisabled) {
+                    const created = await client.post(`/products/${ws}/chatbot-endpoints`, { name: proposedName, config, isTunnelBacked: tunnelBacked });
+                    if (created.id) {
+                        endpointId = created.id;
+                        endpointAlias = tagAlias(ALIAS_PREFIX.chatEndpoint, created.id);
+                        saved = true;
+                        if (!globals.quiet) {
+                            console.error(`Created endpoint ${endpointAlias}`);
+                        }
+                    }
+                }
+                const result = {
+                    success: true,
+                    saved,
+                    endpoint_id: endpointId,
+                    alias: endpointAlias,
+                    config,
+                    tunnel_backed: tunnelBacked,
+                    tunnel_backed_detected: detectedTunnel,
+                    template: tmpl.name,
+                    description: tmpl.description,
+                    warnings: [
+                        "Templates use {{secret:NAME}} placeholders for auth — set the matching workspace secrets via `ish secret set` before testing.",
+                    ],
+                };
+                output(result, globals.json, { writePath: true });
+                return;
+            }
+            // Auto-detect path (curl or JSON paste).
+            const path = (opts.fromCurl ?? opts.fromJson);
+            const paste = await readFileOrStdin(path);
+            const inferRes = await client.post(`/products/${ws}/chat/auto-detect-shape`, { paste }, { timeout: 120_000 });
+            if (!inferRes.ok) {
+                // Surface as a structured failure envelope on stdout AND throw so
+                // the wrapper sets a non-zero exit. The thrown Error carries the
+                // shape's error_kind for the agent to branch on.
+                const err = new Error(inferRes.errorMessage ?? "auto-detect-shape failed.");
+                err.error_kind = inferRes.errorKind;
+                throw err;
+            }
+            const inferred = inferRes.inferred;
+            const config = inferredToConfig(inferred);
+            const inferredUrl = inferred.outgoing.url ?? null;
+            const detectedTunnel = urlLooksLocal(inferredUrl);
+            let tunnelBacked;
+            if (opts.tunnelBacked === true)
+                tunnelBacked = true;
+            else if (opts.tunnelBacked === false)
+                tunnelBacked = false;
+            else
+                tunnelBacked = detectedTunnel;
+            config.isTunnelBacked = tunnelBacked;
+            const warnings = [];
+            if (!inferredUrl) {
+                warnings.push("Inferred shape has no URL; set --url before testing.");
+            }
+            if (inferred.confidence !== "high") {
+                warnings.push(`Auto-detect confidence: ${inferred.confidence} — verify the shape before running.`);
+            }
+            // Decide whether to save. --no-save short-circuits; otherwise save when
+            // a name is available (--name wins; else fall back to the inferred
+            // URL host as a sensible default — agents can rename later).
+            let inferredHost;
+            if (inferredUrl) {
+                try {
+                    inferredHost = new URL(inferredUrl).hostname || undefined;
+                }
+                catch {
+                    inferredHost = undefined;
+                }
+            }
+            let endpointId = null;
+            let endpointAlias = null;
+            let saved = false;
+            const saveExplicitlyDisabled = opts.save === false;
+            const fallbackName = inferredHost
+                ? `inferred:${inferredHost}`
+                : (inferredUrl ? `inferred:${inferredUrl}` : undefined);
+            const proposedName = opts.name ?? fallbackName;
+            if (!saveExplicitlyDisabled && proposedName) {
+                const created = await client.post(`/products/${ws}/chatbot-endpoints`, { name: proposedName, config, isTunnelBacked: tunnelBacked });
+                if (created.id) {
+                    endpointId = created.id;
+                    endpointAlias = tagAlias(ALIAS_PREFIX.chatEndpoint, created.id);
+                    saved = true;
+                    if (!globals.quiet) {
+                        console.error(`Created endpoint ${endpointAlias}`);
+                    }
+                }
+            }
+            const missingSignals = Array.isArray(inferred.missingSignals)
+                ? inferred.missingSignals
+                : [];
+            const result = {
+                success: true,
+                saved,
+                endpoint_id: endpointId,
+                alias: endpointAlias,
+                config,
+                tunnel_backed: tunnelBacked,
+                tunnel_backed_detected: detectedTunnel,
+                confidence: inferred.confidence,
+                explanation: inferred.explanation,
+                missingSignals,
+                warnings,
+            };
+            output(result, globals.json, { writePath: true });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// test — single-turn smoke test
+// ---------------------------------------------------------------------------
+function attachChatEndpointTest(parent) {
+    parent
+        .command("test")
+        .description("Send one message to a saved endpoint and return the bot's reply")
+        .argument("[endpoint-id]", "Endpoint alias or UUID; defaults to the active endpoint")
+        .option("--endpoint <id>", "Endpoint alias or UUID (alternative to positional)")
+        .option("-m, --message <text>", "Message to send", "Hello")
+        .option("--conversation-id <id>", "Thread state across multiple invocations (stateful endpoints)")
+        .option("--tester <json>", "Tester persona JSON ({name, locale, ...}) exposed via {{tester.*}}")
+        .option("--include-request", "Include the dispatched POST body in the output")
+        .option("--workspace <id>", "Workspace ID")
+        .addHelpText("after", `
+Pre-flight: when the saved endpoint is tunnel-backed, GETs /connect/active and
+exits 5 with error_kind=TunnelInactive on miss.
+
+Examples:
+  $ ish chat endpoint test ep-abc -m "Hello"
+  $ ish chat endpoint test ep-abc -m "Yes" --conversation-id conv-123
+  $ ish chat endpoint test ep-abc --tester '{"name":"Pat","locale":"en-US"}'`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const ws = resolveWorkspace(opts.workspace);
+            const rid = resolveChatEndpoint(id, opts.endpoint);
+            // 30 s tolerates dev-backend cold-start; the GET itself is cheap.
+            const saved = await client.get(`/chatbot-endpoints/${rid}`, undefined, { timeout: 30_000 });
+            if (saved.id)
+                tagAlias(ALIAS_PREFIX.chatEndpoint, saved.id);
+            if (saved.isTunnelBacked) {
+                await tunnelGuard(client);
+            }
+            let testerBlock;
+            if (opts.tester !== undefined) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(opts.tester);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    throw new Error(`--tester must be a JSON object: ${message}`);
+                }
+                if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    throw new Error("--tester must be a JSON object.");
+                }
+                testerBlock = parsed;
+            }
+            // The backend test-endpoint route accepts the same envelope shape the
+            // editor sends — drop the saved config in unchanged, with isTunnelBacked
+            // hoisted onto the config so the route's coercion sees it.
+            const endpointPayload = {
+                ...(saved.config ?? {}),
+                isTunnelBacked: saved.isTunnelBacked,
+            };
+            const body = {
+                endpoint: endpointPayload,
+                sample_message: opts.message,
+            };
+            if (testerBlock)
+                body.tester = testerBlock;
+            if (opts.conversationId)
+                body.conversation_id = opts.conversationId;
+            const res = await client.post(`/products/${ws}/chat/test-endpoint`, body, { timeout: 90_000 });
+            if (!res.ok) {
+                const err = new Error(res.error_message ?? "chat endpoint test failed.");
+                err.error_kind = res.error_kind;
+                // Surface dispatched body on failure too when requested.
+                if (opts.includeRequest && res.dispatched_body !== undefined) {
+                    err.dispatched_body = res.dispatched_body;
+                }
+                throw err;
+            }
+            const reply = res.bot_reply;
+            const result = {
+                success: true,
+                text: reply.text,
+                conversation_id: reply.conversation_id ?? null,
+                slots: reply.slots ?? [],
+                references: reply.references ?? [],
+                bot_latency_ms: reply.bot_latency_ms ?? null,
+                end_of_conversation: reply.end_of_conversation ?? false,
+                detected_affordances: res.detected_affordances ?? null,
+            };
+            if (opts.includeRequest) {
+                result.dispatched_body = res.dispatched_body ?? null;
+            }
+            output(result, globals.json);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+export function registerChatCommand(program) {
+    const chat = program
+        .command("chat")
+        .description("Author chatbot endpoints and run chat-modality studies")
+        .addHelpText("after", `
+Use \`ish chat endpoint\` to configure the bot the persona will talk to.
+Run a chat study via the existing flow:
+
+  $ ish chat endpoint init --from-curl ./bot.curl --name my-bot
+  $ ish chat endpoint test my-bot -m "Hello"
+  $ ish study create --modality chat --endpoint my-bot --assignment "Sign up:Try to sign up"
+  $ ish study run --study <study-id> --sample 5 --wait
+
+Concept pages: ish docs get-page guides/chat`);
+    const endpoint = chat
+        .command("endpoint")
+        .description("Manage saved chatbot endpoints")
+        .addHelpText("after", `
+Endpoints are workspace-scoped. The active endpoint (set with
+\`ish chat endpoint use <id>\`) is the default for verbs that
+take an optional endpoint id.
+
+The dialog at https://app.ishlabs.io/<workspace>/chatbot-endpoints
+edits the same resources via PUT /chatbot-endpoints/{id}; the CLI
+mirrors that editing model.`);
+    attachChatEndpointCommands(endpoint);
+    attachChatEndpointInit(endpoint);
+    attachChatEndpointTest(endpoint);
+}
+// Re-exported for tests / external integration if needed.
+export { envelopeFromRow };