@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 426 lines 16.6 KB
Raw
1 import type {
2 NodeId,
3 OrchestrationV2ProviderFailure,
4 OrchestrationV2ProviderFailureClass,
5 OrchestrationV2ProviderRetry,
6 OrchestrationV2TurnItem,
7 ProviderDriverKind,
8 ProviderThreadId,
9 ProviderTurnId,
10 RunId,
11 ThreadId,
12 } from "@t3tools/contracts";
13 import * as DateTime from "effect/DateTime";
14 import * as Cause from "effect/Cause";
15
16 import * as IdAllocator from "./IdAllocator.ts";
17 import type { ProviderAdapterFailureReason } from "./ProviderAdapter.ts";
18 import * as Schema from "effect/Schema";
19
20 export class ContextHandoffBudgetError extends Schema.TaggedError<ContextHandoffBudgetError>()(
21 "ContextHandoffBudgetError",
22 {},
23 ) {
24 override get message() {
25 return "The request leaves too little context for a provider handoff. Shorten the request or use a larger-context model; the current request has not been truncated.";
26 }
27 }
28
29 export class ContextHandoffBackgroundWorkError extends Schema.TaggedError<ContextHandoffBackgroundWorkError>()(
30 "ContextHandoffBackgroundWorkError",
31 {},
32 ) {
33 override get message() {
34 return "The target provider still has background work running. Wait for it to finish or stop it before retrying the handoff.";
35 }
36 }
37
38 export const MAX_PROVIDER_FAILURE_MESSAGE_LENGTH = 4_096;
39 const MAX_PROVIDER_FAILURE_CODE_LENGTH = 128;
40
41 const DEFAULT_PROVIDER_FAILURE_MESSAGE = "Provider turn failed.";
42
43 // Gateways answer an oversized body with a 413 page; resending the same history fails identically.
44 const REQUEST_TOO_LARGE_STATUS = /^\s*(?:(?:API Error|Error|HTTP|status)(?:\s*:)?\s*)?413\b/iu;
45 const REQUEST_TOO_LARGE_REASON = /\b(?:Request Entity|Payload|Content) Too Large\b/u;
46 const REQUEST_TOO_LARGE_MESSAGE =
47 "This thread's request is too large for the provider (HTTP 413), so retrying fails the same way. Start a fresh session with /clear, or continue in a new thread.";
48
49 const PROVIDER_FAILURE_CATEGORIES: Partial<
50 Record<string, { readonly summary: string; readonly guidance: string }>
51 > = {
52 ProviderAdapterTurnStartError: {
53 summary: "The provider could not start this turn",
54 guidance: "Retry the turn; if it keeps failing, check the provider setup and server logs.",
55 },
56 ProviderAdapterEventStreamError: {
57 summary: "The provider event stream closed unexpectedly",
58 guidance: "Retry the turn; if it keeps failing, check the provider and server logs.",
59 },
60 ProviderAdapterOpenSessionError: {
61 summary: "The provider session could not be opened",
62 guidance: "Check that the provider is installed and signed in, then retry the turn.",
63 },
64 ProviderAdapterResumeThreadError: {
65 summary: "The provider conversation could not be resumed",
66 guidance: "Retry the turn; if it keeps failing, check the provider and server logs.",
67 },
68 };
69
70 // macOS privacy protection (TCC) refuses a CLI the project folder with EPERM.
71 const PERMISSION_DENIED_OUTPUT = /\bEPERM\b|Operation not permitted/u;
72
73 /**
74 * What to do after a provider CLI exits on its own. Only recognises the
75 * output; the output itself stays out of the message.
76 */
77 export function providerProcessExitGuidance(output: unknown): string {
78 return typeof output === "string" && PERMISSION_DENIED_OUTPUT.test(output)
79 ? "It was denied access to a file or folder (EPERM). On macOS, allow T3 Code under System Settings > Privacy & Security > Files and Folders, or move the project out of Desktop, Documents, or Downloads, then retry the turn."
80 : "Check the server logs for the provider's output, then retry the turn.";
81 }
82
83 // codex_protocol::protocol::validate_thread_goal_objective
84 const CODEX_GOAL_VALIDATION_MESSAGE =
85 /^goal objective must (?:not be empty|be at most \d{1,6} characters)$/u;
86
87 // codex_config::ConstraintError::InvalidValue for a managed requirements.toml or cloud policy.
88 const CODEX_ACCESS_REQUIREMENT_REJECTION =
89 /invalid value for `(approval_policy|sandbox_mode)`: `([A-Za-z]{1,32})` is not in the allowed set /u;
90
91 const PROVIDER_FAILURE_REASONS: Record<ProviderAdapterFailureReason, string> = {
92 previous_turn_active: "the previous turn is still running",
93 attachment_unreadable: "an attachment could not be read",
94 };
95
96 /**
97 * Walks a cause chain for curated text without reading arbitrary provider
98 * defect text. `known` is the message of a domain error T3 raised itself;
99 * `category` is the generic message of the innermost provider wrapper seen.
100 */
101 function curatedCauseMessages(cause: unknown): {
102 readonly known: string | undefined;
103 readonly category: string | undefined;
104 } {
105 const seen = new Set<unknown>();
106 let category: (typeof PROVIDER_FAILURE_CATEGORIES)[string];
107 let reason: string | undefined;
108 const categoryMessage = () => {
109 if (category === undefined) return undefined;
110 return reason
111 ? `${category.summary}: ${reason}. ${category.guidance}`
112 : `${category.summary}. ${category.guidance}`;
113 };
114 for (let depth = 0; depth < 16 && cause != null && !seen.has(cause); depth++) {
115 seen.add(cause);
116 try {
117 if (Cause.isCause(cause)) {
118 cause = Cause.squash(cause);
119 continue;
120 }
121 if (typeof cause !== "object") break;
122 const tag = (cause as Record<string, unknown>)._tag;
123 switch (tag) {
124 case "ContextHandoffBudgetError":
125 return { known: new ContextHandoffBudgetError().message, category: categoryMessage() };
126 case "ContextHandoffBackgroundWorkError":
127 return {
128 known: new ContextHandoffBackgroundWorkError().message,
129 category: categoryMessage(),
130 };
131 case "AcpModelSelectionError":
132 case "ClaudeBackgroundWorkBlocksQueryReplacementError":
133 case "ClaudeAppendSystemPromptFileError":
134 case "ClaudeAppendSystemPromptMissingValueError":
135 case "ClaudeSettingsLaunchArgError":
136 case "ClaudeMcpRegistrationTimeoutError":
137 case "ClaudeCodeRootRefusalError":
138 case "ClaudeCodeStartupExitError":
139 case "ClaudeConversationNotFoundError":
140 case "CursorModelUnavailableError":
141 case "CodexGoalObjectiveTooLongError":
142 case "ProviderSetupError":
143 case "ProviderAdapterThreadInUseError":
144 case "ProviderCompactionUnsupportedError":
145 return { known: stringField(cause, "message"), category: categoryMessage() };
146 case "CodexAppServerRequestError": {
147 // Only Codex's fixed-shape goal validation and managed-requirements
148 // text is actionable and safe to show; other request error text stays hidden.
149 const rejection = stringField(cause, "message");
150 if (
151 (cause as Record<string, unknown>).method === "thread/goal/set" &&
152 rejection !== undefined &&
153 CODEX_GOAL_VALIDATION_MESSAGE.test(rejection)
154 ) {
155 return { known: `Codex rejected the goal: ${rejection}.`, category: categoryMessage() };
156 }
157 const access =
158 rejection === undefined ? null : CODEX_ACCESS_REQUIREMENT_REJECTION.exec(rejection);
159 if (access !== null) {
160 return {
161 known: `Codex's managed requirements do not allow \`${access[1]}\` \`${access[2]}\`, which this thread's access mode uses. Switch the thread to an access mode the policy allows.`,
162 category: categoryMessage(),
163 };
164 }
165 break;
166 }
167 case "AcpProcessExitedError":
168 case "CodexAppServerProcessExitedError": {
169 const exit = `provider process exited${processExitStatus(cause)}`;
170 const stage = category === undefined ? `The ${exit}` : `${category.summary}: the ${exit}`;
171 const guidance = providerProcessExitGuidance((cause as Record<string, unknown>).stderr);
172 return {
173 known: `${stage}. ${guidance}`,
174 category: categoryMessage(),
175 };
176 }
177 // ACP reserves -32000 for auth_required; the agent's own text is not shown.
178 case "AcpRequestError":
179 if ((cause as Record<string, unknown>).code !== -32000) break;
180 return {
181 known:
182 "The provider needs you to sign in. Sign in from its provider settings or with its own CLI or app, then retry the turn.",
183 category: categoryMessage(),
184 };
185 case "ContextHandoffDeliveryUncertainError":
186 return {
187 known:
188 "T3 could not confirm whether conversation history reached the provider. Retry the turn to recover the session.",
189 category: categoryMessage(),
190 };
191 case "ProviderAdapterProtocolError": {
192 const typedReason = (cause as Record<string, unknown>).reason;
193 if (
194 category !== undefined &&
195 typeof typedReason === "string" &&
196 Object.hasOwn(PROVIDER_FAILURE_REASONS, typedReason)
197 ) {
198 reason ??= PROVIDER_FAILURE_REASONS[typedReason as ProviderAdapterFailureReason];
199 }
200 break;
201 }
202 }
203 if (typeof tag === "string" && Object.hasOwn(PROVIDER_FAILURE_CATEGORIES, tag)) {
204 category = PROVIDER_FAILURE_CATEGORIES[tag];
205 reason = undefined;
206 }
207 cause = (cause as Record<string, unknown>).cause;
208 } catch {
209 break;
210 }
211 }
212 return { known: undefined, category: categoryMessage() };
213 }
214
215 // Only the structured status; stderr and the spawner cause can carry provider output.
216 function processExitStatus(exited: object): string {
217 const { signal, code } = exited as Record<string, unknown>;
218 if (typeof signal === "string" && /^SIG[A-Z0-9]{1,16}$/u.test(signal)) {
219 return ` after signal ${signal}`;
220 }
221 return typeof code === "number" && Number.isSafeInteger(code) ? ` with code ${code}` : "";
222 }
223
224 /**
225 * The curated message of a domain error in a failure's cause chain, if any.
226 * Callers that pass their own `message` to `makeProviderFailure` check it
227 * first, so a known reason is not hidden behind a wrapper's text.
228 */
229 export function knownProviderFailureMessage(cause: unknown): string | undefined {
230 return curatedCauseMessages(cause).known;
231 }
232
233 function stringField(value: unknown, key: "message" | "code"): string | undefined {
234 if (typeof value !== "object" || value === null) return undefined;
235 try {
236 const candidate = (value as Record<string, unknown>)[key];
237 return typeof candidate === "string" ? candidate : undefined;
238 } catch {
239 return undefined;
240 }
241 }
242
243 function redactUrl(match: string): string {
244 const trailing = /[),.;!?]+$/u.exec(match)?.[0] ?? "";
245 const candidate = trailing.length === 0 ? match : match.slice(0, -trailing.length);
246 try {
247 const url = new URL(candidate);
248 url.username = "";
249 url.password = "";
250 url.search = "";
251 url.hash = "";
252 return `${url.toString()}${trailing}`;
253 } catch {
254 return "[REDACTED_URL]";
255 }
256 }
257
258 function replaceUnsafeControlCharacters(value: string): string {
259 const sanitized: Array<string> = [];
260 for (const character of value) {
261 const codePoint = character.codePointAt(0) ?? 0;
262 sanitized.push(
263 codePoint <= 0x08 ||
264 (codePoint >= 0x0b && codePoint <= 0x0c) ||
265 (codePoint >= 0x0e && codePoint <= 0x1f) ||
266 codePoint === 0x7f
267 ? " "
268 : character,
269 );
270 }
271 return sanitized.join("");
272 }
273
274 function redactProviderFailureText(value: string): string {
275 return replaceUnsafeControlCharacters(value)
276 .replace(/\bhttps?:\/\/[^\s<>"']+/giu, redactUrl)
277 .replace(/\b(Bearer|Basic)\s+[^\s,;]+/giu, "$1 [REDACTED]")
278 .replace(
279 /(["'][\w-]*(?:access[_-]?token|api[_-]?key|authorization|credential|password|secret|token)["']\s*:\s*["'])[^"']*(["'])/giu,
280 "$1[REDACTED]$2",
281 )
282 .replace(
283 /((?<![\w-])[\w-]*(?:access[_-]?token|api[_-]?key|authorization|credential|password|secret|token)\b\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/giu,
284 "$1[REDACTED]",
285 )
286 .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/gu, "[REDACTED]")
287 .trim();
288 }
289
290 function boundedText(value: string, maxLength: number): string {
291 const redacted = redactProviderFailureText(value);
292 if (redacted.length <= maxLength) return redacted;
293 let end = Math.max(0, maxLength - 1);
294 const finalCodeUnit = redacted.charCodeAt(end - 1);
295 if (finalCodeUnit >= 0xd800 && finalCodeUnit <= 0xdbff) {
296 end -= 1;
297 }
298 return `${redacted.slice(0, end)}…`;
299 }
300
301 export function makeProviderFailure(input: {
302 readonly cause?: unknown;
303 readonly message?: string | undefined;
304 readonly code?: string | null | undefined;
305 readonly class?: OrchestrationV2ProviderFailureClass;
306 readonly retryable?: boolean | null;
307 readonly resetAt?: string | null;
308 }): OrchestrationV2ProviderFailure {
309 const curated = curatedCauseMessages(input.cause);
310 const requestTooLarge =
311 input.message !== undefined &&
312 (REQUEST_TOO_LARGE_STATUS.test(input.message) || REQUEST_TOO_LARGE_REASON.test(input.message));
313 const rawMessage = requestTooLarge
314 ? REQUEST_TOO_LARGE_MESSAGE
315 : (input.message ?? curated.known ?? curated.category ?? DEFAULT_PROVIDER_FAILURE_MESSAGE);
316 const message = boundedText(rawMessage, MAX_PROVIDER_FAILURE_MESSAGE_LENGTH);
317 const rawCode = input.code ?? stringField(input.cause, "code") ?? null;
318 const code =
319 rawCode === null ? null : boundedText(rawCode, MAX_PROVIDER_FAILURE_CODE_LENGTH) || null;
320
321 return {
322 class: input.class ?? "unknown",
323 message: message || DEFAULT_PROVIDER_FAILURE_MESSAGE,
324 code,
325 retryable: requestTooLarge ? false : (input.retryable ?? null),
326 ...(input.class === "usage_limit" &&
327 input.resetAt != null &&
328 Number.isFinite(Date.parse(input.resetAt))
329 ? { resetAt: DateTime.formatIso(DateTime.makeUnsafe(input.resetAt)) }
330 : {}),
331 };
332 }
333
334 export function makeProviderFailureTurnItem(input: {
335 readonly driver: ProviderDriverKind;
336 readonly threadId: ThreadId;
337 readonly runId: RunId | null;
338 readonly nodeId: NodeId | null;
339 readonly providerThreadId: ProviderThreadId;
340 readonly providerTurnId: ProviderTurnId;
341 readonly itemOrdinal: number;
342 readonly failure: OrchestrationV2ProviderFailure;
343 readonly retry?: OrchestrationV2ProviderRetry;
344 readonly retryStartedAt?: DateTime.Utc;
345 readonly occurredAt: DateTime.Utc;
346 }): Extract<OrchestrationV2TurnItem, { readonly type: "error" }> {
347 return {
348 id: IdAllocator.derive.turnItemFromProviderItem({
349 driver: input.driver,
350 nativeItemId: `terminal-failure:${input.providerTurnId}`,
351 }),
352 threadId: input.threadId,
353 runId: input.runId,
354 nodeId: input.nodeId,
355 providerThreadId: input.providerThreadId,
356 providerTurnId: input.providerTurnId,
357 nativeItemRef: null,
358 parentItemId: null,
359 ordinal: input.itemOrdinal,
360 status: "failed",
361 title: input.failure.class === "usage_limit" ? "Usage limit reached" : "Provider error",
362 startedAt: input.retryStartedAt ?? input.occurredAt,
363 completedAt: input.occurredAt,
364 updatedAt: input.occurredAt,
365 type: "error",
366 failure: input.failure,
367 ...(input.retry === undefined ? {} : { retry: input.retry }),
368 };
369 }
370
371 /**
372 * Longest a turn may stay in provider retries before the adapter stops it as
373 * failed. Codex waits for the network without limit and a hung Claude request
374 * can take many minutes per attempt, so counting attempts alone never ends them.
375 */
376 export const PROVIDER_RETRY_BUDGET_MS = 10 * 60 * 1000;
377
378 export function makeProviderRetryTurnItem(input: {
379 readonly driver: ProviderDriverKind;
380 readonly threadId: ThreadId;
381 readonly runId: RunId | null;
382 readonly nodeId: NodeId | null;
383 readonly providerThreadId: ProviderThreadId;
384 readonly providerTurnId: ProviderTurnId;
385 readonly itemOrdinal: number;
386 readonly failure: OrchestrationV2ProviderFailure;
387 readonly retry: OrchestrationV2ProviderRetry;
388 readonly status: Extract<
389 OrchestrationV2TurnItem["status"],
390 "running" | "completed" | "failed" | "interrupted" | "cancelled"
391 >;
392 readonly startedAt: DateTime.Utc;
393 readonly updatedAt: DateTime.Utc;
394 }): Extract<OrchestrationV2TurnItem, { readonly type: "error" }> {
395 const completed = input.status !== "running";
396 let title = "Provider retry";
397 if (input.status === "completed") {
398 title = "Provider recovered";
399 } else if (input.status === "failed") {
400 title = input.failure.class === "usage_limit" ? "Usage limit reached" : "Provider error";
401 } else if (input.status === "interrupted" || input.status === "cancelled") {
402 title = "Provider retry stopped";
403 }
404 return {
405 id: IdAllocator.derive.turnItemFromProviderItem({
406 driver: input.driver,
407 nativeItemId: `terminal-failure:${input.providerTurnId}`,
408 }),
409 threadId: input.threadId,
410 runId: input.runId,
411 nodeId: input.nodeId,
412 providerThreadId: input.providerThreadId,
413 providerTurnId: input.providerTurnId,
414 nativeItemRef: null,
415 parentItemId: null,
416 ordinal: input.itemOrdinal,
417 status: input.status,
418 title,
419 startedAt: input.startedAt,
420 completedAt: completed ? input.updatedAt : null,
421 updatedAt: input.updatedAt,
422 type: "error",
423 failure: input.failure,
424 retry: input.retry,
425 };
426 }