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
@@ -1,6 +1,6 @@
1
1
  import { AsyncLocalStorage } from 'node:async_hooks'
2
2
  import { mkdir } from 'node:fs/promises'
3
- import { join, relative, sep } from 'node:path'
3
+ import { relative, sep } from 'node:path'
4
4
 
5
5
  import {
6
6
  createBashToolDefinition as piCreateBashToolDefinition,
@@ -19,10 +19,8 @@ import { Type } from 'typebox'
19
19
  import { z } from 'zod'
20
20
 
21
21
  import { ACKNOWLEDGE_GUARDS } from '@/bundled-plugins/guard/keys'
22
- import { config, getSandboxWritablePathSpecs } from '@/config/config'
23
22
  import { readOomEvents, toolOomNote } from '@/container/oom-events'
24
23
  import { withToolOomPriorityCommand } from '@/container/tool-oom-priority'
25
- import { readEnvFile } from '@/init/env-file'
26
24
  import {
27
25
  classifyToolOutcome,
28
26
  deriveMechanicallyVerifiedIncidentFingerprints,
@@ -47,39 +45,28 @@ import type {
47
45
  } from '@/plugin'
48
46
  import { PI_BUILTIN_TOOL_NAMES, type PiBuiltinToolName } from '@/plugin/core-tool-names'
49
47
  import {
50
- buildSandboxedCommand,
51
- canWriteAgentRootInSandbox,
52
- canMountRealProc,
53
- cleanupPrivilegedSandboxRuntime,
54
48
  commandNeedsRealProc,
55
- DEFAULT_SANDBOX_ENV,
56
- DEPENDENCY_BIN_SANDBOX_DIR,
57
49
  dependencyBinUnavailableHint,
58
- ensureBwrapAvailable,
59
- ensureHiddenMaskTargets,
60
50
  ensureSessionTmpDir,
61
- getProcBindSafetyVerdict,
62
51
  isGitControlPath,
63
52
  mapVirtualTmpPath,
64
- reconcileDependencyBinWrappers,
65
53
  resolveHiddenPaths,
66
- resolvePrivilegedSandboxRuntime,
67
- resolveProcBindSafetyWithRetry,
68
- resolveProcSelfExe,
69
- resolveProtectedZones,
70
- resolveSandboxSymlinks,
71
- resolveWritableZones,
72
54
  SandboxPolicyError,
73
- SandboxDegradedProcError,
74
- SandboxProcProbeUnverifiedError,
75
- type SandboxMount,
76
- type DependencyBinReconciliation,
77
- subtractMasked,
78
- verifyHiddenMaskTargets,
79
- verifyPrivilegedSandboxRuntime,
80
55
  } from '@/sandbox'
81
- import { resolveDevSourceMount } from '@/sandbox/dev-source'
82
- import { resolveExposableEnvNames } from '@/sandbox/env-exposure'
56
+
57
+ import {
58
+ prepareBashSandbox,
59
+ type BashSandboxBoundary,
60
+ type DeferredBashPreparation,
61
+ type PreparedBashSandbox,
62
+ } from './bash-sandbox'
63
+ export {
64
+ buildBashFilesystemPolicy,
65
+ type BashSandboxBoundary,
66
+ type DeferredBashPreparation,
67
+ type DeferredBashPreparationResult,
68
+ } from './bash-sandbox'
69
+ export { buildSandboxEnvPolicy } from './bash-sandbox-env'
83
70
 
84
71
  import type { InternalGuard } from './guard-types'
85
72
  import { createLoopGuard, type LoopGuard, type LoopGuardDecision } from './loop-guard'
@@ -113,25 +100,8 @@ export const TYPECLAW_INTERNAL_BASH_PREPARE = '__typeclawBashPrepare'
113
100
 
114
101
  type BashEnvOverlay = Record<string, string>
115
102
  type BashEnvWithhold = string[]
116
- export type DeferredBashPreparationResult = {
117
- command: string
118
- env?: Record<string, string>
119
- mount: Extract<SandboxMount, { type: 'ro-bind' }>
120
- cleanup: () => Promise<void>
121
- }
122
- export type DeferredBashPreparation = () => Promise<DeferredBashPreparationResult>
123
103
  const SECRET_BASH_ENV_NAMES = new Set(['GH_TOKEN', 'GITHUB_TOKEN'])
124
104
 
125
- // Transport classifier for the TRUSTED hook-injected overlay only (e.g.
126
- // github-cli-auth's per-repo GH_TOKEN). Token/secret-shaped names use `inherit`
127
- // so their value never renders into the bwrap argv; plain names (GH_REPO) go
128
- // via `set`. This is NOT a .env exposure filter — the overlay is populated by
129
- // trusted runtime hooks, not operator .env.
130
- const OVERLAY_SECRET_NAME_PATTERN = /(?:^|_)(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|AUTH)$/i
131
- function isOverlaySecretName(name: string): boolean {
132
- return SECRET_BASH_ENV_NAMES.has(name) || OVERLAY_SECRET_NAME_PATTERN.test(name)
133
- }
134
-
135
105
  type BashSpawnEnvContext = {
136
106
  overlay?: BashEnvOverlay
137
107
  withhold?: BashEnvWithhold
@@ -309,20 +279,6 @@ export type WrapToolOptions = {
309
279
  getLoopGuardTurn?: () => number | undefined
310
280
  }
311
281
 
312
- export type BashSandboxBoundary = {
313
- ensureAvailable: () => Promise<void>
314
- buildCommand: typeof buildSandboxedCommand
315
- resolveProcStrategy?: () => Promise<ProcStrategyResolution>
316
- resolveRuntime?: typeof resolvePrivilegedSandboxRuntime
317
- verifyRuntime?: typeof verifyPrivilegedSandboxRuntime
318
- cleanupRuntime?: typeof cleanupPrivilegedSandboxRuntime
319
- }
320
-
321
- const DEFAULT_BASH_SANDBOX_BOUNDARY: BashSandboxBoundary = {
322
- ensureAvailable: ensureBwrapAvailable,
323
- buildCommand: buildSandboxedCommand,
324
- }
325
-
326
282
  export type WrapSystemToolOptions = {
327
283
  agentDir: string
328
284
  sessionId: string
@@ -658,7 +614,7 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
658
614
  let executionError: unknown
659
615
  let cleanupError: unknown
660
616
  let sandboxedRealProcSucceeded = false
661
- const sandboxBoundary = opts.bashSandboxBoundary ?? DEFAULT_BASH_SANDBOX_BOUNDARY
617
+ const sandboxBoundary = opts.bashSandboxBoundary
662
618
  const incidentLedger = opts.incidentLedger ?? new IncidentLedger(opts.agentDir)
663
619
  const originalArgs = { ...mutableArgs }
664
620
  const executeAttempt = async (): Promise<void> => {
@@ -678,17 +634,19 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
678
634
  'model-driven bash has no permission service; refusing unsandboxed execution',
679
635
  )
680
636
  }
681
- preparedSandboxRuntime = await applyBashSandbox(
682
- attemptArgs,
683
- opts.permissions,
684
- liveOrigin,
685
- opts.agentDir,
686
- opts.sessionId,
687
- bashEnvOverlay,
688
- bashEnvWithhold,
689
- bashPreparation,
690
- sandboxBoundary,
691
- )
637
+ if (typeof attemptArgs.command !== 'string') throw new SandboxPolicyError('bash command must be a string')
638
+ preparedSandboxRuntime = await prepareBashSandbox({
639
+ command: attemptArgs.command,
640
+ permissions: opts.permissions,
641
+ origin: liveOrigin,
642
+ agentDir: opts.agentDir,
643
+ sessionId: opts.sessionId,
644
+ envOverlay: bashEnvOverlay,
645
+ envWithhold: bashEnvWithhold,
646
+ deferredPreparation: bashPreparation,
647
+ boundary: sandboxBoundary,
648
+ })
649
+ attemptArgs.command = preparedSandboxRuntime.commandString
692
650
  }
693
651
 
694
652
  tmpRedirect =
@@ -902,156 +860,6 @@ export function buildBuiltinPiToolOverrides(opts: WrapSystemToolOptions): ToolDe
902
860
  return defaultBuiltinPiToolDefinitions(opts.agentDir).map((tool) => wrapBuiltinToolDefinition(tool, opts))
903
861
  }
904
862
 
905
- type BashFilesystemPolicyOptions = {
906
- agentDir: string
907
- canWriteAgentRoot: boolean
908
- masks: { dirs: string[]; files: string[] }
909
- writable: { dirs: string[]; files: string[] }
910
- protected: { dirs: string[]; files: string[] }
911
- }
912
-
913
- type PreparedBashSandbox = {
914
- verify: () => Promise<void>
915
- cleanup: () => Promise<void>
916
- spawnEnv?: Record<string, string>
917
- dependencyBins?: DependencyBinReconciliation
918
- withheld: {
919
- paths: { dirs: string[]; files: string[] }
920
- envNames: string[]
921
- }
922
- }
923
-
924
- export function buildBashFilesystemPolicy(options: BashFilesystemPolicyOptions) {
925
- const { agentDir, canWriteAgentRoot, masks, writable, protected: protectedZones } = options
926
- if (canWriteAgentRoot) {
927
- return { writableRoot: { dir: agentDir }, masks, protected: protectedZones }
928
- }
929
- return { masks, writable, protected: protectedZones }
930
- }
931
-
932
- // Rewrites mutableArgs.command in place so the bash builtin runs inside bwrap
933
- // with role-derived private-directory masks and unconditional canonical-secret
934
- // file masks. When masks are needed but bwrap is unavailable
935
- // we throw rather than run unsandboxed — fail closed, never leak the masked
936
- // surface. Runs after the tool.before guards have inspected the raw command.
937
- async function applyBashSandbox(
938
- mutableArgs: Record<string, unknown>,
939
- permissions: PermissionService,
940
- origin: SessionOrigin | undefined,
941
- agentDir: string,
942
- sessionId: string,
943
- envOverlay: BashEnvOverlay | undefined,
944
- envWithhold: BashEnvWithhold | undefined,
945
- deferredPreparation: DeferredBashPreparation | undefined,
946
- boundary: BashSandboxBoundary,
947
- ): Promise<PreparedBashSandbox> {
948
- const originalCommand = mutableArgs.command
949
- if (typeof originalCommand !== 'string') {
950
- return {
951
- verify: async () => {},
952
- cleanup: async () => {},
953
- withheld: { paths: { dirs: [], files: [] }, envNames: [] },
954
- }
955
- }
956
-
957
- let preparation: DeferredBashPreparationResult | undefined
958
- let privilegedRuntime: Awaited<ReturnType<typeof resolvePrivilegedSandboxRuntime>> | undefined
959
- const cleanup = async (): Promise<void> => {
960
- const tasks: Promise<void>[] = []
961
- if (privilegedRuntime !== undefined) {
962
- tasks.push((boundary.cleanupRuntime ?? cleanupPrivilegedSandboxRuntime)(privilegedRuntime))
963
- }
964
- if (preparation !== undefined) tasks.push(preparation.cleanup())
965
- const outcomes = await Promise.allSettled(tasks)
966
- const failure = outcomes.find((outcome) => outcome.status === 'rejected')
967
- if (failure?.status === 'rejected') throw failure.reason
968
- }
969
- try {
970
- preparation = await deferredPreparation?.()
971
- const command = preparation?.command ?? originalCommand
972
- const preparedEnvOverlay = preparation?.env === undefined ? envOverlay : { ...envOverlay, ...preparation.env }
973
- const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
974
- const envNames = resolveExposableBashEnvNames(agentDir)
975
- const sandboxEnvOverlay = buildRoleScopedConfigEnv(agentDir, dirs, preparedEnvOverlay)
976
- const effectiveEnvWithhold = (envWithhold ?? []).filter((name) => !Object.hasOwn(sandboxEnvOverlay ?? {}, name))
977
- const maskTargets = await ensureHiddenMaskTargets({ dirs, files })
978
- await boundary.ensureAvailable()
979
- const sessionTmp = await ensureSessionTmpDir(sessionId)
980
- const dependencyBins = await reconcileDependencyBinWrappers({ agentDir, sessionTmp })
981
- const writable = subtractMasked(await resolveWritableZones(agentDir, getSandboxWritablePathSpecs(config)), {
982
- dirs,
983
- files,
984
- })
985
- const writableRoot = canWriteAgentRootInSandbox(permissions, origin)
986
- const baseProtectedZones =
987
- writableRoot || writable.dirs.includes(join(agentDir, '.git'))
988
- ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
989
- : { dirs: [], files: [] }
990
- const protectedZones = {
991
- dirs: baseProtectedZones.dirs,
992
- files: [...new Set([...baseProtectedZones.files, ...dependencyBins.protectedFiles])],
993
- }
994
- const writableDirSet = new Set(writable.dirs)
995
- const sandboxHome = DEFAULT_SANDBOX_ENV.HOME ?? '/tmp'
996
- const symlinks = resolveSandboxSymlinks(agentDir, config.sandbox.symlinks, sandboxHome).filter((op) =>
997
- writableDirSet.has(op.target),
998
- )
999
- const { strategy: proc, degradeReason } = await (boundary.resolveProcStrategy ?? resolveProcStrategy)()
1000
- if (proc === 'tmpfs' && commandNeedsRealProc(command)) {
1001
- throw degradeReason === 'unverified' ? new SandboxProcProbeUnverifiedError() : new SandboxDegradedProcError()
1002
- }
1003
- privilegedRuntime = await (boundary.resolveRuntime ?? resolvePrivilegedSandboxRuntime)({
1004
- agentDir,
1005
- command,
1006
- env: sandboxEnvOverlay,
1007
- })
1008
- await verifyHiddenMaskTargets(maskTargets)
1009
- const devSourceMount = await resolveDevSourceMount(agentDir)
1010
- const { commandString, spawnEnv } = boundary.buildCommand(command, {
1011
- mounts: [
1012
- { type: 'ro-bind', source: agentDir, dest: agentDir },
1013
- { type: 'bind', source: sessionTmp, dest: '/tmp' },
1014
- // `/tmp` is writable, but PATH entries must remain runtime-owned for
1015
- // the lifetime of this command. Last-op-wins makes this narrow re-bind
1016
- // read-only without adding any broader filesystem exposure.
1017
- { type: 'ro-bind', source: dependencyBins.wrapperDir, dest: DEPENDENCY_BIN_SANDBOX_DIR },
1018
- ...(devSourceMount === undefined ? [] : [devSourceMount]),
1019
- ...(privilegedRuntime?.mounts ?? []),
1020
- ...(preparation === undefined ? [] : [preparation.mount]),
1021
- ],
1022
- ...(writableRoot
1023
- ? { writableRoot: { dir: agentDir }, masks: maskTargets, protected: protectedZones }
1024
- : { masks: maskTargets, writable, protected: protectedZones }),
1025
- symlinks,
1026
- network: 'inherit',
1027
- cwd: agentDir,
1028
- proc,
1029
- procSelfExe: resolveProcSelfExe(),
1030
- ...spreadSandboxEnv(
1031
- buildSandboxEnvPolicy(sandboxEnvOverlay, privilegedRuntime?.env, envNames.exposable, envWithhold),
1032
- ),
1033
- })
1034
- mutableArgs.command = commandString
1035
- // The overlay carries command-scoped secret VALUES (e.g. a per-repo GH_TOKEN)
1036
- // that live in neither process.env nor argv; resolveSpawnEnv snapshots
1037
- // inherited names from process.env only, so merge the overlay values in here
1038
- // to complete the exact bwrap-parent env.
1039
- const mergedSpawnEnv =
1040
- spawnEnv !== undefined && sandboxEnvOverlay !== undefined ? { ...spawnEnv, ...sandboxEnvOverlay } : spawnEnv
1041
- const runtimeForResult = privilegedRuntime
1042
- return {
1043
- verify: async () => (boundary.verifyRuntime ?? verifyPrivilegedSandboxRuntime)(runtimeForResult),
1044
- cleanup,
1045
- spawnEnv: mergedSpawnEnv,
1046
- dependencyBins,
1047
- withheld: { paths: maskTargets, envNames: [...new Set([...envNames.withheld, ...effectiveEnvWithhold])] },
1048
- }
1049
- } catch (error) {
1050
- await cleanup()
1051
- throw error
1052
- }
1053
- }
1054
-
1055
863
  function bashResultIsCommandNotFound(result: ToolResult): boolean {
1056
864
  if (isRecord(result.details) && result.details.exitCode === 127) return true
1057
865
  return (result.content as ContentPart[]).some(
@@ -1089,164 +897,6 @@ function appendTextResult(result: ToolResult, text: string): ToolResult {
1089
897
  return { ...result, content: [...(result.content as ContentPart[]), { type: 'text', text }] }
1090
898
  }
1091
899
 
1092
- export function buildSandboxEnvPolicy(
1093
- overlay: BashEnvOverlay | undefined,
1094
- runtimeEnv: Record<string, string> | undefined,
1095
- exposableEnvNames: readonly string[] = [],
1096
- withhold: readonly string[] = [],
1097
- ): { inherit?: string[]; set?: Record<string, string>; withhold?: string[] } {
1098
- const requestedWithhold = new Set(withhold)
1099
- const overlayNames = new Set(Object.keys(overlay ?? {}))
1100
- // The overlay is a deliberate command-scoped replacement, while withholding
1101
- // only removes ambient values; an overlay therefore wins for the same name.
1102
- const effectiveWithhold = [...requestedWithhold].filter((name) => !overlayNames.has(name))
1103
- const effectiveWithholdSet = new Set(effectiveWithhold)
1104
- const set = Object.fromEntries(Object.entries(runtimeEnv ?? {}).filter(([key]) => !requestedWithhold.has(key)))
1105
- const inherit: string[] = []
1106
- const inheritSeen = new Set<string>()
1107
- const pushInherit = (key: string): void => {
1108
- if (effectiveWithholdSet.has(key) || Object.hasOwn(set, key) || inheritSeen.has(key)) return
1109
- inheritSeen.add(key)
1110
- inherit.push(key)
1111
- }
1112
- for (const [key, value] of Object.entries(overlay ?? {})) {
1113
- if (Object.hasOwn(set, key)) continue
1114
- if (isOverlaySecretName(key)) pushInherit(key)
1115
- else set[key] = value
1116
- }
1117
- // Operator-declared .env vars pass through by NAME (inherit), keeping values
1118
- // out of the rendered bwrap argv. Sandbox-integrity names were already dropped
1119
- // in resolveExposableEnvNames — these are the survivors.
1120
- for (const key of exposableEnvNames) pushInherit(key)
1121
- // Pass the entrypoint-exported Xvfb display (start_xvfb: `export DISPLAY=:99`)
1122
- // through --clearenv, else sandboxed `agent-browser --headed` dies with
1123
- // "Missing X server or $DISPLAY". Passing the runtime's OWN value (not a fixed
1124
- // ":99") keeps `docker.file.xvfb=false` advertising no display. Rendered via
1125
- // `set` (a display number is neither a credential nor shell-injectable), and no
1126
- // /tmp/.X11-unix bind is needed: Chrome reaches Xvfb over the netns-scoped
1127
- // abstract X11 socket while bash keeps network:'inherit'.
1128
- const display = process.env['DISPLAY']
1129
- if (
1130
- display !== undefined &&
1131
- display !== '' &&
1132
- !effectiveWithholdSet.has('DISPLAY') &&
1133
- !Object.hasOwn(set, 'DISPLAY') &&
1134
- !inheritSeen.has('DISPLAY')
1135
- ) {
1136
- set['DISPLAY'] = display
1137
- }
1138
- return {
1139
- ...(inherit.length > 0 ? { inherit } : {}),
1140
- ...(Object.keys(set).length > 0 ? { set } : {}),
1141
- ...(effectiveWithhold.length > 0 ? { withhold: effectiveWithhold } : {}),
1142
- }
1143
- }
1144
-
1145
- function spreadSandboxEnv(policy: ReturnType<typeof buildSandboxEnvPolicy>): {
1146
- env?: ReturnType<typeof buildSandboxEnvPolicy>
1147
- } {
1148
- return Object.keys(policy).length > 0 ? { env: policy } : {}
1149
- }
1150
-
1151
- function resolveExposableBashEnvNames(agentDir: string): { exposable: string[]; withheld: string[] } {
1152
- const declaredEnv = readEnvFile(agentDir)
1153
- const exposable = resolveExposableEnvNames(declaredEnv, process.env)
1154
- const exposableSet = new Set(exposable)
1155
- const withheld = [...declaredEnv]
1156
- .filter(([name, value]) => value.length > 0 && !exposableSet.has(name))
1157
- .map(([name]) => name)
1158
- return { exposable, withheld }
1159
- }
1160
-
1161
- function buildRoleScopedConfigEnv(
1162
- agentDir: string,
1163
- hiddenDirs: string[],
1164
- envOverlay: BashEnvOverlay | undefined,
1165
- ): BashEnvOverlay | undefined {
1166
- // Low-trust roles have workspace/ masked. Do not let container-global config
1167
- // env vars point CLIs back at that private surface: apps that honor XDG should
1168
- // still run, but their config must land in the sandbox's per-session /tmp.
1169
- // Trusted/owner have only the unconditional credential-dir masks, not the
1170
- // workspace root mask, so their command broker decides whether to set GWS.
1171
- const workspaceHidden = hiddenDirs.includes(join(agentDir, 'workspace'))
1172
- if (!workspaceHidden) return envOverlay
1173
-
1174
- return {
1175
- ...envOverlay,
1176
- XDG_CONFIG_HOME: '/tmp/.config',
1177
- GWS_CONFIG_HOME: '/tmp/.config/gws',
1178
- }
1179
- }
1180
-
1181
- // Picks the /proc strategy for a sandboxed bash call. The branch order is:
1182
- // 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
1183
- // the kernel permits the mount (canMountRealProc) — it adds PID isolation but
1184
- // needs CAP_SYS_ADMIN (unshare --mount-proc), so it is a deliberate, narrow
1185
- // opt-in; else 'proc-bind' (--ro-bind /proc, NO CAP_SYS_ADMIN) when its userns
1186
- // leak-block is verified safe; else 'tmpfs'. Because sandbox.realProc DEFAULTS
1187
- // FALSE, the first branch is normally skipped and proc-bind is the de-facto
1188
- // default — which is the point: the common path needs no broad outer capability.
1189
- // 'tmpfs' is the last-resort degraded mode where external packages can't run;
1190
- // reached only when proc-bind is DEFINITIVELY unavailable (a real cross-userns
1191
- // environ leak → fail closed) or its safety stays unverifiable after retries.
1192
- //
1193
- // Read from the boot-time `config` snapshot, NOT live getConfig(): sandbox is
1194
- // restart-required, and the strategy MUST track the boot-time CAP_SYS_ADMIN
1195
- // grant. A `typeclaw reload` flipping realProc would otherwise emit `unshare
1196
- // --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
1197
- // probes are cached process-globally, so this resolves to one spawn per
1198
- // container lifetime regardless of how many bash calls hit it.
1199
- // A tmpfs degrade carries WHY it happened so the caller can pick a permanent vs
1200
- // retryable error. 'definitive': the probe returned a real cross-userns leak
1201
- // ('unsafe') — the ONLY verdict proven permanent, so it fails closed for good.
1202
- // 'unverified': the safety probe never reached a definitive verdict within its
1203
- // retry budget. That covers BOTH a transient load spike AND a durable
1204
- // incapability (no usable namespaces, a bwrap that starts but cannot set up its
1205
- // sandbox): the probe cannot prove a NEGATIVE capability — only a leak is
1206
- // definitive — so a genuinely incapable host also lands here and simply keeps
1207
- // re-degrading on each call. Since 'inconclusive' is never cached, that costs a
1208
- // re-probe but is correct: the only false case is "capable but briefly
1209
- // saturated", which recovers; an incapable host stays degraded either way.
1210
- // Absent when the strategy is not tmpfs.
1211
- type ProcStrategyResolution =
1212
- | { strategy: 'real-proc' | 'proc-bind'; degradeReason?: undefined }
1213
- | { strategy: 'tmpfs'; degradeReason: 'definitive' | 'unverified' }
1214
-
1215
- async function resolveProcStrategy(): Promise<ProcStrategyResolution> {
1216
- if (config.sandbox.realProc && (await canMountRealProc())) return { strategy: 'real-proc' }
1217
- // Retry an 'inconclusive' proc-bind probe (transient under load) before
1218
- // degrading — a single such hiccup must not break external-package runs on a
1219
- // capable host. 'unsafe' still fails closed with no retry.
1220
- const verdict = await resolveProcBindSafetyWithRetry(
1221
- () => getProcBindSafetyVerdict(),
1222
- (ms) => Bun.sleep(ms),
1223
- )
1224
- if (verdict === 'safe') return { strategy: 'proc-bind' }
1225
- // Degraded last resort: no working /proc strategy. External package runners
1226
- // (bunx/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
1227
- // /proc/self/{fd,maps} are absent. Only a proven 'unsafe' (a real cross-userns
1228
- // leak) is DEFINITIVE — warn once (a real operator-facing limit). An
1229
- // 'inconclusive' is reported as retryable upstream and NOT warned (it would cry
1230
- // wolf every boot storm); a durably-incapable host re-degrades quietly here,
1231
- // since the probe cannot distinguish it from transient load.
1232
- if (verdict === 'unsafe') {
1233
- warnTmpfsProcFallbackOnce()
1234
- return { strategy: 'tmpfs', degradeReason: 'definitive' }
1235
- }
1236
- return { strategy: 'tmpfs', degradeReason: 'unverified' }
1237
- }
1238
-
1239
- let tmpfsProcFallbackWarned = false
1240
- function warnTmpfsProcFallbackOnce(): void {
1241
- if (tmpfsProcFallbackWarned) return
1242
- tmpfsProcFallbackWarned = true
1243
- console.warn(
1244
- '[sandbox] degraded /proc mode: neither real-proc nor proc-bind is available on this host, ' +
1245
- 'so sandboxed external package runners (bunx / bun run <pkg-bin>) will fail. ' +
1246
- 'This needs a runtime with working user namespaces.',
1247
- )
1248
- }
1249
-
1250
900
  // The builtin file tools that take a single filesystem `path` arg. They run in
1251
901
  // the main process rather than bwrap, so each must apply the same
1252
902
  // /tmp -> session-dir mapping that
@@ -297,6 +297,7 @@ export function renderInteractiveSessionContext(subagentRoster: string): string
297
297
  '',
298
298
  '- Spawns run in the background by default: a `<system-reminder>` arrives when the subagent completes — do not poll `subagent_output`. Pass `run_in_foreground: true` for a quick result you need this turn; deep-profile subagents always run in the background from here. In channel sessions a completion reminder is not a user message: surface the result via `channel_reply`/`channel_send`.',
299
299
  '- Broad search: spawn 2-5 `explorer`/`scout` workers in parallel, end your response, then collect each completion once. Use `scout` for narrow lookups and `researcher` for decomposed, multi-source, cross-validated synthesis. When the user *explicitly* asks to research or investigate, you MUST spawn `researcher`: answering from training memory or one inline `web_search` does not satisfy the request, and `scout`/`explorer` fan-out does not replace `researcher`.',
300
+ '- Delegate the search, not the judgment. When an answer depends on reasoning across raw records — transactions, logs, messages, database rows — use `explorer` to locate them, then read or query the decisive records yourself before concluding. A subagent summary drops the cross-record patterns an answer usually hinges on (sequences, matching amounts, what stopped and what started), and a subagent that found nothing is not evidence that the records hold nothing.',
300
301
  '- Delegate-and-converse: for side-effectful or noisy work over ~30s, spawn one background subagent and stay responsive — `operator` for side effects, `scout` for a quick lookup, `researcher` for deep investigation, `planner` for risk-aware sequencing, `qa` to prove a PR, repo, or deployed product actually works by running it. Pass `profile: "deep"` only when the work needs stronger reasoning than the default tier.',
301
302
  '- Web browsing: never drive a browser yourself. Any task that needs a real browser — navigating, clicking, forms, logins, screenshots, JS-rendered pages — goes to `browser`. Plain lookups stay with `scout`/`web_fetch`.',
302
303
  '- Troubleshooting: after ~3 non-converging attempts at the same failure, stop and hand the loop to `operator` (background; `profile: "deep"` when genuinely hard) with the symptom, attempts, and success condition. Read `typeclaw-troubleshooting` before spawning.',
@@ -346,7 +347,7 @@ function renderChannelRolePolicy(): string {
346
347
  '',
347
348
  'Channel sessions may include multiple speakers; never carry one speaker’s',
348
349
  'role onto later messages. The current speaker’s authoritative role is the',
349
- '`<your-role>` turn tag; absent tag = unconstrained default.',
350
+ '`<your-role>` turn tag; no tag means the speaker is the owner.',
350
351
  '',
351
352
  'Tool calls/channel admission are gated by that speaker’s permissions;',
352
353
  '`blocked:` or "denied by permissions" means they lack the needed grant.',
@@ -101,8 +101,8 @@ export type SubagentCompletedPayload = {
101
101
  hasRecoverableOutput?: boolean
102
102
  // Present when the parent was a channel session. Lets the router fall back
103
103
  // to the live successor session for the same channel key when the parent
104
- // rolled over (SESSION_FRESHNESS_TTL_MS) or was idle-evicted while the
105
- // subagent ran — otherwise the completion is silently dropped.
104
+ // rolled over after 60 minutes idle (SESSION_FRESHNESS_TTL_MS) or was
105
+ // idle-evicted while the subagent ran — otherwise the completion is silently dropped.
106
106
  channelKey?: SubagentCompletedChannelKey
107
107
  }
108
108
 
@@ -0,0 +1,141 @@
1
+ import {
2
+ renderInteractiveSessionContext,
3
+ renderSessionOrigin,
4
+ type SessionOrigin,
5
+ type SessionRoleContext,
6
+ } from './session-origin'
7
+ import {
8
+ buildSystemPolicy,
9
+ DEFAULT_SUBAGENT_ROSTER,
10
+ renderRuntimeBlock,
11
+ renderRuntimeNondisclosureRule,
12
+ } from './system-prompt'
13
+
14
+ // Origins with a conversation partner waiting on the reply get the full-mode
15
+ // session context: the interactive orchestration context with the live public
16
+ // roster, the MCP catalog, and the git nudge. Unattended origins (cron fires,
17
+ // default subagents, system processes) skip that context and the roster/git/MCP
18
+ // work it needs — their origin block already says what is expected. Every
19
+ // origin gets the same shared policy either way.
20
+ //
21
+ // Exhaustive switch (not a boolean expression) so a future origin kind forces
22
+ // the author to make an explicit full-or-slim decision at compile time. The
23
+ // previous form silently defaulted new origins to slim, which would have
24
+ // stripped the interactive context from a new interactive surface by
25
+ // accident.
26
+ export function deriveSystemPromptMode(origin: SessionOrigin | undefined): SystemPromptMode {
27
+ if (origin === undefined) return 'full'
28
+ switch (origin.kind) {
29
+ case 'tui':
30
+ case 'channel':
31
+ return 'full'
32
+ case 'cron':
33
+ case 'subagent':
34
+ case 'system':
35
+ return 'slim'
36
+ default: {
37
+ const _exhaustive: never = origin
38
+ void _exhaustive
39
+ return 'full'
40
+ }
41
+ }
42
+ }
43
+
44
+ // Pure inputs for `composeSystemPrompt`. Each field maps 1:1 to a rendered
45
+ // section of the prompt; callers that don't want a section pass `undefined`
46
+ // (or `''` for `gitNudge`). Extracted so the debug dumper in
47
+ // `scripts/dump-system-prompt.ts` can reuse the exact same composition
48
+ // pipeline `createResourceLoader` uses, with no risk of drift if the
49
+ // section order changes.
50
+ //
51
+ // `mode` selects only the optional session context, never the policy: every
52
+ // standard session starts with `buildSystemPolicy(branding)`.
53
+ // - 'full' (default) — TUI, channel, and origin-less sessions: appends the
54
+ // interactive context (`renderInteractiveSessionContext`) with the roster.
55
+ // - 'slim' — cron, default subagents, system processes: no interactive
56
+ // context; the origin block covers per-kind specifics (no human, side
57
+ // effects via tools, narrow scope).
58
+ export type SystemPromptMode = 'full' | 'slim'
59
+
60
+ export type SystemPromptComposition = {
61
+ mode?: SystemPromptMode
62
+ // Whether the prompt discloses that the agent runs on TypeClaw. When false,
63
+ // the policy's opening is phrased generically, the `## Runtime` version
64
+ // block is dropped, and the runtime-disclosure rule is appended. Defaults to
65
+ // true. Mirrors `config.branding`.
66
+ branding?: boolean
67
+ self: string
68
+ // Pre-rendered interactive-context roster (from `renderPublicSubagentRoster`).
69
+ // Kept as a ready string so this composer stays pure and registry-free; the
70
+ // registry-aware caller renders it. Ignored in slim mode (no interactive
71
+ // context). Falls back to `DEFAULT_SUBAGENT_ROSTER` when omitted.
72
+ subagentRoster?: string
73
+ runtimeVersion?: string
74
+ origin?: SessionOrigin
75
+ roleContext?: SessionRoleContext
76
+ mcpCatalog?: string
77
+ gitNudge: string
78
+ proactiveNextStepNudge?: string
79
+ evalHint?: string
80
+ }
81
+
82
+ // Section-order contract for the system prompt. Kept as a pure string→string
83
+ // transform so it can be exercised without disk, plugin runtime, or auth.
84
+ //
85
+ // Cache-suffix ordering: least-volatile sections first, most-volatile last.
86
+ // This minimises the number of cached prompt bytes invalidated when a
87
+ // section changes (the provider's prompt cache hits up to the first byte
88
+ // that differs).
89
+ //
90
+ // 0. shared policy — identical for every standard session of an agent.
91
+ // 1. self — IDENTITY.md + SOUL.md (plus any plugin `session.prompt` append).
92
+ // 2. runtime block (or the runtime-disclosure rule when branding is off) —
93
+ // only changes on typeclaw releases.
94
+ // 3. interactive context (full mode) — stable per agent registry, so it
95
+ // precedes the per-session origin block.
96
+ // 4. origin block + role — stable across sessions of the same kind; channel
97
+ // origins carry per-conversation details.
98
+ // 5. MCP catalog — changes when servers connect or disconnect.
99
+ // 6. gitNudge — rare changes; agent folders force-commit sessions/ and
100
+ // memory/ after every turn, so the dirty-files list is empty most of
101
+ // the time.
102
+ // 7. proactive next-step nudge — deterministic per model family.
103
+ //
104
+ // The wall-clock anchor that used to live here as `## Now` moved out
105
+ // entirely. It is now injected into the user turn at each `session.prompt`
106
+ // site via `renderTurnTimeAnchor` (src/agent/system-prompt.ts) so the
107
+ // stamp reflects the moment of THIS turn, not session creation. Per-turn
108
+ // injection costs zero cached bytes — the user turn is the non-cacheable
109
+ // suffix anyway — and removes the staleness failure mode where a session
110
+ // opened Friday answered "today is Friday" on Thursday. Retrieved memory and
111
+ // the live channel role ride in the user turn for the same reason.
112
+ //
113
+ // pi appends project context (AGENTS.md), the skill catalog, and the cwd
114
+ // after this preamble when it builds the final system message.
115
+ export function composeSystemPrompt(parts: SystemPromptComposition): string {
116
+ const branding = parts.branding ?? true
117
+ let prompt = `${buildSystemPolicy(branding)}\n\n${parts.self}`
118
+ if (branding && parts.runtimeVersion !== undefined) {
119
+ prompt = `${prompt}\n\n${renderRuntimeBlock(parts.runtimeVersion)}`
120
+ }
121
+ if (!branding) {
122
+ prompt = `${prompt}\n\n${renderRuntimeNondisclosureRule()}`
123
+ }
124
+ if (parts.mode !== 'slim') {
125
+ prompt = `${prompt}\n\n${renderInteractiveSessionContext(parts.subagentRoster ?? DEFAULT_SUBAGENT_ROSTER)}`
126
+ }
127
+ if (parts.origin !== undefined) {
128
+ prompt = `${prompt}\n\n${renderSessionOrigin(parts.origin, Date.now(), parts.roleContext)}`
129
+ }
130
+ if (parts.mcpCatalog !== undefined && parts.mcpCatalog !== '') {
131
+ prompt = `${prompt}\n\n${parts.mcpCatalog}`
132
+ }
133
+ if (parts.gitNudge !== '') {
134
+ prompt = `${prompt}\n\n${parts.gitNudge}`
135
+ }
136
+ if (parts.proactiveNextStepNudge !== undefined && parts.proactiveNextStepNudge !== '') {
137
+ prompt = `${prompt}\n\n${parts.proactiveNextStepNudge}`
138
+ }
139
+ if (parts.evalHint) prompt = `${prompt}\n\n${parts.evalHint}`
140
+ return prompt
141
+ }