@almyty/client 0.1.0 → 1.2.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,61 @@ 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;
 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.
+     */
+    streamSSE(path: string, handler: StreamEventHandler, signal?: AbortSignal): 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 +119,65 @@ 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 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>;
+    pollRun(runId: string, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onStep?: (run: AgentRun) => void;
+    }): Promise<AgentRun>;
 }

package/dist/client.js

@@ -6,6 +6,7 @@
  * 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']);
 export class AlmytyClient {
     baseUrl;
     token;
@@ -38,6 +39,67 @@ export class AlmytyClient {
             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.
+     */
+    async streamSSE(path, handler, signal) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            headers: { ...this.headers(), Accept: 'text/event-stream' },
+            signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`SSE ${res.status}: ${text}`);
+        }
+        const body = res.body;
+        if (!body)
+            return;
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                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';
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
     unwrap(data) {
         return data?.data ?? data;
     }
@@ -81,7 +143,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 +225,151 @@ 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,
+        };
+    }
+    async getRun(runId) {
+        const data = await this.client.request(`${this.prefix}/runs/${encodeURIComponent(runId)}`);
+        return (data?.data ?? data);
+    }
+    /**
+     * 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 {
+            // SSE failed — fall back to polling until completion
+            return this.pollRun(runId);
+        }
+    }
+    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' });
+    }
+    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) {
+            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 new Error(`Run ${runId} did not finish within ${Math.round(timeoutMs / 1000)}s`);
+    }
 }

package/dist/credentials.d.ts

@@ -20,3 +20,8 @@ export declare function resolveCredentials(): StoredCredentials | null;
  * Resolve credentials or exit with an error message.
  */
 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

@@ -43,3 +43,30 @@ export function resolveCredentialsOrExit() {
     console.error('  export ALMYTY_TOKEN=<your-token>');
     process.exit(1);
 }
+/**
+ * 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 } 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 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 } from './client.js';
+export { loadCredentials, resolveCredentials, resolveCredentialsOrExit, getOrgSlugFromToken, 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.2.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,19 @@
     "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"
   }
 }