@minionry/minion 0.7.36

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

@@ -0,0 +1,86 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { logAppAudit } from './audit.js';
+import { removeAppEndpoints } from './endpoints.js';
+import { clearAllSessionGrants, clearSessionGrants, removeGrant, removeSessionGrantsForApp, } from './grant-store.js';
+import { deregisterLiveSubscription, getLiveRunsForApp, getLiveSubscriptionsForApp, getLiveSubscriptionsForViewer, listLiveSubscriptions, } from './live-registry.js';
+import { SdkMethodError } from './registry.js';
+import { isValidAppId } from './sandbox.js';
+import { dropSdkStream, dropSdkStreamsForApp } from './streams.js';
+export function dropSubscription(sub, auditMethod, cause) {
+    deregisterLiveSubscription(sub.requestId);
+    dropSdkStream(sub.requestId);
+    try {
+        sub.teardown();
+    }
+    catch (error) {
+        console.error(`[SdkRevoke] teardown of ${sub.kind} subscription '${sub.requestId}' threw:`, error);
+    }
+    logAppAudit({
+        appId: sub.appId,
+        origin: sub.origin,
+        method: auditMethod,
+        decision: 'allow',
+        requestId: sub.requestId,
+        spaceKey: sub.spaceKey,
+        reason: `dropped ${sub.kind} subscription (${cause})`,
+    });
+}
+export function revokeAppGrantsInSpace(appId, spaceKey, notify) {
+    const removedPersisted = removeGrant(appId, spaceKey);
+    const removedSessionGrants = removeSessionGrantsForApp(appId, spaceKey);
+    const runs = getLiveRunsForApp(appId, spaceKey);
+    for (const run of runs) {
+        try {
+            run.cancel();
+        }
+        catch (error) {
+            console.error(`[SdkRevoke] cancel of run '${run.runId}' threw:`, error);
+        }
+        logAppAudit({
+            appId: run.appId,
+            origin: run.origin,
+            method: 'grants.revoke.runCancelled',
+            decision: 'allow',
+            requestId: run.requestId,
+            spaceKey: run.spaceKey,
+            reason: `cancelled run ${run.runId} in tab ${run.tabId} (grant revoked)`,
+        });
+    }
+    const subscriptions = getLiveSubscriptionsForApp(appId, spaceKey);
+    for (const sub of subscriptions) {
+        dropSubscription(sub, 'grants.revoke.subscriptionDropped', 'grant revoked');
+    }
+    dropSdkStreamsForApp(appId, spaceKey);
+    try {
+        removeAppEndpoints(appId, spaceKey, 'grant revoked');
+    }
+    catch (error) {
+        console.error(`[SdkRevoke] removing '${appId}' endpoints threw:`, error instanceof Error ? error.message : error);
+    }
+    notify?.({ type: 'sdkGrantsChanged', data: { appId, grants: [] }, broadcast: true });
+    return {
+        revoked: removedPersisted || removedSessionGrants > 0,
+        cancelledRuns: runs.length,
+        droppedSubscriptions: subscriptions.length,
+    };
+}
+export function revokeGrantsHandler(args) {
+    const { appId, spaceKey } = args;
+    if (!isValidAppId(appId)) {
+        throw new SdkMethodError('BAD_REQUEST', `invalid appId '${appId}' — expected the D5 grammar (lowercase [a-z0-9-])`);
+    }
+    return revokeAppGrantsInSpace(appId, spaceKey, args.notify);
+}
+export function teardownSdkForViewer(viewerId) {
+    clearSessionGrants(viewerId);
+    for (const sub of getLiveSubscriptionsForViewer(viewerId)) {
+        dropSubscription(sub, 'session.end.subscriptionDropped', 'viewer session ended');
+    }
+}
+export function teardownSdkOnTransportClose() {
+    clearAllSessionGrants();
+    for (const sub of listLiveSubscriptions()) {
+        dropSubscription(sub, 'session.end.subscriptionDropped', 'transport closed');
+    }
+}

package/dist/server/services/sdk/run-profile.js

@@ -0,0 +1,41 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { isScope } from '@minionry/app-manifest';
+import { spacePath } from '../space-layout.js';
+import { isValidAppId } from './sandbox.js';
+export const WORKSPACE_READ_TOOLS = ['Read', 'Grep', 'Glob', 'LS', 'NotebookRead'];
+export const WORKSPACE_WRITE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit'];
+export const WORKSPACE_SHELL_TOOLS = ['Bash', 'BashOutput', 'KillBash', 'KillShell'];
+export const WORKSPACE_NOTE_OPEN = '--- Minionry host note ---';
+export const WORKSPACE_NOTE_CLOSE = '--- End host note ---';
+export function buildWorkspaceNote(workingDir) {
+    return [
+        WORKSPACE_NOTE_OPEN,
+        `This session was started by a Workshop app. The Space root is: ${workingDir}`,
+        `A path written \`workspace:/<path>\` means \`${workingDir}/<path>\`.`,
+        'Your working directory is the app\'s sandbox, not the Space root — relative paths resolve inside the sandbox, so address Space files by their absolute path.',
+        WORKSPACE_NOTE_CLOSE,
+    ].join('\n');
+}
+export function deriveRunProfile(input) {
+    if (!isValidAppId(input.appId)) {
+        throw new Error(`Cannot derive a run profile for invalid appId '${input.appId}' (fail closed)`);
+    }
+    const scopes = input.grantScopes.filter(isScope);
+    const workspaceWrite = scopes.includes('files:workspace:write');
+    const workspaceRead = workspaceWrite || scopes.includes('files:workspace:read');
+    return {
+        appId: input.appId,
+        origin: input.origin,
+        scopes,
+        cwd: spacePath(input.workingDir, 'apps', input.appId, 'data'),
+        disallowedTools: [
+            ...(workspaceRead ? [] : WORKSPACE_READ_TOOLS),
+            ...(workspaceWrite ? [] : [...WORKSPACE_WRITE_TOOLS, ...WORKSPACE_SHELL_TOOLS]),
+        ],
+        ...(workspaceRead ? { workspaceNote: buildWorkspaceNote(input.workingDir) } : {}),
+    };
+}
+export function profileAllowsBrowserControl(profile) {
+    return profile.scopes.includes('browser:control');
+}

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

@@ -0,0 +1,89 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { lstatSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { spacePath } from '../space-layout.js';
+const APP_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+export function isValidAppId(appId) {
+    return typeof appId === 'string' && APP_ID_PATTERN.test(appId);
+}
+function lexists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertNotSymlink(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        return;
+    }
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Refusing to provision app sandbox through a symlink: ${path}`);
+    }
+}
+export function getAppSandboxPaths(workingDir, appId) {
+    if (!isValidAppId(appId)) {
+        throw new Error(`Invalid appId '${appId}' — expected the D5 grammar (lowercase [a-z0-9-])`);
+    }
+    const realWorkingDir = realpathSync(resolve(workingDir));
+    const root = spacePath(realWorkingDir, 'apps', appId);
+    return { root, dataDir: join(root, 'data'), kvFile: join(root, 'kv.json') };
+}
+export function provisionAppSandbox(workingDir, appId) {
+    const paths = getAppSandboxPaths(workingDir, appId);
+    const { root, dataDir, kvFile } = paths;
+    const appsDir = dirname(root);
+    const minionryDir = dirname(appsDir);
+    for (const component of [minionryDir, appsDir, root, dataDir, kvFile]) {
+        assertNotSymlink(component);
+    }
+    mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    if (!lexists(kvFile)) {
+        try {
+            writeFileSync(kvFile, '{}\n', { mode: 0o600, flag: 'wx' });
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    return paths;
+}
+export function resolveWithinRoot(root, targetPath, opts) {
+    try {
+        const realRoot = realpathSync(resolve(root));
+        const resolved = isAbsolute(targetPath) ? resolve(targetPath) : resolve(realRoot, targetPath);
+        let probe = resolved;
+        const remainder = [];
+        while (!lexists(probe)) {
+            const parent = dirname(probe);
+            if (parent === probe)
+                break;
+            remainder.unshift(basename(probe));
+            probe = parent;
+        }
+        const realProbe = realpathSync(probe);
+        const realResolved = remainder.length > 0 ? join(realProbe, ...remainder) : realProbe;
+        if (realResolved !== realRoot && !realResolved.startsWith(realRoot + sep)) {
+            if (!opts?.quiet) {
+                console.error(`[Sandbox] SECURITY: path escape blocked. Target: "${targetPath}", Resolved: "${realResolved}", Root: "${realRoot}"`);
+            }
+            return { valid: false, resolvedPath: '', error: 'Access denied: path is outside the app sandbox' };
+        }
+        return { valid: true, resolvedPath: realResolved };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            resolvedPath: '',
+            error: `Invalid path: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}

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

@@ -0,0 +1,110 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { SdkMethodError } from './registry.js';
+import { getAppSandboxPaths, provisionAppSandbox } from './sandbox.js';
+export const STORAGE_MAX_BYTES = 1024 * 1024;
+export const STORAGE_MAX_KEY_CHARS = 256;
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function parseKeyParam(params, method) {
+    const raw = paramsObject(params);
+    if (typeof raw.key !== 'string' || raw.key === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { key } — a non-empty string`);
+    }
+    if (raw.key.length > STORAGE_MAX_KEY_CHARS) {
+        throw new SdkMethodError('BAD_REQUEST', `storage key is ${raw.key.length} chars — exceeds the ${STORAGE_MAX_KEY_CHARS}-char key cap`);
+    }
+    return raw.key;
+}
+function appKvFile(args) {
+    try {
+        return provisionAppSandbox(args.workingDir, args.appId).kvFile;
+    }
+    catch (error) {
+        throw new SdkMethodError('INTERNAL', `app sandbox unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function loadStore(kvFile) {
+    let content;
+    try {
+        content = readFileSync(kvFile, 'utf-8');
+    }
+    catch {
+        return Object.create(null);
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return Object.assign(Object.create(null), parsed);
+        }
+        console.warn(`[SdkStorage] ${kvFile} does not hold a JSON object — treating the store as empty`);
+    }
+    catch (error) {
+        console.warn(`[SdkStorage] ${kvFile} is not valid JSON — treating the store as empty:`, error instanceof Error ? error.message : String(error));
+    }
+    return Object.create(null);
+}
+function flushStore(kvFile, serialized) {
+    const tempFile = `${kvFile}.tmp`;
+    try {
+        rmSync(tempFile, { force: true });
+        writeFileSync(tempFile, `${serialized}\n`, { mode: 0o600, flag: 'wx' });
+        renameSync(tempFile, kvFile);
+    }
+    catch (error) {
+        throw new SdkMethodError('INTERNAL', `failed to persist the storage store: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function assertJsonSerializable(value, method) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch (error) {
+        throw new SdkMethodError('BAD_REQUEST', `${method} value is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (serialized === undefined) {
+        throw new SdkMethodError('BAD_REQUEST', `${method} value is not JSON-serializable — undefined, functions, and symbols have no JSON form`);
+    }
+}
+export function storageGetHandler(args) {
+    const key = parseKeyParam(args.params, args.method);
+    const value = loadStore(appKvFile(args))[key];
+    return value === undefined ? null : value;
+}
+export function storageKeysHandler(args) {
+    return Object.keys(loadStore(appKvFile(args)));
+}
+export function storageSetHandler(args) {
+    const key = parseKeyParam(args.params, args.method);
+    const value = paramsObject(args.params).value;
+    assertJsonSerializable(value, args.method);
+    const kvFile = appKvFile(args);
+    const store = loadStore(kvFile);
+    store[key] = value;
+    const serialized = JSON.stringify(store);
+    const bytes = Buffer.byteLength(serialized, 'utf-8');
+    if (bytes > STORAGE_MAX_BYTES) {
+        throw new SdkMethodError('QUOTA_EXCEEDED', `serialized store would be ${bytes} bytes — exceeds the ${STORAGE_MAX_BYTES}-byte per-app storage quota`);
+    }
+    flushStore(kvFile, serialized);
+    return null;
+}
+export function storageDeleteHandler(args) {
+    const key = parseKeyParam(args.params, args.method);
+    const kvFile = appKvFile(args);
+    const store = loadStore(kvFile);
+    if (!Object.hasOwn(store, key))
+        return null;
+    delete store[key];
+    flushStore(kvFile, JSON.stringify(store));
+    return null;
+}
+export function deleteAppStorage(workingDir, appId) {
+    const { kvFile } = getAppSandboxPaths(workingDir, appId);
+    rmSync(kvFile, { force: true });
+}

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

@@ -0,0 +1,147 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { SeqEventBuffer } from '../websocket/tab-event-buffer.js';
+import { planSeqReplay } from '../websocket/tab-event-replay.js';
+import { listLiveRuns, listLiveSubscriptions } from './live-registry.js';
+import { SdkMethodError } from './registry.js';
+export const SDK_STREAM_MAX_EVENTS = 1_000;
+export const SDK_STREAM_MAX_AGE_MS = 10 * 60 * 1000;
+export const SDK_STREAM_MAX_BYTES = 1024 * 1024;
+export const SDK_STREAM_MAX_STREAMS = 256;
+export const SDK_STREAM_MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+export const PTY_STREAM_KINDS = new Set(['terminal.attach']);
+const windows = new Map();
+let totalBytes = 0;
+let evictedStreams = 0;
+const newWindowBuffer = () => new SeqEventBuffer(SDK_STREAM_MAX_EVENTS, SDK_STREAM_MAX_AGE_MS, Date.now, SDK_STREAM_MAX_BYTES);
+const newPtyWindowBuffer = () => new SeqEventBuffer(0, 0, Date.now, 0);
+function touch(window) {
+    windows.delete(window.requestId);
+    windows.set(window.requestId, window);
+}
+function forget(requestId) {
+    const window = windows.get(requestId);
+    if (!window)
+        return false;
+    windows.delete(requestId);
+    totalBytes -= window.bytes;
+    if (totalBytes < 0)
+        totalBytes = 0;
+    return true;
+}
+function enforceGlobalBudget() {
+    while (windows.size > SDK_STREAM_MAX_STREAMS || (totalBytes > SDK_STREAM_MAX_TOTAL_BYTES && windows.size > 0)) {
+        const oldest = windows.keys().next();
+        if (oldest.done)
+            break;
+        forget(oldest.value);
+        evictedStreams += 1;
+    }
+}
+export function recordSdkStreamEvent(identity, event, payload) {
+    let window = windows.get(identity.requestId);
+    if (!window) {
+        const buffer = PTY_STREAM_KINDS.has(identity.kind) ? newPtyWindowBuffer() : newWindowBuffer();
+        window = { ...identity, buffer, bytes: 0 };
+        windows.set(identity.requestId, window);
+    }
+    else {
+        touch(window);
+    }
+    const seq = window.buffer.record(event, payload);
+    const bytes = window.buffer.byteSize();
+    totalBytes += bytes - window.bytes;
+    window.bytes = bytes;
+    enforceGlobalBudget();
+    return seq;
+}
+export function dropSdkStream(requestId) {
+    return forget(requestId);
+}
+export function dropSdkStreamsForApp(appId, spaceKey) {
+    let dropped = 0;
+    for (const window of [...windows.values()]) {
+        if (window.appId === appId && window.spaceKey === spaceKey && forget(window.requestId))
+            dropped += 1;
+    }
+    return dropped;
+}
+export function getSdkStreamBudget() {
+    let events = 0;
+    for (const window of windows.values())
+        events += window.buffer.size();
+    return {
+        streams: windows.size,
+        events,
+        bytes: totalBytes,
+        maxStreams: SDK_STREAM_MAX_STREAMS,
+        maxBytes: SDK_STREAM_MAX_TOTAL_BYTES,
+        evictedStreams,
+    };
+}
+export function resetSdkStreams() {
+    windows.clear();
+    totalBytes = 0;
+    evictedStreams = 0;
+}
+function parseResumeParams(params) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        throw new SdkMethodError('BAD_REQUEST', 'stream.resume requires params { requestId, afterSeq? } naming the stream to resume');
+    }
+    const raw = params;
+    if (typeof raw.requestId !== 'string' || raw.requestId === '') {
+        throw new SdkMethodError('BAD_REQUEST', 'stream.resume requires a non-empty string requestId — the id of the envelope that opened the stream');
+    }
+    if (raw.afterSeq !== undefined && (typeof raw.afterSeq !== 'number' || !Number.isInteger(raw.afterSeq) || raw.afterSeq < 0)) {
+        throw new SdkMethodError('BAD_REQUEST', 'stream.resume afterSeq must be a non-negative integer when present');
+    }
+    return { requestId: raw.requestId, afterSeq: raw.afterSeq ?? 0 };
+}
+function hasLiveStream(requestId, appId, spaceKey) {
+    const owned = (work) => work.requestId === requestId && work.appId === appId && work.spaceKey === spaceKey;
+    return (listLiveRuns().some(owned) ||
+        listLiveSubscriptions().some((sub) => owned(sub) && !PTY_STREAM_KINDS.has(sub.kind)));
+}
+function streamGap(requestId, afterSeq, detail, recovery = 'Reconcile with a snapshot read (agents.result / pm.getBoard) — the buffered window is bounded by design.') {
+    return new SdkMethodError('STREAM_GAP', `stream '${requestId}' cannot be resumed from seq ${afterSeq}: ${detail}. ${recovery}`);
+}
+export function resumeSdkStream(args) {
+    const { requestId, appId, spaceKey, afterSeq } = args;
+    const window = windows.get(requestId);
+    if (!window) {
+        if (hasLiveStream(requestId, appId, spaceKey)) {
+            return { requestId, fromSeq: afterSeq, events: [], currentSeq: 0 };
+        }
+        throw streamGap(requestId, afterSeq, 'no buffered window is held for it');
+    }
+    if (window.appId !== appId || window.spaceKey !== spaceKey) {
+        throw streamGap(requestId, afterSeq, 'no buffered window is held for it');
+    }
+    if (PTY_STREAM_KINDS.has(window.kind)) {
+        throw streamGap(requestId, afterSeq, 'pty streams keep no replay window', 'Re-attach to replay the tail from the terminal scrollback — resume is never supported on a pty stream.');
+    }
+    touch(window);
+    const plan = planSeqReplay(window.buffer, afterSeq);
+    const bytes = window.buffer.byteSize();
+    totalBytes += bytes - window.bytes;
+    window.bytes = bytes;
+    if (plan.kind === 'gap') {
+        throw streamGap(requestId, afterSeq, `events (${afterSeq + 1}..${plan.evictedThroughSeq}) have been evicted from the ` +
+            `bounded window (max ${SDK_STREAM_MAX_EVENTS} events / ${SDK_STREAM_MAX_AGE_MS / 60_000} min / ` +
+            `${SDK_STREAM_MAX_BYTES} bytes per stream)`);
+    }
+    return {
+        requestId,
+        fromSeq: afterSeq,
+        events: plan.events.map((buffered) => ({
+            seq: buffered.seq,
+            event: buffered.type,
+            ...(buffered.data !== undefined ? { payload: buffered.data } : {}),
+        })),
+        currentSeq: window.buffer.currentSeq(),
+    };
+}
+export function sdkStreamResumeHandler(args) {
+    const { requestId, afterSeq } = parseResumeParams(args.params);
+    return resumeSdkStream({ requestId, appId: args.appId, spaceKey: args.spaceKey, afterSeq });
+}

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

@@ -0,0 +1,201 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { getGrant } from './grant-store.js';
+import { deregisterLiveSubscription, listLiveSubscriptions, registerLiveSubscription } from './live-registry.js';
+import { SdkMethodError } from './registry.js';
+export const SDK_TERMINAL_ID_PREFIX = 'sdk-term-';
+export function isSdkOpenedTerminalId(id) {
+    return id.startsWith(SDK_TERMINAL_ID_PREFIX);
+}
+let terminalHost = null;
+export function setSdkTerminalHost(host) {
+    terminalHost = host;
+}
+export function resetSdkTerminalHost() {
+    terminalHost = null;
+}
+function requireHost(method) {
+    if (!terminalHost) {
+        throw new SdkMethodError('INTERNAL', `${method}: the terminal host is not wired — the WebSocket handler installs it at startup`);
+    }
+    return terminalHost;
+}
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function requireIdParam(raw, method) {
+    const value = raw.id;
+    if (typeof value !== 'string' || value === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { id } — a non-empty string`);
+    }
+    return value;
+}
+function requireSizeParam(raw, name, method) {
+    const value = raw[name];
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 1000) {
+        throw new SdkMethodError('BAD_REQUEST', `${method}: ${name} must be an integer between 1 and 1000`);
+    }
+    return value;
+}
+function ptyUnavailable(host) {
+    return new SdkMethodError('PTY_NOT_AVAILABLE', host.installInstructions());
+}
+function normalizePtyError(error, host) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('PTY_NOT_AVAILABLE')) {
+        const instructions = message.slice('PTY_NOT_AVAILABLE'.length).replace(/^:/, '').trim();
+        throw new SdkMethodError('PTY_NOT_AVAILABLE', instructions || host.installInstructions());
+    }
+    throw error;
+}
+export function terminalSessionsListHandler(args) {
+    return requireHost(args.method).listSessions();
+}
+export function terminalSessionsSubscribeHandler(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    const host = requireHost(args.method);
+    let active = true;
+    const unsubscribe = host.subscribeSessions((change) => {
+        if (!active)
+            return;
+        args.emit('sessionChanged', change);
+    });
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'terminal.sessions.subscribe',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            active = false;
+            unsubscribe();
+        },
+    });
+    return { subscribed: true };
+}
+export function terminalAttachHandler(args) {
+    const host = requireHost(args.method);
+    const raw = paramsObject(args.params);
+    const id = requireIdParam(raw, args.method);
+    if (!host.isPtyAvailable())
+        throw ptyUnavailable(host);
+    if (!host.exists(id)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: no terminal session '${id}' in this Space`);
+    }
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    let active = true;
+    const detach = host.attach(id, {
+        onOutput: (data) => {
+            if (active)
+                args.emit('output', { data });
+        },
+        onExit: (exitCode) => {
+            if (!active)
+                return;
+            args.emit('exit', { exitCode });
+            active = false;
+            detach();
+            deregisterLiveSubscription(args.requestId);
+        },
+        onError: (message) => {
+            if (active)
+                args.emit('error', { message });
+        },
+    });
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'terminal.attach',
+        viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+        teardown: () => {
+            active = false;
+            detach();
+        },
+    });
+    args.emit('scrollback', { data: host.getScrollback(id) ?? '' });
+    return { id };
+}
+export async function terminalOpenHandler(args) {
+    const host = requireHost(args.method);
+    const raw = paramsObject(args.params);
+    const cols = requireSizeParam(raw, 'cols', args.method);
+    const rows = requireSizeParam(raw, 'rows', args.method);
+    const cwd = typeof raw.cwd === 'string' && raw.cwd !== '' ? raw.cwd : undefined;
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+    if (!(await host.ensurePtyAvailable()))
+        throw ptyUnavailable(host);
+    try {
+        const opened = await host.open({ appId: args.appId, cwd, cols, rows, workingDir: args.workingDir });
+        const unsubscribeRoster = host.subscribeSessions((change) => {
+            if (change.kind === 'closed' && change.id === opened.id) {
+                unsubscribeRoster();
+                deregisterLiveSubscription(args.requestId);
+            }
+        });
+        registerLiveSubscription({
+            requestId: args.requestId,
+            appId: args.appId,
+            origin: args.origin,
+            spaceKey: args.spaceKey,
+            kind: 'terminal.open',
+            viewerId: getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId,
+            teardown: () => {
+                unsubscribeRoster();
+                if (isSdkOpenedTerminalId(opened.id))
+                    host.close(opened.id);
+            },
+        });
+        return opened;
+    }
+    catch (error) {
+        normalizePtyError(error, host);
+    }
+}
+export function terminalWriteHandler(args) {
+    const host = requireHost(args.method);
+    const raw = paramsObject(args.params);
+    const id = requireIdParam(raw, args.method);
+    const data = raw.data;
+    const isChunkArray = Array.isArray(data) && data.every((chunk) => typeof chunk === 'string');
+    if (typeof data !== 'string' && !isChunkArray) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires params { id, data } — data a string or an array of strings`);
+    }
+    if (!host.exists(id)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: no terminal session '${id}' in this Space`);
+    }
+    const input = typeof data === 'string' ? data : data.join('');
+    if (input !== '' && !host.write(id, input)) {
+        throw new SdkMethodError('INTERNAL', `${args.method}: write to terminal session '${id}' failed`);
+    }
+    return null;
+}
+export function terminalResizeHandler(args) {
+    const host = requireHost(args.method);
+    const raw = paramsObject(args.params);
+    const id = requireIdParam(raw, args.method);
+    const cols = requireSizeParam(raw, 'cols', args.method);
+    const rows = requireSizeParam(raw, 'rows', args.method);
+    if (!host.exists(id)) {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method}: no terminal session '${id}' in this Space`);
+    }
+    host.resize(id, cols, rows);
+    return null;
+}
+export function terminalCloseHandler(args) {
+    const host = requireHost(args.method);
+    const raw = paramsObject(args.params);
+    const id = requireIdParam(raw, args.method);
+    host.close(id);
+    return null;
+}