@almyty/client 0.1.0 → 1.3.0

package/README.md

@@ -0,0 +1,36 @@
+# @almyty/client
+
+Shared HTTP client and credential resolver used by all almyty CLI packages.
+
+## Usage
+
+```typescript
+import { AlmytyClient, resolveCredentialsOrExit } from '@almyty/client';
+
+const creds = resolveCredentialsOrExit();
+const client = new AlmytyClient(creds.url, creds.token);
+
+const agents = await client.listAgents();
+```
+
+## Exports
+
+- `AlmytyClient` -- API client (agents, runs, gateways)
+- `GatewayClient` -- gateway-scoped client (invoke, stream, conversations)
+- `resolveCredentials()` -- read `~/.almyty/credentials.json` (returns null if missing)
+- `resolveCredentialsOrExit()` -- same, but exits with an error message if missing
+- `getOrgSlugFromToken(token)` -- extract org slug from JWT
+- `loadCredentials()` -- raw file read
+- `CREDENTIALS_FILE` -- path to `~/.almyty/credentials.json`
+
+## About almyty
+
+almyty is the full-stack platform for AI agents, agnostic by design: any LLM, any
+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
+
+Apache-2.0 © Almyty Inc.

package/dist/client.d.ts

@@ -5,6 +5,11 @@
  * and @almyty/mcp-server. Covers agent discovery, invocation,
  * autonomous run management, and polling.
  */
+export interface AgentTool {
+    id: string;
+    name: string;
+    description?: string;
+}
 export interface AgentInfo {
     id: string;
     name: string;
@@ -16,6 +21,7 @@ export interface AgentInfo {
         nodes?: PipelineNode[];
     };
     modelConfig?: Record<string, unknown>;
+    tools?: AgentTool[];
 }
 export interface PipelineNode {
     id: string;
@@ -39,16 +45,79 @@ export interface RunLimits {
     maxCostCents?: number;
     maxDurationMs?: number;
 }
+/** SSE event from the agent run stream. */
+export interface StreamEvent {
+    type: string;
+    data: Record<string, unknown>;
+}
+/** A coding CLI detected on a runner machine. */
+export interface RunnerCodingAgent {
+    id: string;
+    displayName: string;
+    binary: string;
+    version?: string;
+    providerFamily?: string;
+}
+/** A registered runner (one of the user's machines). */
+export interface RunnerSummary {
+    id: string;
+    name: string;
+    state?: string;
+    labels?: Record<string, string>;
+    /** Coding CLIs the runner reported at registration. */
+    codingAgents: RunnerCodingAgent[];
+}
+/** A coding session running on a runner. */
+export interface CodingSession {
+    sessionId: string;
+    agent: string;
+    binary?: string;
+    processId?: string;
+    cwd?: string;
+    task?: string;
+    status?: string;
+    exitCode?: number | null;
+}
+/** 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;
     constructor(baseUrl: string, token: string);
     private headers;
     request(path: string, init?: RequestInit): Promise<any>;
+    /**
+     * 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, init?: RequestInit): Promise<void>;
     private unwrap;
     listAgents(): Promise<AgentInfo[]>;
     getAgent(id: string): Promise<AgentInfo>;
     findAgentByNameOrId(nameOrId: string): Promise<AgentInfo | null>;
+    /**
+     * Return a gateway-scoped client that routes all calls through
+     * /:orgSlug/:agentSlug instead of /agents/:id.
+     */
+    gateway(orgSlug: string, agentSlug: string): GatewayClient;
     invokeAgent(agentId: string, input: Record<string, any>): Promise<any>;
     startRun(agentId: string, input: any, options?: RunLimits & {
         conversationId?: string;
@@ -68,4 +137,84 @@ export declare class AlmytyClient {
         timeoutMs?: number;
         onStep?: (run: AgentRun) => void;
     }): Promise<AgentRun>;
+    /** The caller's registered runners, with their detected coding CLIs. */
+    listRunners(): Promise<RunnerSummary[]>;
+    /** Fresh probe of coding CLIs installed on the runner machine. */
+    listRunnerCodingAgents(runnerId: string): Promise<RunnerCodingAgent[]>;
+    /** Start a coding session (spawns the CLI with the task prompt). */
+    startCodingSession(runnerId: string, options: {
+        agent: string;
+        task: string;
+        cwd?: string;
+        model?: string;
+    }): Promise<CodingSession>;
+    getCodingSession(runnerId: string, sessionId: string): Promise<CodingSession>;
+    /** Route a line of user input to the session's stdin. */
+    sendCodingInput(runnerId: string, sessionId: string, data: string): Promise<void>;
+    stopCodingSession(runnerId: string, sessionId: string, force?: boolean): Promise<void>;
+    /**
+     * Stream a coding session's output via SSE. Calls handler for each
+     * coding.output / coding.exit event; returns when the session exits or
+     * the stream ends.
+     */
+    streamCodingEvents(runnerId: string, sessionId: string, handler: StreamEventHandler, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Routes all agent calls through the gateway unified endpoint
+ * (/:orgSlug/:agentSlug/...) instead of /agents/:id/...
+ *
+ * Authenticates via API key (same Bearer token).
+ */
+export declare class GatewayClient {
+    private readonly client;
+    private readonly prefix;
+    readonly orgSlug: string;
+    readonly agentSlug: string;
+    constructor(client: AlmytyClient, orgSlug: string, agentSlug: string);
+    getInfo(): Promise<AgentInfo>;
+    invoke(input: Record<string, any>): Promise<any>;
+    startRun(input: any, options?: RunLimits & {
+        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,
+     * step.completed, run.completed, run.failed).
+     * Returns when the run completes or fails.
+     * Falls back to polling if SSE fails.
+     */
+    streamRun(runId: string, handler: StreamEventHandler, signal?: AbortSignal): Promise<AgentRun>;
+    getConversationMessages(conversationId: string): Promise<Array<{
+        id: string;
+        role: string;
+        content: string;
+        createdAt: string;
+    }>>;
+    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,6 +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',
+    // 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;
@@ -26,18 +90,112 @@ 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;
         return res.json();
     }
+    /**
+     * 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, init = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            ...init,
+            headers: { ...this.headers(), Accept: 'text/event-stream', ...(init.headers || {}) },
+            signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw Object.assign(new Error(`SSE ${res.status}: ${text}`), {
+                status: res.status,
+                body: text,
+                url,
+            });
+        }
+        const body = res.body;
+        if (!body)
+            return;
+        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 {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                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();
+        }
+    }
     unwrap(data) {
         return data?.data ?? data;
     }
@@ -81,7 +239,15 @@ export class AlmytyClient {
             all.find((a) => a.slug?.toLowerCase() === lower) ||
             null);
     }
-    // ── Workflow invocation ───────────────────────���─────────────────
+    // ── Gateway-scoped client ───────────────────────────────────────
+    /**
+     * Return a gateway-scoped client that routes all calls through
+     * /:orgSlug/:agentSlug instead of /agents/:id.
+     */
+    gateway(orgSlug, agentSlug) {
+        return new GatewayClient(this, orgSlug, agentSlug);
+    }
+    // ── Workflow invocation ────────────────────────────────────────
     async invokeAgent(agentId, input) {
         const data = await this.request(`/agents/${encodeURIComponent(agentId)}/invoke`, {
             method: 'POST',
@@ -155,4 +321,186 @@ export class AlmytyClient {
         }
         throw new Error(`Run ${runId} did not finish within ${Math.round(timeoutMs / 1000)}s`);
     }
+    // ── Runners & coding sessions ───────────────────────────────────
+    /** The caller's registered runners, with their detected coding CLIs. */
+    async listRunners() {
+        const data = await this.request('/runners');
+        const list = data?.data ?? data ?? [];
+        return list.map((r) => ({
+            id: r.id,
+            name: r.name,
+            state: r.state,
+            labels: r.labels,
+            codingAgents: r.runtimeInfo?.codingAgents ?? [],
+        }));
+    }
+    /** Fresh probe of coding CLIs installed on the runner machine. */
+    async listRunnerCodingAgents(runnerId) {
+        const data = await this.request(`/runners/${encodeURIComponent(runnerId)}/coding/agents`);
+        return this.unwrap(data)?.agents ?? [];
+    }
+    /** Start a coding session (spawns the CLI with the task prompt). */
+    async startCodingSession(runnerId, options) {
+        const data = await this.request(`/runners/${encodeURIComponent(runnerId)}/coding/sessions`, { method: 'POST', body: JSON.stringify(options) });
+        return this.unwrap(data);
+    }
+    async getCodingSession(runnerId, sessionId) {
+        const data = await this.request(`/runners/${encodeURIComponent(runnerId)}/coding/sessions/${encodeURIComponent(sessionId)}`);
+        return this.unwrap(data);
+    }
+    /** Route a line of user input to the session's stdin. */
+    async sendCodingInput(runnerId, sessionId, data) {
+        await this.request(`/runners/${encodeURIComponent(runnerId)}/coding/sessions/${encodeURIComponent(sessionId)}/input`, { method: 'POST', body: JSON.stringify({ data }) });
+    }
+    async stopCodingSession(runnerId, sessionId, force = false) {
+        await this.request(`/runners/${encodeURIComponent(runnerId)}/coding/sessions/${encodeURIComponent(sessionId)}/stop`, { method: 'POST', body: JSON.stringify(force ? { force } : {}) });
+    }
+    /**
+     * Stream a coding session's output via SSE. Calls handler for each
+     * coding.output / coding.exit event; returns when the session exits or
+     * the stream ends.
+     */
+    async streamCodingEvents(runnerId, sessionId, handler, signal) {
+        await this.streamSSE(`/runners/${encodeURIComponent(runnerId)}/coding/sessions/${encodeURIComponent(sessionId)}/events`, handler, signal);
+    }
+}
+// ── Gateway-scoped client ───────────────────────────────────────
+/**
+ * Routes all agent calls through the gateway unified endpoint
+ * (/:orgSlug/:agentSlug/...) instead of /agents/:id/...
+ *
+ * Authenticates via API key (same Bearer token).
+ */
+export class GatewayClient {
+    client;
+    prefix;
+    orgSlug;
+    agentSlug;
+    constructor(client, orgSlug, agentSlug) {
+        this.client = client;
+        this.orgSlug = orgSlug;
+        this.agentSlug = agentSlug;
+        this.prefix = `/${encodeURIComponent(orgSlug)}/${encodeURIComponent(agentSlug)}`;
+    }
+    async getInfo() {
+        const data = await this.client.request(this.prefix);
+        return data?.data ?? data;
+    }
+    async invoke(input) {
+        const data = await this.client.request(`${this.prefix}/invoke`, {
+            method: 'POST',
+            body: JSON.stringify({ input }),
+        });
+        return data?.data ?? data;
+    }
+    async startRun(input, options) {
+        const body = { input };
+        if (options?.maxSteps)
+            body.maxSteps = options.maxSteps;
+        if (options?.maxCostCents)
+            body.maxCostCents = options.maxCostCents;
+        if (options?.maxDurationMs)
+            body.maxDurationMs = options.maxDurationMs;
+        if (options?.conversationId)
+            body.conversationId = options.conversationId;
+        const data = await this.client.request(`${this.prefix}/runs`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        const run = data?.data ?? data;
+        return {
+            id: run.id,
+            agentId: run.agentId,
+            status: run.status,
+            conversationId: run.conversationId,
+            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,
+     * step.completed, run.completed, run.failed).
+     * Returns when the run completes or fails.
+     * Falls back to polling if SSE fails.
+     */
+    async streamRun(runId, handler, signal) {
+        try {
+            await this.client.streamSSE(`${this.prefix}/runs/${encodeURIComponent(runId)}/stream`, handler, signal);
+            // Stream ended — get final state
+            return this.getRun(runId);
+        }
+        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, { signal });
+        }
+    }
+    async getConversationMessages(conversationId) {
+        const data = await this.client.request(`${this.prefix}/conversations/${encodeURIComponent(conversationId)}/messages`);
+        return data?.data ?? [];
+    }
+    async sendRunInput(runId, input) {
+        await this.client.request(`${this.prefix}/runs/${encodeURIComponent(runId)}/input`, { method: 'POST', body: JSON.stringify({ input }) });
+    }
+    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;
+                options.onStep?.(run);
+            }
+            if (run.status && (TERMINAL_STATUSES.has(run.status) || run.status === 'waiting_input')) {
+                return run;
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        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,13 +10,40 @@ 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;
+/**
+ * Extract the default org slug from a JWT token.
+ * Returns null if the token isn't a JWT or has no orgs.
+ */
+export declare function getOrgSlugFromToken(token: string): string | null;

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,19 +40,57 @@ 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.
+ * Returns null if the token isn't a JWT or has no orgs.
+ */
+export function getOrgSlugFromToken(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        let payload = parts[1];
+        payload += '='.repeat((4 - payload.length % 4) % 4);
+        const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString());
+        const orgs = decoded.organizations;
+        if (!Array.isArray(orgs) || !orgs.length)
+            return null;
+        // Use slug if available, otherwise derive from name
+        const org = orgs[0];
+        if (org.slug)
+            return org.slug;
+        if (org.name)
+            return org.name.toLowerCase().replace(/\s+/g, '-');
+        return null;
+    }
+    catch {
+        return null;
+    }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AlmytyClient } from './client.js';
-export type { AgentInfo, AgentRun, PipelineNode, RunLimits } from './client.js';
-export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, CREDENTIALS_FILE, } from './credentials.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, credentialsExpired, CREDENTIALS_FILE, } from './credentials.js';
 export type { StoredCredentials } from './credentials.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AlmytyClient } from './client.js';
-export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, 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,7 +1,10 @@
 {
   "name": "@almyty/client",
-  "version": "0.1.0",
-  "description": "Shared HTTP client and credential resolver for almyty CLI packages",
+  "version": "1.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Shared HTTP client and credential resolver used by the almyty CLIs. Reads ~/.almyty/credentials.json; not usually installed on its own.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,10 +23,22 @@
     "sdk"
   ],
   "author": "almyty",
-  "license": "BSL-1.1",
+  "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^25.4.0",
     "typescript": "^5.3.0",
     "vitest": "^4.1.0"
+  },
+  "homepage": "https://almyty.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almyty-inc/almyty.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/almyty-inc/almyty/issues"
+  },
+  "overrides": {
+    "postcss": "^8.5.23"
   }
 }