@notis_ai/cli 0.2.17 → 0.2.19

package/src/command-specs/handover.js

@@ -2,9 +2,17 @@
  * `notis handover` -- give the branch you are on to a Notis agent.
  *
  * The coding agent already sitting in the user's terminal is the caller here.
- * It pushes the branch, then hands the task to whichever agent the user picked:
- * the hosted Notis agent, or their own Codex/Claude Code running in the Notis
- * cloud sandbox or on their Mac.
+ * It pushes the branch, then starts a Notis thread for the task. The caller
+ * names who runs it and how, from the user's words, so the choice is never left
+ * to the Manager: `--route notis|codex|claude` becomes a plain sentence at the
+ * end of the task ("Use Codex for this task."), so it wins like it does in a
+ * chat message, and `--intelligence` and `--speed` become the thread's
+ * settings. `auto` hands a choice back to Notis, only when the user asked.
+ *
+ * The thread is started with `LOCAL_NOTIS_CONTROL_THREADS` create, the same
+ * operation voice, the hosted MCP and the agents use to start work. It shows up
+ * in the Manager like any other conversation, and its request receipt is what
+ * `handover status` reads back.
  *
  * The CLI deliberately does not create the cloud workspace itself. Doing so
  * would hard-code the Conductor app's database schema and script paths into the
@@ -15,6 +23,8 @@
  * on and getting it to origin.
  */
 
+import { randomUUID } from 'node:crypto';
+
 import { CliError, EXIT_CODES, usageError } from '../runtime/errors.js';
 import {
   commitWorkingTree,
@@ -25,16 +35,40 @@ import {
 import { assertNotDelegated } from '../runtime/delegated-context.js';
 import { fetchToolSchema, nextIdempotencyKey, runToolCommand } from './helpers.js';
 
-const HAND_OVER_TOOL = 'LOCAL_NOTIS_HAND_OVER';
-const SEARCH_THREADS_TOOL = 'LOCAL_NOTIS_SEARCH_CODING_AGENT_THREADS';
+const THREADS_TOOL = 'LOCAL_NOTIS_CONTROL_THREADS';
 
-const ROUTES = ['notis', 'auto', 'codex_cloud', 'claude_cloud', 'codex_local', 'claude_local'];
+// What --route accepts and advertises. `auto` lets Notis pick the agent.
+const ROUTES = ['notis', 'codex', 'claude', 'auto'];
+// Values from before Notis picked the agent itself, the retired Mac runtimes
+// among them. Still accepted, so scripts and agents that learned them keep
+// working, but never shown in help, examples or errors. Each one now means the
+// agent it names.
+const LEGACY_ROUTES = new Map([
+  ['codex_cloud', 'codex'],
+  ['codex_local', 'codex'],
+  ['claude_cloud', 'claude'],
+  ['claude_local', 'claude'],
+]);
+const ROUTE_LABELS = { notis: 'Notis', codex: 'Codex', claude: 'Claude' };
 const BRANCH_MODES = ['new', 'same'];
+// The thread's settings. `auto` lets Notis pick the intelligence.
+const INTELLIGENCE = ['low', 'medium', 'high', 'auto'];
+const SPEEDS = ['normal', 'priority', 'flex'];
+// Who runs the hand-over and how. All three are required, so the caller turns
+// the user's words into a choice rather than leaving it to the Manager.
+const CHOICES = [
+  ['route', '--route', ROUTES],
+  ['intelligence', '--intelligence', INTELLIGENCE],
+  ['speed', '--speed', SPEEDS],
+];
 
-// A cloud coding agent takes minutes to start, and the hand-over POST itself
-// queues a manager turn. 30s is the CLI default and is not enough headroom.
+// A cloud coding agent takes minutes to start, and creating the thread admits
+// its first turn. 30s is the CLI default and is not enough headroom.
 const HANDOVER_TIMEOUT_MS = 120_000;
 
+const TITLE_LENGTH = 120;
+const RECENT_THREADS = 20;
+
 /**
  * Preflight outcomes that mean "this account cannot hand over", as opposed to
  * "something went wrong on the way to asking". A tool denied by surface policy
@@ -44,6 +78,27 @@ const HANDOVER_TIMEOUT_MS = 120_000;
  */
 const HANDOVER_UNAVAILABLE_CODES = new Set(['usage_error', 'forbidden']);
 
+/** A legacy route as the agent it now means; anything else unchanged. */
+function normalizeRoute(route) {
+  return LEGACY_ROUTES.get(route) || route;
+}
+
+/** Who the hand-over went to, in words, for progress lines and the summary. */
+function describeRoute(route) {
+  if (route === 'auto') return 'Notis, which picks the agent';
+  return ROUTE_LABELS[route] || route;
+}
+
+/**
+ * The task as the thread receives it. A named agent becomes a plain sentence at
+ * the end ("Use Codex for this task."), so the user's choice wins like it does
+ * in a chat message; `auto` adds nothing and Notis picks the agent.
+ */
+function routedInstruction(instruction, route) {
+  const name = ROUTE_LABELS[route];
+  return name ? `${instruction}\n\nUse ${name} for this task.` : instruction;
+}
+
 /**
  * Quote a value for the command line the receiving agent is told to run.
  *
@@ -106,6 +161,66 @@ function buildInstruction({ task, repository, branchMode, repoSlug }) {
   ].join('\n');
 }
 
+/** The task's first line, short enough to read in the Manager's thread list. */
+function threadTitle(task) {
+  const line = task.split('\n').find((part) => part.trim()) || task;
+  const title = line.replace(/\s+/g, ' ').trim();
+  return title.length > TITLE_LENGTH ? `${title.slice(0, TITLE_LENGTH - 3)}...` : title;
+}
+
+/** The intelligence and speed as the thread's settings. */
+function threadSettings(intelligence, speed) {
+  return intelligence === 'auto' ? { auto: true, speed } : { mode: intelligence, speed };
+}
+
+/** The intelligence and speed, in words, for progress lines and the summary. */
+function describeSettings(intelligence, speed) {
+  const level = intelligence === 'auto' ? 'Notis picks the intelligence' : `${intelligence} intelligence`;
+  return `${level}, ${speed} speed`;
+}
+
+/**
+ * The command that starts this hand-over again: with its key, the same
+ * request; without one, a new request.
+ */
+function startCommand({ task, branchMode, route, intelligence, speed, repoSlug }, idempotencyKey = null) {
+  return [
+    ...(idempotencyKey ? ['notis --idempotency-key', shellSingleQuote(idempotencyKey)] : ['notis']),
+    'handover start', shellSingleQuote(task),
+    '--route', route, '--intelligence', intelligence, '--speed', speed,
+    ...(branchMode === 'new' ? [] : ['--branch-mode', branchMode]),
+    ...(repoSlug ? ['--repo', shellSingleQuote(repoSlug)] : []),
+  ].join(' ');
+}
+
+/**
+ * How to settle a start whose outcome is unknown. Asking again with the same
+ * key settles it only when the answer was lost on the way (a timeout, a dropped
+ * connection) or the first attempt is still running. Any other uncertain answer
+ * is kept under the key and replayed as it is, so check whether the work
+ * started, and hand it over afresh only if it did not. A refusal gets neither:
+ * asking again cannot change it.
+ */
+function recoveryHints(error, command, idempotencyKey, requestIds = []) {
+  const serverCode = error.details?.error?.code;
+  if (['network_timeout', 'network_error'].includes(error.code) || serverCode === 'idempotency_in_progress') {
+    return [{
+      command: startCommand(command, idempotencyKey),
+      reason: 'Ask again with the same key: it returns this hand-over\'s answer and never starts the work twice',
+    }];
+  }
+  if (['backend_error', 'handover_unconfirmed'].includes(error.code) || serverCode === 'idempotency_outcome_unknown') {
+    return [
+      {
+        command: requestIds[0] ? `notis handover status ${requestIds[0]}` : 'notis handover status',
+        reason: 'Check whether the hand-over started before anything else',
+      },
+      { command: startCommand(command), reason: 'Only if it did not start: hand it over again as a new request' },
+    ];
+  }
+  return [];
+}
+
 async function handoverStartHandler(ctx) {
   // First statement on purpose. Everything below spends the user's credits and
   // starts real work; the check that this is a person's terminal comes first.
@@ -121,23 +236,45 @@ async function handoverStartHandler(ctx) {
     throw usageError(`--branch-mode must be one of: ${BRANCH_MODES.join(', ')}`, { branchMode });
   }
 
-  const route = ctx.options.route || 'notis';
-  if (!ROUTES.includes(route)) {
-    throw usageError(`--route must be one of: ${ROUTES.join(', ')}`, { route });
+  const choice = {
+    route: ctx.options.route === undefined ? undefined : normalizeRoute(ctx.options.route),
+    intelligence: ctx.options.intelligence,
+    speed: ctx.options.speed,
+  };
+  for (const [name, flag, values] of CHOICES) {
+    if (choice[name] !== undefined && !values.includes(choice[name])) {
+      throw usageError(`${flag} must be one of: ${values.join(', ')}`, { [name]: ctx.options[name] });
+    }
+  }
+  // No defaults: a missing choice stops here, before git is touched, and the
+  // refusal names every one still to make.
+  const missing = CHOICES.filter(([name]) => choice[name] === undefined);
+  if (missing.length) {
+    throw usageError(
+      'Choose who runs the hand-over and how from the user\'s words, then pass '
+      + `${missing.map(([, flag, values]) => `${flag} ${values.join('|')}`).join(', ')}.`,
+      { missing: missing.map(([, flag]) => flag) },
+    );
+  }
+  const { route, intelligence, speed } = choice;
+  // Codex and Claude have no flex speed, and with auto Notis may pick either,
+  // which would then inherit it.
+  if (speed === 'flex' && route !== 'notis') {
+    throw usageError('--speed flex runs on Notis only; use --route notis, or --speed normal.', { route, speed });
   }
 
   const repository = inspectRepository(ctx.options.cwd || process.cwd());
 
   // Ask whether the hand-over is even allowed before touching git. Everything
   // below this line is irreversible from the user's point of view -- a commit
-  // and a push -- and during rollout the common answer is "not available",
-  // which would otherwise leave a `wip:` commit on their remote for a hand-over
-  // that never happened.
+  // and a push -- and a server that does not offer the tool here would
+  // otherwise leave a `wip:` commit on their remote for a hand-over that never
+  // happened.
   //
   // Only an explicit refusal blocks: a network or schema hiccup must not stop a
   // hand-over that would have worked.
   try {
-    await fetchToolSchema(ctx.runtime, HAND_OVER_TOOL);
+    await fetchToolSchema(ctx.runtime, THREADS_TOOL);
   } catch (error) {
     if (error instanceof CliError && HANDOVER_UNAVAILABLE_CODES.has(error.code)) {
       throw new CliError({
@@ -216,33 +353,71 @@ async function handoverStartHandler(ctx) {
     throw error;
   }
 
-  const instruction = buildInstruction({
-    task,
-    repository,
-    branchMode,
-    repoSlug: ctx.options.repo || null,
-  });
+  const repoSlug = ctx.options.repo || null;
+  const instruction = buildInstruction({ task, repository, branchMode, repoSlug });
 
-  ctx.output.emitProgress({ phase: 'handover', message: `Handing over to ${route}` });
-  const result = await runToolCommand({
-    runtime: {
-      ...ctx.runtime,
-      // Raise the floor, never pin: an explicit --timeout-ms must still win.
-      timeoutMs: Math.max(ctx.runtime.timeoutMs || 0, HANDOVER_TIMEOUT_MS),
-    },
-    toolName: HAND_OVER_TOOL,
-    arguments_: { instruction, agent_routing: route },
-    mutating: true,
-    idempotencyKey: nextIdempotencyKey(ctx.globalOptions),
+  // One key names this hand-over end to end: the HTTP retry key and, prefixed,
+  // the thread request. Resending it returns the thread the first attempt made.
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const requestKey = `handover:${idempotencyKey}`;
+  const command = { task, branchMode, route, intelligence, speed, repoSlug };
+
+  ctx.output.emitProgress({
+    phase: 'handover',
+    message: `Handing over to ${describeRoute(route)} (${describeSettings(intelligence, speed)})`,
   });
+  let result;
+  try {
+    result = await runToolCommand({
+      runtime: {
+        ...ctx.runtime,
+        // Raise the floor, never pin: an explicit --timeout-ms must still win.
+        timeoutMs: Math.max(ctx.runtime.timeoutMs || 0, HANDOVER_TIMEOUT_MS),
+      },
+      toolName: THREADS_TOOL,
+      arguments_: {
+        action: 'create',
+        request_id: requestKey,
+        instructions: routedInstruction(instruction, route),
+        title: threadTitle(task),
+        settings: threadSettings(intelligence, speed),
+      },
+      mutating: true,
+      idempotencyKey,
+    });
+  } catch (error) {
+    // A failed call may still have started the thread. Say how to find out
+    // without starting the work twice.
+    if (error instanceof CliError) {
+      error.details = { ...error.details, request_key: requestKey };
+      error.hints = [...(error.hints || []), ...recoveryHints(error, command, idempotencyKey)];
+    }
+    throw error;
+  }
 
   const payload = result?.payload ?? {};
   if (payload.status === 'error') {
     throw new CliError({
       code: payload.error_code || 'handover_failed',
-      message: payload.message || 'Notis could not start the hand-over.',
+      message: payload.message || `Notis could not start the hand-over (${payload.error_code || 'error'}).`,
       exitCode: EXIT_CODES.backend,
-      details: payload.details || {},
+      details: { request_key: requestKey, http_status: payload.http_status ?? null },
+    });
+  }
+  if (payload.status !== 'accepted') {
+    const requestIds = payload.request_ids || [];
+    throw new CliError({
+      code: 'handover_unconfirmed',
+      message:
+        'Notis could not confirm that the hand-over started. It may be running already, '
+        + 'so check its status before handing it over again.',
+      exitCode: EXIT_CODES.backend,
+      details: {
+        request_key: requestKey,
+        request_ids: requestIds,
+        cause: payload.error_code || null,
+      },
+      hints: recoveryHints({ code: 'handover_unconfirmed' }, command, idempotencyKey, requestIds),
     });
   }
 
@@ -255,21 +430,29 @@ async function handoverStartHandler(ctx) {
     branch_mode: branchMode,
     head: repository.head,
     wip_commit: wipCommit,
-    agent_routing: payload.agent_routing || route,
-    interaction_id: payload.interaction_id || null,
+    agent_routing: route,
+    intelligence,
+    speed,
+    request_id: payload.request_id || null,
+    request_key: payload.request_key || requestKey,
+    row_id: payload.row_id || null,
     thread_id: payload.thread_id || null,
+    interaction_id: payload.interaction_id || null,
   };
 
   return ctx.output.emitSuccess({
     command: 'handover start',
     data,
     humanSummary:
-      `Handed ${data.branch} over to ${data.agent_routing} ` +
-      `(${branchMode === 'same' ? 'continuing the branch' : 'new branch from it'}).`,
+      `Handed ${data.branch} over to ${describeRoute(data.agent_routing)} `
+      + `(${describeSettings(intelligence, speed)}; `
+      + `${branchMode === 'same' ? 'continuing the branch' : 'new branch from it'}).`,
     hints: [
-      { command: 'notis handover status', reason: 'See what the agent is doing' },
+      ...(data.request_id
+        ? [{ command: `notis handover status ${data.request_id}`, reason: 'Follow the hand-over and read its result' }]
+        : []),
       {
-        command: `git fetch origin ${repository.branch}`,
+        command: `git fetch origin ${shellSingleQuote(repository.branch)}`,
         reason: 'Pull the agent\'s commits back down when it has pushed',
       },
     ],
@@ -277,32 +460,83 @@ async function handoverStartHandler(ctx) {
   });
 }
 
+function eventText(event) {
+  const body = event?.body || {};
+  const message = body.message || {};
+  const text = message.text || message.body || message.content || body.text || '';
+  return typeof text === 'string' ? text : JSON.stringify(text);
+}
+
 async function handoverStatusHandler(ctx) {
+  const requestId = (ctx.args.requestId || '').trim();
   const result = await runToolCommand({
     runtime: ctx.runtime,
-    toolName: SEARCH_THREADS_TOOL,
-    arguments_: {
-      ...(ctx.options.provider ? { provider: ctx.options.provider } : {}),
-      ...(ctx.options.refresh ? { refresh: true } : {}),
-    },
+    toolName: THREADS_TOOL,
+    arguments_: requestId
+      ? { action: 'request', request_id: requestId }
+      : { action: 'list', filters: { activity: 'running' }, limit: RECENT_THREADS },
     mutating: false,
+    // The tool also writes, so the server asks every call for a key. A fresh
+    // one, never --idempotency-key: a reused key would replay a cached, stale
+    // read instead of asking again.
+    idempotencyKey: randomUUID(),
+    sendIdempotencyKeyWhenReading: true,
   });
 
   const payload = result?.payload ?? {};
-  const threads = Array.isArray(payload.threads) ? payload.threads : [];
+  if (payload.status === 'error') {
+    throw new CliError({
+      code: payload.error_code || 'handover_status_failed',
+      message: payload.message || `Notis could not read the hand-over (${payload.error_code || 'error'}).`,
+      exitCode: EXIT_CODES.backend,
+      details: { request_id: requestId || null, http_status: payload.http_status ?? null },
+    });
+  }
 
+  if (!requestId) {
+    // The running filter applies to the most recent threads only, so say so
+    // rather than claiming nothing runs anywhere.
+    const threads = Array.isArray(payload.threads) ? payload.threads : [];
+    const summary = threads.length
+      ? `${threads.length} of your ${RECENT_THREADS} most recent threads running.`
+      : `None of your ${RECENT_THREADS} most recent threads is running.`;
+    return ctx.output.emitSuccess({
+      command: 'handover status',
+      data: { threads },
+      humanSummary: summary,
+      hints: [
+        { command: 'notis handover status <request-id>', reason: 'Read one hand-over\'s progress and result' },
+      ],
+      renderHuman: () => [
+        summary,
+        ...threads.map((thread) => `  ${thread.id}  ${thread.title || '(untitled)'}`),
+      ].join('\n'),
+      meta: { mutating: false },
+    });
+  }
+
+  const events = Array.isArray(payload.events) ? payload.events : [];
+  const finished = events.find((event) => event?.terminal);
+  const summary = finished
+    ? `The hand-over finished (${finished.kind}).`
+    : `The hand-over is still running (${events.length} update(s) so far).`;
   return ctx.output.emitSuccess({
     command: 'handover status',
     data: payload,
-    humanSummary: threads.length
-      ? `${threads.length} coding-agent thread(s).`
-      : 'No coding-agent threads yet. A hosted Notis hand-over shows up in the portal instead.',
-    hints: [
-      {
-        command: 'notis tools exec LOCAL_NOTIS_OBSERVE_CODING_AGENT_THREAD --arguments \'{"external_session_id":"...","question":"..."}\'',
-        reason: 'Ask a focused question about one thread',
-      },
-    ],
+    humanSummary: summary,
+    hints: payload.has_more
+      ? [{
+        command:
+          `notis tools exec ${THREADS_TOOL} --arguments '${JSON.stringify({
+            action: 'request', request_id: requestId, after: payload.next_cursor,
+          })}'`,
+        reason: 'Read the next page of updates',
+      }]
+      : [],
+    renderHuman: () => [
+      summary,
+      ...events.map((event) => `\n[${event.kind}] ${eventText(event)}`.trimEnd()),
+    ].join('\n'),
     meta: { mutating: false },
   });
 }
@@ -312,22 +546,36 @@ export const handoverCommandSpecs = [
     command_path: ['handover', 'start'],
     summary: 'Hand the current branch to a Notis agent and keep working.',
     when_to_use:
-      'Use this when you want Notis to continue work on the branch you are on -- long refactors, ' +
-      'test fixing, or anything that should keep running after you close the laptop. Pick the agent ' +
-      'with --route.',
+      'Use this when you want Notis to continue work on the branch you are on -- long refactors, '
+      + 'test fixing, or anything that should keep running after you close the laptop. Choose the agent, '
+      + 'intelligence and speed yourself from the user\'s words, even loose ones ("get Claude on it", '
+      + '"this one is tricky", "no rush"), and pass all three; with no agent named, codex for code work. '
+      + 'Use auto only when the user asks Notis to pick.',
     args_schema: {
       arguments: [{ token: '<task>', description: 'What the agent should do, in plain language.' }],
       options: [
         {
-          flags: '--branch-mode <mode>',
-          key: 'branchMode',
+          flags: '--route <agent>',
           description:
-            'same = the agent commits onto your branch. new = the agent cuts a new branch from it (default).',
+            'Required. Which agent runs it: notis, codex or claude, or auto only when the user asks Notis to pick.',
         },
         {
-          flags: '--route <target>',
+          flags: '--intelligence <level>',
           description:
-            'Which agent runs it: notis (hosted, default), codex_cloud, claude_cloud, codex_local, claude_local, or auto.',
+            'Required. low (quick, simple tasks), medium (most multi-step work and coding), high (hard '
+            + 'reasoning, investigations, complex code), or auto only when the user asks Notis to pick.',
+        },
+        {
+          flags: '--speed <speed>',
+          description:
+            'Required. normal (the usual choice), priority (faster, costs more; for Codex or Claude only when '
+            + 'the user asks for their fast mode) or flex (cheaper and slower, Notis only).',
+        },
+        {
+          flags: '--branch-mode <mode>',
+          key: 'branchMode',
+          description:
+            'same = the agent commits onto your branch. new = the agent cuts a new branch from it (default).',
         },
         { flags: '--repo <slug>', description: 'Configured repository slug on the cloud computer, when you know it.' },
         {
@@ -337,38 +585,42 @@ export const handoverCommandSpecs = [
       ],
     },
     examples: [
-      'notis handover start "fix the failing auth tests"',
-      'notis handover start "finish the migration" --branch-mode same --route codex_cloud',
-      'notis handover start "add integration tests" --route claude_cloud',
-      'notis handover start "review and clean up this branch" --route claude_local',
+      'notis handover start "fix the failing auth tests" --route codex --intelligence medium --speed normal',
+      'notis handover start "finish the migration" --branch-mode same --route codex --intelligence high --speed normal',
+      'notis handover start "add integration tests" --route claude --intelligence medium --speed normal',
+      'notis handover start "review and clean up this branch" --route notis --intelligence low --speed flex',
     ],
     output_schema:
-      'Returns the branch, the resolved routing target, and the interaction/thread ids of the started run.',
+      'Returns the branch, the agent routing (notis, codex or claude, or auto when Notis picks), the '
+      + 'intelligence and speed the thread runs at, and the started thread: its request_id (for '
+      + '`handover status`), row and thread ids, and the interaction id of its first turn.',
     mutates: true,
     idempotent: false,
     require_auth: true,
-    related_commands: ['notis handover status'],
-    backend_call: { type: 'tool', name: HAND_OVER_TOOL },
+    related_commands: ['notis handover status <request-id>'],
+    backend_call: { type: 'tool', name: THREADS_TOOL },
     handler: handoverStartHandler,
   },
   {
     command_path: ['handover', 'status'],
-    summary: 'Show the coding-agent threads Notis is running for you.',
-    when_to_use: 'Use this after a hand-over to see whether the agent is still working.',
+    summary: 'Follow a hand-over, or list the work Notis is running for you.',
+    when_to_use:
+      'Use this after a hand-over. Pass the request_id `handover start` returned to read its progress '
+      + 'and result; with no id it lists the threads still running.',
     args_schema: {
-      arguments: [],
-      options: [
-        { flags: '--provider <provider>', description: 'Filter to codex or claude_code.' },
-        { flags: '--refresh', description: 'Force a live refresh instead of cached state.' },
+      arguments: [
+        { token: '[request-id]', key: 'requestId', description: 'The request_id `handover start` returned.' },
       ],
+      options: [],
     },
-    examples: ['notis handover status', 'notis handover status --provider codex --refresh'],
-    output_schema: 'Returns the coding-agent thread list with status and metadata.',
+    examples: ['notis handover status', 'notis handover status 6f1c2e8a-4b7d-5c3e-9a1f-2d8b7e6c5a4f'],
+    output_schema:
+      'With a request id: the request state, its result and its updates. Without: the running threads.',
     mutates: false,
     idempotent: true,
     require_auth: true,
     related_commands: ['notis handover start <task>'],
-    backend_call: { type: 'tool', name: SEARCH_THREADS_TOOL },
+    backend_call: { type: 'tool', name: THREADS_TOOL },
     handler: handoverStatusHandler,
   },
 ];