The best way to control Claude Code, Codex and more from any computer or phone

main
ts 521 lines 20.3 KB
Raw
1 import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
2 import {
3 XAiPromptFailureText,
4 isXAiTaskCompletedWakeNotification,
5 xAiRateLimitedErrorCode,
6 } from "./xaiAcpExtension.ts";
7 import { discoverGrokSkills, leadingGrokSkillMention } from "./skills.ts";
8 import * as HostProcess from "@t3tools/shared/HostProcess";
9 import { resolveSelfInvocation, type SelfInvocation } from "@t3tools/shared/nodeRuntime";
10 import {
11 defaultInstanceIdForDriver,
12 ProviderDriverKind,
13 type OrchestrationV2ProviderCapabilities,
14 type RuntimeMode,
15 } from "@t3tools/contracts";
16 import { GrokSettings } from "../settings.ts";
17 import * as SecureRandom from "effect/crypto/SecureRandom";
18 import * as Effect from "effect/Effect";
19 import * as FileSystem from "effect/FileSystem";
20 import * as Path from "effect/Path";
21 import * as Schema from "effect/Schema";
22 import type * as Scope from "effect/Scope";
23 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
24 import * as EffectAcpErrors from "effect-acp/errors";
25 import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
26
27 import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
28 import * as ProviderHost from "@t3tools/provider-core/server/ProviderHost";
29 import { makeAcpNativeLoggerFactory } from "@t3tools/provider-acp/server/nativeLogging";
30 import {
31 applyGrokAcpModelSelection,
32 currentGrokModelIdFromSessionSetup,
33 GROK_DEFAULT_MODEL_SLUG,
34 grokApprovalOptions,
35 makeGrokAcpRuntime,
36 resolveGrokAcpBaseModelId,
37 } from "./acpSupport.ts";
38 import { grokReasoningOptionsFromModel } from "./status.ts";
39 import {
40 extractGrokPlanMarkdownFromToolCallData,
41 extractXAiAcpBackgroundToolMutation,
42 extractXAiAcpSubagentEndNotice,
43 extractXAiAcpSubagentUpdate,
44 extractXAiAskUserQuestionIdentity,
45 extractXAiAskUserQuestions,
46 extractXAiBackgroundTaskCompletion,
47 extractXAiKilledBackgroundTasks,
48 extractXAiMonitorTaskId,
49 xAiBackgroundShellTaskId,
50 isXAiPersistentMonitor,
51 extractXAiExitPlanMarkdown,
52 registerXAiSubagentFinished,
53 makeXAiAskUserQuestionCancelledResponse,
54 makeXAiAskUserQuestionResponse,
55 makeXAiExitPlanModeCapturedResponse,
56 normalizeXAiAcpToolCallState,
57 registerXAiBackgroundTaskTracking,
58 XAiAskUserQuestionRequest,
59 XAiExitPlanModeRequest,
60 } from "./xaiAcpExtension.ts";
61 import { mergeProviderInstanceEnvironment } from "@t3tools/provider-core/server/instanceEnvironment";
62 import { acpPermissionDisposition } from "@t3tools/provider-acp/server/clientPolicy";
63 import {
64 findModelConfigOption,
65 sessionModelStateFromInitialize,
66 } from "@t3tools/provider-acp/server/runtimeModel";
67 import * as AcpSessionRuntime from "@t3tools/provider-acp/server/AcpSessionRuntime";
68 import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEventLoggers";
69 import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
70 import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
71 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
72 import {
73 ProviderAdapterDriverCreateError,
74 type ProviderAdapterDriver,
75 type ProviderAdapterDriverCreateInput,
76 } from "@t3tools/provider-core/server/adapterDriver";
77 import {
78 AcpProviderCapabilitiesV2,
79 makeAcpAdapterV2,
80 type AcpAdapterV2ExtensionContext,
81 type AcpAdapterV2Flavor,
82 type AcpAdapterV2RuntimeInput,
83 } from "@t3tools/provider-acp/server/adapter";
84
85 const isXAiPromptFailureText = Schema.is(XAiPromptFailureText);
86
87 export const GROK_PROVIDER = ProviderDriverKind.make("grok");
88 const GROK_DRIVER_KIND = GROK_PROVIDER;
89 export const GROK_DEFAULT_INSTANCE_ID = defaultInstanceIdForDriver(GROK_DRIVER_KIND);
90 const DEFAULT_GROK_SETTINGS = Schema.decodeSync(GrokSettings)({});
91 const isAcpRequestError = Schema.is(EffectAcpErrors.AcpRequestError);
92
93 const GrokProviderCapabilitiesV2 = {
94 ...AcpProviderCapabilitiesV2,
95 sessions: {
96 ...AcpProviderCapabilitiesV2.sessions,
97 supportsModelSwitchInSession: true,
98 supportsRuntimeModeSwitchInSession: false,
99 },
100 threads: {
101 ...AcpProviderCapabilitiesV2.threads,
102 canReadThreadSnapshot: true,
103 canForkThread: false,
104 canForkFromTurn: false,
105 },
106 subagents: {
107 ...AcpProviderCapabilitiesV2.subagents,
108 supportsSubagents: true,
109 exposesSubagentThreadIds: true,
110 emitsSubagentLifecycle: true,
111 },
112 tools: {
113 ...AcpProviderCapabilitiesV2.tools,
114 supportsMcpTools: true,
115 },
116 checkpointing: {
117 ...AcpProviderCapabilitiesV2.checkpointing,
118 providerCanReadConversationSnapshot: true,
119 },
120 turns: {
121 ...AcpProviderCapabilitiesV2.turns,
122 // `_x.ai/interject` lets the running tool finish; the model reads the message at its next step.
123 supportsActiveSteering: true,
124 activeSteeringInterruptsTools: false,
125 // Cancelling a Grok prompt kills its running foreground tool.
126 supportsSteeringByInterruptRestart: false,
127 },
128 } satisfies OrchestrationV2ProviderCapabilities;
129
130 const XAI_INTERJECT_METHOD = "_x.ai/interject";
131 const isXAiInterjectQueued = Schema.is(
132 Schema.Struct({ result: Schema.Struct({ status: Schema.Literal("queued") }) }),
133 );
134
135 /** A queued interjection joins the running prompt, so its acceptance is the delivery. */
136 const grokSteering: NonNullable<AcpAdapterV2Flavor["steering"]> = {
137 send: (runtime, sessionId, text, images) =>
138 runtime
139 .request(XAI_INTERJECT_METHOD, {
140 sessionId,
141 text,
142 ...(images.length === 0 ? {} : { content: images }),
143 })
144 .pipe(
145 Effect.flatMap((result) =>
146 isXAiInterjectQueued(result)
147 ? Effect.undefined
148 : Effect.fail(
149 new EffectAcpErrors.AcpRequestError({
150 code: -32603,
151 errorMessage: "Grok did not queue the interjection.",
152 method: XAI_INTERJECT_METHOD,
153 data: result,
154 }),
155 ),
156 ),
157 ),
158 };
159
160 export interface GrokAdapterV2Options {
161 readonly instanceId: Parameters<typeof makeAcpAdapterV2>[0]["instanceId"];
162 readonly settings: GrokSettings;
163 readonly environment: NodeJS.ProcessEnv;
164 readonly hostPlatform: NodeJS.Platform;
165 readonly selfInvocation: SelfInvocation;
166 readonly nativeLogging?: Parameters<typeof makeAcpAdapterV2>[0]["nativeLogging"];
167 readonly continuationRequests?: Parameters<typeof makeAcpAdapterV2>[0]["continuationRequests"];
168 readonly testHooks?: Parameters<typeof makeAcpAdapterV2>[0]["testHooks"];
169 readonly makeRuntime?: (
170 input: AcpAdapterV2RuntimeInput,
171 ) => Effect.Effect<
172 AcpSessionRuntime.AcpSessionRuntime["Service"],
173 EffectAcpErrors.AcpError,
174 ChildProcessSpawner.ChildProcessSpawner | SecureRandom.SecureRandom | Scope.Scope
175 >;
176 readonly assertComplete?: Effect.Effect<void, EffectAcpErrors.AcpError>;
177 }
178
179 const registerGrokAcpExtensions: NonNullable<AcpAdapterV2Flavor["registerExtensions"]> = ({
180 runtime,
181 requestUserInput,
182 applyBackgroundTaskMutation,
183 finishSubagent,
184 captureProposedPlan,
185 lastProposedPlanMarkdown,
186 }) =>
187 registerXAiBackgroundTaskTracking(runtime, applyBackgroundTaskMutation).pipe(
188 Effect.andThen(registerXAiSubagentFinished(runtime, finishSubagent)),
189 Effect.andThen(registerGrokAskUserQuestionExtensions({ runtime, requestUserInput })),
190 Effect.andThen(
191 registerGrokExitPlanModeExtensions({
192 runtime,
193 captureProposedPlan,
194 lastProposedPlanMarkdown,
195 }),
196 ),
197 );
198
199 // Capture the reverse-requested plan, then abandon the native gate to finish the turn.
200 const registerGrokExitPlanModeExtensions = ({
201 runtime,
202 captureProposedPlan,
203 lastProposedPlanMarkdown,
204 }: Pick<
205 AcpAdapterV2ExtensionContext,
206 "runtime" | "captureProposedPlan" | "lastProposedPlanMarkdown"
207 >) =>
208 Effect.forEach(
209 ["x.ai/exit_plan_mode", "_x.ai/exit_plan_mode"] as const,
210 (method) =>
211 runtime.handleExtRequest(method, XAiExitPlanModeRequest, (params) =>
212 Effect.gen(function* () {
213 const fallback = yield* lastProposedPlanMarkdown;
214 yield* captureProposedPlan({
215 planMarkdown: extractXAiExitPlanMarkdown(params, fallback),
216 });
217 return makeXAiExitPlanModeCapturedResponse();
218 }),
219 ),
220 { discard: true },
221 );
222
223 const registerGrokAskUserQuestionExtensions = ({
224 runtime,
225 requestUserInput,
226 }: Pick<AcpAdapterV2ExtensionContext, "runtime" | "requestUserInput">) =>
227 Effect.forEach(
228 ["x.ai/ask_user_question", "_x.ai/ask_user_question"] as const,
229 (method) =>
230 runtime.handleExtRequest(method, XAiAskUserQuestionRequest, (params, requestContext) => {
231 const identity = extractXAiAskUserQuestionIdentity(params);
232 const questions = extractXAiAskUserQuestions(params).map((question) => ({
233 ...question,
234 options: [...question.options],
235 }));
236 return requestUserInput(
237 {
238 nativeItemId: `${identity.sessionId}:xai-question:${identity.toolCallId}`,
239 nativeRequestId: identity.toolCallId,
240 questions,
241 },
242 requestContext,
243 ).pipe(
244 Effect.flatMap(({ acknowledgeNativeResponse, answers }) =>
245 Effect.succeed(
246 answers === null
247 ? makeXAiAskUserQuestionCancelledResponse()
248 : makeXAiAskUserQuestionResponse(params, answers),
249 ).pipe(Effect.tap(() => acknowledgeNativeResponse)),
250 ),
251 );
252 }),
253 { discard: true },
254 );
255
256 /** Explicit policy overrides launch in ask mode so Grok cannot bypass T3 approval checks. */
257 export function grokLaunchRuntimeMode(
258 runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy,
259 ): RuntimeMode {
260 return runtimePolicy.approvalPolicy === undefined && runtimePolicy.sandboxPolicy === undefined
261 ? runtimePolicy.runtimeMode
262 : "approval-required";
263 }
264
265 /** The capability id the composer stores Grok's reasoning effort under. */
266 const GROK_REASONING_EFFORT_OPTION_ID = "reasoningEffort";
267
268 // Protocol 1 sends the effort as `session/set_model` metadata on every call: that response
269 // carries no config options, so there is no live effort to compare against. Newer protocols
270 // write the `thought_level` config option after the model switch. An effort the model does
271 // not offer, or that Grok refuses, is skipped with a warning and Grok's default applies.
272 const applyGrokSessionModelSelection: NonNullable<AcpAdapterV2Flavor["applyModelSelection"]> =
273 Effect.fn("GrokAdapter.applyModelSelection")(function* ({
274 runtime,
275 startResult,
276 modelSelection,
277 }) {
278 const requestedModelId = resolveGrokAcpBaseModelId(modelSelection.model);
279 const requestedEffort = getModelSelectionStringOptionValue(
280 modelSelection,
281 GROK_REASONING_EFFORT_OPTION_ID,
282 );
283 const skipEffort = (detail: string) =>
284 Effect.logWarning("Grok session skipped the requested reasoning effort", {
285 sessionId: startResult.sessionId,
286 reasoningEffort: requestedEffort,
287 detail,
288 });
289
290 if (startResult.initializeResult.protocolVersion === 1) {
291 const setup = startResult.sessionSetupResult;
292 const currentModelId = currentGrokModelIdFromSessionSetup(setup);
293 const targetModelId =
294 requestedModelId === GROK_DEFAULT_MODEL_SLUG ? currentModelId : requestedModelId;
295 const targetModel = setup.models?.availableModels.find(
296 (model) => model.modelId.trim() === targetModelId,
297 );
298 const offeredEfforts =
299 targetModel === undefined
300 ? []
301 : grokReasoningOptionsFromModel(targetModel).options.map((option) => option.value);
302 const effort =
303 requestedEffort !== undefined &&
304 (offeredEfforts.length === 0 || offeredEfforts.includes(requestedEffort))
305 ? requestedEffort
306 : undefined;
307 if (requestedEffort !== undefined && effort === undefined) {
308 yield* skipEffort(`${targetModelId} does not offer it`);
309 }
310 const apply = (requestedReasoningEffort: string | undefined) =>
311 applyGrokAcpModelSelection({
312 runtime,
313 currentModelId,
314 requestedModelId,
315 requestedReasoningEffort,
316 mapError: (cause) => cause,
317 });
318 return yield* effort === undefined
319 ? apply(undefined)
320 : apply(effort).pipe(
321 Effect.catchTags({
322 AcpRequestError: (error) =>
323 skipEffort(error.message).pipe(Effect.andThen(apply(undefined))),
324 }),
325 );
326 }
327
328 const appliedModelId = yield* applyGrokAcpModelSelection({
329 runtime: { setSessionModel: (model) => runtime.setModel(model).pipe(Effect.as({})) },
330 currentModelId: findModelConfigOption(yield* runtime.getConfigOptions)?.currentValue,
331 requestedModelId,
332 mapError: (cause) => cause,
333 });
334 if (requestedEffort === undefined) {
335 return appliedModelId;
336 }
337 // Read after the model switch: the effort choices belong to the new model.
338 const effortOption = (yield* runtime.getConfigOptions).find(
339 (option) => option.type === "select" && option.category === "thought_level",
340 );
341 if (effortOption === undefined) {
342 yield* skipEffort("the session has no reasoning effort option");
343 return appliedModelId;
344 }
345 // setConfigOption rejects a value the option does not offer and skips the current one.
346 yield* runtime
347 .setConfigOption(effortOption.id, requestedEffort)
348 .pipe(Effect.catchTags({ AcpRequestError: (error) => skipEffort(error.message) }));
349 return appliedModelId;
350 });
351
352 export function makeGrokAcpAdapterFlavor(
353 options: GrokAdapterV2Options,
354 homeDirectory: string,
355 ): AcpAdapterV2Flavor {
356 return {
357 driver: GROK_PROVIDER,
358 runtimeHarness: "Grok",
359 capabilities: GrokProviderCapabilitiesV2,
360 interruptPromptOnCancel: false,
361 // User Stop restarts the process group; steering cancels softly to preserve background work.
362 restartRuntimeAfterInterrupt: true,
363 terminateRuntimeProcessGroupOnInterrupt: true,
364 // Settled Grok sessions accept concurrent prompts; skip cancel to preserve background subagents.
365 preserveRuntimeOnSettledInterrupt: true,
366 // Grok accepts image blocks despite advertising promptCapabilities.image:false.
367 supportsImagePrompts: true,
368 supportsCompaction: true,
369 steering: grokSteering,
370 // Grok expands only a leading `/name`, while the `$` picker inserts `$name` from the
371 // `grok inspect` catalog. Ask that catalog again so other `$` text is left alone.
372 rewriteUserText: (text, turnInput) => {
373 const mention = leadingGrokSkillMention(text);
374 if (mention === undefined) return Effect.succeed(text);
375 return discoverGrokSkills(
376 options.settings,
377 options.environment,
378 turnInput.runtimePolicy.cwd ?? undefined,
379 ).pipe(
380 Effect.map((skills) =>
381 skills.some((skill) => skill.enabled && skill.name === mention.name)
382 ? `/${mention.name}${mention.rest}`
383 : text,
384 ),
385 Effect.orElseSucceed(() => text),
386 );
387 },
388 resolveModelId: (selection) => resolveGrokAcpBaseModelId(selection.model),
389 getModelContextWindow: (selection, session) => {
390 if (selection.instanceId !== options.instanceId) return undefined;
391 const modelId = resolveGrokAcpBaseModelId(selection.model);
392 const models =
393 session.sessionSetupResult.models ??
394 sessionModelStateFromInitialize(session.initializeResult);
395 const window = models?.availableModels.find((model) => model.modelId === modelId)?._meta
396 ?.totalContextTokens;
397 // contextWindows includes selectable larger windows; totalContextTokens is the default.
398 return typeof window === "number" && Number.isSafeInteger(window) && window > 0
399 ? window
400 : undefined;
401 },
402 applyModelSelection: applyGrokSessionModelSelection,
403 ownedModelOptionIds: [GROK_REASONING_EFFORT_OPTION_ID],
404 makeRuntime:
405 options.makeRuntime ??
406 (({ runtimePolicy, ...input }) =>
407 makeGrokAcpRuntime({
408 ...input,
409 interruptPromptOnCancel: input.interruptPromptOnCancel ?? false,
410 grokSettings: options.settings,
411 environment: options.environment,
412 runtimeMode: grokLaunchRuntimeMode(runtimePolicy),
413 })),
414 // Auto prompts represent classifier refusals and must reach the user.
415 permissionDisposition: (policy, request) =>
416 grokLaunchRuntimeMode(policy) === "auto" ? "ask" : acpPermissionDisposition(policy, request),
417 approvalOptions: grokApprovalOptions,
418 promptFailure: (cause) =>
419 makeProviderFailure({
420 cause,
421 ...(isAcpRequestError(cause)
422 ? {
423 message: isXAiPromptFailureText(cause.cause)
424 ? cause.cause.message
425 : cause.errorMessage,
426 code: String(cause.code),
427 class: cause.code === xAiRateLimitedErrorCode ? "usage_limit" : "provider_error",
428 }
429 : { class: "provider_error" }),
430 }),
431 registerExtensions: registerGrokAcpExtensions,
432 extractSubagentUpdate: extractXAiAcpSubagentUpdate,
433 extractSubagentEndNotice: extractXAiAcpSubagentEndNotice,
434 normalizeToolCall: normalizeXAiAcpToolCallState,
435 extractProposedPlanMarkdown: (toolCall) =>
436 extractGrokPlanMarkdownFromToolCallData(toolCall.data, {
437 platform: options.hostPlatform,
438 environment: options.environment,
439 homeDirectory,
440 }),
441 extractBackgroundTaskId: extractXAiMonitorTaskId,
442 isBackgroundCommandTool: (toolCall) => xAiBackgroundShellTaskId(toolCall) !== undefined,
443 extractBackgroundToolMutation: extractXAiAcpBackgroundToolMutation,
444 extractBackgroundTaskCompletion: (toolCall) => [
445 ...extractXAiBackgroundTaskCompletion(toolCall),
446 ...extractXAiKilledBackgroundTasks(toolCall),
447 ],
448 isPersistentBackgroundTool: isXAiPersistentMonitor,
449 isProviderWakeNotification: isXAiTaskCompletedWakeNotification,
450 deferFinalizeForBackgroundWork: true,
451 enablePostSettleContinuation: true,
452 ...(options.assertComplete === undefined ? {} : { assertComplete: options.assertComplete }),
453 };
454 }
455
456 export const makeGrokAdapterV2 = Effect.fn("makeGrokAdapterV2")(function* (
457 options: GrokAdapterV2Options,
458 ) {
459 return yield* makeAcpAdapterV2({
460 instanceId: options.instanceId,
461 flavor: makeGrokAcpAdapterFlavor(options, yield* HostProcess.HomeDirectory),
462 selfInvocation: options.selfInvocation,
463 ...(options.nativeLogging === undefined ? {} : { nativeLogging: options.nativeLogging }),
464 ...(options.continuationRequests === undefined
465 ? {}
466 : { continuationRequests: options.continuationRequests }),
467 ...(options.testHooks === undefined ? {} : { testHooks: options.testHooks }),
468 });
469 });
470
471 export type GrokAdapterV2DriverEnv =
472 | ChildProcessSpawner.ChildProcessSpawner
473 | SecureRandom.SecureRandom
474 | FileSystem.FileSystem
475 | IdAllocator.IdAllocatorV2
476 | Path.Path
477 | McpProviderSessions.McpProviderSessions
478 | ProviderEventLoggers.ProviderEventLoggers
479 | ProviderHost.ProviderHost;
480
481 export const GrokAdapterV2Driver: ProviderAdapterDriver<GrokSettings, GrokAdapterV2DriverEnv> = {
482 driverKind: GROK_DRIVER_KIND,
483 configSchema: GrokSettings,
484 defaultConfig: (): GrokSettings => DEFAULT_GROK_SETTINGS,
485 create: Effect.fn("GrokAdapterV2Driver.create")(
486 function* (input: ProviderAdapterDriverCreateInput<GrokSettings>) {
487 const hostEnvironment = yield* HostProcess.Environment;
488 const hostPlatform = yield* HostProcess.Platform;
489 const selfInvocation = yield* resolveSelfInvocation();
490 const providerEventLoggers = yield* ProviderEventLoggers.ProviderEventLoggers;
491 const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests;
492 const makeNativeLogger = yield* makeAcpNativeLoggerFactory();
493 return yield* makeGrokAdapterV2({
494 instanceId: input.instanceId,
495 settings: { ...input.config, enabled: input.enabled },
496 environment: yield* mergeProviderInstanceEnvironment(input.environment, hostEnvironment),
497 hostPlatform,
498 selfInvocation,
499 continuationRequests,
500 nativeLogging: (threadId) =>
501 makeNativeLogger({
502 nativeEventLogger: providerEventLoggers.native,
503 provider: GROK_PROVIDER,
504 threadId,
505 }),
506 });
507 },
508 (effect, input) =>
509 effect.pipe(
510 Effect.mapError(
511 (cause) =>
512 new ProviderAdapterDriverCreateError({
513 driver: GROK_DRIVER_KIND,
514 instanceId: input.instanceId,
515 detail: "Failed to create Grok ACP adapter.",
516 cause,
517 }),
518 ),
519 ),
520 ),
521 };