@ocis/myagent-cli 0.2.0

package/dist/index.js

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// myagent CLI — entry point.
+//
+// Interactive TUI by default; `-p`/`run`/piped stdin switch to headless mode.
+// Credentials resolve flags > env > config file; the config wizard lives under
+// `myagent config`.
+// ---------------------------------------------------------------------------
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { IntegrationClient } from "./protocol/client.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { combinedIntegrationUrl, configDir, isConfigured, loadConfig, migrateLegacyConfigDir, resolveConfig, saveConfig, sessionsPath, splitIntegrationUrl, } from "./config.js";
+import { SessionIndex } from "./agent/sessions.js";
+import { DEFAULT_MODE } from "./agent/modes.js";
+import { runTui } from "./ui/app.js";
+import { failureDoneEvent, failureResult, runHeadless } from "./headless.js";
+import { discoverSkills, formatSkillList, resolveSkillDirs } from "./skills/discovery.js";
+import { sanitizeForTerminal } from "./sanitize.js";
+import { isMainModule, readJsonFile, readStdinText } from "./runtime.js";
+/**
+ * Package version, read from package.json so npm releases never drift from
+ * `--version`. Resolves to the package root from both src/ (dev) and dist/.
+ */
+async function readVersion() {
+    try {
+        const pkg = await readJsonFile(fileURLToPath(new URL("../package.json", import.meta.url)));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const HELP = `myagent — a coding agent for your local repository, powered by MyAgent
+
+Usage:
+  myagent [options] [prompt...]          interactive TUI (or headless if not a TTY)
+  myagent run [options] [prompt...]      one-shot; prompt from args or stdin
+  myagent -p "prompt"                    same as run
+  myagent --prompt "prompt"              prompt mode: unattended one-shot (CI)
+  myagent config                         configure credentials interactively
+  myagent config show                    print the current config (redacted)
+  myagent skills                         list locally installed skills
+  myagent sessions                       list remote sessions
+
+Connection:
+  --base-url <url>          MyAgent base URL (env MYAGENT_BASE_URL)
+  --integration-id <id>     integration id (env MYAGENT_INTEGRATION_ID)
+  --api-key <key>           integration API key (env MYAGENT_API_KEY)
+
+Session:
+  -c, --continue            continue the most recent session for this directory
+  -r, --resume              resume the most recent session (same as -c)
+  --session <thread-id>     resume a specific remote session
+
+Agent:
+  --plan                    start in plan mode (read-only)
+  --coding                  start in coding mode (software work; default)
+  --cowork                  start in cowork mode (general tasks)
+  --ask                     confirm mutating tools (interactive only; headless denies them)
+  --auto                    run tools unattended (default)
+  --model <id>              model for new sessions (client-choice integrations; see /v1/models)
+  --thinking <level>        off | minimal | low | medium | high | xhigh | max | default
+  --skills-dir <dir>        extra skills directory (repeatable)
+  --allow-outside           allow tools to touch paths outside the workspace
+  --no-context-files        do not load AGENTS.md / CLAUDE.md
+
+Prompt mode (CI):
+  --prompt <text|->         non-interactive one-shot: auto-approves every tool
+                            (including paths outside the workspace) and prints
+                            only the final assistant message. "-" reads stdin.
+  --timeout <sec>           abort the run after N seconds (headless only)
+
+Output:
+  --output-format <fmt>     text | json | stream-json (headless only)
+  --no-logo                 skip the startup logo animation
+  -q, --quiet               suppress tool/progress output (headless)
+
+Exit codes:
+  0 success · 1 run failed (incl. timeout) · 2 usage/config/connection error
+  130/143 interrupted (SIGINT/SIGTERM)
+
+Other:
+  -h, --help                show this help
+  -v, --version             show the version
+`;
+export function parseArgs(argv) {
+    const args = { command: "chat", flags: {}, skillsDirs: [], promptParts: [] };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = (name) => {
+            const value = argv[++i];
+            if (value === undefined)
+                throw new Error(`Missing value for ${name}`);
+            return value;
+        };
+        switch (arg) {
+            case "run":
+                args.command = "run";
+                break;
+            case "config":
+                args.command = "config";
+                args.configSub = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : undefined;
+                break;
+            case "skills":
+                args.command = "skills";
+                break;
+            case "sessions":
+                args.command = "sessions";
+                break;
+            case "-h":
+            case "--help":
+                args.command = "help";
+                break;
+            case "-v":
+            case "--version":
+                args.command = "version";
+                break;
+            case "--base-url":
+                args.flags.baseUrl = next(arg);
+                break;
+            case "--integration-id":
+                args.flags.integrationId = next(arg);
+                break;
+            case "--api-key":
+                args.flags.apiKey = next(arg);
+                break;
+            case "--workspace":
+            case "-w":
+                args.flags.workspace = next(arg);
+                break;
+            case "-c":
+            case "--continue":
+            case "-r":
+            case "--resume":
+                args.flags.continue = true;
+                break;
+            case "--session":
+                args.flags.session = next(arg);
+                break;
+            case "--plan":
+                args.flags.mode = "plan";
+                break;
+            case "--coding":
+                args.flags.mode = "coding";
+                break;
+            case "--cowork":
+                args.flags.mode = "cowork";
+                break;
+            case "--ask":
+                args.flags.ask = true;
+                break;
+            case "--auto":
+                args.flags.auto = true;
+                break;
+            case "--thinking":
+                args.flags.thinking = next(arg);
+                break;
+            case "--model":
+                args.flags.model = next(arg);
+                break;
+            case "--skills-dir":
+                args.skillsDirs.push(next(arg));
+                break;
+            case "--allow-outside":
+                args.flags.allowOutside = true;
+                break;
+            case "--no-context-files":
+                args.flags.noContextFiles = true;
+                break;
+            case "--no-logo":
+                args.flags.noLogo = true;
+                break;
+            case "-q":
+            case "--quiet":
+                args.flags.quiet = true;
+                break;
+            case "--prompt":
+                args.flags.prompt = next(arg);
+                break;
+            case "--timeout": {
+                const raw = next(arg);
+                const value = Number(raw);
+                // setTimeout coerces delays above 2^31-1 ms to 1 ms — an oversized
+                // value would fire immediately, the opposite of the user's intent.
+                if (!Number.isFinite(value) || value <= 0 || value * 1000 > 2_147_483_647) {
+                    throw new Error(`Invalid --timeout "${raw}" (positive seconds, max 2147483)`);
+                }
+                args.flags.timeout = value;
+                break;
+            }
+            case "--output-format": {
+                const value = next(arg);
+                if (value !== "text" && value !== "json" && value !== "stream-json") {
+                    throw new Error(`Invalid --output-format "${value}" (text | json | stream-json)`);
+                }
+                args.flags.outputFormat = value;
+                break;
+            }
+            case "-p":
+            case "--print":
+                args.command = args.command === "chat" ? "run" : args.command;
+                break;
+            default:
+                if (arg.startsWith("-") && arg !== "-")
+                    throw new Error(`Unknown option: ${arg}`);
+                rest.push(arg);
+        }
+    }
+    args.promptParts = rest;
+    return args;
+}
+/**
+ * Interactive means the TUI: a plain `chat` invocation with both streams on a
+ * TTY. `run`/`-p`, `--prompt`, `--output-format`, and piped stdin all mean
+ * headless.
+ */
+export function isInteractiveMode(args, stdinIsTty, stdoutIsTty) {
+    return (args.command === "chat" &&
+        !args.flags.outputFormat &&
+        !args.flags.prompt &&
+        stdinIsTty &&
+        stdoutIsTty);
+}
+/**
+ * Whether stdin should be read as prompt text. Piped stdin is a prompt for
+ * every headless path (`echo fix | myagent`); an inline `--prompt` never reads
+ * it (a CI stdin may be an open pipe — reading it would hang), while
+ * `--prompt -` reads it explicitly.
+ */
+export function shouldReadStdin(args, interactive) {
+    if (interactive)
+        return false;
+    // An inline --prompt is the whole prompt; `-` and no flag read stdin.
+    return args.flags.prompt === undefined || args.flags.prompt === "-";
+}
+/** Join the prompt sources: positional words, `--prompt` (or stdin), piped stdin. */
+export function assemblePrompt(args, stdinText) {
+    const promptFromStdin = args.flags.prompt === "-";
+    return [
+        ...args.promptParts,
+        promptFromStdin ? "" : args.flags.prompt,
+        stdinText.trim(),
+    ].filter(Boolean).join("\n");
+}
+/**
+ * Report a pre-run failure (usage/config/connection) in the requested output
+ * format and return the exit code. `json` always emits a parseable object — a
+ * CI parser must never see an empty stdout; `stream-json` emits a terminal
+ * `done` event; text goes to stderr.
+ */
+export function fail(format, message, errorCode) {
+    if (format === "json") {
+        process.stdout.write(failureResult(message, errorCode) + "\n");
+    }
+    else if (format === "stream-json") {
+        process.stdout.write(failureDoneEvent(message, errorCode) + "\n");
+    }
+    else {
+        process.stderr.write(message + "\n");
+    }
+    return 2;
+}
+/**
+ * Read piped stdin as prompt text. Bounded by the run's `--timeout` when one
+ * is set: a non-TTY stdin that never closes (a CI misconfiguration like
+ * `docker run -i` without `< /dev/null`) would otherwise hang before the
+ * run's own timeout control is even created. Returns null on timeout so the
+ * caller can fail with a clear message instead of running an empty prompt.
+ */
+export async function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return "";
+    const read = readStdinText().catch(() => "");
+    if (!timeoutMs)
+        return read;
+    let timer = null;
+    try {
+        return await Promise.race([
+            read,
+            new Promise((resolve) => { timer = setTimeout(() => resolve(null), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function main() {
+    await migrateLegacyConfigDir();
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n\n${HELP}`);
+        return 2;
+    }
+    if (args.command === "help") {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (args.command === "version") {
+        process.stdout.write(`${await readVersion()}\n`);
+        return 0;
+    }
+    const stored = await loadConfig();
+    const config = resolveConfig(stored, args.flags);
+    if (args.command === "config") {
+        if (args.configSub === "show") {
+            process.stdout.write(`apiBaseUrl:    ${combinedIntegrationUrl(config) || "(unset)"}\n` +
+                `apiKey:        ${config.apiKey ? `${"•".repeat(8)}…${config.apiKey.slice(-4)}` : "(unset)"}\n` +
+                `approvalDefault: ${config.approvalDefault}\n` +
+                `config file:   ${configDir()}/config.json\n`);
+            return 0;
+        }
+        // The wizard edits the FILE, so it must see the file's values — not the
+        // env/flag-merged runtime config. Otherwise pressing Enter through the
+        // prompts would persist a temporary MYAGENT_API_KEY / --base-url into
+        // config.json without ever saying so.
+        return await configWizard(stored);
+    }
+    const workspace = resolveWorkspace(args.flags.workspace);
+    const skillDirs = await resolveSkillDirs(workspace, configDir(), args.skillsDirs);
+    if (args.command === "skills") {
+        const skills = await discoverSkills(skillDirs);
+        process.stdout.write(`Search paths:\n${skillDirs.map((d) => `  ${d}`).join("\n")}\n\n${formatSkillList(skills)}\n`);
+        return 0;
+    }
+    if (!isConfigured(config)) {
+        return fail(args.flags.outputFormat, "Not configured. Run `myagent config` first, or pass --base-url/--integration-id/--api-key.\n" +
+            "Create an integration and API key on the MyAgent Integrations page.", "not_configured");
+    }
+    const client = new IntegrationClient({
+        baseUrl: config.baseUrl,
+        integrationId: config.integrationId,
+        apiKey: config.apiKey,
+    });
+    let status;
+    try {
+        // Bounded connect: a hung server must fail (exit 2) instead of hanging CI.
+        status = await client.getStatus({ signal: AbortSignal.timeout(30_000) });
+    }
+    catch (err) {
+        return fail(args.flags.outputFormat, `Could not reach ${config.baseUrl}: ${err instanceof Error ? err.message : String(err)}`, "connection_failed");
+    }
+    if (!status.enabled) {
+        return fail(args.flags.outputFormat, `Integration "${status.label}" is disabled on the server.`, "integration_disabled");
+    }
+    const sessionIndex = await SessionIndex.load(sessionsPath());
+    if (args.command === "sessions") {
+        const sessions = await client.listSessions();
+        return printSessions(sessions);
+    }
+    const mode = args.flags.mode ?? DEFAULT_MODE;
+    const promptMode = args.flags.prompt !== undefined;
+    // Prompt mode is unattended by contract: every tool runs, including paths
+    // outside the workspace — no one is present to answer an approval prompt.
+    const approval = promptMode
+        ? "auto"
+        : args.flags.ask
+            ? "ask"
+            : args.flags.auto
+                ? "auto"
+                : config.approvalDefault;
+    const allowOutside = promptMode ? true : (args.flags.allowOutside ?? false);
+    const resumeThreadId = args.flags.session
+        ?? (args.flags.continue ? sessionIndex.lastThread(workspace) : undefined);
+    // `--prompt` is unattended by contract, so an explicit `--ask` cannot be
+    // honored — say so instead of silently dropping the safer setting.
+    if (promptMode && args.flags.ask) {
+        process.stderr.write("Warning: --ask is ignored with --prompt (unattended mode auto-approves every tool, including paths outside the workspace).\n");
+    }
+    const interactive = isInteractiveMode(args, Boolean(process.stdin.isTTY), Boolean(process.stdout.isTTY));
+    const readsStdin = shouldReadStdin(args, interactive);
+    // A prompt is already complete, yet stdin is still read (it may carry extra
+    // context: `cat log | myagent run "summarize:"`). Reading blocks until EOF,
+    // so a non-TTY stdin that never closes (CI `docker run -i` without
+    // `< /dev/null`) would hang silently — announce the wait instead.
+    if (readsStdin && !process.stdin.isTTY && args.promptParts.length > 0 && !args.flags.timeout) {
+        process.stderr.write("Reading additional prompt text from stdin until EOF — pass `< /dev/null` or --timeout <sec> if nothing is piped.\n");
+    }
+    const stdinText = readsStdin
+        ? await readStdin(args.flags.timeout ? args.flags.timeout * 1000 : undefined)
+        : "";
+    if (stdinText === null) {
+        return fail(args.flags.outputFormat, `Timed out after ${args.flags.timeout}s waiting for stdin.`, "timeout");
+    }
+    const prompt = assemblePrompt(args, stdinText);
+    const registry = new ToolRegistry();
+    if (interactive) {
+        return await runTui({
+            client,
+            registry,
+            config,
+            sessionIndex,
+            workspace,
+            allowOutside: args.flags.allowOutside ?? false,
+            skillDirs,
+            noContextFiles: args.flags.noContextFiles,
+            initialMode: mode,
+            initialApproval: approval,
+            initialThinking: args.flags.thinking === "default" ? undefined : args.flags.thinking,
+            initialModel: args.flags.model,
+            initialPrompt: prompt || undefined,
+            resumeThreadId,
+            noLogo: args.flags.noLogo,
+        });
+    }
+    if (!prompt) {
+        return fail(args.flags.outputFormat, "No prompt provided. Usage: myagent -p \"...\" or pipe text via stdin.", "no_prompt");
+    }
+    return await runHeadless({
+        client,
+        registry,
+        sessionIndex,
+        workspace,
+        allowOutside,
+        skillDirs,
+        mode,
+        approval,
+        model: args.flags.model,
+        thinkingLevel: args.flags.thinking === "default" ? undefined : args.flags.thinking,
+        noContextFiles: args.flags.noContextFiles,
+        resumeThreadId,
+        prompt,
+        outputFormat: args.flags.outputFormat ?? "text",
+        quiet: args.flags.quiet,
+        lastMessageOnly: promptMode,
+        timeoutMs: args.flags.timeout ? args.flags.timeout * 1000 : undefined,
+    });
+}
+function printSessions(sessions) {
+    if (sessions.length === 0) {
+        process.stdout.write("No remote sessions.\n");
+        return 0;
+    }
+    for (const session of sessions) {
+        const updated = new Date(session.updated_at).toLocaleString();
+        // Remote free text (title, status) reaches the real terminal here — same
+        // sanitizing rule as the TUI transcript and the headless writer.
+        const line = `${session.thread_id}  ${session.status.padEnd(10)} ${String(session.message_count).padStart(4)} msgs  ${updated}  ${session.title}`;
+        process.stdout.write(`${sanitizeForTerminal(line)}\n`);
+    }
+    return 0;
+}
+/** Resolve the workspace flag (with ~ expansion) against the process cwd. */
+function resolveWorkspace(flag) {
+    if (!flag)
+        return process.cwd();
+    const expanded = flag.replace(/^~(?=$|\/)/, homedir());
+    return resolve(expanded);
+}
+async function configWizard(config) {
+    const rl = createInterface({ input, output });
+    try {
+        // The Integrations page shows one combined URL (`<host>/integrations/<id>`)
+        // — accept it here and derive the id, so pasting it just works.
+        const baseUrlDefault = combinedIntegrationUrl(config) || "https://...";
+        const baseUrlInput = (await rl.question(`API base URL [${baseUrlDefault}]: `)).trim() || config.baseUrl;
+        const { baseUrl, integrationId: derivedId } = splitIntegrationUrl(baseUrlInput);
+        const integrationIdDefault = derivedId ?? config.integrationId;
+        const integrationId = (await rl.question(`Integration ID [${integrationIdDefault || "..."}]: `)).trim() || integrationIdDefault;
+        const apiKey = (await rl.question(`API key [${config.apiKey ? "unchanged" : "iak_..."}]: `)).trim() || config.apiKey;
+        const next = { ...config, baseUrl, integrationId, apiKey };
+        if (baseUrl && integrationId && apiKey) {
+            const client = new IntegrationClient({ baseUrl, integrationId, apiKey });
+            try {
+                const status = await client.getStatus();
+                process.stdout.write(`Connected: ${status.label} (${status.enabled ? "enabled" : "DISABLED"})\n`);
+            }
+            catch (err) {
+                process.stdout.write(`Connection test failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                const saveAnyway = (await rl.question("Save anyway? [y/N] ")).trim().toLowerCase();
+                if (saveAnyway !== "y" && saveAnyway !== "yes")
+                    return 1;
+            }
+        }
+        // Informed consent for the approval default: AUTO runs workspace tool
+        // actions (shell, write, edit) unattended — only outside-workspace paths
+        // still prompt. The current value is the preselected answer.
+        const approvalHint = next.approvalDefault === "auto" ? "Y/n" : "y/N";
+        const approval = (await rl.question(`Auto-approve tool actions inside the workspace (shell/write/edit run unattended; outside-workspace paths always ask)? [${approvalHint}]: `)).trim().toLowerCase();
+        if (["y", "yes"].includes(approval))
+            next.approvalDefault = "auto";
+        if (["n", "no"].includes(approval))
+            next.approvalDefault = "ask";
+        if (!isConfigured(next)) {
+            process.stderr.write("Configuration incomplete — base URL, integration ID, and API key are all required. Nothing was saved.\n");
+            return 1;
+        }
+        await saveConfig(next);
+        process.stdout.write(`Saved to ${configDir()}/config.json\n`);
+        return 0;
+    }
+    finally {
+        rl.close();
+    }
+}
+if (isMainModule(import.meta)) {
+    main()
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/protocol/client.d.ts

@@ -0,0 +1,123 @@
+import type { AguiEvent, AguiInputMessage, AguiRunRequest, AguiToolDef, IntegrationStatus, ModelInfo, RunStreamResult, SessionDetail, SessionSummary, WorkspaceEntry, WorkspaceFile, WorkspaceWriteResult } from "./types.js";
+export interface IntegrationClientOptions {
+    baseUrl: string;
+    integrationId: string;
+    apiKey: string;
+    /** Injectable fetch (tests). */
+    fetch?: typeof fetch;
+}
+/** Error thrown for non-2xx integration API responses. */
+export declare class IntegrationApiError extends Error {
+    readonly status: number;
+    /** Machine-readable discriminator from the error body (e.g. `tool_call_expired`). */
+    readonly code?: string | undefined;
+    /** Additive machine-readable context (e.g. `{ expiredIds }`). */
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, status: number, 
+    /** Machine-readable discriminator from the error body (e.g. `tool_call_expired`). */
+    code?: string | undefined, 
+    /** Additive machine-readable context (e.g. `{ expiredIds }`). */
+    details?: Record<string, unknown> | undefined);
+}
+/** Options for a run stream (AG-UI surface). */
+export interface RunStreamOptions {
+    signal?: AbortSignal;
+    onEvent: (event: AguiEvent) => void;
+    /** Called as soon as the server reports the thread id (X-Thread-Id header). */
+    onThreadId?: (threadId: string) => void;
+}
+/** One client tool result as the local execution layer produces it. */
+export interface ToolOutput {
+    tool_call_id: string;
+    output: string;
+    isError?: boolean;
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+}
+export declare class IntegrationClient {
+    readonly baseUrl: string;
+    readonly integrationId: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(opts: IntegrationClientOptions);
+    private url;
+    private headers;
+    /**
+     * 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`.
+     */
+    startRun(req: AguiRunRequest, opts: RunStreamOptions): Promise<RunStreamResult>;
+    /**
+     * 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.
+     */
+    sendRunMessages(threadId: string, messages: AguiInputMessage[], opts?: {
+        tools?: AguiToolDef[];
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
+    getStatus(opts?: {
+        signal?: AbortSignal;
+    }): Promise<IntegrationStatus>;
+    /**
+     * 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.
+     */
+    listModels(): Promise<ModelInfo[]>;
+    listSessions(): Promise<SessionSummary[]>;
+    getSession(threadId: string, opts?: {
+        history?: boolean;
+        historyLimit?: number;
+    }): Promise<SessionDetail>;
+    patchSessionTitle(threadId: string, title: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    deleteSession(threadId: string): Promise<void>;
+    stopSession(threadId: string): Promise<void>;
+    compactSession(threadId: string, focus?: string): Promise<void>;
+    /** GET /integrations/<id>/workspace?path= — list a workspace directory. */
+    workspaceList(path: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceEntry[]>;
+    /** GET /integrations/<id>/workspace/read?path= — read one file (base64 when binary). */
+    workspaceRead(path: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceFile>;
+    /** PUT /integrations/<id>/workspace/write — create or overwrite one file. */
+    workspaceWrite(path: string, content: string, binary: boolean, opts?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceWriteResult>;
+    /**
+     * 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).
+     */
+    openSessionEvents(threadId: string, opts: {
+        signal?: AbortSignal;
+        onEvent: (event: Record<string, unknown>) => void;
+    }): Promise<void>;
+    private json;
+    /** Build an IntegrationApiError from a non-OK response, preserving the
+     *  machine-readable `error.code` (e.g. `tool_call_expired`). */
+    private apiError;
+}