@actcore/web-runtime 0.1.0

package/dist/webmcp.js

@@ -0,0 +1,189 @@
+/**
+ * Bridge: expose an ACT component's tools on the browser's native WebMCP
+ * surface (`document.modelContext`). Native-only, feature-gated, opt-in.
+ *
+ * WebMCP is pre-standardization; we type only the slice we depend on
+ * (`registerTool` + `AbortSignal`) so upstream churn cannot break the build.
+ * Spec: https://webmachinelearning.github.io/webmcp/
+ */
+import { decode, encode } from 'cbor2';
+import { resolveLocalizedString } from './locale.js';
+/** Native WebMCP surface if present (canonical `document`, legacy `navigator`). */
+export function getModelContext() {
+    if (typeof document !== 'undefined' && document.modelContext)
+        return document.modelContext;
+    if (typeof navigator !== 'undefined' && navigator.modelContext)
+        return navigator.modelContext;
+    return null;
+}
+/** True when the browser exposes a native WebMCP surface. */
+export function isWebmcpAvailable() {
+    return getModelContext() !== null;
+}
+/** Coerce an ACT tool name to WebMCP's `[A-Za-z0-9_.-]`, ≤128, non-empty. */
+export function sanitizeName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 128);
+    return cleaned || 'tool';
+}
+/** ACT `parameters-schema` (a JSON Schema string) → a JSON Schema object. */
+export function parseInputSchema(schemaStr) {
+    if (schemaStr && schemaStr.trim()) {
+        try {
+            const parsed = JSON.parse(schemaStr);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            /* fall through to default */
+        }
+    }
+    return { type: 'object', properties: {} };
+}
+/** Read the `std:read-only` boolean from ACT tool metadata, if present. */
+export function readReadOnlyHint(metadata) {
+    for (const [key, val] of metadata) {
+        if (key === 'std:read-only') {
+            try {
+                const decoded = decode(val);
+                if (typeof decoded === 'boolean')
+                    return decoded;
+            }
+            catch {
+                /* ignore undecodable value */
+            }
+        }
+    }
+    return undefined;
+}
+/** WebMCP annotations for an ACT tool: readOnly from meta, untrusted by default. */
+export function buildAnnotations(metadata) {
+    const readOnly = readReadOnlyHint(metadata);
+    return {
+        ...(readOnly !== undefined ? { readOnlyHint: readOnly } : {}),
+        untrustedContentHint: true,
+    };
+}
+/** wasi:http content-parts surface mimeType as an `option<string>` variant
+ *  (`{tag:'some',val}`) rather than a plain string; normalise both. */
+function normalizeMime(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (raw && typeof raw === 'object' && raw.tag === 'some') {
+        return String(raw.val);
+    }
+    return 'application/octet-stream';
+}
+function asBytes(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    return new Uint8Array(Array.isArray(data) ? data : []);
+}
+/** Collect a ToolResult's events (immediate array or streaming ReadableStream)
+ *  into a single text blob, flagging whether a terminal error occurred. */
+async function drainToText(result) {
+    const events = [];
+    if (result.tag === 'immediate') {
+        events.push(...result.val);
+    }
+    else {
+        // Typed as ReadableStream, but accept an already-drained array too — some intermediaries
+        // normalise streaming→immediate (mirrors normalizeMime's static-vs-runtime note).
+        const val = result.val;
+        if (Array.isArray(val)) {
+            events.push(...val);
+        }
+        else {
+            const reader = val.getReader();
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value)
+                        events.push(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+    }
+    const parts = [];
+    let isError = false;
+    for (const ev of events) {
+        if (ev.tag === 'content') {
+            const mime = normalizeMime(ev.val.mimeType);
+            const data = asBytes(ev.val.data);
+            if (mime.startsWith('text/') || mime === 'application/json') {
+                parts.push(new TextDecoder().decode(data));
+            }
+            else {
+                parts.push(`(${mime}, ${data.length} bytes)`);
+            }
+        }
+        else {
+            isError = true;
+            parts.push(`error: ${ev.val.kind} · ${resolveLocalizedString(ev.val.message)}`);
+        }
+    }
+    return { text: parts.join('\n'), isError };
+}
+/** Build the WebMCP `execute` handler that bridges to `ToolProvider.callTool`. */
+export function buildExecute(provider, def, options) {
+    return async (input) => {
+        try {
+            const argBytes = encode(input ?? {}, { dcbor: true });
+            // Forward std:session-id only for a non-empty session id; null,
+            // undefined, and "" (a meaningless id) are all omitted.
+            const sessionId = options.getSessionId?.();
+            const meta = sessionId
+                ? [['std:session-id', encode(sessionId, { dcbor: true })]]
+                : [];
+            const result = await provider.callTool(def.name, argBytes, meta);
+            const { text, isError } = await drainToText(result);
+            return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+        }
+        catch (err) {
+            const msg = String(err?.message ?? err);
+            return { content: [{ type: 'text', text: msg }], isError: true };
+        }
+    };
+}
+/** Map one ACT ToolDefinition to a WebMCP descriptor (execute included). */
+export function toDescriptor(provider, def, options) {
+    return {
+        name: sanitizeName(def.name),
+        description: resolveLocalizedString(def.description),
+        inputSchema: parseInputSchema(def.parametersSchema),
+        annotations: buildAnnotations(def.metadata),
+        execute: buildExecute(provider, def, options),
+    };
+}
+/**
+ * Register every tool of an ACT component on the native WebMCP surface.
+ * Opt-in and headless — the caller decides when to call it and renders any UI.
+ * No-ops (returns `available:false`) where `document.modelContext` is absent.
+ * Call `dispose()` before re-exposing a different component.
+ */
+export async function exposeToWebmcp(provider, tools, options = {}) {
+    const mc = getModelContext();
+    if (!mc)
+        return { count: 0, available: false, dispose() { } };
+    const controller = new AbortController();
+    let count = 0;
+    for (const def of tools) {
+        try {
+            const descriptor = toDescriptor(provider, def, options);
+            await mc.registerTool(descriptor, {
+                signal: controller.signal,
+                ...(options.exposedTo ? { exposedTo: options.exposedTo } : {}),
+            });
+            count++;
+        }
+        catch (err) {
+            console.warn(`[webmcp] registerTool for "${def.name}" failed:`, err);
+        }
+    }
+    return { count, available: true, dispose: () => controller.abort() };
+}
+//# sourceMappingURL=webmcp.js.map

package/dist/webmcp.js.map

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

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@actcore/web-runtime",
+  "version": "0.1.0",
+  "description": "Web runtime for ACT (Agent Component Tools) — loads and runs signed wasm agent tools in the browser, and exposes them to browser agents via WebMCP",
+  "keywords": [
+    "act",
+    "agent-component-tools",
+    "agent",
+    "wasm",
+    "webassembly",
+    "component-model",
+    "mcp",
+    "webmcp",
+    "ai",
+    "tools",
+    "browser",
+    "wasip3",
+    "jspi"
+  ],
+  "homepage": "https://actcore.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/actcore/web-runtime"
+  },
+  "bugs": "https://github.com/actcore/web-runtime/issues",
+  "license": "MIT OR Apache-2.0",
+  "author": "Alexander Shishenko <alex@shishenko.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "npm run gen-version && npm run gen-types && tsc",
+    "gen-version": "node scripts/gen-version.mjs",
+    "clean": "rm -rf dist src/generated",
+    "typecheck": "tsc --noEmit",
+    "gen-types": "jco types wit --world-name host-view --async-mode jspi --async-wasi-imports -o src/generated",
+    "sync-wit": "WKG_CONFIG_FILE=wkg-registry.toml wkg wit fetch --type wit",
+    "test": "node --test 'tests/*.test.mjs'",
+    "example": "python3 -m http.server 8765"
+  },
+  "dependencies": {
+    "@bytecodealliance/jco": "^1.25.0",
+    "@bytecodealliance/jco-transpile": "^0.4.1",
+    "@bytecodealliance/preview2-shim": "^0.19.0",
+    "cbor2": "^2.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "undici": "^8.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}