mandala-computer-mcp 0.1.0

package/dist/tools/agent.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { MODEL_KEY_HEADER } from '../api.js';
+import { guarded, refused, said } from '../format.js';
+import * as P from '../paths.js';
+/**
+ * The platform's own agent loop, as one tool.
+ *
+ * Registered only when a model key is configured, and that is the point of the
+ * conditional: a tool a model can see is a tool it will try, and one that fails
+ * on every call with "no model key" costs a turn to discover. Absent is a
+ * clearer answer than present-and-broken.
+ *
+ * Worth having even though the caller is already a model with eyes. The outer
+ * agent pays for every screenshot in context; this route runs the pixel-level
+ * loop inside the platform on the caller's own Anthropic key and hands back a
+ * sentence. Ten clicks stop being ten images.
+ */
+export const registerAgent = (server, session) => {
+    if (!session.modelKey)
+        return;
+    server.registerTool('run_agent', {
+        title: 'Have the platform drive the computer',
+        description: 'Give the computer a task in plain language and let the platform drive it — screenshot, decide, click, type, repeat — until it is done. Runs on the Anthropic key this server was configured with, and bills that key for every step. Use it to delegate a long stretch of pixel work; drive with the individual tools when you want to see each frame yourself. The computer must already be running. A run is MINUTES, not seconds: it reports progress on every step so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open, and a client that cannot should lower max_steps rather than watch its own default timeout cancel a run it is already paying for.',
+        inputSchema: {
+            computer_id: z
+                .string()
+                .optional()
+                .describe('Which computer. Defaults to the one selected with use_computer.'),
+            prompt: z.string().describe('The task, in plain language.'),
+            system: z.string().optional().describe('Standing instructions carried into the run.'),
+            max_steps: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe('Each step is a model call plus a screenshot on your key, so this is a spending cap as much as a loop bound.'),
+        },
+        annotations: { openWorldHint: true },
+    }, ({ computer_id, prompt, system, max_steps }, extra) => guarded(async () => {
+        const id = session.resolve(computer_id);
+        const steps = [];
+        let done;
+        // The token the CLIENT sends when it wants progress, exactly as
+        // watch_build reads it. Without one there is nothing to address a
+        // progress notification to, and this falls back to logging alone.
+        const progressToken = extra._meta?.progressToken;
+        for await (const ev of session.api.sse('POST', P.computerAction(id, 'agent'), {
+            body: P.agentBody({ prompt, system, max_steps, stream: true }),
+            headers: { [MODEL_KEY_HEADER]: session.modelKey },
+            signal: extra.signal,
+        })) {
+            if (ev.event === 'step') {
+                if (!isRecord(ev.data))
+                    continue;
+                const s = ev.data;
+                steps.push(`${s.n ?? steps.length + 1}. ${s.detail ?? s.action ?? 'step'}`);
+                // A PROGRESS notification, not only a logging one, for the reason
+                // watch_build sends one: `_onprogress` in the SDK's
+                // shared/protocol.js resets a pending request's timer, and
+                // `notifications/message` — what sendLoggingMessage emits — never
+                // touches it. This tool had only the logging half, so a run of the
+                // default 20 steps, each a model call plus a screenshot, sailed past
+                // the client's 60s default and was cancelled while the platform went
+                // on driving the desktop on the caller's own Anthropic key.
+                //
+                // Not sufficient on its own, and the same caveat applies here as
+                // there: protocol.js reads `options?.resetTimeoutOnProgress ?? false`,
+                // so a client that mints a token and leaves that option alone is
+                // still cancelled. What this does is make the keepalive AVAILABLE.
+                // The description says so, and max_steps is the lever for a client
+                // that cannot opt in.
+                if (progressToken !== undefined) {
+                    await extra
+                        .sendNotification({
+                        method: 'notifications/progress',
+                        params: {
+                            progressToken,
+                            // The step COUNT, which the SDK's ProgressSchema asks to
+                            // increase every time. `max_steps` is a real total here —
+                            // unlike a build's step count it is known before the first
+                            // step and cannot change — so the bar means something.
+                            progress: steps.length,
+                            total: max_steps,
+                            message: steps[steps.length - 1],
+                        },
+                    })
+                        .catch(() => { });
+                }
+                // Told, not just collected. A run is minutes of clicking, and a tool
+                // that says nothing until it is over is one nobody watching can tell
+                // from a hang.
+                await server.server
+                    .sendLoggingMessage({ level: 'info', data: steps[steps.length - 1] })
+                    .catch(() => { });
+            }
+            else if (ev.event === 'done') {
+                // Stop at the terminal frame rather than waiting for EOF, as
+                // watch_build does. Waiting held a result that was already in hand
+                // until the generator ended, so a client that aborted in that window
+                // — or a stream the platform left open — turned a finished run into
+                // a CancelledError and threw the answer away.
+                //
+                // Terminal means it SAYS SO, which is watch_build's discipline
+                // (OPL-3835) applied to this stream's own vocabulary: `stop` is the
+                // field the platform always sends on a result — the AgentResult type
+                // in its lib/agent.ts requires it, and every `done` it yields carries
+                // one — and it is the field the verdict below reads. A record
+                // without it is not a result, so it is kept, in case nothing better
+                // arrives, but it does not end the loop and discard the frame that
+                // would have been the real one. A `done` that is not a record at all
+                // is skipped entirely: the null-done case the regression suite pins.
+                if (isRecord(ev.data)) {
+                    done = ev.data;
+                    if (typeof ev.data.stop === 'string' && ev.data.stop)
+                        break;
+                }
+            }
+            else if (ev.event === 'error') {
+                // A run that errored is a failure, and has to carry `isError` to
+                // say so. Prose alone leaves it indistinguishable at the protocol
+                // level from a run that worked — a caller checking whether the step
+                // succeeded would read this one as a success that happened to have
+                // a discouraging sentence in it.
+                return refused(`The run failed after ${steps.length} step(s).`, ev.data);
+            }
+        }
+        if (!done) {
+            return refused(`The stream ended without a result after ${steps.length} step(s). What it did:\n${steps.join('\n')}`);
+        }
+        // `stop` is the field that matters and the one a caller most easily
+        // ignores: a run that hit max_steps ended without finishing, and
+        // treating every ending as success reports a failure as a result.
+        const stop = String(done.stop ?? 'unknown');
+        const verdict = stop === 'end_turn'
+            ? 'finished'
+            : stop === 'max_steps'
+                ? `RAN OUT OF STEPS after ${done.steps ?? max_steps} — the task is probably unfinished`
+                : stop === 'refusal'
+                    ? 'the model declined the task'
+                    : `ended: ${stop}`;
+        const result = `${verdict}\n\n${String(done.text ?? '')}\n\nWhat it did:\n${steps.join('\n')}`;
+        return stop === 'end_turn' ? said(result, done) : refused(result, done);
+    }));
+};
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+//# sourceMappingURL=agent.js.map

package/dist/tools/agent.js.map

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

package/dist/tools/computers.d.ts

@@ -0,0 +1,3 @@
+import type { Registrar } from './types.js';
+export declare const registerComputers: Registrar;
+//# sourceMappingURL=computers.d.ts.map

package/dist/tools/computers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computers.d.ts","sourceRoot":"","sources":["../../src/tools/computers.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA8P5C,eAAO,MAAM,iBAAiB,EAAE,SA6iC/B,CAAC"}