@minionry/minion 0.7.36

package/dist/server/services/sdk/app-tools.js

@@ -0,0 +1,303 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomUUID } from 'node:crypto';
+import { logAppAudit } from './audit.js';
+import { getLiveSubscriptionsForApp, listLiveSubscriptions, registerLiveSubscription } from './live-registry.js';
+import { SdkMethodError } from './registry.js';
+export const APP_TOOL_CALL_TIMEOUT_MS = 30_000;
+export const APP_TOOL_CALL_TIMEOUT_MAX_MS = 120_000;
+export const APP_TOOL_MAX_PENDING_CALLS = 8;
+export const APP_TOOL_MAX_RESULT_BYTES = 1024 * 1024;
+const registrations = new Map();
+const senders = new Map();
+const pending = new Map();
+export class AppToolCallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AppToolCallError';
+        this.code = code;
+    }
+}
+function paramsObject(params, method) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires an object params payload`);
+    }
+    return params;
+}
+function requireString(raw, field, method) {
+    const value = raw[field];
+    if (typeof value !== 'string' || value === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires a non-empty string ${field}`);
+    }
+    return value;
+}
+function parseToolSpec(raw, seen, method) {
+    const entry = paramsObject(raw, method);
+    const name = requireString(entry, 'name', `${method} tools[].name:`);
+    if (name.includes('__')) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: invalid tool name '${name}' — must contain no '__' (the agent sees '<appId>__<tool>')`);
+    }
+    if (seen.has(name)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: duplicate tool name '${name}'`);
+    }
+    const description = requireString(entry, 'description', `${method} tools[].description:`);
+    const inputSchema = entry.inputSchema;
+    if (typeof inputSchema !== 'object' || inputSchema === null || Array.isArray(inputSchema)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: '${name}' needs an inputSchema object`);
+    }
+    const timeoutMs = entry.timeoutMs;
+    if (timeoutMs !== undefined && (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs <= 0)) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: '${name}' timeoutMs must be a positive integer`);
+    }
+    return {
+        name,
+        description,
+        inputSchema: inputSchema,
+        ...(timeoutMs !== undefined ? { timeoutMs: timeoutMs } : {}),
+    };
+}
+function buildToolTable(rawTools, appId, spaceKey) {
+    const served = new Map();
+    for (const live of registrations.values()) {
+        if (live.appId !== appId || live.spaceKey !== spaceKey)
+            continue;
+        for (const name of live.tools.keys())
+            served.set(name, live.requestId);
+    }
+    const tools = new Map();
+    for (const entry of rawTools) {
+        const spec = parseToolSpec(entry, tools, 'tools.register');
+        const owner = served.get(spec.name);
+        if (owner !== undefined) {
+            throw new SdkMethodError('BAD_REQUEST', `tools.register: '${spec.name}' is already served by registration '${owner}'`);
+        }
+        tools.set(spec.name, spec);
+    }
+    return tools;
+}
+export function toolsRegisterHandler(args) {
+    const raw = paramsObject(args.params, 'tools.register');
+    const rawTools = raw.tools;
+    if (!Array.isArray(rawTools) || rawTools.length === 0) {
+        throw new SdkMethodError('BAD_REQUEST', 'tools.register: tools must be a non-empty array');
+    }
+    const rawProfile = raw.profile;
+    if (rawProfile !== undefined && rawProfile !== 'browser') {
+        throw new SdkMethodError('BAD_REQUEST', `tools.register: unknown profile '${String(rawProfile)}' (fail closed)`);
+    }
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    if (!args.notify) {
+        throw new SdkMethodError('UNSUPPORTED', 'tools.register needs a host session to deliver calls over — this transport has none');
+    }
+    const tools = buildToolTable(rawTools, args.appId, args.spaceKey);
+    const registration = {
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        viewerId: args.viewerId,
+        ...(rawProfile !== undefined ? { profile: rawProfile } : {}),
+        tools,
+    };
+    const sub = {
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'tools.register',
+        viewerId: args.viewerId,
+        teardown: () => retireAppToolRegistration(args.requestId, 'registration torn down'),
+    };
+    registrations.set(args.requestId, registration);
+    senders.set(args.requestId, args.notify);
+    registerLiveSubscription(sub);
+    return { registered: true };
+}
+export function toolsResultHandler(args) {
+    const raw = paramsObject(args.params, 'tools.result');
+    const callId = requireString(raw, 'callId', 'tools.result');
+    let failure;
+    if (raw.ok === false) {
+        const error = paramsObject(raw.error, 'tools.result error:');
+        const code = requireString(error, 'code', 'tools.result error:');
+        const message = requireString(error, 'message', 'tools.result error:');
+        failure = new AppToolCallError(code === 'APP_UNAVAILABLE' || code === 'APP_TIMEOUT' ? code : 'APP_ERROR', message);
+    }
+    else if (raw.ok !== true) {
+        throw new SdkMethodError('BAD_REQUEST', "tools.result: 'ok' must be a boolean");
+    }
+    const call = pending.get(callId);
+    if (!call)
+        return null;
+    if (call.appId !== args.appId || call.spaceKey !== args.spaceKey) {
+        console.warn(`[SdkAppTools] dropped tools.result for '${callId}' from '${args.appId}' — the call belongs to another app`);
+        logAppAudit({
+            appId: args.appId,
+            origin: args.origin,
+            method: 'tools.result.rejected',
+            decision: 'scope_denied',
+            requestId: args.requestId,
+            spaceKey: args.spaceKey,
+            reason: `answer for call '${callId}' does not belong to this app in this Space`,
+        });
+        return null;
+    }
+    if (failure) {
+        settlePending(call, `app reported ${failure.code}`, () => call.fail(failure));
+        return null;
+    }
+    const result = raw.result;
+    const oversize = serializedBytes(result);
+    if (oversize > APP_TOOL_MAX_RESULT_BYTES) {
+        settlePending(call, 'result over cap', () => call.fail(new AppToolCallError('APP_ERROR', `'${call.tool}' returned ${oversize} bytes, over the ${APP_TOOL_MAX_RESULT_BYTES}-byte result cap`)));
+        return null;
+    }
+    settlePending(call, 'ok', () => call.settle(result));
+    return null;
+}
+function serializedBytes(value) {
+    if (value === undefined)
+        return 0;
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+function settlePending(call, outcomeLabel, outcome) {
+    if (!pending.delete(call.callId))
+        return;
+    clearTimeout(call.timer);
+    const registration = registrations.get(call.registrationId);
+    logAppAudit({
+        appId: call.appId,
+        origin: registration?.origin ?? '',
+        method: 'tools.call',
+        decision: 'allow',
+        requestId: call.registrationId,
+        spaceKey: call.spaceKey,
+        reason: `host call '${call.callId}' to '${call.tool}' settled: ${outcomeLabel}`,
+    });
+    outcome();
+}
+function sendToolCall(registration, data) {
+    const notify = senders.get(registration.requestId);
+    if (!notify)
+        return;
+    try {
+        notify({ type: 'sdkToolCall', data, targetViewerId: registration.viewerId });
+    }
+    catch (error) {
+        console.error(`[SdkAppTools] failed to deliver ${data.op} '${data.callId}' to app '${registration.appId}':`, error);
+    }
+}
+function findServingRegistration(appId, spaceKey, tool) {
+    for (const registration of registrations.values()) {
+        if (registration.appId === appId && registration.spaceKey === spaceKey && registration.tools.has(tool)) {
+            return registration;
+        }
+    }
+    return undefined;
+}
+function pendingForApp(appId, spaceKey) {
+    let count = 0;
+    for (const call of pending.values()) {
+        if (call.appId === appId && call.spaceKey === spaceKey)
+            count += 1;
+    }
+    return count;
+}
+export function callAppTool(args) {
+    const registration = findServingRegistration(args.appId, args.spaceKey, args.tool);
+    if (!registration) {
+        return Promise.reject(new AppToolCallError('APP_UNAVAILABLE', `no connected app serves '${args.tool}' for '${args.appId}' in this Space`));
+    }
+    if (pendingForApp(args.appId, args.spaceKey) >= APP_TOOL_MAX_PENDING_CALLS) {
+        return Promise.reject(new AppToolCallError('RATE_LIMITED', `'${args.appId}' already has ${APP_TOOL_MAX_PENDING_CALLS} tool calls in flight — wait for one to finish`));
+    }
+    const spec = registration.tools.get(args.tool);
+    const timeoutMs = Math.min(args.timeoutMs ?? spec.timeoutMs ?? APP_TOOL_CALL_TIMEOUT_MS, APP_TOOL_CALL_TIMEOUT_MAX_MS);
+    const callId = `tc-${randomUUID()}`;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            const call = pending.get(callId);
+            if (!call)
+                return;
+            settlePending(call, 'deadline elapsed', () => reject(new AppToolCallError('APP_TIMEOUT', `'${args.tool}' did not answer within ${timeoutMs}ms`)));
+            sendToolCall(registration, { op: 'cancel', callId, requestId: registration.requestId });
+        }, timeoutMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        pending.set(callId, {
+            callId,
+            registrationId: registration.requestId,
+            appId: args.appId,
+            spaceKey: args.spaceKey,
+            tool: args.tool,
+            timer,
+            settle: resolve,
+            fail: reject,
+        });
+        sendToolCall(registration, {
+            op: 'call',
+            callId,
+            requestId: registration.requestId,
+            tool: args.tool,
+            ...(args.input !== undefined ? { input: args.input } : {}),
+        });
+    });
+}
+export function cancelAppToolCall(callId, cause = 'cancelled by the host') {
+    const call = pending.get(callId);
+    if (!call)
+        return false;
+    settlePending(call, `cancelled: ${cause}`, () => call.fail(new AppToolCallError('APP_UNAVAILABLE', `call '${callId}' to '${call.tool}' was cancelled: ${cause}`)));
+    const registration = registrations.get(call.registrationId);
+    if (registration)
+        sendToolCall(registration, { op: 'cancel', callId, requestId: registration.requestId });
+    return true;
+}
+export function retireAppToolRegistration(requestId, cause) {
+    const registration = registrations.get(requestId);
+    if (!registration)
+        return false;
+    registrations.delete(requestId);
+    senders.delete(requestId);
+    for (const call of [...pending.values()]) {
+        if (call.registrationId !== requestId)
+            continue;
+        settlePending(call, `registration retired: ${cause}`, () => call.fail(new AppToolCallError('APP_UNAVAILABLE', `'${call.tool}' is no longer served by '${call.appId}': ${cause}`)));
+    }
+    return true;
+}
+export function listAppToolRegistrations() {
+    return [...registrations.values()];
+}
+export function listAppToolRegistrationsForApp(appId, spaceKey) {
+    return [...registrations.values()].filter((r) => r.appId === appId && r.spaceKey === spaceKey);
+}
+export function listAppToolsForApp(appId, spaceKey) {
+    return listAppToolRegistrationsForApp(appId, spaceKey).flatMap((r) => [...r.tools.values()]);
+}
+export function pendingAppToolCallCount() {
+    return pending.size;
+}
+export function retireAppToolsForApp(appId, spaceKey, cause) {
+    let retired = 0;
+    for (const sub of getLiveSubscriptionsForApp(appId, spaceKey)) {
+        if (sub.kind === 'tools.register' && retireAppToolRegistration(sub.requestId, cause))
+            retired += 1;
+    }
+    return retired;
+}
+export function resetAppTools() {
+    for (const call of pending.values())
+        clearTimeout(call.timer);
+    pending.clear();
+    registrations.clear();
+    senders.clear();
+}

package/dist/server/services/sdk/audit.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { machinePath } from '../../../bin/machine-layout.js';
+function logsDir() {
+    return machinePath('logs');
+}
+function auditFilePath() {
+    return join(logsDir(), 'app-audit.jsonl');
+}
+export function logAppAudit(entry) {
+    const record = { ...entry, timestamp: entry.timestamp ?? new Date().toISOString() };
+    try {
+        const dir = logsDir();
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        appendFileSync(auditFilePath(), `${JSON.stringify(record)}\n`, { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch (error) {
+        console.error('[AppAudit] Failed to write app-audit.jsonl:', error);
+    }
+}
+export function readAppAudit(opts) {
+    const path = auditFilePath();
+    if (!existsSync(path))
+        return [];
+    let content;
+    try {
+        content = readFileSync(path, 'utf-8');
+    }
+    catch (error) {
+        console.error('[AppAudit] Failed to read app-audit.jsonl:', error);
+        return [];
+    }
+    const lines = content.split('\n').filter((line) => line.trim().length > 0);
+    const selected = opts?.limit && opts.limit > 0 ? lines.slice(-opts.limit) : lines;
+    const entries = [];
+    for (const line of selected) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+        }
+    }
+    return entries;
+}

package/dist/server/services/sdk/browser-transport.js

@@ -0,0 +1,188 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { createHash } from 'node:crypto';
+import { deriveAppId } from '@minionry/app-manifest';
+import { getLocalAppBinding, isLoopbackHostname } from './local-app-bindings.js';
+import { runSdkPipeline } from './pipeline.js';
+import { SDK_METHOD_REGISTRY } from './registry.js';
+const SDK_REQUEST_TYPE = 'minionry:request';
+const SDK_RESPONSE_TYPE = 'minionry:response';
+const SDK_EVENT_TYPE = 'minionry:event';
+const BROWSER_TRANSPORT_ROLE = 'owner';
+export const BROWSER_TRANSPORT_VIEWER_ID = 'minionry-browser-transport';
+const sha256Hex = (input) => createHash('sha256').update(input, 'utf8').digest('hex');
+function parseBindingPayload(payload) {
+    let data;
+    try {
+        data = JSON.parse(payload);
+    }
+    catch {
+        return {
+            ok: false,
+            requestId: '',
+            error: { code: 'BAD_REQUEST', message: 'binding payload is not parseable JSON' },
+        };
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return {
+            ok: false,
+            requestId: '',
+            error: { code: 'BAD_REQUEST', message: 'binding payload is not a frame object' },
+        };
+    }
+    const raw = data;
+    const requestId = typeof raw.requestId === 'string' ? raw.requestId : '';
+    if (raw.type !== SDK_REQUEST_TYPE) {
+        return {
+            ok: false,
+            requestId,
+            error: { code: 'BAD_REQUEST', message: `binding payload is not a ${SDK_REQUEST_TYPE} frame` },
+        };
+    }
+    if (requestId === '' || typeof raw.method !== 'string' || raw.method === '') {
+        return {
+            ok: false,
+            requestId,
+            error: { code: 'BAD_REQUEST', message: 'request frame has missing or invalid requestId/method' },
+        };
+    }
+    return {
+        ok: true,
+        frame: { requestId, method: raw.method, params: raw.params },
+    };
+}
+export function attachSdkBrowserTransport(host, deps) {
+    const onSdkRequest = (event) => {
+        void handleBrowserSdkRequest(host, deps, event).catch((error) => {
+            console.error('[SdkBrowserTransport] request handling failed:', error);
+        });
+    };
+    host.on('sdkRequest', onSdkRequest);
+    return () => {
+        host.off('sdkRequest', onSdkRequest);
+    };
+}
+async function deliverFrame(host, pageId, frame) {
+    try {
+        await host.sdk.deliver({ pageId, frame: JSON.stringify(frame) });
+    }
+    catch (error) {
+        console.warn(`[SdkBrowserTransport] deliver to page ${pageId} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function originPort(url) {
+    if (url.port !== '')
+        return Number(url.port);
+    return url.protocol === 'https:' ? 443 : 80;
+}
+async function resolveCallerIdentity(url) {
+    const binding = isLoopbackHostname(url.hostname) ? getLocalAppBinding(originPort(url)) : undefined;
+    if (binding)
+        return { appId: binding.appId, binding };
+    return { appId: await deriveAppId(url.hostname, url.origin, sha256Hex), binding: undefined };
+}
+function requestedScopeStrings(params) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params))
+        return [];
+    const raw = params.scopes;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((scope) => typeof scope === 'string');
+}
+function connectManifestEnvelope(origin, binding, params) {
+    if (binding)
+        return binding.manifest;
+    return {
+        hash: `browser-unpinned-${sha256Hex(origin)}`,
+        scopes: requestedScopeStrings(params),
+        optionalScopes: [],
+    };
+}
+async function handleBrowserSdkRequest(host, deps, event) {
+    const respond = (payload) => deliverFrame(host, event.pageId, { ...payload, type: SDK_RESPONSE_TYPE });
+    const parsed = parseBindingPayload(event.payload);
+    if (!parsed.ok) {
+        if (parsed.requestId === '') {
+            console.warn(`[SdkBrowserTransport] dropped an uncorrelatable request from ${event.origin}: ${parsed.error.message}`);
+            return;
+        }
+        await respond({ requestId: parsed.requestId, ok: false, error: parsed.error });
+        return;
+    }
+    const { frame } = parsed;
+    let url;
+    try {
+        url = new URL(new URL(event.origin).origin);
+        if (url.origin === 'null')
+            throw new Error('opaque origin');
+    }
+    catch {
+        await respond({
+            requestId: frame.requestId,
+            ok: false,
+            error: { code: 'BAD_REQUEST', message: `this page's origin ('${event.origin}') cannot use the Minionry SDK` },
+        });
+        return;
+    }
+    const origin = url.origin;
+    const workingDir = deps.getWorkingDir();
+    if (!workingDir) {
+        await respond({
+            requestId: frame.requestId,
+            ok: false,
+            error: { code: 'INTERNAL', message: 'no Space is attached to this browser yet — open the Space in Minionry first' },
+        });
+        return;
+    }
+    if (frame.method === 'auth.getToken') {
+        await respond({
+            requestId: frame.requestId,
+            ok: false,
+            error: {
+                code: 'SPACE_DISCONNECTED',
+                message: 'auth.getToken is unavailable on the Minionry Browser transport (v1) — tokens are minted by an ' +
+                    'attached authenticated web host session; open the app inside the Minionry web shell instead',
+            },
+        });
+        return;
+    }
+    const { appId, binding } = await resolveCallerIdentity(url);
+    const wireType = SDK_METHOD_REGISTRY[frame.method]?.type ?? 'sdkRequest';
+    const response = await runSdkPipeline({
+        wireType,
+        appId,
+        origin,
+        requestId: frame.requestId,
+        method: frame.method,
+        params: frame.params,
+        role: BROWSER_TRANSPORT_ROLE,
+        viewerId: BROWSER_TRANSPORT_VIEWER_ID,
+        tabId: event.tabId,
+        workingDir,
+        ...(frame.method === 'connect'
+            ? { manifest: connectManifestEnvelope(origin, binding, frame.params) }
+            : {}),
+        consentRouting: { mode: 'owner-sessions', listSessions: deps.consent.listOwnerSessions },
+        ...(binding ? { verifiedLocalBinding: true } : {}),
+        emit: (evt, payload, seq) => {
+            void deliverFrame(host, event.pageId, {
+                type: SDK_EVENT_TYPE,
+                requestId: frame.requestId,
+                event: evt,
+                ...(payload !== undefined ? { payload } : {}),
+                seq,
+            });
+        },
+        notify: (sessionFrame) => {
+            if (sessionFrame.broadcast) {
+                deps.consent.broadcast({ type: sessionFrame.type, data: sessionFrame.data });
+                return;
+            }
+            const target = sessionFrame.targetViewerId;
+            if (target !== undefined && target !== BROWSER_TRANSPORT_VIEWER_ID) {
+                deps.consent.deliverToSession(target, { type: sessionFrame.type, data: sessionFrame.data });
+            }
+        },
+    });
+    await respond(response);
+}