@ocis/myagent-cli 0.2.0

package/dist/protocol/client.js

@@ -0,0 +1,250 @@
+// ---------------------------------------------------------------------------
+// HTTP client for the MyAgent integration API.
+//
+// One instance per configured server; stateless apart from configuration.
+// Streaming responses are read with readSseFrames (the run stream and the
+// single-frame input ack); non-streaming endpoints return parsed JSON.
+// Tests inject a `fetch` implementation; production uses global fetch with the
+// API key attached.
+// ---------------------------------------------------------------------------
+import { readSseFrames } from "./sse-frames.js";
+/** Error thrown for non-2xx integration API responses. */
+export class IntegrationApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, status, 
+    /** Machine-readable discriminator from the error body (e.g. `tool_call_expired`). */
+    code, 
+    /** Additive machine-readable context (e.g. `{ expiredIds }`). */
+    details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "IntegrationApiError";
+    }
+}
+export class IntegrationClient {
+    baseUrl;
+    integrationId;
+    apiKey;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.integrationId = opts.integrationId;
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    url(path) {
+        return `${this.baseUrl}/integrations/${encodeURIComponent(this.integrationId)}${path}`;
+    }
+    headers(json = false) {
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        if (json)
+            headers["Content-Type"] = "application/json";
+        return headers;
+    }
+    // -------------------------------------------------------------------------
+    // AG-UI run surface
+    // -------------------------------------------------------------------------
+    /**
+     * Start a run and stream its AG-UI events. The stream stays open through
+     * client-tool waits (heartbeats keep it alive), so it is the single line for
+     * the whole run: collect `CUSTOM_TOOL_CALL` events, execute the calls, then
+     * submit results with sendRunMessages — the continuation's events keep
+     * flowing on this same stream.
+     *
+     * The thread id arrives in the X-Thread-Id response header, before the first
+     * event, and is also latched through `onThreadId`.
+     */
+    async startRun(req, opts) {
+        const res = await this.fetchImpl(this.url("/v1/runs"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(req),
+            signal: opts.signal,
+        });
+        if (!res.ok)
+            throw await this.apiError(res);
+        const threadId = res.headers.get("X-Thread-Id") ?? undefined;
+        if (threadId)
+            opts.onThreadId?.(threadId);
+        if (!res.body)
+            throw new IntegrationApiError("Server returned an empty response body.", res.status);
+        let error;
+        try {
+            await readSseFrames(res.body, (frame) => opts.onEvent(frame));
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError")
+                throw err;
+            error = err instanceof Error ? err.message : String(err);
+        }
+        return { threadId, error };
+    }
+    /**
+     * Continue the thread's active run: user/system messages steer it, tool-role
+     * messages resume it (tool results are awaited by the agent). The server
+     * answers with a single SSE frame — INPUT_ACCEPTED, or INPUT_REJECTED
+     * (thrown as IntegrationApiError with the machine-readable `code`). Run
+     * events keep flowing on the run stream, never on this response.
+     *
+     * Returns the persisted message id for steers (absent for tool-result
+     * resumes) — the caller correlates the later QUEUED_MESSAGE_DELIVERED event
+     * with it.
+     */
+    async sendRunMessages(threadId, messages, opts = {}) {
+        const res = await this.fetchImpl(this.url(`/v1/runs/${encodeURIComponent(threadId)}/messages`), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ messages, ...(opts.tools?.length ? { tools: opts.tools } : {}) }),
+            signal: opts.signal,
+        });
+        if (!res.ok)
+            throw await this.apiError(res);
+        if (!res.body)
+            throw new IntegrationApiError("Server returned an empty response body.", res.status);
+        const acks = [];
+        // One frame is the whole answer: stop reading instead of waiting for the
+        // connection to close (a proxy that holds it open would hang the caller).
+        await readSseFrames(res.body, (frame) => {
+            acks.push(frame);
+            return "stop";
+        });
+        const ack = acks[0];
+        if (!ack)
+            throw new IntegrationApiError("The server did not acknowledge the input.", res.status);
+        if (ack.type === "INPUT_REJECTED") {
+            throw new IntegrationApiError(ack.message, res.status, ack.code, ack.details);
+        }
+        return ack.messageId;
+    }
+    // -------------------------------------------------------------------------
+    // Non-streaming endpoints
+    // -------------------------------------------------------------------------
+    async getStatus(opts = {}) {
+        return this.json(this.url(""), { method: "GET", signal: opts.signal });
+    }
+    /**
+     * Models this integration accepts (default first, `default: true` marks it).
+     * A forced-model integration returns exactly one entry — there is nothing to
+     * choose. Used by the `/model` picker.
+     */
+    async listModels() {
+        const body = await this.json(this.url("/v1/models"), { method: "GET" });
+        return body.data ?? [];
+    }
+    async listSessions() {
+        return this.json(this.url("/sessions"), { method: "GET" });
+    }
+    async getSession(threadId, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.history)
+            params.set("include_history", "true");
+        if (opts.historyLimit)
+            params.set("history_limit", String(opts.historyLimit));
+        const query = params.size > 0 ? `?${params}` : "";
+        return this.json(this.url(`/sessions/${encodeURIComponent(threadId)}${query}`), { method: "GET" });
+    }
+    async patchSessionTitle(threadId, title, opts = {}) {
+        await this.json(this.url(`/sessions/${encodeURIComponent(threadId)}`), {
+            method: "PATCH",
+            body: JSON.stringify({ title }),
+            signal: opts.signal,
+        });
+    }
+    async deleteSession(threadId) {
+        await this.json(this.url(`/sessions/${encodeURIComponent(threadId)}`), { method: "DELETE" });
+    }
+    async stopSession(threadId) {
+        await this.json(this.url(`/sessions/${encodeURIComponent(threadId)}/stop`), { method: "POST" });
+    }
+    async compactSession(threadId, focus) {
+        await this.json(this.url(`/sessions/${encodeURIComponent(threadId)}/compact`), {
+            method: "POST",
+            body: JSON.stringify(focus ? { focus } : {}),
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Workspace files (per-integration path — see integration-api.md)
+    // -------------------------------------------------------------------------
+    /** GET /integrations/<id>/workspace?path= — list a workspace directory. */
+    async workspaceList(path, opts = {}) {
+        const params = new URLSearchParams({ path });
+        return this.json(this.url(`/workspace?${params}`), { method: "GET", signal: opts.signal });
+    }
+    /** GET /integrations/<id>/workspace/read?path= — read one file (base64 when binary). */
+    async workspaceRead(path, opts = {}) {
+        const params = new URLSearchParams({ path });
+        return this.json(this.url(`/workspace/read?${params}`), { method: "GET", signal: opts.signal });
+    }
+    /** PUT /integrations/<id>/workspace/write — create or overwrite one file. */
+    async workspaceWrite(path, content, binary, opts = {}) {
+        return this.json(this.url("/workspace/write"), {
+            method: "PUT",
+            body: JSON.stringify({ path, content, binary }),
+            signal: opts.signal,
+        });
+    }
+    /**
+     * Subscribe to a session's AG-UI event stream (SSE). Resolves when the
+     * stream ends (server close or network drop) — the caller reconnects with
+     * backoff. AbortError propagates so a deliberate unsubscribe is
+     * distinguishable from a drop.
+     *
+     * Events are delivered verbatim: `MESSAGES_SNAPSHOT` first (transcript +
+     * status), then live AG-UI events including `TOOL_CALL_RESULT` for
+     * client-executed calls (an error result means the server released the call).
+     */
+    async openSessionEvents(threadId, opts) {
+        const res = await this.fetchImpl(this.url(`/sessions/${encodeURIComponent(threadId)}/events`), {
+            method: "GET",
+            headers: { ...this.headers(false), Accept: "text/event-stream" },
+            signal: opts.signal,
+        });
+        if (!res.ok)
+            throw await this.apiError(res);
+        if (!res.body)
+            throw new IntegrationApiError("Server returned an empty response body.", res.status);
+        try {
+            await readSseFrames(res.body, opts.onEvent);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError")
+                throw err;
+            // Network drop — the caller reconnects.
+        }
+    }
+    async json(url, init) {
+        const res = await this.fetchImpl(url, {
+            ...init,
+            headers: this.headers(init.body !== undefined),
+        });
+        if (!res.ok)
+            throw await this.apiError(res);
+        return await res.json();
+    }
+    /** Build an IntegrationApiError from a non-OK response, preserving the
+     *  machine-readable `error.code` (e.g. `tool_call_expired`). */
+    async apiError(res) {
+        let message = `HTTP ${res.status}`;
+        let code;
+        let details;
+        try {
+            const body = await res.json();
+            if (body.error?.message)
+                message = body.error.message;
+            code = body.error?.code;
+            details = body.error?.details;
+        }
+        catch { /* non-JSON error body */ }
+        if (res.status === 404) {
+            message += " (check the integration id and that the integration is enabled)";
+        }
+        else if (res.status === 401) {
+            message += " (check the API key)";
+        }
+        return new IntegrationApiError(message, res.status, code, details);
+    }
+}

package/dist/protocol/sse-frames.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read an SSE body, invoking `onFrame` with each parsed `data:` payload.
+ * Returning `"stop"` from `onFrame` ends the read (and cancels the reader) —
+ * a single-frame endpoint must not wait for the whole connection to close.
+ */
+export declare function readSseFrames(body: ReadableStream<Uint8Array>, onFrame: (frame: Record<string, unknown>) => void | "stop"): Promise<void>;

package/dist/protocol/sse-frames.js

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// AG-UI SSE frame reader.
+//
+// The AG-UI surface streams `data: {json}` frames verbatim (no OpenAI chunk
+// mapping): the run stream and the session events channel share this reader.
+// `: comment` lines (heartbeats) and unknown fields are ignored; malformed
+// JSON is skipped — a single bad frame must not kill an observation stream.
+// ---------------------------------------------------------------------------
+/**
+ * Cap for one un-terminated frame. Frames are bounded in practice (the widest
+ * is a MESSAGES_SNAPSHOT), so the cap only bites on a stuck or hostile stream
+ * that never sends the blank-line terminator. The partial is dropped and the
+ * reader resynchronizes at the next frame boundary rather than growing the
+ * buffer without limit.
+ */
+const MAX_FRAME_CHARS = 8 * 1024 * 1024;
+/**
+ * Read an SSE body, invoking `onFrame` with each parsed `data:` payload.
+ * Returning `"stop"` from `onFrame` ends the read (and cancels the reader) —
+ * a single-frame endpoint must not wait for the whole connection to close.
+ */
+export async function readSseFrames(body, onFrame) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    /** Set when an oversized partial was dropped: skip up to the next boundary. */
+    let resyncing = false;
+    const dispatch = (frame) => {
+        if (!frame.startsWith("data: "))
+            return; // heartbeat comments
+        try {
+            return onFrame(JSON.parse(frame.slice(6)));
+        }
+        catch { /* malformed frame — ignore */ }
+    };
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            let stop = false;
+            while ((idx = buffer.indexOf("\n\n")) >= 0) {
+                const frame = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                if (resyncing) {
+                    resyncing = false; // the dropped frame ends here
+                    continue;
+                }
+                if (dispatch(frame) === "stop") {
+                    stop = true;
+                    break;
+                }
+            }
+            if (stop)
+                return;
+            if (buffer.length > MAX_FRAME_CHARS) {
+                buffer = "";
+                resyncing = true;
+            }
+        }
+        // EOF flush: a stream can deliver a complete `data:` payload but be cut
+        // before its blank-line terminator (a server crash mid-write still flushes
+        // the bytes it already wrote). Recover that final frame — malformed JSON
+        // is skipped by the same rule as inside the loop.
+        if (buffer && !resyncing)
+            dispatch(buffer);
+    }
+    finally {
+        // An early return (or a throw) leaves the body open otherwise — the
+        // connection would stay alive until the process exits.
+        reader.cancel().catch(() => { });
+    }
+}

package/dist/protocol/types.d.ts

@@ -0,0 +1,200 @@
+/** Token usage/cost numbers as carried by the AG-UI `RUN_USAGE` event. */
+export interface AgentUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    turns: number;
+    cost?: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        total: number;
+    };
+    /** Current context size (last LLM call's input tokens). */
+    contextTokens: number;
+    /** Model context window in tokens (0 = unknown). */
+    contextWindow: number;
+}
+/** A client-executed tool call requested by the agent. */
+export interface ClientToolCall {
+    id: string;
+    name: string;
+    /** Raw JSON argument string from the model. */
+    arguments: string;
+}
+/** One server-executed tool call (informational stream only). */
+export interface ServerToolEvent {
+    id: string;
+    name: string;
+    phase: "start" | "result";
+    arguments?: string;
+    result?: unknown;
+    isError?: boolean;
+}
+export interface IntegrationStatus {
+    id: string;
+    label: string;
+    enabled: boolean;
+}
+/** One directory entry from GET /integrations/workspace. */
+export interface WorkspaceEntry {
+    name: string;
+    path: string;
+    type: "file" | "directory";
+    size: number;
+    lastModified: string | null;
+}
+/** Result of GET /integrations/workspace/read. Content is base64 when binary. */
+export interface WorkspaceFile {
+    path: string;
+    content: string;
+    size: number;
+    binary: boolean;
+}
+/** Result of PUT /integrations/workspace/write. */
+export interface WorkspaceWriteResult {
+    ok: boolean;
+    size: number;
+}
+/**
+ * One entry of GET /v1/models. The list is ordered with myagent's default
+ * model first; `default` marks that entry explicitly. When the integration
+ * forces a model there is exactly one entry.
+ */
+export interface ModelInfo {
+    id: string;
+    label?: string;
+    default?: boolean;
+}
+export interface SessionSummary {
+    thread_id: string;
+    title: string;
+    status: "idle" | "running" | "compacting" | "error";
+    message_count: number;
+    created_at: number;
+    updated_at: number;
+}
+export interface ThinkingInfo {
+    levels: string[];
+    default: string;
+    reasoning: boolean;
+}
+export interface SessionUsage {
+    tokenUsage: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        totalTokens: number;
+        turns: number;
+        cost?: AgentUsage["cost"];
+    };
+    contextTokens: number;
+    contextWindow: number;
+}
+export interface HistoryToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+    result: unknown;
+    isError: boolean;
+    source: "server" | "client";
+}
+export interface HistoryMessage {
+    role: "user" | "assistant";
+    text: string;
+    createdAt: number;
+    toolCalls?: HistoryToolCall[];
+}
+export interface PendingToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface SessionDetail {
+    thread_id: string;
+    status: SessionSummary["status"];
+    message_count: number;
+    title: string;
+    created_at: number;
+    updated_at: number;
+    model?: string | null;
+    usage?: SessionUsage | null;
+    thinking?: ThinkingInfo;
+    history?: HistoryMessage[];
+    pending_tool_calls?: PendingToolCall[];
+    /** Unix ms: the previous run was interrupted by a server restart. */
+    last_run_interrupted_at?: number;
+}
+/** OpenAI-style error body from the integration API. */
+export interface ApiErrorBody {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * One verbatim AG-UI event from the run stream (or the session events
+ * channel) — the server forwards these without a lossy mapping. Only the
+ * types/fields this client consumes are modelled; unknown ones are ignored.
+ */
+export interface AguiEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/** A custom (client-executed) tool definition on the AG-UI surface. */
+export interface AguiToolDef {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** A user or system message on the AG-UI input surface. */
+export interface AguiUserMessage {
+    role: "user" | "system";
+    content: string;
+}
+/** A client tool result — resumes the run awaiting that call. */
+export interface AguiToolResult {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+    isError?: boolean;
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+}
+export type AguiInputMessage = AguiUserMessage | AguiToolResult;
+/** Body of POST /v1/runs — starts a run and streams its events. */
+export interface AguiRunRequest {
+    threadId?: string;
+    messages: AguiUserMessage[];
+    tools?: AguiToolDef[];
+    /** Client-choice model for a new thread. */
+    model?: string;
+    thinkingLevel?: string;
+}
+/** Result of a run stream that ended (server close or drop). */
+export interface RunStreamResult {
+    /** Thread id from the X-Thread-Id response header. */
+    threadId?: string;
+    /** Set when the connection dropped (network error) instead of closing cleanly. */
+    error?: string;
+}
+/** Single-frame ack of POST /v1/runs/:threadId/messages. */
+export type AguiInputAck = {
+    type: "INPUT_ACCEPTED";
+    /** Steer only: the persisted message id — correlates the later
+     *  QUEUED_MESSAGE_DELIVERED event with the submitted input. */
+    messageId?: string;
+} | {
+    type: "INPUT_REJECTED";
+    message: string;
+    code?: string;
+    details?: Record<string, unknown>;
+};

package/dist/protocol/types.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// Wire types for the MyAgent integration API
+//
+// Kept local (not imported from @agent-assistant/shared) because the CLI is a
+// standalone app outside the Bun workspace — it must compile without the
+// monorepo's node_modules. Only the fields this client consumes are modelled.
+// ---------------------------------------------------------------------------
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,38 @@
+export declare const isBun: boolean;
+export declare function fileExists(path: string): Promise<boolean>;
+export declare function readTextFile(path: string): Promise<string>;
+export declare function readJsonFile<T>(path: string): Promise<T>;
+export declare function writeFile(path: string, data: string): Promise<void>;
+/** Resolve an executable on PATH (Bun.which on Bun, a PATH scan on Node). */
+export declare function which(cmd: string): string | null;
+/** Read all of stdin as UTF-8 text. Callers check `process.stdin.isTTY` first. */
+export declare function readStdinText(): Promise<string>;
+/**
+ * True when the caller's module is the process entry point. `import.meta` is
+ * module-scoped, so the caller must pass its own (`isMainModule(import.meta)`).
+ * Bun and Node ≥24.2 expose `import.meta.main`; older Node falls back to
+ * comparing the resolved entry path (realpath, so npm/bun bin symlinks match).
+ */
+export declare function isMainModule(meta: ImportMeta): boolean;
+export interface ProcessStdin {
+    write(data: Uint8Array): void;
+    end(): void;
+}
+export interface ProcessHandle {
+    pid: number;
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    stdin: ProcessStdin;
+    exited: Promise<number>;
+    kill(signal?: number | NodeJS.Signals): void;
+}
+export interface SpawnOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: "pipe" | "ignore";
+    stdout?: "pipe" | "ignore";
+    stderr?: "pipe" | "ignore";
+    /** POSIX: run in a new process group so `process.kill(-pid)` reaches the tree. */
+    detached?: boolean;
+}
+export declare function spawnProcess(args: string[], opts?: SpawnOptions): ProcessHandle;