@almyty/client 1.2.0 → 1.5.0

package/README.md

@@ -29,8 +29,8 @@ almyty is the full-stack platform for AI agents, agnostic by design: any LLM, an
 API turned into tools, served over MCP, A2A, UTCP, and Agent Skills. Open source,
 no lock-in.
 
-- Website — https://almyty.com
-- Docs — https://docs.almyty.com
-- Source — https://github.com/almyty-inc/almyty
+- Website: https://almyty.com
+- Docs: https://docs.almyty.com
+- Source: https://github.com/almyty-inc/almyty
 
 Apache-2.0 © Almyty Inc.

package/dist/client.d.ts

@@ -80,6 +80,21 @@ export interface CodingSession {
 }
 /** Callback for stream events. */
 export type StreamEventHandler = (event: StreamEvent) => void;
+/** Whether a rejection is a caller-requested abort rather than a failure. */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Turn one SSE frame's lines into a StreamEvent, or null when the frame
+ * carries nothing usable (a keep-alive comment, or malformed JSON).
+ *
+ * Server frames are not uniform. Run events arrive wrapped as
+ * `{type, data, timestamp}`; coding and pipeline events put their
+ * fields at the top level and may also carry a `data` object. So the
+ * envelope's own `data` object is flattened onto the result and the
+ * top-level fields are kept. Reading `event.data.content` off an
+ * `llm.chunk` returned undefined before this, which is why a streaming
+ * reply used to arrive as one block once the run had already finished.
+ */
+export declare function parseSseFrame(lines: string[]): StreamEvent | null;
 export declare class AlmytyClient {
     private readonly baseUrl;
     private readonly token;
@@ -89,8 +104,11 @@ export declare class AlmytyClient {
     /**
      * Connect to an SSE endpoint and call handler for each event.
      * Returns when the stream ends or a terminal event is received.
+     *
+     * `init` lets a caller POST (the workflow pipeline stream does);
+     * omitted, this is a GET.
      */
-    streamSSE(path: string, handler: StreamEventHandler, signal?: AbortSignal): Promise<void>;
+    streamSSE(path: string, handler: StreamEventHandler, signal?: AbortSignal, init?: RequestInit): Promise<void>;
     private unwrap;
     listAgents(): Promise<AgentInfo[]>;
     getAgent(id: string): Promise<AgentInfo>;
@@ -159,6 +177,16 @@ export declare class GatewayClient {
         conversationId?: string;
     }): Promise<AgentRun>;
     getRun(runId: string): Promise<AgentRun>;
+    /**
+     * Stream a workflow agent's pipeline as it executes.
+     *
+     * The unified endpoint answers POST /:org/:agent/stream with SSE:
+     * execution.started, node.started, node.output, node.completed,
+     * node.skipped, then execution.completed or execution.failed. Without
+     * this a multi-node pipeline is a blocking POST with nothing to show
+     * while it runs.
+     */
+    streamInvoke(input: Record<string, any>, handler: StreamEventHandler, signal?: AbortSignal): Promise<void>;
     /**
      * Stream run events via SSE. Calls handler for each event
      * (llm.started, llm.chunk, llm.response, tool.started, tool.result,
@@ -175,9 +203,18 @@ export declare class GatewayClient {
     }>>;
     sendRunInput(runId: string, input: string): Promise<void>;
     cancelRun(runId: string): Promise<void>;
+    /**
+     * Cancel a workflow execution.
+     *
+     * The workflow counterpart of cancelRun. A workflow run is an execution,
+     * not a run, so cancelRun could never stop one -- a Ctrl-C that did not
+     * also drop the SSE connection left the pipeline running and billing.
+     */
+    cancelExecution(executionId: string): Promise<void>;
     pollRun(runId: string, options?: {
         intervalMs?: number;
         timeoutMs?: number;
         onStep?: (run: AgentRun) => void;
+        signal?: AbortSignal;
     }): Promise<AgentRun>;
 }

package/dist/client.js

@@ -6,7 +6,70 @@
  * autonomous run management, and polling.
  */
 const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled', 'timeout']);
-const TERMINAL_EVENT_TYPES = new Set(['run.completed', 'run.failed', 'run.cancelled', 'coding.exit']);
+const TERMINAL_EVENT_TYPES = new Set([
+    'run.completed',
+    'run.failed',
+    'run.cancelled',
+    'coding.exit',
+    // The workflow pipeline stream's own terminators.
+    'execution.completed',
+    'execution.failed',
+    'done',
+]);
+/** Whether a rejection is a caller-requested abort rather than a failure. */
+export function isAbortError(err) {
+    const e = err;
+    return !!e && (e.name === 'AbortError' || e.code === 'ABORT_ERR');
+}
+/**
+ * Turn one SSE frame's lines into a StreamEvent, or null when the frame
+ * carries nothing usable (a keep-alive comment, or malformed JSON).
+ *
+ * Server frames are not uniform. Run events arrive wrapped as
+ * `{type, data, timestamp}`; coding and pipeline events put their
+ * fields at the top level and may also carry a `data` object. So the
+ * envelope's own `data` object is flattened onto the result and the
+ * top-level fields are kept. Reading `event.data.content` off an
+ * `llm.chunk` returned undefined before this, which is why a streaming
+ * reply used to arrive as one block once the run had already finished.
+ */
+export function parseSseFrame(lines) {
+    let eventType = 'message';
+    const dataLines = [];
+    for (const line of lines) {
+        // A line starting with ':' is a comment. The server sends
+        // ': keep-alive' every 15s on the coding stream.
+        if (line.startsWith(':'))
+            continue;
+        if (line.startsWith('event:')) {
+            eventType = line.slice(6).trim();
+        }
+        else if (line.startsWith('data:')) {
+            const value = line.slice(5);
+            dataLines.push(value.startsWith(' ') ? value.slice(1) : value);
+        }
+    }
+    if (!dataLines.length)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(dataLines.join('\n'));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const envelope = parsed;
+    const inner = envelope.data;
+    const flat = inner && typeof inner === 'object' && !Array.isArray(inner)
+        ? { ...envelope, ...inner }
+        : envelope;
+    return {
+        type: typeof envelope.type === 'string' ? envelope.type : eventType,
+        data: flat,
+    };
+}
 export class AlmytyClient {
     baseUrl;
     token;
@@ -27,13 +90,27 @@ export class AlmytyClient {
             ...this.headers(),
             ...(init.headers || {}),
         };
-        const res = await fetch(url, { ...init, headers });
+        let res;
+        try {
+            res = await fetch(url, { ...init, headers });
+        }
+        catch (err) {
+            // A transport failure carries no status, so callers that want to
+            // say something useful about it need the cause and the host.
+            throw Object.assign(new Error(err?.message || 'Network request failed'), {
+                url,
+                cause: err,
+                networkError: true,
+            });
+        }
         if (!res.ok) {
-            if (res.status === 401) {
-                throw new Error('Authentication failed. Run: npx @almyty/auth login');
-            }
             const text = await res.text().catch(() => '');
-            throw new Error(`API error ${res.status}: ${text}`);
+            // Status and body ride on the error. A CLI cannot turn
+            // "API error 400: {...}" into a sentence a user can act on without
+            // them, and parsing the message string back apart is worse.
+            throw Object.assign(new Error(res.status === 401
+                ? 'Authentication failed. Run: npx @almyty/auth login'
+                : `API error ${res.status}: ${text}`), { status: res.status, body: text, url });
         }
         if (res.status === 204)
             return null;
@@ -42,16 +119,24 @@ export class AlmytyClient {
     /**
      * Connect to an SSE endpoint and call handler for each event.
      * Returns when the stream ends or a terminal event is received.
+     *
+     * `init` lets a caller POST (the workflow pipeline stream does);
+     * omitted, this is a GET.
      */
-    async streamSSE(path, handler, signal) {
+    async streamSSE(path, handler, signal, init = {}) {
         const url = `${this.baseUrl}${path}`;
         const res = await fetch(url, {
-            headers: { ...this.headers(), Accept: 'text/event-stream' },
+            ...init,
+            headers: { ...this.headers(), Accept: 'text/event-stream', ...(init.headers || {}) },
             signal,
         });
         if (!res.ok) {
             const text = await res.text().catch(() => '');
-            throw new Error(`SSE ${res.status}: ${text}`);
+            throw Object.assign(new Error(`SSE ${res.status}: ${text}`), {
+                status: res.status,
+                body: text,
+                url,
+            });
         }
         const body = res.body;
         if (!body)
@@ -59,44 +144,55 @@ export class AlmytyClient {
         const reader = body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
+        // Frame state lives outside the read loop. It used to be declared
+        // per chunk, so any frame whose terminating blank line arrived in
+        // the next chunk was dropped -- which is most of them on a busy
+        // stream, and is why streamed tokens never reached the CLI.
+        let frame = [];
         try {
-            while (true) {
+            for (;;) {
                 const { value, done } = await reader.read();
                 if (done)
                     break;
                 buffer += decoder.decode(value, { stream: true });
-                // Parse SSE frames
-                const lines = buffer.split('\n');
-                buffer = lines.pop(); // keep incomplete line
-                let eventType = 'message';
-                let dataLines = [];
-                for (const line of lines) {
-                    if (line.startsWith('event: ')) {
-                        eventType = line.slice(7).trim();
-                    }
-                    else if (line.startsWith('data: ')) {
-                        dataLines.push(line.slice(6));
-                    }
-                    else if (line === '') {
-                        // End of frame
-                        if (dataLines.length) {
-                            const raw = dataLines.join('\n');
-                            try {
-                                const data = JSON.parse(raw);
-                                const event = { type: data.type || eventType, data };
-                                handler(event);
-                                if (TERMINAL_EVENT_TYPES.has(event.type))
-                                    return;
-                            }
-                            catch { /* skip malformed */ }
-                            dataLines = [];
-                            eventType = 'message';
+                let nl = buffer.indexOf('\n');
+                while (nl !== -1) {
+                    // CRLF is legal in SSE and a proxy may rewrite to it. Without
+                    // stripping the carriage return, no line ever compares equal
+                    // to '' and not one frame is ever dispatched.
+                    const line = buffer.slice(0, nl).replace(/\r$/, '');
+                    buffer = buffer.slice(nl + 1);
+                    if (line === '') {
+                        const event = parseSseFrame(frame);
+                        frame = [];
+                        if (event) {
+                            handler(event);
+                            if (TERMINAL_EVENT_TYPES.has(event.type))
+                                return;
                         }
                     }
+                    else {
+                        frame.push(line);
+                    }
+                    nl = buffer.indexOf('\n');
                 }
             }
+            // A server that closes without a trailing blank line still sent a
+            // frame worth reading.
+            if (buffer)
+                frame.push(buffer.replace(/\r$/, ''));
+            const tail = parseSseFrame(frame);
+            if (tail)
+                handler(tail);
         }
         finally {
+            // Releasing the lock does not close the connection. A terminal
+            // event returns from the loop above with the body unread and the
+            // socket still open, and an SSE endpoint holds its end open too,
+            // so the handle keeps Node's event loop alive: `almyty chat` would
+            // not exit after a streamed turn, and a REPL leaked one connection
+            // per answer. Cancelling the body is what actually closes it.
+            await reader.cancel().catch(() => undefined);
             reader.releaseLock();
         }
     }
@@ -320,12 +416,29 @@ export class GatewayClient {
             output: run.output,
             error: run.error,
             steps: run.steps,
+            totalCost: run.totalCost,
+            totalTokens: run.totalTokens,
         };
     }
     async getRun(runId) {
         const data = await this.client.request(`${this.prefix}/runs/${encodeURIComponent(runId)}`);
         return (data?.data ?? data);
     }
+    /**
+     * Stream a workflow agent's pipeline as it executes.
+     *
+     * The unified endpoint answers POST /:org/:agent/stream with SSE:
+     * execution.started, node.started, node.output, node.completed,
+     * node.skipped, then execution.completed or execution.failed. Without
+     * this a multi-node pipeline is a blocking POST with nothing to show
+     * while it runs.
+     */
+    async streamInvoke(input, handler, signal) {
+        await this.client.streamSSE(`${this.prefix}/stream`, handler, signal, {
+            method: 'POST',
+            body: JSON.stringify({ input }),
+        });
+    }
     /**
      * Stream run events via SSE. Calls handler for each event
      * (llm.started, llm.chunk, llm.response, tool.started, tool.result,
@@ -339,9 +452,14 @@ export class GatewayClient {
             // Stream ended — get final state
             return this.getRun(runId);
         }
-        catch {
+        catch (err) {
+            // An abort is what the caller asked for, not a transport failure.
+            // Falling back to polling here kept a cancelled run under watch
+            // for the full five-minute poll window.
+            if (signal?.aborted || isAbortError(err))
+                throw err;
             // SSE failed — fall back to polling until completion
-            return this.pollRun(runId);
+            return this.pollRun(runId, { signal });
         }
     }
     async getConversationMessages(conversationId) {
@@ -354,12 +472,25 @@ export class GatewayClient {
     async cancelRun(runId) {
         await this.client.request(`${this.prefix}/runs/${encodeURIComponent(runId)}/cancel`, { method: 'POST' });
     }
+    /**
+     * Cancel a workflow execution.
+     *
+     * The workflow counterpart of cancelRun. A workflow run is an execution,
+     * not a run, so cancelRun could never stop one -- a Ctrl-C that did not
+     * also drop the SSE connection left the pipeline running and billing.
+     */
+    async cancelExecution(executionId) {
+        await this.client.request(`${this.prefix}/executions/${encodeURIComponent(executionId)}/cancel`, { method: 'POST' });
+    }
     async pollRun(runId, options = {}) {
         const intervalMs = options.intervalMs ?? 1500;
         const timeoutMs = options.timeoutMs ?? 5 * 60_000;
         const deadline = Date.now() + timeoutMs;
         let lastStepCount = -1;
         while (Date.now() < deadline) {
+            if (options.signal?.aborted) {
+                throw Object.assign(new Error('Aborted'), { name: 'AbortError' });
+            }
             const run = await this.getRun(runId);
             if (Array.isArray(run.steps) && run.steps.length !== lastStepCount) {
                 lastStepCount = run.steps.length;
@@ -370,6 +501,6 @@ export class GatewayClient {
             }
             await new Promise((r) => setTimeout(r, intervalMs));
         }
-        throw new Error(`Run ${runId} did not finish within ${Math.round(timeoutMs / 1000)}s`);
+        throw Object.assign(new Error(`Run ${runId} did not finish within ${Math.round(timeoutMs / 1000)}s`), { runId, pollTimeout: true });
     }
 }

package/dist/credentials.d.ts

@@ -10,14 +10,36 @@ export interface StoredCredentials {
     token: string;
     email?: string;
     frontendUrl?: string;
+    /**
+     * When the token stops working, from the JWT's own `exp` claim.
+     *
+     * `@almyty/auth` writes it; this reader did not carry the field, so
+     * every CLI other than `auth` could not tell an expired credential
+     * from a live one and discovered the difference on its first API call
+     * — as a 401 from whatever the user was actually trying to do.
+     */
+    expiresAt?: string;
 }
+/** Past its `exp`, treating a malformed or absent value as "no idea, assume live". */
+export declare function credentialsExpired(creds: Pick<StoredCredentials, 'expiresAt'>): boolean;
 export declare function loadCredentials(): StoredCredentials | null;
 /**
- * Resolve credentials from env or file. Returns null if nothing found.
+ * Resolve credentials from env or file. Returns null if nothing usable
+ * was found — an expired stored credential counts as nothing, because
+ * using it produces a 401 on the user's actual request rather than a
+ * sentence telling them to log in again.
+ *
+ * `ALMYTY_TOKEN` is never expiry-checked: it did not come from `auth
+ * login`, so there is no claim to check and no file to correct.
  */
 export declare function resolveCredentials(): StoredCredentials | null;
 /**
- * Resolve credentials or exit with an error message.
+ * Resolve credentials or exit.
+ *
+ * Exits 3, which is "not authenticated" in the exit-code table every
+ * almyty CLI shares (0 ok, 1 unexpected, 2 usage, 3 not authenticated,
+ * 4 not found, 5 the operation ran and failed). It exited 1 before, so
+ * a script could not tell a stale login from a crash.
  */
 export declare function resolveCredentialsOrExit(): StoredCredentials;
 /**

package/dist/credentials.js

@@ -8,6 +8,13 @@ import { readFileSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 export const CREDENTIALS_FILE = join(homedir(), '.almyty', 'credentials.json');
+/** Past its `exp`, treating a malformed or absent value as "no idea, assume live". */
+export function credentialsExpired(creds) {
+    if (!creds.expiresAt)
+        return false;
+    const at = Date.parse(creds.expiresAt);
+    return Number.isFinite(at) && at <= Date.now();
+}
 export function loadCredentials() {
     try {
         if (!existsSync(CREDENTIALS_FILE))
@@ -19,7 +26,13 @@ export function loadCredentials() {
     }
 }
 /**
- * Resolve credentials from env or file. Returns null if nothing found.
+ * Resolve credentials from env or file. Returns null if nothing usable
+ * was found — an expired stored credential counts as nothing, because
+ * using it produces a 401 on the user's actual request rather than a
+ * sentence telling them to log in again.
+ *
+ * `ALMYTY_TOKEN` is never expiry-checked: it did not come from `auth
+ * login`, so there is no claim to check and no file to correct.
  */
 export function resolveCredentials() {
     const envToken = process.env.ALMYTY_TOKEN;
@@ -27,21 +40,32 @@ export function resolveCredentials() {
     if (envToken)
         return { url: envUrl, token: envToken };
     const stored = loadCredentials();
-    if (stored?.token)
+    if (stored?.token && !credentialsExpired(stored))
         return stored;
     return null;
 }
 /**
- * Resolve credentials or exit with an error message.
+ * Resolve credentials or exit.
+ *
+ * Exits 3, which is "not authenticated" in the exit-code table every
+ * almyty CLI shares (0 ok, 1 unexpected, 2 usage, 3 not authenticated,
+ * 4 not found, 5 the operation ran and failed). It exited 1 before, so
+ * a script could not tell a stale login from a crash.
  */
 export function resolveCredentialsOrExit() {
     const creds = resolveCredentials();
     if (creds)
         return creds;
+    const stored = loadCredentials();
+    if (stored?.token && credentialsExpired(stored)) {
+        console.error(`Your login expired on ${stored.expiresAt}. Run:`);
+        console.error('  npx @almyty/auth login');
+        process.exit(3);
+    }
     console.error('Not authenticated. Run one of:');
     console.error('  npx @almyty/auth login');
     console.error('  export ALMYTY_TOKEN=<your-token>');
-    process.exit(1);
+    process.exit(3);
 }
 /**
  * Extract the default org slug from a JWT token.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AlmytyClient, GatewayClient } from './client.js';
+export { AlmytyClient, GatewayClient, parseSseFrame, isAbortError } from './client.js';
 export type { AgentInfo, AgentTool, AgentRun, PipelineNode, RunLimits, StreamEvent, StreamEventHandler, RunnerSummary, RunnerCodingAgent, CodingSession, } from './client.js';
-export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, getOrgSlugFromToken, CREDENTIALS_FILE, } from './credentials.js';
+export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, getOrgSlugFromToken, credentialsExpired, CREDENTIALS_FILE, } from './credentials.js';
 export type { StoredCredentials } from './credentials.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AlmytyClient, GatewayClient } from './client.js';
-export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, getOrgSlugFromToken, CREDENTIALS_FILE, } from './credentials.js';
+export { AlmytyClient, GatewayClient, parseSseFrame, isAbortError } from './client.js';
+export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, getOrgSlugFromToken, credentialsExpired, CREDENTIALS_FILE, } from './credentials.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almyty/client",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -37,5 +37,8 @@
   },
   "bugs": {
     "url": "https://github.com/almyty-inc/almyty/issues"
+  },
+  "overrides": {
+    "postcss": "^8.5.23"
   }
 }