@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.160.1

package/src/command-specs/tools.js

@@ -1,17 +1,24 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { accessSync, constants as fsConstants, createReadStream, existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
 import { usageError } from '../runtime/errors.js';
+import { assertToolNotDelegated } from '../runtime/delegated-context.js';
 import {
+  COMPOSIO_GET_TOOL_SCHEMAS,
+  COMPOSIO_MULTI_EXECUTE_TOOL,
+  COMPOSIO_SEARCH_TOOLS,
+  fetchToolDiscovery,
   fetchToolkits,
   fetchToolSchema,
+  localNotisToolSlug,
   nextIdempotencyKey,
   parseJson,
   parseMaybeJson,
-  resolveSearchToolkits,
   runToolCommand,
   validateArguments,
 } from './helpers.js';
 
-async function resolveJsonInput(value, label) {
+export async function resolveJsonInput(value, label) {
   if (!value) return undefined;
 
   if (value === '-') {
@@ -33,6 +40,263 @@ async function resolveJsonInput(value, label) {
   return parseJson(value, label);
 }
 
+const READ_ACTIONS = new Set([
+  'CHECK',
+  'DESCRIBE',
+  'DOWNLOAD',
+  'FETCH',
+  'FIND',
+  'GET',
+  'INSPECT',
+  'LIST',
+  'LOOKUP',
+  'PREVIEW',
+  'QUERY',
+  'READ',
+  'SEARCH',
+  'STATUS',
+  'VERIFY',
+]);
+const WRITE_ACTIONS = new Set([
+  'AUTHENTIFY',
+  'CANCEL',
+  'CONNECT',
+  'COPY',
+  'CREATE',
+  'DELETE',
+  'DEPLOY',
+  'DISCARD',
+  'EDIT',
+  'GRANT',
+  'INCREMENT',
+  'INSERT',
+  'LINK',
+  'MOVE',
+  'POST',
+  'PUBLISH',
+  'REFUND',
+  'REMOVE',
+  'RENAME',
+  'SAVE',
+  'SEND',
+  'SUBMIT',
+  'UPDATE',
+  'UPLOAD',
+  'UPSERT',
+]);
+
+function splitSqlStatements(query) {
+  const statements = [];
+  let current = '';
+  let quote = null;
+  let dollarTag = null;
+  for (let index = 0; index < query.length; index += 1) {
+    const char = query[index];
+    if (dollarTag) {
+      if (query.startsWith(dollarTag, index)) {
+        current += dollarTag;
+        index += dollarTag.length - 1;
+        dollarTag = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (quote) {
+      current += char;
+      if (char === quote) {
+        if (query[index + 1] === quote) {
+          current += query[index + 1];
+          index += 1;
+        } else {
+          quote = null;
+        }
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === '$') {
+      const match = query.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/);
+      if (match) {
+        dollarTag = match[0];
+        current += dollarTag;
+        index += dollarTag.length - 1;
+        continue;
+      }
+    }
+    if (char === ';') {
+      if (current.trim()) statements.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) statements.push(current.trim());
+  return statements;
+}
+
+function classifySqlMutation(query) {
+  const statements = splitSqlStatements(query);
+  if (statements.length > 1) {
+    const classifications = statements.map(classifySqlMutation);
+    if (classifications.includes(true)) return true;
+    if (classifications.every((classification) => classification === false)) return false;
+    return null;
+  }
+  const statement = statements[0] || '';
+  if (statement) {
+    const normalizedStatement = statement.toUpperCase();
+    if (/^EXPLAIN\b/.test(normalizedStatement)) {
+      const executes = /^EXPLAIN\s+(?:\([^)]*\bANALYZE\b[^)]*\)\s*|ANALYZE\s+)/.test(normalizedStatement);
+      if (!executes) return false;
+      return /\b(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement);
+    }
+    if (/^SHOW\b/.test(normalizedStatement)) return false;
+    // PostgreSQL SELECT can call side-effecting functions. Without catalog
+    // knowledge it is not provably read-only, so preserve idempotency and report
+    // an unknown classification instead of claiming mutating=false.
+    if (/^SELECT\b/.test(normalizedStatement)) return null;
+    if (/^WITH\b/.test(normalizedStatement)) {
+      return /\b(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement)
+        ? true
+        : null;
+    }
+    if (/^(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement)) {
+      return true;
+    }
+  }
+  return null;
+}
+
+export function classifyToolMutation(toolName, args = {}) {
+  const normalized = localNotisToolSlug(toolName).toUpperCase();
+  if (normalized === 'LOCAL_NOTIS_SANDBOX_PREVIEW') {
+    if (args.action === 'status') return false;
+    if (['register', 'open', 'heartbeat', 'stop'].includes(args.action)) return true;
+    return null;
+  }
+  if (normalized.includes('EXECUTE_SQL') && typeof args.query === 'string') {
+    const query = args.query
+      .replace(/\/\*[\s\S]*?\*\//g, ' ')
+      .replace(/--[^\n]*/g, ' ')
+      .trim();
+    const sqlClassification = classifySqlMutation(query);
+    if (sqlClassification !== null) return sqlClassification;
+  }
+  if (/(?:^|_)(?:FIND|GET|LOOKUP|SEARCH)_OR_(?:CREATE|INSERT|SAVE|UPDATE|UPSERT)(?:_|$)/.test(normalized)) {
+    return true;
+  }
+  const tokens = normalized.split(/[^A-Z0-9]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (WRITE_ACTIONS.has(token)) return true;
+    if (READ_ACTIONS.has(token)) return false;
+  }
+  return null;
+}
+
+const LONG_RUNNING_TOOL_TIMEOUT_MS = 600000;
+const LONG_RUNNING_TOOL_NAMES = new Set([
+  'LOCAL_NOTIS_GENERATE_IMAGE_OPENAI',
+  'LOCAL_NOTIS_EDIT_IMAGE_OPENAI',
+  'LOCAL_NOTIS_GENERATE_IMAGE_GEMINI',
+  'LOCAL_NOTIS_EDIT_IMAGE_GEMINI',
+]);
+
+const EXTENSION_CONTENT_TYPES = new Map([
+  ['.pdf', 'application/pdf'],
+  ['.png', 'image/png'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.gif', 'image/gif'],
+  ['.webp', 'image/webp'],
+  ['.txt', 'text/plain'],
+  ['.csv', 'text/csv'],
+  ['.json', 'application/json'],
+  ['.md', 'text/markdown'],
+]);
+
+function guessContentType(filePath) {
+  const lower = filePath.toLowerCase();
+  const dotIndex = lower.lastIndexOf('.');
+  if (dotIndex === -1) return 'application/octet-stream';
+  return EXTENSION_CONTENT_TYPES.get(lower.slice(dotIndex)) || 'application/octet-stream';
+}
+
+export async function hashFileSha256(localPath) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(localPath)) {
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+async function parseFileBindingSpec(spec, index) {
+  if (typeof spec !== 'string' || !spec.trim()) {
+    throw usageError('--file must be formatted as <argument-path>=<local-path>');
+  }
+
+  const equalsIndex = spec.indexOf('=');
+  if (equalsIndex <= 0 || equalsIndex === spec.length - 1) {
+    throw usageError('--file must be formatted as <argument-path>=<local-path>');
+  }
+
+  const argumentPath = spec.slice(0, equalsIndex).trim();
+  const localPath = spec.slice(equalsIndex + 1).trim();
+  if (!argumentPath) {
+    throw usageError('--file argument path is required');
+  }
+  if (!localPath) {
+    throw usageError('--file local path is required');
+  }
+  if (!existsSync(localPath)) {
+    throw usageError(`File not found: ${localPath}`);
+  }
+
+  let stats;
+  try {
+    stats = statSync(localPath);
+    accessSync(localPath, fsConstants.R_OK);
+  } catch {
+    throw usageError(`File is not readable: ${localPath}`);
+  }
+  if (!stats.isFile()) {
+    throw usageError(`File is not a regular file: ${localPath}`);
+  }
+
+  const sha256 = await hashFileSha256(localPath);
+  const fileBasename = basename(localPath);
+  const fieldName = `file_${index}`;
+
+  return {
+    argument_path: argumentPath,
+    field_name: fieldName,
+    basename: fileBasename,
+    size: stats.size,
+    sha256,
+    contentType: guessContentType(fileBasename),
+    localPath,
+  };
+}
+
+export async function parseFileBindings(rawFileOptions) {
+  const values = Array.isArray(rawFileOptions)
+    ? rawFileOptions
+    : (rawFileOptions ? [rawFileOptions] : []);
+  return Promise.all(values.map((value, index) => parseFileBindingSpec(value, index)));
+}
+
+function ensureLongRunningToolTimeout(ctx, toolNames) {
+  const names = Array.isArray(toolNames) ? toolNames : [toolNames];
+  if (!names.some((name) => LONG_RUNNING_TOOL_NAMES.has(localNotisToolSlug(name)))) {
+    return;
+  }
+  ctx.runtime.timeoutMs = Math.max(ctx.runtime.timeoutMs || 0, LONG_RUNNING_TOOL_TIMEOUT_MS);
+}
+
 async function toolsToolkitsHandler(ctx) {
   const toolkits = await fetchToolkits(ctx.runtime);
   return ctx.output.emitSuccess({
@@ -40,27 +304,55 @@ async function toolsToolkitsHandler(ctx) {
     data: { toolkits },
     humanSummary: `Found ${toolkits.length} toolkits`,
     hints: [
-      { command: 'notis tools search <query>', reason: 'Search for tools in these toolkits' },
+      { command: 'notis tools search <query>', reason: 'Search canonical tools and schemas' },
     ],
-    renderHuman: () => toolkits.map((entry) => `${entry.id}  ${entry.description}`).join('\n'),
+    renderHuman: () =>
+      toolkits
+        .map((entry) => {
+          const status = entry.has_active_connection ? 'connected' : 'needs auth';
+          return `${entry.id}  ${status}  ${entry.description}`;
+        })
+        .join('\n'),
   });
 }
 
+function discoveryToolRows(payload) {
+  const schemas = payload.tool_schemas || {};
+  const statuses = new Map(
+    (payload.toolkit_connection_statuses || [])
+      .filter((entry) => entry && typeof entry.toolkit === 'string')
+      .map((entry) => [entry.toolkit, entry])
+  );
+  const seen = new Set();
+  const rows = [];
+  for (const result of payload.results || []) {
+    for (const name of [...(result.primary_tool_slugs || []), ...(result.related_tool_slugs || [])]) {
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      const schema = schemas[name] || {};
+      const toolkit = schema.toolkit || name.split('-').slice(0, -1).join('-');
+      const status = statuses.get(toolkit);
+      rows.push({
+        name,
+        toolkit,
+        description: schema.description || '',
+        schema_available: Boolean(schemas[name]),
+        connection_status: status
+          ? (status.has_active_connection ? 'connected' : 'needs auth')
+          : 'unknown',
+      });
+    }
+  }
+  return rows;
+}
+
 async function toolsSearchHandler(ctx) {
-  const toolkits = await resolveSearchToolkits(ctx.runtime, ctx.options.toolkits);
-  const result = await runToolCommand({
-    runtime: ctx.runtime,
-    toolName: 'notis_find_tools',
-    arguments_: {
-      query: ctx.args.query || undefined,
-      toolkits,
-    },
-  });
-  const tools = result.payload.tools || [];
+  const payload = await fetchToolDiscovery(ctx.runtime, ctx.args.query || 'Find tools', ctx.options.knownFields || '');
+  const tools = discoveryToolRows(payload);
   const firstTool = tools[0];
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
-    data: { toolkits, tools },
+    data: payload,
     humanSummary: `Found ${tools.length} tools`,
     hints: firstTool
       ? [
@@ -70,70 +362,79 @@ async function toolsSearchHandler(ctx) {
       : [],
     renderHuman: () =>
       tools
-        .map((tool) => `${tool.name}\n  ${tool.toolkit_id || 'unknown toolkit'}\n  ${tool.description || 'No description'}\n`)
+        .map((tool) => `${tool.name}\n  toolkit: ${tool.toolkit || 'unknown'} (${tool.connection_status})\n  schema: ${tool.schema_available ? 'available' : 'missing'}\n  ${tool.description || 'No description'}\n`)
         .join('\n')
         .trim(),
   });
 }
 
 async function toolsDescribeHandler(ctx) {
-  const toolkits = await resolveSearchToolkits(ctx.runtime, ctx.options.toolkits);
-  const result = await runToolCommand({
-    runtime: ctx.runtime,
-    toolName: 'notis_find_tools',
-    arguments_: {
-      query: ctx.args.toolName,
-      toolkits,
-    },
-  });
-  const tools = result.payload.tools || [];
-  const match = tools.find((tool) => tool.name === ctx.args.toolName);
-  if (!match) {
-    throw usageError(`Tool ${ctx.args.toolName} was not found in the selected toolkits.`);
-  }
+  const requestedToolName = localNotisToolSlug(ctx.args.toolName);
+  const match = await fetchToolSchema(ctx.runtime, requestedToolName);
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
-    data: { tool: match, toolkits },
-    humanSummary: `Described tool ${ctx.args.toolName}`,
+    data: { tool: match },
+    humanSummary: `Described tool ${requestedToolName}`,
     hints: [
-      { command: `notis tools exec ${ctx.args.toolName} --dry-run --arguments '{}'`, reason: 'Validate arguments first' },
-      { command: `notis tools exec ${ctx.args.toolName} --arguments '{}'`, reason: 'Execute this tool' },
+      { command: `notis tools exec ${requestedToolName} --dry-run --arguments '{}'`, reason: 'Validate arguments first' },
+      { command: `notis tools exec ${requestedToolName} --arguments '{}'`, reason: 'Execute this tool' },
     ],
     renderHuman: () => JSON.stringify(match, null, 2),
   });
 }
 
 async function toolsExecHandler(ctx) {
+  const requestedToolName = localNotisToolSlug(ctx.args.toolName);
+  // `tools exec` is the escape hatch around every first-class command, so the
+  // hand-over guard has to live here too or it guards nothing.
+  assertToolNotDelegated(requestedToolName);
+  let targetMutating = classifyToolMutation(requestedToolName);
+  ensureLongRunningToolTimeout(ctx, requestedToolName);
+  ctx.output.emitProgress({
+    phase: 'prepare',
+    message: `Resolving ${requestedToolName}`,
+  });
+  const fileBindings = await parseFileBindings(ctx.options.file);
+
   if (ctx.options.getSchema) {
-    const tool = await fetchToolSchema(ctx.runtime, ctx.args.toolName);
+    const tool = await fetchToolSchema(ctx.runtime, requestedToolName);
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(' '),
       data: { tool },
-      humanSummary: `Schema for ${ctx.args.toolName}`,
+      humanSummary: `Schema for ${requestedToolName}`,
       hints: [
-        { command: `notis tools exec ${ctx.args.toolName} --dry-run --arguments '{}'`, reason: 'Validate arguments before executing' },
+        { command: `notis tools exec ${requestedToolName} --dry-run --arguments '{}'`, reason: 'Validate arguments before executing' },
       ],
       renderHuman: () => JSON.stringify(tool, null, 2),
     });
   }
 
-  const rawArguments = ctx.options.arguments || '{}';
+  if (ctx.options.argumentsFile && ctx.options.arguments) {
+    throw usageError('Use either --arguments or --arguments-file, not both.');
+  }
+  const rawArguments = ctx.options.argumentsFile
+    ? `@${ctx.options.argumentsFile}`
+    : (ctx.options.arguments || '{}');
   const args = rawArguments === '-' || rawArguments.startsWith('@')
     ? await resolveJsonInput(rawArguments, 'arguments') || {}
     : parseMaybeJson(rawArguments, 'arguments') || {};
+  targetMutating = classifyToolMutation(requestedToolName, args);
 
   if (ctx.options.dryRun) {
-    const tool = await fetchToolSchema(ctx.runtime, ctx.args.toolName);
+    if (fileBindings.length) {
+      throw usageError('--file is only supported when executing a tool, not with --dry-run');
+    }
+    const tool = await fetchToolSchema(ctx.runtime, requestedToolName);
     const errors = validateArguments(tool.parameters, args);
 
     if (errors.length) {
       return ctx.output.emitSuccess({
         command: ctx.spec.command_path.join(' '),
-        data: { valid: false, errors, tool: ctx.args.toolName },
+        data: { valid: false, errors, tool: requestedToolName },
         humanSummary: `Dry run failed: ${errors.length} validation error(s)`,
         hints: [
-          { command: `notis tools exec ${ctx.args.toolName} --get-schema`, reason: 'Review the full parameter schema' },
+          { command: `notis tools exec ${requestedToolName} --get-schema`, reason: 'Review the full parameter schema' },
         ],
         renderHuman: () => errors.map((e) => `  - ${e}`).join('\n'),
       });
@@ -141,64 +442,59 @@ async function toolsExecHandler(ctx) {
 
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(' '),
-      data: { valid: true, tool: ctx.args.toolName, arguments: args },
-      humanSummary: `Dry run passed for ${ctx.args.toolName}`,
+      data: { valid: true, tool: requestedToolName, arguments: args },
+      humanSummary: `Dry run passed for ${requestedToolName}`,
       hints: [
-        { command: `notis tools exec ${ctx.args.toolName} --arguments '${JSON.stringify(args)}'`, reason: 'Execute with these arguments' },
+        { command: `notis tools exec ${requestedToolName} --arguments '${JSON.stringify(args)}'`, reason: 'Execute with these arguments' },
       ],
     });
   }
 
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
-
-  if (ctx.options.watch) {
-    const intervalSec = Math.max(1, parseInt(ctx.options.watch, 10));
-    const intervalMs = intervalSec * 1000;
-    process.on('SIGINT', () => process.exit(0));
-
-    while (true) {
-      try {
-        const result = await runToolCommand({
-          runtime: ctx.runtime,
-          toolName: 'notis_execute_tool',
-          arguments_: { tool_name: ctx.args.toolName, arguments: args },
-          mutating: true,
-          idempotencyKey: nextIdempotencyKey(ctx.globalOptions),
-        });
-        ctx.output.emitSuccess({
-          command: ctx.spec.command_path.join(' '),
-          data: result.payload,
-          humanSummary: `[${new Date().toISOString()}] ${ctx.args.toolName}`,
-          renderHuman: () => JSON.stringify(result.payload, null, 2),
-        });
-      } catch (error) {
-        process.stderr.write(`[${new Date().toISOString()}] Error: ${error.message}\n`);
-      }
-      await new Promise((r) => setTimeout(r, intervalMs));
-    }
-  }
+  ctx.output.emitProgress({
+    phase: 'execute',
+    message: `Calling ${requestedToolName}`,
+  });
 
   const result = await runToolCommand({
     runtime: ctx.runtime,
-    toolName: 'notis_execute_tool',
+    toolName: COMPOSIO_MULTI_EXECUTE_TOOL,
     arguments_: {
-      tool_name: ctx.args.toolName,
-      arguments: args,
+      tools: [{ tool_slug: requestedToolName, arguments: args }],
     },
+    // The server is authoritative about provider/MCP effects. A tool name that
+    // looks like a read is not proof of read-only behavior, so generic
+    // executions always carry a key and use mutation-safe transport retries.
+    // Proven reads are still executed in the read lane by hosted MCP.
     mutating: true,
     idempotencyKey,
+    fileBindings,
+  });
+  ctx.output.emitProgress({
+    phase: 'complete',
+    message: `Finished ${requestedToolName}`,
+    requestId: result.requestId,
   });
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: result.payload,
-    humanSummary: `Executed tool ${ctx.args.toolName}`,
-    meta: { mutating: true, idempotency_key: idempotencyKey },
+    humanSummary: `Executed tool ${requestedToolName}`,
+    requestId: result.requestId,
+    meta: {
+      mutating: targetMutating,
+      mutation_classification: targetMutating === null ? 'unknown' : 'name_hint_only',
+      idempotency_key: idempotencyKey,
+    },
     renderHuman: () => JSON.stringify(result.payload, null, 2),
   });
 }
 
 async function toolsExecParallelHandler(ctx) {
+  const parallelFileBindings = await parseFileBindings(ctx.options.file);
+  if (parallelFileBindings.length) {
+    throw usageError('--file is supported by `notis tools exec` only; exec-parallel accepts JSON calls without file uploads.');
+  }
   const calls = parseMaybeJson(ctx.args.calls, 'calls');
   if (!Array.isArray(calls) || !calls.length) {
     throw usageError('calls must be a non-empty JSON array of {tool_name, arguments} objects');
@@ -208,16 +504,18 @@ async function toolsExecParallelHandler(ctx) {
     if (!call.tool_name || typeof call.tool_name !== 'string') {
       throw usageError(`calls[${i}] missing required "tool_name" string`);
     }
+    // A batch is just as good an escape hatch as a single exec.
+    assertToolNotDelegated(localNotisToolSlug(call.tool_name));
   }
+  ensureLongRunningToolTimeout(ctx, calls.map((call) => localNotisToolSlug(call.tool_name)));
 
   const data = await Promise.all(
     calls.map((call) =>
       runToolCommand({
         runtime: ctx.runtime,
-        toolName: 'notis_execute_tool',
+        toolName: COMPOSIO_MULTI_EXECUTE_TOOL,
         arguments_: {
-          tool_name: call.tool_name,
-          arguments: call.arguments || {},
+          tools: [{ tool_slug: localNotisToolSlug(call.tool_name), arguments: call.arguments || {} }],
         },
         mutating: true,
         idempotencyKey: nextIdempotencyKey(ctx.globalOptions),
@@ -237,58 +535,63 @@ async function toolsExecParallelHandler(ctx) {
 }
 
 async function toolsLinkHandler(ctx) {
-  const apiBase = ctx.runtime.apiBase.replace(/\/+$/, '');
-  let portalBase;
-  try {
-    const parsed = new URL(apiBase);
-    if (parsed.hostname.startsWith('api.')) {
-      parsed.hostname = parsed.hostname.replace(/^api\./, 'app.');
-      portalBase = parsed.origin;
-    } else if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
-      const apiPort = parseInt(parsed.port, 10) || 80;
-      parsed.port = String(apiPort === 3001 ? 3000 : apiPort);
-      portalBase = parsed.origin;
-    } else {
-      portalBase = apiBase;
-    }
-  } catch {
-    portalBase = apiBase.replace('api.', 'app.');
+  const credentials = ctx.options.credentials
+    ? await resolveJsonInput(ctx.options.credentials, 'credentials')
+    : undefined;
+  if (credentials !== undefined && (typeof credentials !== 'object' || credentials === null || Array.isArray(credentials))) {
+    throw usageError('credentials must be a JSON object');
+  }
+
+  const arguments_ = {
+    toolkit: ctx.args.toolkit,
+    ...(ctx.options.reconnect ? { reconnect: true } : {}),
+    ...(ctx.options.connectionId ? { reconnect_connection_id: ctx.options.connectionId } : {}),
+    ...(ctx.options.label ? { label: ctx.options.label } : {}),
+    ...(credentials ? { credentials } : {}),
+  };
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'LOCAL_NOTIS_AUTHENTIFY',
+    arguments_,
+    mutating: true,
+    idempotencyKey,
+  });
+  const payload = result.payload || {};
+  if (payload.status === 'error') {
+    throw usageError(payload.message || `Failed to connect ${ctx.args.toolkit}`, payload);
   }
-  const portalUrl = `${portalBase}/integrations?connect=${encodeURIComponent(ctx.args.toolkit)}`;
+  const authUrl = payload.redirect_url || payload.integrations_url || payload.url || null;
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
-      toolkit: ctx.args.toolkit,
-      auth_url: portalUrl,
+      ...payload,
+      auth_url: authUrl,
     },
-    humanSummary: `Open this URL to connect ${ctx.args.toolkit}`,
+    humanSummary: ctx.options.reconnect
+      ? `Reconnected ${ctx.args.toolkit}`
+      : `Started connection for ${ctx.args.toolkit}`,
     hints: [
       { command: 'notis tools toolkits', reason: 'Verify the toolkit is connected after setup' },
     ],
-    renderHuman: () =>
-      [
-        `Connect ${ctx.args.toolkit}:`,
-        `  ${portalUrl}`,
-        '',
-        'After connecting, verify with:',
-        '  notis tools toolkits',
-      ].join('\n'),
+    meta: { mutating: true, idempotency_key: idempotencyKey },
+    renderHuman: () => JSON.stringify({ ...payload, auth_url: authUrl }, null, 2),
   });
 }
 
 export const toolsCommandSpecs = [
   {
     command_path: ['tools', 'toolkits'],
-    summary: 'List toolkit namespaces available to the active user.',
-    when_to_use: 'Use this before searching or executing generic tools.',
+    summary: 'List toolkit namespaces and connection statuses available to the active user.',
+    when_to_use: 'Use this to inspect connection state before searching or executing generic tools.',
     args_schema: { arguments: [], options: [] },
     examples: ['notis tools toolkits', 'notis tools toolkits --json'],
-    output_schema: 'Returns available toolkit namespaces.',
+    output_schema: 'Returns toolkit_connection_statuses from COMPOSIO_SEARCH_TOOLS, rendered as toolkit rows.',
     mutates: false,
     idempotent: true,
     related_commands: ['notis tools search <query>', 'notis tools describe <tool-name>'],
-    backend_call: { type: 'tool', name: 'notis_find_toolkits' },
+    backend_call: { type: 'tool', name: COMPOSIO_SEARCH_TOOLS },
     handler: toolsToolkitsHandler,
   },
   {
@@ -297,14 +600,14 @@ export const toolsCommandSpecs = [
     when_to_use: 'Use this when you need a generic capability that does not have a first-class CLI command.',
     args_schema: {
       arguments: [{ token: '<query>', description: 'Natural language description of the tool you need.' }],
-      options: [{ flags: '--toolkits <csv-or-json>', description: 'Optional subset of toolkit ids to search.' }],
+      options: [{ flags: '--known-fields <text>', key: 'knownFields', description: 'Optional known field hints, such as channel_name:general or user_email:a@example.com.' }],
     },
-    examples: ['notis tools search "send an email"', 'notis tools search "update framer page" --toolkits mcp-framer'],
-    output_schema: 'Returns tool matches with descriptions and parameter schemas.',
+    examples: ['notis tools search "send an email"', 'notis tools search "post on LinkedIn" --known-fields "platform:linkedin"'],
+    output_schema: 'Returns the full COMPOSIO_SEARCH_TOOLS response. Human output renders canonical names, connection status, and schema availability.',
     mutates: false,
     idempotent: true,
     related_commands: ['notis tools toolkits', 'notis tools exec <tool-name>'],
-    backend_call: { type: 'tool', name: 'notis_find_tools' },
+    backend_call: { type: 'tool', name: COMPOSIO_SEARCH_TOOLS },
     handler: toolsSearchHandler,
   },
   {
@@ -313,14 +616,14 @@ export const toolsCommandSpecs = [
     when_to_use: 'Use this when you know the tool name and want its parameter schema before execution.',
     args_schema: {
       arguments: [{ token: '<tool-name>', description: 'Exact tool name to locate and describe.' }],
-      options: [{ flags: '--toolkits <csv-or-json>', description: 'Optional subset of toolkit ids to search.' }],
+      options: [],
     },
-    examples: ['notis tools describe composio-gmail-default-send_email', 'notis tools describe notis-default-query --toolkits notis-default'],
+    examples: ['notis tools describe composio-gmail-send_email', 'notis tools describe LOCAL_NOTIS_DATABASE_QUERY'],
     output_schema: 'Returns one tool descriptor with name, description, and parameters.',
     mutates: false,
     idempotent: true,
     related_commands: ['notis tools search <query>', 'notis tools exec <tool-name>'],
-    backend_call: { type: 'tool', name: 'notis_find_tools' },
+    backend_call: { type: 'tool', name: COMPOSIO_GET_TOOL_SCHEMAS },
     handler: toolsDescribeHandler,
   },
   {
@@ -331,24 +634,27 @@ export const toolsCommandSpecs = [
       arguments: [{ token: '<tool-name>', description: 'Tool name returned by `notis tools search`.' }],
       options: [
         { flags: '--arguments <json>', description: 'JSON object, @file path, or - for stdin.' },
+        { flags: '--arguments-file <path>', description: 'Read the JSON arguments object from a file.' },
+        { flags: '--file <argument-path=local-path>', description: 'Upload a local file into a file-uploadable tool argument. Repeatable.', collect: true },
         { flags: '--get-schema', description: 'Display the tool parameter schema without executing.' },
         { flags: '--dry-run', description: 'Validate arguments against the tool schema without executing.' },
-        { flags: '--watch <seconds>', description: 'Re-execute on an interval and stream results.' },
       ],
     },
     examples: [
-      'notis tools exec notis-default-query --arguments \'{"database_slug":"tasks","query":{}}\'',
-      'notis tools exec notis-default-query --get-schema',
-      'notis tools exec notis-default-query --dry-run --arguments \'{"database_slug":"tasks","query":{}}\'',
-      'notis tools exec notis-default-query --arguments @query.json',
-      'notis tools exec notis-default-query --arguments - < query.json',
-      'notis tools exec notis-default-query --watch 10 --arguments \'{"database_slug":"tasks","query":{}}\'',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments \'{"database_slug":"tasks","query":{}}\'',
+      'notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments \'{"database_slug":"tasks"}\'',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --get-schema',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments \'{"database_slug":"tasks","query":{}}\'',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments @query.json',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments-file query.json',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments - < query.json',
+      'notis tools exec composio-dropbox-upload_file --arguments \'{"path":"/target/in/dropbox.pdf"}\' --file content=./Invoice.pdf',
     ],
     output_schema: 'Returns the raw tool execution payload.',
     mutates: true,
     idempotent: true,
     related_commands: ['notis tools search <query>', 'notis tools describe <tool-name>', 'notis tools exec-parallel <calls>'],
-    backend_call: { type: 'tool', name: 'notis_execute_tool' },
+    backend_call: { type: 'tool', name: COMPOSIO_MULTI_EXECUTE_TOOL },
     handler: toolsExecHandler,
   },
   {
@@ -359,33 +665,43 @@ export const toolsCommandSpecs = [
       arguments: [
         { token: '<calls>', description: 'JSON array of {tool_name, arguments} objects.' },
       ],
-      options: [],
+      options: [
+        { flags: '--file <argument-path=local-path>', description: 'Unsupported for exec-parallel; use tools exec for file uploads.', collect: true },
+      ],
     },
     examples: [
-      'notis tools exec-parallel \'[{"tool_name":"notis-default-query","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"notis-default-list_databases","arguments":{}}]\'',
+      'notis tools exec-parallel \'[{"tool_name":"LOCAL_NOTIS_DATABASE_QUERY","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"LOCAL_NOTIS_DATABASE_LIST_DATABASES","arguments":{}}]\'',
     ],
     output_schema: 'Returns an array of results, one per tool call.',
     mutates: true,
     idempotent: true,
     related_commands: ['notis tools exec <tool-name>', 'notis tools search <query>'],
-    backend_call: { type: 'tool', name: 'notis_execute_tool' },
+    backend_call: { type: 'tool', name: COMPOSIO_MULTI_EXECUTE_TOOL },
     handler: toolsExecParallelHandler,
   },
   {
     command_path: ['tools', 'link'],
-    summary: 'Get the URL to connect an integration toolkit.',
-    when_to_use: 'Use this when a tool requires authentication with an external service.',
+    summary: 'Connect or reconnect an integration toolkit.',
+    when_to_use: 'Use this when a tool requires authentication or an active connection must be replaced.',
     args_schema: {
       arguments: [{ token: '<toolkit>', description: 'Toolkit name to connect (e.g. github, gmail, slack).' }],
-      options: [],
+      options: [
+        { flags: '--reconnect', description: 'Replace the existing account instead of adding another connection.' },
+        { flags: '--connection-id <id>', key: 'connectionId', description: 'Exact connection id to replace when multiple accounts exist.' },
+        { flags: '--label <label>', description: 'Account label for a new or replacement connection.' },
+        { flags: '--credentials <json>', description: 'Credential JSON object, @file path, or - for stdin. Prefer stdin so secrets do not enter shell history.' },
+      ],
     },
-    examples: ['notis tools link github', 'notis tools link gmail --json'],
-    output_schema: 'Returns the authentication URL for the specified toolkit.',
-    mutates: false,
-    idempotent: true,
-    require_auth: false,
+    examples: [
+      'notis tools link github',
+      'notis tools link dataforseo --reconnect --credentials - < credentials.json',
+    ],
+    output_schema: 'Returns the connection result and an authentication URL when provider authorization is still required.',
+    mutates: true,
+    idempotent: false,
+    require_auth: true,
     related_commands: ['notis tools toolkits', 'notis tools search <query>'],
-    backend_call: { type: 'local' },
+    backend_call: { type: 'tool', name: 'LOCAL_NOTIS_AUTHENTIFY' },
     handler: toolsLinkHandler,
   },
 ];