@almyty/chat 0.2.0 → 1.3.0

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' });
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,32 @@
+export declare const EXIT: {
+    /** Success. */
+    readonly OK: 0;
+    /** Unexpected failure (a thrown error with no better classification). */
+    readonly ERROR: 1;
+    /** Bad or missing arguments, or an unknown command. */
+    readonly USAGE: 2;
+    /** No stored credential, or the API rejected the one we had. */
+    readonly AUTH: 3;
+    /** The named agent / gateway / skill / run does not exist. */
+    readonly NOT_FOUND: 4;
+    /** The command ran; the operation it asked for failed. */
+    readonly FAILED: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** One line per code, for `--help` output and READMEs. */
+export declare const EXIT_CODE_HELP: string;
+/**
+ * Classify a thrown value into an exit code.
+ *
+ * The sibling CLIs read the status back out of the message string.
+ * This one does not have to: the shared client now puts `status` on
+ * the error it throws, which `inspectError` reads.
+ */
+export declare function exitCodeForError(err: unknown): ExitCode;
+/**
+ * The exit code a finished turn earns, so a chat call can gate a shell
+ * script: a run that ran and failed is 5, not 1, so
+ * `almyty chat deploy-check -m "ok?" || case $? in 5) ...` can tell a
+ * failed answer from a broken invocation.
+ */
+export declare function exitCodeForStatus(status: 'completed' | 'failed' | 'cancelled' | 'waiting_input'): ExitCode;

package/dist/exit-codes.js

@@ -0,0 +1,65 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+import { inspectError } from './errors.js';
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Unexpected failure (a thrown error with no better classification). */
+    ERROR: 1,
+    /** Bad or missing arguments, or an unknown command. */
+    USAGE: 2,
+    /** No stored credential, or the API rejected the one we had. */
+    AUTH: 3,
+    /** The named agent / gateway / skill / run does not exist. */
+    NOT_FOUND: 4,
+    /** The command ran; the operation it asked for failed. */
+    FAILED: 5,
+};
+/** One line per code, for `--help` output and READMEs. */
+export const EXIT_CODE_HELP = [
+    '  0  success',
+    '  1  unexpected error',
+    '  2  usage error (bad flags, unknown command)',
+    '  3  not authenticated — run `almyty login`',
+    '  4  not found (agent, gateway, skill, or run)',
+    '  5  the operation ran and failed',
+].join('\n');
+/**
+ * Classify a thrown value into an exit code.
+ *
+ * The sibling CLIs read the status back out of the message string.
+ * This one does not have to: the shared client now puts `status` on
+ * the error it throws, which `inspectError` reads.
+ */
+export function exitCodeForError(err) {
+    const f = inspectError(err);
+    if (f.aborted)
+        return EXIT.FAILED;
+    if (f.network)
+        return EXIT.ERROR;
+    if (f.code === 'AGENT_AUTH_REQUIRED' || f.code === 'AGENT_AUTH_INVALID' || f.code === 'AGENT_AUTH_EXPIRED')
+        return EXIT.AUTH;
+    if (f.status === 401 || f.status === 403 || f.code === 'AGENT_AUTH_FORBIDDEN')
+        return EXIT.AUTH;
+    if (f.status === 404)
+        return EXIT.NOT_FOUND;
+    if (f.status !== undefined && f.status >= 400)
+        return EXIT.FAILED;
+    return EXIT.ERROR;
+}
+/**
+ * The exit code a finished turn earns, so a chat call can gate a shell
+ * script: a run that ran and failed is 5, not 1, so
+ * `almyty chat deploy-check -m "ok?" || case $? in 5) ...` can tell a
+ * failed answer from a broken invocation.
+ */
+export function exitCodeForStatus(status) {
+    return status === 'completed' || status === 'waiting_input' ? EXIT.OK : EXIT.FAILED;
+}

package/dist/headless.d.ts

@@ -0,0 +1,44 @@
+/**
+ * chat without a terminal.
+ *
+ * A CLI that only draws to a tty cannot be piped, scripted or put in
+ * CI, which is half of what a CLI is for. This path answers one
+ * question — from --message, or from stdin — writes the answer to
+ * stdout, writes attribution to stderr so stdout stays clean for a
+ * pipe, and exits 0 or 1 on whether the run actually completed.
+ *
+ * `--json` prints one object per answer instead, with the text, the
+ * cost and the ids needed to resume.
+ */
+import type { AgentInfo, RunLimits } from '@almyty/client';
+import { type ErrorContext } from './errors.js';
+import { type TurnResult, type TurnTarget } from './turn.js';
+export interface HeadlessIO {
+    out(text: string): void;
+    err(text: string): void;
+}
+export interface HeadlessOptions {
+    message: string;
+    agent: AgentInfo;
+    target: TurnTarget;
+    json: boolean;
+    /** False buffers the answer and prints it once. */
+    stream: boolean;
+    conversationId?: string;
+    limits?: RunLimits;
+    signal?: AbortSignal;
+    io: HeadlessIO;
+    errorContext?: ErrorContext;
+}
+/** Everything --json promises, in one object. */
+export declare function jsonResult(result: TurnResult, agent: AgentInfo): Record<string, unknown>;
+/** Read all of stdin, for `echo "..." | almyty chat <agent> --stdin`. */
+export declare function readStdin(stream: AsyncIterable<string | Buffer>): Promise<string>;
+/**
+ * Answer once and return the process exit code.
+ *
+ * Streaming to a pipe writes the tokens as they arrive, which is what
+ * makes `almyty chat bot -m "..." | less` feel alive; --json buffers,
+ * because half a JSON object is not JSON.
+ */
+export declare function runHeadless(options: HeadlessOptions): Promise<number>;

package/dist/headless.js

@@ -0,0 +1,106 @@
+/**
+ * chat without a terminal.
+ *
+ * A CLI that only draws to a tty cannot be piped, scripted or put in
+ * CI, which is half of what a CLI is for. This path answers one
+ * question — from --message, or from stdin — writes the answer to
+ * stdout, writes attribution to stderr so stdout stays clean for a
+ * pipe, and exits 0 or 1 on whether the run actually completed.
+ *
+ * `--json` prints one object per answer instead, with the text, the
+ * cost and the ids needed to resume.
+ */
+import { explainError } from './errors.js';
+import { exitCodeForError, exitCodeForStatus } from './exit-codes.js';
+import { formatUsage } from './stream.js';
+import { runTurn } from './turn.js';
+/** Everything --json promises, in one object. */
+export function jsonResult(result, agent) {
+    return {
+        status: result.status,
+        output: result.text,
+        agent: { id: agent.id, name: agent.name, slug: agent.slug, mode: agent.mode },
+        model: result.usage.model ?? null,
+        routing: result.usage.model
+            ? { model: result.usage.model, rationale: result.usage.rationale ?? null, attempt: result.usage.attempt ?? null }
+            : null,
+        usage: { cost: result.usage.cost, tokens: result.usage.tokens, steps: result.usage.steps },
+        runId: result.runId ?? null,
+        conversationId: result.conversationId ?? null,
+        ...(result.error ? { error: result.error } : {}),
+    };
+}
+/** Read all of stdin, for `echo "..." | almyty chat <agent> --stdin`. */
+export async function readStdin(stream) {
+    const parts = [];
+    for await (const chunk of stream)
+        parts.push(typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
+    return parts.join('').trim();
+}
+/**
+ * Answer once and return the process exit code.
+ *
+ * Streaming to a pipe writes the tokens as they arrive, which is what
+ * makes `almyty chat bot -m "..." | less` feel alive; --json buffers,
+ * because half a JSON object is not JSON.
+ */
+export async function runHeadless(options) {
+    const { io, json, agent } = options;
+    let written = 0;
+    try {
+        const result = await runTurn(options.target, options.message, {
+            mode: agent.mode,
+            conversationId: options.conversationId,
+            limits: options.limits,
+            signal: options.signal,
+            hooks: json || !options.stream
+                ? undefined
+                : {
+                    partial: (text) => {
+                        // Only the new tail: the reducer hands back the whole
+                        // buffer each time.
+                        if (text.length > written) {
+                            io.out(text.slice(written));
+                            written = text.length;
+                        }
+                    },
+                },
+        });
+        if (json) {
+            io.out(JSON.stringify(jsonResult(result, agent), null, 2) + '\n');
+            return exitCodeForStatus(result.status);
+        }
+        if (options.stream) {
+            // Anything the stream did not already print (a non-streaming
+            // provider, or a final output that replaced the buffer).
+            if (result.text.length > written)
+                io.out(result.text.slice(written));
+            if (result.text)
+                io.out('\n');
+        }
+        else if (result.text) {
+            io.out(result.text + '\n');
+        }
+        const attribution = formatUsage(result.usage);
+        if (attribution)
+            io.err(attribution + '\n');
+        if (result.status === 'failed')
+            io.err(`Run failed: ${result.error ?? 'no reason given'}\n`);
+        if (result.status === 'cancelled')
+            io.err('Cancelled.\n');
+        if (result.status === 'waiting_input' && result.conversationId) {
+            io.err(`The agent asked a question. Continue with: almyty chat ${agent.slug ?? agent.name} --resume ${result.conversationId}\n`);
+        }
+        return exitCodeForStatus(result.status);
+    }
+    catch (err) {
+        const message = explainError(err, options.errorContext);
+        if (json) {
+            io.out(JSON.stringify({ status: 'error', error: message }, null, 2) + '\n');
+        }
+        else {
+            io.err(message + '\n');
+        }
+        return exitCodeForError(err);
+    }
+}

package/dist/history.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Input history that survives the session.
+ *
+ * History used to be derived from the messages on screen, so it emptied
+ * on /clear and every new session started with nothing to press up
+ * into. It is kept in a file next to the credentials instead, one entry
+ * per line, oldest first.
+ *
+ * Nothing the agent says is written here — only what the user typed —
+ * and slash commands are kept because re-running one is the common case.
+ */
+/** How many lines are kept. Beyond this the oldest are dropped. */
+export declare const HISTORY_LIMIT = 500;
+/** Longest line kept, so a pasted file cannot bloat the file. */
+export declare const HISTORY_MAX_LINE = 4000;
+export declare function historyFile(env?: Record<string, string | undefined>): string;
+/** Newlines are the record separator, so they are escaped on the way in. */
+export declare function encodeEntry(value: string): string;
+export declare function decodeEntry(value: string): string;
+/**
+ * How many appends go by before the file is trimmed.
+ *
+ * Trimming reads and rewrites the whole file, so doing it on every
+ * message put two extra filesystem round-trips in front of every turn.
+ * The file is allowed to run a little over the limit between trims.
+ */
+export declare const TRIM_EVERY = 50;
+/** Forget the in-process memo. Tests use this; nothing else needs it. */
+export declare function resetHistoryState(): void;
+/** Oldest first. Never throws: no history is a worse day, not a crash. */
+export declare function loadHistory(file?: string): string[];
+/** Cut the file back to the newest HISTORY_LIMIT entries. */
+export declare function trimHistory(file?: string): void;
+/**
+ * Append one entry, skipping a repeat of the line before it.
+ *
+ * One filesystem write on the common path: this runs on the keystroke
+ * that submits a message, so it is not the place for a read, a mkdir
+ * and a rewrite.
+ */
+export declare function appendHistory(entry: string, file?: string): void;
+/**
+ * Where up/down land, given how far back the cursor already is.
+ *
+ * `idx` is -1 for "at the live prompt" and counts backwards from the
+ * newest entry. Returns the new index and the text to show.
+ */
+export declare function walkHistory(history: string[], idx: number, direction: 'up' | 'down'): {
+    idx: number;
+    value: string;
+};

package/dist/history.js

@@ -0,0 +1,146 @@
+/**
+ * Input history that survives the session.
+ *
+ * History used to be derived from the messages on screen, so it emptied
+ * on /clear and every new session started with nothing to press up
+ * into. It is kept in a file next to the credentials instead, one entry
+ * per line, oldest first.
+ *
+ * Nothing the agent says is written here — only what the user typed —
+ * and slash commands are kept because re-running one is the common case.
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** How many lines are kept. Beyond this the oldest are dropped. */
+export const HISTORY_LIMIT = 500;
+/** Longest line kept, so a pasted file cannot bloat the file. */
+export const HISTORY_MAX_LINE = 4000;
+export function historyFile(env = process.env) {
+    if (env.ALMYTY_CHAT_HISTORY)
+        return env.ALMYTY_CHAT_HISTORY;
+    return join(homedir(), '.almyty', 'chat-history');
+}
+/** Newlines are the record separator, so they are escaped on the way in. */
+export function encodeEntry(value) {
+    return value.replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+export function decodeEntry(value) {
+    let out = '';
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] === '\\' && i + 1 < value.length) {
+            const next = value[i + 1];
+            if (next === 'n') {
+                out += '\n';
+                i++;
+                continue;
+            }
+            if (next === '\\') {
+                out += '\\';
+                i++;
+                continue;
+            }
+        }
+        out += value[i];
+    }
+    return out;
+}
+/**
+ * How many appends go by before the file is trimmed.
+ *
+ * Trimming reads and rewrites the whole file, so doing it on every
+ * message put two extra filesystem round-trips in front of every turn.
+ * The file is allowed to run a little over the limit between trims.
+ */
+export const TRIM_EVERY = 50;
+/** Last entry written per file, so a repeat costs no read. */
+const lastAppended = new Map();
+const appendsSinceTrim = new Map();
+/** Forget the in-process memo. Tests use this; nothing else needs it. */
+export function resetHistoryState() {
+    lastAppended.clear();
+    appendsSinceTrim.clear();
+}
+/** Oldest first. Never throws: no history is a worse day, not a crash. */
+export function loadHistory(file = historyFile()) {
+    try {
+        return readFileSync(file, 'utf-8')
+            .split('\n')
+            .filter((line) => line.length > 0)
+            .map(decodeEntry);
+    }
+    catch {
+        return [];
+    }
+}
+/** Cut the file back to the newest HISTORY_LIMIT entries. */
+export function trimHistory(file = historyFile()) {
+    try {
+        const entries = loadHistory(file);
+        if (entries.length <= HISTORY_LIMIT)
+            return;
+        writeFileSync(file, entries.slice(entries.length - HISTORY_LIMIT).map(encodeEntry).join('\n') + '\n', 'utf-8');
+    }
+    catch {
+        /* a history file we cannot rewrite is not worth failing a turn over */
+    }
+}
+/**
+ * Append one entry, skipping a repeat of the line before it.
+ *
+ * One filesystem write on the common path: this runs on the keystroke
+ * that submits a message, so it is not the place for a read, a mkdir
+ * and a rewrite.
+ */
+export function appendHistory(entry, file = historyFile()) {
+    const value = entry.trim();
+    if (!value || value.length > HISTORY_MAX_LINE)
+        return;
+    if (lastAppended.get(file) === value)
+        return;
+    try {
+        const line = encodeEntry(value) + '\n';
+        try {
+            appendFileSync(file, line, 'utf-8');
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
+            mkdirSync(dirname(file), { recursive: true });
+            appendFileSync(file, line, 'utf-8');
+        }
+        lastAppended.set(file, value);
+        const count = (appendsSinceTrim.get(file) ?? 0) + 1;
+        if (count >= TRIM_EVERY) {
+            appendsSinceTrim.set(file, 0);
+            trimHistory(file);
+        }
+        else {
+            appendsSinceTrim.set(file, count);
+        }
+    }
+    catch {
+        /* history is a convenience, never a reason to fail a turn */
+    }
+}
+/**
+ * Where up/down land, given how far back the cursor already is.
+ *
+ * `idx` is -1 for "at the live prompt" and counts backwards from the
+ * newest entry. Returns the new index and the text to show.
+ */
+export function walkHistory(history, idx, direction) {
+    if (direction === 'up') {
+        if (!history.length)
+            return { idx, value: '' };
+        const next = Math.min(idx + 1, history.length - 1);
+        return { idx: next, value: history[history.length - 1 - next] };
+    }
+    if (idx > 0) {
+        const next = idx - 1;
+        return { idx: next, value: history[history.length - 1 - next] };
+    }
+    if (idx === 0)
+        return { idx: -1, value: '' };
+    return { idx, value: '' };
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export declare const VERSION = "0.2.0";
+import { VERSION } from './version.js';
+export { VERSION };