@notis_ai/cli 0.2.6 → 0.2.7

package/src/command-specs/index.js

@@ -1,14 +1,20 @@
 import { appsCommandSpecs } from './apps.js';
 import { toolsCommandSpecs } from './tools.js';
 import { metaCommandSpecs } from './meta.js';
+import { diagnosticCommandSpecs } from './diagnostics.js';
+import { smokeCommandSpecs } from './smoke.js';
 
 export const GROUP_SUMMARIES = {
   apps: 'Develop, deploy, and submit Notis Apps.',
   tools: 'Discover and execute generic tools exposed through Notis.',
+  debug: 'Inspect effective runtime context, worker identity, and trace costs.',
+  smoke: 'Run deterministic connected-service smoke tests with guaranteed cleanup.',
 };
 
 export const COMMAND_SPECS = [
   ...appsCommandSpecs,
   ...toolsCommandSpecs,
+  ...diagnosticCommandSpecs,
+  ...smokeCommandSpecs,
   ...metaCommandSpecs,
 ];

package/src/command-specs/smoke.js

@@ -0,0 +1,386 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { usageError } from '../runtime/errors.js';
+import {
+  COMPOSIO_MULTI_EXECUTE_TOOL,
+  fetchToolDiscovery,
+  fetchToolSchema,
+  nextIdempotencyKey,
+  runToolCommand,
+} from './helpers.js';
+import { mintEntitlementOverride, unwrapToolExecutionPayload } from './diagnostics.js';
+import { hashFileSha256, parseFileBindings } from './tools.js';
+
+function discoveryNames(payload) {
+  return [...new Set(
+    (payload.results || []).flatMap((result) => [
+      ...(result.primary_tool_slugs || []),
+      ...(result.related_tool_slugs || []),
+    ]).filter(Boolean),
+  )];
+}
+
+function selectDropboxTools(payloads) {
+  const names = [...new Set(payloads.flatMap(discoveryNames))];
+  const find = (preferred, ...needles) => (
+    names.find((name) => name.toUpperCase() === preferred)
+    || names.find((name) => {
+    const upper = name.toUpperCase();
+    return upper.includes('DROPBOX')
+      && !upper.includes('ALPHA')
+      && needles.every((needle) => upper.includes(needle));
+    })
+  );
+  const tools = {
+    upload: find('DROPBOX_UPLOAD_FILE', 'UPLOAD', 'FILE'),
+    metadata: find('DROPBOX_GET_METADATA', 'GET', 'METADATA'),
+    read: find('DROPBOX_READ_FILE', 'READ', 'FILE')
+      || find('DROPBOX_DOWNLOAD_FILE', 'DOWNLOAD', 'FILE'),
+    delete: find('DROPBOX_DELETE_FILE', 'DELETE', 'FILE'),
+  };
+  const missing = Object.entries(tools).filter(([, value]) => !value).map(([key]) => key);
+  if (missing.length) {
+    throw usageError(`Dropbox smoke could not discover: ${missing.join(', ')}.`);
+  }
+  return tools;
+}
+
+async function fetchDiscoveryWithRetry(ctx, useCase, knownFields) {
+  const maxAttempts = 3;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await fetchToolDiscovery(ctx.runtime, useCase, knownFields);
+    } catch (error) {
+      if (!error?.retryable || attempt === maxAttempts) throw error;
+      ctx.output.emitProgress({
+        phase: 'discover-retry',
+        message: `Tool discovery transiently failed; retrying (${attempt}/${maxAttempts - 1})`,
+        requestId: error?.details?.request_id || null,
+      });
+      await delay(250 * (2 ** (attempt - 1)));
+    }
+  }
+  throw usageError('Dropbox tool discovery exhausted its retries.');
+}
+
+function targetResponse(payload) {
+  const unwrapped = unwrapToolExecutionPayload(payload);
+  if (unwrapped?.results?.[0]?.response) return unwrapped.results[0].response;
+  if (payload?.data?.results?.[0]?.response) return payload.data.results[0].response;
+  if (payload?.results?.[0]?.response) return payload.results[0].response;
+  return unwrapped;
+}
+
+function requireSuccessfulResponse(payload, phase) {
+  const response = targetResponse(payload);
+  if (!response || response.successful === false || payload?.successful === false) {
+    throw usageError(`Dropbox ${phase} failed.`, { phase, response });
+  }
+  return response.data ?? response;
+}
+
+async function executeDropboxTool(ctx, toolName, args, {
+  mutating,
+  fileBindings = [],
+  phase,
+}) {
+  ctx.output.emitProgress({ phase, message: `${phase} via ${toolName}` });
+  const baseIdempotencyKey = mutating ? nextIdempotencyKey(ctx.globalOptions) : null;
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: COMPOSIO_MULTI_EXECUTE_TOOL,
+    arguments_: { tools: [{ tool_slug: toolName, arguments: args }] },
+    mutating,
+    idempotencyKey: baseIdempotencyKey ? `${baseIdempotencyKey}:${phase}` : null,
+    fileBindings,
+  });
+  return result;
+}
+
+function remotePath(folder, name) {
+  const normalizedFolder = `/${String(folder || '/Notis Tests/cli-file-upload')
+    .split('/')
+    .filter(Boolean)
+    .join('/')}`;
+  return `${normalizedFolder}/${name}`;
+}
+
+async function smokeFileUploadHandler(ctx) {
+  const tempDir = mkdtempSync(join(tmpdir(), 'notis-smoke-file-upload-'));
+  const marker = `${new Date().toISOString().replaceAll(/[-:.]/g, '')}-${randomUUID().slice(0, 8)}`;
+  const generatedFixture = !ctx.options.sourceFile;
+  const fixturePath = ctx.options.sourceFile || join(tempDir, `notis-file-upload-${marker}.txt`);
+  if (generatedFixture) {
+    writeFileSync(
+      fixturePath,
+      `Notis Dropbox file-upload smoke\nmarker=${marker}\nunicode=été Zürich 東京\n`,
+      'utf-8',
+    );
+  }
+  const localHash = await hashFileSha256(fixturePath);
+  const localBytes = readFileSync(fixturePath);
+  const destination = remotePath(
+    ctx.options.remoteFolder,
+    `notis-file-upload-${marker}-${basename(fixturePath)}`,
+  );
+  const result = {
+    marker,
+    destination,
+    local: { bytes: localBytes.length, sha256: localHash },
+    phases: [],
+    request_ids: {},
+    cleanup: { attempted: false, deleted: false, not_found_verified: false },
+    parity: null,
+  };
+  let uploadAttempted = false;
+  let deleted = false;
+  let revision = null;
+  let tools;
+
+  try {
+    ctx.output.emitProgress({ phase: 'discover', message: 'Resolving Dropbox upload, metadata, read, and delete capabilities' });
+    // Discover sequentially. Both calls can materialize the same provider session,
+    // and racing that initialization has caused otherwise healthy smoke runs to
+    // fail with a transient "Server disconnected" before any upload occurred.
+    const discoveries = [
+      await fetchDiscoveryWithRetry(
+        ctx,
+        'Upload a local file to Dropbox, get its exact metadata, and read the same file bytes back',
+        'path, content, strict_conflict',
+      ),
+      await fetchDiscoveryWithRetry(
+        ctx,
+        'Delete one Dropbox file by exact canonical path and parent revision, then verify metadata reports path not found',
+        'path, parent_rev',
+      ),
+    ];
+    tools = selectDropboxTools(discoveries);
+    const uploadSchema = await fetchToolSchema(ctx.runtime, tools.upload);
+    if (uploadSchema.parameters?.properties?.content?.file_uploadable !== true) {
+      throw usageError(`${tools.upload} content is not marked file_uploadable.`);
+    }
+
+    if (ctx.options.parityUser) {
+      const minted = await mintEntitlementOverride(ctx, ctx.options.parityUser);
+      ctx.runtime.debugEntitlementOverride = minted.override;
+      result.parity = {
+        requested: true,
+        expected_parity_hash: minted.parity_hash,
+        reference_scope_type: minted.reference_scope_type,
+        persistent: false,
+      };
+    }
+
+    const fileBindings = await parseFileBindings([`content=${fixturePath}`]);
+    uploadAttempted = true;
+    const upload = await executeDropboxTool(
+      ctx,
+      tools.upload,
+      { path: destination, strict_conflict: true, mode: 'add', autorename: false },
+      { mutating: true, fileBindings, phase: 'upload' },
+    );
+    result.request_ids.upload = upload.requestId;
+    const uploadData = requireSuccessfulResponse(upload.payload, 'upload');
+    const appliedParity = upload.payload?.debug_entitlement_override;
+    if (result.parity) {
+      if (!appliedParity?.applied || appliedParity.parity_hash !== result.parity.expected_parity_hash) {
+        throw usageError('Backend did not assert the requested entitlement parity before upload.');
+      }
+      result.parity.applied = true;
+      result.parity.expires_at = appliedParity.expires_at;
+    }
+    revision = uploadData.rev;
+    result.upload = {
+      path: uploadData.path_display,
+      revision,
+      bytes: uploadData.size,
+      provider_content_hash: uploadData.content_hash,
+    };
+    result.phases.push('upload');
+
+    const metadata = await executeDropboxTool(
+      ctx,
+      tools.metadata,
+      { path: uploadData.path_display || destination },
+      { mutating: false, phase: 'metadata' },
+    );
+    result.request_ids.metadata = metadata.requestId;
+    const metadataData = requireSuccessfulResponse(metadata.payload, 'metadata').metadata;
+    if (!metadataData || metadataData.rev !== revision || Number(metadataData.size) !== localBytes.length) {
+      throw usageError('Dropbox metadata did not match the uploaded file revision and byte count.');
+    }
+    result.metadata = {
+      path: metadataData.path_display,
+      revision: metadataData.rev,
+      bytes: metadataData.size,
+    };
+    result.phases.push('metadata');
+
+    const read = await executeDropboxTool(
+      ctx,
+      tools.read,
+      { path: metadataData.path_display },
+      { mutating: false, phase: 'download' },
+    );
+    result.request_ids.download = read.requestId;
+    const readData = requireSuccessfulResponse(read.payload, 'read');
+    const signedUrl = readData.content?.s3url;
+    if (!signedUrl) throw usageError('Dropbox read did not return a temporary download URL.');
+    const downloadResponse = await fetch(signedUrl);
+    if (!downloadResponse.ok) {
+      throw usageError(`Dropbox temporary download returned HTTP ${downloadResponse.status}.`);
+    }
+    const downloaded = Buffer.from(await downloadResponse.arrayBuffer());
+    const downloadedHash = createHash('sha256').update(downloaded).digest('hex');
+    if (downloadedHash !== localHash) {
+      throw usageError('Downloaded Dropbox bytes did not match the uploaded fixture hash.');
+    }
+    result.download = {
+      bytes: downloaded.length,
+      sha256: downloadedHash,
+      hash_match: true,
+    };
+    result.phases.push('download');
+
+    result.cleanup.attempted = true;
+    const deletion = await executeDropboxTool(
+      ctx,
+      tools.delete,
+      { path: metadataData.path_display, parent_rev: revision },
+      { mutating: true, phase: 'delete' },
+    );
+    result.request_ids.delete = deletion.requestId;
+    requireSuccessfulResponse(deletion.payload, 'delete');
+    result.cleanup.deleted = true;
+    result.phases.push('delete');
+
+    const finalMetadata = await executeDropboxTool(
+      ctx,
+      tools.metadata,
+      { path: metadataData.path_display },
+      { mutating: false, phase: 'verify-not-found' },
+    );
+    result.request_ids.verify_not_found = finalMetadata.requestId;
+    const finalResponse = targetResponse(finalMetadata.payload);
+    const finalText = JSON.stringify(finalResponse);
+    if (finalResponse?.successful !== false || !finalText.includes('path/not_found')) {
+      throw usageError('Dropbox cleanup verification did not return path/not_found.');
+    }
+    result.cleanup.not_found_verified = true;
+    deleted = true;
+    result.phases.push('verify-not-found');
+    ctx.output.emitProgress({ phase: 'complete', message: 'Dropbox file-upload smoke passed with verified cleanup' });
+    return ctx.output.emitSuccess({
+      command: ctx.spec.command_path.join(' '),
+      data: { ...result, tools },
+      humanSummary: `Dropbox file-upload smoke passed for ${destination}; SHA-256 matched and cleanup was verified.`,
+      requestId: result.request_ids.verify_not_found,
+      meta: { mutating: true, cleaned_up: true },
+      renderHuman: () => JSON.stringify({ ...result, tools }, null, 2),
+    });
+  } catch (error) {
+    if (error && typeof error === 'object') {
+      error.details = {
+        ...(error.details || {}),
+        smoke_result: { ...result, tools },
+      };
+    }
+    throw error;
+  } finally {
+    if (uploadAttempted && !result.cleanup.not_found_verified && tools) {
+      result.cleanup.attempted = true;
+      try {
+        let cleanupRevision = revision;
+        if (!cleanupRevision) {
+          const recoveryMetadata = await executeDropboxTool(
+            ctx,
+            tools.metadata,
+            { path: destination },
+            { mutating: false, phase: 'recover-cleanup-metadata' },
+          );
+          result.request_ids.recover_cleanup_metadata = recoveryMetadata.requestId;
+          const recoveryResponse = targetResponse(recoveryMetadata.payload);
+          const recoveryText = JSON.stringify(recoveryResponse);
+          if (recoveryResponse?.successful === false && recoveryText.includes('path/not_found')) {
+            result.cleanup.deleted = true;
+            result.cleanup.not_found_verified = true;
+          } else {
+            const recoveryData = requireSuccessfulResponse(recoveryMetadata.payload, 'cleanup metadata');
+            cleanupRevision = recoveryData.metadata?.rev || recoveryData.rev;
+            if (!cleanupRevision) {
+              throw usageError('Dropbox cleanup metadata did not return the uploaded file revision.');
+            }
+          }
+        }
+        if (!result.cleanup.not_found_verified) {
+          const cleanup = await executeDropboxTool(
+            ctx,
+            tools.delete,
+            { path: destination, parent_rev: cleanupRevision },
+            { mutating: true, phase: 'cleanup-after-failure' },
+          );
+          result.request_ids.cleanup_after_failure = cleanup.requestId;
+          const cleanupResponse = targetResponse(cleanup.payload);
+          const cleanupText = JSON.stringify(cleanupResponse);
+          result.cleanup.deleted = (
+            cleanupResponse?.successful === true
+            || cleanupText.includes('path/not_found')
+          );
+        }
+        const verification = await executeDropboxTool(
+          ctx,
+          tools.metadata,
+          { path: destination },
+          { mutating: false, phase: 'verify-cleanup-after-failure' },
+        );
+        result.request_ids.verify_cleanup_after_failure = verification.requestId;
+        const verificationResponse = targetResponse(verification.payload);
+        const verificationText = JSON.stringify(verificationResponse);
+        result.cleanup.not_found_verified = (
+          verificationResponse?.successful === false
+          && verificationText.includes('path/not_found')
+        );
+        deleted = result.cleanup.not_found_verified;
+        result.cleanup.deleted = deleted;
+      } catch {
+        deleted = false;
+        result.cleanup.deleted = false;
+      }
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+export const smokeCommandSpecs = [
+  {
+    command_path: ['smoke', 'file-upload'],
+    summary: 'Run a complete Dropbox upload/read/hash/delete smoke test.',
+    when_to_use: 'Use to prove the local-file bridge and connected Dropbox behavior under the current or parity entitlement context.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--source-file <path>', description: 'Use an existing local fixture instead of generating one.' },
+        { flags: '--remote-folder <path>', description: 'Unique Dropbox parent folder (default /Notis Tests/cli-file-upload).' },
+        { flags: '--parity-user <user>', description: 'Apply this reference user’s effective plan for only the smoke requests.' },
+      ],
+    },
+    examples: [
+      'notis smoke file-upload --json',
+      'notis smoke file-upload --parity-user user@example.com --json',
+    ],
+    output_schema: 'Returns structured phase results, request ids, metadata, hashes, parity proof, and cleanup verification.',
+    mutates: true,
+    idempotent: true,
+    related_commands: ['notis debug user-context <user>', 'notis debug entitlement-override <reference-user>'],
+    backend_call: { type: 'tool-discovery', name: 'Dropbox upload/read/delete capabilities' },
+    handler: smokeFileUploadHandler,
+  },
+];

package/src/command-specs/tools.js

@@ -17,7 +17,7 @@ import {
   validateArguments,
 } from './helpers.js';
 
-async function resolveJsonInput(value, label) {
+export async function resolveJsonInput(value, label) {
   if (!value) return undefined;
 
   if (value === '-') {
@@ -39,6 +39,159 @@ 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.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',
@@ -67,7 +220,7 @@ function guessContentType(filePath) {
   return EXTENSION_CONTENT_TYPES.get(lower.slice(dotIndex)) || 'application/octet-stream';
 }
 
-async function hashFileSha256(localPath) {
+export async function hashFileSha256(localPath) {
   const hash = createHash('sha256');
   for await (const chunk of createReadStream(localPath)) {
     hash.update(chunk);
@@ -123,7 +276,7 @@ async function parseFileBindingSpec(spec, index) {
   };
 }
 
-async function parseFileBindings(rawFileOptions) {
+export async function parseFileBindings(rawFileOptions) {
   const values = Array.isArray(rawFileOptions)
     ? rawFileOptions
     : (rawFileOptions ? [rawFileOptions] : []);
@@ -227,7 +380,12 @@ async function toolsDescribeHandler(ctx) {
 
 async function toolsExecHandler(ctx) {
   const requestedToolName = localNotisToolSlug(ctx.args.toolName);
+  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) {
@@ -243,10 +401,16 @@ async function toolsExecHandler(ctx) {
     });
   }
 
-  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) {
     if (fileBindings.length) {
@@ -278,6 +442,10 @@ async function toolsExecHandler(ctx) {
   }
 
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  ctx.output.emitProgress({
+    phase: 'execute',
+    message: `Calling ${requestedToolName}`,
+  });
 
   const result = await runToolCommand({
     runtime: ctx.runtime,
@@ -285,16 +453,26 @@ async function toolsExecHandler(ctx) {
     arguments_: {
       tools: [{ tool_slug: requestedToolName, arguments: args }],
     },
-    mutating: true,
-    idempotencyKey,
+    mutating: targetMutating !== false,
+    idempotencyKey: targetMutating === false ? null : 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 ${requestedToolName}`,
-    meta: { mutating: true, idempotency_key: idempotencyKey },
+    requestId: result.requestId,
+    meta: {
+      mutating: targetMutating,
+      mutation_classification: targetMutating === null ? 'unknown' : 'inferred',
+      idempotency_key: targetMutating === false ? null : idempotencyKey,
+    },
     renderHuman: () => JSON.stringify(result.payload, null, 2),
   });
 }
@@ -441,6 +619,7 @@ 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.' },
@@ -452,6 +631,7 @@ export const toolsCommandSpecs = [
       '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',
     ],