@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/dist/platform/coordination-lock.js

@@ -0,0 +1,233 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { processBirth, processNamespace, sameProcessNamespace } from './process-identity.js';
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const failure = (code, message, details = {}) => Object.assign(new Error(message), { code, ...details });
+export async function coordinationObservation(filename) {
+    let stat;
+    try {
+        stat = await fs.lstat(filename);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw failure('COORDINATION_PATH_UNSAFE', 'Coordination path is not an ordinary file.', { path: filename });
+    let body;
+    if (stat.size <= 4096) {
+        try {
+            const parsed = JSON.parse(await fs.readFile(filename, 'utf8'));
+            if (Number.isSafeInteger(parsed.pid) && parsed.pid > 0 && typeof parsed.token === 'string' && parsed.token) {
+                body = { pid: parsed.pid, token: parsed.token, ...(Number.isFinite(parsed.createdAt) ? { createdAt: parsed.createdAt } : {}),
+                    ...(typeof parsed.processBirth === 'string' && parsed.processBirth.length <= 256 ? { processBirth: parsed.processBirth } : {}),
+                    ...(parsed.namespace && typeof parsed.namespace.platform === 'string' && typeof parsed.namespace.hostname === 'string' ? { namespace: parsed.namespace } : {}) };
+            }
+        }
+        catch { }
+    }
+    return { body, ageMs: Math.max(0, Date.now() - stat.mtimeMs), mtimeMs: stat.mtimeMs, size: stat.size };
+}
+export function processAppearsDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+export async function coordinationOwnerAbandoned(body) {
+    if (!await sameProcessNamespace(body.namespace))
+        return false;
+    if (processAppearsDead(body.pid))
+        return true;
+    if (!body.processBirth)
+        return false;
+    const actual = await processBirth(body.pid);
+    return actual !== null && actual !== body.processBirth;
+}
+export async function createCoordinationLock(filename, token = randomUUID()) {
+    await fs.mkdir(path.dirname(filename), { recursive: true });
+    const [birth, namespace] = await Promise.all([processBirth(process.pid), processNamespace()]);
+    const body = JSON.stringify({ pid: process.pid, token, createdAt: Date.now(), ...(birth ? { processBirth: birth } : {}), ...(namespace ? { namespace } : {}) }) + '\n';
+    const claim = filename + '.claim-' + token;
+    let handle, linked = false, direct = false;
+    try {
+        handle = await fs.open(claim, 'wx', 0o600);
+        await handle.writeFile(body);
+        await handle.sync();
+        try {
+            await fs.link(claim, filename);
+            linked = true;
+            await fs.unlink(claim);
+            return { handle, token };
+        }
+        catch (error) {
+            const code = error.code;
+            if (!['EPERM', 'EXDEV', 'ENOTSUP', 'EOPNOTSUPP', 'EINVAL'].includes(String(code)))
+                throw error;
+            await handle.close();
+            handle = undefined;
+            await fs.rm(claim, { force: true });
+            try {
+                handle = await fs.open(filename, 'wx', 0o600);
+                direct = true;
+            }
+            catch (openError) {
+                const openCode = String(openError.code);
+                // The claim file was created in this directory, so EPERM/EACCES on the
+                // target itself is Windows file contention/pending deletion, not a
+                // directory permission failure. Surface it as ordinary lock busy so the
+                // caller follows the existing bounded retry/recovery path.
+                if (process.platform === 'win32' && ['EPERM', 'EACCES'].includes(openCode)) {
+                    openError.code = 'EEXIST';
+                }
+                throw openError;
+            }
+            try {
+                await handle.writeFile(body);
+                await handle.sync();
+                return { handle, token };
+            }
+            catch (writeError) {
+                await handle.close();
+                handle = undefined;
+                await fs.unlink(filename).catch(() => { });
+                throw writeError;
+            }
+        }
+    }
+    catch (error) {
+        if (handle)
+            await handle.close().catch(() => { });
+        if (linked) {
+            const current = await coordinationObservation(filename).catch(() => null);
+            if (current?.body?.token === token)
+                await fs.unlink(filename).catch(() => { });
+        }
+        if (direct)
+            await fs.unlink(filename).catch(() => { });
+        await fs.rm(claim, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+export async function releaseCoordinationLock(lock, filename) {
+    await lock.handle.close();
+    try {
+        const current = await coordinationObservation(filename);
+        if (current?.body?.token === lock.token)
+            await fs.unlink(filename);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+async function recoverObserved(lockPath, recoveryPath, observed, options, allowIncomplete, depth = 0) {
+    const recoveryToken = randomUUID();
+    let recovery;
+    try {
+        recovery = await createCoordinationLock(recoveryPath, recoveryToken);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Recovery is itself crashable. Serialize reclamation of its abandoned
+        // generation with another guard, never an unguarded read-then-unlink.
+        // Unknown/incomplete guards remain fail-closed, including explicit repair.
+        if (depth >= 8)
+            return false;
+        const guard = await coordinationObservation(recoveryPath);
+        if (!guard?.body || !await coordinationOwnerAbandoned(guard.body))
+            return false;
+        if (!await recoverObserved(recoveryPath, recoveryPath + '.recovery', guard, options, false, depth + 1))
+            return false;
+        try {
+            recovery = await createCoordinationLock(recoveryPath, recoveryToken);
+        }
+        catch (retry) {
+            if (retry.code === 'EEXIST')
+                return false;
+            throw retry;
+        }
+    }
+    try {
+        const current = await coordinationObservation(lockPath);
+        if (!current)
+            return true;
+        const same = current.mtimeMs === observed.mtimeMs && current.size === observed.size
+            && current.body?.token === observed.body?.token && current.body?.pid === observed.body?.pid && current.body?.processBirth === observed.body?.processBirth
+            && JSON.stringify(current.body?.namespace) === JSON.stringify(observed.body?.namespace);
+        if (!same)
+            return false;
+        if (current.body) {
+            if (!await coordinationOwnerAbandoned(current.body))
+                return false;
+        }
+        else if (!allowIncomplete || current.ageMs < (options.staleMs ?? 5000))
+            return false;
+        const abandoned = lockPath + '.abandoned-' + randomUUID();
+        if (options.retainAbandoned !== false)
+            await fs.rename(lockPath, abandoned);
+        else
+            await fs.unlink(lockPath);
+        return true;
+    }
+    finally {
+        await releaseCoordinationLock(recovery, recoveryPath);
+    }
+}
+export async function repairCoordinationLock(lockPath, options) {
+    const observed = await coordinationObservation(lockPath);
+    if (!observed)
+        return { recovered: false, reason: 'absent' };
+    if (observed.body && !await coordinationOwnerAbandoned(observed.body))
+        throw failure(options.codes.active, (options.messagePrefix ?? 'Coordination') + ' owner is live or cannot be proved abandoned.', { path: lockPath, pid: observed.body.pid });
+    if (!observed.body && observed.ageMs < (options.staleMs ?? 5000))
+        throw failure(options.codes.active, (options.messagePrefix ?? 'Coordination') + ' lock may still be initializing.', { path: lockPath });
+    const ok = await recoverObserved(lockPath, lockPath + '.recovery', observed, options, true);
+    if (!ok)
+        throw failure(options.codes.recoveryRequired, (options.messagePrefix ?? 'Coordination') + ' ownership changed during recovery.', { path: lockPath });
+    return { recovered: true };
+}
+export async function withCoordinationLock(lockPath, work, options) {
+    const recoveryPath = lockPath + '.recovery';
+    if (options.breakLock)
+        await repairCoordinationLock(lockPath, options).catch(error => { if (error.reason === 'absent')
+            return; throw error; });
+    let lock;
+    const attempts = options.nonBlocking ? 1 : (options.attempts ?? 200);
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            lock = await createCoordinationLock(lockPath);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const prior = await coordinationObservation(lockPath);
+            if (!prior)
+                continue;
+            if (prior.body && await coordinationOwnerAbandoned(prior.body)) {
+                if (await recoverObserved(lockPath, recoveryPath, prior, options, false))
+                    continue;
+            }
+            if (!prior.body && prior.ageMs >= (options.staleMs ?? 5000))
+                throw failure(options.codes.recoveryRequired, (options.messagePrefix ?? 'Coordination') + ' has an incomplete old lock; explicit recovery is required.', { path: lockPath });
+            if (options.nonBlocking)
+                throw failure(options.codes.busy, (options.messagePrefix ?? 'Coordination') + ' is busy.', { path: lockPath });
+            await sleep(10);
+        }
+    }
+    if (!lock)
+        throw failure(options.codes.busy, (options.messagePrefix ?? 'Coordination') + ' is busy or uninspectable.', { path: lockPath });
+    try {
+        return await work();
+    }
+    finally {
+        await releaseCoordinationLock(lock, lockPath);
+    }
+}

package/dist/platform/device-runtime.d.ts

@@ -0,0 +1,16 @@
+import { type DeviceCore, type DeviceCoreOptions } from '../device/core.js';
+import { PluginHost } from './plugin-host.js';
+import { type Capability } from './plugin-contract.js';
+import type { DevicePluginPolicy } from './plugin-policy.js';
+export interface PlatformDeviceCore extends DeviceCore {
+    readonly plugins: PluginHost;
+    readonly capabilityContracts: Capability[];
+    onCapabilitiesChanged(listener: () => void): () => void;
+}
+export declare function createPlatformDeviceCore(options: DeviceCoreOptions & {
+    projectRoots?: string[];
+    sourceRoots?: string[];
+    bundledPlugins?: boolean;
+    pluginPolicy?: DevicePluginPolicy;
+    exposeKnowledgeMcp?: boolean;
+}): Promise<PlatformDeviceCore>;

package/dist/platform/device-runtime.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { createDeviceCore } from '../device/core.js';
+import { PluginHost } from './plugin-host.js';
+import { ActivityJournal } from './activity-journal.js';
+import { compatible, CapabilityError } from './plugin-contract.js';
+export async function createPlatformDeviceCore(options) {
+    const core = await createDeviceCore(options);
+    const activity = new ActivityJournal(core.stateRoot, core.deviceId, core.runtimeInstanceId);
+    const plugins = new PluginHost({ stateRoot: core.stateRoot, deviceId: core.deviceId, projectRoots: options.projectRoots ?? options.allowedRoots ?? [], sourceRoots: options.sourceRoots ?? [path.join(core.stateRoot, 'logs')] });
+    try {
+        // Core never provisions optional plugins. Legacy distribution-enabled Palace
+        // needs one explicit enable; manual installs and explicit intent are durable.
+        await plugins.start({ skipIds: ['palace'] });
+    }
+    catch (error) {
+        process.stderr.write(`[plugins] Native Device Core remains available: ${error.message}\n`);
+    }
+    let closed = false;
+    let closeRequest;
+    const pluginContracts = () => plugins.list().filter(record => record.installed && record.enabled && record.state === 'enabled').flatMap(record => record.manifest.capabilities).filter(capability => plugins.capabilities().includes(capability.name) && ['provider', 'fallback'].includes(capability.role ?? 'provider'));
+    const advertised = () => pluginContracts().filter(capability => !capability.name.startsWith('knowledge.') ? true : options.exposeKnowledgeMcp !== false && compatible(capability.version, '^1.0.0'));
+    const contracts = () => closed ? [] : [...core.capabilities.map(name => ({ name, version: '1.0.0' })), { name: 'platform.capabilities', version: '1.0.0' }, { name: 'platform.invoke', version: '1.0.0' }, ...pluginContracts()];
+    return {
+        deviceId: core.deviceId, stateRoot: core.stateRoot, runtimeInstanceId: core.runtimeInstanceId, plugins,
+        get capabilities() { return closed ? [] : [...new Set([...core.capabilities, 'platform.capabilities', 'platform.invoke', ...advertised().map(capability => capability.name)])]; },
+        get capabilityContracts() { return contracts().filter(capability => options.exposeKnowledgeMcp !== false || !capability.name.startsWith('knowledge.')); },
+        onCapabilitiesChanged: listener => plugins.onCapabilitiesChanged(listener),
+        async invoke(tool, args = {}) {
+            if (closed)
+                throw Object.assign(new Error('Device runtime is closed'), { code: 'DEVICE_NOT_READY' });
+            if (tool === 'platform.capabilities')
+                return { deviceId: core.deviceId, contracts: contracts().filter(capability => options.exposeKnowledgeMcp !== false || !capability.name.startsWith('knowledge.')) };
+            if (tool === 'platform.invoke') {
+                const request = args;
+                if (typeof request.name !== 'string' || request.name.length > 96 || (request.version !== undefined && (typeof request.version !== 'string' || request.version.length > 64)))
+                    throw new CapabilityError('INVALID_ARGUMENT', 'A capability name and optional compatible contract version are required');
+                return plugins.invoke(request.name, request.input ?? {}, { version: request.version });
+            }
+            if (plugins.capabilities().includes(tool))
+                return plugins.invoke(tool, args, { version: tool.startsWith('knowledge.') ? '^1.0.0' : undefined });
+            try {
+                const result = await core.invoke(tool, args);
+                activity.record(tool, args, result);
+                return result;
+            }
+            catch (error) {
+                activity.record(tool, args, undefined, error);
+                throw error;
+            }
+        },
+        async invokeNative(tool, args = {}) {
+            try {
+                const result = await core.invokeNative(tool, args);
+                activity.record(tool, args, result);
+                return result;
+            }
+            catch (error) {
+                activity.record(tool, args, undefined, error);
+                throw error;
+            }
+        },
+        close() {
+            closed = true;
+            if (!closeRequest)
+                closeRequest = (async () => {
+                    const failures = [];
+                    for (const close of [() => plugins.close(), () => activity.close(), () => core.close()]) {
+                        try {
+                            await close();
+                        }
+                        catch (error) {
+                            failures.push(error);
+                        }
+                    }
+                    if (failures.length)
+                        throw failures[0];
+                })().catch(error => { closeRequest = undefined; throw error; });
+            // A failed cleanup stays observable. Retrying performs real cleanup again;
+            // disabling invocation alone is never evidence that resources were freed.
+            return closeRequest;
+        }
+    };
+}

package/dist/platform/knowledge-contract.d.ts

@@ -0,0 +1,46 @@
+/** Platform exchange contract. No knowledge provider package is imported here. */
+export interface KnowledgeScope {
+    projectId?: string;
+    visibility: 'project' | 'account' | 'local';
+}
+export type KnowledgeStatus = 'hypothesis' | 'observed' | 'validated' | 'stale' | 'superseded' | 'withdrawn';
+export interface KnowledgeEvidence {
+    id: string;
+    originDeviceId: string;
+    sourceId: string;
+    sourceRef: string;
+    recordHash: string;
+    kind: 'source_trace' | 'tool_receipt' | 'postcondition';
+    sourceAvailable: boolean;
+    observedAt: number;
+}
+export interface KnowledgeCard {
+    id: string;
+    version: number;
+    contentHash: string;
+    summary: string;
+    body: string;
+    status: KnowledgeStatus;
+    originDeviceId: string;
+    servingDeviceId: string;
+    scope: KnowledgeScope;
+    evidence: KnowledgeEvidence[];
+    derivedFrom: string[];
+    provenance: string[];
+    updatedAt: number;
+    lastVerifiedAt: number | null;
+}
+export interface KnowledgePreview {
+    id: string;
+    version: number;
+    contentHash: string;
+    summary: string;
+    status: KnowledgeStatus;
+    originDeviceId: string;
+    servingDeviceId: string;
+    scope: KnowledgeScope;
+    read_ref: string;
+    evidenceCount: number;
+    lastVerifiedAt: number | null;
+}
+export declare const KNOWLEDGE_CONTRACT_VERSION = "1.0.0";

package/dist/platform/knowledge-contract.js

@@ -0,0 +1 @@
+export const KNOWLEDGE_CONTRACT_VERSION = '1.0.0';

package/dist/platform/knowledge-mcp.d.ts

@@ -0,0 +1,29 @@
+interface BrokerDevice {
+    deviceId: string;
+    online: boolean;
+    capabilities: string[];
+    projects?: string[];
+    lastSeenAt?: number;
+    latencyMs?: number;
+}
+export interface TrustedToolContext {
+    accountId: string;
+    sessionId: string;
+    listDevices(): BrokerDevice[] | Promise<BrokerDevice[]>;
+    callDevice(options: {
+        deviceId: string;
+        tool: string;
+        arguments: Record<string, unknown>;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+}
+export interface PlatformTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: Record<string, boolean>;
+    handler(args: Record<string, any>, context: TrustedToolContext): Promise<unknown>;
+}
+/** All owner and caller policy checks still flow through the authenticated wrapper. */
+export declare function createPlatformTools(stateRoot: string): Promise<PlatformTool[]>;
+export {};

package/dist/platform/knowledge-mcp.js

@@ -0,0 +1,95 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { KnowledgeRouter, unwrapKnowledgeResult } from './knowledge-router.js';
+import { CapabilityError } from './plugin-contract.js';
+/** The key is runtime state, so references survive restart and verified restore. */
+async function referenceKey(stateRoot) {
+    await fs.mkdir(stateRoot, { recursive: true });
+    const filename = path.join(stateRoot, 'knowledge-reference.key');
+    try {
+        await fs.writeFile(filename, randomBytes(32), { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const key = await fs.readFile(filename);
+    if (key.length !== 32)
+        throw new CapabilityError('KNOWLEDGE_KEY_INVALID', 'Persisted knowledge reference key is invalid; restore the original key');
+    return key;
+}
+/** All owner and caller policy checks still flow through the authenticated wrapper. */
+export async function createPlatformTools(stateRoot) {
+    const requests = new AsyncLocalStorage();
+    const trusted = (accountId) => {
+        const context = requests.getStore();
+        if (!context || !context.accountId || context.accountId !== accountId)
+            throw new CapabilityError('AUTH_REQUIRED', 'An authenticated account context is required');
+        return context;
+    };
+    const router = new KnowledgeRouter({
+        async devices(accountId) {
+            return (await trusted(accountId).listDevices()).map(device => ({ ...device, accountId }));
+        },
+        call: (accountId, deviceId, capability, input) => trusted(accountId).callDevice({ deviceId, tool: capability, arguments: input, timeoutMs: 30000 })
+    }, { secret: await referenceKey(stateRoot) });
+    const properties = {
+        device_id: { type: 'string', minLength: 1, maxLength: 64, description: 'Owned Device requesting the knowledge. It may have no knowledge plugin.' },
+        project_id: { type: 'string', minLength: 1, maxLength: 512 },
+        max_bytes: { type: 'integer', minimum: 1024, maximum: 65536, default: 16384 }
+    };
+    const contextFor = (args, context) => {
+        if (!context.accountId || !context.sessionId)
+            throw new CapabilityError('AUTH_REQUIRED', 'An authenticated account and session are required');
+        return { accountId: context.accountId, sessionId: context.sessionId, requesterDeviceId: args.device_id };
+    };
+    const tools = ['search', 'list'].map(action => ({
+        name: 'knowledge.' + action,
+        description: action === 'search' ? 'Search compact knowledge previews across an account’s relevant available Devices. Does not import knowledge.' : 'List scoped knowledge previews on relevant available Devices. Does not import knowledge.',
+        inputSchema: { type: 'object', additionalProperties: false, required: action === 'search' ? ['device_id', 'query'] : ['device_id'], properties: { ...properties, query: { type: 'string', maxLength: 4096 }, limit: { type: 'integer', minimum: 1, maximum: 50, default: 10 }, provider_device_id: { type: 'string', minLength: 1, maxLength: 64 } } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+        handler: (args, context) => requests.run(context, () => router.search(contextFor(args, context), { query: args.query, projectId: args.project_id, limit: args.limit, maxBytes: args.max_bytes, providerDeviceId: args.provider_device_id }, action))
+    }));
+    tools.push({
+        name: 'knowledge.read',
+        description: 'Read one selected knowledge reference with provenance and freshness. Lazily import that item only when the requesting Device has a storage provider; otherwise use bounded session cache. Evidence is returned only when requested.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['device_id', 'ref'], properties: { ...properties, ref: { type: 'string', minLength: 1, maxLength: 4096 }, evidence: { type: 'boolean', default: false } } },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+        handler: (args, context) => requests.run(context, () => router.read(contextFor(args, context), { ref: args.ref, projectId: args.project_id, evidence: args.evidence, maxBytes: args.max_bytes }))
+    });
+    tools.push({
+        name: 'capability.list',
+        description: 'Discover current capabilities advertised by an owned Device. Plugin disable, crash and dependency loss remove unavailable capabilities.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['device_id'], properties: { device_id: properties.device_id } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+        async handler(args, context) {
+            if (!context.accountId)
+                throw new CapabilityError('AUTH_REQUIRED', 'An authenticated account is required');
+            const device = (await context.listDevices()).find(item => item.deviceId === args.device_id);
+            if (!device)
+                throw new CapabilityError('ACCESS_DENIED', 'Device is not owned by this account');
+            const contracts = device.online && device.capabilities.includes('platform.capabilities') ? unwrapKnowledgeResult(await context.callDevice({ deviceId: device.deviceId, tool: 'platform.capabilities', arguments: {} })).contracts : undefined;
+            return { device_id: device.deviceId, online: device.online, capabilities: device.capabilities, ...(contracts ? { contracts } : {}) };
+        }
+    }, {
+        name: 'capability.call',
+        description: 'Invoke an advertised plugin capability on an owned Device through normal caller policy. Knowledge exchange uses knowledge.search/list/read; native tools use their existing contracts.',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['device_id', 'capability', 'arguments'], properties: { device_id: properties.device_id, capability: { type: 'string', pattern: '^[a-z][a-z0-9_-]*\\.[a-z0-9_.-]+$', maxLength: 96 }, version: { type: 'string', maxLength: 64, description: 'Required compatible capability contract, such as ^1.0.0 or 1.x.' }, arguments: { type: 'object', additionalProperties: true } } },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        async handler(args, context) {
+            if (!context.accountId)
+                throw new CapabilityError('AUTH_REQUIRED', 'An authenticated account is required');
+            if (String(args.capability).startsWith('knowledge.'))
+                throw new CapabilityError('CAPABILITY_PRIVATE', 'Use the public knowledge exchange contract');
+            const device = (await context.listDevices()).find(item => item.deviceId === args.device_id);
+            if (!device)
+                throw new CapabilityError('ACCESS_DENIED', 'Device is not owned by this account');
+            if (!device.online || !device.capabilities.includes('platform.invoke') || !device.capabilities.includes(args.capability))
+                throw new CapabilityError('CAPABILITY_UNAVAILABLE', 'The Device does not advertise this plugin capability');
+            return context.callDevice({ deviceId: args.device_id, tool: 'platform.invoke', arguments: { name: args.capability, version: args.version, input: args.arguments }, timeoutMs: 30000 });
+        }
+    });
+    return tools;
+}

package/dist/platform/knowledge-router.d.ts

@@ -0,0 +1,64 @@
+export interface KnowledgeDevice {
+    deviceId: string;
+    accountId: string;
+    online: boolean;
+    capabilities: string[];
+    projects?: string[];
+    lastSeenAt?: number;
+    latencyMs?: number;
+}
+export interface KnowledgeTransport {
+    devices(accountId: string): Promise<KnowledgeDevice[]>;
+    call(accountId: string, deviceId: string, capability: string, input: unknown): Promise<unknown>;
+}
+export interface KnowledgeRequestContext {
+    accountId: string;
+    requesterDeviceId: string;
+    sessionId: string;
+}
+export declare function unwrapKnowledgeResult(value: any): any;
+/** Account-aware routing and lazy transfer live in the platform, not in a plugin. */
+export declare class KnowledgeRouter {
+    private transport;
+    private options;
+    private cache;
+    private cacheBytes;
+    private revisions;
+    private readonly secret;
+    constructor(transport: KnowledgeTransport, options?: {
+        secret?: Buffer;
+        cacheBytes?: number;
+        cacheTtlMs?: number;
+        maxProviders?: number;
+        now?: () => number;
+    });
+    private now;
+    private accountTag;
+    private reference;
+    private parseReference;
+    private scope;
+    private allowed;
+    private cacheKey;
+    private pruneCache;
+    private forgetCached;
+    private rememberRevision;
+    private cacheCard;
+    cacheStats(): {
+        entries: number;
+        bytes: number;
+    };
+    private preview;
+    search(context: KnowledgeRequestContext, input: {
+        query?: string;
+        projectId?: string;
+        limit?: number;
+        maxBytes?: number;
+        providerDeviceId?: string;
+    }, action?: 'search' | 'list'): Promise<unknown>;
+    read(context: KnowledgeRequestContext, input: {
+        ref: string;
+        projectId?: string;
+        evidence?: boolean;
+        maxBytes?: number;
+    }): Promise<unknown>;
+}