feat(native-chat): Grok as a structured chat over the Agent Client Protocol

config/scripts/vitest-sqlite-runtime-files.mjs

@@ -54,6 +54,7 @@ export const SQLITE_RUNTIME_INCLUDE = [
   'src/main/native-chat/agent-session-wire/structured-agent-session-claude-stop-exit-ends-record.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-claude-stop-note-end.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-claude-stop-turn-end.test.ts',
+  'src/main/native-chat/agent-session-wire/structured-agent-session-close-aborts-start.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-close-verdict.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-codex-stop-note-end.test.ts',
   'src/main/native-chat/agent-session-wire/structured-agent-session-codex-stop-row.test.ts',

src/main/acp/acp-dialects/acp-dialect.ts

@@ -11,6 +11,10 @@ export type AcpRequestPresentation = {
   reply(response: AgentSessionPromptResponse | null): unknown
 }
 
+/** A request the client answers at once, asking no one: the reply, and a plan it carried for the
+ *  chat's existing plan row. */
+export type AcpRequestSettlement = { reply: unknown; plan?: string }
+
 export type AcpBackgroundTaskUpdate = Pick<NativeChatBackgroundTaskBlock, 'taskId' | 'state'> &
   Partial<Omit<NativeChatBackgroundTaskBlock, 'type' | 'taskId' | 'state'>> & {
     /** Used only until a provider description is known. */
@@ -45,6 +49,8 @@ export type AcpDialect = {
   notification?(method: string, params: unknown, at: number): AcpDialectNotification | undefined
   contextWindow?(models: unknown): number | undefined
   request?(method: string, params: unknown): AcpRequestPresentation | undefined
+  /** Requests answered at once instead of shown to the person. */
+  settleRequest?(method: string, params: unknown): AcpRequestSettlement | undefined
   /** The provider's words in a `session/prompt` error answer, when its message is generic. */
   promptErrorDetail?(error: AcpAgentError): string | undefined
   /** The row for a failed turn the provider gave no words for. */

src/main/acp/acp-dialects/grok-dialect.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 import { acpNotificationEnvelopeSchema } from '../acp-context-usage'
 import type { AcpDialect, AcpDialectNotification } from './acp-dialect'
-import { grokRequest } from './grok-requests'
+import { grokRequest, grokSettleRequest } from './grok-requests'
 import { grokBackgroundTaskNotification, grokToolBackgroundTasks } from './grok-background-tasks'
 
 const tokenCount = z.number().int().nonnegative()
@@ -173,6 +173,7 @@ export const GROK_ACP_DIALECT: AcpDialect = {
     return parsed.success ? parsed.data['x.ai/tool'].name : undefined
   },
   request: grokRequest,
+  settleRequest: grokSettleRequest,
   toolBackgroundTasks: grokToolBackgroundTasks,
   notification,
   contextWindow,

src/main/acp/acp-dialects/grok-requests.ts

@@ -5,7 +5,7 @@ import {
 } from '../../../shared/agent-session-question-answer'
 import { AcpRpcError } from '../acp-errors'
 import { pendingAcpResolution } from '../acp-timeline-requests'
-import type { AcpRequestPresentation } from './acp-dialect'
+import type { AcpRequestPresentation, AcpRequestSettlement } from './acp-dialect'
 
 const questionRequestSchema = z.object({
   sessionId: z.string(),
@@ -98,47 +98,35 @@ function questionRequest(params: unknown): AcpRequestPresentation {
   }
 }
 
-function planRequest(params: unknown): AcpRequestPresentation {
+/** What Grok hears once Orca has shown its plan: no approval is given for the person. */
+const PLAN_SHOWN_FEEDBACK =
+  'Orca showed your plan to the user. Stop here and wait for their feedback or a request to implement it in a later turn.'
+
+/** Grok's plan-mode exit: its plan goes to the chat's plan row and the gate is answered at once
+ *  (`abandoned`), so the turn ends instead of waiting on an approval card. */
+function settlePlanRequest(params: unknown): AcpRequestSettlement {
   const parsed = planRequestSchema.safeParse(params)
   if (!parsed.success) {
-    throw new AcpRpcError(-32602, 'Invalid agent plan approval request')
+    throw new AcpRpcError(-32602, 'Invalid agent plan request')
   }
   return {
-    body: {
-      kind: 'approval',
-      title: 'Approve plan',
-      detail: null,
-      subject: {
-        kind: 'plan',
-        text: parsed.data.planContent ?? 'The agent exited plan mode without writing a plan.'
-      },
-      options: [
-        { id: 'approved', label: 'Approve plan' },
-        { id: 'request_changes', label: 'Request changes' }
-      ],
-      resolution: pendingAcpResolution
-    },
-    reply: (response) => {
-      if (response === null) {
-        return { outcome: 'abandoned' }
-      }
-      if (
-        response.kind !== 'option' ||
-        !['approved', 'request_changes'].includes(response.optionId)
-      ) {
-        throw new AcpRpcError(-32602, 'Plan answer must select an offered option')
-      }
-      return { outcome: response.optionId }
-    }
+    reply: { outcome: 'abandoned', feedback: PLAN_SHOWN_FEEDBACK },
+    plan: parsed.data.planContent?.trim() || 'The agent exited plan mode without writing a plan.'
   }
 }
 
+export function grokSettleRequest(
+  method: string,
+  params: unknown
+): AcpRequestSettlement | undefined {
+  return ['_x.ai/exit_plan_mode', 'x.ai/exit_plan_mode'].includes(method)
+    ? settlePlanRequest(params)
+    : undefined
+}
+
 export function grokRequest(method: string, params: unknown): AcpRequestPresentation | undefined {
   if (['_x.ai/ask_user_question', 'x.ai/ask_user_question'].includes(method)) {
     return questionRequest(params)
   }
-  if (['_x.ai/exit_plan_mode', 'x.ai/exit_plan_mode'].includes(method)) {
-    return planRequest(params)
-  }
   return undefined
 }

src/main/acp/acp-launch-specs.ts

@@ -0,0 +1,76 @@
+// How Orca starts each ACP agent, as data: adding an agent is one more row (plus a dialect when it
+// speaks protocol extensions). Nothing outside `acp-dialects/` branches on an agent's name.
+
+import { join } from 'node:path'
+import {
+  ORCA_SCRUB_SAFE_LAUNCH_ENV,
+  ORCA_SCRUB_SAFE_PANE_ENV
+} from '../../shared/agent-hook-scrub-safe-env'
+import { AGENT_HOOK_RUNTIME_ENV_KEYS } from '../ipc/pty/host-env/spawn-env-keys'
+import type { AcpDialect } from './acp-dialects/acp-dialect'
+import { GROK_ACP_DIALECT } from './acp-dialects/grok-dialect'
+
+export type AcpLaunchSpec = {
+  /** The Orca agent id (a `TuiAgent`), which names the agent's records and its catalog label. */
+  agent: string
+  command: string
+  /** Built per launch: `fullAccess` is the Agent Permissions setting's bypass posture. */
+  args(input: { fullAccess: boolean }): string[]
+  /** Overlaid on the child's environment. */
+  env: Readonly<Record<string, string>>
+  dialect: AcpDialect
+  /** The agent's own sign-in command, for a person to run when it reports auth required. */
+  loginCommand: readonly string[]
+  /** Which advertised sign-in method to use when the agent reports auth required, read from the
+   *  environment it was launched with (on its own machine); none leaves it not signed in. */
+  authMethod?(input: {
+    advertised: readonly string[]
+    env: Readonly<Record<string, string>>
+  }): string | undefined
+  /** Variable naming the agent's config directory, pinned as each record's account home. */
+  accountHomeVariable: string
+  /** The config directory the agent uses when the variable is unset, under the user's home. */
+  defaultAccountHome(homePath: string): string
+  /** Where the agent installs its own binary, searched after PATH. */
+  installDirectories(accountHomePath: string): string[]
+}
+
+const GROK_LAUNCH_SPEC: AcpLaunchSpec = {
+  agent: 'grok',
+  command: 'grok',
+  // `--always-approve` only for full access, as the user's setting chooses.
+  args: ({ fullAccess }) => ['agent', ...(fullAccess ? ['--always-approve'] : []), 'stdio'],
+  env: {},
+  dialect: GROK_ACP_DIALECT,
+  loginCommand: ['grok', 'login'],
+  // An API key in Grok's own environment, else the sign-in Grok already cached; never interactive.
+  authMethod: ({ advertised, env }) =>
+    env.XAI_API_KEY?.trim() && advertised.includes('xai.api_key')
+      ? 'xai.api_key'
+      : advertised.includes('cached_token')
+        ? 'cached_token'
+        : undefined,
+  accountHomeVariable: 'GROK_HOME',
+  defaultAccountHome: (homePath) => join(homePath, '.grok'),
+  installDirectories: (accountHomePath) => [join(accountHomePath, 'bin')]
+}
+
+export const ACP_LAUNCH_SPECS: readonly AcpLaunchSpec[] = [GROK_LAUNCH_SPEC]
+
+export function acpLaunchSpecFor(agent: string): AcpLaunchSpec | null {
+  return ACP_LAUNCH_SPECS.find((spec) => spec.agent === agent) ?? null
+}
+
+/**
+ * A pane's identity in the inherited environment would let the agent's own Orca status hooks
+ * report for this session too; the structured session is its one status producer.
+ */
+export const ACP_CHILD_ENV_TO_DELETE: readonly string[] = [
+  'ORCA_PANE_KEY',
+  'ORCA_TAB_ID',
+  'ORCA_WORKTREE_ID',
+  'ORCA_AGENT_LAUNCH_TOKEN',
+  ORCA_SCRUB_SAFE_PANE_ENV,
+  ORCA_SCRUB_SAFE_LAUNCH_ENV,
+  ...AGENT_HOOK_RUNTIME_ENV_KEYS
+]

src/main/acp/acp-prompt-turns.ts

@@ -33,6 +33,15 @@ export class AcpPromptTurns {
     this.current = undefined
   }
 
+  /** Forgets a prompt the agent refused before its turn opened; false for any other. */
+  refuse(clientMessageId: string): boolean {
+    if (this.current?.clientMessageId !== clientMessageId || this.current.opened) {
+      return false
+    }
+    this.current = undefined
+    return true
+  }
+
   start(turn: string, at: number): ProviderTimelineEvent[] {
     const prompt = this.current
     if (prompt?.turn !== turn || prompt.opened) {

src/main/acp/acp-session-reopen-failure.ts

@@ -0,0 +1,65 @@
+// What takes over when an ACP agent cannot reopen the session a chat proved. A session this chat
+// created and never exchanged a turn on, which the agent says it does not hold, is superseded:
+// there was nothing to remember. Any other is replaced by a new session that names it, and the
+// chat says once that the agent forgot: the row names the lost conversation, so a later start
+// can tell whether it was ever written.
+
+import { agentSessionFailureFact } from '../../shared/agent-session-failure'
+import { agentSessionFailureWords } from '../../shared/agent-session-failure-words'
+import type { AgentSessionProviderHandleLink } from '../../shared/agent-session-provider-handle'
+import type { ProviderTimelineEvent } from '../native-chat/agent-session-timeline/provider-timeline-event'
+import { AcpAuthRequiredError, AcpRpcError } from './acp-errors'
+import type { AcpStructuredLaunch } from './acp-structured-launch-resolution'
+
+/** ACP's "resource not found": the agent holds no session under the id this chat proved. */
+const ACP_RESOURCE_NOT_FOUND = -32002
+export const ACP_REOPEN_FAILED = 'ACP agent could not reopen its saved session; starting a new one'
+
+/** The fields the new session's link carries; rethrows `error` when the start must fail instead. */
+export function acpReopenTakeover(
+  error: unknown,
+  resume: NonNullable<AcpStructuredLaunch['resume']>,
+  start: { over: boolean; now: number; warn: (fields: { scope: string; error: unknown }) => void }
+): Pick<AgentSessionProviderHandleLink, 'supersedesKey' | 'replaces'> {
+  // Signed out, or the start is over (Close, Stop, a lost agent): a new session would not help.
+  if (error instanceof AcpAuthRequiredError || start.over) {
+    throw error
+  }
+  if (
+    error instanceof AcpRpcError &&
+    error.code === ACP_RESOURCE_NOT_FOUND &&
+    resume.mayBeUnsaved()
+  ) {
+    return { supersedesKey: resume.key }
+  }
+  start.warn({ scope: 'acp-restore-failed', error })
+  return { replaces: { key: resume.key, reason: 'restore-failed', replacedAt: start.now } }
+}
+
+/** The provider item key of the row saying the conversation under chain key `lostKey` was lost. */
+export function acpSessionNotRestoredItem(lostKey: string): string {
+  return `session-not-restored:${lostKey}`
+}
+
+/** The one row a lost conversation gets: the agent no longer remembers what came before. */
+export function acpSessionNotRestoredRow(
+  lostKey: string,
+  providerSessionId: string,
+  agentName: string
+): ProviderTimelineEvent[] {
+  return [
+    {
+      type: 'item.update',
+      item: acpSessionNotRestoredItem(lostKey),
+      body: {
+        kind: 'status',
+        tone: 'warning',
+        ...agentSessionFailureWords(agentSessionFailureFact('sessionNotRestored'), {
+          surface: 'row',
+          agentName
+        })
+      },
+      join: { thread: providerSessionId }
+    }
+  ]
+}