typeclaw 0.45.1 → 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 (142) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -1
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +151 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +198 -0
  11. package/src/agent/plugin-tools.ts +379 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1050 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +143 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +27 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/index.ts +2 -1
  32. package/src/bundled-plugins/backup/runner.ts +2 -1
  33. package/src/bundled-plugins/doc-render/render.ts +93 -12
  34. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  35. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  36. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  37. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  38. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  39. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  40. package/src/bundled-plugins/memory/README.md +23 -11
  41. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  42. package/src/bundled-plugins/memory/citations.ts +22 -9
  43. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  44. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  45. package/src/bundled-plugins/memory/index.ts +0 -4
  46. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  47. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  48. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  49. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  50. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  51. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  52. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  53. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  54. package/src/bundled-plugins/reviewer/index.ts +2 -2
  55. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  56. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  57. package/src/bundled-plugins/scout/scout.ts +8 -0
  58. package/src/bundled-plugins/security/index.ts +4 -4
  59. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  60. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  61. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  62. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  63. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  64. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  65. package/src/channels/adapters/discord-bot.ts +66 -6
  66. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  67. package/src/channels/adapters/discord-id.ts +4 -0
  68. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  69. package/src/channels/adapters/discord.ts +57 -7
  70. package/src/channels/adapters/github/auth-app.ts +41 -12
  71. package/src/channels/adapters/github/index.ts +23 -11
  72. package/src/channels/adapters/github/review-submitter.ts +302 -0
  73. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  74. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  75. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  76. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  77. package/src/channels/adapters/slack-bot.ts +19 -8
  78. package/src/channels/adapters/slack-classify.ts +21 -2
  79. package/src/channels/adapters/slack.ts +59 -7
  80. package/src/channels/adapters/telegram-bot.ts +18 -5
  81. package/src/channels/adapters/webex-bot.ts +8 -3
  82. package/src/channels/adapters/webex.ts +8 -3
  83. package/src/channels/fetch-attachment.ts +43 -0
  84. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  85. package/src/channels/github-token-bridge.ts +10 -3
  86. package/src/channels/manager.ts +9 -0
  87. package/src/channels/router.ts +248 -6
  88. package/src/channels/types.ts +28 -1
  89. package/src/cli/channel.ts +1 -1
  90. package/src/cli/init.ts +1 -1
  91. package/src/cli/model.ts +57 -7
  92. package/src/compose/stop.ts +17 -5
  93. package/src/config/config.ts +6 -6
  94. package/src/config/models-mutation.ts +13 -1
  95. package/src/config/providers.ts +176 -0
  96. package/src/container/start.ts +49 -10
  97. package/src/doctor/checks.ts +3 -1
  98. package/src/doctor/commit.ts +2 -1
  99. package/src/doctor/file-ownership.ts +52 -0
  100. package/src/dreams/git.ts +2 -1
  101. package/src/git/hookless.ts +5 -0
  102. package/src/git/reconcile-ignored.ts +18 -5
  103. package/src/git/secret-history.ts +371 -0
  104. package/src/git/system-commit.ts +12 -6
  105. package/src/init/dockerfile.ts +86 -5
  106. package/src/init/index.ts +17 -5
  107. package/src/init/models-dev.ts +4 -0
  108. package/src/init/validate-api-key.ts +2 -0
  109. package/src/mcp/tools.ts +16 -3
  110. package/src/permissions/builtins.ts +3 -1
  111. package/src/plugin/context.ts +2 -0
  112. package/src/plugin/index.ts +1 -0
  113. package/src/plugin/manager.ts +4 -0
  114. package/src/plugin/types.ts +21 -0
  115. package/src/run/index.ts +40 -0
  116. package/src/run/llm-fetch-observer.ts +41 -4
  117. package/src/sandbox/build.ts +37 -15
  118. package/src/sandbox/canonical-secrets.ts +18 -0
  119. package/src/sandbox/env-exposure.ts +80 -0
  120. package/src/sandbox/errors.ts +13 -6
  121. package/src/sandbox/hidden-paths.ts +102 -44
  122. package/src/sandbox/index.ts +22 -4
  123. package/src/sandbox/package-install.ts +3 -27
  124. package/src/sandbox/policy.ts +11 -25
  125. package/src/sandbox/privileged-runtime.ts +255 -0
  126. package/src/sandbox/session-tmp.ts +8 -2
  127. package/src/sandbox/writable-zones.ts +204 -140
  128. package/src/secrets/index.ts +8 -0
  129. package/src/secrets/refresh-provider-oauth.ts +128 -0
  130. package/src/server/command-runner.ts +48 -4
  131. package/src/server/index.ts +4 -0
  132. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  133. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  134. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  135. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  136. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  137. package/src/skills/typeclaw-config/SKILL.md +5 -5
  138. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  139. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  140. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  141. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  142. 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
  }
@@ -104,6 +104,14 @@ const ENV_CODEX_OVERALL_MS = 'TYPECLAW_CODEX_OVERALL_MS'
104
104
  const DEFAULT_TTFB_MS = 15_000
105
105
  const DEFAULT_IDLE_MS = 120_000
106
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
107
115
  const LOG_PREFIX = '[llm-fetch]'
108
116
 
109
117
  // Adaptive TTFB: give a provider that is OBSERVED to be slow-but-healthy more
@@ -248,10 +256,12 @@ export function defaultLlmFetchEndpoints(env: NodeJS.ProcessEnv = process.env):
248
256
  // GETs to the same host (auth probes, etc.) are deliberately ignored.
249
257
  match: (url, method) =>
250
258
  method === 'POST' && url.hostname === 'chatgpt.com' && url.pathname.includes('/codex/responses'),
251
- // Only pin a per-endpoint value when the operator explicitly set the
252
- // Codex-specific var; unset falls through to the generic TYPECLAW_LLM_*
253
- // (or built-in default) so it isn't masked. See readEnvMsOptional.
254
- 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,
255
265
  idleMs: readEnvMsOptional(env, ENV_CODEX_IDLE_MS),
256
266
  overallMs: readEnvMsOptional(env, ENV_CODEX_OVERALL_MS),
257
267
  },
@@ -316,6 +326,18 @@ function quote(value: string | null): string {
316
326
 
317
327
  function formatLine(fields: {
318
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
319
341
  status: number | null
320
342
  headersMs: number | null
321
343
  firstByteMs: number | null
@@ -329,6 +351,8 @@ function formatLine(fields: {
329
351
  return [
330
352
  LOG_PREFIX,
331
353
  `provider=${fields.provider}`,
354
+ `origin=${fields.origin}`,
355
+ `seq=${fields.seq}`,
332
356
  `status=${fields.status === null ? 'null' : fields.status}`,
333
357
  `headers_ms=${fields.headersMs === null ? 'null' : fields.headersMs}`,
334
358
  `first_byte_ms=${fields.firstByteMs === null ? 'null' : fields.firstByteMs}`,
@@ -367,6 +391,8 @@ type ResolvedTimeouts = {
367
391
 
368
392
  type BodyTapConfig = {
369
393
  provider: string
394
+ origin: string
395
+ seq: number
370
396
  idleMs: number
371
397
  overallMs: number
372
398
  scheduler: TimeoutScheduler
@@ -387,6 +413,8 @@ function attachBodyTimingTap(
387
413
  logger.info(
388
414
  formatLine({
389
415
  provider: config.provider,
416
+ origin: config.origin,
417
+ seq: config.seq,
390
418
  status,
391
419
  headersMs,
392
420
  firstByteMs: null,
@@ -412,6 +440,8 @@ function attachBodyTimingTap(
412
440
  logger.info(
413
441
  formatLine({
414
442
  provider: config.provider,
443
+ origin: config.origin,
444
+ seq: config.seq,
415
445
  status,
416
446
  headersMs,
417
447
  firstByteMs,
@@ -577,6 +607,7 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
577
607
  }
578
608
  const originalFetch = globalThis.fetch
579
609
  const adaptive = opts.adaptiveTracker ?? new AdaptiveTtfbTracker(now)
610
+ const fetchSeqByKey = new Map<string, number>()
580
611
  // Adaptation is a property of the built-in floor default only. Any explicit
581
612
  // static TTFB (observer opt, per-endpoint value, or a set TYPECLAW_*_TTFB_MS)
582
613
  // means the operator pinned a deadline — honour it verbatim, no widening.
@@ -616,6 +647,8 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
616
647
  const timeouts = resolveTimeouts(endpoint, perRequest)
617
648
  const provider = endpoint.label
618
649
  const adaptiveKey = `${provider}|${origin}`
650
+ const seq = (fetchSeqByKey.get(adaptiveKey) ?? 0) + 1
651
+ fetchSeqByKey.set(adaptiveKey, seq)
619
652
  const usesAdaptiveTtfb = adaptiveEligible && perRequest?.ttfbMs === undefined && endpoint.ttfbMs === undefined
620
653
  const effectiveTtfbMs = usesAdaptiveTtfb ? adaptive.resolve(adaptiveKey) : timeouts.ttfbMs
621
654
  const start = now()
@@ -653,6 +686,8 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
653
686
  logger.info(
654
687
  formatLine({
655
688
  provider,
689
+ origin,
690
+ seq,
656
691
  status: null,
657
692
  headersMs: null,
658
693
  firstByteMs: null,
@@ -673,6 +708,8 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
673
708
  const requestId = response.headers.get('x-request-id')
674
709
  return attachBodyTimingTap(response, start, headersMs, response.status, retryAfter, requestId, now, logger, {
675
710
  provider,
711
+ origin,
712
+ seq,
676
713
  idleMs: timeouts.idleMs,
677
714
  overallMs: timeouts.overallMs,
678
715
  scheduler,
@@ -15,6 +15,13 @@ const { dirname } = posix
15
15
  export type SandboxedCommand = {
16
16
  argv: string[]
17
17
  commandString: string
18
+ // Exact environment the bwrap PARENT process must run with. bwrap only drops
19
+ // --clearenv when there are inherited names and then --unsetenv's the keys
20
+ // present in process.env AT BUILD TIME — a secret added to the live env between
21
+ // build and spawn would otherwise be inherited. The spawn must therefore start
22
+ // from THIS snapshot (defaults + resolved set + snapshotted inherited values),
23
+ // never the live process.env, so late-added keys can't reach the sandbox.
24
+ spawnEnv: Record<string, string>
18
25
  }
19
26
 
20
27
  // Fixed fd the rendered commandString opens to /dev/null for --ro-bind-data
@@ -35,7 +42,7 @@ export function buildSandboxedCommand(command: string, policy: SandboxPolicy = {
35
42
  const argv = buildArgv(command, policy)
36
43
  const needsMaskFd = (policy.masks?.files?.length ?? 0) > 0
37
44
  const commandString = needsMaskFd ? `${formatCommand(argv)} ${MASK_DATA_FD}</dev/null` : formatCommand(argv)
38
- return { argv, commandString }
45
+ return { argv, commandString, spawnEnv: resolveSpawnEnv(policy.env) }
39
46
  }
40
47
 
41
48
  function buildArgv(command: string, policy: SandboxPolicy): string[] {
@@ -84,8 +91,21 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
84
91
  argv.push('--die-with-parent')
85
92
  }
86
93
 
87
- argv.push('--clearenv')
94
+ const inheritedNames = new Set(policy.env?.inherit ?? [])
95
+ if (inheritedNames.size === 0) {
96
+ argv.push('--clearenv')
97
+ } else {
98
+ const retained = new Set([
99
+ ...inheritedNames,
100
+ ...Object.keys(DEFAULT_SANDBOX_ENV),
101
+ ...Object.keys(policy.env?.set ?? {}),
102
+ ])
103
+ for (const key of Object.keys(process.env).sort()) {
104
+ if (!retained.has(key)) argv.push('--unsetenv', key)
105
+ }
106
+ }
88
107
  for (const [key, value] of Object.entries(resolveEnv(policy.env))) {
108
+ if (inheritedNames.has(key)) continue
89
109
  argv.push('--setenv', key, value)
90
110
  }
91
111
 
@@ -168,10 +188,9 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
168
188
  }
169
189
 
170
190
  appendWritableRoot(argv, policy)
171
- appendMasks(argv, policy)
172
191
  appendWritable(argv, policy)
192
+ appendMasks(argv, policy)
173
193
  appendProtected(argv, policy)
174
- appendBlockedCreation(argv, policy)
175
194
  appendSymlinks(argv, policy)
176
195
 
177
196
  if (policy.cwd !== undefined) {
@@ -218,17 +237,6 @@ function appendProtected(argv: string[], policy: SandboxPolicy): void {
218
237
  }
219
238
  }
220
239
 
221
- // Occupies each path with an empty read-only object so a writable-root install
222
- // script cannot CREATE a real file there. /dev/null always exists (bwrap mounts
223
- // --dev), so unlike --ro-bind-data this needs no manufactured placeholder on the
224
- // host FS. Renders after appendProtected: both are RO carve-outs of the RW root,
225
- // last-op-wins.
226
- function appendBlockedCreation(argv: string[], policy: SandboxPolicy): void {
227
- for (const file of policy.blockedCreation?.files ?? []) {
228
- argv.push('--ro-bind', '/dev/null', file)
229
- }
230
- }
231
-
232
240
  // Rendered after every bind (incl. the /tmp session bind in policy.mounts) so
233
241
  // last-op-wins keeps the symlink: a `/tmp/.foo` dest emitted before the /tmp
234
242
  // bind would be erased by it. `--dir` ensures the symlink's parent exists inside
@@ -267,6 +275,20 @@ function resolveEnv(env: SandboxEnvPolicy | undefined): Record<string, string> {
267
275
  return resolved
268
276
  }
269
277
 
278
+ // The exact env for the bwrap parent process: the --setenv/passthrough values
279
+ // PLUS a one-shot snapshot of each inherited name's current value. Because the
280
+ // parent starts from exactly this map (and nothing else), a key added to the
281
+ // live process.env after this point cannot be inherited — closing the
282
+ // build-to-spawn TOCTOU on the --unsetenv enumeration.
283
+ function resolveSpawnEnv(env: SandboxEnvPolicy | undefined): Record<string, string> {
284
+ const resolved = resolveEnv(env)
285
+ for (const name of env?.inherit ?? []) {
286
+ const value = process.env[name]
287
+ if (value !== undefined) resolved[name] = value
288
+ }
289
+ return resolved
290
+ }
291
+
270
292
  // Token-boundary match: the normalized command must equal a prefix exactly or
271
293
  // start with `prefix + ' '`. Substring matching would let `git-evil ...` slip
272
294
  // past a `git` prefix; this does not.
@@ -0,0 +1,18 @@
1
+ export const CANONICAL_AGENT_SECRET_DIRS = [
2
+ 'workspace/.config/gws',
3
+ 'workspace/.agent-messenger',
4
+ '.typeclaw/home',
5
+ ] as const
6
+
7
+ export const CANONICAL_AGENT_SECRET_FILES = ['.env', 'secrets.json', 'auth.json'] as const
8
+
9
+ export const CANONICAL_HOME_SECRET_DIRS = [
10
+ '.ssh',
11
+ '.config/gh',
12
+ '.config/gws',
13
+ '.agent-messenger',
14
+ '.codex',
15
+ '.claude',
16
+ ] as const
17
+
18
+ export const CANONICAL_HOME_SECRET_FILES = ['.gitconfig', '.claude.json', '.netrc'] as const
@@ -0,0 +1,80 @@
1
+ import { DEFAULT_SANDBOX_ENV } from './policy'
2
+
3
+ // DEFAULT_SANDBOX_ENV names are sandbox-OWNED: build.ts renders them via
4
+ // --setenv, but an inherited name skips that --setenv (inherit keeps the parent
5
+ // value), so letting `.env` PATH/HOME/BUN_* through would REPLACE the sandbox's
6
+ // safe fixed values — a PATH/loader hijack of the sandbox mechanism itself.
7
+ const RESERVED_SANDBOX_ENV_NAMES = new Set(Object.keys(DEFAULT_SANDBOX_ENV))
8
+
9
+ // Names TypeClaw's own runtime/broker OWNS: github-cli-auth gates GH_TOKEN /
10
+ // GITHUB_TOKEN behind a capability + command-scoped overlay (only a validated
11
+ // `gh` call gets the token, out of argv), and the TYPECLAW_* tokens are
12
+ // host/container-injected auth. Ambient inheritance would bypass the broker and
13
+ // hand a reusable credential to arbitrary bash — so these are withheld even when
14
+ // declared in `.env`. Not a credential-name registry: these five names are ones
15
+ // the runtime CLAIMS, distinct from operator credentials (which belong in
16
+ // secrets.json). A matching `.env` line would otherwise make the runtime value
17
+ // eligible; the parsed-value gate (below) also blocks the empty-declaration case.
18
+ const RUNTIME_OWNED_ENV_NAMES = new Set<string>([
19
+ 'GH_TOKEN',
20
+ 'GITHUB_TOKEN',
21
+ 'TYPECLAW_TUI_TOKEN',
22
+ 'TYPECLAW_HOSTD_TOKEN',
23
+ 'TYPECLAW_HOSTD_BROKER_TOKEN',
24
+ ])
25
+
26
+ // Process-hijack vectors: an inherited value here changes how the shell, loader,
27
+ // or a runtime INTERPRETS later commands (arbitrary code load, config override,
28
+ // credential-socket handoff). SHELLOPTS/BASHOPTS/PS4/BASH_XTRACEFD and the
29
+ // BASH_FUNC_ prefix are OUTER-shell controls that execute in the `bash -c` that
30
+ // launches bwrap — before confinement begins (e.g. SHELLOPTS=xtrace + a
31
+ // command-substituting PS4, or an exported `BASH_FUNC_bwrap%%` replacing the
32
+ // bwrap command). These subvert the sandbox rather than expose a value.
33
+ const EXECUTION_CONTROL_ENV_NAMES = new Set<string>([
34
+ 'BASH_ENV',
35
+ 'ENV',
36
+ 'SHELLOPTS',
37
+ 'BASHOPTS',
38
+ 'PS4',
39
+ 'BASH_XTRACEFD',
40
+ 'LD_PRELOAD',
41
+ 'LD_LIBRARY_PATH',
42
+ 'LD_AUDIT',
43
+ 'NODE_OPTIONS',
44
+ 'BUN_OPTIONS',
45
+ 'PYTHONPATH',
46
+ 'PYTHONSTARTUP',
47
+ 'RUBYOPT',
48
+ 'PERL5OPT',
49
+ 'SSH_AUTH_SOCK',
50
+ 'KUBECONFIG',
51
+ ])
52
+
53
+ const EXECUTION_CONTROL_ENV_PREFIXES = ['GIT_CONFIG', 'BASH_FUNC_'] as const
54
+
55
+ // Withheld ONLY when the name would compromise sandbox integrity or the runtime
56
+ // credential broker — not for being credential-shaped. `.env` is the operator's
57
+ // expose-to-the-agent surface: every value they declare there reaches model bash
58
+ // by design. Credentials that must stay hidden belong in secrets.json.
59
+ function isWithheldEnvName(name: string): boolean {
60
+ if (RESERVED_SANDBOX_ENV_NAMES.has(name)) return true
61
+ if (RUNTIME_OWNED_ENV_NAMES.has(name)) return true
62
+ if (EXECUTION_CONTROL_ENV_NAMES.has(name)) return true
63
+ return EXECUTION_CONTROL_ENV_PREFIXES.some((prefix) => name === prefix || name.startsWith(prefix))
64
+ }
65
+
66
+ // Every name an operator declared in the `.env` FILE with a non-empty value,
67
+ // minus the sandbox-integrity/broker withholds. Eligibility is decided from the
68
+ // PARSED `.env` value, never process.env: an empty `.env` line (`X=`) is not an
69
+ // operator expose-choice even if hydrateChannelEnvFromSecrets later fills
70
+ // process.env[X] from secrets.json. The inherited VALUE is still snapshotted
71
+ // from process.env at spawn time.
72
+ export function resolveExposableEnvNames(declaredEnv: ReadonlyMap<string, string>): string[] {
73
+ const out: string[] = []
74
+ for (const [name, fileValue] of declaredEnv) {
75
+ if (fileValue.length === 0) continue
76
+ if (isWithheldEnvName(name)) continue
77
+ out.push(name)
78
+ }
79
+ return out
80
+ }
@@ -7,6 +7,13 @@ export class SandboxUnavailableError extends Error {
7
7
  }
8
8
  }
9
9
 
10
+ export class SandboxMaskTargetError extends Error {
11
+ override readonly name = 'SandboxMaskTargetError'
12
+ constructor(target: string, reason: string) {
13
+ super(`sandbox canonical mask target is unsafe: ${target} (${reason}). Refusing to run model-driven bash.`)
14
+ }
15
+ }
16
+
10
17
  // Raised by the optional command-filter knobs (allowPrefixes,
11
18
  // rejectShellMetacharacters). These are consumer-opt-in restrictions layered
12
19
  // ABOVE the always-on kernel containment, so a rejection here is a policy
@@ -20,9 +27,9 @@ export class SandboxPolicyError extends Error {
20
27
  }
21
28
 
22
29
  // Raised when the /proc strategy degraded to the empty `tmpfs` fallback AND the
23
- // command needs a real /proc (a bun install / bunx / bun run that reads the
30
+ // command needs a real /proc (bunx / bun run that reads the
24
31
  // kernel-backed /proc/self/{fd,maps}). Without this pre-check Bun aborts deep in
25
- // its install pipeline with the opaque "NotDir" (ENOTDIR) error, which the model
32
+ // its runner pipeline with the opaque "NotDir" (ENOTDIR) error, which the model
26
33
  // misreads as a bad package or a transient hiccup and retries forever. Surfacing
27
34
  // it here, before the command runs, turns the failure into one the operator (or
28
35
  // the model) can act on: it is an environment/runtime limitation, not the
@@ -31,8 +38,8 @@ export class SandboxDegradedProcError extends Error {
31
38
  override readonly name = 'SandboxDegradedProcError'
32
39
  constructor() {
33
40
  super(
34
- 'sandbox /proc is in degraded tmpfs mode, so bun package commands ' +
35
- '(bun install / bun add / bunx / bun run) cannot run: Bun needs a real ' +
41
+ 'sandbox /proc is in degraded tmpfs mode, so bun package runners ' +
42
+ '(bunx / bun x / bun create / bun run) cannot run: Bun needs a real ' +
36
43
  '/proc/self/fd, which this strategy cannot provide, and would otherwise ' +
37
44
  'fail with an opaque "NotDir" error. This is a container/runtime limitation ' +
38
45
  '(no usable user namespaces for the cap-free proc-bind strategy), not a ' +
@@ -59,8 +66,8 @@ export class SandboxProcProbeUnverifiedError extends Error {
59
66
  super(
60
67
  'sandbox /proc strategy could not be verified right now: the cap-free ' +
61
68
  'proc-bind safety probe stayed inconclusive (usually transient load on the ' +
62
- 'host while the container was starting up), so this bun package command ' +
63
- '(bun install / bun add / bunx / bun run) was held back rather than run ' +
69
+ 'host while the container was starting up), so this bun package runner ' +
70
+ '(bunx / bun x / bun create / bun run) was held back rather than run ' +
64
71
  'under a broken /proc. This is almost certainly temporary and NOT a problem ' +
65
72
  'with the command or the package: retry the SAME command in a few seconds — ' +
66
73
  'the next attempt re-probes and normally succeeds.',