mandala-computer-mcp 0.4.0 → 0.5.0

package/dist/stdio.d.ts

@@ -1,4 +1,8 @@
 import { type ServerConfig } from './server.js';
+export type StdioConfig = Omit<ServerConfig, 'apiKey'> & {
+    apiKey?: string;
+    profile?: string;
+};
 /**
  * The local install: one process, one key, spawned by the MCP client.
  *
@@ -7,5 +11,5 @@ import { type ServerConfig } from './server.js';
  * here may ever write to stdout: that stream is the protocol, and one stray
  * console.log is a parse error at the other end. Diagnostics go to stderr.
  */
-export declare function runStdio(cfg: ServerConfig): Promise<void>;
+export declare function runStdio(cfg?: StdioConfig): Promise<void>;
 //# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC/D"}
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,GAAG,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCnE"}

package/dist/stdio.js

@@ -1,5 +1,5 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { DEFAULT_BASE_URL } from './api.js';
+import { resolveCredentials } from './credentials.js';
 import { createServer } from './server.js';
 /**
  * The local install: one process, one key, spawned by the MCP client.
@@ -9,8 +9,14 @@ import { createServer } from './server.js';
  * here may ever write to stdout: that stream is the protocol, and one stray
  * console.log is a parse error at the other end. Diagnostics go to stderr.
  */
-export async function runStdio(cfg) {
-    const server = createServer(cfg);
+export async function runStdio(cfg = {}) {
+    const credentials = resolveCredentials(cfg);
+    const resolved = {
+        ...cfg,
+        apiKey: credentials.apiKey,
+        baseUrl: credentials.baseUrl,
+    };
+    const server = createServer(resolved);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // The end of the client, and therefore the end of this process.
@@ -38,6 +44,6 @@ export async function runStdio(cfg) {
     const shutdown = () => void server.close().catch(() => { });
     process.stdin.once('end', shutdown);
     process.stdin.once('close', shutdown);
-    console.error(`mandala-computer-mcp on stdio → ${new URL(cfg.baseUrl ?? DEFAULT_BASE_URL).origin}`);
+    console.error(`mandala-computer-mcp on stdio → ${new URL(credentials.baseUrl).origin}`);
 }
 //# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAiB;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,gEAAgE;IAChE,EAAE;IACF,+EAA+E;IAC/E,4EAA4E;IAC5E,6EAA6E;IAC7E,uEAAuE;IACvE,oEAAoE;IACpE,+EAA+E;IAC/E,iCAAiC;IACjC,EAAE;IACF,yEAAyE;IACzE,+EAA+E;IAC/E,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,+DAA+D;IAC/D,EAAE;IACF,8EAA8E;IAC9E,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,qBAAqB;IACrB,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC3D,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO,CAAC,KAAK,CACX,mCAAmC,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,CACrF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAC;AAI9D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAmB,EAAE;IAClD,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAiB;QAC7B,GAAG,GAAG;QACN,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,OAAO,EAAE,WAAW,CAAC,OAAO;KAC7B,CAAC;IACF,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,gEAAgE;IAChE,EAAE;IACF,+EAA+E;IAC/E,4EAA4E;IAC5E,6EAA6E;IAC7E,uEAAuE;IACvE,oEAAoE;IACpE,+EAA+E;IAC/E,iCAAiC;IACjC,EAAE;IACF,yEAAyE;IACzE,+EAA+E;IAC/E,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,+DAA+D;IAC/D,EAAE;IACF,8EAA8E;IAC9E,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,qBAAqB;IACrB,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC3D,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACtC,OAAO,CAAC,KAAK,CAAC,mCAAmC,IAAI,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAC1F,CAAC"}

package/dist/tool-filters.d.ts

@@ -0,0 +1,38 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+/** Tags describe capabilities, not whether calling a tool is safe. */
+export declare const TOOL_TAGS: {
+    readonly account: readonly ["get_account"];
+    readonly agent: readonly ["run_agent", "run_agent_chat"];
+    readonly activities: readonly ["list_activities", "get_activity", "get_activity_results"];
+    readonly signals: readonly ["read_signals"];
+    readonly artifacts: readonly ["publish_artifact", "get_artifact", "read_artifact", "delete_artifact"];
+    readonly computers: readonly ["list_computers", "get_computer", "use_computer", "wait_for_computer", "get_desktop_url", "list_sizes"];
+    readonly events: readonly ["wait_for_event", "poll_events", "wait_for_file_change"];
+    readonly executions: readonly ["get_execution", "read_execution_output"];
+    readonly files: readonly ["list_directory", "read_file", "write_file", "wait_for_file_change"];
+    readonly guest: readonly ["exec", "exec_poll", "exec_kill", "open_url", "list_windows", "window_action", "read_clipboard", "write_clipboard"];
+    readonly input: readonly ["screenshot", "click", "type_text", "press_key", "scroll", "drag", "move_mouse", "mouse_button", "cursor_position", "wait"];
+    readonly lifecycle: readonly ["create_computer", "start_computer", "stop_computer", "suspend_computer", "restart_computer", "update_computer", "clone_computer", "delete_computer", "move_computer", "list_moves"];
+    readonly results: readonly ["get_activity_results", "retain_execution_output", "get_result", "read_result_output", "delete_result"];
+    readonly snapshots: readonly ["list_snapshots", "snapshot_holdings", "create_snapshot", "restore_snapshot", "clone_snapshot", "snapshot_schedule", "get_retention", "delete_snapshot"];
+    readonly templates: readonly ["list_templates", "get_template_schema", "check_template", "publish_template", "get_template", "retire_template", "build_template", "list_builds", "get_build", "watch_build"];
+    readonly secrets: readonly ["get_computer_secrets", "set_computer_secrets"];
+    readonly ssh: readonly ["list_ssh_keys", "add_ssh_key", "remove_ssh_key", "get_computer_ssh", "set_computer_ssh"];
+    readonly usage: readonly ["get_usage"];
+    readonly webhooks: readonly ["list_webhooks", "create_webhook", "get_webhook", "update_webhook", "rotate_webhook_secret", "test_webhook", "list_webhook_deliveries", "delete_webhook"];
+};
+export type ToolTag = keyof typeof TOOL_TAGS;
+export type ToolFilters = {
+    /** Keep only tools whose existing readOnlyHint is exactly true. */
+    readOnly?: boolean;
+    /** Union of these tags; absent or empty means all tags. Names are lowercase. */
+    tags?: readonly string[];
+};
+export declare const VALID_TAGS: ToolTag[];
+export declare function parseToolTags(raw: string | undefined): ToolTag[];
+/** Validate before constructing the session; never infer read-only from a name or verb. */
+export declare function toolFilter(cfg: ToolFilters): {
+    filtered: boolean;
+    allows: (name: string, annotations?: ToolAnnotations) => boolean;
+};
+//# sourceMappingURL=tool-filters.d.ts.map

package/dist/tool-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-filters.d.ts","sourceRoot":"","sources":["../src/tool-filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,sEAAsE;AACtE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;CA6FZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,SAAS,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG;IACxB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAoC,OAAO,EAAE,CAAC;AAcrE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,EAAE,CAEhE;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG;IAC5C,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC;CAClE,CAmBA"}

package/dist/tool-filters.js

@@ -0,0 +1,129 @@
+/** Tags describe capabilities, not whether calling a tool is safe. */
+export const TOOL_TAGS = {
+    account: ['get_account'],
+    agent: ['run_agent', 'run_agent_chat'],
+    activities: ['list_activities', 'get_activity', 'get_activity_results'],
+    signals: ['read_signals'],
+    artifacts: ['publish_artifact', 'get_artifact', 'read_artifact', 'delete_artifact'],
+    computers: [
+        'list_computers',
+        'get_computer',
+        'use_computer',
+        'wait_for_computer',
+        'get_desktop_url',
+        'list_sizes',
+    ],
+    events: ['wait_for_event', 'poll_events', 'wait_for_file_change'],
+    executions: ['get_execution', 'read_execution_output'],
+    files: ['list_directory', 'read_file', 'write_file', 'wait_for_file_change'],
+    guest: [
+        'exec',
+        'exec_poll',
+        'exec_kill',
+        'open_url',
+        'list_windows',
+        'window_action',
+        'read_clipboard',
+        'write_clipboard',
+    ],
+    input: [
+        'screenshot',
+        'click',
+        'type_text',
+        'press_key',
+        'scroll',
+        'drag',
+        'move_mouse',
+        'mouse_button',
+        'cursor_position',
+        'wait',
+    ],
+    lifecycle: [
+        'create_computer',
+        'start_computer',
+        'stop_computer',
+        'suspend_computer',
+        'restart_computer',
+        'update_computer',
+        'clone_computer',
+        'delete_computer',
+        'move_computer',
+        'list_moves',
+    ],
+    results: [
+        'get_activity_results',
+        'retain_execution_output',
+        'get_result',
+        'read_result_output',
+        'delete_result',
+    ],
+    snapshots: [
+        'list_snapshots',
+        'snapshot_holdings',
+        'create_snapshot',
+        'restore_snapshot',
+        'clone_snapshot',
+        'snapshot_schedule',
+        'get_retention',
+        'delete_snapshot',
+    ],
+    templates: [
+        'list_templates',
+        'get_template_schema',
+        'check_template',
+        'publish_template',
+        'get_template',
+        'retire_template',
+        'build_template',
+        'list_builds',
+        'get_build',
+        'watch_build',
+    ],
+    secrets: ['get_computer_secrets', 'set_computer_secrets'],
+    ssh: ['list_ssh_keys', 'add_ssh_key', 'remove_ssh_key', 'get_computer_ssh', 'set_computer_ssh'],
+    usage: ['get_usage'],
+    webhooks: [
+        'list_webhooks',
+        'create_webhook',
+        'get_webhook',
+        'update_webhook',
+        'rotate_webhook_secret',
+        'test_webhook',
+        'list_webhook_deliveries',
+        'delete_webhook',
+    ],
+};
+export const VALID_TAGS = Object.keys(TOOL_TAGS).sort();
+function validateTags(tags) {
+    const names = [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
+    for (const name of names) {
+        if (!Object.hasOwn(TOOL_TAGS, name)) {
+            throw new Error(`Unknown MANDALA_TAGS tag "${name}". Valid tags (lowercase only): ${VALID_TAGS.join(', ')}`);
+        }
+    }
+    return names;
+}
+export function parseToolTags(raw) {
+    return validateTags(raw?.split(',') ?? []);
+}
+/** Validate before constructing the session; never infer read-only from a name or verb. */
+export function toolFilter(cfg) {
+    if (cfg.readOnly !== undefined && typeof cfg.readOnly !== 'boolean') {
+        throw new Error('readOnly must be a boolean');
+    }
+    const tags = validateTags(cfg.tags ?? []);
+    const selected = new Set(tags.flatMap((tag) => [...TOOL_TAGS[tag]]));
+    const known = new Set(Object.values(TOOL_TAGS).flat());
+    const readOnly = cfg.readOnly === true;
+    return {
+        filtered: readOnly || tags.length > 0,
+        allows: (name, annotations) => {
+            // Even unfiltered startup must fail when a new tool lacks a tag, instead
+            // of silently hiding it only for clients who use filters.
+            if (!known.has(name))
+                throw new Error(`Tool "${name}" has no tag in TOOL_TAGS`);
+            return ((!tags.length || selected.has(name)) && (!readOnly || annotations?.readOnlyHint === true));
+        },
+    };
+}
+//# sourceMappingURL=tool-filters.js.map

package/dist/tool-filters.js.map

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

package/dist/tools/account.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/tools/account.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4E5C,eAAO,MAAM,eAAe,EAAE,SAoD7B,CAAC"}

package/dist/tools/account.js

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { APIError } from '../errors.js';
+import { said } from '../format.js';
+import * as P from '../paths.js';
+import { count, label, metadata, metadataCall } from './directory.js';
+import { readAnnotations } from './results.js';
+// Every object projects only its public fields; a malformed report never becomes zero usage.
+const report = z
+    .object({
+    scope: z.literal('account'),
+    advisory: z.literal(true),
+    observed_at: z.string().datetime(),
+    plan: z.object({ id: label, label }),
+    limits: z.object({
+        max_computers: count,
+        vcpu_pool: count,
+        ram_pool_mb: count,
+        disk_pool_gb: count,
+        snapshot_storage_bytes: count,
+    }),
+    per_computer: z.object({ max_vcpu: count, max_ram_mb: count, max_disk_gb: count }),
+    capabilities: z.object({ windows: z.boolean() }),
+    complete: z.object({ computers: z.boolean(), snapshots: z.boolean() }),
+    usage: z.object({
+        kept_computers: count.nullable(),
+        configured_vcpu: count.nullable(),
+        configured_disk_gb: count.nullable(),
+        running_or_reserved_computers: count.nullable(),
+        running_or_reserved_vcpu: count.nullable(),
+        running_or_reserved_ram_mb: count.nullable(),
+        snapshot_storage_bytes: count.nullable(),
+    }),
+    remaining: z.object({
+        kept_computers: count.nullable(),
+        configured_vcpu: count.nullable(),
+        configured_disk_gb: count.nullable(),
+        running_or_reserved_ram_mb: count.nullable(),
+        snapshot_storage_bytes: count.nullable(),
+    }),
+})
+    .refine((data) => {
+    for (const group of [data.usage, data.remaining]) {
+        for (const [field, value] of Object.entries(group)) {
+            const complete = field === 'snapshot_storage_bytes' ? data.complete.snapshots : data.complete.computers;
+            if (complete !== (value !== null))
+                return false;
+        }
+    }
+    if (data.complete.computers) {
+        // Nullability was checked above. These are relationships within one observation,
+        // independent of plan ceilings: a consistent account can still be over quota.
+        const kept = data.usage.kept_computers;
+        const cpu = data.usage.configured_vcpu;
+        const disk = data.usage.configured_disk_gb;
+        const active = data.usage.running_or_reserved_computers;
+        const activeCPU = data.usage.running_or_reserved_vcpu;
+        const activeRAM = data.usage.running_or_reserved_ram_mb;
+        if (active > kept || activeCPU > cpu)
+            return false;
+        // Equal counts mean both CPU sums cover every kept computer.
+        if (active === kept && activeCPU !== cpu)
+            return false;
+        if (kept === 0 && (cpu !== 0 || disk !== 0))
+            return false;
+        if (active === 0 && (activeCPU !== 0 || activeRAM !== 0))
+            return false;
+        // Each active computer contributes positive integer MB, but its CPU may be zero.
+        if (activeRAM < active)
+            return false;
+    }
+    const ceilings = {
+        kept_computers: data.limits.max_computers,
+        configured_vcpu: data.limits.vcpu_pool,
+        configured_disk_gb: data.limits.disk_pool_gb,
+        running_or_reserved_ram_mb: data.limits.ram_pool_mb,
+        snapshot_storage_bytes: data.limits.snapshot_storage_bytes,
+    };
+    for (const field of Object.keys(ceilings)) {
+        const used = data.usage[field];
+        if (used !== null && data.remaining[field] !== Math.max(0, ceilings[field] - used))
+            return false;
+    }
+    return true;
+});
+export const registerAccount = (server, session) => {
+    server.registerTool('get_account', {
+        title: 'Read current account quota',
+        description: 'Read account-wide plan ceilings, per-computer maxima, current consumption and advisory remaining quota. Viewer or stronger; workspace-scoped keys receive aggregates without resource identities. No arguments, selected computer or model key. Incomplete computer/snapshot groups have null consumption and remaining values, meaning unknown. Snapshot headroom covers indexed stored bytes, excludes in-flight capture reservations and cannot promise that a capture will fit. This observation reserves nothing; later mutations still enforce quota.',
+        inputSchema: z.object({}).strict(),
+        annotations: readAnnotations,
+    }, (_args, extra) => metadataCall(async () => {
+        let raw;
+        try {
+            raw = await session.api.json('GET', P.ACCOUNT, { signal: extra.signal });
+        }
+        catch (error) {
+            if (error instanceof APIError) {
+                const refusal = z.object({ error: label.optional() }).safeParse(error.body);
+                throw new APIError(refusal.success && refusal.data.error
+                    ? refusal.data.error
+                    : 'Account quota request failed', error.status, error.body, error.retryAfterMs, error);
+            }
+            // JSON decoding failures can carry raw response text. Never print that text here.
+            throw new Error(extra.signal.aborted
+                ? 'Account quota read cancelled; no report was established.'
+                : 'Account quota could not be read; consumption and remaining quota are unknown.');
+        }
+        const data = metadata(report, raw);
+        const unknown = [
+            ...(!data.complete.computers ? ['computer'] : []),
+            ...(!data.complete.snapshots ? ['snapshot'] : []),
+        ];
+        return said((unknown.length
+            ? `UNKNOWN ${unknown.join(' and ')} consumption and remaining quota: null is not zero. `
+            : '') +
+            'ADVISORY account observation; this reserves nothing and does not guarantee a later request will fit. ' +
+            'Snapshot headroom is against indexed stored bytes only; in-flight capture reservations are not included. ' +
+            'Configured CPU/disk cover kept computers; running or reserved RAM includes current reservations. ' +
+            'Units are CPU, MB, GB and snapshot bytes as named. Use get_usage for historical metered consumption.', data);
+    }));
+};
+//# sourceMappingURL=account.js.map

package/dist/tools/account.js.map

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

package/dist/tools/activities.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"activities.d.ts","sourceRoot":"","sources":["../../src/tools/activities.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAmG5C,eAAO,MAAM,kBAAkB,EAAE,SA+EhC,CAAC"}

package/dist/tools/activities.js

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import { said } from '../format.js';
+import * as P from '../paths.js';
+import { count, executionId, exitCode, label, metadata, metadataCall } from './directory.js';
+import { computerSchema, readAnnotations } from './results.js';
+const activityId = z.string().regex(/^act_[a-f0-9]{32}$/);
+const identity = { computer_id: computerSchema, activity_id: activityId };
+const record = z.object({
+    activity_id: activityId,
+    account_id: label,
+    computer_id: label,
+    workspace_id: label.nullable(),
+    channel: label,
+    route: label,
+    action: label,
+    state: z.enum(['pending', 'acknowledged', 'exited', 'accepted', 'refused', 'unknown']),
+    received_at: label,
+    observed_at: label,
+    revision: count.min(1).optional(),
+    has_results: z.boolean().optional(),
+    dispatched_at: label.optional(),
+    elapsed_ms: count.optional(),
+    reason: label.optional(),
+    http_status: z.number().int().min(100).max(599).optional(),
+    exit_code: exitCode.optional(),
+    execution_id: executionId.optional(),
+});
+const health = z.object({
+    recording_started_at: label,
+    earliest_retained_at: label.nullable(),
+    count_truncated: z.boolean(),
+    age_truncated: z.boolean(),
+    capture: z.enum(['available', 'degraded']),
+    completeness: z.literal('best-effort'),
+    gap_at: label.nullable(),
+    recovered_at: label.nullable(),
+});
+const page = z.object({
+    items: z.array(record),
+    next_cursor: label.nullable(),
+    changes_cursor: label,
+    gap: z.boolean(),
+    health,
+});
+const observation = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('running') }),
+    z.object({ status: z.literal('exited'), exit_code: exitCode }),
+]);
+const stream = (sync) => z.object({
+    bytes: count.max(4 * 1024 * 1024),
+    retained_truncated: z.boolean(),
+    upstream_truncated: sync ? z.boolean() : z.null(),
+});
+const link = (kind, association, fields) => {
+    const base = {
+        id: z.string().regex(kind === 'artifact' ? /^art_[a-f0-9]{32}$/ : /^res_[a-f0-9]{32}$/),
+        kind: z.literal(kind),
+        association: z.literal(association),
+    };
+    return z.discriminatedUnion('availability', [
+        z.object({ ...base, availability: z.literal('unavailable') }),
+        z.object({
+            ...base,
+            availability: z.literal('available'),
+            captured_at: label,
+            expires_at: label,
+            ...fields,
+        }),
+    ]);
+};
+const resultLinks = z.object({
+    activity_id: activityId,
+    revision: count.min(1),
+    more: z.boolean(),
+    items: z
+        .array(z.union([
+        link('artifact', 'caller_selected_artifact', { bytes: count }),
+        link('background-output', 'background_execution_output', {
+            stdout: stream(false),
+            stderr: stream(false),
+            diagnostic: z.object({ bytes: count.max(65536), truncated: z.boolean() }),
+            observation,
+        }),
+        link('synchronous-output', 'synchronous_exec_response', {
+            stdout: stream(true),
+            stderr: stream(true),
+            diagnostic: z.null(),
+            observation: z.object({ status: z.literal('exited'), exit_code: exitCode }),
+        }),
+    ]))
+        .max(8),
+});
+const historyNote = 'Selected, retained, best-effort request history; not all guest work or an agent identity. Accepted background work is not completed execution; a dispatched error may have had effects. Activity IDs identify requests, never idempotency keys.';
+export const registerActivities = (server, session) => {
+    server.registerTool('list_activities', {
+        title: 'Read one activity history page',
+        description: `${historyNote} History is newest first with a fixed watermark. Changes include late final updates to older rows. No automatic paging. A gap requires refreshing history.`,
+        inputSchema: {
+            computer_id: computerSchema,
+            cursor: z.string().min(1).max(2048).optional(),
+            changes: z.boolean().optional(),
+        },
+        annotations: readAnnotations,
+    }, ({ computer_id, cursor, changes }, extra) => metadataCall(async () => {
+        if (changes && !cursor)
+            throw new Error('changes=true requires a cursor.');
+        const id = session.resolve(computer_id);
+        const data = metadata(page, await session.api.json('GET', P.activities(id), {
+            query: { cursor, ...(changes ? { changes: 1 } : {}) },
+            signal: extra.signal,
+        }));
+        if (data.items.some((item) => item.computer_id !== id))
+            throw new Error('Activity history did not match the requested computer.');
+        return said(`${data.gap ? 'GAP: discard the change cursor and refresh history. ' : ''}${historyNote}`, data);
+    }));
+    server.registerTool('get_activity', {
+        title: 'Read one activity record',
+        description: historyNote,
+        inputSchema: identity,
+        annotations: readAnnotations,
+    }, ({ computer_id, activity_id }, extra) => metadataCall(async () => {
+        const id = session.resolve(computer_id);
+        const data = metadata(record, await session.api.json('GET', P.activity(id, activity_id), { signal: extra.signal }));
+        if (data.activity_id !== activity_id || data.computer_id !== id)
+            throw new Error('Activity response did not match the requested identity.');
+        return said(historyNote, data);
+    }));
+    server.registerTool('get_activity_results', {
+        title: 'Read passive result links for an activity',
+        description: 'Metadata only: at most eight newest links. more has no cursor and does not mean all versions were returned. No content reads, guest files, captures, execution polling or downloads. An unavailable link is not empty content. Caller-selected artifact association does not prove creation or command success.',
+        inputSchema: identity,
+        annotations: readAnnotations,
+    }, ({ computer_id, activity_id }, extra) => metadataCall(async () => {
+        const data = metadata(resultLinks, await session.api.json('GET', P.activityResults(session.resolve(computer_id), activity_id), { signal: extra.signal }));
+        if (data.activity_id !== activity_id)
+            throw new Error('Result links did not match the requested activity.');
+        return said(`${data.more ? 'More versions exist; this endpoint has no continuation cursor. ' : ''}Result links are metadata only. Availability and association do not establish command success.`, data);
+    }));
+};
+//# sourceMappingURL=activities.js.map

package/dist/tools/activities.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,SAiK3B,CAAC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,SAmL3B,CAAC"}

package/dist/tools/agent.js

@@ -1,7 +1,9 @@
 import { z } from 'zod';
 import { MODEL_KEY_HEADER } from '../api.js';
-import { guarded, refused, said } from '../format.js';
+import { APIError, authenticationAdvice, platformSaid } from '../errors.js';
+import { errorMetadata, guarded, refused, said, withErrorMetadata } from '../format.js';
 import * as P from '../paths.js';
+import { safeResult } from './chat.js';
 /**
  * The platform's own agent loop, as one tool.
  *
@@ -130,8 +132,19 @@ export const registerAgent = (server, session) => {
                 // handed "the run failed" and a JSON blob does the natural thing,
                 // which is to call this tool again with the same prompt — paying for
                 // every completed step a second time to be refused the same way.
-                return refused(`The run failed after ${steps.length} step(s).${stopReason(ev.data)}` +
-                    (steps.length ? `\n\nWhat it did, and is billed for:\n${steps.join('\n')}` : ''), ev.data);
+                const frame = isRecord(ev.data) ? ev.data : {};
+                const diagnostic = new APIError('', typeof frame.status === 'number' ? frame.status : 0, frame);
+                return withErrorMetadata(refused(`The run failed after ${steps.length} step(s).${stopReason(ev.data)}` +
+                    (steps.length ? `\n\nWhat it did, and is billed for:\n${steps.join('\n')}` : ''), {
+                    error: platformSaid(frame),
+                    status: errorMetadata({ status: frame.status }).fields.status,
+                    steps: frame.steps,
+                    usage: frame.usage,
+                }), {
+                    status: frame.status,
+                    reason: diagnostic.reason,
+                    request_id: diagnostic.requestId,
+                });
             }
         }
         if (!done) {
@@ -162,7 +175,7 @@ export const registerAgent = (server, session) => {
                 : JSON.stringify(done.text);
         const result = `${verdict}\n\n${text}\n\nWhat it did:\n${steps.join('\n')}`;
         return stop === 'end_turn' ? said(result, done) : refused(result, done);
-    }));
+    }).then((result) => safeResult(result, session.modelKey)));
 };
 /**
  * What an `error` frame says about whether calling this tool again can work.
@@ -185,17 +198,16 @@ export const registerAgent = (server, session) => {
 function stopReason(data) {
     const frame = isRecord(data) ? data : undefined;
     const status = typeof frame?.status === 'number' ? frame.status : undefined;
-    const said = typeof frame?.error === 'string' && frame.error ? frame.error : undefined;
+    const said = platformSaid(frame);
     const why = said ? ` ${said}` : '';
     // 401 and 403 are split, because the recovery is not the same one. A shared
     // clause told a caller whose ROLE had been taken away to re-authenticate,
     // which restores nothing and sends it round the same refusal with another
     // prompt's worth of billed steps behind it (Codex review).
     if (status === 401) {
-        return (` It was stopped because this server's credential is no longer accepted (HTTP ${status}) —` +
-            ` not by anything wrong with the computer.${why} Do NOT call run_agent again with the same` +
-            ` prompt: it is refused the same way until the credential is fixed. Once it is, read what` +
-            ` the steps below already did before deciding what is left to do.`);
+        const reason = new APIError('', status, frame).reason;
+        return (` HTTP ${status}: ${authenticationAdvice(reason)}.${why} Do NOT call run_agent again with the same` +
+            ` prompt. Read what the steps below already did before deciding what is left to do.`);
     }
     if (status === 403) {
         return (` It was stopped because this account does not permit the run (HTTP ${status}) — a role that` +