@rayrun/cli 0.1.0 → 0.3.0

package/src/execution.js

@@ -0,0 +1,862 @@
+/* eslint-disable node/no-process-env -- execution intentionally reads the invoking user's Rayrun configuration */
+import { clearOAuthSession, connectExecutionMcp, openExternalUrl } from './oauth.js';
+import { atomicWrite, assertNoSymbolicLinkComponents } from './setup.js';
+import { randomUUID } from 'node:crypto';
+import { chmod, link, lstat, mkdir, readFile, readdir, rename, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+
+const DEFAULT_MCP_ENDPOINT = 'https://ray.run/mcp/direct';
+const INPUT_LIMIT_BYTES = 1024 * 1024;
+const MAX_REQUEST_STATE_RETRIES = 10;
+const PENDING_LIFETIME_MILLISECONDS = 10 * 60 * 1_000;
+const PENDING_VERSION = 1;
+const REQUEST_STATE_RETRY_DELAY_MILLISECONDS = 250;
+const EXECUTION_ID_REGEX = /^[a-f\d-]{36}$/u;
+
+export const executionUsage = `Execution (OAuth, no API key):
+  rayrun tools describe <service.tool> [--endpoint <url>] [--json] [--no-open]
+  rayrun call <service.tool> [<arguments-json> | --input <path|->] [--endpoint <url>] [--json] [--no-open]
+  rayrun resume --execution-id <id> [--json] [--no-open]
+  rayrun logout [--endpoint <url>]
+
+Execution environment:
+  RAYRUN_MCP_URL   Optional Direct Mode endpoint (defaults to https://ray.run/mcp/direct)`;
+
+const isFileSystemError = (error, code) => {
+  return error && typeof error === 'object' && 'code' in error && error.code === code;
+};
+
+const configurationRoot = ({
+  environment = process.env,
+  homeDirectory = os.homedir(),
+  platform = process.platform,
+} = {}) => {
+  const configuredRoot = environment.RAYRUN_CONFIG_HOME;
+  const root = configuredRoot ?? path.join(homeDirectory, '.rayrun');
+  if (!path.isAbsolute(root)) throw new Error('RAYRUN_CONFIG_HOME must be an absolute path.');
+  if (platform === 'win32' && configuredRoot !== undefined) {
+    const relative = path.relative(homeDirectory, root);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error('On Windows, RAYRUN_CONFIG_HOME must stay inside the current user profile.');
+    }
+  }
+  return root;
+};
+
+const pendingDirectory = (options) => path.join(configurationRoot(options), 'execution', 'pending');
+
+const pendingPath = (executionId, options) => {
+  if (!EXECUTION_ID_REGEX.test(executionId)) throw new Error('Invalid execution id.');
+  return path.join(pendingDirectory(options), `${executionId}.json`);
+};
+
+const claimedPendingPath = (executionId, options) => {
+  if (!EXECUTION_ID_REGEX.test(executionId)) throw new Error('Invalid execution id.');
+  return path.join(pendingDirectory(options), `${executionId}.resuming`);
+};
+
+const ensurePrivateDirectory = async (directory) => {
+  await assertNoSymbolicLinkComponents(directory);
+  await mkdir(directory, { mode: 0o700, recursive: true });
+  await assertNoSymbolicLinkComponents(directory);
+  await chmod(directory, 0o700);
+};
+
+const readPrivateJson = async (target, { platform = process.platform } = {}) => {
+  await assertNoSymbolicLinkComponents(target);
+
+  try {
+    const metadata = await lstat(target);
+    if (!metadata.isFile() || (platform !== 'win32' && (metadata.mode & 0o077) !== 0)) {
+      throw new Error(`Refusing to read pending execution without 0600 permissions: ${target}`);
+    }
+    return JSON.parse(await readFile(target, 'utf8'));
+  } catch (error) {
+    if (isFileSystemError(error, 'ENOENT')) return null;
+    throw error;
+  }
+};
+
+const assertPendingShape = (pending, executionId) => {
+  const valid =
+    pending &&
+    typeof pending === 'object' &&
+    !Array.isArray(pending) &&
+    pending.version === PENDING_VERSION &&
+    pending.executionId === executionId &&
+    typeof pending.endpoint === 'string' &&
+    typeof pending.toolName === 'string' &&
+    pending.arguments &&
+    typeof pending.arguments === 'object' &&
+    !Array.isArray(pending.arguments) &&
+    pending.toolDefinition &&
+    typeof pending.toolDefinition === 'object' &&
+    !Array.isArray(pending.toolDefinition) &&
+    Array.isArray(pending.nextInputResponseIds) &&
+    pending.nextInputResponseIds.every((value) => typeof value === 'string') &&
+    pending.inputResponses &&
+    typeof pending.inputResponses === 'object' &&
+    !Array.isArray(pending.inputResponses) &&
+    typeof pending.expiresAt === 'number' &&
+    Number.isFinite(pending.expiresAt) &&
+    (pending.requestState === undefined || typeof pending.requestState === 'string');
+
+  if (!valid) {
+    throw new Error(`Pending execution ${executionId} is invalid. Remove it and repeat the call.`);
+  }
+  return pending;
+};
+
+const readPending = async (executionId, options, linkFile = link) => {
+  const target = pendingPath(executionId, options);
+  const claimedTarget = claimedPendingPath(executionId, options);
+  const throwClaimState = async () => {
+    const claimed = await readPrivateJson(claimedTarget, options);
+    if (claimed === null) throw new Error(`Pending execution not found: ${executionId}`);
+    const pending = assertPendingShape(claimed, executionId);
+    if (pending.expiresAt <= Date.now()) {
+      await rm(claimedTarget, { force: true });
+      await rm(target, { force: true });
+      throw new Error(`Pending execution expired: ${executionId}. Repeat the original call.`);
+    }
+    throw new Error(`Pending execution is already being resumed: ${executionId}`);
+  };
+  await assertNoSymbolicLinkComponents(target);
+  await assertNoSymbolicLinkComponents(claimedTarget);
+  try {
+    // A hard link gives this claim create-if-absent semantics; rename would overwrite an active
+    // claim during the brief window where a newer continuation has already been written.
+    await linkFile(target, claimedTarget);
+  } catch (error) {
+    if (isFileSystemError(error, 'EEXIST')) {
+      await throwClaimState();
+    }
+    if (
+      ['ENOSYS', 'ENOTSUP', 'EOPNOTSUPP', 'EPERM'].some((code) => isFileSystemError(error, code))
+    ) {
+      throw new Error(
+        'Pending execution storage must support hard links for atomic resume. Move RAYRUN_CONFIG_HOME to a local hard-link-capable filesystem.',
+      );
+    }
+    if (!isFileSystemError(error, 'ENOENT')) throw error;
+    await throwClaimState();
+  }
+  try {
+    await rm(target);
+  } catch (error) {
+    await rm(claimedTarget, { force: true });
+    throw error;
+  }
+
+  let pending;
+  try {
+    pending = assertPendingShape(await readPrivateJson(claimedTarget, options), executionId);
+  } catch (error) {
+    await rename(claimedTarget, target);
+    throw error;
+  }
+  if (pending.expiresAt <= Date.now()) {
+    await rm(claimedTarget, { force: true });
+    throw new Error(`Pending execution expired: ${executionId}. Repeat the original call.`);
+  }
+  return pending;
+};
+
+const writePending = async (pending, options) => {
+  const target = pendingPath(pending.executionId, options);
+  await ensurePrivateDirectory(path.dirname(target));
+  await atomicWrite({
+    contents: Buffer.from(`${JSON.stringify(pending, null, 2)}\n`),
+    mode: 0o600,
+    target,
+  });
+};
+
+const releasePendingClaim = async (executionId, options, completed) => {
+  const target = pendingPath(executionId, options);
+  const claimedTarget = claimedPendingPath(executionId, options);
+  if (completed) {
+    await rm(claimedTarget, { force: true });
+    return;
+  }
+
+  try {
+    await lstat(target);
+    // A new continuation superseded the claimed round before browser launching failed.
+    await rm(claimedTarget, { force: true });
+  } catch (error) {
+    if (!isFileSystemError(error, 'ENOENT')) throw error;
+    await rename(claimedTarget, target).catch((renameError) => {
+      if (!isFileSystemError(renameError, 'ENOENT')) throw renameError;
+    });
+  }
+};
+
+const assertPendingClaimStillExists = async (pending, options) => {
+  const claimed = await readPrivateJson(claimedPendingPath(pending.executionId, options), options);
+  if (claimed === null) {
+    throw new Error(`Pending execution was cancelled before resume: ${pending.executionId}`);
+  }
+  assertPendingShape(claimed, pending.executionId);
+};
+
+const clearPendingForEndpoint = async (endpoint, options) => {
+  const directory = pendingDirectory(options);
+  await assertNoSymbolicLinkComponents(directory);
+  let names;
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (isFileSystemError(error, 'ENOENT')) return 0;
+    throw error;
+  }
+
+  const removedExecutionIds = new Set();
+  for (const name of names) {
+    const suffix = name.endsWith('.json')
+      ? '.json'
+      : name.endsWith('.resuming')
+        ? '.resuming'
+        : null;
+    if (suffix === null) continue;
+    const executionId = name.slice(0, -suffix.length);
+    if (!EXECUTION_ID_REGEX.test(executionId)) continue;
+    let pending;
+    try {
+      pending = await readPrivateJson(path.join(directory, name), options);
+    } catch {
+      // A damaged entry must not prevent logout from removing the valid sessions it can identify.
+      continue;
+    }
+    if (pending?.endpoint !== endpoint) continue;
+    await rm(path.join(directory, name), { force: true });
+    removedExecutionIds.add(executionId);
+  }
+  return removedExecutionIds.size;
+};
+
+const pruneExpiredPending = async (options, preservedExecutionId) => {
+  const directory = pendingDirectory(options);
+  await assertNoSymbolicLinkComponents(directory);
+  let names;
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (isFileSystemError(error, 'ENOENT')) return;
+    throw error;
+  }
+
+  for (const name of names) {
+    if (!name.endsWith('.json') && !name.endsWith('.resuming')) continue;
+    if (
+      typeof preservedExecutionId === 'string' &&
+      (name === `${preservedExecutionId}.json` || name === `${preservedExecutionId}.resuming`)
+    ) {
+      continue;
+    }
+    const target = path.join(directory, name);
+    let pending;
+    try {
+      pending = await readPrivateJson(target, options);
+    } catch {
+      // The explicitly resumed id is validated by readPending; unrelated damage is isolated.
+      continue;
+    }
+    if (typeof pending?.expiresAt === 'number' && pending.expiresAt <= Date.now()) {
+      await rm(target, { force: true });
+    }
+  }
+};
+
+const validateWebUrl = (value, label) => {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${label} must be an absolute HTTP or HTTPS URL.`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error(`${label} must use HTTP or HTTPS.`);
+  }
+  if (
+    url.protocol === 'http:' &&
+    !['127.0.0.1', '::1', '[::1]', 'localhost'].includes(url.hostname)
+  ) {
+    throw new Error(`${label} may use HTTP only on localhost.`);
+  }
+  if (url.username || url.password) throw new Error(`${label} cannot contain credentials.`);
+  return url;
+};
+
+export const validateExecutionEndpoint = (value) => {
+  const endpoint = validateWebUrl(value, 'MCP endpoint');
+  if (endpoint.search || endpoint.hash) {
+    throw new Error('MCP endpoint cannot contain a query string or fragment.');
+  }
+  endpoint.pathname = endpoint.pathname.replace(/\/$/u, '');
+  if (!endpoint.pathname.endsWith('/mcp/direct')) {
+    throw new Error('Execution MCP endpoint path must end in /mcp/direct.');
+  }
+  return endpoint.href;
+};
+
+const optionNames = new Map([
+  ['--endpoint', 'endpoint'],
+  ['--execution-id', 'executionId'],
+  ['--input', 'inputPath'],
+]);
+
+const parseCommandArguments = (arguments_, allowedOptions) => {
+  const options = { json: false, noOpen: false };
+  const positional = [];
+
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === '--json' || argument === '--no-open') {
+      const key = argument === '--json' ? 'json' : 'noOpen';
+      if (!allowedOptions.has(key)) throw new Error(`Unknown option: ${argument}`);
+      if (options[key]) throw new Error(`${argument} can only be used once.`);
+      options[key] = true;
+      continue;
+    }
+    const optionName = optionNames.get(argument);
+    if (optionName) {
+      if (!allowedOptions.has(optionName)) throw new Error(`Unknown option: ${argument}`);
+      const value = arguments_[index + 1];
+      if (!value || (value.startsWith('--') && value !== '-')) {
+        throw new Error(`${argument} requires a value.`);
+      }
+      if (options[optionName] !== undefined) {
+        throw new Error(`${argument} can only be used once.`);
+      }
+      options[optionName] = value;
+      index += 1;
+      continue;
+    }
+    if (argument?.startsWith('--')) throw new Error(`Unknown option: ${argument}`);
+    if (argument) positional.push(argument);
+  }
+  return { options, positional };
+};
+
+const resolveEndpoint = (options, environment) => {
+  return validateExecutionEndpoint(
+    options.endpoint ?? environment.RAYRUN_MCP_URL ?? DEFAULT_MCP_ENDPOINT,
+  );
+};
+
+const parseJsonObject = (contents) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch {
+    throw new Error('Tool arguments must be valid JSON.');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('Tool arguments must be a JSON object.');
+  }
+  return parsed;
+};
+
+const readStream = async (input) => {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of input) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > INPUT_LIMIT_BYTES) throw new Error('Tool arguments exceed the 1 MiB input limit.');
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+const readArguments = async ({ input, inputPath, positional }) => {
+  if (inputPath !== undefined && positional.length > 1) {
+    throw new Error('Use either inline JSON or --input, not both.');
+  }
+  if (positional.length > 2) throw new Error(executionUsage);
+  if (inputPath === undefined) return parseJsonObject(positional[1] ?? '{}');
+  if (inputPath === '-') return parseJsonObject(await readStream(input));
+
+  const metadata = await stat(inputPath);
+  if (!metadata.isFile()) throw new Error(`Tool input is not a file: ${inputPath}`);
+  if (metadata.size > INPUT_LIMIT_BYTES)
+    throw new Error('Tool arguments exceed the 1 MiB input limit.');
+  return parseJsonObject(await readFile(inputPath, 'utf8'));
+};
+
+const cleanLine = (value) => {
+  return stripVTControlCharacters(String(value))
+    .replaceAll(/\p{Cc}+/gu, ' ')
+    .replaceAll(/\s+/gu, ' ')
+    .trim();
+};
+
+const cleanText = (value) => {
+  return stripVTControlCharacters(String(value))
+    .split('\n')
+    .map((line) => line.replaceAll(/\p{Cc}+/gu, ''))
+    .join('\n');
+};
+
+const writeJson = (output, value) => output.write(`${JSON.stringify(value, null, 2)}\n`);
+
+const renderTool = ({ json, output, tool }) => {
+  if (json) {
+    writeJson(output, tool);
+    return;
+  }
+  output.write(`Name: ${cleanLine(tool.name)}\n`);
+  if (tool.title) output.write(`Title: ${cleanLine(tool.title)}\n`);
+  if (tool.description) output.write(`Description: ${cleanText(tool.description)}\n`);
+  output.write(`Input schema:\n${JSON.stringify(tool.inputSchema, null, 2)}\n`);
+  if (tool.outputSchema !== undefined) {
+    output.write(`Output schema:\n${JSON.stringify(tool.outputSchema, null, 2)}\n`);
+  }
+  if (tool.annotations !== undefined) {
+    output.write(`Annotations:\n${JSON.stringify(tool.annotations, null, 2)}\n`);
+  }
+};
+
+const renderResult = ({ json, output, result }) => {
+  if (json) {
+    writeJson(output, result);
+    return;
+  }
+  let wroteContent = false;
+  for (const content of result.content ?? []) {
+    if (content?.type === 'text' && typeof content.text === 'string') {
+      const text = cleanText(content.text);
+      output.write(`${text}${text.endsWith('\n') ? '' : '\n'}`);
+    } else {
+      writeJson(output, content);
+    }
+    wroteContent = true;
+  }
+  if (!wroteContent && result.structuredContent !== undefined) {
+    writeJson(output, result.structuredContent);
+  }
+  if (!wroteContent && result.structuredContent === undefined)
+    output.write('Tool returned no content.\n');
+};
+
+class TerminalToolError extends Error {}
+
+const findTool = async (client, name) => {
+  const { tools } = await client.listTools();
+  const tool = tools.find((candidate) => candidate.name === name);
+  if (!tool) throw new Error(`Tool not found: ${name}`);
+  return tool;
+};
+
+const readUrlContinuations = (result) => {
+  if (result?.resultType === 'input_required') {
+    const requests = Object.entries(result.inputRequests ?? {});
+    if (requests.length === 0) {
+      throw new Error('The tool requested unsupported continuation input.');
+    }
+    return requests.map(([id, request]) => {
+      const parameters = request?.params;
+      if (
+        request?.method !== 'elicitation/create' ||
+        parameters?.mode !== 'url' ||
+        typeof parameters.message !== 'string' ||
+        typeof parameters.url !== 'string'
+      ) {
+        throw new Error('The Rayrun CLI can resume URL requests only.');
+      }
+      return {
+        id,
+        message: parameters.message,
+        url: validateWebUrl(parameters.url, 'Continuation URL').href,
+      };
+    });
+  }
+
+  const approval = result?._meta?.['io.rayrun/approval'];
+  if (
+    result?.isError === true &&
+    approval?.state === 'pending' &&
+    typeof approval.approvalUrl === 'string'
+  ) {
+    return [
+      {
+        id: null,
+        message: 'Review and approve this exact call in Rayrun.',
+        url: validateWebUrl(approval.approvalUrl, 'Approval URL').href,
+      },
+    ];
+  }
+  return null;
+};
+
+const pauseExecution = async ({
+  arguments: toolArguments,
+  endpoint,
+  errorOutput,
+  executionId = randomUUID(),
+  inputResponses,
+  json,
+  noOpen,
+  openUrl,
+  output,
+  priorRequestState,
+  result,
+  storageOptions,
+  toolDefinition,
+  toolName,
+}) => {
+  const requests = readUrlContinuations(result);
+  if (requests === null) return null;
+  const approvalRequestState = result?._meta?.['io.rayrun/approval']?.requestState;
+  const approvalExpiresAt = result?._meta?.['io.rayrun/approval']?.expiresAt;
+  const parsedApprovalExpiresAt =
+    typeof approvalExpiresAt === 'string' ? Date.parse(approvalExpiresAt) : Number.NaN;
+  const nextRequestState =
+    result.resultType === 'input_required'
+      ? result.requestState
+      : typeof approvalRequestState === 'string'
+        ? approvalRequestState
+        : priorRequestState;
+  const pending = {
+    arguments: toolArguments,
+    endpoint,
+    executionId,
+    expiresAt: Math.min(
+      Date.now() + PENDING_LIFETIME_MILLISECONDS,
+      Number.isFinite(parsedApprovalExpiresAt) ? parsedApprovalExpiresAt : Number.POSITIVE_INFINITY,
+    ),
+    inputResponses,
+    nextInputResponseIds: requests.flatMap((request) => (request.id === null ? [] : [request.id])),
+    ...(nextRequestState === undefined ? {} : { requestState: nextRequestState }),
+    toolDefinition,
+    toolName,
+    version: PENDING_VERSION,
+  };
+  await writePending(pending, storageOptions);
+
+  if (json) {
+    writeJson(output, {
+      executionId,
+      requests: requests.map(({ message, url }) => ({ message, url })),
+      status: 'input_required',
+    });
+  } else {
+    output.write(`Execution paused: ${executionId}\n`);
+    for (const request of requests) output.write(`${cleanLine(request.message)}\n`);
+    output.write(`Resume: rayrun resume --execution-id ${executionId}\n`);
+  }
+  for (const request of requests) {
+    await openUrl(request.url, { errorOutput, noOpen });
+  }
+  return executionId;
+};
+
+const callTool = async ({
+  arguments: toolArguments,
+  client,
+  endpoint,
+  errorOutput,
+  executionId,
+  inputResponses = {},
+  json,
+  noOpen,
+  openUrl,
+  output,
+  requestState,
+  sleep,
+  storageOptions,
+  toolDefinition,
+  toolName,
+}) => {
+  // The MCP 2.0 client validates outputSchema before returning input_required, even though
+  // continuation legs have no final structuredContent yet. Keep the input schema (including
+  // x-mcp-header declarations) while deferring output validation to the authoritative server.
+  const { outputSchema: _outputSchema, ...callToolDefinition } = toolDefinition;
+  let continuationState = requestState;
+  let requestStateRetries = 0;
+  let result;
+  while (true) {
+    result = await client.callTool(
+      {
+        arguments: toolArguments,
+        ...(Object.keys(inputResponses).length === 0 ? {} : { inputResponses }),
+        name: toolName,
+        ...(continuationState === undefined ? {} : { requestState: continuationState }),
+      },
+      { allowInputRequired: true, toolDefinition: callToolDefinition },
+    );
+    const hasInputRequests = Object.keys(result?.inputRequests ?? {}).length > 0;
+    if (
+      result?.resultType !== 'input_required' ||
+      hasInputRequests ||
+      typeof result.requestState !== 'string'
+    ) {
+      break;
+    }
+    if (requestStateRetries >= MAX_REQUEST_STATE_RETRIES) {
+      throw new Error('The tool did not finish after 10 continuation retries.');
+    }
+    requestStateRetries += 1;
+    continuationState = result.requestState;
+    await sleep(REQUEST_STATE_RETRY_DELAY_MILLISECONDS);
+  }
+  const paused = await pauseExecution({
+    arguments: toolArguments,
+    endpoint,
+    errorOutput,
+    executionId,
+    inputResponses,
+    json,
+    noOpen,
+    openUrl,
+    output,
+    priorRequestState: continuationState,
+    result,
+    storageOptions,
+    toolDefinition,
+    toolName,
+  });
+  if (paused !== null) return { paused: true };
+
+  renderResult({ json, output, result });
+  if (result.isError) throw new TerminalToolError(`Tool call failed: ${toolName}`);
+  return { paused: false };
+};
+
+const revokeSession = async ({ errorOutput, fetchImplementation, session }) => {
+  const metadata = session.discoveryState?.authorizationServerMetadata;
+  const revocationEndpoint = metadata?.revocation_endpoint;
+  if (typeof revocationEndpoint !== 'string') return;
+  const revocationIssuer = metadata?.issuer ?? session.discoveryState?.authorizationServerUrl;
+  let endpoint;
+  try {
+    endpoint = validateWebUrl(revocationEndpoint, 'OAuth revocation endpoint');
+  } catch (error) {
+    errorOutput.write(`Warning: ${error.message}\n`);
+    return;
+  }
+
+  for (const [issuer, tokens] of Object.entries(session.tokensByIssuer)) {
+    if (issuer !== revocationIssuer) {
+      errorOutput.write(
+        `Warning: skipped token revocation for an older OAuth issuer: ${issuer}.\n`,
+      );
+      continue;
+    }
+    const token = tokens?.refresh_token ?? tokens?.access_token;
+    if (typeof token !== 'string') continue;
+    const body = new URLSearchParams({ token });
+    body.set('token_type_hint', tokens.refresh_token ? 'refresh_token' : 'access_token');
+    const clientId = session.clientInformationByIssuer[issuer]?.client_id;
+    if (typeof clientId === 'string') body.set('client_id', clientId);
+    try {
+      const response = await fetchImplementation(endpoint, {
+        body,
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        method: 'POST',
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!response.ok) {
+        errorOutput.write(
+          `Warning: OAuth token revocation returned HTTP ${String(response.status)}.\n`,
+        );
+      }
+    } catch (error) {
+      errorOutput.write(
+        `Warning: OAuth token revocation failed: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+    }
+  }
+};
+
+export const isExecutionCommand = (arguments_) => {
+  return (
+    arguments_[0] === 'call' ||
+    arguments_[0] === 'resume' ||
+    arguments_[0] === 'logout' ||
+    (arguments_[0] === 'tools' && arguments_[1] === 'describe')
+  );
+};
+
+export const runExecutionCommand = async (
+  arguments_,
+  {
+    connect = connectExecutionMcp,
+    environment = process.env,
+    errorOutput = process.stderr,
+    fetchImplementation = globalThis.fetch,
+    input = process.stdin,
+    linkFile = link,
+    openUrl = openExternalUrl,
+    output = process.stdout,
+    sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    storageOptions = { environment },
+    version = '0.0.0',
+  } = {},
+) => {
+  const command = arguments_[0];
+  const action = arguments_[1];
+  const executionIdOptionIndex = arguments_.indexOf('--execution-id');
+  await pruneExpiredPending(
+    storageOptions,
+    command === 'resume' && executionIdOptionIndex >= 0
+      ? arguments_[executionIdOptionIndex + 1]
+      : undefined,
+  );
+
+  if (command === 'logout') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(1),
+      new Set(['endpoint']),
+    );
+    if (positional.length > 0) throw new Error(executionUsage);
+    const endpoint = resolveEndpoint(options, environment);
+    let removed = 0;
+    const session = await clearOAuthSession(endpoint, storageOptions, async () => {
+      removed = await clearPendingForEndpoint(endpoint, storageOptions);
+    });
+    await revokeSession({ errorOutput, fetchImplementation, session });
+    output.write(
+      `Logged out of ${endpoint}.${removed > 0 ? ` Removed ${String(removed)} pending execution(s).` : ''}\n`,
+    );
+    return;
+  }
+
+  if (command === 'resume') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(1),
+      new Set(['executionId', 'json', 'noOpen']),
+    );
+    if (positional.length > 0 || !options.executionId) throw new Error(executionUsage);
+    const pending = await readPending(options.executionId, storageOptions, linkFile);
+    let completed = false;
+    try {
+      const inputResponses = {
+        ...pending.inputResponses,
+        ...Object.fromEntries(pending.nextInputResponseIds.map((id) => [id, { action: 'accept' }])),
+      };
+      const connection = await connect({
+        endpoint: pending.endpoint,
+        errorOutput,
+        noOpen: options.noOpen,
+        openUrl,
+        storageOptions,
+        version,
+      });
+      try {
+        // Logout can win the endpoint lock after this process claims the file but before connect.
+        // Rechecking under connect's lock prevents a cancelled exact call from executing afterward.
+        await assertPendingClaimStillExists(pending, storageOptions);
+        await callTool({
+          arguments: pending.arguments,
+          client: connection.client,
+          endpoint: pending.endpoint,
+          errorOutput,
+          executionId: pending.executionId,
+          inputResponses,
+          json: options.json,
+          noOpen: options.noOpen,
+          openUrl,
+          output,
+          requestState: pending.requestState,
+          sleep,
+          storageOptions,
+          toolDefinition: pending.toolDefinition,
+          toolName: pending.toolName,
+        });
+        completed = true;
+      } catch (error) {
+        if (error instanceof TerminalToolError) completed = true;
+        throw error;
+      } finally {
+        try {
+          await releasePendingClaim(pending.executionId, storageOptions, completed);
+        } finally {
+          await connection.close();
+        }
+      }
+    } finally {
+      if (!completed) {
+        await releasePendingClaim(pending.executionId, storageOptions, false).catch((error) => {
+          if (!isFileSystemError(error, 'ENOENT')) throw error;
+        });
+      }
+    }
+    return;
+  }
+
+  if (command === 'tools' && action === 'describe') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['endpoint', 'json', 'noOpen']),
+    );
+    if (positional.length !== 1) throw new Error(executionUsage);
+    const endpoint = resolveEndpoint(options, environment);
+    const connection = await connect({
+      endpoint,
+      errorOutput,
+      noOpen: options.noOpen,
+      openUrl,
+      storageOptions,
+      version,
+    });
+    try {
+      renderTool({
+        json: options.json,
+        output,
+        tool: await findTool(connection.client, positional[0]),
+      });
+    } finally {
+      await connection.close();
+    }
+    return;
+  }
+
+  if (command === 'call') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(1),
+      new Set(['endpoint', 'inputPath', 'json', 'noOpen']),
+    );
+    if (positional.length === 0) throw new Error(executionUsage);
+    const endpoint = resolveEndpoint(options, environment);
+    const toolArguments = await readArguments({
+      input,
+      inputPath: options.inputPath,
+      positional,
+    });
+    const connection = await connect({
+      endpoint,
+      errorOutput,
+      noOpen: options.noOpen,
+      openUrl,
+      storageOptions,
+      version,
+    });
+    try {
+      const tool = await findTool(connection.client, positional[0]);
+      await callTool({
+        arguments: toolArguments,
+        client: connection.client,
+        endpoint,
+        errorOutput,
+        inputResponses: {},
+        json: options.json,
+        noOpen: options.noOpen,
+        openUrl,
+        output,
+        sleep,
+        storageOptions,
+        toolDefinition: tool,
+        toolName: positional[0],
+      });
+    } finally {
+      await connection.close();
+    }
+    return;
+  }
+
+  throw new Error(executionUsage);
+};