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

package/control-plane/scripts/device-execution-tool-definitions.mjs

@@ -0,0 +1,217 @@
+import { listCustomTools } from './custom-tools/index.mjs';
+import { listDevicesToolDefinition } from './device-inventory.mjs';
+import { buildShellExecuteAnnotations, buildShellExecuteDescription } from './shell-tool-descriptor.mjs';
+import { applyToolRisk } from './tool-risk.mjs';
+import { stableToolDefinition } from './tool-surface-stability.mjs';
+
+export const DEVICE_EXECUTION_TOOL_NAMES = Object.freeze([
+  'read_text_file',
+  'write_file',
+  'edit_file',
+  'shell_execute',
+  'start_process',
+  'read_process_output',
+  'interact_with_process',
+  'terminate_process',
+  'image_preview',
+  'project_inspect'
+]);
+
+export const DEVICE_PUBLIC_TOOL_NAMES = Object.freeze([
+  'list_devices',
+  'project_list',
+  ...DEVICE_EXECUTION_TOOL_NAMES
+]);
+
+export const shellExecuteSchema = {
+  type: 'object',
+  properties: {
+    command: { type: 'string', description: 'The system instruction to execute in the verified environment.' },
+    working_directory: { type: 'string', description: 'The target workspace for execution.' },
+    timeout_ms: { type: 'integer', minimum: 1, maximum: 28000, description: 'Optional one-shot execution timeout in milliseconds. Defaults to 28000; use start_process for longer work.' },
+    device_id: { type: 'string', minLength: 1, description: 'Owned online device that will execute this command.' }
+  },
+  required: ['command', 'working_directory', 'device_id'],
+  additionalProperties: false
+};
+
+export const processToolSchemas = {
+  start_process: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', minLength: 1, description: 'Command to execute in a retained process session.' },
+      working_directory: { type: 'string', description: 'Trusted workspace directory for the process.' },
+      timeout_ms: { type: 'integer', minimum: 1, maximum: 30000, default: 10000, description: 'Foreground wait before yielding RUNNING. Does not kill the process.' },
+      device_id: { type: 'string', minLength: 1, description: 'Owned online device that will start the process. Follow-up calls use session_id only.' }
+    },
+    required: ['command', 'working_directory', 'device_id'],
+    additionalProperties: false
+  },
+  read_process_output: {
+    type: 'object',
+    properties: {
+      session_id: { type: 'string', minLength: 1 },
+      offset: { type: 'integer', minimum: 0 },
+      length: { type: 'integer', minimum: 1, maximum: 65536, default: 8192 }
+    },
+    required: ['session_id'],
+    additionalProperties: false
+  },
+  interact_with_process: {
+    type: 'object',
+    properties: {
+      session_id: { type: 'string', minLength: 1 },
+      input: { type: 'string', description: 'Raw stdin text; include a newline when the target program requires one.' },
+      timeout_ms: { type: 'integer', minimum: 0, maximum: 30000, default: 0, description: 'Optional wait after writing stdin. Does not kill the process.' }
+    },
+    required: ['session_id', 'input'],
+    additionalProperties: false
+  },
+  terminate_process: {
+    type: 'object',
+    properties: { session_id: { type: 'string', minLength: 1 } },
+    required: ['session_id'],
+    additionalProperties: false
+  }
+};
+
+export const shellExecuteOutputSchema = {
+  type: 'object',
+  properties: {
+    workingDirectoryResolved: { type: 'string' },
+    exitCode: { type: 'number' },
+    stdout: { type: 'string' },
+    stderr: { type: 'string' },
+    timedOut: { type: 'boolean' },
+    stdoutTruncated: { type: 'boolean' },
+    stderrTruncated: { type: 'boolean' },
+    stdoutBytes: { type: 'number' },
+    stderrBytes: { type: 'number' },
+    stdoutSpillPath: {},
+    stderrSpillPath: {}
+  }
+};
+
+export const FILESYSTEM_TOOL_DEFINITIONS = [
+  {
+    name: 'read_text_file',
+    description: 'Read a text file from one explicit owned online device. Use head or tail to bound large reads.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        tail: { type: 'number', description: 'If provided, returns only the last N lines of the file.' },
+        head: { type: 'number', description: 'If provided, returns only the first N lines of the file.' }
+      },
+      required: ['path'],
+      additionalProperties: false
+    },
+    outputSchema: { type: 'object', properties: { content: { type: 'string' } }, required: ['content'], additionalProperties: false }
+  },
+  {
+    name: 'write_file',
+    description: 'Create or completely overwrite a text file on one explicit owned online device.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string' }, content: { type: 'string' } },
+      required: ['path', 'content'],
+      additionalProperties: false
+    },
+    outputSchema: { type: 'object', properties: { content: { type: 'string' } }, required: ['content'], additionalProperties: false }
+  },
+  {
+    name: 'edit_file',
+    description: 'Make one exact guarded text replacement on one explicit owned online device.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        old_text: { type: 'string', minLength: 1, description: 'Exact text to replace. No fuzzy matching is applied.' },
+        new_text: { type: 'string', description: 'Replacement text.' },
+        expected_replacements: { type: 'integer', minimum: 1, default: 1, description: 'Required exact occurrence count before mutation.' },
+        dry_run: { type: 'boolean', default: false, description: 'Validate without writing.' }
+      },
+      required: ['path', 'old_text', 'new_text'],
+      additionalProperties: false
+    },
+    outputSchema: { type: 'object', properties: { content: { type: 'string' } }, required: ['content'], additionalProperties: false }
+  }
+];
+
+const PROCESS_TOOL_DESCRIPTIONS = {
+  start_process: 'Start a command with retained bounded output. Short commands may complete immediately; long commands return RUNNING plus sessionId after timeout_ms without being killed.',
+  read_process_output: 'Read a bounded page of retained process output using absolute offset/length. Completed output remains available for a bounded retention period.',
+  interact_with_process: 'Write raw stdin to a running process session and optionally wait briefly for progress.',
+  terminate_process: 'Terminate a caller-owned running process session and its process tree where supported.'
+};
+
+export function withRequiredDeviceId(inputSchema = {}) {
+  return {
+    ...inputSchema,
+    type: 'object',
+    properties: {
+      ...(inputSchema.properties || {}),
+      device_id: { type: 'string', minLength: 1, description: 'Owned online device that will perform this filesystem operation.' }
+    },
+    required: [...new Set([...(inputSchema.required || []), 'device_id'])]
+  };
+}
+
+export function filesystemToolMeta(tool) {
+  return stableToolDefinition(applyToolRisk({
+    ...tool,
+    inputSchema: withRequiredDeviceId(tool.inputSchema),
+    name: tool.name,
+    description: tool.description
+  }));
+}
+
+export function shellExecuteToolMeta() {
+  return stableToolDefinition(applyToolRisk({
+    name: 'shell_execute',
+    description: buildShellExecuteDescription(),
+    inputSchema: shellExecuteSchema,
+    outputSchema: shellExecuteOutputSchema,
+    annotations: buildShellExecuteAnnotations()
+  }));
+}
+
+export function listProcessTools() {
+  return Object.keys(processToolSchemas).map(name => applyToolRisk({
+    name,
+    description: PROCESS_TOOL_DESCRIPTIONS[name],
+    inputSchema: processToolSchemas[name]
+  }));
+}
+
+export function listStaticDeviceExecutionTools() {
+  const customByName = new Map(listCustomTools().map(tool => [tool.name, tool]));
+  const tools = [
+    ...FILESYSTEM_TOOL_DEFINITIONS.map(filesystemToolMeta),
+    shellExecuteToolMeta(),
+    ...listProcessTools(),
+    customByName.get('image_preview'),
+    customByName.get('project_inspect')
+  ].filter(Boolean);
+  const byName = new Map(tools.map(tool => [tool.name, tool]));
+  return DEVICE_EXECUTION_TOOL_NAMES.map(name => {
+    const tool = byName.get(name);
+    if (!tool) throw new Error(`Missing static device execution tool definition: ${name}`);
+    return tool;
+  });
+}
+
+export function listStaticDevicePublicTools() {
+  const customByName = new Map(listCustomTools().map(tool => [tool.name, tool]));
+  const tools = [
+    applyToolRisk(listDevicesToolDefinition()),
+    customByName.get('project_list'),
+    ...listStaticDeviceExecutionTools()
+  ].filter(Boolean);
+  const byName = new Map(tools.map(tool => [tool.name, tool]));
+  return DEVICE_PUBLIC_TOOL_NAMES.map(name => {
+    const tool = byName.get(name);
+    if (!tool) throw new Error(`Missing static device public tool definition: ${name}`);
+    return tool;
+  });
+}

package/control-plane/scripts/device-inventory.mjs

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 100;
+
+function deviceSelectionError(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+function pathStyleFromHint(pathHint) {
+  const hint = String(pathHint || '').trim();
+  if (!hint) throw deviceSelectionError('PATH_HINT_REQUIRED', 'path_hint is required.');
+  if (/^[A-Za-z]:[\\/]/.test(hint) || /^\\\\/.test(hint)) return 'windows';
+  if (hint.startsWith('/')) return 'posix';
+  throw deviceSelectionError('PATH_HINT_UNSUPPORTED', 'path_hint must be an absolute Windows or POSIX path.');
+}
+
+export function selectDeviceForPathHint(devices, pathHint) {
+  const pathStyle = pathStyleFromHint(pathHint);
+  const matches = (Array.isArray(devices) ? devices : []).filter(device =>
+    Boolean(device?.online) &&
+    !device?.revoked &&
+    String(device?.pathStyle || '') === pathStyle
+  );
+  if (matches.length === 1) return matches[0];
+  if (matches.length === 0) {
+    throw deviceSelectionError('DEVICE_NOT_FOUND', `No owned online ${pathStyle} device matches path_hint.`);
+  }
+  throw deviceSelectionError('DEVICE_SELECTION_AMBIGUOUS', `Multiple owned online ${pathStyle} devices match path_hint; provide device_id explicitly.`);
+}
+
+function boundedLimit(value) {
+  const limit = value === undefined ? DEFAULT_LIMIT : Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new Error(`limit must be an integer between 1 and ${MAX_LIMIT}`);
+  }
+  return limit;
+}
+
+function inventorySignature(devices) {
+  return createHash('sha256')
+    .update(JSON.stringify(devices.map(device => ({
+      deviceId: device?.deviceId || '',
+      online: Boolean(device?.online),
+      capabilities: Array.isArray(device?.capabilities) ? device.capabilities : []
+    }))))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function encodeCursor(offset, signature) {
+  return Buffer.from(JSON.stringify({ v: 1, offset, signature }), 'utf8').toString('base64url');
+}
+
+function decodeCursor(cursor, signature) {
+  if (!cursor) return 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(String(cursor), 'base64url').toString('utf8'));
+  } catch {
+    throw new Error('Invalid cursor: expected an opaque cursor returned by list_devices.');
+  }
+  if (parsed?.v !== 1 || parsed?.signature !== signature || !Number.isInteger(parsed?.offset) || parsed.offset < 0) {
+    throw new Error('Invalid or stale cursor: device inventory changed.');
+  }
+  return parsed.offset;
+}
+
+export function listDevicesToolDefinition() {
+  return {
+    name: 'list_devices',
+    description: 'List currently paired device identities and bounded capability/status metadata. Forgotten devices are excluded; adding or removing devices does not change the MCP tool schema.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cursor: { type: 'string', description: 'Opaque cursor returned by the previous page.' },
+        limit: { type: 'integer', minimum: 1, maximum: MAX_LIMIT, default: DEFAULT_LIMIT },
+        path_hint: { type: 'string', description: 'Optional absolute Windows/POSIX path hint. Returns selected_device_id only when exactly one owned online device is compatible.' }
+      },
+      additionalProperties: false
+    }
+  };
+}
+
+function toWireDevice(device = {}) {
+  return {
+    device_id: device.deviceId || '',
+    device_name: device.deviceName || device.deviceId || '',
+    hostname: device.hostname || null,
+    platform: device.platform || null,
+    arch: device.arch || null,
+    path_style: device.pathStyle || null,
+    online: Boolean(device.online),
+    revoked: false,
+    agent_version: device.agentVersion || 'unknown',
+    capabilities: Array.isArray(device.capabilities) ? [...device.capabilities] : [],
+    connection_epoch: Number(device.connectionEpoch || 0),
+    connected_at: device.connectedAt || null,
+    last_seen_at: device.lastSeenAt || null,
+    account: device.account || { connected: false, label: null },
+    usage: device.usage ?? null,
+    schema: device.schema ?? null
+  };
+}
+
+export function paginateDeviceInventory(devices, options = {}) {
+  const sorted = [...(Array.isArray(devices) ? devices : [])]
+    .filter(device => !device?.revoked)
+    .sort((left, right) => String(left?.deviceId || '').localeCompare(String(right?.deviceId || '')));
+  const pathHint = String(options.path_hint || '').trim();
+  const selectedDevice = pathHint ? selectDeviceForPathHint(sorted, pathHint) : null;
+  const signature = inventorySignature(sorted);
+  const offset = decodeCursor(options.cursor, signature);
+  if (offset > sorted.length) throw new Error('Invalid or stale cursor: device offset is outside the current inventory.');
+  const limit = boundedLimit(options.limit);
+  const page = sorted.slice(offset, offset + limit).map(toWireDevice);
+  const nextOffset = offset + page.length;
+  const truncated = nextOffset < sorted.length;
+  return {
+    devices: page,
+    ...(selectedDevice ? { selected_device_id: selectedDevice.deviceId } : {}),
+    truncated,
+    nextCursor: truncated ? encodeCursor(nextOffset, signature) : null,
+    total: sorted.length
+  };
+}

package/control-plane/scripts/device-pairing-http.mjs

@@ -0,0 +1,109 @@
+import { escapeHtml, pageShell, quickGuide } from './enduser-ui.mjs';
+
+function renderVerificationPage({ pairing, account, approved = false }) {
+  if (approved) {
+    return pageShell({ title: 'Device approved', body: `<section class="card"><h1>Device approved</h1><p><strong>${escapeHtml(pairing.deviceName)}</strong> is approved for ${escapeHtml(account.email)}.</p><p class="muted">Return to the device terminal. It can now finish enrollment.</p><div class="actions"><a class="button" href="/dashboard">Dashboard</a><a href="/pair">Pair another device</a></div></section>` });
+  }
+  return pageShell({ title: 'Approve device', body: `<section class="card"><h1>Approve device</h1><p class="muted">Confirm that this is the device you intended to pair.</p><p>Account: <strong>${escapeHtml(account.email)}</strong></p><p>Device: <strong>${escapeHtml(pairing.deviceName)}</strong><br><span class="muted">${escapeHtml(pairing.deviceId)}</span></p><p>Code: <strong>${escapeHtml(pairing.userCode)}</strong></p><form method="post" action="/device/verify"><input type="hidden" name="user_code" value="${escapeHtml(pairing.userCode)}"><button class="primary" type="submit">Approve device</button></form></section>` });
+}
+
+function pairingStatePage(title, message, { status = 200, baseUrl = '' } = {}) {
+  return { status, html: pageShell({ title, body: `<section class="card"><h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p><div class="actions"><a class="button primary" href="/pair">Enter a code</a><a href="/help">Pairing help</a></div></section>${quickGuide(baseUrl)}` }) };
+}
+
+function errorPayload(error, fallback = 'invalid_request') {
+  const message = String(error?.message || error || fallback);
+  return { error: fallback, error_description: message.slice(0, 240) };
+}
+
+function verificationReturnTo(_req, userCode) {
+  const code = encodeURIComponent(String(userCode || '').trim());
+  return `/device/verify?user_code=${code}`;
+}
+
+export function installDevicePairingRoutes(app, { pairingStore, accountFromRequest, baseUrlFromRequest }) {
+  if (!app || !pairingStore || typeof accountFromRequest !== 'function') {
+    throw new Error('Device pairing routes require app, pairingStore, and accountFromRequest.');
+  }
+  const getBaseUrl = typeof baseUrlFromRequest === 'function' ? baseUrlFromRequest : req => `${req.protocol}://${req.get('host')}`;
+
+  app.get('/pair', (req, res) => {
+    const baseUrl = String(getBaseUrl(req) || '').replace(/\/+$/, '');
+    res.status(200).type('html').send(pageShell({ title: 'Pair a device', body: `<section class="card"><h1>Pair a device</h1><p class="muted">Start pairing on your device, then enter the code it shows.</p><form class="inline" method="get" action="/device/verify"><input name="user_code" autocomplete="one-time-code" placeholder="ABCD-EFGH" maxlength="9" required><button class="primary" type="submit">Continue</button></form></section>${quickGuide(baseUrl)}` }));
+  });
+
+  app.get('/help', (req, res) => {
+    const baseUrl = String(getBaseUrl(req) || '').replace(/\/+$/, '');
+    res.status(200).type('html').send(pageShell({ title: 'Help', body: `<section class="card"><h1>Device setup</h1><p>Point the device CLI at this gateway, sign in, approve the browser pairing code, then install the background service.</p><p class="muted">If a code expires, restart <code>mcp-device login</code> to get a new one.</p></section>${quickGuide(baseUrl)}` }));
+  });
+
+  app.post('/device/start', (req, res) => {
+    try {
+      if (String(req.body?.code_challenge_method || '') !== 'S256') {
+        res.status(400).json({ error: 'invalid_request', error_description: 'code_challenge_method must be S256.' });
+        return;
+      }
+      const started = pairingStore.start({ clientId: req.body?.client_id, deviceId: req.body?.device_id, deviceName: req.body?.device_name, publicKeyPem: req.body?.public_key_pem, codeChallenge: req.body?.code_challenge });
+      const baseUrl = String(getBaseUrl(req) || '').replace(/\/+$/, '');
+      const verificationUri = `${baseUrl}/device/verify`;
+      res.json({ device_code: started.deviceCode, user_code: started.userCode, verification_uri: verificationUri, verification_uri_complete: `${verificationUri}?user_code=${encodeURIComponent(started.userCode)}`, expires_in: started.expiresIn, interval: started.interval });
+    } catch (error) {
+      res.status(400).json(errorPayload(error));
+    }
+  });
+
+  app.get('/device/verify', (req, res) => {
+    const rawCode = String(req.query?.user_code || '').trim();
+    const baseUrl = String(getBaseUrl(req) || '').replace(/\/+$/, '');
+    if (!rawCode) {
+      const state = pairingStatePage('Enter the code from your device', 'Start pairing on your device first, then enter the code shown in its terminal.', { baseUrl });
+      res.status(state.status).type('html').send(state.html);
+      return;
+    }
+    try {
+      const pairing = pairingStore.getStatusByUserCode(rawCode);
+      if (pairing.status === 'expired') {
+        const state = pairingStatePage('Pairing code expired', 'Restart device login to create a fresh pairing code.', { status: 410, baseUrl });
+        res.status(state.status).type('html').send(state.html);
+        return;
+      }
+      const account = accountFromRequest(req);
+      if (!account) {
+        res.redirect(302, `/login?return_to=${encodeURIComponent(verificationReturnTo(req, pairing.userCode))}`);
+        return;
+      }
+      res.status(200).type('html').send(renderVerificationPage({ pairing, account }));
+    } catch {
+      const state = pairingStatePage('Invalid pairing code', 'Check the code and try again, or restart device login to create a new code.', { status: 404, baseUrl });
+      res.status(state.status).type('html').send(state.html);
+    }
+  });
+
+  app.post('/device/verify', (req, res) => {
+    try {
+      const pairing = pairingStore.getStatusByUserCode(req.body?.user_code);
+      const account = accountFromRequest(req);
+      if (!account) {
+        res.redirect(302, `/login?return_to=${encodeURIComponent(verificationReturnTo(req, pairing.userCode))}`);
+        return;
+      }
+      const approvedPairing = pairingStore.approve({ userCode: pairing.userCode, accountId: account.accountId, accountLabel: account.email });
+      res.status(200).type('html').send(renderVerificationPage({ pairing: approvedPairing, account, approved: true }));
+    } catch (error) {
+      res.status(400).type('html').send(pageShell({ title: 'Pairing failed', body: `<section class="card"><h1>Pairing failed</h1><p>${escapeHtml(error?.message || error)}</p><a href="/pair">Try again</a></section>` }));
+    }
+  });
+
+  app.post('/device/poll', (req, res) => {
+    try {
+      const result = pairingStore.poll({ deviceCode: req.body?.device_code, clientId: req.body?.client_id, codeVerifier: req.body?.code_verifier });
+      if (result.status === 'authorization_pending') {
+        res.status(400).json({ error: 'authorization_pending' });
+        return;
+      }
+      res.json({ enrollment_grant: result.enrollmentGrant, device_id: result.deviceId, account: result.account });
+    } catch (error) {
+      res.status(400).json(errorPayload(error, 'invalid_grant'));
+    }
+  });
+}