@ishlabs/cli 0.9.0 → 0.11.0

package/dist/lib/alias-hydrate.js

@@ -0,0 +1,175 @@
+/**
+ * Best-effort alias-cache hydration on alias-miss (Pattern F).
+ *
+ * The CLI persists aliases to ``~/.ish/aliases.json``, so the cache survives
+ * across processes. Where it bites: the file is missing/empty (fresh install,
+ * `rm ~/.ish/aliases.json`, agent running in a sandbox with a fresh
+ * `ISH_HOME`) and the agent has an alias from a prior process or the docs.
+ *
+ * ``resolveIdAsync(input, client, hints?)`` mirrors the sync ``resolveId``
+ * contract but, on alias-miss, attempts a single ``GET /list`` to repopulate
+ * the cache before retrying. The hydrate is BEST-EFFORT: a failing list
+ * call is swallowed and the canonical "Unknown alias" error fires with the
+ * actionable suggestion in the message.
+ *
+ * For prefixes whose list endpoint requires a parent ID (study/iteration/
+ * ask/etc), the caller passes ``hints`` carrying the parent (workspaceId,
+ * studyId). Without a parent we skip the hydrate — global N+1 fan-out is
+ * too expensive for a papercut.
+ */
+import { ALIAS_PREFIX, resolveId, tagAlias } from "./alias-store.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ALIAS_RE = /^[a-z]+-[0-9a-f]{3,}$|^[a-z]+\d{2,}$/;
+function aliasPrefix(value) {
+    if (!ALIAS_RE.test(value))
+        return null;
+    const m = value.match(/^([a-z]+)/);
+    return m ? m[1] : null;
+}
+function isAliasShape(value) {
+    return ALIAS_RE.test(value);
+}
+function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/**
+ * Try to resolve a parent ID — accepts either a UUID or a known alias. Used
+ * to extract ``workspaceId`` / ``studyId`` from hints before we fan out to a
+ * scoped list endpoint. Returns ``null`` if the value can't be resolved
+ * cheaply (e.g. it's an alias that's also missing from the cache).
+ */
+function resolveParent(value) {
+    if (!value)
+        return null;
+    if (isUuid(value))
+        return value;
+    // Try the sync resolver but never throw.
+    try {
+        return resolveId(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hit a list endpoint and tag every returned ID under the given prefix.
+ * Silently swallows network/auth failures — we only ever block the
+ * underlying call when the alias is genuinely unknown after hydrate.
+ */
+async function hydrateList(client, prefix, path, params) {
+    let data;
+    try {
+        data = await client.get(path, params);
+    }
+    catch {
+        return;
+    }
+    let items = [];
+    if (Array.isArray(data)) {
+        items = data;
+    }
+    else if (typeof data === "object" && data !== null && "items" in data) {
+        const inner = data.items;
+        if (Array.isArray(inner))
+            items = inner;
+    }
+    for (const item of items) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const id = item.id;
+        if (typeof id === "string" && id.length > 0) {
+            try {
+                tagAlias(prefix, id);
+            }
+            catch {
+                // Ignore — bad UUIDs are not catastrophic.
+            }
+        }
+    }
+}
+/**
+ * Best-effort hydrate of the alias cache for ``alias``'s entity type. Returns
+ * silently on success or any failure — the caller checks the cache after
+ * this returns.
+ */
+export async function hydrateForAlias(client, alias, hints = {}) {
+    const prefix = aliasPrefix(alias);
+    if (!prefix)
+        return;
+    const ws = resolveParent(hints.workspaceId);
+    const study = resolveParent(hints.studyId);
+    switch (prefix) {
+        case ALIAS_PREFIX.workspace: {
+            // Top-level — no parent.
+            await hydrateList(client, ALIAS_PREFIX.workspace, "/products");
+            return;
+        }
+        case ALIAS_PREFIX.study: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.study, `/products/${ws}/studies`);
+            return;
+        }
+        case ALIAS_PREFIX.iteration: {
+            if (!study)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.iteration, `/studies/${study}/iterations`);
+            return;
+        }
+        case ALIAS_PREFIX.testerProfile: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.testerProfile, "/tester-profiles", { workspace_id: ws, type: "all", limit: "200" });
+            return;
+        }
+        case ALIAS_PREFIX.ask: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.ask, `/products/${ws}/asks`);
+            return;
+        }
+        case ALIAS_PREFIX.chatEndpoint: {
+            if (!ws)
+                return;
+            await hydrateList(client, ALIAS_PREFIX.chatEndpoint, `/products/${ws}/chatbot-endpoints`);
+            return;
+        }
+        // No cheap single-call hydrate for the rest:
+        //   tester (`t-`)         — scoped to iteration
+        //   ask round (`r-`)      — nested on the ask
+        //   audience source (`tps-`) — fetched per-id
+        //   simulation config (`c-`) — no list endpoint yet
+        default:
+            return;
+    }
+}
+/**
+ * Async sibling of ``resolveId``: same UUID-or-alias contract, but on
+ * alias-miss attempts a best-effort hydrate via the matching list endpoint
+ * before retrying. Falls back to the canonical "Unknown alias" error
+ * (with named list-command suggestion) when the alias is still missing
+ * after the hydrate.
+ *
+ * Use this at command-handler entry points where the agent supplies an
+ * alias and the same call carries enough context (workspace / study) to
+ * scope the hydrate cheaply.
+ */
+export async function resolveIdAsync(input, client, hints = {}) {
+    if (isUuid(input))
+        return input;
+    if (!isAliasShape(input)) {
+        // Fall through to the sync resolver so the "Invalid ID" guidance fires.
+        return resolveId(input);
+    }
+    // Cheap-path: alias already in store.
+    try {
+        return resolveId(input);
+    }
+    catch {
+        // Cache miss — attempt best-effort hydrate.
+        await hydrateForAlias(client, input, hints);
+        // Retry — sync resolver re-reads ``aliases.json`` from disk on every
+        // call (see loadAliases), so the freshly tagged entries are visible.
+        return resolveId(input);
+    }
+}

package/dist/lib/alias-store.d.ts

@@ -17,6 +17,7 @@ export declare const ALIAS_PREFIX: {
     readonly job: "j";
     readonly ask: "a";
     readonly askRound: "r";
+    readonly chatEndpoint: "ep";
 };
 /**
  * Save aliases for a list of IDs under the given prefix.

package/dist/lib/alias-store.js

@@ -20,6 +20,7 @@ export const ALIAS_PREFIX = {
     job: "j",
     ask: "a",
     askRound: "r",
+    chatEndpoint: "ep",
 };
 /** Format a number with zero-padding (minimum 2 digits). */
 function padNum(n) {
@@ -110,6 +111,32 @@ export function deterministicAlias(prefix, uuid) {
 }
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const ALIAS_RE = /^[a-z]+-[0-9a-f]{3,}$|^[a-z]+\d{2,}$/;
+/**
+ * Suggested `ish ... list` command per alias prefix. Surfaced in the
+ * unknown-alias error (Pattern F) so the agent doesn't have to guess
+ * which list command to run.
+ */
+const HYDRATE_HINT = {
+    w: "ish workspace list",
+    s: "ish study list",
+    i: "ish iteration list --study <study-id>",
+    tp: "ish profile list",
+    tps: "ish source list",
+    t: "ish tester get <tester-id>",
+    c: "ish config list",
+    a: "ish ask list",
+    r: "ish ask get <ask-id>",
+    ep: "ish chat endpoint list",
+    // Legacy two-letter prefixes the deterministic generator may have
+    // produced before; defaults below cover anything else.
+};
+function hintForPrefix(alias) {
+    // Pull the leading alpha run, which is the prefix.
+    const m = alias.match(/^([a-z]+)/);
+    if (!m)
+        return "the matching list command";
+    return HYDRATE_HINT[m[1]] ?? "the matching list command";
+}
 /**
  * Resolve a short alias to a full UUID, or validate and pass through a full UUID.
  *
@@ -130,7 +157,7 @@ export function resolveId(input) {
         const uuid = aliases[input];
         if (uuid)
             return uuid;
-        throw new Error(`Unknown alias "${input}". Run a list command first to generate aliases.`);
+        throw new Error(`Unknown alias "${input}". Run \`${hintForPrefix(input)}\` first to generate aliases.`);
     }
     // 3. Anything else — fail with helpful guidance
     throw new Error(`Invalid ID "${input}". Use a short alias (e.g. w-a3f, s-b2c) or a full UUID.\n` +

package/dist/lib/auth.js

@@ -24,8 +24,10 @@ async function verifyToken(token, apiUrl) {
         return resp.status !== 401 && resp.status !== 403;
     }
     catch {
-        // Network error — can't verify, assume ok
-        console.error("Warning: Could not verify token (network error). Proceeding anyway.");
+        // Network blip on the best-effort probe. The subsequent API call will
+        // surface the real auth failure (with a proper exit code 3) if there
+        // is one, so don't pollute stderr on every command — it fired on
+        // every successful run during Phase A (Pattern F / C4-finding-5).
         return true;
     }
 }

package/dist/lib/chat-endpoint-formatters.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Lean-vs-verbose projection for ChatbotEndpointResponse.
+ *
+ * The backend returns a nested camelCase shape (id, name, productId, config,
+ * isTunnelBacked, createdAt, updatedAt). The lean projection keeps only the
+ * fields an agent typically branches on: id/alias/name, transport, the
+ * outgoing url + method, the incoming messagePath, slot/reference counts, and
+ * isTunnelBacked. `--verbose` (or piped) passes the raw response.
+ *
+ * Slots-only model: `incoming.slots` and `incoming.references` are typed
+ * binding lists. Each slot carries `{containerPath, kind, labelPath, idPath}`;
+ * each reference carries `{containerPath, labelPath, urlPath}`. Legacy fields
+ * (`optionsPath`, `formRequestPath`, `cardsPath`, `artifactsPath`,
+ * `suggestedFollowupsPath`, plus the parallel `slotsContainerPaths` /
+ * `slotsKindHints` / `slotsLabelPaths` / `slotsIdPaths` /
+ * `referencesContainerPaths` arrays) are gone — anything interactive is a
+ * slot tagged with `kind`; anything passive is a reference.
+ */
+export interface OutgoingHttp {
+    url?: string;
+    method?: string;
+    mode?: string;
+    [key: string]: unknown;
+}
+export interface SlotBinding {
+    containerPath: string;
+    kind?: "alternatives" | "form" | "text" | null;
+    labelPath?: string | null;
+    idPath?: string | null;
+}
+export interface ReferenceBinding {
+    containerPath: string;
+    labelPath?: string | null;
+    urlPath?: string | null;
+}
+export interface IncomingHttp {
+    messagePath?: string;
+    conversationIdPath?: string | null;
+    endOfConversationPath?: string | null;
+    errorPath?: string | null;
+    toolCallsPath?: string | null;
+    tokenUsagePath?: string | null;
+    slots?: SlotBinding[];
+    references?: ReferenceBinding[];
+    responseStub?: unknown;
+    [key: string]: unknown;
+}
+export interface StreamingSettings {
+    eventFormat?: "openai" | "anthropic" | "raw";
+    deltaPath?: string | null;
+    terminalEvent?: string | null;
+    maxWaitSeconds?: number;
+}
+export interface ChatbotEndpointConfig {
+    transport?: string;
+    outgoing?: OutgoingHttp;
+    incoming?: IncomingHttp;
+    streaming?: StreamingSettings | null;
+    asyncPoll?: unknown;
+    isTunnelBacked?: boolean;
+    [key: string]: unknown;
+}
+export interface ChatbotEndpointRow {
+    id?: string;
+    name?: string;
+    productId?: string;
+    config?: ChatbotEndpointConfig;
+    isTunnelBacked?: boolean;
+    [key: string]: unknown;
+}
+/** Return the round-trippable envelope used by `endpoint get --verbose`. */
+export declare function envelopeFromRow(row: ChatbotEndpointRow): Record<string, unknown>;
+export declare function formatChatEndpointList(rows: ChatbotEndpointRow[], json: boolean, verbose: boolean): void;
+export declare function formatChatEndpointDetail(row: ChatbotEndpointRow, json: boolean, verbose: boolean): void;

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

@@ -0,0 +1,154 @@
+/**
+ * Lean-vs-verbose projection for ChatbotEndpointResponse.
+ *
+ * The backend returns a nested camelCase shape (id, name, productId, config,
+ * isTunnelBacked, createdAt, updatedAt). The lean projection keeps only the
+ * fields an agent typically branches on: id/alias/name, transport, the
+ * outgoing url + method, the incoming messagePath, slot/reference counts, and
+ * isTunnelBacked. `--verbose` (or piped) passes the raw response.
+ *
+ * Slots-only model: `incoming.slots` and `incoming.references` are typed
+ * binding lists. Each slot carries `{containerPath, kind, labelPath, idPath}`;
+ * each reference carries `{containerPath, labelPath, urlPath}`. Legacy fields
+ * (`optionsPath`, `formRequestPath`, `cardsPath`, `artifactsPath`,
+ * `suggestedFollowupsPath`, plus the parallel `slotsContainerPaths` /
+ * `slotsKindHints` / `slotsLabelPaths` / `slotsIdPaths` /
+ * `referencesContainerPaths` arrays) are gone — anything interactive is a
+ * slot tagged with `kind`; anything passive is a reference.
+ */
+import { tagAlias, ALIAS_PREFIX } from "./alias-store.js";
+import { output, printTable } from "./output.js";
+function leanRow(row) {
+    const cfg = row.config ?? {};
+    const out = {};
+    if (row.id)
+        out.alias = tagAlias(ALIAS_PREFIX.chatEndpoint, row.id);
+    if (row.id)
+        out.id = row.id;
+    if (row.name)
+        out.name = row.name;
+    if (cfg.transport)
+        out.transport = cfg.transport;
+    out.is_tunnel_backed = Boolean(row.isTunnelBacked);
+    if (cfg.outgoing?.url)
+        out.url = cfg.outgoing.url;
+    if (cfg.outgoing?.method)
+        out.method = cfg.outgoing.method;
+    if (cfg.outgoing?.mode)
+        out.mode = cfg.outgoing.mode;
+    if (cfg.incoming?.messagePath)
+        out.message_path = cfg.incoming.messagePath;
+    out.slots = Array.isArray(cfg.incoming?.slots) ? cfg.incoming.slots.length : 0;
+    out.references = Array.isArray(cfg.incoming?.references)
+        ? cfg.incoming.references.length
+        : 0;
+    return out;
+}
+/** Return the round-trippable envelope used by `endpoint get --verbose`. */
+export function envelopeFromRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        isTunnelBacked: Boolean(row.isTunnelBacked),
+        config: row.config ?? {},
+    };
+}
+export function formatChatEndpointList(rows, json, verbose) {
+    if (json) {
+        if (verbose) {
+            output(rows, true);
+            return;
+        }
+        output(rows.map(leanRow), true);
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("No chatbot endpoints.");
+        return;
+    }
+    const lean = rows.map(leanRow);
+    printTable(["#", "NAME", "TRANSPORT", "URL", "METHOD", "MODE", "TUNNEL"], lean.map((r) => [
+        String(r.alias ?? r.id ?? ""),
+        String(r.name ?? ""),
+        String(r.transport ?? "-"),
+        String(r.url ?? "-"),
+        String(r.method ?? "-"),
+        String(r.mode ?? "-"),
+        r.is_tunnel_backed ? "yes" : "no",
+    ]));
+}
+function formatSlotLine(slot) {
+    const kindLabel = slot.kind ?? "auto";
+    const subParts = [];
+    if (slot.labelPath)
+        subParts.push(`label=${slot.labelPath}`);
+    if (slot.idPath)
+        subParts.push(`id=${slot.idPath}`);
+    const tail = subParts.length > 0 ? `  (${subParts.join(", ")})` : "";
+    return `    ${slot.containerPath}  [${kindLabel}]${tail}`;
+}
+function formatReferenceLine(ref) {
+    const subParts = [];
+    if (ref.labelPath)
+        subParts.push(`label=${ref.labelPath}`);
+    if (ref.urlPath)
+        subParts.push(`url=${ref.urlPath}`);
+    const tail = subParts.length > 0 ? `  (${subParts.join(", ")})` : "";
+    return `    ${ref.containerPath}${tail}`;
+}
+export function formatChatEndpointDetail(row, json, verbose) {
+    if (json) {
+        if (verbose) {
+            output(envelopeFromRow(row), true);
+            return;
+        }
+        output(leanRow(row), true);
+        return;
+    }
+    const cfg = row.config ?? {};
+    const alias = row.id ? tagAlias(ALIAS_PREFIX.chatEndpoint, row.id) : "-";
+    console.log(`${row.name || "Untitled"} (${alias})`);
+    const meta = [];
+    if (cfg.transport)
+        meta.push(String(cfg.transport));
+    if (row.isTunnelBacked)
+        meta.push("tunnel-backed");
+    if (meta.length > 0)
+        console.log(meta.join(" · "));
+    if (cfg.outgoing) {
+        console.log("");
+        console.log(`  URL    ${cfg.outgoing.url ?? "-"}`);
+        console.log(`  Method ${cfg.outgoing.method ?? "-"}`);
+        console.log(`  Mode   ${cfg.outgoing.mode ?? "-"}`);
+    }
+    if (cfg.incoming) {
+        console.log("");
+        console.log(`  Message path  ${cfg.incoming.messagePath ?? "-"}`);
+        if (cfg.incoming.conversationIdPath) {
+            console.log(`  Session path  ${cfg.incoming.conversationIdPath}`);
+        }
+        if (cfg.incoming.errorPath) {
+            console.log(`  Error path    ${cfg.incoming.errorPath}`);
+        }
+        const slots = Array.isArray(cfg.incoming.slots) ? cfg.incoming.slots : [];
+        console.log(`  Slots         ${slots.length}`);
+        for (const slot of slots) {
+            console.log(formatSlotLine(slot));
+        }
+        const refs = Array.isArray(cfg.incoming.references) ? cfg.incoming.references : [];
+        console.log(`  References    ${refs.length}`);
+        for (const ref of refs) {
+            console.log(formatReferenceLine(ref));
+        }
+    }
+    if (cfg.transport === "streaming" && cfg.streaming) {
+        console.log("");
+        console.log(`  Streaming     ${cfg.streaming.eventFormat ?? "openai"}`);
+        if (cfg.streaming.deltaPath) {
+            console.log(`    delta_path  ${cfg.streaming.deltaPath}`);
+        }
+        if (cfg.streaming.terminalEvent) {
+            console.log(`    terminal    ${cfg.streaming.terminalEvent}`);
+        }
+    }
+}

package/dist/lib/chat-endpoint-templates.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+import type { ChatbotEndpointConfig } from "./chat-endpoint-formatters.js";
+export type ChatEndpointTemplateName = "openai" | "anthropic" | "voiceflow" | "dialogflow-cx" | "botframework";
+export interface ChatEndpointTemplate {
+    name: ChatEndpointTemplateName;
+    description: string;
+    config: ChatbotEndpointConfig;
+}
+export declare const TEMPLATE_NAMES: ChatEndpointTemplateName[];
+export declare function getChatEndpointTemplate(name: string): ChatEndpointTemplate | undefined;
+export declare function listChatEndpointTemplates(): ChatEndpointTemplate[];