typeclaw 0.50.0 → 0.51.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 (90) hide show
  1. package/dist/types/agent/bash-sandbox-env.d.ts +15 -0
  2. package/dist/types/agent/bash-sandbox-proc.d.ts +8 -0
  3. package/dist/types/agent/bash-sandbox.d.ts +94 -0
  4. package/dist/types/agent/compaction.d.ts +4 -4
  5. package/dist/types/agent/idle-compaction.d.ts +1 -0
  6. package/dist/types/agent/index.d.ts +5 -17
  7. package/dist/types/agent/output-allowance.d.ts +4 -0
  8. package/dist/types/agent/plugin-tools.d.ts +4 -75
  9. package/dist/types/agent/system-prompt-composition.d.ts +17 -0
  10. package/dist/types/agent/tools/ddg.d.ts +9 -0
  11. package/dist/types/agent/tools/stream-snapshot.d.ts +1 -1
  12. package/dist/types/agent/tools/webfetch/tool.d.ts +1 -1
  13. package/dist/types/channels/github-review-check.d.ts +1 -1
  14. package/dist/types/channels/router.d.ts +11 -49
  15. package/dist/types/config/config.d.ts +24 -11
  16. package/dist/types/config/providers.d.ts +3 -1
  17. package/dist/types/container/start.d.ts +1 -0
  18. package/dist/types/eval/cell.d.ts +26 -0
  19. package/dist/types/eval/config.d.ts +19 -0
  20. package/dist/types/eval/dispatch.d.ts +7 -0
  21. package/dist/types/eval/kernel.d.ts +28 -0
  22. package/dist/types/eval/process.d.ts +23 -0
  23. package/dist/types/eval/protocol.d.ts +34 -0
  24. package/dist/types/eval/sandbox.d.ts +10 -0
  25. package/dist/types/eval/tool.d.ts +17 -0
  26. package/dist/types/eval/wire.d.ts +33 -0
  27. package/dist/types/sandbox/env-exposure.d.ts +2 -0
  28. package/package.json +5 -5
  29. package/src/agent/bash-sandbox-env.ts +104 -0
  30. package/src/agent/bash-sandbox-proc.ts +70 -0
  31. package/src/agent/bash-sandbox.ts +225 -0
  32. package/src/agent/compaction.ts +22 -10
  33. package/src/agent/idle-compaction.ts +7 -3
  34. package/src/agent/index.ts +66 -157
  35. package/src/agent/output-allowance.ts +7 -0
  36. package/src/agent/plugin-tools.ts +29 -379
  37. package/src/agent/session-origin.ts +2 -1
  38. package/src/agent/subagent-completion-reminder.ts +2 -2
  39. package/src/agent/system-prompt-composition.ts +141 -0
  40. package/src/agent/system-prompt.ts +4 -4
  41. package/src/agent/todo/scope.ts +1 -1
  42. package/src/agent/tools/ddg.ts +71 -11
  43. package/src/agent/tools-without-local-file-operands.ts +4 -0
  44. package/src/browser/fill-secret.ts +307 -0
  45. package/src/bundled-plugins/explorer/explorer.ts +1 -1
  46. package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts +40 -16
  47. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +12 -7
  48. package/src/bundled-plugins/github-cli-auth/index.ts +10 -1
  49. package/src/bundled-plugins/managed-browser/index.ts +107 -2
  50. package/src/bundled-plugins/memory/dreaming.ts +4 -1
  51. package/src/bundled-plugins/memory/load-memory.ts +2 -4
  52. package/src/bundled-plugins/memory/memory-logger.ts +74 -2
  53. package/src/bundled-plugins/memory/transcript-preload.ts +103 -0
  54. package/src/bundled-plugins/memory/vector/hybrid.ts +25 -14
  55. package/src/bundled-plugins/security/policies/private-surface-read.ts +166 -201
  56. package/src/channels/adapters/discord-bot-reference.ts +5 -4
  57. package/src/channels/adapters/discord-bot.ts +1 -0
  58. package/src/channels/adapters/discord-classify.ts +8 -3
  59. package/src/channels/adapters/discord.ts +29 -0
  60. package/src/channels/github-review-check.ts +5 -1
  61. package/src/channels/github-review-verdict-coordinator.ts +68 -2
  62. package/src/channels/router.ts +88 -107
  63. package/src/channels/subagent-completion-bridge.ts +3 -2
  64. package/src/cli/hostd.ts +3 -0
  65. package/src/config/config.ts +15 -0
  66. package/src/config/providers.ts +10 -4
  67. package/src/container/start.ts +37 -1
  68. package/src/doctor/checks.ts +25 -16
  69. package/src/doctor/index.ts +48 -12
  70. package/src/doctor/operational-incidents.ts +16 -1
  71. package/src/doctor/plugin-bridge.ts +14 -1
  72. package/src/doctor/stage.ts +14 -0
  73. package/src/doctor/types.ts +6 -0
  74. package/src/eval/cell.ts +93 -0
  75. package/src/eval/config.ts +32 -0
  76. package/src/eval/dispatch.ts +67 -0
  77. package/src/eval/entry.ts +261 -0
  78. package/src/eval/kernel.ts +154 -0
  79. package/src/eval/process.ts +113 -0
  80. package/src/eval/protocol.ts +26 -0
  81. package/src/eval/redeclare.ts +174 -0
  82. package/src/eval/sandbox.ts +114 -0
  83. package/src/eval/tool.ts +98 -0
  84. package/src/eval/wire.ts +93 -0
  85. package/src/operations/classify-tool-outcome.ts +1 -1
  86. package/src/plugin/core-tool-names.ts +6 -1
  87. package/src/sandbox/env-exposure.ts +20 -0
  88. package/src/server/index.ts +46 -11
  89. package/src/skills/typeclaw-config/SKILL.md +20 -2
  90. package/typeclaw.schema.json +52 -0
@@ -8,6 +8,7 @@ import { z } from 'zod'
8
8
 
9
9
  import { BROWSER_ENGINE_IDS, BROWSER_EXTENSION_IDS } from '@/browser/registry'
10
10
  import { channelsSchema, SEEDED_GITHUB_EVENT_ALLOWLISTS } from '@/channels/schema'
11
+ import { evalConfigSchema } from '@/eval/config'
11
12
  import { commitSystemFileSync } from '@/git/system-commit'
12
13
  import { parseMatchRule } from '@/permissions/match-rule'
13
14
  import { rolesConfigSchema } from '@/permissions/schema'
@@ -884,6 +885,7 @@ export const configSchema = z
884
885
  portForward: portForwardSchema,
885
886
  network: networkSchema,
886
887
  sandbox: sandboxSchema,
888
+ eval: evalConfigSchema,
887
889
  docker: dockerSchema,
888
890
  browser: browserSchema,
889
891
  git: gitSchema,
@@ -899,6 +901,17 @@ export const configSchema = z
899
901
  // block is omitted entirely. Read fresh per session via `getConfig()`, so
900
902
  // it applies on reload without a restart.
901
903
  branding: z.boolean().default(true),
904
+ // Auto-compaction budget. `maxTriggerTokens` sets the agent's own ceiling
905
+ // on the compaction trigger, so each agent can trade per-turn re-read cost
906
+ // against working room for its workload; omitted, the 200K default in
907
+ // src/agent/compaction.ts applies. The 80% window-relative trigger still
908
+ // applies. The floor is 3x the 20K recent window that compaction keeps, so
909
+ // a compaction cannot immediately retrigger. Read per session, so a reload
910
+ // applies to sessions created afterwards.
911
+ compaction: z
912
+ .object({ maxTriggerTokens: z.number().int().min(60_000).optional() })
913
+ .strict()
914
+ .default({}),
902
915
  })
903
916
  .catchall(z.unknown())
904
917
 
@@ -1164,6 +1177,7 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
1164
1177
  portForward: 'restart-required',
1165
1178
  network: 'restart-required',
1166
1179
  sandbox: 'restart-required',
1180
+ eval: 'restart-required',
1167
1181
  tunnels: 'restart-required',
1168
1182
  'docker.file': 'restart-required', // Includes omoCli; installation changes rebuild the image.
1169
1183
  browser: 'restart-required',
@@ -1181,6 +1195,7 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
1181
1195
  'roles.match': 'applied',
1182
1196
  'roles.permissions': 'restart-required',
1183
1197
  branding: 'applied',
1198
+ compaction: 'applied',
1184
1199
  }
1185
1200
 
1186
1201
  // Stable JSON for value comparison. Fields are small JSON-shaped objects, so
@@ -121,8 +121,12 @@ export const KNOWN_PROVIDERS = {
121
121
  maxTokens: 128000,
122
122
  },
123
123
  // GPT-6 Sol and Luna use Responses because Chat Completions accepts tools
124
- // only at effort `none`. The full map and compat are pi-ai 0.87.1's
124
+ // only at effort `none`. The full map and compat are pi-ai 1.4.0's
125
125
  // catalog values, preserving every documented effort through `max`.
126
+ // With `supportsMidConvoEffort` (pi-ai 1.3.0), API-key requests keep a
127
+ // fixed reasoning.effort and carry the thinking level in
128
+ // configuration_update input items, so a mid-session level change keeps
129
+ // the prompt cache. Sign in with ChatGPT still sends reasoning.effort.
126
130
  'gpt-6-sol': {
127
131
  id: 'gpt-6-sol',
128
132
  name: 'GPT-6 Sol',
@@ -149,6 +153,7 @@ export const KNOWN_PROVIDERS = {
149
153
  supportsAdditionalTools: true,
150
154
  supportsToolSearch: true,
151
155
  supportsMidConvoSystemMessages: true,
156
+ supportsMidConvoEffort: true,
152
157
  supportsExplicitPromptCacheMode: true,
153
158
  },
154
159
  },
@@ -178,6 +183,7 @@ export const KNOWN_PROVIDERS = {
178
183
  supportsAdditionalTools: true,
179
184
  supportsToolSearch: true,
180
185
  supportsMidConvoSystemMessages: true,
186
+ supportsMidConvoEffort: true,
181
187
  supportsExplicitPromptCacheMode: true,
182
188
  },
183
189
  },
@@ -747,8 +753,8 @@ export const KNOWN_PROVIDERS = {
747
753
  apiKeyEnv: 'XAI_API_KEY',
748
754
  oauthProviderId: 'xai',
749
755
  models: {
750
- // pi-ai 0.87.1's xAI catalog caps Grok 4.3 at 30K and maps its efforts;
751
- // `minimal` is not an xAI effort, so it clamps to `low`. The current
756
+ // pi-ai 1.4.0's xAI catalog caps Grok 4.3 at 30K and maps its efforts,
757
+ // including `xhigh`; `minimal` is not an xAI effort, so it clamps to `low`. The current
752
758
  // transport sends model.maxTokens by default, so keep that vendor-safe cap.
753
759
  'grok-4.3': {
754
760
  id: 'grok-4.3',
@@ -767,7 +773,7 @@ export const KNOWN_PROVIDERS = {
767
773
  low: 'low',
768
774
  medium: 'medium',
769
775
  high: 'high',
770
- xhigh: null,
776
+ xhigh: 'xhigh',
771
777
  max: null,
772
778
  },
773
779
  compat: { supportsLongCacheRetention: false },
@@ -1,5 +1,5 @@
1
1
  import { randomBytes } from 'node:crypto'
2
- import { accessSync, constants as fsConstants, existsSync, realpathSync } from 'node:fs'
2
+ import { accessSync, constants as fsConstants, existsSync, realpathSync, statSync } from 'node:fs'
3
3
  import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
4
4
  import { homedir, tmpdir } from 'node:os'
5
5
  import { isAbsolute, join, posix, relative, resolve } from 'node:path'
@@ -127,6 +127,7 @@ export type StartPlan = {
127
127
  hostPort: number
128
128
  tuiToken: string | null
129
129
  memoryLimitBytes: number
130
+ mountWarnings: string[]
130
131
  }
131
132
 
132
133
  export type PlanStartOptions = {
@@ -660,6 +661,11 @@ async function runStart({
660
661
  totalMemoryBytes,
661
662
  })
662
663
 
664
+ for (const warning of plan.mountWarnings) {
665
+ if (onWarning !== undefined) onWarning(warning)
666
+ else if (streamOutput) process.stderr.write(`typeclaw: warning: ${warning}\n`)
667
+ }
668
+
663
669
  if (!skipMemoryOversubscriptionCheck) {
664
670
  await warnOnMemoryOversubscription({
665
671
  exec,
@@ -1222,8 +1228,14 @@ export async function planStart({
1222
1228
  runArgs.push(...dockerBindMount({ src: devSourcePath, dst: DEV_SOURCE_CONTAINER_PATH, readonly: true }))
1223
1229
  }
1224
1230
 
1231
+ const mountWarnings: string[] = []
1225
1232
  for (const mount of mounts) {
1226
1233
  const hostPath = expandMountPath(mount.path, cwd)
1234
+ const conflict = describeMountTargetConflict(cwd, mount.name, hostPath)
1235
+ if (conflict !== null) {
1236
+ mountWarnings.push(conflict)
1237
+ continue
1238
+ }
1227
1239
  const target = `${MOUNT_TARGET_PREFIX}/${mount.name}`
1228
1240
  runArgs.push(...dockerBindMount({ src: hostPath, dst: target, readonly: mount.readOnly }))
1229
1241
  }
@@ -1251,9 +1263,33 @@ export async function planStart({
1251
1263
  hostPort,
1252
1264
  tuiToken,
1253
1265
  memoryLimitBytes: memoryLimit.bytes,
1266
+ mountWarnings,
1254
1267
  }
1255
1268
  }
1256
1269
 
1270
+ // Docker leaves the bind target it created under the agent folder after the
1271
+ // container is gone, so a mount whose source switched between file and directory
1272
+ // collides with that leftover and fails the whole `docker run` ("not a
1273
+ // directory"). Skip just that mount so the agent still boots; deleting the
1274
+ // target is left to the operator because it lives in their agent folder.
1275
+ function describeMountTargetConflict(cwd: string, name: string, hostPath: string): string | null {
1276
+ const target = join(cwd, 'mounts', name)
1277
+ let targetIsDirectory: boolean
1278
+ let sourceIsDirectory: boolean
1279
+ try {
1280
+ targetIsDirectory = statSync(target).isDirectory()
1281
+ sourceIsDirectory = statSync(hostPath).isDirectory()
1282
+ } catch {
1283
+ return null
1284
+ }
1285
+ if (targetIsDirectory === sourceIsDirectory) return null
1286
+ const kind = (isDirectory: boolean): string => (isDirectory ? 'a directory' : 'a file')
1287
+ return (
1288
+ `mount "${name}" skipped: ${hostPath} is ${kind(sourceIsDirectory)} but its target ${target} is ` +
1289
+ `${kind(targetIsDirectory)}, so Docker cannot bind it. Remove ${target} and restart to restore the mount.`
1290
+ )
1291
+ }
1292
+
1257
1293
  // Surfaces the arithmetic when every agent's cap together exceeds what Docker
1258
1294
  // actually has. Never blocks: a fleet that has run fine at a nominal
1259
1295
  // oversubscription must not be bricked by an upgrade, and a refused start is a
@@ -34,30 +34,39 @@ import type { DoctorCheck } from './types'
34
34
  export function buildStaticChecks(opts: { dockerExec?: DockerExec } & FileOwnershipDeps = {}): DoctorCheck[] {
35
35
  const dockerExec = opts.dockerExec ?? defaultDockerExec
36
36
 
37
+ // hostOnly: the container sees neither Docker nor hostd, carries its own Bun,
38
+ // runs under a different uid namespace, cannot stat host mount sources, and
39
+ // masks secrets.json from model bash, so these checks would only report
40
+ // false failures there. The managed Dockerfile/.gitignore are rewritten by
41
+ // the host on every `typeclaw start`.
37
42
  return [
38
- dockerDaemon(boundedExec(dockerExec)),
39
- bunRuntime(),
43
+ hostOnly(dockerDaemon(boundedExec(dockerExec))),
44
+ hostOnly(bunRuntime()),
40
45
  agentFolderInitialized(),
41
- agentFolderDockerfileTemplate(),
42
- agentFolderGitignoreTemplate(),
46
+ hostOnly(agentFolderDockerfileTemplate()),
47
+ hostOnly(agentFolderGitignoreTemplate()),
43
48
  agentFolderNodeModules(),
44
49
  agentFolderGitRepo(),
45
- agentFileOwnership(opts),
46
- configValid(),
47
- apparmorSandbox(),
48
- hostdHomeWritable(),
49
- wslDriveMount(),
50
- windowsSecretPerms(),
51
- hostdReachable(),
52
- hostdRegistration(),
53
- windowsBindMount(),
54
- containerState(boundedExec(dockerExec)),
55
- containerHostPort(dockerExec),
50
+ hostOnly(agentFileOwnership(opts)),
51
+ hostOnly(configValid()),
52
+ hostOnly(apparmorSandbox()),
53
+ hostOnly(hostdHomeWritable()),
54
+ hostOnly(wslDriveMount()),
55
+ hostOnly(windowsSecretPerms()),
56
+ hostOnly(hostdReachable()),
57
+ hostOnly(hostdRegistration()),
58
+ hostOnly(windowsBindMount()),
59
+ hostOnly(containerState(boundedExec(dockerExec))),
60
+ hostOnly(containerHostPort(dockerExec)),
56
61
  ...buildOperationalIncidentChecks(),
57
- ...buildChannelChecks(),
62
+ ...buildChannelChecks().map(hostOnly),
58
63
  ]
59
64
  }
60
65
 
66
+ function hostOnly(check: DoctorCheck): DoctorCheck {
67
+ return { ...check, hostOnly: true }
68
+ }
69
+
61
70
  function dockerDaemon(exec: DockerExec): DoctorCheck {
62
71
  return {
63
72
  name: 'docker.daemon-reachable',
@@ -1,5 +1,6 @@
1
1
  import type { DockerExec } from '@/container'
2
2
  import { findAgentDir } from '@/init'
3
+ import { TYPECLAW_CLI_ENTRY } from '@/init/dockerfile'
3
4
  import type { DoctorCheckPayload } from '@/shared'
4
5
 
5
6
  import { buildStaticChecks } from './checks'
@@ -12,12 +13,14 @@ import {
12
13
  type PluginBridgeFetchFix,
13
14
  type PluginBridgeFixResult,
14
15
  } from './plugin-bridge'
16
+ import { detectDoctorStage } from './stage'
15
17
  import type {
16
18
  CheckContext,
17
19
  CheckResult,
18
20
  DoctorCheck,
19
21
  DoctorReport,
20
22
  DoctorRunResult,
23
+ DoctorStage,
21
24
  FixAttempt,
22
25
  ReportEntry,
23
26
  ReportSummary,
@@ -26,6 +29,7 @@ import type {
26
29
 
27
30
  export * from './types'
28
31
  export { buildStaticChecks } from './checks'
32
+ export { detectDoctorStage } from './stage'
29
33
  export { formatJson, formatReport } from './report'
30
34
  export { buildCommitMessage, commitAutoFixes } from './commit'
31
35
  export {
@@ -39,6 +43,7 @@ export type RunDoctorOptions = {
39
43
  cwd?: string
40
44
  only?: string[]
41
45
  fix?: boolean
46
+ stage?: DoctorStage
42
47
  // Docker executor used by BOTH the static checks and plugin discovery, so a
43
48
  // test can drive the whole command against one wedged daemon and prove the
44
49
  // real sequencing terminates — not just each half in isolation.
@@ -53,27 +58,32 @@ export async function runDoctor(opts: RunDoctorOptions = {}): Promise<DoctorRunR
53
58
  const cwd = opts.cwd ?? findAgentDir(process.cwd()) ?? process.cwd()
54
59
  const hasAgentFolder = findAgentDir(cwd) === cwd
55
60
  const ctx: CheckContext = { cwd, hasAgentFolder }
61
+ const stage = opts.stage ?? detectDoctorStage(cwd)
62
+ const inContainer = stage === 'container'
56
63
 
57
64
  const staticChecks = (
58
65
  opts.staticChecks ?? buildStaticChecks(opts.dockerExec === undefined ? {} : { dockerExec: opts.dockerExec })
59
- ).filter((c) => isAllowed(c, opts.only, c.category))
66
+ ).filter((c) => isAllowed(c, opts.only, c.category) && !(inContainer && c.hostOnly === true))
60
67
  const staticResults = await runStaticChecks(staticChecks, ctx)
61
68
 
62
69
  const fetchPluginChecks =
63
70
  opts.fetchPluginChecks ??
64
71
  ((bridgeOpts) =>
65
- defaultFetchPluginDoctorChecks(
66
- opts.dockerExec === undefined ? bridgeOpts : { ...bridgeOpts, exec: opts.dockerExec },
67
- ))
72
+ defaultFetchPluginDoctorChecks({
73
+ ...bridgeOpts,
74
+ inContainer,
75
+ ...(opts.dockerExec === undefined ? {} : { exec: opts.dockerExec }),
76
+ }))
68
77
  const pluginResults = await collectPluginChecks(fetchPluginChecks, ctx, opts.only)
69
78
 
70
- const initial = buildReport(ctx, staticResults, pluginResults)
79
+ const initial = buildReport(ctx, stage, staticResults, pluginResults)
71
80
 
72
81
  if (opts.fix !== true || initial.ok) {
73
82
  return { initial }
74
83
  }
75
84
 
76
- const fetchPluginFix = opts.fetchPluginFix ?? defaultFetchPluginDoctorFix
85
+ const fetchPluginFix =
86
+ opts.fetchPluginFix ?? ((bridgeOpts) => defaultFetchPluginDoctorFix({ ...bridgeOpts, inContainer }))
77
87
  const attempts: FixAttempt[] = []
78
88
  attempts.push(...(await runStaticFixes(staticResults, ctx)))
79
89
  attempts.push(...(await runPluginFixes(pluginResults.entries, fetchPluginFix, ctx)))
@@ -84,7 +94,7 @@ export async function runDoctor(opts: RunDoctorOptions = {}): Promise<DoctorRunR
84
94
 
85
95
  const finalStaticResults = await runStaticChecks(staticChecks, ctx)
86
96
  const finalPluginResults = await collectPluginChecks(fetchPluginChecks, ctx, opts.only)
87
- const final = buildReport(ctx, finalStaticResults, finalPluginResults)
97
+ const final = buildReport(ctx, stage, finalStaticResults, finalPluginResults)
88
98
 
89
99
  return { initial, fixAttempts: attempts, commit, final }
90
100
  }
@@ -133,8 +143,14 @@ async function collectPluginChecks(
133
143
  return { entries: filtered.map((payload) => ({ payload })), reachability }
134
144
  }
135
145
 
136
- function buildReport(ctx: CheckContext, staticResults: StaticResult[], plugin: PluginCollect): DoctorReport {
146
+ function buildReport(
147
+ ctx: CheckContext,
148
+ stage: DoctorStage,
149
+ staticResults: StaticResult[],
150
+ plugin: PluginCollect,
151
+ ): DoctorReport {
137
152
  const entries: ReportEntry[] = []
153
+ if (stage === 'container') entries.push(containerStageNote())
138
154
  for (const { check, result } of staticResults) {
139
155
  const entry: ReportEntry = {
140
156
  name: check.name,
@@ -152,7 +168,7 @@ function buildReport(ctx: CheckContext, staticResults: StaticResult[], plugin: P
152
168
  }
153
169
 
154
170
  if (ctx.hasAgentFolder && plugin.reachability.kind !== 'ok') {
155
- entries.push(reachabilityNote(plugin.reachability))
171
+ entries.push(reachabilityNote(plugin.reachability, stage))
156
172
  }
157
173
 
158
174
  for (const { payload } of plugin.entries) {
@@ -174,10 +190,25 @@ function buildReport(ctx: CheckContext, staticResults: StaticResult[], plugin: P
174
190
 
175
191
  const summary = summarize(entries)
176
192
  const ok = summary.error === 0 && summary.warning === 0
177
- return { cwd: ctx.cwd, hasAgentFolder: ctx.hasAgentFolder, entries, summary, ok }
193
+ return { cwd: ctx.cwd, stage, hasAgentFolder: ctx.hasAgentFolder, entries, summary, ok }
194
+ }
195
+
196
+ function containerStageNote(): ReportEntry {
197
+ return {
198
+ name: 'doctor.container-stage',
199
+ category: 'runtime',
200
+ description: 'doctor is running inside the agent container',
201
+ source: 'static',
202
+ status: 'info',
203
+ message: 'running inside the agent container; host-only checks were omitted',
204
+ details: [
205
+ 'Docker, hostd, Bun, config mounts, AppArmor, file ownership, managed templates, and channel credentials are checked only on the host.',
206
+ 'Run `typeclaw doctor` in the agent folder on the host for the full report.',
207
+ ],
208
+ }
178
209
  }
179
210
 
180
- function reachabilityNote(reach: PluginBridgeChecksResult): ReportEntry {
211
+ function reachabilityNote(reach: PluginBridgeChecksResult, stage: DoctorStage): ReportEntry {
181
212
  const message =
182
213
  reach.kind === 'unreachable'
183
214
  ? `plugin checks deferred: container not reachable (${reach.reason})`
@@ -191,7 +222,12 @@ function reachabilityNote(reach: PluginBridgeChecksResult): ReportEntry {
191
222
  source: 'static',
192
223
  status: 'info',
193
224
  message,
194
- details: ['Run `typeclaw start` then re-run `typeclaw doctor` to include plugin checks.'],
225
+ details:
226
+ stage === 'container'
227
+ ? [
228
+ `Sandboxed bash does not receive the agent websocket token. Run \`typeclaw doctor\` on the host, or \`docker exec <container> bun ${TYPECLAW_CLI_ENTRY} doctor\`, to include plugin checks.`,
229
+ ]
230
+ : ['Run `typeclaw start` then re-run `typeclaw doctor` to include plugin checks.'],
195
231
  }
196
232
  }
197
233
 
@@ -1,4 +1,6 @@
1
- import { readIncidentLedger } from '@/operations'
1
+ import { readFile } from 'node:fs/promises'
2
+
3
+ import { incidentsPath, readIncidentLedger } from '@/operations'
2
4
 
3
5
  import type { DoctorCheck } from './types'
4
6
 
@@ -10,6 +12,19 @@ export function buildOperationalIncidentChecks(): DoctorCheck[] {
10
12
  description: 'deterministic operational incidents are resolved',
11
13
  applies: (ctx) => ctx.hasAgentFolder,
12
14
  async run(ctx) {
15
+ // Sandboxed bash sees the runtime-private ledger as a 0-byte mask
16
+ // (src/sandbox/runtime-private.ts); the ledger itself is always written
17
+ // as JSON. readIncidentLedger would read that as "no incidents".
18
+ const raw = await readFile(incidentsPath(ctx.cwd), 'utf8').catch(() => null)
19
+ if (raw !== null && raw.trim() === '') {
20
+ return {
21
+ status: 'info',
22
+ message: 'operational incident check deferred: the incident ledger is not readable here',
23
+ details: [
24
+ 'Sandboxed bash masks .typeclaw/incidents.json. Run doctor on the host or via `docker exec` to check incidents.',
25
+ ],
26
+ }
27
+ }
13
28
  const ledger = await readIncidentLedger(ctx.cwd)
14
29
  const unresolved = ledger.incidents.filter((incident) => incident.status === 'unresolved')
15
30
  if (unresolved.length === 0) return { status: 'ok', message: 'no unresolved operational incidents' }
@@ -1,4 +1,4 @@
1
- import { resolveHostPort, resolveTuiToken, type DockerExec } from '@/container'
1
+ import { CONTAINER_PORT, resolveHostPort, resolveTuiToken, type DockerExec } from '@/container'
2
2
  import type { ClientMessage, DoctorCheckPayload, DoctorFixPayload, ServerMessage } from '@/shared'
3
3
 
4
4
  import { boundedExec } from './bounded-exec'
@@ -10,6 +10,8 @@ export type PluginBridgeOptions = {
10
10
  // Injectable so a regression test can prove the late discovery path is
11
11
  // bounded too, not just the static checks.
12
12
  exec?: DockerExec
13
+ // Inside the container there is no `docker`; dial the agent's own loopback.
14
+ inContainer?: boolean
13
15
  }
14
16
 
15
17
  export type PluginBridgeFetchChecks = (opts: PluginBridgeOptions) => Promise<PluginBridgeChecksResult>
@@ -82,6 +84,9 @@ type DialResult = { kind: 'ok'; ws: WebSocket; timeoutMs: number } | { kind: 'un
82
84
  async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
83
85
  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
84
86
  let url = opts.url
87
+ if (url === undefined && opts.inContainer === true) {
88
+ url = resolveInContainerBridgeUrl(process.env)
89
+ }
85
90
  if (url === undefined) {
86
91
  try {
87
92
  // Plugin discovery runs AFTER the static checks, so it is the last place
@@ -148,6 +153,14 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
148
153
  return { kind: 'ok', ws, timeoutMs }
149
154
  }
150
155
 
156
+ // Sandboxed model bash never receives TYPECLAW_TUI_TOKEN (src/sandbox/env-exposure.ts),
157
+ // so there a token-protected server rejects the dial and plugin checks are
158
+ // reported as deferred. `docker exec` keeps the container env and authenticates.
159
+ export function resolveInContainerBridgeUrl(env: NodeJS.ProcessEnv): string {
160
+ const token = env.TYPECLAW_TUI_TOKEN
161
+ return buildBridgeUrl(CONTAINER_PORT, token !== undefined && token !== '' ? token : null)
162
+ }
163
+
151
164
  function buildBridgeUrl(port: number, token: string | null): string {
152
165
  const url = new URL(`ws://127.0.0.1:${port}`)
153
166
  if (token !== null) url.searchParams.set('token', token)
@@ -0,0 +1,14 @@
1
+ import type { DoctorStage } from './types'
2
+
3
+ const CONTAINER_AGENT_DIR = '/agent'
4
+
5
+ // `docker run` sets TYPECLAW_CONTAINER_NAME, so a `docker exec` doctor run
6
+ // sees it. Model bash does not: the bwrap sandbox clears the container
7
+ // env (src/sandbox/policy.ts DEFAULT_SANDBOX_ENV) and hides /.dockerenv. Its
8
+ // cwd still resolves to the agent folder at its container mount point, so the
9
+ // /agent agent folder is the marker that survives the sandbox.
10
+ export function detectDoctorStage(agentDir: string, env: NodeJS.ProcessEnv = process.env): DoctorStage {
11
+ if (env.TYPECLAW_CONTAINER_NAME !== undefined) return 'container'
12
+ if (agentDir === CONTAINER_AGENT_DIR) return 'container'
13
+ return 'host'
14
+ }
@@ -34,10 +34,15 @@ export type CheckContext = {
34
34
  hasAgentFolder: boolean
35
35
  }
36
36
 
37
+ export type DoctorStage = 'host' | 'container'
38
+
37
39
  export type DoctorCheck = {
38
40
  name: string
39
41
  category: DoctorCategory
40
42
  description: string
43
+ // Probes host-only state (Docker, hostd, host kernel, host paths, host-side
44
+ // secrets). Omitted when doctor runs inside the agent container.
45
+ hostOnly?: boolean
41
46
  applies?: (ctx: CheckContext) => boolean
42
47
  run: (ctx: CheckContext) => Promise<CheckResult>
43
48
  }
@@ -64,6 +69,7 @@ export type ReportSummary = {
64
69
 
65
70
  export type DoctorReport = {
66
71
  cwd: string
72
+ stage: DoctorStage
67
73
  hasAgentFolder: boolean
68
74
  entries: ReportEntry[]
69
75
  summary: ReportSummary
@@ -0,0 +1,93 @@
1
+ import { randomUUID } from 'node:crypto'
2
+
3
+ import { CellOutput, EVAL_LIMITS, EvalError, type HostFrame, type KernelFrame } from './protocol'
4
+ import { assertNever } from './wire'
5
+
6
+ export type EvalDispatch = (
7
+ request: {
8
+ readonly name: string
9
+ readonly args: Extract<KernelFrame, { type: 'tool-call' }>['args']
10
+ readonly callId: string
11
+ },
12
+ signal: AbortSignal,
13
+ ) => Promise<unknown>
14
+
15
+ export class EvalCell {
16
+ readonly id = randomUUID()
17
+ readonly output = new CellOutput()
18
+ readonly completed = Promise.withResolvers<void>()
19
+ private readonly ids = new Set<string>()
20
+ private readonly pending = new Set<Promise<void>>()
21
+ private finished = false
22
+
23
+ constructor(
24
+ private readonly dispatch: EvalDispatch,
25
+ private readonly signal: AbortSignal,
26
+ ) {}
27
+
28
+ receive(frame: KernelFrame, send: (frame: HostFrame) => void): void {
29
+ switch (frame.type) {
30
+ case 'ready':
31
+ throw new EvalError('protocol', 'unexpected ready frame')
32
+ case 'output':
33
+ this.assertActive(frame.cellId)
34
+ this.output.append(frame.text)
35
+ return
36
+ case 'done':
37
+ this.assertActive(frame.cellId)
38
+ this.finished = true
39
+ void Promise.all(this.pending).then(() => {
40
+ if (frame.error === undefined) this.completed.resolve()
41
+ else this.completed.reject(new EvalError('cell', frame.error))
42
+ }, this.completed.reject)
43
+ return
44
+ case 'tool-call': {
45
+ this.assertActive(frame.cellId)
46
+ if (
47
+ this.ids.has(frame.id) ||
48
+ this.ids.size >= EVAL_LIMITS.calls ||
49
+ this.pending.size >= EVAL_LIMITS.concurrency
50
+ ) {
51
+ throw new EvalError('protocol', 'eval tool-call id, count, or concurrency limit exceeded')
52
+ }
53
+ this.ids.add(frame.id)
54
+ const task = this.invoke(frame, send)
55
+ this.pending.add(task)
56
+ void task.then(() => this.pending.delete(task), this.completed.reject)
57
+ return
58
+ }
59
+ default:
60
+ assertNever(frame)
61
+ }
62
+ }
63
+
64
+ private assertActive(cellId: string): void {
65
+ if (this.finished || this.signal.aborted || cellId !== this.id) {
66
+ throw new EvalError('protocol', 'eval frame is outside its active cell')
67
+ }
68
+ }
69
+
70
+ private async invoke(
71
+ frame: Extract<KernelFrame, { type: 'tool-call' }>,
72
+ send: (frame: HostFrame) => void,
73
+ ): Promise<void> {
74
+ try {
75
+ const value = await this.dispatch(
76
+ {
77
+ name: frame.name,
78
+ args: frame.args,
79
+ callId: `eval:${this.id}:${frame.id}`,
80
+ },
81
+ this.signal,
82
+ )
83
+ if (!this.signal.aborted) send({ type: 'tool-result', id: frame.id, value })
84
+ } catch (error) {
85
+ if (!this.signal.aborted)
86
+ send({
87
+ type: 'tool-error',
88
+ id: frame.id,
89
+ error: (error instanceof Error ? error.message : String(error)).slice(0, 4096),
90
+ })
91
+ }
92
+ }
93
+ }
@@ -0,0 +1,32 @@
1
+ import { z } from 'zod'
2
+
3
+ import type { WrapSystemToolOptions } from '@/agent/plugin-tools'
4
+ import type { SessionOrigin } from '@/agent/session-origin'
5
+
6
+ const origins = ['tui', 'channel', 'cron', 'subagent', 'system'] as const
7
+
8
+ export const evalConfigSchema = z
9
+ .object({
10
+ enabled: z.boolean().default(false),
11
+ origins: z.array(z.enum(origins)).default([...origins]),
12
+ })
13
+ .strict()
14
+ .default({ enabled: false, origins: [...origins] })
15
+
16
+ export function evalEnabledForSession(options: {
17
+ readonly settings: z.infer<typeof evalConfigSchema>
18
+ readonly origin: SessionOrigin | undefined
19
+ readonly tools: readonly string[]
20
+ readonly bashPolicy?: WrapSystemToolOptions['bashPolicy']
21
+ }): boolean {
22
+ // Raw JavaScript is arbitrary code, just like unrestricted bash. The command
23
+ // fence is NOT a filesystem policy and cannot be enforced on JavaScript.
24
+ // Use the wrapper's actual policy source, never a list of subagent names.
25
+ return (
26
+ options.settings.enabled &&
27
+ options.origin !== undefined &&
28
+ options.settings.origins.includes(options.origin.kind) &&
29
+ options.tools.includes('bash') &&
30
+ options.bashPolicy === undefined
31
+ )
32
+ }