@ishlabs/cli 0.9.0 → 0.11.0

package/dist/lib/chat-endpoint-templates.js

@@ -0,0 +1,210 @@
+/**
+ * Hand-curated `ChatbotEndpointConfig` templates for `ish chat endpoint init
+ * --template <name>`.
+ *
+ * Each template is a known-good wire shape an agent can drop straight into
+ * `create_chatbot_endpoint` — derived from public docs for the named
+ * provider. Auth / API key values are placeholder secret refs
+ * (`{{secret:NAME}}`); the agent stores the real value via
+ * `ish secret set` before testing.
+ *
+ * Templates are intentionally minimal:
+ *   - `transport`, `outgoing`, `incoming` (slots-only).
+ *   - No `retry` block — defaults are fine.
+ *   - No `asyncPoll` — none of the listed providers use it.
+ *   - `streaming` only when the provider's default flow is SSE-shaped
+ *     (we currently keep all templates in `sync` mode; agents who want
+ *     streaming flip the transport themselves after init).
+ *
+ * Slots / references are populated when the provider documents a stable
+ * structured-output container (e.g. Bot Framework's `suggestedActions`,
+ * Watson Assistant's `output.generic[]`). Where the provider is pure text
+ * (vanilla OpenAI / Anthropic chat-completions), the lists stay empty —
+ * the runtime auto-classifier handles any structured content the bot
+ * decides to emit per turn.
+ */
+const OPENAI = {
+    name: "openai",
+    description: "OpenAI chat-completions wire shape. Stateless by default; ish ships the rolled-up history per turn. Drop in any OpenAI-compatible bot (Groq / Together / vLLM / OpenRouter / LiteLLM).",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://api.openai.com/v1/chat/completions",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "Bearer {{secret:OPENAI_API_KEY}}",
+            },
+            bodyTemplate: {
+                model: "gpt-4o-mini",
+                messages: "{{history_with_current}}",
+            },
+            mode: "stateless",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "choices[0].message.content",
+            toolCallsPath: "choices[0].message.tool_calls",
+            tokenUsagePath: "usage",
+            slots: [],
+            references: [],
+        },
+    },
+};
+const ANTHROPIC = {
+    name: "anthropic",
+    description: "Anthropic Messages API. Stateless: each request carries the full history and a fresh system prompt. Default model is the latest Sonnet.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://api.anthropic.com/v1/messages",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "anthropic-version": "2023-06-01",
+                "x-api-key": "{{secret:ANTHROPIC_API_KEY}}",
+            },
+            bodyTemplate: {
+                model: "claude-sonnet-4-20250514",
+                max_tokens: 1024,
+                messages: "{{history_with_current}}",
+            },
+            mode: "stateless",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "content[0].text",
+            tokenUsagePath: "usage",
+            slots: [],
+            references: [],
+        },
+    },
+};
+const VOICEFLOW = {
+    name: "voiceflow",
+    description: "Voiceflow Dialog Manager API. Stateful — the URL embeds the user/session id, and Voiceflow returns a list of trace objects. Body is `{action: {type: 'text', payload: <text>}}` per turn.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://general-runtime.voiceflow.com/state/user/{{conversation_id}}/interact",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "{{secret:VOICEFLOW_API_KEY}}",
+                versionID: "production",
+            },
+            bodyTemplate: {
+                action: {
+                    type: "text",
+                    payload: "{{action.text}}",
+                },
+            },
+            mode: "stateful",
+            roleAliases: {},
+        },
+        incoming: {
+            // Voiceflow's runtime returns an array of trace objects; the bot's
+            // textual reply lives in the first `speak` / `text` trace's payload.
+            // Agents typically tighten this path after a probe turn.
+            messagePath: "[0].payload.message",
+            slots: [
+                {
+                    containerPath: "[0].payload.choices",
+                    kind: "alternatives",
+                    labelPath: "name",
+                    idPath: "intent",
+                },
+            ],
+            references: [],
+        },
+    },
+};
+const DIALOGFLOW_CX = {
+    name: "dialogflow-cx",
+    description: "Google Dialogflow CX `detectIntent`. Stateful: the URL embeds the agent + session id and the response carries the next `currentPage` plus a list of fulfillment messages.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://dialogflow.googleapis.com/v3/projects/{{secret:GCP_PROJECT}}/locations/global/agents/{{secret:DIALOGFLOW_AGENT_ID}}/sessions/{{conversation_id}}:detectIntent",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "Bearer {{secret:GOOGLE_ACCESS_TOKEN}}",
+            },
+            bodyTemplate: {
+                queryInput: {
+                    text: { text: "{{action.text}}" },
+                    languageCode: "en",
+                },
+            },
+            mode: "stateful",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "queryResult.responseMessages[0].text.text[0]",
+            conversationIdPath: "responseId",
+            slots: [
+                {
+                    containerPath: "queryResult.responseMessages",
+                    kind: null,
+                },
+            ],
+            references: [],
+        },
+    },
+};
+const BOTFRAMEWORK = {
+    name: "botframework",
+    description: "Microsoft Bot Framework Direct Line `conversations/{id}/activities`. Stateful via the conversation id; activities[] carry the bot's reply plus suggestedActions for choice slots.",
+    config: {
+        transport: "sync",
+        outgoing: {
+            url: "https://directline.botframework.com/v3/directline/conversations/{{conversation_id}}/activities",
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Authorization: "Bearer {{secret:DIRECTLINE_SECRET}}",
+            },
+            bodyTemplate: {
+                type: "message",
+                from: { id: "{{tester.name}}" },
+                text: "{{action.text}}",
+            },
+            mode: "stateful",
+            roleAliases: {},
+        },
+        incoming: {
+            messagePath: "activities[0].text",
+            conversationIdPath: "activities[0].conversation.id",
+            slots: [
+                {
+                    containerPath: "activities[0].suggestedActions.actions",
+                    kind: "alternatives",
+                    labelPath: "title",
+                    idPath: "value",
+                },
+            ],
+            references: [
+                {
+                    containerPath: "activities[0].attachments",
+                    labelPath: "name",
+                    urlPath: "contentUrl",
+                },
+            ],
+        },
+    },
+};
+const TEMPLATES = {
+    openai: OPENAI,
+    anthropic: ANTHROPIC,
+    voiceflow: VOICEFLOW,
+    "dialogflow-cx": DIALOGFLOW_CX,
+    botframework: BOTFRAMEWORK,
+};
+export const TEMPLATE_NAMES = Object.keys(TEMPLATES);
+export function getChatEndpointTemplate(name) {
+    return TEMPLATES[name];
+}
+export function listChatEndpointTemplates() {
+    return TEMPLATE_NAMES.map((n) => TEMPLATES[n]);
+}

package/dist/lib/command-helpers.d.ts

@@ -123,6 +123,12 @@ export declare function confirmDestructive(prompt: string, opts: {
 export declare function resolveWorkspace(explicit?: string): string;
 export declare function resolveStudy(explicit?: string): string;
 export declare function resolveAsk(explicit?: string): string;
+/**
+ * Resolve a chat endpoint id from (in order): the positional argument, the
+ * `--endpoint <id>` flag, the `ISH_CHAT_ENDPOINT` env var, or the active
+ * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
+ */
+export declare function resolveChatEndpoint(positional?: string, flag?: string): string;
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export declare function collectRepeatable(value: string, prev?: string[]): string[];
 /**
@@ -150,4 +156,16 @@ export declare function parseWaitTimeout(raw: string | undefined, defaultMs?: nu
  * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
  * unused values.
  */
+/**
+ * Read a `--*-config <file>` style flag value, treating "-" as "read from
+ * stdin" and any other value as a file path on disk. Trailing newlines on
+ * stdin input are stripped so the resulting string parses cleanly as JSON.
+ *
+ * Throws when "-" is passed but stdin is a TTY (no upstream pipe).
+ *
+ * Mirrors the readSecretFlag pattern in src/commands/workspace.ts; extracted
+ * so every `--<x>-config <file>` flag across commands shares one
+ * implementation.
+ */
+export declare function readFileOrStdin(path: string): Promise<string>;
 export declare function injectGlobalWorkspaceOption(program: Command): void;

package/dist/lib/command-helpers.js

@@ -348,6 +348,20 @@ export function exitCodeFromError(err) {
         // Client-side validation failures
         if (err.name === "ValidationError" || /^invalid |^cannot read |is empty:|--\w[\w-]* must be|pick an audience|use either /i.test(err.message))
             return 2;
+        // Errors that pre-declare their own retryability / error_code take
+        // precedence — WaitTimeoutError sets `error_code: "wait_timeout"`
+        // and `retryable: true`, so callers can branch on exit 5 (transient)
+        // distinct from the api-client's generic 408/timeout family.
+        const tagged = err;
+        if (tagged.error_code === "wait_timeout")
+            return 5;
+        if (typeof tagged.retryable === "boolean" && tagged.retryable)
+            return 5;
+        // Structured error_kind on the Error object (set by chat endpoint test/init,
+        // simulation routes, etc.). TunnelInactive is the canonical transient one.
+        const kind = err.error_kind;
+        if (typeof kind === "string" && kind === "TunnelInactive")
+            return 5;
     }
     return 1;
 }
@@ -439,6 +453,18 @@ export function readJsonFileOrStdin(filePath) {
         process.stdin.on("error", reject);
     });
 }
+/**
+ * Build the suggested re-invocation example by taking the live argv and
+ * appending `--yes` if it isn't already there. Strips the `node` /
+ * `dist/index.js` prefix so the example reads as a normal `ish` command.
+ */
+function buildConfirmationExample() {
+    const argv = process.argv.slice(2);
+    const args = argv.includes("--yes") || argv.includes("-y")
+        ? argv
+        : [...argv, "--yes"];
+    return ["ish", ...args].join(" ");
+}
 /**
  * Prompt for confirmation of a destructive action, or short-circuit when
  * `--yes` is set. In `--json` mode without `--yes` we refuse with a usage
@@ -451,11 +477,15 @@ export async function confirmDestructive(prompt, opts) {
     if (opts.json) {
         const err = new Error(`--yes is required for destructive actions in --json mode. Refusing to proceed without explicit confirmation.`);
         err.name = "ValidationError";
+        err.error_kind = "ConfirmationRequired";
+        err.example = buildConfirmationExample();
         throw err;
     }
     if (!process.stdin.isTTY) {
         const err = new Error(`--yes is required for destructive actions when stdin is not a TTY. Refusing to proceed without explicit confirmation.`);
         err.name = "ValidationError";
+        err.error_kind = "ConfirmationRequired";
+        err.example = buildConfirmationExample();
         throw err;
     }
     process.stderr.write(`${prompt} [y/N] `);
@@ -486,6 +516,23 @@ export async function confirmDestructive(prompt, opts) {
         throw err;
     }
 }
+/**
+ * Construct a structured "no active <thing>" Error so the JSON envelope from
+ * `outputError` carries `error_code` + `suggestions` rather than a generic
+ * `client_error`. Pattern A (Sprint 2): when the active study/workspace
+ * evaporates between commands, agents need to branch on the error code, not
+ * scrape prose. Without this, downstream modality validation in
+ * `iteration create` would surface a misleading "Image iterations require
+ * --image-urls" message instead of the real "no active study" cause.
+ */
+function noActiveContextError(message, errorCode, suggestions) {
+    const err = new Error(message);
+    err.name = "NoActiveContextError";
+    err.error_code = errorCode;
+    err.retryable = false;
+    err.suggestions = suggestions;
+    return err;
+}
 export function resolveWorkspace(explicit) {
     if (explicit)
         return resolveId(explicit);
@@ -500,7 +547,10 @@ export function resolveWorkspace(explicit) {
     const config = loadConfig();
     if (config.workspace)
         return config.workspace;
-    throw new Error('No workspace set. Use `ish workspace use <alias>` or pass --workspace.');
+    throw noActiveContextError('No active workspace. Run `ish workspace use <workspace-id>` or pass --workspace <id>.', "no_active_workspace", [
+        "ish workspace list",
+        "ish workspace use <workspace-id>",
+    ]);
 }
 export function resolveStudy(explicit) {
     if (explicit)
@@ -511,7 +561,10 @@ export function resolveStudy(explicit) {
     const config = loadConfig();
     if (config.study)
         return config.study;
-    throw new Error('No study set. Use `ish study use <alias>` or pass --study.');
+    throw noActiveContextError('No active study. Run `ish study use <study-id>` or pass --study <id>.', "no_active_study", [
+        "ish study use <study-id>",
+        "ish iteration create --study <study-id> ...",
+    ]);
 }
 export function resolveAsk(explicit) {
     if (explicit)
@@ -522,7 +575,28 @@ export function resolveAsk(explicit) {
     const config = loadConfig();
     if (config.ask)
         return config.ask;
-    throw new Error('No ask set. Use `ish ask use <alias>` or pass the ask ID as an argument.');
+    throw noActiveContextError('No active ask. Run `ish ask use <ask-id>` or pass the ask ID as an argument.', "no_active_ask", [
+        "ish ask list",
+        "ish ask use <ask-id>",
+    ]);
+}
+/**
+ * Resolve a chat endpoint id from (in order): the positional argument, the
+ * `--endpoint <id>` flag, the `ISH_CHAT_ENDPOINT` env var, or the active
+ * endpoint persisted by `ish chat endpoint use`. Throws when none are set.
+ */
+export function resolveChatEndpoint(positional, flag) {
+    if (positional)
+        return resolveId(positional);
+    if (flag)
+        return resolveId(flag);
+    const env = process.env.ISH_CHAT_ENDPOINT;
+    if (env)
+        return resolveId(env);
+    const config = loadConfig();
+    if (config.chat_endpoint)
+        return config.chat_endpoint;
+    throw new Error('No chat endpoint set. Use `ish chat endpoint use <id>`, pass the endpoint id, or set --endpoint.');
 }
 /** Commander option-collector for repeatable flags (e.g. `--variant text:"..."` repeated). */
 export function collectRepeatable(value, prev = []) {
@@ -571,6 +645,34 @@ const WORKSPACE_SCOPED_GROUPS = new Set([
  * body. Resolvers (`resolveWorkspace`, `resolveAudienceProfileIds`) ignore
  * unused values.
  */
+/**
+ * Read a `--*-config <file>` style flag value, treating "-" as "read from
+ * stdin" and any other value as a file path on disk. Trailing newlines on
+ * stdin input are stripped so the resulting string parses cleanly as JSON.
+ *
+ * Throws when "-" is passed but stdin is a TTY (no upstream pipe).
+ *
+ * Mirrors the readSecretFlag pattern in src/commands/workspace.ts; extracted
+ * so every `--<x>-config <file>` flag across commands shares one
+ * implementation.
+ */
+export async function readFileOrStdin(path) {
+    if (path === "-") {
+        if (process.stdin.isTTY) {
+            throw new Error('Use "-" only when piping the value on stdin.');
+        }
+        return await new Promise((resolve, reject) => {
+            let data = "";
+            process.stdin.setEncoding("utf-8");
+            process.stdin.on("data", (chunk) => {
+                data += chunk;
+            });
+            process.stdin.on("end", () => resolve(data.replace(/\r?\n$/, "")));
+            process.stdin.on("error", reject);
+        });
+    }
+    return fs.readFileSync(path, "utf-8");
+}
 export function injectGlobalWorkspaceOption(program) {
     const walk = (cmd) => {
         if (cmd.commands.length === 0) {