typeclaw 0.47.2 → 0.48.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 (105) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +1 -2
  3. package/src/agent/loop-guard.ts +71 -41
  4. package/src/agent/plugin-tools.ts +167 -50
  5. package/src/agent/system-prompt.ts +1 -1
  6. package/src/agent/turn-runner.ts +12 -2
  7. package/src/bundled-plugins/agent-browser/index.ts +0 -38
  8. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
  9. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
  10. package/src/bundled-plugins/memory/append-tool.ts +75 -2
  11. package/src/bundled-plugins/memory/frontmatter.ts +13 -2
  12. package/src/bundled-plugins/memory/load-memory.ts +1 -1
  13. package/src/bundled-plugins/memory/memory-logger.ts +5 -1
  14. package/src/bundled-plugins/memory/secret-detector.ts +7 -0
  15. package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
  16. package/src/bundled-plugins/memory/vector/passages.ts +5 -1
  17. package/src/bundled-plugins/security/index.ts +148 -98
  18. package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
  19. package/src/channels/adapters/discord-bot-edit.ts +3 -5
  20. package/src/channels/adapters/discord-bot-reactions.ts +4 -6
  21. package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
  22. package/src/channels/adapters/discord-bot.ts +20 -23
  23. package/src/channels/adapters/discord-edit.ts +3 -5
  24. package/src/channels/adapters/discord-reactions.ts +4 -6
  25. package/src/channels/adapters/discord.ts +1 -1
  26. package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
  27. package/src/channels/adapters/github/history.ts +2 -1
  28. package/src/channels/adapters/github/inbound.ts +4 -11
  29. package/src/channels/adapters/github/index.ts +6 -9
  30. package/src/channels/adapters/github/outbound.ts +3 -6
  31. package/src/channels/adapters/github/reactions.ts +3 -2
  32. package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
  33. package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
  34. package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
  35. package/src/channels/adapters/github/review-state.ts +3 -2
  36. package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
  37. package/src/channels/adapters/github/webhook-register.ts +5 -8
  38. package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
  39. package/src/channels/adapters/instagram.ts +1 -1
  40. package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
  41. package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
  42. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
  43. package/src/channels/adapters/kakaotalk-membership.ts +2 -5
  44. package/src/channels/adapters/kakaotalk-typing.ts +1 -1
  45. package/src/channels/adapters/kakaotalk.ts +1 -1
  46. package/src/channels/adapters/line-channel-resolver.ts +3 -5
  47. package/src/channels/adapters/line.ts +1 -1
  48. package/src/channels/adapters/slack-bot-edit.ts +1 -1
  49. package/src/channels/adapters/slack-bot-reactions.ts +4 -6
  50. package/src/channels/adapters/slack-bot.ts +8 -8
  51. package/src/channels/adapters/slack-edit.ts +3 -5
  52. package/src/channels/adapters/slack-reactions.ts +4 -6
  53. package/src/channels/adapters/slack.ts +1 -1
  54. package/src/channels/adapters/teams-edit.ts +2 -5
  55. package/src/channels/adapters/teams.ts +1 -1
  56. package/src/channels/adapters/telegram-bot-edit.ts +4 -7
  57. package/src/channels/adapters/telegram-bot.ts +1 -1
  58. package/src/channels/adapters/webex-bot.ts +1 -1
  59. package/src/channels/adapters/webex-edit.ts +3 -5
  60. package/src/channels/adapters/webex.ts +1 -1
  61. package/src/channels/github-review-claim.ts +89 -4
  62. package/src/channels/github-token-bridge.ts +2 -1
  63. package/src/channels/manager.ts +478 -64
  64. package/src/channels/membership-cache.ts +2 -5
  65. package/src/channels/persistence.ts +3 -6
  66. package/src/channels/reloadable.ts +23 -6
  67. package/src/channels/router.ts +134 -56
  68. package/src/channels/tunnel-bridge.ts +2 -1
  69. package/src/channels/types.ts +6 -3
  70. package/src/cli/hostd.ts +56 -28
  71. package/src/config/config.ts +10 -0
  72. package/src/config/providers.ts +179 -0
  73. package/src/dependencies/bin-resolver.ts +88 -0
  74. package/src/dependencies/bins.ts +227 -0
  75. package/src/dependencies/index.ts +17 -0
  76. package/src/doctor/checks.ts +2 -0
  77. package/src/doctor/operational-incidents.ts +32 -0
  78. package/src/hostd/credential-rotation-apply.ts +94 -0
  79. package/src/init/models-dev.ts +17 -3
  80. package/src/init/validate-api-key.ts +26 -4
  81. package/src/operations/classify-tool-outcome.ts +151 -0
  82. package/src/operations/incidents.ts +274 -0
  83. package/src/operations/index.ts +3 -0
  84. package/src/operations/remediations.ts +41 -0
  85. package/src/reload/client.ts +8 -2
  86. package/src/reload/docker-exec-client.ts +10 -2
  87. package/src/reload/index.ts +1 -1
  88. package/src/reload/recover.ts +5 -3
  89. package/src/reload/registry.ts +5 -5
  90. package/src/reload/types.ts +9 -1
  91. package/src/run/index.ts +5 -0
  92. package/src/sandbox/dependency-bins.ts +125 -0
  93. package/src/sandbox/errors.ts +32 -0
  94. package/src/sandbox/hidden-paths.ts +4 -1
  95. package/src/sandbox/index.ts +8 -0
  96. package/src/sandbox/policy.ts +1 -1
  97. package/src/sandbox/privileged-runtime.ts +88 -7
  98. package/src/sandbox/runtime-private.ts +4 -0
  99. package/src/sandbox/writable-zones.ts +4 -4
  100. package/src/server/index.ts +7 -5
  101. package/src/shared/protocol.ts +6 -1
  102. package/typeclaw.schema.json +35 -5
  103. package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
  104. package/src/bundled-plugins/agent-browser/shim.ts +0 -108
  105. /package/src/channels/{adapters/describe-error.ts → describe-error.ts} +0 -0
@@ -0,0 +1,41 @@
1
+ import type { OperationalIncidentFact } from './classify-tool-outcome'
2
+
3
+ export type RemediationResult = { repaired: boolean }
4
+ export type RemediationHandler = (fact: OperationalIncidentFact) => Promise<RemediationResult>
5
+
6
+ export class RemediationRegistry {
7
+ private readonly handlers = new Map<OperationalIncidentFact['kind'], RemediationHandler>()
8
+
9
+ register(kind: OperationalIncidentFact['kind'], handler: RemediationHandler): void {
10
+ this.handlers.set(kind, handler)
11
+ }
12
+
13
+ get(fact: OperationalIncidentFact): RemediationHandler | undefined {
14
+ return this.handlers.get(fact.kind)
15
+ }
16
+ }
17
+
18
+ export const operationalRemediations = new RemediationRegistry()
19
+
20
+ export type RepairAndRetryResult<T> =
21
+ | { outcome: 'retried'; value: T }
22
+ | { outcome: 'unhandled'; error: unknown }
23
+ | { outcome: 'repair-failed'; error: unknown }
24
+ | { outcome: 'retry-failed'; error: unknown }
25
+
26
+ export async function repairAndRetryOnce<T>(
27
+ registry: RemediationRegistry,
28
+ fact: OperationalIncidentFact,
29
+ originalError: unknown,
30
+ retry: () => Promise<T>,
31
+ ): Promise<RepairAndRetryResult<T>> {
32
+ const handler = registry.get(fact)
33
+ if (handler === undefined) return { outcome: 'unhandled', error: originalError }
34
+ const repaired = await handler(fact).catch(() => ({ repaired: false }))
35
+ if (!repaired.repaired) return { outcome: 'repair-failed', error: originalError }
36
+ try {
37
+ return { outcome: 'retried', value: await retry() }
38
+ } catch (retryError) {
39
+ return { outcome: 'retry-failed', error: retryError }
40
+ }
41
+ }
@@ -1,10 +1,11 @@
1
1
  import type { ClientMessage, ServerMessage } from '@/shared'
2
2
 
3
- import type { ReloadResult } from './types'
3
+ import type { ReloadCause, ReloadResult } from './types'
4
4
 
5
5
  export type RequestReloadOptions = {
6
6
  url: string
7
7
  scope?: string
8
+ cause?: ReloadCause
8
9
  timeoutMs?: number
9
10
  }
10
11
 
@@ -20,6 +21,7 @@ export class ReloadConnectionError extends Error {
20
21
  export async function requestReload({
21
22
  url,
22
23
  scope,
24
+ cause,
23
25
  timeoutMs = DEFAULT_TIMEOUT_MS,
24
26
  }: RequestReloadOptions): Promise<ReloadResult[]> {
25
27
  const ws = new WebSocket(url)
@@ -60,7 +62,11 @@ export async function requestReload({
60
62
  })
61
63
 
62
64
  try {
63
- const request: ClientMessage = scope ? { type: 'reload', scope } : { type: 'reload' }
65
+ const request: ClientMessage = {
66
+ type: 'reload',
67
+ ...(scope ? { scope } : {}),
68
+ ...(cause ? { cause } : {}),
69
+ }
64
70
  ws.send(JSON.stringify(request))
65
71
 
66
72
  return await new Promise<ReloadResult[]>((resolve, reject) => {
@@ -7,12 +7,13 @@ import {
7
7
  type DockerExecResult,
8
8
  } from '@/container'
9
9
 
10
- import type { ReloadResult } from './types'
10
+ import type { ReloadCause, ReloadResult } from './types'
11
11
 
12
12
  export type RequestReloadViaDockerExecOptions = {
13
13
  cwd: string
14
14
  token: string | null
15
15
  scope?: string
16
+ cause?: ReloadCause
16
17
  timeoutMs?: number
17
18
  exec?: DockerExec
18
19
  }
@@ -37,7 +38,12 @@ const finish = (payload, code) => {
37
38
  const timer = setTimeout(() => finish({ ok: false, reason: 'timed out waiting for container-local reload_result after ' + timeoutMs + 'ms' }, 1), timeoutMs)
38
39
  ws.addEventListener('open', () => {
39
40
  const scope = process.env.TYPECLAW_RELOAD_SCOPE
40
- ws.send(JSON.stringify(scope ? { type: 'reload', scope } : { type: 'reload' }))
41
+ const rawCause = process.env.TYPECLAW_RELOAD_CAUSE
42
+ ws.send(JSON.stringify({
43
+ type: 'reload',
44
+ ...(scope ? { scope } : {}),
45
+ ...(rawCause ? { cause: JSON.parse(rawCause) } : {}),
46
+ }))
41
47
  })
42
48
  ws.addEventListener('message', (event) => {
43
49
  const msg = JSON.parse(String(event.data))
@@ -53,12 +59,14 @@ export async function requestReloadViaDockerExec({
53
59
  cwd,
54
60
  token,
55
61
  scope,
62
+ cause,
56
63
  timeoutMs = DEFAULT_TIMEOUT_MS,
57
64
  exec = defaultDockerExec,
58
65
  }: RequestReloadViaDockerExecOptions): Promise<ReloadResult[]> {
59
66
  const envArgs = ['-e', `TYPECLAW_CONTAINER_PORT=${CONTAINER_PORT}`, '-e', `TYPECLAW_RELOAD_TIMEOUT_MS=${timeoutMs}`]
60
67
  if (token !== null) envArgs.push('-e', `TYPECLAW_TUI_TOKEN=${token}`)
61
68
  if (scope !== undefined) envArgs.push('-e', `TYPECLAW_RELOAD_SCOPE=${scope}`)
69
+ if (cause !== undefined) envArgs.push('-e', `TYPECLAW_RELOAD_CAUSE=${JSON.stringify(cause)}`)
62
70
 
63
71
  const signal = AbortSignal.timeout(timeoutMs)
64
72
  let result: DockerExecResult
@@ -7,4 +7,4 @@ export {
7
7
  type RequestReloadWithFallbackOptions,
8
8
  type RequestReloadWithFallbackResult,
9
9
  } from './recover'
10
- export type { Reloadable, ReloadAllResult, ReloadResult } from './types'
10
+ export type { Reloadable, ReloadAllResult, ReloadCause, ReloadContext, ReloadResult } from './types'
@@ -1,12 +1,13 @@
1
1
  import { ReloadConnectionError, requestReload } from './client'
2
2
  import { requestReloadViaDockerExec } from './docker-exec-client'
3
- import type { ReloadResult } from './types'
3
+ import type { ReloadCause, ReloadResult } from './types'
4
4
 
5
5
  export type RequestReloadWithFallbackOptions = {
6
6
  url: string
7
7
  cwd?: string
8
8
  token?: string | null
9
9
  scope?: string
10
+ cause?: ReloadCause
10
11
  timeoutMs?: number
11
12
  reload?: typeof requestReload
12
13
  reloadViaDockerExec?: typeof requestReloadViaDockerExec
@@ -21,17 +22,18 @@ export async function requestReloadWithFallback({
21
22
  cwd,
22
23
  token,
23
24
  scope,
25
+ cause,
24
26
  timeoutMs,
25
27
  reload = requestReload,
26
28
  reloadViaDockerExec = requestReloadViaDockerExec,
27
29
  }: RequestReloadWithFallbackOptions): Promise<RequestReloadWithFallbackResult> {
28
30
  try {
29
- return { transport: 'host', results: await reload({ url, scope, timeoutMs }) }
31
+ return { transport: 'host', results: await reload({ url, scope, cause, timeoutMs }) }
30
32
  } catch (err) {
31
33
  if (!(err instanceof ReloadConnectionError) || cwd === undefined || token === undefined) throw err
32
34
  return {
33
35
  transport: 'container-local',
34
- results: await reloadViaDockerExec({ cwd, token, scope, timeoutMs }),
36
+ results: await reloadViaDockerExec({ cwd, token, scope, cause, timeoutMs }),
35
37
  hostError: err.message,
36
38
  }
37
39
  }
@@ -1,4 +1,4 @@
1
- import type { Reloadable, ReloadAllResult, ReloadResult } from './types'
1
+ import type { Reloadable, ReloadAllResult, ReloadContext, ReloadResult } from './types'
2
2
 
3
3
  export class ReloadRegistry {
4
4
  private items = new Map<string, Reloadable>()
@@ -26,11 +26,11 @@ export class ReloadRegistry {
26
26
  // effects of earlier ones — e.g. cron reload reads the freshly swapped
27
27
  // config when it runs after the config reloadable. Manual reload is rare,
28
28
  // so deterministic ordering wins over parallelism.
29
- async reloadAll(): Promise<ReloadAllResult> {
29
+ async reloadAll(context?: ReloadContext): Promise<ReloadAllResult> {
30
30
  const results: ReloadResult[] = []
31
31
  for (const item of this.list()) {
32
32
  try {
33
- results.push(await item.reload())
33
+ results.push(await item.reload(context))
34
34
  } catch (err) {
35
35
  results.push({ scope: item.scope, ok: false, reason: errorMessage(err) })
36
36
  }
@@ -38,11 +38,11 @@ export class ReloadRegistry {
38
38
  return { results }
39
39
  }
40
40
 
41
- async reloadOne(scope: string): Promise<ReloadResult> {
41
+ async reloadOne(scope: string, context?: ReloadContext): Promise<ReloadResult> {
42
42
  const item = this.items.get(scope)
43
43
  if (!item) return { scope, ok: false, reason: `unknown scope: ${scope}` }
44
44
  try {
45
- return await item.reload()
45
+ return await item.reload(context)
46
46
  } catch (err) {
47
47
  return { scope, ok: false, reason: errorMessage(err) }
48
48
  }
@@ -2,10 +2,18 @@ export type ReloadResult =
2
2
  | { scope: string; ok: true; summary: string; details?: unknown }
3
3
  | { scope: string; ok: false; reason: string }
4
4
 
5
+ // An operator-initiated reload (CLI, agent tool, /reload) carries no cause and
6
+ // stays non-destructive for live adapters. A credential-rotation reload names
7
+ // the single adapter whose credential was just rewritten on disk, which is what
8
+ // authorizes the channels reloadable to bounce exactly that one adapter.
9
+ export type ReloadCause = { kind: 'credential-rotation'; adapter: string }
10
+
11
+ export type ReloadContext = { cause?: ReloadCause }
12
+
5
13
  export type Reloadable = {
6
14
  scope: string
7
15
  description: string
8
- reload: () => Promise<ReloadResult>
16
+ reload: (context?: ReloadContext) => Promise<ReloadResult>
9
17
  }
10
18
 
11
19
  export type ReloadAllResult = {
package/src/run/index.ts CHANGED
@@ -55,6 +55,7 @@ import {
55
55
  type ParseCronMode,
56
56
  type Scheduler,
57
57
  } from '@/cron'
58
+ import { logDependencyBinProblems, registerDependencyBinDoctorCheck, validateDependencyBins } from '@/dependencies'
58
59
  import { CLI_VERSION } from '@/init/cli-version'
59
60
  import { createMcpManager, resolveContainerMcpOAuthStore, TypeClawMcpOAuthProvider } from '@/mcp'
60
61
  import { runStartupMigrations } from '@/migrations'
@@ -330,6 +331,10 @@ async function startAgentRuntime(
330
331
  )
331
332
  const pluginRegistry = pluginsLoaded.registry
332
333
  const pluginHooks = pluginsLoaded.hooks
334
+ const dependencyBinLogger = createPluginLogger('typeclaw')
335
+ const bootDependencyBins = await validateDependencyBins(cwd)
336
+ logDependencyBinProblems(bootDependencyBins, dependencyBinLogger)
337
+ registerDependencyBinDoctorCheck(pluginRegistry, cwd, dependencyBinLogger)
333
338
 
334
339
  const { registry: subagents, pluginSubagentByShim, pluginSubagentByName } = mergeSubagents(pluginRegistry)
335
340
 
@@ -0,0 +1,125 @@
1
+ import { randomUUID } from 'node:crypto'
2
+ import { constants } from 'node:fs'
3
+ import { lstat, mkdir, open, readdir, rename, rm, writeFile } from 'node:fs/promises'
4
+ import { join } from 'node:path'
5
+
6
+ import { validateDependencyBins, type DependencyBinIssue, type ResolvedDependencyBin } from '@/dependencies'
7
+
8
+ export const DEPENDENCY_BIN_DIR_NAME = 'typeclaw-dependency-bin'
9
+ export const DEPENDENCY_BIN_SANDBOX_DIR = `/tmp/${DEPENDENCY_BIN_DIR_NAME}`
10
+ export const DEPENDENCY_BIN_SANDBOX_PATH = `${DEPENDENCY_BIN_SANDBOX_DIR}:/usr/local/bin:/usr/bin:/bin`
11
+
12
+ export type DependencyBinReconciliation = {
13
+ wrapperDir: string
14
+ resolutions: ResolvedDependencyBin[]
15
+ unavailable: Extract<ResolvedDependencyBin, { kind: 'unavailable' }>[]
16
+ issues: DependencyBinIssue[]
17
+ protectedFiles: string[]
18
+ }
19
+
20
+ const reconciliationLocks = new Map<string, Promise<void>>()
21
+
22
+ export async function reconcileDependencyBinWrappers(options: {
23
+ agentDir: string
24
+ sessionTmp: string
25
+ baselineDirs?: readonly string[]
26
+ }): Promise<DependencyBinReconciliation> {
27
+ const dir = join(options.sessionTmp, DEPENDENCY_BIN_DIR_NAME)
28
+ const previous = reconciliationLocks.get(dir) ?? Promise.resolve()
29
+ let release: () => void = () => {}
30
+ const gate = new Promise<void>((resolve) => {
31
+ release = resolve
32
+ })
33
+ const queued = previous.then(() => gate)
34
+ reconciliationLocks.set(dir, queued)
35
+ await previous
36
+ try {
37
+ return await reconcileDependencyBinWrappersUnlocked(options, dir)
38
+ } finally {
39
+ release()
40
+ if (reconciliationLocks.get(dir) === queued) reconciliationLocks.delete(dir)
41
+ }
42
+ }
43
+
44
+ async function reconcileDependencyBinWrappersUnlocked(
45
+ options: { agentDir: string; sessionTmp: string; baselineDirs?: readonly string[] },
46
+ dir: string,
47
+ ): Promise<DependencyBinReconciliation> {
48
+ const validation = await validateDependencyBins(options.agentDir, options.baselineDirs)
49
+ await ensureWrapperDir(dir)
50
+ const wrappers = new Map<string, string>()
51
+ for (const resolution of validation.resolutions) {
52
+ if (resolution.kind !== 'package' || wrappers.has(resolution.declaration.bin)) continue
53
+ wrappers.set(resolution.declaration.bin, renderWrapper(resolution.containerEntrypoint))
54
+ }
55
+ for (const entry of await readdir(dir).catch(() => [])) {
56
+ if (entry.startsWith('.')) continue
57
+ if (!wrappers.has(entry)) await rm(join(dir, entry), { recursive: true, force: true })
58
+ }
59
+ for (const [bin, contents] of wrappers) {
60
+ const path = join(dir, bin)
61
+ if (await isCurrentWrapper(path, contents)) continue
62
+ const temporary = join(dir, `.${bin}.${randomUUID()}.tmp`)
63
+ await writeFile(temporary, contents, { mode: 0o755, flag: 'wx' })
64
+ await rename(temporary, path).catch(async (error) => {
65
+ await rm(temporary, { force: true })
66
+ // POSIX rename replaces atomically, but Windows can fail while a concurrent
67
+ // reconcile holds the destination. Losing that race is benign as long as the
68
+ // winner wrote the identical wrapper.
69
+ if (await isCurrentWrapper(path, contents)) return
70
+ throw error
71
+ })
72
+ }
73
+ return {
74
+ wrapperDir: dir,
75
+ resolutions: validation.resolutions,
76
+ unavailable: validation.unavailable,
77
+ issues: validation.issues,
78
+ protectedFiles: validation.protectedFiles,
79
+ }
80
+ }
81
+
82
+ export function dependencyBinUnavailableHint(
83
+ command: string,
84
+ reconciliation: DependencyBinReconciliation,
85
+ ): string | undefined {
86
+ const unavailable = reconciliation.unavailable.find((entry) => commandInvokesBin(command, entry.declaration.bin))
87
+ if (unavailable === undefined) return undefined
88
+ const declaration = unavailable.declaration
89
+ return `[typeclaw:capability-unavailable capability=dependency-bin dependency=${declaration.package} bin=${declaration.bin} action=operator-install]`
90
+ }
91
+
92
+ async function ensureWrapperDir(dir: string): Promise<void> {
93
+ const existing = await lstat(dir).catch(() => undefined)
94
+ if (existing !== undefined && (!existing.isDirectory() || existing.isSymbolicLink())) {
95
+ await rm(dir, { recursive: true, force: true })
96
+ }
97
+ await mkdir(dir, { recursive: true, mode: 0o700 })
98
+ }
99
+
100
+ async function isCurrentWrapper(path: string, expected: string): Promise<boolean> {
101
+ const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => undefined)
102
+ if (handle === undefined) return false
103
+ try {
104
+ const [contents, info] = await Promise.all([handle.readFile('utf8'), handle.stat()])
105
+ // Windows has no POSIX permission bits, so requiring 0o755 there would make
106
+ // every wrapper look stale and defeat both idempotence and race recovery.
107
+ const modeMatches = process.platform === 'win32' || (info.mode & 0o777) === 0o755
108
+ return info.isFile() && modeMatches && contents === expected
109
+ } finally {
110
+ await handle.close()
111
+ }
112
+ }
113
+
114
+ function renderWrapper(entrypoint: string): string {
115
+ return `#!/bin/sh\nexec bun ${shellQuote(entrypoint)} "$@"\n`
116
+ }
117
+
118
+ function commandInvokesBin(command: string, bin: string): boolean {
119
+ const escaped = bin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
120
+ return new RegExp(`(?:^|[;&|()\\n]\\s*)${escaped}(?:\\s|$)`).test(command)
121
+ }
122
+
123
+ function shellQuote(value: string): string {
124
+ return `'${value.replaceAll("'", `'"'"'`)}'`
125
+ }
@@ -26,6 +26,38 @@ export class SandboxPolicyError extends Error {
26
26
  }
27
27
  }
28
28
 
29
+ // Raised when model-driven bash invokes an agent-messenger CLI. TypeClaw never
30
+ // brokers those reusable auth profiles (resolvePrivilegedSandboxRuntime) AND
31
+ // masks the whole `workspace/.agent-messenger` directory, so the CLI can never
32
+ // authenticate here — every platform resolves credentials from a
33
+ // `<platform>-credentials.json` file, never from the environment.
34
+ //
35
+ // The refusal MUST announce itself. A silent one lets the uncredentialed CLI
36
+ // print its own "No current workspace set. Run `auth extract` first.", which the
37
+ // model reads as a fact about the WORLD — and it will then tell a human the
38
+ // runtime has no workspace authentication, laundering a local policy decision
39
+ // into a false claim about the upstream service. The CLI is honest about ITS
40
+ // state; it has no way to know it was deliberately deprived.
41
+ //
42
+ // Hence the message states its own provenance: what was withheld, that the
43
+ // decision is local, that retrying cannot help, and which mediated tool does
44
+ // work. The last part is load-bearing — a dead end the model cannot route
45
+ // around produces exactly the confabulation this class exists to prevent.
46
+ export class SandboxCredentialWithheldError extends Error {
47
+ override readonly name = 'SandboxCredentialWithheldError'
48
+ constructor(executable: string) {
49
+ super(
50
+ `credential withheld by TypeClaw policy: \`${executable}\` cannot authenticate in model-driven bash. ` +
51
+ 'TypeClaw never brokers an agent-messenger auth profile to a model-controlled child (the CLI can upload ' +
52
+ 'arbitrary files, so a brokered credential would make it a confused deputy), and its credential directory ' +
53
+ 'is masked. This is a LOCAL sandbox policy decision. It is NOT evidence that the workspace, account, or ' +
54
+ 'upstream service lacks authentication — do not report it as such. Retrying, running `auth extract`, or ' +
55
+ 'switching package runner will not change it. Use the mediated channel_* tools instead (channel_read, ' +
56
+ 'channel_history, channel_send), which run inside TypeClaw with the configured channel credential.',
57
+ )
58
+ }
59
+ }
60
+
29
61
  // Raised when the /proc strategy degraded to the empty `tmpfs` fallback AND the
30
62
  // command needs a real /proc (bunx / bun run that reads the
31
63
  // kernel-backed /proc/self/{fd,maps}). Without this pre-check Bun aborts deep in
@@ -7,6 +7,7 @@ import type { PermissionService } from '@/permissions/permissions'
7
7
 
8
8
  import { CANONICAL_AGENT_SECRET_DIRS, CANONICAL_AGENT_SECRET_FILES } from './canonical-secrets'
9
9
  import { SandboxMaskTargetError } from './errors'
10
+ import { CANONICAL_AGENT_RUNTIME_PRIVATE_FILES } from './runtime-private'
10
11
 
11
12
  export type HiddenPaths = {
12
13
  dirs: string[]
@@ -38,7 +39,9 @@ export function resolveHiddenPaths(
38
39
  ...CANONICAL_AGENT_SECRET_DIRS.map((dir) => join(agentDir, dir)),
39
40
  ...(seesPrivate ? [] : PRIVATE_DIRS.map((dir) => join(agentDir, dir))),
40
41
  ]
41
- const files = CANONICAL_AGENT_SECRET_FILES.map((f) => join(agentDir, f))
42
+ const files = [...CANONICAL_AGENT_SECRET_FILES, ...CANONICAL_AGENT_RUNTIME_PRIVATE_FILES].map((f) =>
43
+ join(agentDir, f),
44
+ )
42
45
  return { dirs, files }
43
46
  }
44
47
 
@@ -6,6 +6,7 @@ export {
6
6
  CANONICAL_HOME_SECRET_FILES,
7
7
  CONTAINER_RUNTIME_HOME,
8
8
  } from './canonical-secrets'
9
+ export { CANONICAL_AGENT_RUNTIME_PRIVATE_FILES } from './runtime-private'
9
10
  export {
10
11
  buildProcBindProbeScript,
11
12
  canBindProcSafely,
@@ -44,6 +45,13 @@ export {
44
45
  type PrivilegedSandboxRuntime,
45
46
  } from './privileged-runtime'
46
47
  export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
48
+ export {
49
+ DEPENDENCY_BIN_SANDBOX_DIR,
50
+ DEPENDENCY_BIN_SANDBOX_PATH,
51
+ dependencyBinUnavailableHint,
52
+ reconcileDependencyBinWrappers,
53
+ type DependencyBinReconciliation,
54
+ } from './dependency-bins'
47
55
  export { formatCommand, shellQuote } from './quote'
48
56
  export {
49
57
  SandboxDegradedProcError,
@@ -153,7 +153,7 @@ export type SandboxPolicy = {
153
153
  // these, every sandboxed bun invocation — the core subagent install path —
154
154
  // fails before it starts.
155
155
  export const DEFAULT_SANDBOX_ENV: Record<string, string> = {
156
- PATH: '/usr/local/bin:/usr/bin:/bin',
156
+ PATH: '/tmp/typeclaw-dependency-bin:/usr/local/bin:/usr/bin:/bin',
157
157
  HOME: '/tmp',
158
158
  LANG: 'C.UTF-8',
159
159
  BUN_TMPDIR: '/tmp',
@@ -2,7 +2,7 @@ import { chmod, lstat, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises
2
2
  import { homedir, tmpdir } from 'node:os'
3
3
  import path from 'node:path'
4
4
 
5
- import { SandboxPolicyError } from './errors'
5
+ import { SandboxCredentialWithheldError, SandboxPolicyError } from './errors'
6
6
  import type { SandboxMount } from './policy'
7
7
 
8
8
  const SAFE_GIT_SUBCOMMANDS = new Set([
@@ -30,6 +30,49 @@ const SAFE_GIT_SUBCOMMANDS = new Set([
30
30
 
31
31
  const SHELL_ACTIVE = new Set(['|', ';', '&', '\n', '\r', '(', ')', '{', '}', '<', '>', '`', '$', '\\'])
32
32
 
33
+ // The exact bins agent-messenger installs, kept in lockstep with the installed
34
+ // manifest by a test. Reserving the whole `agent-*` namespace instead would
35
+ // over-claim AND under-claim: an unrelated user-installed `agent-lint` would be
36
+ // refused with a false agent-messenger credential claim — the very class of
37
+ // false statement this refusal exists to prevent — while `amsg`, a real
38
+ // agent-messenger bin, carries no `agent-` prefix and would slip through.
39
+ export const AGENT_MESSENGER_BINS: ReadonlySet<string> = new Set([
40
+ 'agent-channeltalk',
41
+ 'agent-channeltalkbot',
42
+ 'agent-discord',
43
+ 'agent-discordbot',
44
+ 'agent-imessage',
45
+ 'agent-instagram',
46
+ 'agent-kakaotalk',
47
+ 'agent-line',
48
+ 'agent-messenger',
49
+ 'agent-slack',
50
+ 'agent-slackbot',
51
+ 'agent-teams',
52
+ 'agent-telegram',
53
+ 'agent-telegrambot',
54
+ 'agent-webex',
55
+ 'agent-webexbot',
56
+ 'agent-wechatbot',
57
+ 'agent-whatsapp',
58
+ 'agent-whatsappbot',
59
+ 'amsg',
60
+ ])
61
+
62
+ // Ephemeral runners that execute a package bin named by their first operand.
63
+ // `bunx` is the bare-binary alias for `bun x` (see sandbox/package-install.ts);
64
+ // npx/pnpx are the non-bun spellings the bun-hygiene guard still permits.
65
+ const PACKAGE_RUNNERS = new Set(['bunx', 'npx', 'pnpx'])
66
+ const BUN_RUNNER_SUBCOMMANDS = new Set(['x', 'run'])
67
+
68
+ // Splits at the shell operators that begin a NEW simple command, mirroring
69
+ // `commandNeedsRealProc`. Deliberately coarse: it over-splits inside quotes and
70
+ // `$()`, but this feeds a DENY-ONLY decision, so a spurious extra segment can
71
+ // only make the refusal MORE likely — it can never grant a credential.
72
+ const SHELL_COMMAND_SEPARATOR = /(?:&&|\|\||[;|&\n()<>])+/
73
+
74
+ const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/
75
+
33
76
  export type PrivilegedSandboxRuntime = {
34
77
  env: Record<string, string>
35
78
  mounts: SandboxMount[]
@@ -46,6 +89,7 @@ export async function resolvePrivilegedSandboxRuntime(options: {
46
89
  env?: NodeJS.ProcessEnv
47
90
  homeDir?: string
48
91
  }): Promise<PrivilegedSandboxRuntime> {
92
+ rejectAgentMessengerCommand(options.command)
49
93
  const runtime = emptyRuntime()
50
94
  // TYPECLAW_GIT_TOKEN is set only after the auth analyzer accepts a Git command.
51
95
  // Trust that decision rather than reparsing its command with a less capable
@@ -62,15 +106,23 @@ export async function resolvePrivilegedSandboxRuntime(options: {
62
106
  const executable = unwrapBunx(parsed)
63
107
  if (executable === null) return runtime
64
108
 
109
+ // Re-checked here as well as in the deny-only scan: this path resolves quoted
110
+ // and `bunx`-wrapped executables the coarse segment split cannot.
111
+ if (AGENT_MESSENGER_BINS.has(path.basename(executable.executable))) {
112
+ throw new SandboxCredentialWithheldError(path.basename(executable.executable))
113
+ }
114
+
65
115
  // These CLIs can print or upload arbitrary files. Supplying their reusable
66
116
  // auth profile to a model-controlled child would therefore make the CLI a
67
117
  // confused deputy even when the outer shell is syntactically standalone.
68
- if (
69
- executable.executable === 'gws' ||
70
- executable.executable === 'codex' ||
71
- executable.executable === 'claude' ||
72
- executable.executable.startsWith('agent-')
73
- ) {
118
+ //
119
+ // They stay executable-but-uncredentialed rather than refused outright: an
120
+ // operator CAN authenticate them from `.env`, which model bash does inherit,
121
+ // so refusing would break working setups. The agent-messenger family cannot —
122
+ // every platform reads a `<platform>-credentials.json` file under the
123
+ // unconditionally masked `workspace/.agent-messenger` — so it is a guaranteed
124
+ // dead end and is refused loudly above instead of failing misleadingly.
125
+ if (executable.executable === 'gws' || executable.executable === 'codex' || executable.executable === 'claude') {
74
126
  return runtime
75
127
  }
76
128
 
@@ -96,6 +148,35 @@ function containsGitInvocation(command: string): boolean {
96
148
  return /(^|[;&|]\s*)git(?:\s|$)/.test(command.trim())
97
149
  }
98
150
 
151
+ function rejectAgentMessengerCommand(command: string): void {
152
+ for (const segment of command.split(SHELL_COMMAND_SEPARATOR)) {
153
+ const bin = agentMessengerBinIn(segment)
154
+ if (bin !== undefined) throw new SandboxCredentialWithheldError(bin)
155
+ }
156
+ }
157
+
158
+ function agentMessengerBinIn(segment: string): string | undefined {
159
+ const words = segment
160
+ .trim()
161
+ .split(/\s+/)
162
+ .map((word) => word.replaceAll(/^["']|["']$/g, ''))
163
+ .filter((word) => word !== '' && !ENV_ASSIGNMENT.test(word))
164
+ const operand = unwrapPackageRunner(words).find((word) => !word.startsWith('-'))
165
+ if (operand === undefined) return undefined
166
+ const bin = path.basename(operand)
167
+ return AGENT_MESSENGER_BINS.has(bin) ? bin : undefined
168
+ }
169
+
170
+ function unwrapPackageRunner(words: readonly string[]): readonly string[] {
171
+ const head = words[0]
172
+ if (head === undefined) return words
173
+ const runner = path.basename(head)
174
+ if (PACKAGE_RUNNERS.has(runner)) return words.slice(1)
175
+ const subcommand = words[1]
176
+ if (runner === 'bun' && subcommand !== undefined && BUN_RUNNER_SUBCOMMANDS.has(subcommand)) return words.slice(2)
177
+ return words
178
+ }
179
+
99
180
  export async function verifyPrivilegedSandboxRuntime(runtime: PrivilegedSandboxRuntime): Promise<void> {
100
181
  const identities = mountedIdentities.get(runtime) ?? new Map()
101
182
  for (const mount of runtime.mounts) {
@@ -0,0 +1,4 @@
1
+ // Runtime-owned operational state is private to TypeClaw, but is not a
2
+ // credential. Keep this category separate from canonical-secrets so security
3
+ // diagnostics never mislabel incident metadata as secret material.
4
+ export const CANONICAL_AGENT_RUNTIME_PRIVATE_FILES = ['.typeclaw/incidents.json'] as const
@@ -71,10 +71,10 @@ const FORBIDDEN_WRITABLE_ROOTS = [
71
71
  // `echo … > cron.json` from bash and defeat the guard entirely. Keeping them off
72
72
  // this list forces every mutation of a guarded file through the one guarded path
73
73
  // (the write/edit tool), so a managed file has exactly one mutation boundary.
74
- // `package.json` stays writable: it is NOT a semantically-guarded managed file
75
- // (only cron.json/typeclaw.json are), and ordinary trusted/manual edits remain
76
- // supported.
77
- const WRITABLE_ROOT_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md', 'package.json'] as const
74
+ // `package.json` is operator-owned because direct dependencies define the
75
+ // executable surface exposed in the model sandbox. It must not receive an RW
76
+ // rebind that would let model-driven bash expand its own PATH capabilities.
77
+ const WRITABLE_ROOT_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as const
78
78
 
79
79
  // SECURITY: the symlink rejection is load-bearing. An RW bind follows symlinks,
80
80
  // so a `workspace -> /etc` symlink at a zone root would grant write access to an
@@ -41,7 +41,7 @@ import type { McpManager } from '@/mcp'
41
41
  import type { PermissionService } from '@/permissions'
42
42
  import type { HookBus } from '@/plugin'
43
43
  import type { BrokerWsData, ContainerBroker } from '@/portbroker'
44
- import type { ReloadAllResult, ReloadRegistry } from '@/reload'
44
+ import type { ReloadAllResult, ReloadCause, ReloadContext, ReloadRegistry } from '@/reload'
45
45
  import type { ClaimController, ClaimResultEvent } from '@/role-claim'
46
46
  import type { PluginRuntime, PluginRuntimeState } from '@/run/plugin-runtime'
47
47
  import type { CommandOutbound, CommandRunner } from '@/server/command-runner'
@@ -64,7 +64,7 @@ import type {
64
64
  import type { Stream, StreamMessage, StreamMessageId, Unsubscribe } from '@/stream'
65
65
  import type { TunnelManager } from '@/tunnels'
66
66
 
67
- export type ReloadAllFn = () => Promise<ReloadAllResult>
67
+ export type ReloadAllFn = (context?: ReloadContext) => Promise<ReloadAllResult>
68
68
  export type CreateSessionFn = (options?: CreateSessionOptions) => Promise<AgentSession | CreateSessionResult>
69
69
 
70
70
  export type ServerLogger = {
@@ -744,7 +744,7 @@ export function createServer({
744
744
  }
745
745
 
746
746
  if (msg.type === 'reload') {
747
- await handleReload(ws, reloadAll, reloadRegistry, msg.scope)
747
+ await handleReload(ws, reloadAll, reloadRegistry, msg.scope, msg.cause)
748
748
  return
749
749
  }
750
750
 
@@ -1678,7 +1678,9 @@ async function handleReload(
1678
1678
  reloadAll: ReloadAllFn | undefined,
1679
1679
  reloadRegistry: ReloadRegistry | undefined,
1680
1680
  scope: string | undefined,
1681
+ cause: ReloadCause | undefined,
1681
1682
  ): Promise<void> {
1683
+ const context = cause === undefined ? undefined : { cause }
1682
1684
  if (scope !== undefined && scope.length > 0) {
1683
1685
  if (!reloadRegistry) {
1684
1686
  send(ws, {
@@ -1688,7 +1690,7 @@ async function handleReload(
1688
1690
  return
1689
1691
  }
1690
1692
  try {
1691
- const result = await reloadRegistry.reloadOne(scope)
1693
+ const result = await reloadRegistry.reloadOne(scope, context)
1692
1694
  send(ws, { type: 'reload_result', results: [result] })
1693
1695
  } catch (err) {
1694
1696
  send(ws, {
@@ -1705,7 +1707,7 @@ async function handleReload(
1705
1707
  return
1706
1708
  }
1707
1709
  try {
1708
- const { results } = await reloadAll()
1710
+ const { results } = await reloadAll(context)
1709
1711
  send(ws, { type: 'reload_result', results })
1710
1712
  } catch (err) {
1711
1713
  send(ws, {