typeclaw 0.47.2 → 0.48.1

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 (129) 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 +234 -58
  5. package/src/agent/system-prompt.ts +1 -1
  6. package/src/agent/turn-runner.ts +12 -2
  7. package/src/agent-messenger/config-dir.ts +131 -0
  8. package/src/agent-messenger/host-config-dir.ts +121 -0
  9. package/src/bundled-plugins/agent-browser/index.ts +0 -38
  10. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
  11. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
  12. package/src/bundled-plugins/memory/append-tool.ts +75 -2
  13. package/src/bundled-plugins/memory/frontmatter.ts +13 -2
  14. package/src/bundled-plugins/memory/load-memory.ts +1 -1
  15. package/src/bundled-plugins/memory/memory-logger.ts +5 -1
  16. package/src/bundled-plugins/memory/secret-detector.ts +7 -0
  17. package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
  18. package/src/bundled-plugins/memory/vector/passages.ts +5 -1
  19. package/src/bundled-plugins/security/index.ts +148 -98
  20. package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
  21. package/src/channels/adapters/discord-bot-edit.ts +3 -5
  22. package/src/channels/adapters/discord-bot-reactions.ts +4 -6
  23. package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
  24. package/src/channels/adapters/discord-bot.ts +20 -23
  25. package/src/channels/adapters/discord-edit.ts +3 -5
  26. package/src/channels/adapters/discord-reactions.ts +4 -6
  27. package/src/channels/adapters/discord.ts +1 -1
  28. package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
  29. package/src/channels/adapters/github/history.ts +2 -1
  30. package/src/channels/adapters/github/inbound.ts +4 -11
  31. package/src/channels/adapters/github/index.ts +6 -9
  32. package/src/channels/adapters/github/outbound.ts +3 -6
  33. package/src/channels/adapters/github/reactions.ts +3 -2
  34. package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
  35. package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
  36. package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
  37. package/src/channels/adapters/github/review-state.ts +3 -2
  38. package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
  39. package/src/channels/adapters/github/webhook-register.ts +5 -8
  40. package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
  41. package/src/channels/adapters/instagram.ts +1 -1
  42. package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
  43. package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
  44. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
  45. package/src/channels/adapters/kakaotalk-membership.ts +2 -5
  46. package/src/channels/adapters/kakaotalk-typing.ts +1 -1
  47. package/src/channels/adapters/kakaotalk.ts +1 -1
  48. package/src/channels/adapters/line-channel-resolver.ts +3 -5
  49. package/src/channels/adapters/line.ts +1 -1
  50. package/src/channels/adapters/slack-bot-edit.ts +1 -1
  51. package/src/channels/adapters/slack-bot-reactions.ts +4 -6
  52. package/src/channels/adapters/slack-bot.ts +8 -8
  53. package/src/channels/adapters/slack-edit.ts +3 -5
  54. package/src/channels/adapters/slack-reactions.ts +4 -6
  55. package/src/channels/adapters/slack.ts +1 -1
  56. package/src/channels/adapters/teams-edit.ts +2 -5
  57. package/src/channels/adapters/teams.ts +1 -1
  58. package/src/channels/adapters/telegram-bot-edit.ts +4 -7
  59. package/src/channels/adapters/telegram-bot.ts +1 -1
  60. package/src/channels/adapters/webex-bot.ts +1 -1
  61. package/src/channels/adapters/webex-edit.ts +3 -5
  62. package/src/channels/adapters/webex.ts +1 -1
  63. package/src/channels/github-review-claim.ts +89 -4
  64. package/src/channels/github-token-bridge.ts +2 -1
  65. package/src/channels/manager.ts +478 -64
  66. package/src/channels/membership-cache.ts +2 -5
  67. package/src/channels/persistence.ts +3 -6
  68. package/src/channels/reloadable.ts +23 -6
  69. package/src/channels/router.ts +134 -56
  70. package/src/channels/tunnel-bridge.ts +2 -1
  71. package/src/channels/types.ts +6 -3
  72. package/src/cli/channel.ts +15 -16
  73. package/src/cli/hostd.ts +61 -38
  74. package/src/cli/init.ts +21 -7
  75. package/src/cli/model.ts +6 -3
  76. package/src/cli/restart.ts +13 -15
  77. package/src/compose/restart.ts +14 -6
  78. package/src/config/config.ts +10 -0
  79. package/src/config/providers.ts +68 -0
  80. package/src/container/agent-operation-lock.ts +85 -0
  81. package/src/container/controller.ts +6 -0
  82. package/src/container/index.ts +8 -0
  83. package/src/container/restart.ts +55 -0
  84. package/src/container/shared.ts +5 -0
  85. package/src/container/start.ts +70 -4
  86. package/src/container/stop.ts +17 -1
  87. package/src/dependencies/bin-resolver.ts +88 -0
  88. package/src/dependencies/bins.ts +227 -0
  89. package/src/dependencies/index.ts +17 -0
  90. package/src/doctor/checks.ts +2 -0
  91. package/src/doctor/operational-incidents.ts +32 -0
  92. package/src/hostd/credential-rotation-apply.ts +94 -0
  93. package/src/hostd/daemon.ts +1 -1
  94. package/src/hostd/paths.ts +17 -0
  95. package/src/hostd/supervisor.ts +27 -10
  96. package/src/init/dockerfile.ts +6 -5
  97. package/src/init/env-file.ts +42 -18
  98. package/src/init/instagram-auth.ts +55 -31
  99. package/src/init/kakaotalk-auth.ts +1 -5
  100. package/src/init/line-auth.ts +45 -29
  101. package/src/init/models-dev.ts +131 -10
  102. package/src/init/opengateway-catalog.ts +120 -0
  103. package/src/init/validate-api-key.ts +26 -4
  104. package/src/operations/classify-tool-outcome.ts +151 -0
  105. package/src/operations/incidents.ts +274 -0
  106. package/src/operations/index.ts +3 -0
  107. package/src/operations/remediations.ts +41 -0
  108. package/src/reload/client.ts +8 -2
  109. package/src/reload/docker-exec-client.ts +10 -2
  110. package/src/reload/index.ts +1 -1
  111. package/src/reload/recover.ts +5 -3
  112. package/src/reload/registry.ts +5 -5
  113. package/src/reload/types.ts +9 -1
  114. package/src/run/index.ts +5 -0
  115. package/src/sandbox/canonical-secrets.ts +10 -1
  116. package/src/sandbox/dependency-bins.ts +125 -0
  117. package/src/sandbox/hidden-paths.ts +4 -1
  118. package/src/sandbox/index.ts +8 -0
  119. package/src/sandbox/policy.ts +1 -1
  120. package/src/sandbox/privileged-runtime.ts +7 -12
  121. package/src/sandbox/runtime-private.ts +4 -0
  122. package/src/sandbox/writable-zones.ts +4 -4
  123. package/src/server/index.ts +7 -5
  124. package/src/shared/protocol.ts +6 -1
  125. package/src/test-helpers/fake-agent-operation-lock.ts +66 -0
  126. package/typeclaw.schema.json +10 -5
  127. package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
  128. package/src/bundled-plugins/agent-browser/shim.ts +0 -108
  129. /package/src/channels/{adapters/describe-error.ts → describe-error.ts} +0 -0
@@ -0,0 +1,274 @@
1
+ import { chmod, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
2
+ import { dirname, join } from 'node:path'
3
+
4
+ import lockfile from 'proper-lockfile'
5
+
6
+ import { deriveOperationalIncidentFactsForSuccess } from './classify-tool-outcome'
7
+ import type { OperationalIncidentFact, OperationalIncidentSuccessInput } from './classify-tool-outcome'
8
+
9
+ export type IncidentStatus = 'unresolved' | 'resolved'
10
+
11
+ export type OperationalIncident = {
12
+ fingerprint: string
13
+ kind: OperationalIncidentFact['kind']
14
+ bin?: string
15
+ count: number
16
+ firstSeenAt: string
17
+ lastSeenAt: string
18
+ lastSessionId: string
19
+ status: IncidentStatus
20
+ recurrent: boolean
21
+ }
22
+
23
+ export type IncidentLedgerFile = { version: 1; incidents: OperationalIncident[] }
24
+
25
+ type LedgerInspection = { kind: 'missing' } | { kind: 'unknown' } | { kind: 'present'; version: string; size: number }
26
+
27
+ export type IncidentLedgerIo = {
28
+ inspect: (path: string) => Promise<LedgerInspection>
29
+ read: (agentDir: string) => Promise<IncidentLedgerFile>
30
+ serialize: (path: string, operation: () => Promise<void>) => Promise<void>
31
+ }
32
+
33
+ type OpenIncidentSnapshot = { version?: string; fingerprints: Set<string> }
34
+
35
+ const LOCK_RETRIES = { retries: 600, factor: 1, minTimeout: 10, maxTimeout: 10, randomize: false } as const
36
+ const openIncidentSnapshots = new Map<string, OpenIncidentSnapshot>()
37
+
38
+ export function incidentsPath(agentDir: string): string {
39
+ return join(agentDir, '.typeclaw', 'incidents.json')
40
+ }
41
+
42
+ export function fingerprintIncident(fact: OperationalIncidentFact): string {
43
+ if (fact.kind === 'sandbox-proc-unavailable') return 'sandbox:proc-unavailable'
44
+ const bin = normalizeBin(fact.bin)
45
+ return fact.kind === 'bash-command-not-found'
46
+ ? `bash:command-not-found:${bin}`
47
+ : `skill-bin:declared-but-unresolved:${bin}`
48
+ }
49
+
50
+ export function deriveMechanicallyVerifiedIncidentFingerprints(input: OperationalIncidentSuccessInput): Set<string> {
51
+ return new Set(deriveOperationalIncidentFactsForSuccess(input).map(fingerprintIncident))
52
+ }
53
+
54
+ export async function readIncidentLedger(agentDir: string): Promise<IncidentLedgerFile> {
55
+ try {
56
+ const parsed = JSON.parse(await readFile(incidentsPath(agentDir), 'utf8')) as unknown
57
+ return parseLedger(parsed)
58
+ } catch {
59
+ return { version: 1, incidents: [] }
60
+ }
61
+ }
62
+
63
+ const DEFAULT_INCIDENT_LEDGER_IO: IncidentLedgerIo = {
64
+ inspect: inspectLedger,
65
+ read: readIncidentLedger,
66
+ serialize,
67
+ }
68
+
69
+ export class IncidentLedger {
70
+ constructor(
71
+ private readonly agentDir: string,
72
+ private readonly io: IncidentLedgerIo = DEFAULT_INCIDENT_LEDGER_IO,
73
+ ) {}
74
+
75
+ async record(fact: OperationalIncidentFact, sessionId: string, now = new Date()): Promise<OperationalIncident> {
76
+ const path = incidentsPath(this.agentDir)
77
+ let recorded: OperationalIncident | undefined
78
+ await this.io.serialize(path, async () => {
79
+ const ledger = await this.io.read(this.agentDir)
80
+ const fingerprint = fingerprintIncident(fact)
81
+ const timestamp = now.toISOString()
82
+ const existing = ledger.incidents.find((incident) => incident.fingerprint === fingerprint)
83
+ if (existing === undefined) {
84
+ recorded = {
85
+ fingerprint,
86
+ kind: fact.kind,
87
+ ...(fact.kind === 'sandbox-proc-unavailable' ? {} : { bin: normalizeBin(fact.bin) }),
88
+ count: 1,
89
+ firstSeenAt: timestamp,
90
+ lastSeenAt: timestamp,
91
+ lastSessionId: sessionId,
92
+ status: 'unresolved',
93
+ recurrent: false,
94
+ }
95
+ ledger.incidents.push(recorded)
96
+ } else {
97
+ existing.count += 1
98
+ existing.lastSeenAt = timestamp
99
+ existing.status = 'unresolved'
100
+ existing.recurrent ||= existing.lastSessionId !== sessionId
101
+ existing.lastSessionId = sessionId
102
+ recorded = existing
103
+ }
104
+ ledger.incidents.sort((a, b) => a.fingerprint.localeCompare(b.fingerprint))
105
+ await persistLedger(path, ledger)
106
+ rememberOpenIncidents(path, ledger, await this.io.inspect(path))
107
+ })
108
+ if (recorded === undefined) throw new Error('incident ledger record was not created')
109
+ return { ...recorded }
110
+ }
111
+
112
+ async resolve(fingerprint: string): Promise<boolean> {
113
+ return (await this.resolveCandidates(new Set([fingerprint]))).found > 0
114
+ }
115
+
116
+ async resolveObservedSuccess(fingerprints: Iterable<string>): Promise<number> {
117
+ const candidates = new Set(fingerprints)
118
+ if (candidates.size === 0) return 0
119
+ const path = incidentsPath(this.agentDir)
120
+ const cached = openIncidentSnapshots.get(path)
121
+ if (cached !== undefined && intersects(cached.fingerprints, candidates)) {
122
+ return (await this.resolveCandidates(candidates)).resolved
123
+ }
124
+
125
+ const inspection = await this.io.inspect(path)
126
+ if (inspection.kind === 'unknown') return 0
127
+ if (inspection.kind === 'missing' || inspection.size === 0) {
128
+ openIncidentSnapshots.set(path, {
129
+ ...(inspection.kind === 'present' ? { version: inspection.version } : {}),
130
+ fingerprints: new Set(),
131
+ })
132
+ return 0
133
+ }
134
+ if (cached?.version === inspection.version) return 0
135
+
136
+ const ledger = await this.io.read(this.agentDir)
137
+ rememberOpenIncidents(path, ledger, inspection)
138
+ if (!intersects(openIncidentSnapshots.get(path)?.fingerprints ?? new Set(), candidates)) return 0
139
+ return (await this.resolveCandidates(candidates)).resolved
140
+ }
141
+
142
+ private async resolveCandidates(candidates: Set<string>): Promise<{ found: number; resolved: number }> {
143
+ const path = incidentsPath(this.agentDir)
144
+ let found = 0
145
+ let resolved = 0
146
+ await this.io.serialize(path, async () => {
147
+ const ledger = await this.io.read(this.agentDir)
148
+ for (const incident of ledger.incidents) {
149
+ if (!candidates.has(incident.fingerprint)) continue
150
+ found += 1
151
+ if (incident.status === 'resolved') continue
152
+ incident.status = 'resolved'
153
+ resolved += 1
154
+ }
155
+ if (resolved > 0) await persistLedger(path, ledger)
156
+ rememberOpenIncidents(path, ledger, await this.io.inspect(path))
157
+ })
158
+ return { found, resolved }
159
+ }
160
+ }
161
+
162
+ export function renderIncidentHint(incident: OperationalIncident): string {
163
+ return `TYPECLAW_OPERATIONAL_INCIDENT ${JSON.stringify({
164
+ fingerprint: incident.fingerprint,
165
+ occurrence: incident.count,
166
+ recurrent: incident.recurrent,
167
+ status: incident.status,
168
+ automaticRepair: 'unavailable',
169
+ provenance: 'typeclaw-environment',
170
+ action: incident.recurrent
171
+ ? 'escalate-recurrent-environment-issue-to-operator'
172
+ : 'report-environment-issue-to-operator',
173
+ doNot: 'delegate-the-original-task-to-the-user',
174
+ })}`
175
+ }
176
+
177
+ export function renderUntrackedIncidentHint(fact: OperationalIncidentFact): string {
178
+ return `TYPECLAW_OPERATIONAL_INCIDENT ${JSON.stringify({
179
+ fingerprint: fingerprintIncident(fact),
180
+ recurrenceTracking: 'unavailable',
181
+ status: 'unresolved',
182
+ automaticRepair: 'unavailable',
183
+ provenance: 'typeclaw-environment',
184
+ action: 'report-environment-issue-to-operator',
185
+ doNot: 'delegate-the-original-task-to-the-user',
186
+ })}`
187
+ }
188
+
189
+ function normalizeBin(bin: string): string {
190
+ return bin.toLocaleLowerCase('en-US')
191
+ }
192
+
193
+ function parseLedger(value: unknown): IncidentLedgerFile {
194
+ if (typeof value !== 'object' || value === null) return { version: 1, incidents: [] }
195
+ const incidents = (value as { incidents?: unknown }).incidents
196
+ if (!Array.isArray(incidents)) return { version: 1, incidents: [] }
197
+ return { version: 1, incidents: incidents.filter(isIncident) }
198
+ }
199
+
200
+ function isIncident(value: unknown): value is OperationalIncident {
201
+ if (typeof value !== 'object' || value === null) return false
202
+ const candidate = value as Partial<OperationalIncident>
203
+ return (
204
+ typeof candidate.fingerprint === 'string' &&
205
+ typeof candidate.kind === 'string' &&
206
+ typeof candidate.count === 'number' &&
207
+ Number.isInteger(candidate.count) &&
208
+ candidate.count > 0 &&
209
+ typeof candidate.firstSeenAt === 'string' &&
210
+ typeof candidate.lastSeenAt === 'string' &&
211
+ typeof candidate.lastSessionId === 'string' &&
212
+ (candidate.status === 'unresolved' || candidate.status === 'resolved') &&
213
+ typeof candidate.recurrent === 'boolean'
214
+ )
215
+ }
216
+
217
+ function rememberOpenIncidents(path: string, ledger: IncidentLedgerFile, inspection: LedgerInspection): void {
218
+ openIncidentSnapshots.set(path, {
219
+ ...(inspection.kind === 'present' ? { version: inspection.version } : {}),
220
+ fingerprints: new Set(
221
+ ledger.incidents.filter((incident) => incident.status === 'unresolved').map((incident) => incident.fingerprint),
222
+ ),
223
+ })
224
+ }
225
+
226
+ function intersects(left: Set<string>, right: Set<string>): boolean {
227
+ for (const value of left) {
228
+ if (right.has(value)) return true
229
+ }
230
+ return false
231
+ }
232
+
233
+ async function inspectLedger(path: string): Promise<LedgerInspection> {
234
+ try {
235
+ const info = await stat(path)
236
+ if (!info.isFile()) return { kind: 'missing' }
237
+ return {
238
+ kind: 'present',
239
+ version: `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}`,
240
+ size: info.size,
241
+ }
242
+ } catch (error) {
243
+ const code = errorCode(error)
244
+ return code === 'ENOENT' || code === 'ENOTDIR' ? { kind: 'missing' } : { kind: 'unknown' }
245
+ }
246
+ }
247
+
248
+ function errorCode(error: unknown): string | undefined {
249
+ if (typeof error !== 'object' || error === null || !('code' in error)) return undefined
250
+ return typeof error.code === 'string' ? error.code : undefined
251
+ }
252
+
253
+ async function persistLedger(path: string, ledger: IncidentLedgerFile): Promise<void> {
254
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 })
255
+ const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`
256
+ await writeFile(temporary, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 })
257
+ await rename(temporary, path)
258
+ await chmod(path, 0o600)
259
+ }
260
+
261
+ async function serialize(path: string, operation: () => Promise<void>): Promise<void> {
262
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 })
263
+ const release = await lockfile.lock(path, {
264
+ realpath: false,
265
+ stale: 10_000,
266
+ update: 2_000,
267
+ retries: LOCK_RETRIES,
268
+ })
269
+ try {
270
+ await operation()
271
+ } finally {
272
+ await release().catch(() => undefined)
273
+ }
274
+ }
@@ -0,0 +1,3 @@
1
+ export * from './classify-tool-outcome'
2
+ export * from './incidents'
3
+ export * from './remediations'
@@ -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
 
@@ -1,6 +1,14 @@
1
+ import {
2
+ AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
3
+ LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
4
+ } from '@/agent-messenger/config-dir'
5
+
1
6
  export const CANONICAL_AGENT_SECRET_DIRS = [
2
7
  'workspace/.config/gws',
3
- 'workspace/.agent-messenger',
8
+ AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
9
+ // Retained permanently for interrupted migrations, operator backups under
10
+ // the old name, and older installs. This is not an active config location.
11
+ LEGACY_AGENT_MESSENGER_CONFIG_RELATIVE_DIR,
4
12
  '.typeclaw/home',
5
13
  '.typeclaw/logs',
6
14
  ] as const
@@ -17,6 +25,7 @@ export const CANONICAL_HOME_SECRET_DIRS = [
17
25
  '.ssh',
18
26
  '.config/gh',
19
27
  '.config/gws',
28
+ '.config/agent-messenger',
20
29
  '.agent-messenger',
21
30
  '.codex',
22
31
  '.claude',
@@ -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
+ }