@minionry/minion 0.7.36

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

@@ -0,0 +1,314 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomUUID } from 'node:crypto';
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { ModelProfileError, ModelProfileStore, parseProfileExpiry, profileCredentialId, profileModelValue, } from '../../engines/credentials/model-profiles.js';
+import { ProviderCredentialStore } from '../../engines/credentials/provider-credentials.js';
+import { cancelRunsForModel } from './agents.js';
+import { appProfileId, isAppOwnedProfile, listAppProfiles, purgeExpiredAppProfiles, removeAppProfiles, } from './app-endpoints.js';
+import { logAppAudit } from './audit.js';
+import { findBlockedEndpointAddressReason, MAX_ENDPOINT_URL_BYTES, validateEndpointUrl } from './endpoint-url.js';
+import { SdkMethodError } from './registry.js';
+export { validateEndpointUrl } from './endpoint-url.js';
+export const MAX_ENDPOINTS_PER_APP = 8;
+export const DEFAULT_ENDPOINT_TTL_MS = 3_600_000;
+export const MAX_ENDPOINT_TTL_MS = 86_400_000;
+export const ENDPOINT_REAPER_INTERVAL_MS = 60_000;
+const ENDPOINT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const MAX_LABEL_CHARS = 80;
+const MAX_MODEL_CHARS = 200;
+const MAX_API_KEY_BYTES = 4096;
+const ENDPOINT_ENGINES = ['hermes'];
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const WHITESPACE_OR_CONTROL = /[\s\u0000-\u001f\u007f]/;
+const REGISTER_SHAPE = '{ id, label, engine, baseUrl, apiKey, model, contextLength?, ttlMs? }';
+const REGISTER_KEYS = new Set([
+    'id',
+    'label',
+    'engine',
+    'baseUrl',
+    'apiKey',
+    'model',
+    'contextLength',
+    'ttlMs',
+]);
+const UNREGISTER_KEYS = new Set(['id']);
+const defaultLookup = (hostname) => dnsLookup(hostname, { all: true, verbatim: true });
+let lookup = defaultLookup;
+export function setSdkEndpointsLookup(fn) {
+    lookup = fn;
+}
+export function resetSdkEndpoints() {
+    lookup = defaultLookup;
+    stopAppEndpointReaper();
+}
+export async function resolveAndCheck(host, resolve = lookup) {
+    let addresses;
+    try {
+        addresses = await resolve(host);
+    }
+    catch {
+        throw new SdkMethodError('ENDPOINT_INVALID', 'endpoints.register: the endpoint hostname did not resolve');
+    }
+    if (addresses.length === 0) {
+        throw new SdkMethodError('ENDPOINT_INVALID', 'endpoints.register: the endpoint hostname did not resolve');
+    }
+    for (const { address } of addresses) {
+        const reason = findBlockedEndpointAddressReason(address);
+        if (reason !== null) {
+            throw new SdkMethodError('ENDPOINT_INVALID', `endpoints.register: the endpoint hostname resolves to a refused address range (${reason})`);
+        }
+    }
+}
+function badRequest(message) {
+    return new SdkMethodError('BAD_REQUEST', message);
+}
+function strictParams(params, method, shape, keys) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        throw badRequest(`${method} requires params ${shape}`);
+    }
+    const raw = params;
+    for (const key of Object.keys(raw)) {
+        if (!keys.has(key)) {
+            const named = key.length > 64 ? `${key.slice(0, 64)}…` : key;
+            throw badRequest(`${method}: unknown param '${named}' — expected ${shape}`);
+        }
+    }
+    return raw;
+}
+function parseEndpointId(raw, method) {
+    if (typeof raw !== 'string' || !ENDPOINT_ID_PATTERN.test(raw)) {
+        throw badRequest(`${method}: id must match ${ENDPOINT_ID_PATTERN.source}`);
+    }
+    return raw;
+}
+function parseText(raw, field, max) {
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > max || CONTROL_CHARS.test(raw)) {
+        throw badRequest(`endpoints.register: ${field} must be a non-empty string of at most ${max} characters, without control characters`);
+    }
+    return raw.trim();
+}
+function parsePositiveInteger(raw, field) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw <= 0) {
+        throw badRequest(`endpoints.register: ${field} must be a positive integer when present`);
+    }
+    return raw;
+}
+function parseRegisterParams(params) {
+    const raw = strictParams(params, 'endpoints.register', REGISTER_SHAPE, REGISTER_KEYS);
+    const id = parseEndpointId(raw.id, 'endpoints.register');
+    const label = parseText(raw.label, 'label', MAX_LABEL_CHARS);
+    if (typeof raw.engine !== 'string' || !ENDPOINT_ENGINES.includes(raw.engine)) {
+        throw badRequest(`endpoints.register: engine must be one of ${ENDPOINT_ENGINES.join(', ')}`);
+    }
+    const engine = raw.engine;
+    if (typeof raw.baseUrl !== 'string' || Buffer.byteLength(raw.baseUrl, 'utf8') > MAX_ENDPOINT_URL_BYTES) {
+        throw badRequest(`endpoints.register: baseUrl must be a string of at most ${MAX_ENDPOINT_URL_BYTES} bytes`);
+    }
+    if (typeof raw.apiKey !== 'string' ||
+        raw.apiKey === '' ||
+        Buffer.byteLength(raw.apiKey, 'utf8') > MAX_API_KEY_BYTES ||
+        WHITESPACE_OR_CONTROL.test(raw.apiKey)) {
+        throw badRequest(`endpoints.register: apiKey is required — a string of at most ${MAX_API_KEY_BYTES} bytes, without whitespace or control characters`);
+    }
+    const model = parseText(raw.model, 'model', MAX_MODEL_CHARS);
+    const contextLength = parsePositiveInteger(raw.contextLength, 'contextLength');
+    const ttlMs = Math.min(parsePositiveInteger(raw.ttlMs, 'ttlMs') ?? DEFAULT_ENDPOINT_TTL_MS, MAX_ENDPOINT_TTL_MS);
+    return {
+        id,
+        label,
+        engine,
+        baseUrl: raw.baseUrl,
+        apiKey: raw.apiKey,
+        model,
+        ...(contextLength !== undefined ? { contextLength } : {}),
+        ttlMs,
+    };
+}
+export function endpointsRegisterBouncerInput(params) {
+    const raw = typeof params === 'object' && params !== null && !Array.isArray(params) ? params : {};
+    const verdict = typeof raw.baseUrl === 'string' ? validateEndpointUrl(raw.baseUrl) : undefined;
+    return {
+        id: typeof raw.id === 'string' ? raw.id.slice(0, 32) : 'invalid',
+        engine: typeof raw.engine === 'string' ? raw.engine.slice(0, 32) : 'invalid',
+        model: typeof raw.model === 'string' ? raw.model.slice(0, MAX_MODEL_CHARS) : 'invalid',
+        host: verdict?.ok ? verdict.host : 'invalid',
+    };
+}
+function isExpiredAt(profile, now) {
+    const expiresMs = parseProfileExpiry(profile.expiresAt);
+    return expiresMs === undefined || expiresMs <= now;
+}
+function endpointIdOf(profile) {
+    return profile.id.slice(appProfileId(profile.owner.appId, '').length);
+}
+function hostOf(profile) {
+    try {
+        return profile.baseUrl ? new URL(profile.baseUrl).hostname : 'none';
+    }
+    catch {
+        return 'invalid';
+    }
+}
+function toRegisteredEndpoint(profile) {
+    return {
+        id: endpointIdOf(profile),
+        label: profile.label,
+        engine: profile.engine,
+        modelValue: profileModelValue(profile),
+        model: profile.model,
+        ...(profile.contextLength !== undefined ? { contextLength: profile.contextLength } : {}),
+        expiresAt: profile.expiresAt,
+    };
+}
+function auditFields(profile) {
+    return `id=${endpointIdOf(profile)} engine=${profile.engine} model=${profile.model} host=${hostOf(profile)}`;
+}
+function retireEndpoints(profiles, cause) {
+    for (const profile of profiles) {
+        const { appId, spaceKey } = profile.owner;
+        const cancelled = cancelRunsForModel(appId, spaceKey, profileModelValue(profile));
+        logAppAudit({
+            appId,
+            origin: '',
+            method: 'endpoints.removed',
+            decision: 'allow',
+            requestId: randomUUID(),
+            spaceKey,
+            reason: `endpoints.removed ${auditFields(profile)} (${cause})${cancelled > 0 ? ` cancelledRuns=${cancelled}` : ''}`,
+        });
+    }
+}
+export async function endpointsRegisterHandler(args) {
+    const request = parseRegisterParams(args.params);
+    const verdict = validateEndpointUrl(request.baseUrl);
+    if (!verdict.ok) {
+        throw new SdkMethodError('ENDPOINT_INVALID', `endpoints.register: baseUrl ${verdict.reason}`);
+    }
+    await resolveAndCheck(verdict.host);
+    const owner = { appId: args.appId, spaceKey: args.spaceKey };
+    const profileId = appProfileId(args.appId, request.id);
+    const profiles = new ModelProfileStore();
+    const credentials = new ProviderCredentialStore();
+    const now = Date.now();
+    const others = listAppProfiles(profiles, owner).filter((profile) => profile.id !== profileId && !isExpiredAt(profile, now));
+    if (others.length >= MAX_ENDPOINTS_PER_APP) {
+        throw new SdkMethodError('QUOTA_EXCEEDED', `endpoints.register: this app already holds ${MAX_ENDPOINTS_PER_APP} endpoints in this Space — unregister one first`);
+    }
+    let saved;
+    try {
+        saved = profiles.save({
+            id: profileId,
+            label: request.label,
+            engine: request.engine,
+            model: request.model,
+            baseUrl: verdict.url,
+            owner,
+            expiresAt: new Date(now + request.ttlMs).toISOString(),
+            ...(request.contextLength !== undefined ? { contextLength: request.contextLength } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof ModelProfileError) {
+            throw badRequest(error.code === 'OWNER_CONFLICT'
+                ? 'endpoints.register: that id is already registered by another owner on this machine — choose another id'
+                : `endpoints.register: ${error.message}`);
+        }
+        throw new SdkMethodError('INTERNAL', 'endpoints.register: the endpoint could not be stored');
+    }
+    try {
+        credentials.setApiKey(profileCredentialId(saved.id), request.apiKey);
+    }
+    catch {
+        try {
+            credentials.remove(profileCredentialId(saved.id));
+            profiles.remove(saved.id);
+        }
+        catch {
+        }
+        throw new SdkMethodError('INTERNAL', 'endpoints.register: the endpoint key could not be stored');
+    }
+    const registered = saved;
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'endpoints.register',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `endpoints.register ${auditFields(registered)}`,
+    });
+    return toRegisteredEndpoint(registered);
+}
+export function endpointsUnregisterHandler(args) {
+    const raw = strictParams(args.params, 'endpoints.unregister', '{ id }', UNREGISTER_KEYS);
+    const id = parseEndpointId(raw.id, 'endpoints.unregister');
+    const owner = { appId: args.appId, spaceKey: args.spaceKey };
+    const profileId = appProfileId(args.appId, id);
+    const profiles = new ModelProfileStore();
+    const profile = listAppProfiles(profiles, owner).find((candidate) => candidate.id === profileId);
+    if (!profile) {
+        throw badRequest(`unknown endpoint id '${id}' — endpoints.unregister removes only this app's endpoints in this Space`);
+    }
+    new ProviderCredentialStore().remove(profileCredentialId(profile.id));
+    profiles.remove(profile.id);
+    const cancelled = cancelRunsForModel(args.appId, args.spaceKey, profileModelValue(profile));
+    logAppAudit({
+        appId: args.appId,
+        origin: args.origin,
+        method: 'endpoints.unregister',
+        decision: 'allow',
+        requestId: args.requestId,
+        spaceKey: args.spaceKey,
+        reason: `endpoints.unregister ${auditFields(profile)}${cancelled > 0 ? ` cancelledRuns=${cancelled}` : ''}`,
+    });
+    return null;
+}
+export function endpointsListHandler(args) {
+    const now = Date.now();
+    return listAppProfiles(new ModelProfileStore(), { appId: args.appId, spaceKey: args.spaceKey })
+        .filter((profile) => !isExpiredAt(profile, now))
+        .map(toRegisteredEndpoint);
+}
+export function removeAppEndpoints(appId, spaceKey, cause) {
+    const profiles = new ModelProfileStore();
+    const owner = { appId, spaceKey };
+    const owned = listAppProfiles(profiles, owner);
+    if (owned.length === 0)
+        return [];
+    const removed = new Set(removeAppProfiles(profiles, new ProviderCredentialStore(), owner));
+    retireEndpoints(owned.filter((profile) => removed.has(profile.id)), cause);
+    return [...removed];
+}
+export function reapExpiredAppEndpoints() {
+    try {
+        const profiles = new ModelProfileStore();
+        const owned = new Map(profiles
+            .list()
+            .filter(isAppOwnedProfile)
+            .map((profile) => [profile.id, profile]));
+        const removed = purgeExpiredAppProfiles(profiles, new ProviderCredentialStore(), Date.now());
+        retireEndpoints(removed.map((id) => owned.get(id)).filter((profile) => profile !== undefined), 'expired');
+        return removed;
+    }
+    catch (error) {
+        console.error('[SdkEndpoints] expired-endpoint sweep failed:', error instanceof Error ? error.message : error);
+        return [];
+    }
+}
+let reaperTimer = null;
+export function startAppEndpointReaper() {
+    if (reaperTimer)
+        return;
+    reapExpiredAppEndpoints();
+    reaperTimer = setInterval(reapExpiredAppEndpoints, ENDPOINT_REAPER_INTERVAL_MS);
+    reaperTimer.unref();
+}
+export function stopAppEndpointReaper() {
+    if (!reaperTimer)
+        return;
+    clearInterval(reaperTimer);
+    reaperTimer = null;
+}

package/dist/server/services/sdk/file-change-notify.js

@@ -0,0 +1,36 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { realpathSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+const listeners = new Set();
+export function registerFileChangeListener(spaceKey, root, cb) {
+    const listener = { spaceKey, root, cb };
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function notifyFileChangedAbsolute(spaceKey, absolutePath, kind) {
+    for (const listener of listeners) {
+        if (listener.spaceKey !== spaceKey)
+            continue;
+        if (absolutePath !== listener.root && !absolutePath.startsWith(listener.root + sep))
+            continue;
+        listener.cb({ path: relative(listener.root, absolutePath), kind });
+    }
+}
+export function notifyFileChanged(spaceKey, workingDir, path, kind) {
+    if (listeners.size === 0)
+        return;
+    let absolute;
+    try {
+        absolute = realpathSync(path.startsWith('/') ? path : join(workingDir, path));
+    }
+    catch {
+        return;
+    }
+    notifyFileChangedAbsolute(spaceKey, absolute, kind);
+}
+export function resetFileChangeListeners() {
+    listeners.clear();
+}

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

@@ -0,0 +1,163 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute } from 'node:path';
+import { createDirectory, renameFile } from '../files.js';
+import { readFileContent } from '../websocket/file-utils.js';
+import { SdkMethodError } from './registry.js';
+import { provisionAppSandbox, resolveWithinRoot } from './sandbox.js';
+export const FILES_APP_MAX_WRITE_BYTES = 5 * 1024 * 1024;
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function parsePathParam(params, method) {
+    const raw = paramsObject(params);
+    if (typeof raw.path !== 'string' || raw.path === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { path } — a non-empty string relative to the app data dir ('.' is the root)`);
+    }
+    return raw.path;
+}
+function notFound(path) {
+    return new SdkMethodError('BAD_REQUEST', `'${path}' not found in the app data dir`);
+}
+function parseRenameParams(params, method) {
+    const raw = paramsObject(params);
+    if (typeof raw.path !== 'string' || raw.path === '' || typeof raw.newPath !== 'string' || raw.newPath === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { path, newPath } — non-empty strings relative to the app data dir`);
+    }
+    return { path: raw.path, newPath: raw.newPath };
+}
+function serviceError(error) {
+    const message = error ?? 'file operation failed';
+    return /denied|dangerous|invalid path/i.test(message)
+        ? new SdkMethodError('SCOPE_DENIED', message)
+        : new SdkMethodError('BAD_REQUEST', message);
+}
+export function appDataDir(args) {
+    try {
+        return provisionAppSandbox(args.workingDir, args.appId).dataDir;
+    }
+    catch (error) {
+        throw new SdkMethodError('INTERNAL', `app sandbox unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function guardAppDataPath(dataDir, path) {
+    if (isAbsolute(path)) {
+        throw new SdkMethodError('SCOPE_DENIED', 'Access denied: absolute paths are not allowed — app file paths are relative to the app data dir');
+    }
+    const guarded = resolveWithinRoot(dataDir, path);
+    if (!guarded.valid) {
+        throw new SdkMethodError('SCOPE_DENIED', guarded.error ?? 'Access denied: path is outside the app sandbox');
+    }
+    return guarded.resolvedPath;
+}
+function statOrUndefined(resolved) {
+    try {
+        return statSync(resolved);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function filesReadHandler(args) {
+    const path = parsePathParam(args.params, args.method);
+    const resolved = guardAppDataPath(appDataDir(args), path);
+    const stat = statOrUndefined(resolved);
+    if (!stat)
+        throw notFound(path);
+    if (stat.isDirectory()) {
+        throw new SdkMethodError('BAD_REQUEST', `'${path}' is a directory — files.read reads files (use files.list)`);
+    }
+    return readFileSync(resolved, 'utf-8');
+}
+export function filesReadEntryHandler(args) {
+    const path = parsePathParam(args.params, args.method);
+    const dataDir = appDataDir(args);
+    const resolved = guardAppDataPath(dataDir, path);
+    const stat = statOrUndefined(resolved);
+    if (!stat)
+        throw notFound(path);
+    if (stat.isDirectory()) {
+        throw new SdkMethodError('BAD_REQUEST', `'${path}' is a directory — files.readEntry reads files (use files.list)`);
+    }
+    const result = readFileContent(resolved, dataDir);
+    if (result.error)
+        throw serviceError(result.error);
+    return result.isImage
+        ? { kind: 'binary', content: result.content, mimeType: result.mimeType ?? 'application/octet-stream' }
+        : { kind: 'text', content: result.content };
+}
+export function filesWriteHandler(args) {
+    const path = parsePathParam(args.params, args.method);
+    const raw = paramsObject(args.params);
+    if (typeof raw.content !== 'string') {
+        throw new SdkMethodError('BAD_REQUEST', `${args.method} requires params { path, content } with string content`);
+    }
+    const bytes = Buffer.byteLength(raw.content, 'utf-8');
+    if (bytes > FILES_APP_MAX_WRITE_BYTES) {
+        throw new SdkMethodError('BAD_REQUEST', `content is ${bytes} bytes — exceeds the ${FILES_APP_MAX_WRITE_BYTES}-byte per-file files.write cap`);
+    }
+    const resolved = guardAppDataPath(appDataDir(args), path);
+    if (statOrUndefined(resolved)?.isDirectory()) {
+        throw new SdkMethodError('BAD_REQUEST', `'${path}' is a directory — cannot write over it`);
+    }
+    mkdirSync(dirname(resolved), { recursive: true });
+    writeFileSync(resolved, raw.content, 'utf-8');
+    return null;
+}
+export function filesListHandler(args) {
+    const path = parsePathParam(args.params, args.method);
+    const resolved = guardAppDataPath(appDataDir(args), path);
+    const stat = statOrUndefined(resolved);
+    if (!stat)
+        throw notFound(path);
+    if (!stat.isDirectory()) {
+        throw new SdkMethodError('BAD_REQUEST', `'${path}' is not a directory — files.list lists directories`);
+    }
+    return readdirSync(resolved, { withFileTypes: true })
+        .map((entry) => {
+        const isDir = entry.isDirectory();
+        const entryStat = statOrUndefined(`${resolved}/${entry.name}`);
+        return {
+            name: entry.name,
+            dir: isDir,
+            kind: isDir ? 'directory' : 'file',
+            size: !isDir && entryStat ? entryStat.size : undefined,
+            modifiedAt: entryStat ? entryStat.mtime.toISOString() : undefined,
+        };
+    })
+        .sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1));
+}
+export function filesDeleteHandler(args) {
+    const path = parsePathParam(args.params, args.method);
+    const dataDir = appDataDir(args);
+    const resolved = guardAppDataPath(dataDir, path);
+    if (resolved === dataDir) {
+        throw new SdkMethodError('BAD_REQUEST', 'cannot delete the app data root');
+    }
+    if (!statOrUndefined(resolved))
+        throw notFound(path);
+    rmSync(resolved, { recursive: true });
+    return null;
+}
+export function filesMkdirHandler(args) {
+    const path = parsePathParam(args.params, args.method);
+    const dataDir = appDataDir(args);
+    const resolved = guardAppDataPath(dataDir, path);
+    const result = createDirectory(resolved, dataDir);
+    if (!result.success)
+        throw serviceError(result.error);
+    return null;
+}
+export function filesRenameHandler(args) {
+    const { path, newPath } = parseRenameParams(args.params, args.method);
+    const dataDir = appDataDir(args);
+    const resolvedOld = guardAppDataPath(dataDir, path);
+    const resolvedNew = guardAppDataPath(dataDir, newPath);
+    const result = renameFile(resolvedOld, resolvedNew, dataDir);
+    if (!result.success)
+        throw serviceError(result.error);
+    return null;
+}

package/dist/server/services/sdk/files-search.js

@@ -0,0 +1,131 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { statSync } from 'node:fs';
+import { findDefinitions } from '../websocket/file-definition-handlers.js';
+import { streamRgSearch } from '../websocket/file-search-handlers.js';
+import { registerFileChangeListener } from './file-change-notify.js';
+import { appDataDir, guardAppDataPath } from './files-app.js';
+import { guardWorkspacePath, parseWorkspacePath, resolveFilesReadScopes } from './files-workspace.js';
+import { getGrant } from './grant-store.js';
+import { listLiveSubscriptions, registerLiveSubscription } from './live-registry.js';
+import { SdkMethodError } from './registry.js';
+import { dropSubscription } from './revoke.js';
+export { resolveFilesReadScopes as resolveFilesSearchScopes };
+function paramsObject(params) {
+    return typeof params === 'object' && params !== null && !Array.isArray(params)
+        ? params
+        : {};
+}
+function requireStringParam(raw, name, method) {
+    const value = raw[name];
+    if (typeof value !== 'string' || value === '') {
+        throw new SdkMethodError('BAD_REQUEST', `${method} requires params { ${name} } — a non-empty string`);
+    }
+    return value;
+}
+function resolveFilesRoot(args, path) {
+    const target = parseWorkspacePath({ path });
+    const resolved = target === null ? guardAppDataPath(appDataDir(args), path) : guardWorkspacePath(args.workingDir, target.rel).resolvedPath;
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch {
+        throw new SdkMethodError('BAD_REQUEST', `'${path}' not found`);
+    }
+    if (!stat.isDirectory()) {
+        throw new SdkMethodError('BAD_REQUEST', `'${path}' is not a directory`);
+    }
+    return resolved;
+}
+function refuseDuplicateStream(args) {
+    if (listLiveSubscriptions().some((sub) => sub.requestId === args.requestId)) {
+        throw new SdkMethodError('BAD_REQUEST', `requestId '${args.requestId}' already holds a live subscription`);
+    }
+}
+function subscriptionViewerId(args) {
+    return getGrant(args.appId, args.spaceKey) ? undefined : args.viewerId;
+}
+function toWireMatch(match) {
+    return {
+        path: match.filePath,
+        line: match.line,
+        column: match.column,
+        lineContent: match.lineContent,
+        contextBefore: match.contextBefore,
+        contextAfter: match.contextAfter,
+    };
+}
+function parseSearchOptions(raw) {
+    return typeof raw.options === 'object' && raw.options !== null && !Array.isArray(raw.options)
+        ? raw.options
+        : {};
+}
+export function filesSearchHandler(args) {
+    const raw = paramsObject(args.params);
+    const path = requireStringParam(raw, 'path', args.method);
+    const query = requireStringParam(raw, 'query', args.method);
+    const options = parseSearchOptions(raw);
+    const root = resolveFilesRoot(args, path);
+    refuseDuplicateStream(args);
+    const sub = {
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'files.search',
+        viewerId: subscriptionViewerId(args),
+        teardown: () => handle.cancel(),
+    };
+    const handle = streamRgSearch(query, options, root, {
+        onBatch: (matches) => args.emit('results', { matches: matches.map(toWireMatch) }),
+        onComplete: (stats) => {
+            args.emit('complete', { totalMatches: stats.totalMatches, fileCount: stats.fileCount, truncated: stats.truncated });
+            dropSubscription(sub, 'files.search.complete', 'search finished');
+        },
+        onError: (message) => {
+            args.emit('complete', { totalMatches: 0, fileCount: 0, truncated: false, error: message });
+            dropSubscription(sub, 'files.search.complete', `search failed: ${message}`);
+        },
+    });
+    registerLiveSubscription(sub);
+    return null;
+}
+function toWireDefinition(entry) {
+    return { path: entry.filePath, line: entry.line, column: entry.column, lineContent: entry.lineContent, kind: entry.kind };
+}
+export async function filesDefinitionHandler(args) {
+    const raw = paramsObject(args.params);
+    const path = requireStringParam(raw, 'path', args.method);
+    const symbolName = requireStringParam(raw, 'symbolName', args.method);
+    const language = typeof raw.language === 'string' && raw.language !== '' ? raw.language : 'typescript';
+    const currentFile = typeof raw.currentFile === 'string' ? raw.currentFile : '';
+    const root = resolveFilesRoot(args, path);
+    const definitions = await findDefinitions(symbolName, language, currentFile, root);
+    return definitions.map(toWireDefinition);
+}
+export function filesSubscribeChangesHandler(args) {
+    const raw = paramsObject(args.params);
+    const path = requireStringParam(raw, 'path', args.method);
+    const root = resolveFilesRoot(args, path);
+    refuseDuplicateStream(args);
+    let active = true;
+    const unsubscribe = registerFileChangeListener(args.spaceKey, root, (change) => {
+        if (!active)
+            return;
+        args.emit('changed', change);
+    });
+    registerLiveSubscription({
+        requestId: args.requestId,
+        appId: args.appId,
+        origin: args.origin,
+        spaceKey: args.spaceKey,
+        kind: 'files.subscribeChanges',
+        viewerId: subscriptionViewerId(args),
+        teardown: () => {
+            active = false;
+            unsubscribe();
+        },
+    });
+    return { subscribed: true };
+}