mandala-computer-mcp 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,186 @@
+export declare const DEFAULT_BASE_URL = "https://app.mandala.computer/api/v1";
+/** Anthropic's own key, forwarded for the one route that runs a model. */
+export declare const MODEL_KEY_HEADER = "X-Model-Key";
+export type RequestOptions = {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Raw bytes as the request body, for the file upload. Mutually exclusive with `body`. */
+    raw?: Uint8Array;
+    /** Extra headers for this call only — currently just the model key. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+};
+export type Bytes = {
+    bytes: Uint8Array;
+    contentType: string;
+    /** From Content-Disposition, when the platform named the file. */
+    filename?: string;
+    /** True when the response was deliberately stopped at the caller's cap. */
+    truncated: boolean;
+    /**
+     * Exact size when the response declared one, or when it fitted in full.
+     *
+     * On a `206` this is the WHOLE file's length, off `Content-Range`, and not
+     * the length of the window that came back — which is the number a caller
+     * paging through a file needs and the only place it appears.
+     */
+    totalBytes?: number;
+    /**
+     * Which bytes of the file these are, when the platform served a window.
+     *
+     * Present only on a `206`, because that status is the only promise that the
+     * `Range` was honoured. A `200` may perfectly well be a response to a request
+     * that carried one — an unmeasurable file has no byte positions to name, so
+     * the platform ignores the header and sends the whole thing — and reporting
+     * the head of a file as the window somebody asked for is how a paging loop
+     * reads the same bytes forever.
+     *
+     * `total` is absent for a `Content-Range` whose total is `*`: the window is
+     * known and the file's length is not.
+     */
+    window?: {
+        start: number;
+        end: number;
+        total?: number;
+    };
+    /**
+     * True when the response said this file cannot be served in windows at all.
+     *
+     * `Accept-Ranges: none`, which the platform sets for a file whose length the
+     * guest could not measure — a `/proc` entry, say. Worth keeping apart from a
+     * merely absent window, because it is the difference between "ask again
+     * differently" and "there is no offset that will work on this file".
+     */
+    unrangeable: boolean;
+};
+/**
+ * The longest guest exec waits 300 seconds before it answers. Node's bundled
+ * fetch also gives response headers 300 seconds by default, so the client can
+ * lose that race while the command is still finishing in the guest. Keep the
+ * public exec limit and give the platform enough time to report its timeout.
+ *
+ * The body is a different clock. undici's default `bodyTimeout` is 300 seconds
+ * of silence *between chunks*, and `run_agent` SSE (or a long exec that has
+ * already sent headers) can sit quiet after that. Raising only the header
+ * allowance left those streams aborting on the default idle limit. Zero
+ * disables it: a quiet gap is not a dead connection, and the caller's
+ * AbortSignal is what ends a request nobody is waiting for.
+ */
+export declare const PLATFORM_HEADERS_TIMEOUT_MS = 330000;
+/** Disabled. A finite idle limit is what used to kill a quiet SSE stream. */
+export declare const PLATFORM_BODY_TIMEOUT_MS = 0;
+/**
+ * The fetch a platform request actually goes through, and why it is not simply
+ * `fetch`.
+ *
+ * The dispatcher above is an Agent from the `undici` PACKAGE, and Node's
+ * built-in fetch is a DIFFERENT COPY of undici — the one bundled with the
+ * runtime. Handing one's Agent to the other's fetch works only while the two
+ * agree on the internal handler interface, and they have stopped agreeing:
+ * Node 26 bundles undici 8.9, whose fetch passes a handler that undici 6's
+ * Agent rejects outright with `invalid onError method`. That surfaces here as
+ * `fetch failed`, which this class then wraps as "could not reach
+ * app.mandala.computer" — so on Node 26 every call this server makes reported
+ * the platform as down, before a packet was sent.
+ *
+ * NOT FIXABLE BY A VERSION BUMP, which is the thing worth writing down: npm's
+ * newest undici is 7.x and Node 26 bundles 8.x, so no dependency this package
+ * can declare matches what the runtime carries — and even if one did, matching
+ * Node 26 would mean mismatching Node 20, which `engines` still admits. Two
+ * undicis is the bug; using one of them for both halves is the fix.
+ *
+ * So the request goes through undici's OWN fetch, which understands its own
+ * Agent on every Node. The global is still preferred when something has
+ * replaced it: that is how the tests stand a stub in front of the platform, and
+ * an embedder that installs an instrumented fetch means it to be used.
+ */
+export declare const platformFetch: () => typeof globalThis.fetch;
+/** One server-sent event off the agent route. */
+export type SSEEvent = {
+    event: string;
+    data: unknown;
+};
+/**
+ * The transport for one API key.
+ *
+ * One per MCP session rather than one per process, because the HTTP transport
+ * authenticates each caller with their own `com_…` key and two sessions must
+ * never share a client. See `src/session.ts`.
+ *
+ * The key lives in this object's closure and is never put on an error, a log
+ * line, or a tool result. That is not paranoia about our own code: an MCP tool
+ * result goes into a model's context and from there into transcripts, and an
+ * API key is every computer on the account, forever.
+ */
+export declare class Api {
+    #private;
+    readonly baseUrl: string;
+    constructor(apiKey: string, baseUrl?: string, signal?: AbortSignal);
+    /**
+     * This same client, with every request bound to one tool call's cancellation.
+     *
+     * MCP hands a tool handler an `AbortSignal` that fires when the client gives
+     * up on the call, and a request nobody is waiting for is one this server
+     * should stop making — most of all in the tools that poll. A cancelled
+     * `wait_for_computer` would otherwise go on asking the platform about a
+     * computer for the rest of its `timeout_s`, which reaches fifteen minutes.
+     *
+     * Bound per call rather than per session, because a session serves many calls
+     * at once and one of them being abandoned says nothing about the others.
+     */
+    with(signal: AbortSignal | undefined): Api;
+    /**
+     * A JSON body, from a route that is supposed to have one.
+     *
+     * An empty answer here is a failure, not a value, and it has to be said so
+     * rather than cast away. `as T` was a lie the compiler could not catch: a 204
+     * on a route that should have answered handed every caller `undefined` typed
+     * as present, and what a caller does with that is either `text: undefined` —
+     * which is not a valid tool result, so the client rejects the whole call with
+     * a schema error naming nothing useful — or a TypeError reading a field off
+     * it. Both report the platform's silence as this server's own bug.
+     *
+     * Routes where an empty body IS the answer use `send`.
+     */
+    json<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    /**
+     * A request whose answer may legitimately be nothing.
+     *
+     * The DELETEs and the acknowledgements: /api/v1 answers some of them with a
+     * body worth repeating and some with a 204, and both are correct. Typed as
+     * possibly-absent so a caller has to decide what to say when it is.
+     */
+    send<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T | undefined>;
+    /**
+     * A collection read that the platform may have had to answer short.
+     *
+     * `GET /computers` and `GET /snapshots` are fan-outs across the fleet, so a
+     * hypervisor nobody can reach makes the answer incomplete. /api/v1 fails
+     * closed about that — without `allow_partial` a short listing is a 503, not a
+     * short 200 — but a caller that opts in gets the list plus `X-GC-Incomplete`,
+     * and a header is only a warning if something reads it.
+     *
+     * It is the count of what the placement cache could account for, and it is
+     * legitimately `0`: a computer created during the outage was never cached
+     * against the host now holding it. So presence is the signal and the number is
+     * detail, which is why this returns `null` versus a number rather than a
+     * count that means nothing at zero.
+     */
+    listing<T>(path: string, opts?: RequestOptions): Promise<{
+        items: T | undefined;
+        incomplete: number | null;
+    }>;
+    /** For the two routes whose body is not JSON: the screenshot and the download. */
+    bytes(method: string, path: string, opts?: RequestOptions, maxBytes?: number | ((contentType: string) => number)): Promise<Bytes>;
+    /**
+     * The agent route, which answers with a stream of steps rather than a result.
+     *
+     * Yielded rather than collected so the caller can report progress while the
+     * run is going. A run is minutes of clicking; a tool that says nothing until
+     * it is over is one the person watching cannot tell from a hang.
+     */
+    sse(method: string, path: string, opts?: RequestOptions): AsyncGenerator<SSEEvent>;
+}
+/** The filename the platform put on a download, if it put one there. */
+export declare function filenameFrom(disposition: string | null): string | undefined;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}