@almyty/chat 0.2.0 → 1.3.0

package/dist/index.js

@@ -1,60 +1,93 @@
 #!/usr/bin/env node
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { render, Box, Text } from 'ink';
-import { AlmytyClient, resolveCredentialsOrExit, getOrgSlugFromToken } from '@almyty/client';
+import { AlmytyClient, resolveCredentials, getOrgSlugFromToken } from '@almyty/client';
 import { AgentSelector } from './components.js';
 import { ChatApp, exitMessage } from './app.js';
-export const VERSION = '0.2.0';
+import { helpText, isNonInteractive, parseArgs, resolveRef, splitRef, useColor } from './args.js';
+import { explainError, DEFAULT_APP_URL } from './errors.js';
+import { EXIT, exitCodeForError } from './exit-codes.js';
+import { readStdin, runHeadless } from './headless.js';
+import { VERSION } from './version.js';
+export { VERSION };
+function limitsFrom(args) {
+    if (args.maxSteps === undefined && args.maxCostCents === undefined)
+        return undefined;
+    return {
+        ...(args.maxSteps !== undefined ? { maxSteps: args.maxSteps } : {}),
+        ...(args.maxCostCents !== undefined ? { maxCostCents: args.maxCostCents } : {}),
+    };
+}
 // ── Entry point ─────────────────────────────────────────────────
 async function main() {
-    const argv = process.argv.slice(2);
-    if (argv.includes('--version') || argv.includes('-v')) {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.error) {
+        console.error(args.error);
+        process.exit(EXIT.USAGE);
+    }
+    if (args.version) {
         console.log(VERSION);
         return;
     }
-    if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(`almyty chat v${VERSION}\n\nUsage:\n  npx @almyty/chat <org>/<agent-slug>\n  npx @almyty/chat <org>/<agent-slug> --resume <conversation-id>\n\nExamples:\n  npx @almyty/chat acme/support-bot\n  npx @almyty/chat myorg/my-agent --resume 60d93c85-...\n\nCommands:\n  /help /agents /clear /quit\n\nAuth:\n  npx @almyty/auth login`);
+    if (args.help) {
+        console.log(helpText(VERSION));
         return;
     }
-    const creds = resolveCredentialsOrExit();
-    const client = new AlmytyClient(creds.url, creds.token);
-    let resumeId;
-    const ri = Math.max(argv.indexOf('--resume'), argv.indexOf('-resume'));
-    if (ri !== -1) {
-        resumeId = argv[ri + 1];
-        if (!resumeId || resumeId.startsWith('-')) {
-            console.error('--resume requires a conversation id');
-            process.exit(1);
-        }
+    const creds = resolveCredentials();
+    if (!creds) {
+        // Said once, in full, rather than as a 401 three calls later.
+        console.error('Not authenticated. Run one of:');
+        console.error('  npx @almyty/auth login');
+        console.error('  export ALMYTY_TOKEN=<your-token>');
+        process.exit(EXIT.AUTH);
     }
-    const ref = argv.find(arg => !arg.startsWith('-') && arg !== resumeId);
-    // Resolve org slug — from ref (org/slug) or JWT token
+    const client = new AlmytyClient(creds.url, creds.token);
+    const appUrl = process.env.ALMYTY_APP_URL || creds.frontendUrl || DEFAULT_APP_URL;
+    const headless = isNonInteractive(args, {
+        stdinTty: process.stdin.isTTY === true,
+        stdoutTty: process.stdout.isTTY === true,
+    });
+    const ref = resolveRef(args);
     const defaultOrg = getOrgSlugFromToken(creds.token);
     let orgSlug;
     let agentSlug;
-    if (ref && ref.includes('/')) {
-        [orgSlug, agentSlug] = ref.split('/', 2);
-    }
-    else if (ref) {
-        // Bare slug — use org from JWT
-        if (!defaultOrg) {
-            console.error('Cannot determine org. Use org/agent-slug format or log in: npx @almyty/auth login');
-            process.exit(1);
+    if (ref) {
+        const parts = splitRef(ref);
+        if (parts.orgSlug) {
+            orgSlug = parts.orgSlug;
+            agentSlug = parts.agentSlug;
+        }
+        else {
+            if (!defaultOrg) {
+                console.error('Cannot tell which organization to use. Pass <org>/<agent-slug>, or log in again: npx @almyty/auth login');
+                process.exit(EXIT.USAGE);
+            }
+            orgSlug = defaultOrg;
+            agentSlug = parts.agentSlug;
         }
-        orgSlug = defaultOrg;
-        agentSlug = ref;
+    }
+    else if (headless) {
+        // There is nobody to answer a picker on a pipe.
+        console.error('No agent given. Pass <org>/<agent-slug>, or set ALMYTY_AGENT.');
+        process.exit(EXIT.USAGE);
     }
     else {
-        // No arg — interactive picker
         if (!defaultOrg) {
-            console.error('Usage: npx @almyty/chat <org>/<agent-slug>');
-            process.exit(1);
+            console.error('Usage: almyty chat <org>/<agent-slug>');
+            process.exit(EXIT.USAGE);
         }
         orgSlug = defaultOrg;
-        const agents = await client.listAgents();
+        let agents;
+        try {
+            agents = await client.listAgents();
+        }
+        catch (err) {
+            console.error(explainError(err, { apiUrl: creds.url, appUrl }));
+            process.exit(exitCodeForError(err));
+        }
         if (!agents.length) {
-            console.error('No agents found. Create one at https://app.almyty.com/agents');
-            process.exit(1);
+            console.error(`No agents in this organization yet. Create one at ${appUrl}/agents`);
+            process.exit(EXIT.NOT_FOUND);
         }
         if (agents.length === 1) {
             agentSlug = agents[0].slug || agents[0].name.toLowerCase().replace(/\s+/g, '-');
@@ -69,21 +102,60 @@ async function main() {
         }
     }
     const gw = client.gateway(orgSlug, agentSlug);
+    const errorContext = { agentRef: `${orgSlug}/${agentSlug}`, apiUrl: creds.url, appUrl };
     let agent;
     try {
         agent = await gw.getInfo();
     }
-    catch {
-        console.error(`Agent not found: ${orgSlug}/${agentSlug}`);
-        process.exit(1);
+    catch (err) {
+        // "Agent not found" used to be printed for a bad login, a wrong
+        // org, a draft agent and an unreachable API alike.
+        console.error(explainError(err, { ...errorContext, what: 'info' }));
+        process.exit(exitCodeForError(err));
+    }
+    if (headless) {
+        const message = args.message ?? (await readStdin(process.stdin));
+        if (!message) {
+            console.error('Nothing to ask. Pass --message "<question>", or pipe it in.');
+            process.exit(EXIT.USAGE);
+        }
+        // Ctrl-C on a pipe cancels the run rather than orphaning it.
+        const ac = new AbortController();
+        const onSigint = () => ac.abort();
+        process.on('SIGINT', onSigint);
+        const code = await runHeadless({
+            message,
+            agent,
+            target: gw,
+            json: args.json,
+            stream: args.stream && !args.json,
+            conversationId: args.resume,
+            limits: limitsFrom(args),
+            signal: ac.signal,
+            errorContext,
+            io: {
+                out: (text) => process.stdout.write(text),
+                err: (text) => process.stderr.write(text),
+            },
+        });
+        process.off('SIGINT', onSigint);
+        process.exit(code);
+    }
+    // Colour is decided once, here, so NO_COLOR reaches ink's own
+    // detection rather than being re-derived per component.
+    if (!useColor(args, process.env, process.stdout.isTTY === true)) {
+        process.env.FORCE_COLOR = '0';
     }
-    const { waitUntilExit } = render(_jsx(ChatApp, { client: client, initialAgent: agent, gw: gw, resumeConversationId: resumeId }), { exitOnCtrlC: true });
+    const { waitUntilExit } = render(_jsx(ChatApp, { client: client, initialAgent: agent, gw: gw, resumeConversationId: args.resume, errorContext: errorContext }), 
+    // Ctrl-C is handled inside the app: the first press cancels the
+    // run server-side, and only then does a second one exit.
+    { exitOnCtrlC: false });
     await waitUntilExit();
     if (exitMessage) {
         process.stdout.write(exitMessage);
     }
 }
 main().catch(err => {
-    console.error(err.message);
-    process.exit(1);
+    console.error(explainError(err));
+    process.exit(exitCodeForError(err));
 });

package/dist/stream.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The run stream, reduced.
+ *
+ * Every event a run or a pipeline emits lands here and turns into three
+ * things: the assistant text so far (rendered as it arrives), lines for
+ * the transcript, and a running cost/token tally. Kept pure and free of
+ * ink so both the REPL and the non-interactive path drive the same
+ * reducer, and so it can be tested without a terminal.
+ *
+ * Event shapes come from the backend: run events are
+ * llm.started / llm.chunk / llm.response / tool.started / tool.result /
+ * step.completed / verify.failed / run.completed / run.failed /
+ * run.cancelled; workflow pipelines emit execution.started /
+ * node.started / node.output / node.completed / node.skipped /
+ * execution.completed / execution.failed.
+ */
+import type { StreamEvent } from '@almyty/client';
+export type ActivityRole = 'agent' | 'tool' | 'info' | 'error';
+export interface Activity {
+    role: ActivityRole;
+    text: string;
+}
+/** What a run cost, as far as the stream has said. */
+export interface Usage {
+    /** US dollars. The backend's cost fields are dollars, not cents. */
+    cost: number;
+    tokens: number;
+    steps: number;
+    /** Which model answered, when the server names one. */
+    model?: string;
+    /** Why the router picked it, when routing is in play. */
+    rationale?: string;
+    /** 1-based position of the answering candidate in the routing plan. */
+    attempt?: number;
+}
+export interface StreamState {
+    /** Assistant text streamed so far. Rendered live, not at the end. */
+    partial: string;
+    /** Spinner label: what the agent is doing right now. */
+    label: string;
+    /** Transcript lines produced since the last drain. */
+    emit: Activity[];
+    usage: Usage;
+    /** Terminal output, once a completion event carries one. */
+    output?: string;
+    done: boolean;
+    failed?: string;
+    cancelled: boolean;
+}
+export declare const INITIAL_LABEL = "Thinking";
+export declare function initialStreamState(): StreamState;
+/** Anything the server hands back as an "output", as text. */
+export declare function formatOutput(value: unknown): string;
+/**
+ * Fold one event into the state.
+ *
+ * Returns a new object every time so a React setState sees a change.
+ */
+export declare function reduceStreamEvent(prev: StreamState, event: StreamEvent): StreamState;
+/**
+ * The assistant text a finished stream should show.
+ *
+ * The streamed tokens are preferred over the completion event's output:
+ * they are what the user already watched arrive, and re-rendering a
+ * re-serialised copy of the same answer makes it flicker.
+ */
+export declare function finalText(state: StreamState, fallbackOutput?: unknown): string;
+/** Take the pending transcript lines, leaving the state without them. */
+export declare function drain(state: StreamState): {
+    activities: Activity[];
+    state: StreamState;
+};
+/** Add two tallies, for a session total across turns. */
+export declare function addUsage(a: Usage, b: Usage): Usage;
+/** Dollars, at a precision that does not round a real cost to zero. */
+export declare function formatCost(dollars: number): string;
+export declare function formatTokens(tokens: number): string;
+/**
+ * One line of attribution: what answered, what it cost.
+ *
+ * This is the product's whole argument — many models, routed, with the
+ * bill attached — so a chat session says it out loud rather than
+ * leaving it in an audit log.
+ */
+export declare function formatUsage(usage: Usage): string;
+/**
+ * Model attribution off a finished run's steps.
+ *
+ * The llm.response event does not carry the answering model, so a run
+ * that streamed to completion has to be asked afterwards. Only the
+ * tool-calling step records `routing` today, so a single-step answer
+ * has no attribution to find and this returns null rather than
+ * guessing.
+ */
+export declare function routingFromSteps(steps: unknown): Pick<Usage, 'model' | 'rationale' | 'attempt'> | null;

package/dist/stream.js

@@ -0,0 +1,276 @@
+/**
+ * The run stream, reduced.
+ *
+ * Every event a run or a pipeline emits lands here and turns into three
+ * things: the assistant text so far (rendered as it arrives), lines for
+ * the transcript, and a running cost/token tally. Kept pure and free of
+ * ink so both the REPL and the non-interactive path drive the same
+ * reducer, and so it can be tested without a terminal.
+ *
+ * Event shapes come from the backend: run events are
+ * llm.started / llm.chunk / llm.response / tool.started / tool.result /
+ * step.completed / verify.failed / run.completed / run.failed /
+ * run.cancelled; workflow pipelines emit execution.started /
+ * node.started / node.output / node.completed / node.skipped /
+ * execution.completed / execution.failed.
+ */
+export const INITIAL_LABEL = 'Thinking';
+export function initialStreamState() {
+    return {
+        partial: '',
+        label: INITIAL_LABEL,
+        emit: [],
+        usage: { cost: 0, tokens: 0, steps: 0 },
+        done: false,
+        cancelled: false,
+    };
+}
+/** Anything the server hands back as an "output", as text. */
+export function formatOutput(value) {
+    if (value == null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value, null, 2);
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function str(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+/** A tool's duration, when the event reported one. */
+function duration(ms) {
+    const n = num(ms);
+    if (!n)
+        return '';
+    return n >= 1000 ? ` ${(n / 1000).toFixed(1)}s` : ` ${Math.round(n)}ms`;
+}
+/**
+ * Fold one event into the state.
+ *
+ * Returns a new object every time so a React setState sees a change.
+ */
+export function reduceStreamEvent(prev, event) {
+    const s = { ...prev, emit: [...prev.emit], usage: { ...prev.usage } };
+    const d = (event.data ?? {});
+    switch (event.type) {
+        case 'llm.started':
+            s.label = 'Thinking';
+            return s;
+        case 'llm.chunk': {
+            const chunk = str(d.content);
+            if (chunk)
+                s.partial += chunk;
+            return s;
+        }
+        case 'llm.response': {
+            s.usage.cost += num(d.cost);
+            const usage = (d.usage ?? {});
+            s.usage.tokens += num(usage.totalTokens) || num(usage.inputTokens) + num(usage.outputTokens);
+            const routing = (d.routing ?? {});
+            s.usage.model = str(d.model) ?? str(routing.vendorModelId) ?? str(routing.modelId) ?? s.usage.model;
+            s.usage.rationale = str(routing.rationale) ?? s.usage.rationale;
+            if (typeof routing.attempt === 'number')
+                s.usage.attempt = routing.attempt;
+            const content = str(d.content);
+            const toolCalls = Array.isArray(d.toolCalls) ? d.toolCalls : [];
+            // A provider without token streaming emits no chunks at all, so
+            // the response body is the only copy of the answer.
+            if (content && !s.partial)
+                s.partial = content;
+            // Text that came before a tool call is a preamble, not the
+            // answer: flush it so the tool lines read underneath it, and
+            // start the next step with an empty buffer.
+            if (toolCalls.length) {
+                if (s.partial.trim())
+                    s.emit.push({ role: 'agent', text: s.partial.trim() });
+                s.partial = '';
+                s.label = 'Working';
+            }
+            return s;
+        }
+        case 'tool.started': {
+            const tool = str(d.tool);
+            if (tool) {
+                s.emit.push({ role: 'tool', text: tool });
+                s.label = `Running ${tool}`;
+            }
+            return s;
+        }
+        case 'tool.result': {
+            const tool = str(d.tool) ?? 'tool';
+            const ok = d.success !== false;
+            s.emit.push({
+                role: ok ? 'info' : 'error',
+                text: `${tool} ${ok ? 'ok' : 'failed'}${duration(d.executionTime)}`,
+            });
+            s.label = 'Thinking';
+            return s;
+        }
+        case 'step.completed': {
+            s.usage.steps += 1;
+            const status = str(d.status);
+            if (status === 'waiting_input')
+                s.label = 'Waiting for your input';
+            else if (status === 'sleeping')
+                s.label = 'Sleeping';
+            else if (status === 'revising')
+                s.label = 'Revising';
+            else
+                s.label = 'Thinking';
+            return s;
+        }
+        case 'verify.failed':
+            s.emit.push({ role: 'info', text: 'verification rejected the draft — revising' });
+            s.label = 'Revising';
+            return s;
+        // ── Workflow pipelines ───────────────────────────────────────
+        case 'execution.started':
+            s.label = 'Starting';
+            return s;
+        case 'node.started': {
+            const label = str(d.nodeType) ?? 'node';
+            const id = str(d.nodeId);
+            s.emit.push({ role: 'tool', text: id ? `${label} · ${id}` : label });
+            s.label = `Running ${label}`;
+            return s;
+        }
+        case 'node.completed': {
+            s.usage.cost += num(d.cost);
+            s.usage.tokens += num(d.tokens);
+            s.usage.steps += 1;
+            const error = str(d.error);
+            if (error)
+                s.emit.push({ role: 'error', text: `${str(d.nodeId) ?? 'node'} failed: ${error}` });
+            return s;
+        }
+        case 'node.skipped':
+            s.emit.push({ role: 'info', text: `${str(d.nodeId) ?? 'node'} skipped` });
+            return s;
+        case 'node.output':
+            // Intermediate node output is noise in a chat transcript; the
+            // pipeline's final output arrives on execution.completed.
+            return s;
+        case 'execution.completed': {
+            s.usage.cost += num(d.totalCost);
+            s.usage.tokens += num(d.totalTokens);
+            const output = formatOutput(d.output);
+            if (output)
+                s.output = output;
+            s.done = true;
+            return s;
+        }
+        case 'execution.failed':
+            s.failed = str(d.error) ?? str(d.message) ?? 'The pipeline failed';
+            s.done = true;
+            return s;
+        // ── Autonomous runs ──────────────────────────────────────────
+        case 'run.completed': {
+            const output = formatOutput(d.output);
+            if (output)
+                s.output = output;
+            s.done = true;
+            return s;
+        }
+        case 'run.failed':
+            s.failed = str(d.error) ?? 'The run failed';
+            s.done = true;
+            return s;
+        case 'run.cancelled':
+            s.cancelled = true;
+            s.done = true;
+            return s;
+        default:
+            return s;
+    }
+}
+/**
+ * The assistant text a finished stream should show.
+ *
+ * The streamed tokens are preferred over the completion event's output:
+ * they are what the user already watched arrive, and re-rendering a
+ * re-serialised copy of the same answer makes it flicker.
+ */
+export function finalText(state, fallbackOutput) {
+    const streamed = state.partial.trim();
+    if (streamed)
+        return streamed;
+    if (state.output)
+        return state.output;
+    return formatOutput(fallbackOutput);
+}
+/** Take the pending transcript lines, leaving the state without them. */
+export function drain(state) {
+    if (!state.emit.length)
+        return { activities: [], state };
+    return { activities: state.emit, state: { ...state, emit: [] } };
+}
+/** Add two tallies, for a session total across turns. */
+export function addUsage(a, b) {
+    return {
+        cost: a.cost + b.cost,
+        tokens: a.tokens + b.tokens,
+        steps: a.steps + b.steps,
+        model: b.model ?? a.model,
+        rationale: b.rationale ?? a.rationale,
+        attempt: b.attempt ?? a.attempt,
+    };
+}
+/** Dollars, at a precision that does not round a real cost to zero. */
+export function formatCost(dollars) {
+    if (!dollars)
+        return '$0';
+    if (dollars < 0.01)
+        return `$${dollars.toFixed(4)}`;
+    if (dollars < 1)
+        return `$${dollars.toFixed(3)}`;
+    return `$${dollars.toFixed(2)}`;
+}
+export function formatTokens(tokens) {
+    return tokens.toLocaleString('en-US');
+}
+/**
+ * One line of attribution: what answered, what it cost.
+ *
+ * This is the product's whole argument — many models, routed, with the
+ * bill attached — so a chat session says it out loud rather than
+ * leaving it in an audit log.
+ */
+export function formatUsage(usage) {
+    const parts = [];
+    if (usage.model) {
+        parts.push(usage.attempt && usage.attempt > 1 ? `${usage.model} (attempt ${usage.attempt})` : usage.model);
+    }
+    if (usage.tokens)
+        parts.push(`${formatTokens(usage.tokens)} tok`);
+    if (usage.cost)
+        parts.push(formatCost(usage.cost));
+    if (usage.steps)
+        parts.push(`${usage.steps} step${usage.steps === 1 ? '' : 's'}`);
+    return parts.join(' · ');
+}
+/**
+ * Model attribution off a finished run's steps.
+ *
+ * The llm.response event does not carry the answering model, so a run
+ * that streamed to completion has to be asked afterwards. Only the
+ * tool-calling step records `routing` today, so a single-step answer
+ * has no attribution to find and this returns null rather than
+ * guessing.
+ */
+export function routingFromSteps(steps) {
+    if (!Array.isArray(steps))
+        return null;
+    for (let i = steps.length - 1; i >= 0; i--) {
+        const routing = steps[i]?.output?.routing;
+        if (routing && typeof routing === 'object') {
+            return {
+                model: str(routing.vendorModelId) ?? str(routing.modelId),
+                rationale: str(routing.rationale),
+                attempt: typeof routing.attempt === 'number' ? routing.attempt : undefined,
+            };
+        }
+    }
+    return null;
+}

package/dist/turn.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One turn of a conversation, driven the same way in both modes.
+ *
+ * The REPL and the non-interactive path used to be different code, and
+ * the non-interactive path did not exist. Both now call `runTurn`,
+ * which owns the choice between a streamed autonomous run and a
+ * streamed workflow pipeline, the cancellation handshake, and the
+ * cost tally. It takes the gateway as an interface so it can be tested
+ * against a fake without a network or a terminal.
+ */
+import type { AgentRun, RunLimits, StreamEvent } from '@almyty/client';
+import { type Activity, type Usage } from './stream.js';
+/** The part of GatewayClient a turn needs. */
+export interface TurnTarget {
+    startRun(input: any, options?: RunLimits & {
+        conversationId?: string;
+    }): Promise<AgentRun>;
+    streamRun(runId: string, handler: (event: StreamEvent) => void, signal?: AbortSignal): Promise<AgentRun>;
+    streamInvoke(input: Record<string, any>, handler: (event: StreamEvent) => void, signal?: AbortSignal): Promise<void>;
+    invoke(input: Record<string, any>): Promise<any>;
+    sendRunInput(runId: string, input: string): Promise<void>;
+    cancelRun(runId: string): Promise<void>;
+    cancelExecution(executionId: string): Promise<void>;
+}
+export interface TurnHooks {
+    /** The assistant text so far, on every change. */
+    partial?(text: string): void;
+    /** A transcript line: a tool call, a node, a warning. */
+    activity?(activity: Activity): void;
+    /** What the agent is doing, for a spinner. */
+    label?(label: string): void;
+}
+export type TurnStatus = 'completed' | 'failed' | 'cancelled' | 'waiting_input';
+export interface TurnResult {
+    status: TurnStatus;
+    text: string;
+    usage: Usage;
+    error?: string;
+    runId?: string;
+    conversationId?: string;
+    /** Set when the agent asked a question and is holding the run open. */
+    pendingRunId?: string;
+}
+export interface TurnOptions {
+    mode?: string;
+    conversationId?: string;
+    /** A run already waiting on input: this message answers it. */
+    pendingRunId?: string;
+    limits?: RunLimits;
+    signal?: AbortSignal;
+    hooks?: TurnHooks;
+}
+export declare function runTurn(target: TurnTarget, message: string, options?: TurnOptions): Promise<TurnResult>;