@minionry/minion 0.7.36

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

@@ -0,0 +1,247 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomBytes } from 'node:crypto';
+import { ENGINE_EFFORT_LEVELS } from '../../engines/EngineEvent.js';
+import { logAppAudit } from './audit.js';
+import { resolveAutomationTarget } from './browser.js';
+import { getGrant } from './grant-store.js';
+import { runClaudeInference } from './inference-claude.js';
+import { deregisterLiveSubscription, listLiveSubscriptions, registerLiveSubscription } from './live-registry.js';
+import { recordAppRunTokens } from './rate-limits.js';
+import { SdkMethodError } from './registry.js';
+export class SdkInferenceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SdkInferenceError';
+        this.code = code;
+    }
+}
+const DEFAULT_EXECUTORS = {
+    'claude-code': (exec) => runClaudeInference(exec),
+};
+let executors = DEFAULT_EXECUTORS;
+export function setSdkInferenceExecutors(table) {
+    executors = table;
+}
+export function resetSdkInference() {
+    executors = DEFAULT_EXECUTORS;
+    runsById.clear();
+}
+export function inferenceEngines() {
+    return Object.keys(executors).filter((engine) => executors[engine] !== undefined);
+}
+const MAX_MESSAGES = 64;
+const MAX_SYSTEM_CHARS = 32_000;
+const MAX_CONTENT_CHARS = 400_000;
+export const INFERENCE_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_TERMINAL_RECORDS = 200;
+const runsById = new Map();
+function pruneTerminalRecords() {
+    let excess = runsById.size - MAX_TERMINAL_RECORDS;
+    for (const [runId, record] of runsById) {
+        if (excess <= 0)
+            break;
+        if (record.outcome) {
+            runsById.delete(runId);
+            excess -= 1;
+        }
+    }
+}
+function settleRun(record, result) {
+    if (record.outcome)
+        return;
+    record.outcome = result;
+    if (record.timer)
+        clearTimeout(record.timer);
+    deregisterLiveSubscription(record.requestId);
+    if (result.usage) {
+        recordAppRunTokens(record.appId, record.spaceKey, result.usage.inputTokens + result.usage.outputTokens);
+    }
+    if (!record.tornDown) {
+        if (result.usage)
+            record.emit('usage', result.usage);
+        record.emit('status', { status: result.status });
+    }
+    for (const waiter of record.waiters.splice(0))
+        waiter(result);
+    logAppAudit({
+        appId: record.appId,
+        origin: record.origin,
+        method: 'inference.chat.end',
+        decision: 'allow',
+        requestId: record.requestId,
+        spaceKey: record.spaceKey,
+        reason: `run ${record.runId} ${result.status} engine=${result.engine} model=${result.model ?? 'default'}` +
+            (result.usage ? ` tokens=${result.usage.inputTokens}/${result.usage.outputTokens}` : '') +
+            (result.error ? ` error=${result.error.code}` : ''),
+    });
+}
+function paramsObject(params) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        throw new SdkMethodError('BAD_REQUEST', 'inference.chat requires params { messages, system?, engine?, model?, effortLevel? }');
+    }
+    return params;
+}
+function parseMessages(raw) {
+    const shapeError = new SdkMethodError('BAD_REQUEST', `inference.chat messages must be 1–${MAX_MESSAGES} { role: 'user' | 'assistant', content: string } turns ending on a 'user' turn`);
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_MESSAGES)
+        throw shapeError;
+    const messages = [];
+    let chars = 0;
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            throw shapeError;
+        const { role, content } = entry;
+        if ((role !== 'user' && role !== 'assistant') || typeof content !== 'string')
+            throw shapeError;
+        chars += content.length;
+        messages.push({ role, content });
+    }
+    if (messages[messages.length - 1]?.role !== 'user')
+        throw shapeError;
+    if (chars > MAX_CONTENT_CHARS) {
+        throw new SdkMethodError('BAD_REQUEST', `inference.chat messages exceed ${MAX_CONTENT_CHARS} characters in total`);
+    }
+    return messages;
+}
+function parseSystem(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string' || raw.length > MAX_SYSTEM_CHARS) {
+        throw new SdkMethodError('BAD_REQUEST', `inference.chat system must be a string of at most ${MAX_SYSTEM_CHARS} characters`);
+    }
+    return raw;
+}
+function parseEffortLevel(raw, engine) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string' || (raw !== 'auto' && !ENGINE_EFFORT_LEVELS[engine].includes(raw))) {
+        const accepted = ENGINE_EFFORT_LEVELS[engine].length > 0 ? ENGINE_EFFORT_LEVELS[engine].join(', ') : 'auto';
+        throw new SdkMethodError('BAD_REQUEST', `inference.chat: '${String(raw)}' is not a ${engine} effort level — expected one of ${accepted}`);
+    }
+    return raw;
+}
+export function inferenceBouncerInput(params) {
+    const raw = typeof params === 'object' && params !== null && !Array.isArray(params) ? params : {};
+    const messages = Array.isArray(raw.messages) ? raw.messages : [];
+    const contentChars = messages.reduce((total, entry) => {
+        const content = typeof entry === 'object' && entry !== null ? entry.content : undefined;
+        return total + (typeof content === 'string' ? content.length : 0);
+    }, 0);
+    return {
+        engine: typeof raw.engine === 'string' ? raw.engine : 'default',
+        model: typeof raw.model === 'string' ? raw.model : 'default',
+        effortLevel: typeof raw.effortLevel === 'string' ? raw.effortLevel : 'auto',
+        messages: messages.length,
+        chars: contentChars + (typeof raw.system === 'string' ? raw.system.length : 0),
+    };
+}
+export function inferenceChatHandler(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    const raw = paramsObject(args.params);
+    const messages = parseMessages(raw.messages);
+    const system = parseSystem(raw.system);
+    const { engine, model } = resolveAutomationTarget(raw.engine, raw.model, 'inference.chat');
+    const executor = executors[engine];
+    if (!executor) {
+        throw new SdkMethodError('UNSUPPORTED', `inference.chat: ${engine} cannot run a tool-less completion on this host — choose one of ${inferenceEngines().join(', ') || '(none)'}`);
+    }
+    const effortLevel = parseEffortLevel(raw.effortLevel, engine);
+    const runId = `inference-${Date.now()}-${randomBytes(4).toString('hex')}`;
+    const record = {
+        runId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        requestId: args.requestId,
+        engine,
+        ...(model ? { model } : {}),
+        controller: new AbortController(),
+        emit: args.emit,
+        text: '',
+        waiters: [],
+    };
+    runsById.set(runId, record);
+    pruneTerminalRecords();
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'inference.chat',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            record.tornDown = true;
+            record.controller.abort();
+            settleRun(record, { status: 'cancelled', text: record.text, engine, ...(model ? { model } : {}) });
+        },
+    });
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'inference.chat.start',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `run ${runId} engine=${engine} model=${model ?? 'default'} effort=${effortLevel ?? 'auto'} messages=${messages.length} [tool-less]`,
+    });
+    setImmediate(() => {
+        if (record.outcome)
+            return;
+        record.emit('status', { status: 'running' });
+        record.timer = setTimeout(() => {
+            record.controller.abort();
+            settleRun(record, {
+                status: 'error',
+                text: record.text,
+                engine,
+                ...(model ? { model } : {}),
+                error: { code: 'TIMEOUT', message: `the completion exceeded ${INFERENCE_TIMEOUT_MS / 1000}s` },
+            });
+        }, INFERENCE_TIMEOUT_MS);
+        record.timer.unref();
+        executor({
+            engine,
+            ...(model ? { model } : {}),
+            ...(effortLevel ? { effortLevel } : {}),
+            ...(system !== undefined ? { system } : {}),
+            messages,
+            signal: record.controller.signal,
+            onDelta: (text) => {
+                if (record.outcome)
+                    return;
+                record.text += text;
+                record.emit('delta', { text });
+            },
+        }).then((outcome) => settleRun(record, {
+            status: 'done',
+            text: outcome.text,
+            engine,
+            ...((outcome.model ?? model) ? { model: outcome.model ?? model } : {}),
+            ...(outcome.usage ? { usage: outcome.usage } : {}),
+        }), (error) => settleRun(record, {
+            status: 'error',
+            text: record.text,
+            engine,
+            ...(model ? { model } : {}),
+            error: error instanceof SdkInferenceError
+                ? { code: error.code, message: error.message }
+                : { code: 'UPSTREAM_ERROR', message: error instanceof Error ? error.message : String(error) },
+        }));
+    });
+    return { runId };
+}
+export function inferenceResultHandler(args) {
+    const raw = typeof args.params === 'object' && args.params !== null ? args.params : {};
+    const runId = typeof raw.runId === 'string' ? raw.runId : '';
+    const record = runId ? runsById.get(runId) : undefined;
+    if (!record || record.appId !== args.appId || record.spaceKey !== args.spaceKey) {
+        throw new SdkMethodError('BAD_REQUEST', `unknown runId '${runId}' — inference.result answers only this app's runs in this Space`);
+    }
+    if (record.outcome)
+        return record.outcome;
+    return new Promise((resolve) => record.waiters.push(resolve));
+}

package/dist/server/services/sdk/live-registry.js

@@ -0,0 +1,42 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+const liveRuns = new Map();
+export function registerLiveRun(run) {
+    liveRuns.set(run.runId, run);
+}
+export function deregisterLiveRun(runId) {
+    liveRuns.delete(runId);
+}
+export function findLiveRunByTab(tabId) {
+    for (const run of liveRuns.values()) {
+        if (run.tabId === tabId)
+            return run;
+    }
+    return undefined;
+}
+export function getLiveRunsForApp(appId, spaceKey) {
+    return [...liveRuns.values()].filter((run) => run.appId === appId && run.spaceKey === spaceKey);
+}
+export function listLiveRuns() {
+    return [...liveRuns.values()];
+}
+const liveSubscriptions = new Map();
+export function registerLiveSubscription(sub) {
+    liveSubscriptions.set(sub.requestId, sub);
+}
+export function deregisterLiveSubscription(requestId) {
+    liveSubscriptions.delete(requestId);
+}
+export function getLiveSubscriptionsForApp(appId, spaceKey) {
+    return [...liveSubscriptions.values()].filter((sub) => sub.appId === appId && sub.spaceKey === spaceKey);
+}
+export function getLiveSubscriptionsForViewer(viewerId) {
+    return [...liveSubscriptions.values()].filter((sub) => sub.viewerId === viewerId);
+}
+export function listLiveSubscriptions() {
+    return [...liveSubscriptions.values()];
+}
+export function resetLiveRegistry() {
+    liveRuns.clear();
+    liveSubscriptions.clear();
+}

package/dist/server/services/sdk/local-app-bindings.js

@@ -0,0 +1,71 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { isLocalhostUrl } from '../../mcp/security-patterns.js';
+import { SDK_HOST_APP_ID } from './host-ops.js';
+import { isValidAppId } from './sandbox.js';
+const bindings = new Map();
+export function isLoopbackHostname(hostname) {
+    const host = hostname.toLowerCase();
+    return (host === 'localhost' ||
+        host.endsWith('.localhost') ||
+        host === '127.0.0.1' ||
+        host === '[::1]' ||
+        host === '::1');
+}
+export function isLocalhostFamilyOrigin(origin) {
+    if (isLocalhostUrl(origin))
+        return true;
+    try {
+        return isLoopbackHostname(new URL(origin).hostname.replace(/\.$/, ''));
+    }
+    catch {
+        return false;
+    }
+}
+export function registerLocalAppBinding(input) {
+    if (!Number.isInteger(input.port) || input.port < 1 || input.port > 65535) {
+        throw new Error(`Invalid port ${input.port} — expected an integer in 1–65535`);
+    }
+    if (!isValidAppId(input.appId)) {
+        throw new Error(`Invalid appId '${input.appId}' — expected the D5 grammar (lowercase [a-z0-9-])`);
+    }
+    if (input.appId === SDK_HOST_APP_ID) {
+        throw new Error(`'${SDK_HOST_APP_ID}' is the reserved host identity and cannot be bound to a port`);
+    }
+    const manifest = input.manifest;
+    if (typeof manifest !== 'object' ||
+        manifest === null ||
+        typeof manifest.hash !== 'string' ||
+        manifest.hash === '' ||
+        !Array.isArray(manifest.scopes) ||
+        !manifest.scopes.every((scope) => typeof scope === 'string') ||
+        !Array.isArray(manifest.optionalScopes) ||
+        !manifest.optionalScopes.every((scope) => typeof scope === 'string')) {
+        throw new Error('Binding manifest must be { hash, scopes, optionalScopes } (the pinned consent envelope)');
+    }
+    const binding = {
+        port: input.port,
+        appId: input.appId,
+        manifest: {
+            hash: manifest.hash,
+            scopes: [...manifest.scopes],
+            optionalScopes: [...manifest.optionalScopes],
+        },
+        registeredAt: new Date().toISOString(),
+        source: input.source,
+    };
+    bindings.set(input.port, binding);
+    return binding;
+}
+export function unregisterLocalAppBinding(port) {
+    return bindings.delete(port);
+}
+export function getLocalAppBinding(port) {
+    return bindings.get(port);
+}
+export function listLocalAppBindings() {
+    return [...bindings.values()];
+}
+export function clearLocalAppBindings() {
+    bindings.clear();
+}

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

@@ -0,0 +1,190 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { can } from '@minionry/roles';
+import { reviewEnginePermission } from '../../mcp/bouncer-integration.js';
+import { getClientId } from '../client-id.js';
+import { makeSpaceKey } from '../settings.js';
+import { logAppAudit } from './audit.js';
+import { getGrant, getSessionGrant, touchLastUsed } from './grant-store.js';
+import { checkSdkRateLimit } from './rate-limits.js';
+import { resolveSdkMethod, SDK_GRANTLESS_METHODS, SDK_WRITE_CAPABILITY, SdkMethodError, } from './registry.js';
+import { recordSdkStreamEvent } from './streams.js';
+const defaultRateLimiter = (op) => checkSdkRateLimit(op);
+let rateLimiter = defaultRateLimiter;
+export function setSdkRateLimiter(limiter) {
+    rateLimiter = limiter;
+}
+export function resetSdkRateLimiter() {
+    rateLimiter = defaultRateLimiter;
+}
+function normalizeParams(params) {
+    if (typeof params === 'object' && params !== null && !Array.isArray(params)) {
+        return params;
+    }
+    return params === undefined ? {} : { params };
+}
+function checkGrantScopesAndRole(method, row, grant, input) {
+    if (!SDK_GRANTLESS_METHODS.has(method)) {
+        if (!grant) {
+            return {
+                decision: 'scope_denied',
+                code: 'SCOPE_DENIED',
+                message: `app '${input.appId}' has no grant in this Space — call connect() first`,
+            };
+        }
+        const required = row.resolveScopes?.(input.params) ?? row.scopes;
+        const missing = required.filter((scope) => !grant.scopes.includes(scope));
+        if (missing.length > 0) {
+            return {
+                decision: 'scope_denied',
+                code: 'SCOPE_DENIED',
+                message: `'${method}' requires scope(s) the app was not granted: ${missing.join(', ')}`,
+            };
+        }
+    }
+    const capability = SDK_WRITE_CAPABILITY[row.type];
+    if (capability && !can(input.role, capability)) {
+        return {
+            decision: 'scope_denied',
+            code: 'SCOPE_DENIED',
+            message: `role '${input.role}' lacks the '${capability}' capability required by ${row.type}`,
+        };
+    }
+    return null;
+}
+async function reviewWithBouncer(method, row, grant, input) {
+    try {
+        const decision = await reviewEnginePermission({
+            toolName: row.bouncerToolName ?? method,
+            input: row.bouncerInput ? row.bouncerInput(input.params) : normalizeParams(input.params),
+            context: {
+                source: 'sdk',
+                appId: input.appId,
+                appOrigin: input.origin,
+                grantedScopes: grant ? [...grant.scopes] : [],
+                workingDirectory: input.workingDir,
+                sessionId: `sdk:${input.appId}`,
+            },
+        });
+        if (decision.decision === 'deny') {
+            return {
+                denial: {
+                    decision: 'deny',
+                    code: 'SECURITY_BLOCKED',
+                    message: `🚫 ${decision.reasoning}`,
+                    reason: decision.reasoning,
+                },
+            };
+        }
+        return { verdict: decision.decision === 'warn_allow' ? 'warn_allow' : 'allow' };
+    }
+    catch (error) {
+        return {
+            denial: {
+                decision: 'deny',
+                code: 'SECURITY_BLOCKED',
+                message: 'security review failed — operation blocked (fail closed)',
+                reason: `bouncer review failed: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        };
+    }
+}
+async function admitOp(row, args) {
+    if (!row.admit)
+        return null;
+    try {
+        await row.admit(args);
+        return null;
+    }
+    catch (error) {
+        if (error instanceof SdkMethodError)
+            return { code: error.code, message: error.message };
+        console.error(`[SdkPipeline] admission for '${args.method}' threw:`, error);
+        return { code: 'INTERNAL', message: `'${args.method}' could not be admitted` };
+    }
+}
+async function dispatchHandler(row, args) {
+    try {
+        const result = await row.handler(args);
+        return { requestId: args.requestId, ok: true, result: result ?? null };
+    }
+    catch (error) {
+        if (error instanceof SdkMethodError) {
+            return { requestId: args.requestId, ok: false, error: { code: error.code, message: error.message } };
+        }
+        console.error(`[SdkPipeline] handler for '${args.method}' threw:`, error);
+        return {
+            requestId: args.requestId,
+            ok: false,
+            error: { code: 'INTERNAL', message: `'${args.method}' failed: ${error instanceof Error ? error.message : String(error)}` },
+        };
+    }
+}
+export async function runSdkPipeline(input) {
+    const { appId, origin, requestId } = input;
+    const spaceKey = makeSpaceKey(getClientId(), input.workingDir);
+    const auditOnce = (method, decision, reason) => {
+        logAppAudit({ appId, origin, method, decision, requestId, spaceKey, ...(reason !== undefined ? { reason } : {}) });
+    };
+    const deny = (method, denial) => {
+        auditOnce(method, denial.decision, denial.reason ?? denial.message);
+        return { requestId, ok: false, error: { code: denial.code, message: denial.message } };
+    };
+    const resolved = resolveSdkMethod(input.wireType, input.method);
+    if (!resolved.ok) {
+        return deny(input.method ?? input.wireType, {
+            decision: 'scope_denied',
+            code: 'SCOPE_DENIED',
+            message: resolved.message,
+        });
+    }
+    const { method, row } = resolved;
+    const persisted = getGrant(appId, spaceKey);
+    const grant = persisted ?? (input.viewerId ? getSessionGrant(input.viewerId, appId, spaceKey) : undefined);
+    const gateDenial = checkGrantScopesAndRole(method, row, grant, input);
+    if (gateDenial)
+        return deny(method, gateDenial);
+    const review = await reviewWithBouncer(method, row, grant, input);
+    if ('denial' in review)
+        return deny(method, review.denial);
+    const handlerArgs = {
+        appId,
+        origin,
+        requestId,
+        method,
+        params: input.params,
+        role: input.role,
+        viewerId: input.viewerId,
+        tabId: input.tabId,
+        workingDir: input.workingDir,
+        spaceKey,
+        grant,
+        manifest: input.manifest,
+        consentRouting: input.consentRouting,
+        verifiedLocalBinding: input.verifiedLocalBinding,
+        emit: (event, payload) => {
+            const seq = recordSdkStreamEvent({ requestId, appId, spaceKey, kind: method }, event, payload);
+            input.emit(event, payload, seq);
+        },
+        notify: input.notify,
+    };
+    const refusal = await admitOp(row, handlerArgs);
+    if (refusal) {
+        auditOnce(method, review.verdict, `refused at admission: ${refusal.code} ${refusal.message}`);
+        return { requestId, ok: false, error: refusal };
+    }
+    const verdict = rateLimiter({ appId, spaceKey, method, grant });
+    if (verdict?.limited) {
+        return deny(method, { decision: 'rate_limited', code: 'RATE_LIMITED', message: verdict.message });
+    }
+    auditOnce(method, review.verdict);
+    if (persisted)
+        touchLastUsed(appId, spaceKey);
+    try {
+        return await dispatchHandler(row, handlerArgs);
+    }
+    finally {
+        if (verdict && !verdict.limited)
+            verdict.onDispatched();
+    }
+}