typeclaw 0.45.0 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +67 -25
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/loop-guard.ts +208 -10
  7. package/src/agent/multimodal/index.ts +1 -1
  8. package/src/agent/multimodal/look-at.ts +78 -44
  9. package/src/agent/multimodal/looker.ts +151 -39
  10. package/src/agent/network/response-body.ts +26 -0
  11. package/src/agent/network/safe-http.ts +198 -0
  12. package/src/agent/plugin-tools.ts +438 -162
  13. package/src/agent/provider-error.ts +62 -4
  14. package/src/agent/restart/index.ts +61 -40
  15. package/src/agent/restart-handoff/index.ts +73 -4
  16. package/src/agent/retry-same-ref.ts +66 -0
  17. package/src/agent/reviewer-bash-policy.ts +42 -1
  18. package/src/agent/session-origin.ts +2 -0
  19. package/src/agent/subagent-drain.ts +117 -7
  20. package/src/agent/subagents.ts +77 -18
  21. package/src/agent/throttle-circuit.ts +25 -5
  22. package/src/agent/tool-error-remediation.ts +72 -0
  23. package/src/agent/tool-file-safety.ts +1050 -0
  24. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  25. package/src/agent/tools/channel-reply.ts +15 -1
  26. package/src/agent/tools/channel-send.ts +17 -1
  27. package/src/agent/tools/ddg.ts +16 -2
  28. package/src/agent/tools/post-github-review.ts +199 -0
  29. package/src/agent/tools/spawn-subagent.ts +21 -18
  30. package/src/agent/tools/webfetch/fetch.ts +143 -183
  31. package/src/agent/tools/webfetch/tool.ts +2 -3
  32. package/src/agent/tools/websearch.ts +23 -2
  33. package/src/agent/tools-without-local-file-operands.ts +27 -0
  34. package/src/agent/turn-runner.ts +109 -15
  35. package/src/bundled-plugins/backup/index.ts +2 -1
  36. package/src/bundled-plugins/backup/runner.ts +2 -1
  37. package/src/bundled-plugins/doc-render/render.ts +93 -12
  38. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  39. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  40. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  41. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  42. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  43. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  44. package/src/bundled-plugins/memory/README.md +23 -11
  45. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  46. package/src/bundled-plugins/memory/citations.ts +22 -9
  47. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  48. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  49. package/src/bundled-plugins/memory/index.ts +0 -4
  50. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  51. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  52. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  53. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  54. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  55. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  56. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  57. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  58. package/src/bundled-plugins/reviewer/index.ts +2 -2
  59. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  60. package/src/bundled-plugins/reviewer/skills/code-review.ts +24 -9
  61. package/src/bundled-plugins/scout/scout.ts +8 -0
  62. package/src/bundled-plugins/security/index.ts +4 -4
  63. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  64. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  65. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  66. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  67. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  68. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  69. package/src/channels/adapters/discord-bot.ts +91 -10
  70. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  71. package/src/channels/adapters/discord-id.ts +4 -0
  72. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  73. package/src/channels/adapters/discord.ts +57 -7
  74. package/src/channels/adapters/github/auth-app.ts +41 -12
  75. package/src/channels/adapters/github/index.ts +23 -11
  76. package/src/channels/adapters/github/review-submitter.ts +302 -0
  77. package/src/channels/adapters/kakaotalk-channel-resolver.ts +12 -1
  78. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  79. package/src/channels/adapters/kakaotalk-typing.ts +127 -0
  80. package/src/channels/adapters/kakaotalk.ts +19 -0
  81. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  82. package/src/channels/adapters/slack-bot.ts +19 -8
  83. package/src/channels/adapters/slack-classify.ts +21 -2
  84. package/src/channels/adapters/slack.ts +59 -7
  85. package/src/channels/adapters/telegram-bot.ts +18 -5
  86. package/src/channels/adapters/webex-bot.ts +8 -3
  87. package/src/channels/adapters/webex.ts +8 -3
  88. package/src/channels/fetch-attachment.ts +43 -0
  89. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  90. package/src/channels/github-token-bridge.ts +10 -3
  91. package/src/channels/manager.ts +9 -0
  92. package/src/channels/router.ts +568 -12
  93. package/src/channels/types.ts +28 -1
  94. package/src/cli/channel.ts +1 -1
  95. package/src/cli/init.ts +1 -1
  96. package/src/cli/model.ts +57 -7
  97. package/src/compose/stop.ts +17 -5
  98. package/src/config/config.ts +6 -6
  99. package/src/config/models-mutation.ts +13 -1
  100. package/src/config/providers.ts +176 -0
  101. package/src/container/start.ts +49 -10
  102. package/src/doctor/checks.ts +3 -1
  103. package/src/doctor/commit.ts +2 -1
  104. package/src/doctor/file-ownership.ts +52 -0
  105. package/src/dreams/git.ts +2 -1
  106. package/src/git/hookless.ts +5 -0
  107. package/src/git/reconcile-ignored.ts +18 -5
  108. package/src/git/secret-history.ts +371 -0
  109. package/src/git/system-commit.ts +12 -6
  110. package/src/init/dockerfile.ts +86 -5
  111. package/src/init/index.ts +17 -5
  112. package/src/init/models-dev.ts +4 -0
  113. package/src/init/validate-api-key.ts +2 -0
  114. package/src/mcp/tools.ts +16 -3
  115. package/src/permissions/builtins.ts +3 -1
  116. package/src/plugin/context.ts +2 -0
  117. package/src/plugin/index.ts +1 -0
  118. package/src/plugin/manager.ts +4 -0
  119. package/src/plugin/types.ts +21 -0
  120. package/src/run/index.ts +40 -0
  121. package/src/run/llm-fetch-observer.ts +188 -13
  122. package/src/sandbox/build.ts +37 -15
  123. package/src/sandbox/canonical-secrets.ts +18 -0
  124. package/src/sandbox/env-exposure.ts +80 -0
  125. package/src/sandbox/errors.ts +13 -6
  126. package/src/sandbox/hidden-paths.ts +102 -44
  127. package/src/sandbox/index.ts +22 -4
  128. package/src/sandbox/package-install.ts +3 -27
  129. package/src/sandbox/policy.ts +11 -25
  130. package/src/sandbox/privileged-runtime.ts +255 -0
  131. package/src/sandbox/session-tmp.ts +8 -2
  132. package/src/sandbox/writable-zones.ts +204 -140
  133. package/src/secrets/index.ts +8 -0
  134. package/src/secrets/refresh-provider-oauth.ts +128 -0
  135. package/src/server/command-runner.ts +48 -4
  136. package/src/server/index.ts +4 -0
  137. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  138. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  139. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  140. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  141. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  142. package/src/skills/typeclaw-config/SKILL.md +5 -5
  143. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  144. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  145. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  146. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  147. package/typeclaw.schema.json +20 -0
package/src/mcp/tools.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
2
2
  import { z } from 'zod'
3
3
 
4
+ import { enforceAndPinToolFiles } from '@/agent/tool-file-safety'
4
5
  import { defineTool } from '@/plugin/define'
5
6
  import type { ContentPart, Tool, ToolResult } from '@/plugin/types'
6
7
 
@@ -87,13 +88,25 @@ function createCallTool(manager: McpManager): Tool<McpCallArgs> {
87
88
  tool: z.string().describe('The bare tool name or namespaced server__tool id.'),
88
89
  args: z.record(z.string(), z.unknown()).optional().describe('Arguments matching the tool input schema.'),
89
90
  }),
90
- async execute(args) {
91
+ async execute(args, ctx) {
91
92
  const resolved = resolveToolArgs(args.server, args.tool)
92
93
  const connection = await manager.ensureConnected(resolved.server)
93
94
  if (connection === undefined) return textResult(unknownServerMessage(manager, resolved.server))
94
95
 
95
- const result = await safeCallTool(connection, resolved.tool, args.args ?? {})
96
- return mapCallToolResult(resolved.server, resolved.tool, result)
96
+ const toolArgs = args.args ?? {}
97
+ const pinned = await enforceAndPinToolFiles({
98
+ tool: 'mcp_call',
99
+ args: toolArgs,
100
+ agentDir: ctx.agentDir,
101
+ genericInputs: true,
102
+ signal: ctx.signal,
103
+ })
104
+ try {
105
+ const result = await safeCallTool(connection, resolved.tool, toolArgs)
106
+ return pinned.restoreResult(mapCallToolResult(resolved.server, resolved.tool, result))
107
+ } finally {
108
+ await pinned.cleanup()
109
+ }
97
110
  },
98
111
  })
99
112
  }
@@ -32,7 +32,9 @@ export const CORE_PERMISSIONS = {
32
32
  // Phrased as capabilities to SEE, not to hide, so the role tower stays
33
33
  // monotonic (a higher tier sees a strict superset of a lower tier).
34
34
  // resolveHiddenPaths masks whatever the resolved role lacks: fsSeePrivate
35
- // gates workspace/+memory/+sessions/, fsSeeSecrets gates .env+secrets.json.
35
+ // gates workspace/+memory/+sessions/. fsSeeSecrets authorizes runtime-owned
36
+ // credential use, never raw LLM tool access to canonical credential stores;
37
+ // canonical files are unconditionally masked for every role.
36
38
  // The fail-safe floor is the undefined origin (see has() in
37
39
  // permissions.ts), not the guest role, which is now grantable.
38
40
  fsSeePrivate: 'fs.see.private',
@@ -14,6 +14,7 @@ export type CreatePluginContextOptions<TConfig> = {
14
14
  permissions: PermissionService
15
15
  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
16
16
  hasGithubAppTokenResolver?: () => boolean
17
+ getGithubAppSelfLogin?: () => string | null
17
18
  spawnSubagent: SpawnSubagentFn
18
19
  isBooted: () => boolean
19
20
  }
@@ -34,6 +35,7 @@ export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TC
34
35
  github: {
35
36
  resolveTokenForRepo: opts.resolveGithubTokenForRepo ?? githubTokenUnavailable,
36
37
  hasAppTokenResolver: opts.hasGithubAppTokenResolver ?? (() => false),
38
+ getAppSelfLogin: opts.getGithubAppSelfLogin ?? (() => null),
37
39
  },
38
40
  spawnSubagent: async (name: string, payload?: unknown, options?: SpawnSubagentOptions) => {
39
41
  if (!opts.isBooted()) {
@@ -60,6 +60,7 @@ export type {
60
60
  ToolBeforeEvent,
61
61
  ToolBeforeResult,
62
62
  ToolContext,
63
+ ToolFileOperands,
63
64
  ToolLogger,
64
65
  ToolResult,
65
66
  } from './types'
@@ -35,6 +35,7 @@ export type LoadPluginsOptions = {
35
35
  roles?: RolesConfig
36
36
  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
37
37
  hasGithubAppTokenResolver?: () => boolean
38
+ getGithubAppSelfLogin?: () => string | null
38
39
  // Bundled plugins resolved by the runtime (not from typeclaw.json). Loaded
39
40
  // before user-declared `entries` so a config block named after a bundled
40
41
  // plugin (e.g. "memory") is consumed by the bundled plugin, and so plugin-
@@ -126,6 +127,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
126
127
  ctxDeps: {
127
128
  resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
128
129
  hasGithubAppTokenResolver: opts.hasGithubAppTokenResolver,
130
+ getGithubAppSelfLogin: opts.getGithubAppSelfLogin,
129
131
  spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
130
132
  isBooted: () => booted,
131
133
  },
@@ -224,6 +226,7 @@ type RegisterOnePluginArgs = {
224
226
  ctxDeps: {
225
227
  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
226
228
  hasGithubAppTokenResolver?: () => boolean
229
+ getGithubAppSelfLogin?: () => string | null
227
230
  spawnSubagent: SpawnSubagentFn
228
231
  isBooted: () => boolean
229
232
  }
@@ -255,6 +258,7 @@ async function registerOnePlugin(args: RegisterOnePluginArgs): Promise<void> {
255
258
  permissions: args.permissions,
256
259
  resolveGithubTokenForRepo: args.ctxDeps.resolveGithubTokenForRepo,
257
260
  hasGithubAppTokenResolver: args.ctxDeps.hasGithubAppTokenResolver,
261
+ getGithubAppSelfLogin: args.ctxDeps.getGithubAppSelfLogin,
258
262
  spawnSubagent: args.ctxDeps.spawnSubagent,
259
263
  isBooted: args.ctxDeps.isBooted,
260
264
  })
@@ -25,9 +25,23 @@ export type ToolContext = {
25
25
  logger: ToolLogger
26
26
  }
27
27
 
28
+ export type ToolFileOperands = {
29
+ input?: readonly string[]
30
+ output?: readonly string[]
31
+ destructive?: readonly string[]
32
+ // Operand paths whose string values are control tokens or remote identifiers,
33
+ // never a local file — the file-operand scanner skips them (like a first-party
34
+ // prose operand) instead of rejecting a `word.ext`-shaped id or a value that
35
+ // collides with an agent-root dir name. Scoped per operand path and survives
36
+ // the runtime `__plugin_*` tool-name prefix that a static in-scanner table
37
+ // cannot. Declare a real file input under `input` (it gets pinned), not here.
38
+ nonFile?: readonly string[]
39
+ }
40
+
28
41
  export type Tool<P = unknown> = {
29
42
  description: string
30
43
  parameters: z.ZodType<P>
44
+ fileOperands?: ToolFileOperands
31
45
  execute: (args: P, ctx: ToolContext) => Promise<ToolResult>
32
46
  }
33
47
 
@@ -211,6 +225,12 @@ export type ToolBeforeEvent = {
211
225
  callId: string
212
226
  args: Record<string, unknown>
213
227
  origin?: SessionOrigin
228
+ // The tool author's operand declarations (never model-controlled — set on the
229
+ // static Tool definition at registration). Carried so a guard that runs before
230
+ // the file-operand scanner (private-surface-read) can honor the same
231
+ // `nonFile` exemptions and not block a declared remote identifier that happens
232
+ // to collide with a hidden dir name. Present only for plugin tools.
233
+ fileOperands?: ToolFileOperands
214
234
  }
215
235
 
216
236
  export type ToolBeforeResult = void | undefined | { block: true; reason: string }
@@ -284,6 +304,7 @@ export type PluginContext<TConfig = never> = {
284
304
  export type PluginGithubServices = {
285
305
  resolveTokenForRepo: ResolveGithubTokenForRepo
286
306
  hasAppTokenResolver: () => boolean
307
+ getAppSelfLogin?: () => string | null
287
308
  }
288
309
 
289
310
  export type PluginExports = {
package/src/run/index.ts CHANGED
@@ -68,6 +68,7 @@ import {
68
68
  exportClaudeCredentialsFileForAgent,
69
69
  exportCodexAuthFileForAgent,
70
70
  hydrateChannelEnvFromSecrets,
71
+ refreshProviderOAuthForAgent,
71
72
  } from '@/secrets'
72
73
  import { createServer, type Server } from '@/server'
73
74
  import {
@@ -121,6 +122,10 @@ export type StartAgentOptions = {
121
122
  // over the real env + <cwd>/secrets.json. Injectable so tests can supply a
122
123
  // fake secrets provider without touching process.env.
123
124
  caps?: RuntimeCapabilities
125
+ // Boot-time proactive provider-OAuth refresh. Injectable so a test can supply
126
+ // a refresh that holds the real secrets lock on a gate, proving the boot
127
+ // barrier settles this before any session-producing consumer starts.
128
+ refreshProviderOAuth?: (options: { agentDir: string; log: (message: string) => void }) => Promise<unknown>
124
129
  }
125
130
 
126
131
  export type StartAgentResult = {
@@ -181,6 +186,7 @@ async function startAgentRuntime(
181
186
  createChannelManager: createChannelManagerFor = createChannelManager,
182
187
  createTunnelManager: createTunnelManagerFor = createTunnelManager,
183
188
  caps = createRuntimeCapabilities(process.env, join(cwd, 'secrets.json')),
189
+ refreshProviderOAuth = refreshProviderOAuthForAgent,
184
190
  }: StartAgentOptions,
185
191
  registerBootCleanup: (cleanup: () => void | Promise<void>) => void,
186
192
  ): Promise<StartAgentResult> {
@@ -287,6 +293,7 @@ async function startAgentRuntime(
287
293
  bundled: BUNDLED_PLUGINS,
288
294
  resolveGithubTokenForRepo: githubTokenBridge.resolveTokenForRepo,
289
295
  hasGithubAppTokenResolver: githubTokenBridge.hasAppTokenResolver,
296
+ getGithubAppSelfLogin: githubTokenBridge.getAppSelfLogin,
290
297
  ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
291
298
  })
292
299
  const vectorStartupPromise = runVectorStartup(cwd)
@@ -374,6 +381,29 @@ async function startAgentRuntime(
374
381
  log: (message) => console.warn(message),
375
382
  })
376
383
 
384
+ // Proactively refresh any stored provider-OAuth token now. The SDK's own
385
+ // refresh is lazy (fires on the first LLM call), so a container that restarts
386
+ // with an already-expired access token otherwise discovers the staleness —
387
+ // and any refresh failure — mid-turn, surfacing a generic provider-error
388
+ // notice into a live thread. Doing it here moves that to a boot-time operator
389
+ // log. Channel-adapter OAuth already has host-side renewal crons; this is the
390
+ // provider-OAuth equivalent.
391
+ //
392
+ // MUST be awaited, and MUST run before the first session-producing consumer
393
+ // (subagentConsumer.start / cronConsumer.start / channelManager.start / the
394
+ // websocket server). The SDK refresh holds SecretsBackend's async file lock
395
+ // across its network request; getAuthFor()'s synchronous lock read gives up
396
+ // after ~200ms and process.exit(1)s on ELOCKED. Fire-and-forget here would let
397
+ // a slow refresh still own the lock when a consumer creates a session — worse
398
+ // than the lazy path. Awaiting behind this barrier guarantees no synchronous
399
+ // auth reader exists while the refresh owns the lock. Never throws (the
400
+ // wrapper swallows and logs), so a probe failure can't block boot; a refresh
401
+ // that hangs on a wedged network hangs the first turn today anyway.
402
+ await refreshProviderOAuth({
403
+ agentDir: cwd,
404
+ log: (message) => console.warn(message),
405
+ })
406
+
377
407
  const claimController = createClaimController({
378
408
  cwd,
379
409
  permissions: pluginsLoaded.permissions,
@@ -429,6 +459,11 @@ async function startAgentRuntime(
429
459
  child.status === 'running' && (newest === null || child.startedAt > newest) ? child.startedAt : newest,
430
460
  null,
431
461
  ),
462
+ listRunningBackgroundSubagentNames: (sessionId) =>
463
+ liveSubagentRegistry
464
+ .list({ parentSessionId: sessionId })
465
+ .filter((child) => child.status === 'running' && child.background === true)
466
+ .map((child) => child.subagentName),
432
467
  onReload: async () => {
433
468
  const { results } = await reloadRegistry.reloadAll()
434
469
  return formatChannelReloadSummary(results)
@@ -971,6 +1006,7 @@ async function startAgentRuntime(
971
1006
  ...mcpManagerOpt,
972
1007
  agentDir: cwd,
973
1008
  pluginRuntime,
1009
+ permissions: pluginsLoaded.permissions,
974
1010
  getFiredCount: (job) => cronCountStore?.get(job.id, job) ?? 0,
975
1011
  claimController,
976
1012
  commandRunnerFactory,
@@ -1038,6 +1074,10 @@ async function startAgentRuntime(
1038
1074
  forceExit.unref()
1039
1075
  void (async () => {
1040
1076
  if (containerName !== undefined) {
1077
+ // Persist the interrupted-subagent handoff BEFORE markRestartAbortForAllLive
1078
+ // aborts the sessions and stop() tears them down — both read the same live
1079
+ // set this write depends on.
1080
+ await channelManager.router.writeInterruptedSubagentHandoff().catch(() => undefined)
1041
1081
  await markRestartAbortPendingForOrigin(cwd, { kind: 'tui', sessionId: 'tui' }).catch(() => undefined)
1042
1082
  await channelManager.router.markRestartAbortForAllLive().catch(() => undefined)
1043
1083
  }
@@ -77,6 +77,9 @@ export type LlmFetchObserverOptions = {
77
77
  // Schedule fn for tests. Receives (delayMs, callback) and returns a handle
78
78
  // the wrapper can pass to `clear`. Default: `setTimeout`/`clearTimeout`.
79
79
  scheduler?: TimeoutScheduler
80
+ // Test-only: inject a pre-seeded adaptive tracker to assert widening/probe/
81
+ // cooldown behaviour deterministically. Production always constructs its own.
82
+ adaptiveTracker?: AdaptiveTtfbTracker
80
83
  }
81
84
 
82
85
  export type TimeoutScheduler = {
@@ -101,8 +104,134 @@ const ENV_CODEX_OVERALL_MS = 'TYPECLAW_CODEX_OVERALL_MS'
101
104
  const DEFAULT_TTFB_MS = 15_000
102
105
  const DEFAULT_IDLE_MS = 120_000
103
106
  const DEFAULT_OVERALL_MS = 300_000
107
+ // Codex is healthy-FAST but silently hangs: observed header latency p50~1s /
108
+ // p99~8s / max~10.8s, yet hung requests wait out the generic 15s floor. Pinning
109
+ // 13s detects hangs ~2s sooner with ~2.2s margin over the healthy max. Pinned,
110
+ // not adaptive: codex's p95 (~5.6s) never crosses the floor so widening is a
111
+ // no-op, and a longer deadline only makes each silent hang costlier to recover.
112
+ // A concrete per-endpoint `ttfbMs` also disables adaptive eligibility for codex
113
+ // (see `usesAdaptiveTtfb`). Operator-set TYPECLAW_CODEX_TTFB_MS still overrides.
114
+ const DEFAULT_CODEX_TTFB_MS = 13_000
104
115
  const LOG_PREFIX = '[llm-fetch]'
105
116
 
117
+ // Adaptive TTFB: give a provider that is OBSERVED to be slow-but-healthy more
118
+ // pre-headers room, without blunting silent-hang detection for fast providers.
119
+ // A fixed 15s guillotine kills legitimately-slow providers (e.g. GLM cold-start
120
+ // TTFB ~16.5s while its p50 is ~1s); a uniform higher default would let a truly
121
+ // hung FAST provider stall for the same widened window. So widening is scoped to
122
+ // the specific origin whose recent successful header latency is actually high.
123
+ //
124
+ // Signal: rolling p95 of successful header latency (not EWMA — the distributions
125
+ // are bimodal, mostly-1s with occasional 10–16s, so a mean-tracker sits low and
126
+ // never widens for the spike). Nearest-rank p95 over the last ADAPTIVE_WINDOW_MS
127
+ // of samples reacts to the current upper tail and forgets stale slowness.
128
+ const ADAPTIVE_TTFB_FLOOR_MS = 15_000
129
+ const ADAPTIVE_TTFB_CEIL_MS = 30_000
130
+ const ADAPTIVE_TTFB_MULTIPLIER = 2
131
+ const ADAPTIVE_MIN_SAMPLES = 8
132
+ const ADAPTIVE_MAX_SAMPLES = 32
133
+ const ADAPTIVE_WINDOW_MS = 5 * 60_000
134
+ // After a timeout at the CEIL budget, the origin is treated as slow-then-hung:
135
+ // suppress all widening (learned + probe) and fail closed to the floor for this
136
+ // long, so five rapid retries can't each inherit the 30s budget. A sub-floor
137
+ // success clears the suppression early.
138
+ const ADAPTIVE_COOLDOWN_MS = 5 * 60_000
139
+
140
+ function clampMs(value: number, floor: number, ceil: number): number {
141
+ return Math.min(ceil, Math.max(floor, value))
142
+ }
143
+
144
+ function p95(samples: readonly number[]): number {
145
+ const sorted = [...samples].sort((a, b) => a - b)
146
+ const rank = Math.ceil(0.95 * sorted.length)
147
+ return sorted[Math.min(rank, sorted.length) - 1]!
148
+ }
149
+
150
+ type AdaptiveSample = { at: number; headersMs: number }
151
+
152
+ // Per-origin adaptive-TTFB state. One instance lives in the first-installed
153
+ // observer's closure and is shared across every in-flight fetch in the process
154
+ // (single-threaded event loop → plain mutable maps are safe, no locking). Keyed
155
+ // by `${label}|${origin}` so unrelated OpenAI-compatible providers/proxies never
156
+ // inherit each other's latency budget.
157
+ export class AdaptiveTtfbTracker {
158
+ private readonly samples = new Map<string, AdaptiveSample[]>()
159
+ // Whether the origin's next request may spend one CEIL-budget recovery probe.
160
+ // Granted after a below-CEIL timeout (the killed request yielded only a
161
+ // right-censored "≥floor" bound, never a usable sample — a bounded probe is
162
+ // the only way to observe a genuinely-slow header latency past the floor).
163
+ private readonly probeGrant = new Set<string>()
164
+ // Origin → wall-clock time until which widening is suppressed (fail-closed).
165
+ private readonly cooldownUntil = new Map<string, number>()
166
+
167
+ constructor(private readonly now: () => number) {}
168
+
169
+ // Consumes the probe grant atomically so exactly one request gets the ceil.
170
+ resolve(key: string): number {
171
+ if (this.isInCooldown(key)) return ADAPTIVE_TTFB_FLOOR_MS
172
+ const learned = this.learnedTtfb(key)
173
+ if (this.probeGrant.has(key)) {
174
+ this.probeGrant.delete(key)
175
+ return Math.max(learned, ADAPTIVE_TTFB_CEIL_MS)
176
+ }
177
+ return learned
178
+ }
179
+
180
+ recordHeaders(key: string, headersMs: number): void {
181
+ // Any arrived-headers response (200/429/500) proves the origin is
182
+ // responsive, so it's a valid latency sample and clears fail-closed state.
183
+ if (headersMs < ADAPTIVE_TTFB_FLOOR_MS) this.cooldownUntil.delete(key)
184
+ const list = this.samples.get(key) ?? []
185
+ list.push({ at: this.now(), headersMs })
186
+ this.prune(list)
187
+ if (list.length > ADAPTIVE_MAX_SAMPLES) list.splice(0, list.length - ADAPTIVE_MAX_SAMPLES)
188
+ this.samples.set(key, list)
189
+ }
190
+
191
+ // A TTFB timeout at `usedMs`. Below the ceil → grant one recovery probe.
192
+ // At/above the ceil → the widened budget already failed; fail closed.
193
+ recordTimeout(key: string, usedMs: number): void {
194
+ if (usedMs >= ADAPTIVE_TTFB_CEIL_MS) {
195
+ this.probeGrant.delete(key)
196
+ this.cooldownUntil.set(key, this.now() + ADAPTIVE_COOLDOWN_MS)
197
+ return
198
+ }
199
+ this.probeGrant.add(key)
200
+ }
201
+
202
+ reset(): void {
203
+ this.samples.clear()
204
+ this.probeGrant.clear()
205
+ this.cooldownUntil.clear()
206
+ }
207
+
208
+ private learnedTtfb(key: string): number {
209
+ const list = this.samples.get(key)
210
+ if (list === undefined) return ADAPTIVE_TTFB_FLOOR_MS
211
+ this.prune(list)
212
+ if (list.length < ADAPTIVE_MIN_SAMPLES) return ADAPTIVE_TTFB_FLOOR_MS
213
+ const target = Math.ceil(ADAPTIVE_TTFB_MULTIPLIER * p95(list.map((s) => s.headersMs)))
214
+ return clampMs(target, ADAPTIVE_TTFB_FLOOR_MS, ADAPTIVE_TTFB_CEIL_MS)
215
+ }
216
+
217
+ private isInCooldown(key: string): boolean {
218
+ const until = this.cooldownUntil.get(key)
219
+ if (until === undefined) return false
220
+ if (this.now() >= until) {
221
+ this.cooldownUntil.delete(key)
222
+ return false
223
+ }
224
+ return true
225
+ }
226
+
227
+ private prune(list: AdaptiveSample[]): void {
228
+ const cutoff = this.now() - ADAPTIVE_WINDOW_MS
229
+ let drop = 0
230
+ while (drop < list.length && list[drop]!.at < cutoff) drop++
231
+ if (drop > 0) list.splice(0, drop)
232
+ }
233
+ }
234
+
106
235
  const defaultScheduler: TimeoutScheduler = {
107
236
  set: (delayMs, cb) => setTimeout(cb, delayMs),
108
237
  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
@@ -127,10 +256,12 @@ export function defaultLlmFetchEndpoints(env: NodeJS.ProcessEnv = process.env):
127
256
  // GETs to the same host (auth probes, etc.) are deliberately ignored.
128
257
  match: (url, method) =>
129
258
  method === 'POST' && url.hostname === 'chatgpt.com' && url.pathname.includes('/codex/responses'),
130
- // Only pin a per-endpoint value when the operator explicitly set the
131
- // Codex-specific var; unset falls through to the generic TYPECLAW_LLM_*
132
- // (or built-in default) so it isn't masked. See readEnvMsOptional.
133
- ttfbMs: readEnvMsOptional(env, ENV_CODEX_TTFB_MS),
259
+ // TTFB is pinned to the codex-specific default (not the generic 15s) so a
260
+ // silent hang is caught fast and adaptation is bypassed for this endpoint;
261
+ // an operator-set TYPECLAW_CODEX_TTFB_MS still wins. Idle/overall keep the
262
+ // fall-through shape (unset → generic TYPECLAW_LLM_* / built-in default) so
263
+ // they aren't masked. See readEnvMsOptional and DEFAULT_CODEX_TTFB_MS.
264
+ ttfbMs: readEnvMsOptional(env, ENV_CODEX_TTFB_MS) ?? DEFAULT_CODEX_TTFB_MS,
134
265
  idleMs: readEnvMsOptional(env, ENV_CODEX_IDLE_MS),
135
266
  overallMs: readEnvMsOptional(env, ENV_CODEX_OVERALL_MS),
136
267
  },
@@ -153,6 +284,7 @@ type InstallState = {
153
284
  originalFetch: typeof fetch
154
285
  wrapped: typeof fetch
155
286
  claimants: number
287
+ adaptive: AdaptiveTtfbTracker
156
288
  }
157
289
 
158
290
  // Ref-counted so multiple agents in one process (compose, tests) share one
@@ -169,7 +301,7 @@ function matchEndpoint(
169
301
  input: RequestInfo | URL,
170
302
  init: RequestInit | undefined,
171
303
  endpoints: readonly LlmFetchEndpoint[],
172
- ): LlmFetchEndpoint | null {
304
+ ): { endpoint: LlmFetchEndpoint; origin: string } | null {
173
305
  const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase()
174
306
  let urlString: string
175
307
  if (typeof input === 'string') urlString = input
@@ -182,7 +314,7 @@ function matchEndpoint(
182
314
  return null
183
315
  }
184
316
  for (const endpoint of endpoints) {
185
- if (endpoint.match(parsed, method)) return endpoint
317
+ if (endpoint.match(parsed, method)) return { endpoint, origin: parsed.origin }
186
318
  }
187
319
  return null
188
320
  }
@@ -194,6 +326,18 @@ function quote(value: string | null): string {
194
326
 
195
327
  function formatLine(fields: {
196
328
  provider: string
329
+ // The request origin (scheme+host, no path/query — non-sensitive) that scopes
330
+ // `seq`. `provider` alone is ambiguous: `openai-compatible` accepts arbitrary
331
+ // proxy origins and the observer is shared across agents, so two origins can
332
+ // each emit `provider=openai-compatible seq=1`. The origin disambiguates them
333
+ // so seq is attributable per stream.
334
+ origin: string
335
+ // Per-(provider,origin) monotonic fetch sequence. A tight run of increasing seq
336
+ // on one provider|origin is the observable signature of retry MULTIPLICATION (the
337
+ // pi-ai codex provider's internal loop stacked under typeclaw's own retries):
338
+ // it makes the physical-fetch count per logical turn countable from logs alone.
339
+ // Observability only — nothing reads this back to drive behavior.
340
+ seq: number
197
341
  status: number | null
198
342
  headersMs: number | null
199
343
  firstByteMs: number | null
@@ -207,6 +351,8 @@ function formatLine(fields: {
207
351
  return [
208
352
  LOG_PREFIX,
209
353
  `provider=${fields.provider}`,
354
+ `origin=${fields.origin}`,
355
+ `seq=${fields.seq}`,
210
356
  `status=${fields.status === null ? 'null' : fields.status}`,
211
357
  `headers_ms=${fields.headersMs === null ? 'null' : fields.headersMs}`,
212
358
  `first_byte_ms=${fields.firstByteMs === null ? 'null' : fields.firstByteMs}`,
@@ -245,6 +391,8 @@ type ResolvedTimeouts = {
245
391
 
246
392
  type BodyTapConfig = {
247
393
  provider: string
394
+ origin: string
395
+ seq: number
248
396
  idleMs: number
249
397
  overallMs: number
250
398
  scheduler: TimeoutScheduler
@@ -265,6 +413,8 @@ function attachBodyTimingTap(
265
413
  logger.info(
266
414
  formatLine({
267
415
  provider: config.provider,
416
+ origin: config.origin,
417
+ seq: config.seq,
268
418
  status,
269
419
  headersMs,
270
420
  firstByteMs: null,
@@ -290,6 +440,8 @@ function attachBodyTimingTap(
290
440
  logger.info(
291
441
  formatLine({
292
442
  provider: config.provider,
443
+ origin: config.origin,
444
+ seq: config.seq,
293
445
  status,
294
446
  headersMs,
295
447
  firstByteMs,
@@ -454,6 +606,16 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
454
606
  overallMs: readEnvMs(process.env, ENV_OVERALL_MS, DEFAULT_OVERALL_MS),
455
607
  }
456
608
  const originalFetch = globalThis.fetch
609
+ const adaptive = opts.adaptiveTracker ?? new AdaptiveTtfbTracker(now)
610
+ const fetchSeqByKey = new Map<string, number>()
611
+ // Adaptation is a property of the built-in floor default only. Any explicit
612
+ // static TTFB (observer opt, per-endpoint value, or a set TYPECLAW_*_TTFB_MS)
613
+ // means the operator pinned a deadline — honour it verbatim, no widening.
614
+ const adaptiveEligible =
615
+ timeoutsEnabled &&
616
+ opts.ttfbMs === undefined &&
617
+ readEnvMsOptional(process.env, ENV_TTFB_MS) === undefined &&
618
+ envDefaults.ttfbMs === DEFAULT_TTFB_MS
457
619
 
458
620
  // Precedence per timer: explicit observer-level option wins over the endpoint's
459
621
  // own value, which wins over the generic env/default. An explicit `opts.*` means
@@ -476,25 +638,31 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
476
638
  input: Parameters<typeof fetch>[0],
477
639
  init?: Parameters<typeof fetch>[1],
478
640
  ): Promise<Response> => {
479
- const endpoint = matchEndpoint(input, init, endpoints)
480
- if (endpoint === null) {
641
+ const matched = matchEndpoint(input, init, endpoints)
642
+ if (matched === null) {
481
643
  return originalFetch(input, init)
482
644
  }
645
+ const { endpoint, origin } = matched
483
646
  const perRequest = (init as LlmFetchObservedRequestInit | undefined)?.[LLM_FETCH_OBSERVER_TIMEOUTS]
484
647
  const timeouts = resolveTimeouts(endpoint, perRequest)
485
648
  const provider = endpoint.label
649
+ const adaptiveKey = `${provider}|${origin}`
650
+ const seq = (fetchSeqByKey.get(adaptiveKey) ?? 0) + 1
651
+ fetchSeqByKey.set(adaptiveKey, seq)
652
+ const usesAdaptiveTtfb = adaptiveEligible && perRequest?.ttfbMs === undefined && endpoint.ttfbMs === undefined
653
+ const effectiveTtfbMs = usesAdaptiveTtfb ? adaptive.resolve(adaptiveKey) : timeouts.ttfbMs
486
654
  const start = now()
487
655
 
488
656
  let ttfbCause: 'ttfb_timeout' | null = null
489
657
  let ttfbHandle: unknown = null
490
658
  let initWithSignal: RequestInit | undefined = init
491
- if (timeouts.ttfbMs > 0) {
659
+ if (effectiveTtfbMs > 0) {
492
660
  const ttfbController = new AbortController()
493
- ttfbHandle = scheduler.set(timeouts.ttfbMs, () => {
661
+ ttfbHandle = scheduler.set(effectiveTtfbMs, () => {
494
662
  ttfbCause = 'ttfb_timeout'
495
663
  ttfbController.abort(
496
664
  new Error(
497
- `${provider} fetch timed out before response headers after ${timeouts.ttfbMs}ms (typeclaw observer timeout)`,
665
+ `${provider} fetch timed out before response headers after ${effectiveTtfbMs}ms (typeclaw observer timeout)`,
498
666
  ),
499
667
  )
500
668
  })
@@ -508,15 +676,18 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
508
676
  } catch (err) {
509
677
  if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
510
678
  const isTtfbAbort = ttfbCause === 'ttfb_timeout'
679
+ if (isTtfbAbort && usesAdaptiveTtfb) adaptive.recordTimeout(adaptiveKey, effectiveTtfbMs)
511
680
  const surfacedError = isTtfbAbort
512
681
  ? new Error(
513
- `${provider} fetch timed out before response headers after ${timeouts.ttfbMs}ms (typeclaw observer timeout)`,
682
+ `${provider} fetch timed out before response headers after ${effectiveTtfbMs}ms (typeclaw observer timeout)`,
514
683
  )
515
684
  : err
516
685
  const message = surfacedError instanceof Error ? surfacedError.message : String(surfacedError)
517
686
  logger.info(
518
687
  formatLine({
519
688
  provider,
689
+ origin,
690
+ seq,
520
691
  status: null,
521
692
  headersMs: null,
522
693
  firstByteMs: null,
@@ -532,10 +703,13 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
532
703
  }
533
704
  if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
534
705
  const headersMs = now() - start
706
+ if (usesAdaptiveTtfb) adaptive.recordHeaders(adaptiveKey, headersMs)
535
707
  const retryAfter = response.headers.get('retry-after')
536
708
  const requestId = response.headers.get('x-request-id')
537
709
  return attachBodyTimingTap(response, start, headersMs, response.status, retryAfter, requestId, now, logger, {
538
710
  provider,
711
+ origin,
712
+ seq,
539
713
  idleMs: timeouts.idleMs,
540
714
  overallMs: timeouts.overallMs,
541
715
  scheduler,
@@ -550,7 +724,7 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
550
724
 
551
725
  globalThis.fetch = wrapped
552
726
 
553
- installed = { originalFetch, wrapped, claimants: 1 }
727
+ installed = { originalFetch, wrapped, claimants: 1, adaptive }
554
728
  return makeRelease(wrapped)
555
729
  }
556
730
 
@@ -564,6 +738,7 @@ function makeRelease(wrapped: typeof fetch): () => void {
564
738
  released = true
565
739
  installed.claimants--
566
740
  if (installed.claimants > 0) return
741
+ installed.adaptive.reset()
567
742
  if (globalThis.fetch === installed.wrapped) {
568
743
  globalThis.fetch = installed.originalFetch
569
744
  }