@almyty/chat 1.2.0 → 1.4.0

package/dist/args.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Command line for `almyty chat`.
+ *
+ * Parsing lives apart from the entry point so the surface can be tested
+ * without a terminal, and so `--help` is generated from the same table
+ * the parser reads. A flag that exists and is undocumented, or is
+ * documented and does not exist, is a bug either way.
+ */
+export interface ChatArgs {
+    help: boolean;
+    version: boolean;
+    /** `<org>/<agent-slug>`, a bare slug, or undefined for the picker. */
+    ref?: string;
+    resume?: string;
+    /** One-shot message. Answers and exits, no REPL. */
+    message?: string;
+    /** Read the message from stdin rather than a tty. */
+    stdin: boolean;
+    json: boolean;
+    /** False renders the answer once it is complete instead of token by token. */
+    stream: boolean;
+    /** Explicit colour choice; undefined means "decide from the terminal". */
+    color?: boolean;
+    maxSteps?: number;
+    maxCostCents?: number;
+    /** A parse problem worth exiting on, rather than guessing. */
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ChatArgs;
+/**
+ * The agent to open: the argument, else $ALMYTY_AGENT.
+ *
+ * The environment variable is how a compiled terminal app knows which
+ * agent it is, since the build compiles this client unchanged and the
+ * recipient should not have to type an agent reference.
+ */
+export declare function resolveRef(args: ChatArgs, env?: Record<string, string | undefined>): string | undefined;
+/** Split `<org>/<agent>` into its parts; a bare slug leaves org unset. */
+export declare function splitRef(ref: string): {
+    orgSlug?: string;
+    agentSlug: string;
+};
+/**
+ * Whether to run without a terminal UI.
+ *
+ * A CLI that only works on a tty is half a CLI: piping in a question or
+ * out to jq has to work, and ink cannot draw to a pipe.
+ */
+export declare function isNonInteractive(args: ChatArgs, io?: {
+    stdinTty?: boolean;
+    stdoutTty?: boolean;
+}): boolean;
+/**
+ * Whether to emit colour.
+ *
+ * Honours the NO_COLOR convention and FORCE_COLOR, and never colours a
+ * pipe unless asked to.
+ */
+export declare function useColor(args: ChatArgs, env?: Record<string, string | undefined>, stdoutTty?: boolean): boolean;
+/**
+ * `--help`, built from the same command table the REPL resolves
+ * against, so a new slash command cannot go undocumented.
+ */
+export declare function helpText(version: string): string;

package/dist/args.js

@@ -0,0 +1,207 @@
+/**
+ * Command line for `almyty chat`.
+ *
+ * Parsing lives apart from the entry point so the surface can be tested
+ * without a terminal, and so `--help` is generated from the same table
+ * the parser reads. A flag that exists and is undocumented, or is
+ * documented and does not exist, is a bug either way.
+ */
+import { SLASH_COMMANDS, COMMAND_DESCS } from './commands.js';
+import { EXIT_CODE_HELP } from './exit-codes.js';
+/** Flags that take no value. */
+const BOOLEAN_FLAGS = new Set([
+    '--help', '-h', '--version', '-v', '--json', '--stdin',
+    '--no-stream', '--stream', '--no-color', '--color',
+]);
+/** Flags that consume the next argument. */
+const VALUE_FLAGS = new Set(['--resume', '--message', '-m', '--max-steps', '--max-cost-cents']);
+function positiveInt(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
+        return { error: `${flag} needs a positive whole number, got "${raw}"` };
+    }
+    return { value: n };
+}
+export function parseArgs(argv) {
+    const args = { help: false, version: false, stdin: false, json: false, stream: true };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (VALUE_FLAGS.has(arg)) {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('-')) {
+                return { ...args, error: `${arg} needs a value` };
+            }
+            i++;
+            switch (arg) {
+                case '--resume':
+                    args.resume = value;
+                    break;
+                case '--message':
+                case '-m':
+                    args.message = value;
+                    break;
+                case '--max-steps': {
+                    const { value: n, error } = positiveInt(value, arg);
+                    if (error)
+                        return { ...args, error };
+                    args.maxSteps = n;
+                    break;
+                }
+                case '--max-cost-cents': {
+                    const { value: n, error } = positiveInt(value, arg);
+                    if (error)
+                        return { ...args, error };
+                    args.maxCostCents = n;
+                    break;
+                }
+            }
+            continue;
+        }
+        if (BOOLEAN_FLAGS.has(arg)) {
+            switch (arg) {
+                case '--help':
+                case '-h':
+                    args.help = true;
+                    break;
+                case '--version':
+                case '-v':
+                    args.version = true;
+                    break;
+                case '--json':
+                    args.json = true;
+                    break;
+                case '--stdin':
+                    args.stdin = true;
+                    break;
+                case '--stream':
+                    args.stream = true;
+                    break;
+                case '--no-stream':
+                    args.stream = false;
+                    break;
+                case '--color':
+                    args.color = true;
+                    break;
+                case '--no-color':
+                    args.color = false;
+                    break;
+            }
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            // Silently ignoring an unknown flag is how `--jsonl` spends an
+            // afternoon looking like a broken --json.
+            return { ...args, error: `Unknown option: ${arg}\nRun with --help to see what this accepts.` };
+        }
+        if (args.ref === undefined)
+            args.ref = arg;
+        else
+            return { ...args, error: `Unexpected argument: ${arg}. Pass a message with --message instead.` };
+    }
+    return args;
+}
+/**
+ * The agent to open: the argument, else $ALMYTY_AGENT.
+ *
+ * The environment variable is how a compiled terminal app knows which
+ * agent it is, since the build compiles this client unchanged and the
+ * recipient should not have to type an agent reference.
+ */
+export function resolveRef(args, env = process.env) {
+    return args.ref ?? (env.ALMYTY_AGENT || undefined);
+}
+/** Split `<org>/<agent>` into its parts; a bare slug leaves org unset. */
+export function splitRef(ref) {
+    const slash = ref.indexOf('/');
+    if (slash === -1)
+        return { agentSlug: ref };
+    return { orgSlug: ref.slice(0, slash), agentSlug: ref.slice(slash + 1) };
+}
+/**
+ * Whether to run without a terminal UI.
+ *
+ * A CLI that only works on a tty is half a CLI: piping in a question or
+ * out to jq has to work, and ink cannot draw to a pipe.
+ */
+export function isNonInteractive(args, io = {}) {
+    if (args.message !== undefined || args.json || args.stdin)
+        return true;
+    return io.stdinTty === false || io.stdoutTty === false;
+}
+/**
+ * Whether to emit colour.
+ *
+ * Honours the NO_COLOR convention and FORCE_COLOR, and never colours a
+ * pipe unless asked to.
+ */
+export function useColor(args, env = process.env, stdoutTty = true) {
+    if (args.color !== undefined)
+        return args.color;
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0')
+        return true;
+    if (env.TERM === 'dumb')
+        return false;
+    return stdoutTty;
+}
+/**
+ * `--help`, built from the same command table the REPL resolves
+ * against, so a new slash command cannot go undocumented.
+ */
+export function helpText(version) {
+    const commands = SLASH_COMMANDS.map((cmd) => `  /${cmd.padEnd(11)}${COMMAND_DESCS[cmd] ?? ''}`).join('\n');
+    return `almyty chat v${version} — an interactive REPL for your almyty agents.
+
+Usage:
+  almyty chat [<org>/<agent-slug>] [options]
+
+  With no agent reference it lists the agents you can reach and asks.
+  A bare slug uses the organization on your credentials.
+
+Options:
+  -m, --message <text>       Ask one question, print the answer, exit.
+      --stdin                Read the question from stdin (for pipes).
+      --resume <id>          Continue a previous conversation.
+      --json                 One JSON object per answer. Implies non-interactive.
+      --no-stream            Wait for the whole answer instead of streaming it.
+      --no-color             Never colour the output. NO_COLOR is honoured too.
+      --max-steps <n>        Autonomous runs: cap the number of steps.
+      --max-cost-cents <n>   Autonomous runs: cap the spend, in cents.
+  -h, --help                 Show this.
+  -v, --version              Print the version.
+
+Slash commands, inside the REPL:
+${commands}
+
+  Commands take unique prefixes and aliases: /q for /quit, /sw for /agents.
+  Tab completes, up and down walk your input history.
+
+Keys:
+  Ctrl-C     Cancel the running answer (server-side too). Again to exit.
+  Ctrl-D     Exit.
+  Enter      Send. End a line with \\ to keep typing on the next one.
+
+Non-interactive:
+  almyty chat acme/support-bot -m "what is our refund window?"
+  echo "summarise today's errors" | almyty chat acme/ops --stdin
+  almyty chat acme/ops -m "check the deploy" --json | jq .output
+
+  The answer goes to stdout and the attribution to stderr, so a pipe
+  stays clean.
+
+Exit codes:
+${EXIT_CODE_HELP}
+
+Environment:
+  ALMYTY_TOKEN         Token override, instead of ~/.almyty/credentials.json.
+  ALMYTY_URL           API URL override.
+  ALMYTY_AGENT         Default agent reference, used when none is given.
+  ALMYTY_APP_URL       Dashboard URL used in error messages.
+  ALMYTY_CHAT_HISTORY  Input history file, instead of ~/.almyty/chat-history.
+  NO_COLOR             Set to anything to disable colour.
+
+Login:
+  npx @almyty/auth login
+`;
+}

package/dist/commands.d.ts

@@ -1,9 +1,29 @@
 import type { RunnerSummary } from '@almyty/client';
-export declare const SLASH_COMMANDS: readonly ["agents", "tools", "runners", "code", "code-stop", "esc", "help", "clear", "quit"];
+export declare const SLASH_COMMANDS: readonly ["agents", "model", "tools", "cost", "trace", "resume", "new", "runners", "code", "code-stop", "esc", "help", "clear", "quit"];
 export declare const ALIASES: Record<string, string>;
 export declare const COMMAND_DESCS: Record<string, string>;
 export declare function resolveSlash(input: string): string | null;
 export declare function getSuggestion(partial: string): string;
+/**
+ * Whether a submitted line asks to keep typing.
+ *
+ * A single-line prompt still has to accept a paragraph, so a trailing
+ * backslash continues onto the next line the way a shell does. Returns
+ * the text without the continuation marker, or null when the line is
+ * complete.
+ */
+export declare function continuationOf(value: string): string | null;
+/**
+ * A pasted block, as one message.
+ *
+ * A multi-line paste used to submit on its first newline and hand the
+ * rest to the prompt a line at a time — so a pasted stack trace became
+ * a dozen messages, and any line of it starting with `/` ran as a
+ * command. Newlines inside a submitted value are content.
+ */
+export declare function joinSubmission(lines: string[]): string;
+/** Whether a submission should be read as a slash command. */
+export declare function isSlashCommand(value: string): boolean;
 export type InputRoute = 'command' | 'coding' | 'chat';
 /**
  * Where a submitted line goes: slash commands are always commands; when a

package/dist/commands.js

@@ -1,11 +1,16 @@
 // ── Slash command resolution ────────────────────────────────────
 export const SLASH_COMMANDS = [
-    'agents', 'tools', 'runners', 'code', 'code-stop', 'esc', 'help', 'clear', 'quit',
+    'agents', 'model', 'tools', 'cost', 'trace', 'resume', 'new',
+    'runners', 'code', 'code-stop', 'esc', 'help', 'clear', 'quit',
 ];
 export const ALIASES = {
     agent: 'agents', ag: 'agents', switch: 'agents', sw: 'agents',
     tool: 'tools', t: 'tools',
-    runner: 'runners',
+    usage: 'cost', spend: 'cost',
+    steps: 'trace', last: 'trace',
+    reset: 'new',
+    // `r` predates /resume and kept meaning runners; /res resolves resume.
+    runner: 'runners', r: 'runners',
     stop: 'code-stop',
     detach: 'esc',
     h: 'help', '?': 'help',
@@ -14,13 +19,18 @@ export const ALIASES = {
 };
 export const COMMAND_DESCS = {
     agents: 'browse and switch agents',
+    model: 'show the model and routing policy in use',
     tools: 'show available tools',
+    cost: 'show tokens and spend for this session',
+    trace: "show the last run's steps",
+    resume: 'print the command that resumes this conversation',
+    new: 'start a fresh conversation with the same agent',
     runners: 'list your runners + coding CLIs',
     code: 'run a coding task on a runner',
     'code-stop': 'stop the active coding session',
     esc: 'leave coding mode (session keeps running)',
     help: 'show commands',
-    clear: 'clear conversation',
+    clear: 'clear the transcript on screen',
     quit: 'exit',
 };
 export function resolveSlash(input) {
@@ -43,13 +53,49 @@ export function getSuggestion(partial) {
     const match = SLASH_COMMANDS.find(c => c.startsWith(p) && c !== p);
     return match ? `/${match}` : '';
 }
+// ── Multi-line input ────────────────────────────────────────────
+/**
+ * Whether a submitted line asks to keep typing.
+ *
+ * A single-line prompt still has to accept a paragraph, so a trailing
+ * backslash continues onto the next line the way a shell does. Returns
+ * the text without the continuation marker, or null when the line is
+ * complete.
+ */
+export function continuationOf(value) {
+    if (!/\\$/.test(value))
+        return null;
+    // An escaped backslash at the end is a literal one, not a hinge.
+    const trailing = value.length - value.replace(/\\+$/, '').length;
+    if (trailing % 2 === 0)
+        return null;
+    return value.slice(0, -1);
+}
+/**
+ * A pasted block, as one message.
+ *
+ * A multi-line paste used to submit on its first newline and hand the
+ * rest to the prompt a line at a time — so a pasted stack trace became
+ * a dozen messages, and any line of it starting with `/` ran as a
+ * command. Newlines inside a submitted value are content.
+ */
+export function joinSubmission(lines) {
+    return lines.join('\n').replace(/\s+$/, '');
+}
+/** Whether a submission should be read as a slash command. */
+export function isSlashCommand(value) {
+    const trimmed = value.trim();
+    // Only a single-line submission can be a command: a pasted block that
+    // happens to begin with a slash is text.
+    return trimmed.startsWith('/') && !trimmed.includes('\n');
+}
 /**
  * Where a submitted line goes: slash commands are always commands; when a
  * coding session is active, everything else routes to the session's stdin;
  * otherwise it's a normal chat message.
  */
 export function classifyInput(value, codingActive) {
-    if (value.trim().startsWith('/'))
+    if (isSlashCommand(value))
         return 'command';
     return codingActive ? 'coding' : 'chat';
 }

package/dist/components.d.ts

@@ -13,13 +13,19 @@ export declare function InlineFormat({ text }: {
     text: string;
 }): React.JSX.Element;
 export declare function boldify(text: string): React.ReactElement;
+/**
+ * Re-exported so callers do not have to know the arithmetic moved.
+ * Takes a message rather than text, which is how it has always read.
+ */
 export declare function estimateLines(msg: Message, cols: number): number;
-export declare function MessageWindow({ messages, loading, loadingLabel, maxRows, scrollOffset }: {
+export declare function MessageWindow({ messages, loading, loadingLabel, maxRows, scrollOffset, streaming }: {
     messages: Message[];
     loading: boolean;
     loadingLabel: string;
     maxRows: number;
     scrollOffset?: number;
+    /** Assistant text arriving right now, drawn below the transcript. */
+    streaming?: string;
 }): React.JSX.Element;
 export declare function Header({ agent, conversationId }: {
     agent: AgentInfo;

package/dist/components.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import Spinner from 'ink-spinner';
+import { columns, estimateLines as estimateMessageLines, selectWindow } from './viewport.js';
 // ── Simple markdown rendering ───────────────────────────────────
 export function MarkdownText({ children, prefix, prefixColor }) {
     const lines = children.split('\n');
@@ -90,35 +91,26 @@ export function boldify(text) {
     }
     return _jsx(_Fragment, { children: parts });
 }
-// ── Message window (manual scroll) ──────────────────────────────
+// ── Message window (bounded to the terminal) ────────────────────
+/**
+ * Re-exported so callers do not have to know the arithmetic moved.
+ * Takes a message rather than text, which is how it has always read.
+ */
 export function estimateLines(msg, cols) {
-    const textWidth = Math.max(cols - 10, 20);
-    const lines = msg.text.split('\n');
-    let total = 1; // margin
-    for (const line of lines) {
-        total += Math.max(1, Math.ceil(Math.max(line.length, 1) / textWidth));
-    }
-    return total;
+    return estimateMessageLines(msg.text, cols);
 }
-export function MessageWindow({ messages, loading, loadingLabel, maxRows, scrollOffset = 0 }) {
-    const cols = process.stdout.columns || 80;
-    const available = Math.max(maxRows, 5);
-    // Calculate the end of the visible window (shifted by scrollOffset)
-    const endIdx = Math.max(0, messages.length - scrollOffset);
-    // Walk backwards from endIdx to find how many messages fit
-    let usedRows = loading && scrollOffset === 0 ? 2 : 0;
-    let startIdx = endIdx;
-    for (let i = endIdx - 1; i >= 0; i--) {
-        const est = estimateLines(messages[i], cols);
-        if (usedRows + est > available && i < endIdx - 1)
-            break;
-        usedRows += est;
-        startIdx = i;
-    }
+export function MessageWindow({ messages, loading, loadingLabel, maxRows, scrollOffset = 0, streaming }) {
+    const cols = columns(process.stdout.columns);
+    const streamRows = streaming ? estimateMessageLines(streaming, cols) : 0;
+    const { startIdx, endIdx, hiddenBefore, hiddenAfter } = selectWindow(messages, {
+        rows: maxRows,
+        cols,
+        // The spinner and the text still arriving both need room.
+        reservedRows: (loading && scrollOffset === 0 ? 2 : 0) + streamRows,
+        scrollOffset,
+    });
     const visible = messages.slice(startIdx, endIdx);
-    const hasEarlier = startIdx > 0;
-    const hasLater = endIdx < messages.length;
-    return (_jsxs(Box, { flexDirection: "column", children: [hasEarlier && (_jsx(Box, { paddingLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2191 ", startIdx, " earlier \u00B7 scroll to see more"] }) })), visible.map((msg, i) => (_jsx(MessageView, { msg: msg }, startIdx + i))), loading && scrollOffset === 0 && _jsx(LoadingIndicator, { label: loadingLabel }), hasLater && (_jsx(Box, { paddingLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2193 ", messages.length - endIdx, " newer \u00B7 scroll to see more"] }) }))] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [hiddenBefore > 0 && (_jsx(Box, { paddingLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2191 ", hiddenBefore, " earlier \u00B7 scroll to see more"] }) })), visible.map((msg, i) => (_jsx(MessageView, { msg: msg }, startIdx + i))), streaming && scrollOffset === 0 && _jsx(MessageView, { msg: { role: 'agent', text: streaming } }), loading && scrollOffset === 0 && _jsx(LoadingIndicator, { label: loadingLabel }), hiddenAfter > 0 && (_jsx(Box, { paddingLeft: 2, children: _jsxs(Text, { dimColor: true, children: ["\u2193 ", hiddenAfter, " newer \u00B7 scroll to see more"] }) }))] }));
 }
 // ── Components ──────────────────────────────────────────────────
 export function Header({ agent, conversationId }) {

package/dist/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One sentence a user can act on, for every way a chat session fails.
+ *
+ * A REPL that answers "API error 400: {"success":false,...}" has told the
+ * user nothing. Every failure a session can reach has a cause and a next
+ * step, and both are known here rather than left for the reader to infer
+ * from a status code.
+ *
+ * Kept free of ink and of the network client so it can be tested as the
+ * pure mapping it is.
+ */
+/** What the session knows about itself when something fails. */
+export interface ErrorContext {
+    /** `<org>/<agent-slug>`, as the user typed it. */
+    agentRef?: string;
+    /** API base URL, for "cannot reach" messages. */
+    apiUrl?: string;
+    /** Dashboard URL, for "fix it here" messages. */
+    appUrl?: string;
+    /** What the session was doing: shapes the timeout wording. */
+    what?: 'run' | 'info' | 'history' | 'stream' | 'cancel';
+}
+export declare const DEFAULT_APP_URL = "https://app.almyty.com";
+interface Failure {
+    status?: number;
+    code?: string;
+    serverMessage?: string;
+    message: string;
+    network: boolean;
+    aborted: boolean;
+    pollTimeout: boolean;
+}
+/** Pull everything useful off a thrown value, whatever shape it has. */
+export declare function inspectError(err: unknown): Failure;
+/** The model name out of a MODEL_NOT_FOUND message, when it names one. */
+export declare function extractModelName(message: string): string | null;
+/**
+ * Turn a thrown value into one sentence, plus the command or URL that
+ * fixes it.
+ */
+export declare function explainError(err: unknown, ctx?: ErrorContext): string;
+/**
+ * Why `<org>/<agent>` could not be opened at startup.
+ *
+ * Startup is the one place a bad reference and a bad login look the
+ * same, and where "Agent not found" was printed for both.
+ */
+export declare function explainStartupFailure(err: unknown, ctx?: ErrorContext): string;
+export {};

package/dist/errors.js

@@ -0,0 +1,144 @@
+/**
+ * One sentence a user can act on, for every way a chat session fails.
+ *
+ * A REPL that answers "API error 400: {"success":false,...}" has told the
+ * user nothing. Every failure a session can reach has a cause and a next
+ * step, and both are known here rather than left for the reader to infer
+ * from a status code.
+ *
+ * Kept free of ink and of the network client so it can be tested as the
+ * pure mapping it is.
+ */
+export const DEFAULT_APP_URL = 'https://app.almyty.com';
+/** Pull everything useful off a thrown value, whatever shape it has. */
+export function inspectError(err) {
+    const e = (err ?? {});
+    const message = typeof e.message === 'string' && e.message ? e.message : String(err ?? 'Unknown error');
+    let status = typeof e.status === 'number' ? e.status : undefined;
+    if (status === undefined) {
+        // Errors that crossed a package boundary as plain strings.
+        const m = message.match(/^(?:API error|SSE) (\d{3})/);
+        if (m)
+            status = Number(m[1]);
+    }
+    let code;
+    let serverMessage;
+    const body = typeof e.body === 'string' ? e.body : message;
+    const jsonStart = body.indexOf('{');
+    if (jsonStart !== -1) {
+        try {
+            const parsed = JSON.parse(body.slice(jsonStart));
+            if (parsed && typeof parsed === 'object') {
+                if (typeof parsed.error === 'string')
+                    code = parsed.error;
+                if (typeof parsed.code === 'string')
+                    code = parsed.code;
+                if (typeof parsed.message === 'string')
+                    serverMessage = parsed.message;
+            }
+        }
+        catch {
+            /* not JSON; the raw message is all there is */
+        }
+    }
+    if (!code && typeof e.code === 'string' && /^[A-Z_]+$/.test(e.code))
+        code = e.code;
+    const errno = typeof e.code === 'string' ? e.code : e.cause?.code;
+    const network = e.networkError === true ||
+        ['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'UND_ERR_SOCKET'].includes(errno) ||
+        /fetch failed|network|socket hang up|ECONNRESET/i.test(message);
+    return {
+        status,
+        code,
+        serverMessage,
+        message,
+        network,
+        aborted: e.name === 'AbortError' || e.code === 'ABORT_ERR',
+        pollTimeout: e.pollTimeout === true || /did not finish within/.test(message),
+    };
+}
+/** The model name out of a MODEL_NOT_FOUND message, when it names one. */
+export function extractModelName(message) {
+    const quoted = message.match(/"([^"]{2,80})"\s+is not available/) || message.match(/model\s+"([^"]{2,80})"/i);
+    return quoted ? quoted[1] : null;
+}
+/**
+ * Turn a thrown value into one sentence, plus the command or URL that
+ * fixes it.
+ */
+export function explainError(err, ctx = {}) {
+    const f = inspectError(err);
+    const ref = ctx.agentRef ?? 'this agent';
+    const app = ctx.appUrl ?? DEFAULT_APP_URL;
+    if (f.aborted)
+        return 'Cancelled.';
+    if (f.network) {
+        const host = ctx.apiUrl ?? 'the almyty API';
+        return `Cannot reach ${host}. Check your connection, or ALMYTY_URL if you are pointing at your own deployment.`;
+    }
+    // Codes first: the server names the cause, so use its word for it.
+    switch (f.code) {
+        case 'AGENT_NOT_ACTIVE':
+            return `${ref} is not active, so it will not answer. Open ${app}/agents, activate it, and try again.`;
+        case 'AGENT_AUTH_REQUIRED':
+        case 'AGENT_AUTH_INVALID':
+            return 'Not authenticated. Run: npx @almyty/auth login';
+        case 'AGENT_AUTH_EXPIRED':
+            return 'Your credentials have expired. Run: npx @almyty/auth login';
+        case 'AGENT_AUTH_FORBIDDEN':
+            return `Your account has no access to the organization that owns ${ref}. Check the org in the reference, or log in as an account that does: npx @almyty/auth login`;
+        case 'MODEL_NOT_FOUND': {
+            const model = extractModelName(f.serverMessage ?? f.message);
+            return `${ref} is configured to use ${model ? `the model ${model}, which` : 'a model that'} its provider no longer serves. Pick a model that is available at ${app}/agents — scheduled runs stay paused until you do.`;
+        }
+        case 'BUDGET_EXCEEDED':
+        case 'SPEND_LIMIT_EXCEEDED':
+            return `This organization has reached its spend cap, so no new model calls will run. Raise it or wait for the period to reset at ${app}/settings.`;
+    }
+    const body = f.serverMessage ?? f.message;
+    if (/MODEL_NOT_FOUND|is not available/i.test(body)) {
+        const model = extractModelName(body);
+        return `${ref} is configured to use ${model ? `the model ${model}, which` : 'a model that'} its provider no longer serves. Pick a model that is available at ${app}/agents — scheduled runs stay paused until you do.`;
+    }
+    if (/no LLM provider configured|modelConfig\.providerId/i.test(body)) {
+        return `${ref} has no model configured. Open it at ${app}/agents and choose a model or a routing policy.`;
+    }
+    if (/not autonomous/i.test(body)) {
+        return `${ref} is a workflow agent, so it has no multi-turn run to continue. It answers one message at a time and that is what this session will do.`;
+    }
+    if (/budget|spend (cap|limit)|quota/i.test(body)) {
+        return `This organization has reached its spend cap, so no new model calls will run. Raise it or wait for the period to reset at ${app}/settings.`;
+    }
+    if (f.pollTimeout) {
+        return 'The run is taking longer than this session will wait. It is still going server-side — reconnect with --resume once it finishes, or stop it from the dashboard.';
+    }
+    switch (f.status) {
+        case 400:
+            return `${ref} rejected the request: ${body}`;
+        case 401:
+            return 'Not authenticated, or the stored token has expired. Run: npx @almyty/auth login';
+        case 403:
+            return `Your account has no access to ${ref}. Check the organization in the reference, or log in as an account that does: npx @almyty/auth login`;
+        case 404:
+            return `No agent at ${ref}. See what you can reach with: npx @almyty/agents list`;
+        case 409:
+            return `${ref} is busy with a conflicting request: ${body}`;
+        case 429:
+            return 'Rate limited. Wait a few seconds and send it again.';
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return `almyty's API answered ${f.status}. This is server-side — retry in a moment, and check status if it keeps happening.`;
+    }
+    return body;
+}
+/**
+ * Why `<org>/<agent>` could not be opened at startup.
+ *
+ * Startup is the one place a bad reference and a bad login look the
+ * same, and where "Agent not found" was printed for both.
+ */
+export function explainStartupFailure(err, ctx = {}) {
+    return explainError(err, { ...ctx, what: 'info' });
+}