typeclaw 0.39.4 → 0.39.6

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.
@@ -22,11 +22,22 @@ export class StickyLedger {
22
22
  inner.set(authorId, expiresAt)
23
23
  }
24
24
 
25
- consume(key: string, authorId: string, now: number): boolean {
25
+ // A live credit SLIDES its window forward (`now + windowMs`) rather than
26
+ // clearing on first spend. The send-path only re-grants after the reply lands
27
+ // (router `send()`), so a same-author follow-up arriving in that gap finds no
28
+ // credit and observes in a multi-human group (the solo-human fallback masks it
29
+ // in 1-human channels). A refreshed credit keeps that follow-up engaged and
30
+ // still expires after a full quiet window. An expired credit is purged and
31
+ // returns false (the expired-credit contract). `windowMs <= 0` purges on spend.
32
+ consume(key: string, authorId: string, now: number, windowMs: number): boolean {
26
33
  const inner = this.byKey.get(key)
27
34
  if (!inner) return false
28
35
  const expiresAt = inner.get(authorId)
29
36
  if (expiresAt === undefined) return false
37
+ if (expiresAt > now && windowMs > 0) {
38
+ inner.set(authorId, now + windowMs)
39
+ return true
40
+ }
30
41
  inner.delete(authorId)
31
42
  if (inner.size === 0) this.byKey.delete(key)
32
43
  return expiresAt > now
@@ -141,7 +152,11 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
141
152
  // STRUCTURALLY addressed elsewhere, leaving plain follow-ups engaged.
142
153
  // GitHub review-thread traffic must not spend content-blind sticky credit
143
154
  // unless the bot was explicitly addressed.
144
- if (!explicitOnly && config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
155
+ if (
156
+ !explicitOnly &&
157
+ config.stickiness !== 'off' &&
158
+ ledger.consume(key, message.authorId, now, config.stickiness.perReply.window)
159
+ ) {
145
160
  return 'engage'
146
161
  }
147
162
 
@@ -4,6 +4,7 @@ import { cancel, confirm, intro, isCancel, log, note, password, select, spinner,
4
4
  import { defineCommand } from 'citty'
5
5
  import QRCode from 'qrcode'
6
6
 
7
+ import { githubRequiredPermissionsNote } from '@/channels/adapters/github/permission-guidance'
7
8
  import { config } from '@/config'
8
9
  import {
9
10
  listChannels,
@@ -1039,8 +1040,7 @@ async function promptGithubCredentials(cwd: string): Promise<{
1039
1040
  note(
1040
1041
  [
1041
1042
  'Choose PAT auth for a quick setup, or GitHub App auth for expiring installation tokens.',
1042
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1043
- 'Metadata read, and Webhooks read/write (TypeClaw will create and manage the repository webhooks for you).',
1043
+ githubRequiredPermissionsNote(true),
1044
1044
  ].join('\n'),
1045
1045
  'Get GitHub credentials',
1046
1046
  )
@@ -1196,19 +1196,16 @@ async function promptGithubAuthUpdate(currentType: 'pat' | 'app'): Promise<Githu
1196
1196
  if (nextType === 'pat') {
1197
1197
  if (action === 'rotate') {
1198
1198
  note(
1199
- [
1200
- 'Rotate at https://github.com/settings/personal-access-tokens.',
1201
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1202
- 'Metadata read, and Webhooks read/write.',
1203
- ].join('\n'),
1199
+ ['Rotate at https://github.com/settings/personal-access-tokens.', githubRequiredPermissionsNote(false)].join(
1200
+ '\n',
1201
+ ),
1204
1202
  'Rotate the GitHub PAT',
1205
1203
  )
1206
1204
  } else {
1207
1205
  note(
1208
1206
  [
1209
1207
  'Create a fine-grained PAT at https://github.com/settings/personal-access-tokens.',
1210
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1211
- 'Metadata read, and Webhooks read/write.',
1208
+ githubRequiredPermissionsNote(false),
1212
1209
  ].join('\n'),
1213
1210
  'Switch to GitHub PAT auth',
1214
1211
  )
@@ -1236,8 +1233,7 @@ async function promptGithubAuthUpdate(currentType: 'pat' | 'app'): Promise<Githu
1236
1233
  note(
1237
1234
  [
1238
1235
  'Create a GitHub App at https://github.com/settings/apps/new and install it on your repositories.',
1239
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1240
- 'Metadata read, and Webhooks read/write.',
1236
+ githubRequiredPermissionsNote(false),
1241
1237
  'Then collect the App ID, generate a private key (.pem), and grab the Installation ID from the URL',
1242
1238
  'of the installation page (https://github.com/settings/installations/<installation-id>).',
1243
1239
  ].join('\n'),
package/src/cli/init.ts CHANGED
@@ -15,6 +15,7 @@ import {
15
15
  } from '@clack/prompts'
16
16
  import { defineCommand } from 'citty'
17
17
 
18
+ import { githubRequiredPermissionsNote } from '@/channels/adapters/github/permission-guidance'
18
19
  import {
19
20
  KNOWN_PROVIDER_VENDORS,
20
21
  KNOWN_PROVIDERS,
@@ -1666,8 +1667,7 @@ async function runGithubFlow(cwd: string): Promise<StepResult<CollectedInputs['c
1666
1667
  note(
1667
1668
  [
1668
1669
  'Choose PAT auth for a quick setup, or GitHub App auth for expiring installation tokens.',
1669
- 'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
1670
- 'Metadata read, and Webhooks read/write (TypeClaw will create and manage the repository webhooks for you).',
1670
+ githubRequiredPermissionsNote(true),
1671
1671
  ].join('\n'),
1672
1672
  'Get GitHub credentials',
1673
1673
  )
@@ -1,4 +1,4 @@
1
- import { proxyContainerCommand } from './container-command-client'
1
+ import { proxyContainerCommand, type ContainerProxyOptions } from './container-command-client'
2
2
  import { parseArgs, runHostCommand } from './host-command-runner'
3
3
  import { renderCommandHelp } from './plugin-command-help'
4
4
  import { discoverCommands } from './plugin-commands'
@@ -16,6 +16,11 @@ export type DispatchOptions = {
16
16
  stdout?: WritableStream<Uint8Array>
17
17
  stderr?: WritableStream<Uint8Array>
18
18
  signal?: AbortSignal
19
+ // Test seam: override container-URL resolution so unit tests exercise the
20
+ // container dispatch path without spawning a real `docker inspect` (slow and
21
+ // flaky on Windows CI). Unset in production: proxyContainerCommand falls back
22
+ // to the live docker probe.
23
+ resolveContainerUrl?: ContainerProxyOptions['resolveUrl']
19
24
  }
20
25
 
21
26
  export async function dispatchPluginCommand(opts: DispatchOptions): Promise<PluginCommandDispatchOutcome> {
@@ -62,6 +67,7 @@ export async function dispatchPluginCommand(opts: DispatchOptions): Promise<Plug
62
67
  stdout,
63
68
  stderr,
64
69
  abortSignal: signal,
70
+ resolveUrl: opts.resolveContainerUrl,
65
71
  })
66
72
  if (!containerResult.ok) {
67
73
  return { kind: 'error', exitCode: containerResult.exitCode, message: containerResult.message }
package/src/cli/ui.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { emitKeypressEvents as nodeEmitKeypressEvents } from 'node:readline'
1
2
  import { styleText } from 'node:util'
2
3
 
3
4
  import { cancel, intro, isCancel, log, note, outro, spinner as clackSpinner } from '@clack/prompts'
@@ -8,29 +9,38 @@ import { COMPACT_WORDMARK, WORDMARK_LINES, WORDMARK_WIDTH } from '@/shared/wordm
8
9
 
9
10
  export { cancel, intro, isCancel, log, note, outro }
10
11
 
11
- type ClackInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume'>
12
-
13
- // Hand stdin to a clack picker in a state it can own. Over an SSH pseudo-TTY,
14
- // Bun's readline keypress wiring only transitions stdin into flowing raw mode
15
- // reliably once the stream has already been resumed; on a never-resumed stdin
16
- // the picker renders but arrow keys echo as raw `^[[B` and never advance it.
17
- // Local terminals dodge this because stdin was already flowing. Worse, after a
18
- // pi-tui viewer (ProcessTerminal.stop() calls process.stdin.pause()), a plain
19
- // resume() does NOT re-flow stdin under Bun, so the next picker is dead over
20
- // SSH. Toggling raw mode on->off forces the TTY read back into flowing mode;
21
- // the trailing resume() + non-raw state is the baseline clack expects.
22
- // Never pause() here — a paused process.stdin does not reliably re-flow.
23
- export function prepareStdinForClack(input: ClackInput = process.stdin): void {
12
+ type ClackInput = Pick<NodeJS.ReadStream, 'isTTY' | 'resume'>
13
+
14
+ type KeypressInterface = { escapeCodeTimeout?: number }
15
+
16
+ type PrepareStdinDeps = {
17
+ emitKeypressEvents?: (stream: NodeJS.ReadableStream, iface: KeypressInterface) => void
18
+ }
19
+
20
+ // @clack/core@1.2.0 builds its readline interface with escapeCodeTimeout: 50 so
21
+ // a bare Esc (the cancel key) resolves fast. readline's keypress decoder binds
22
+ // that timeout ONCE, when emitKeypressEvents first installs it on the stream, and
23
+ // is a no-op on every later call — so pre-arming here without it would lock in
24
+ // readline's 500ms default and clack's own 50ms could never take effect.
25
+ const CLACK_ESCAPE_CODE_TIMEOUT_MS = 50
26
+
27
+ // Arm readline's keypress decoder on stdin before a clack picker reads it. Over
28
+ // an SSH pseudo-TTY, arrow keys arrive as raw `\x1b[A`/`\x1b[B` bytes and only
29
+ // become the `{ name: 'up' }` keypress events clack navigates on once that
30
+ // decoder is installed on THIS stream. After a prior raw-mode 'data' consumer or
31
+ // a pi-tui detach (ProcessTerminal.stop() pauses stdin), Bun does NOT re-arm the
32
+ // decoder when clack later calls createInterface({ terminal: true }), so the
33
+ // picker renders but arrows echo as `^[[A` and never advance. We pass clack's
34
+ // own escapeCodeTimeout so the pre-arm matches what clack would have set; raw
35
+ // mode is left to clack. Never pause() — a paused process.stdin does not
36
+ // reliably re-flow under Bun.
37
+ export function prepareStdinForClack(input: ClackInput = process.stdin, deps: PrepareStdinDeps = {}): void {
24
38
  if (!input.isTTY) return
25
- input.resume()
26
- if (typeof input.setRawMode === 'function') {
27
- try {
28
- input.setRawMode(true)
29
- input.setRawMode(false)
30
- } catch {
31
- /* terminal already torn down */
32
- }
33
- }
39
+ const emitKeypressEvents =
40
+ deps.emitKeypressEvents ??
41
+ ((stream: NodeJS.ReadableStream, iface: KeypressInterface) =>
42
+ nodeEmitKeypressEvents(stream, iface as unknown as Parameters<typeof nodeEmitKeypressEvents>[1]))
43
+ emitKeypressEvents(input as unknown as NodeJS.ReadableStream, { escapeCodeTimeout: CLACK_ESCAPE_CODE_TIMEOUT_MS })
34
44
  input.resume()
35
45
  }
36
46
 
@@ -85,9 +85,8 @@ export type ResolveInspectResult = { ok: true; target: InspectTarget } | { ok: f
85
85
 
86
86
  // Picker phase, split out from the streaming phase so the tail scope is created
87
87
  // AFTER the picker, never before. A raw-mode 'data' listener active during the
88
- // Clack picker (which forces cooked mode via prepareStdinForClack) fights Clack
89
- // for stdin and leaves the later stream in cooked mode — that was the recurring
90
- // "esc does nothing" regression.
88
+ // Clack picker fights Clack for stdin and leaves the later stream in cooked mode
89
+ // — that was the recurring "esc does nothing" regression.
91
90
  export async function resolveInspectTarget(opts: Omit<RunInspectOptions, 'signal'>): Promise<ResolveInspectResult> {
92
91
  const filterResult = parseFilter(opts.filter)
93
92
  if (!filterResult.ok) return { ok: false, exitCode: 2, reason: filterResult.reason }
@@ -87,9 +87,16 @@ const consoleLogger: CodexFetchObserverLogger = {
87
87
 
88
88
  type InstallState = {
89
89
  originalFetch: typeof fetch
90
- uninstall: () => void
90
+ wrapped: typeof fetch
91
+ claimants: number
91
92
  }
92
93
 
94
+ // Ref-counted so multiple agents in one process (compose, tests) share one
95
+ // `globalThis.fetch` wrapper: the FIRST install wraps fetch, each later install
96
+ // just joins, and `globalThis.fetch` is restored only when the LAST claimant
97
+ // releases. A bare singleton would let one agent's release (e.g. a second
98
+ // agent's boot-failure cleanup) tear down the observer out from under another
99
+ // still-running agent.
93
100
  let installed: InstallState | null = null
94
101
 
95
102
  // Returns true when the request is for the Codex Responses endpoint and we
@@ -340,8 +347,8 @@ export function installCodexFetchObserver(opts: CodexFetchObserverOptions = {}):
340
347
  }
341
348
  const logger = opts.logger ?? consoleLogger
342
349
  if (installed !== null) {
343
- logger.warn(`${LOG_PREFIX} install called but observer already installed; ignoring`)
344
- return installed.uninstall
350
+ installed.claimants++
351
+ return makeRelease(installed.wrapped)
345
352
  }
346
353
 
347
354
  const codexHost = opts.codexHost ?? DEFAULT_CODEX_HOST
@@ -421,14 +428,23 @@ export function installCodexFetchObserver(opts: CodexFetchObserverOptions = {}):
421
428
 
422
429
  globalThis.fetch = wrapped
423
430
 
424
- const uninstall = () => {
425
- if (installed === null) return
426
- if (globalThis.fetch === wrapped) {
427
- globalThis.fetch = originalFetch
431
+ installed = { originalFetch, wrapped, claimants: 1 }
432
+ return makeRelease(wrapped)
433
+ }
434
+
435
+ // Each install call gets its own idempotent release. The shared
436
+ // `globalThis.fetch` wrapper is restored only when the final claimant releases,
437
+ // so one agent releasing never disturbs another's still-active observer.
438
+ function makeRelease(wrapped: typeof fetch): () => void {
439
+ let released = false
440
+ return () => {
441
+ if (released || installed === null || installed.wrapped !== wrapped) return
442
+ released = true
443
+ installed.claimants--
444
+ if (installed.claimants > 0) return
445
+ if (globalThis.fetch === installed.wrapped) {
446
+ globalThis.fetch = installed.originalFetch
428
447
  }
429
448
  installed = null
430
449
  }
431
-
432
- installed = { originalFetch, uninstall }
433
- return uninstall
434
450
  }
@@ -0,0 +1,230 @@
1
+ // Process-level crash guard for the container stage. The incident: a Webex KMS
2
+ // request rejected 30s AFTER `listener.on('error')` already fired, so it escaped
3
+ // the adapter as an `unhandledRejection` — which Bun terminates the process on
4
+ // by default, taking Slack/Discord/cron/TUI/websocket down with one flaky dep.
5
+ //
6
+ // The guard NEVER calls `process.exit`. Policy (see `classifyFatalError`) is
7
+ // conservative so "never crash" does not become "pretend the process is healthy":
8
+ // a KNOWN channel-dependency `unhandledRejection` degrades just that channel; an
9
+ // `uncaughtException` or UNKNOWN `unhandledRejection` requests a supervised
10
+ // container restart (corrupt state is safer replaced than swallowed) while
11
+ // continuing best-effort until the host replaces us — it still never self-exits.
12
+ // Restart requests are rate-limited so a per-tick fault can't hammer the daemon.
13
+
14
+ export type FatalGuardKind = 'unhandledRejection' | 'uncaughtException'
15
+
16
+ export type FatalGuardDecision =
17
+ | { action: 'continue'; reason: string; scope?: string }
18
+ | { action: 'restart'; reason: string; scope?: string }
19
+
20
+ export type FatalGuardLogger = {
21
+ warn: (msg: string) => void
22
+ error: (msg: string) => void
23
+ }
24
+
25
+ export type FatalGuardOptions = {
26
+ logger?: FatalGuardLogger
27
+ // Ask the host daemon to bounce this container. Returns ok=false (never
28
+ // throws) when no host control endpoint is configured — the guard then logs
29
+ // and continues degraded rather than exiting.
30
+ requestRestart?: (reason: string) => Promise<{ ok: boolean; reason?: string }>
31
+ // Called for a `continue` decision carrying a channel scope, so the channel
32
+ // can be visibly marked degraded (e.g. log/status) instead of silently
33
+ // swallowing the error.
34
+ onDegrade?: (scope: string, reason: string) => void
35
+ now?: () => number
36
+ // Minimum spacing between restart requests. A fault re-firing on every event
37
+ // loop tick must not spam the host daemon. Default 60s.
38
+ restartMinIntervalMs?: number
39
+ }
40
+
41
+ export type FatalGuard = {
42
+ // Exposed for deterministic tests: invoke the policy without emitting a real
43
+ // process event. Production paths go through the installed listeners.
44
+ handle: (kind: FatalGuardKind, error: unknown) => void
45
+ }
46
+
47
+ const DEFAULT_RESTART_MIN_INTERVAL_MS = 60_000
48
+
49
+ const consoleLogger: FatalGuardLogger = {
50
+ warn: (m) => console.warn(m),
51
+ error: (m) => console.error(m),
52
+ }
53
+
54
+ // One process gets exactly one pair of OS-level listeners no matter how many
55
+ // callers install a guard (tests, `typeclaw compose`, an embedding host). Each
56
+ // caller's handler is refcounted into this set and receives every event; the
57
+ // listeners are attached on the first install and detached when the last
58
+ // disposer runs. A per-caller `process.on` would otherwise stack N copies that
59
+ // all fire on one rejection and survive a single `dispose()`.
60
+ type Installed = {
61
+ handlers: Set<(kind: FatalGuardKind, error: unknown) => void>
62
+ onUnhandledRejection: (reason: unknown) => void
63
+ onUncaughtException: (error: unknown) => void
64
+ }
65
+ let shared: Installed | null = null
66
+
67
+ export function installFatalGuard(options: FatalGuardOptions = {}): { guard: FatalGuard; dispose: () => void } {
68
+ const logger = options.logger ?? consoleLogger
69
+ const now = options.now ?? Date.now
70
+ const restartMinIntervalMs = options.restartMinIntervalMs ?? DEFAULT_RESTART_MIN_INTERVAL_MS
71
+ let lastRestartRequestAt: number | null = null
72
+
73
+ const handle = (kind: FatalGuardKind, error: unknown): void => {
74
+ // The guard body must never throw — a throwing handler re-enters the very
75
+ // failure mode it exists to contain. Everything is wrapped, with a bare
76
+ // console.error as the last-resort fallback.
77
+ try {
78
+ const decision = classifyFatalError(kind, error)
79
+ const detail = describeError(error)
80
+ logger.error(
81
+ `[fatal-guard] ${kind}: ${decision.reason}${decision.scope !== undefined ? ` scope=${decision.scope}` : ''} action=${decision.action} :: ${detail}`,
82
+ )
83
+
84
+ if (decision.action === 'continue') {
85
+ if (decision.scope !== undefined) {
86
+ try {
87
+ options.onDegrade?.(decision.scope, decision.reason)
88
+ } catch (degradeErr) {
89
+ logger.warn(`[fatal-guard] onDegrade(${decision.scope}) threw: ${describeError(degradeErr)}`)
90
+ }
91
+ }
92
+ return
93
+ }
94
+
95
+ requestRestart(decision.reason)
96
+ } catch (handlerErr) {
97
+ try {
98
+ console.error(`[fatal-guard] handler failed: ${describeError(handlerErr)}`)
99
+ } catch {
100
+ // Nothing left to do; swallowing here is the whole point.
101
+ }
102
+ }
103
+ }
104
+
105
+ const requestRestart = (reason: string): void => {
106
+ if (options.requestRestart === undefined) {
107
+ logger.warn(`[fatal-guard] restart requested (${reason}) but no host control endpoint; continuing degraded`)
108
+ return
109
+ }
110
+ const at = now()
111
+ if (lastRestartRequestAt !== null && at - lastRestartRequestAt < restartMinIntervalMs) {
112
+ logger.warn(`[fatal-guard] restart requested (${reason}) but rate-limited; continuing degraded`)
113
+ return
114
+ }
115
+ lastRestartRequestAt = at
116
+ void options
117
+ .requestRestart(reason)
118
+ .then((result) => {
119
+ if (result.ok) {
120
+ logger.warn(`[fatal-guard] container restart requested: ${reason}`)
121
+ } else {
122
+ logger.warn(
123
+ `[fatal-guard] container restart unavailable (${result.reason ?? 'unknown'}); continuing degraded`,
124
+ )
125
+ }
126
+ })
127
+ .catch((restartErr) => {
128
+ logger.warn(`[fatal-guard] container restart request threw: ${describeError(restartErr)}; continuing degraded`)
129
+ })
130
+ }
131
+
132
+ if (shared === null) {
133
+ const onUnhandledRejection = (reason: unknown): void => {
134
+ for (const h of shared?.handlers ?? []) h('unhandledRejection', reason)
135
+ }
136
+ const onUncaughtException = (error: unknown): void => {
137
+ for (const h of shared?.handlers ?? []) h('uncaughtException', error)
138
+ }
139
+ shared = { handlers: new Set(), onUnhandledRejection, onUncaughtException }
140
+ process.on('unhandledRejection', onUnhandledRejection)
141
+ process.on('uncaughtException', onUncaughtException)
142
+ }
143
+ shared.handlers.add(handle)
144
+
145
+ let disposed = false
146
+ const dispose = (): void => {
147
+ if (disposed || shared === null) return
148
+ disposed = true
149
+ shared.handlers.delete(handle)
150
+ if (shared.handlers.size === 0) {
151
+ process.off('unhandledRejection', shared.onUnhandledRejection)
152
+ process.off('uncaughtException', shared.onUncaughtException)
153
+ shared = null
154
+ }
155
+ }
156
+
157
+ return { guard: { handle }, dispose }
158
+ }
159
+
160
+ // Conservative by design. Only errors with positive evidence that they came
161
+ // from a known external channel dependency are recovered in place; everything
162
+ // else escalates to a supervised restart. Broad rules ("any Error with a code",
163
+ // "any network error") are intentionally avoided — they would mask real bugs.
164
+ export function classifyFatalError(kind: FatalGuardKind, error: unknown): FatalGuardDecision {
165
+ if (kind === 'uncaughtException') {
166
+ // A synchronous throw that reached the top of the stack means an unknown
167
+ // code path is in an undefined state. Replace, don't swallow.
168
+ return { action: 'restart', reason: 'uncaught exception' }
169
+ }
170
+
171
+ const scope = recognizeExternalChannelDependency(error)
172
+ if (scope !== null) {
173
+ return { action: 'continue', scope, reason: `${scope} async dependency rejection` }
174
+ }
175
+
176
+ return { action: 'restart', reason: 'unknown unhandled rejection' }
177
+ }
178
+
179
+ // Returns the channel scope to degrade when the rejection carries evidence of
180
+ // an external channel SDK, else null. Matches on structured error codes first,
181
+ // then on stack/module provenance — protocol/diagnostic tokens emitted by the
182
+ // libraries themselves, so English-literal matching is correct here (these are
183
+ // not natural-language user text).
184
+ function recognizeExternalChannelDependency(error: unknown): string | null {
185
+ const code = errorCode(error)
186
+ // Webex KMS (encryption key service) rejections: the incident's exact shape.
187
+ // The `WebexListener` emits an 'error' event for connection failures, but a
188
+ // KMS request that times out 30s later rejects a detached internal promise
189
+ // that never reaches that event.
190
+ if (code === 'KMS_ERROR') return 'webex'
191
+
192
+ const haystack = errorProvenance(error).toLowerCase()
193
+ if (haystack.includes('webex-message-handler') || haystack.includes('agent-messenger/webex')) return 'webex'
194
+
195
+ // Other agent-messenger channel SDKs (slack/discord/telegram/line/kakaotalk).
196
+ // Same containment rationale: one channel's escaped async rejection must not
197
+ // take the whole agent down. Generic `agent-messenger/...` provenance maps to
198
+ // a `channel` scope since the specific platform isn't always recoverable.
199
+ if (haystack.includes('agent-messenger')) return 'channel'
200
+
201
+ return null
202
+ }
203
+
204
+ function errorCode(error: unknown): string | null {
205
+ if (error !== null && typeof error === 'object' && 'code' in error) {
206
+ const code = (error as { code: unknown }).code
207
+ if (typeof code === 'string') return code
208
+ }
209
+ return null
210
+ }
211
+
212
+ function errorProvenance(error: unknown): string {
213
+ if (error instanceof Error) {
214
+ return `${error.stack ?? ''}\n${error.message}`
215
+ }
216
+ if (error !== null && typeof error === 'object') {
217
+ const stack = 'stack' in error ? String((error as { stack: unknown }).stack ?? '') : ''
218
+ const message = 'message' in error ? String((error as { message: unknown }).message ?? '') : ''
219
+ return `${stack}\n${message}`
220
+ }
221
+ return String(error)
222
+ }
223
+
224
+ function describeError(error: unknown): string {
225
+ if (error instanceof Error) {
226
+ const code = errorCode(error)
227
+ return `${error.name}: ${error.message}${code !== null ? ` (code=${code})` : ''}`
228
+ }
229
+ return String(error)
230
+ }
package/src/run/index.ts CHANGED
@@ -80,6 +80,7 @@ import { createTunnelManager, type TunnelManager, type TunnelManagerOptions } fr
80
80
  import { BUNDLED_PLUGINS } from './bundled-plugins'
81
81
  import { buildChannelSessionFactory } from './channel-session-factory'
82
82
  import { installCodexFetchObserver } from './codex-fetch-observer'
83
+ import { installFatalGuard } from './fatal-guard'
83
84
  import { createPluginRuntime, type PluginRuntime, type PluginSubagentEntry } from './plugin-runtime'
84
85
 
85
86
  type BunServer = ReturnType<Server['start']>
@@ -124,19 +125,44 @@ export type StartAgentResult = {
124
125
  stop: () => void | Promise<void>
125
126
  }
126
127
 
127
- export async function startAgent({
128
- port,
129
- attachTui,
130
- initialPrompt,
131
- cwd = process.cwd(),
132
- createTui = createTuiDefault,
133
- loadCron = loadCronDefault,
134
- createSchedulerFor,
135
- sessionFactory = createSessionFactory({ agentDir: cwd }),
136
- stream = createStream(),
137
- createChannelManager: createChannelManagerFor = createChannelManager,
138
- createTunnelManager: createTunnelManagerFor = createTunnelManager,
139
- }: StartAgentOptions): Promise<StartAgentResult> {
128
+ // Thin wrapper that owns ONLY the boot-failure cleanup of process-global
129
+ // installs. `installCodexFetchObserver` and `installFatalGuard` attach
130
+ // process-wide listeners before the fallible boot work; if any boot step throws
131
+ // before `startAgentRuntime` returns, the caller never receives a
132
+ // `StartAgentResult` and can never call `stop()`, so those listeners would
133
+ // strand and double-fire into the next `startAgent`. The runtime hands its
134
+ // disposer back via `onProcessGlobalsInstalled`; on a boot throw we dispose and
135
+ // rethrow, on success ownership transfers to the returned `stop()`. `return
136
+ // await` is load-bearing — without it an async boot rejection would escape this
137
+ // try. Dispose is idempotent, so the success path's `stop()` never double-fires.
138
+ export async function startAgent(options: StartAgentOptions): Promise<StartAgentResult> {
139
+ const captured: { dispose: (() => void) | null } = { dispose: null }
140
+ try {
141
+ return await startAgentRuntime(options, (dispose) => {
142
+ captured.dispose = dispose
143
+ })
144
+ } catch (err) {
145
+ captured.dispose?.()
146
+ throw err
147
+ }
148
+ }
149
+
150
+ async function startAgentRuntime(
151
+ {
152
+ port,
153
+ attachTui,
154
+ initialPrompt,
155
+ cwd = process.cwd(),
156
+ createTui = createTuiDefault,
157
+ loadCron = loadCronDefault,
158
+ createSchedulerFor,
159
+ sessionFactory = createSessionFactory({ agentDir: cwd }),
160
+ stream = createStream(),
161
+ createChannelManager: createChannelManagerFor = createChannelManager,
162
+ createTunnelManager: createTunnelManagerFor = createTunnelManager,
163
+ }: StartAgentOptions,
164
+ onProcessGlobalsInstalled: (dispose: () => void) => void,
165
+ ): Promise<StartAgentResult> {
140
166
  const reloadRegistry = new ReloadRegistry()
141
167
 
142
168
  // Wrap globalThis.fetch BEFORE any plugin/session/manager construction so
@@ -157,6 +183,37 @@ export async function startAgent({
157
183
  const tuiToken = process.env.TYPECLAW_TUI_TOKEN
158
184
  const tuiTokenOpt = tuiToken !== undefined && tuiToken !== '' ? { tuiToken } : {}
159
185
 
186
+ // Install the crash guard FIRST, before any plugin/channel/session
187
+ // construction, so an `unhandledRejection` escaping a channel SDK during boot
188
+ // or steady-state cannot terminate the container. Restart goes through the
189
+ // host daemon only when there is a container to bounce; outside Docker the
190
+ // guard logs and continues degraded (requestContainerRestart returns ok=false
191
+ // when the hostd control endpoint is absent, never throws).
192
+ const fatalGuard = installFatalGuard({
193
+ ...(containerName !== undefined
194
+ ? {
195
+ requestRestart: async (reason: string) => {
196
+ console.warn(`[fatal-guard] requesting container restart: ${reason}`)
197
+ const result = await requestContainerRestart({ containerName })
198
+ return result.ok ? { ok: true } : { ok: false, reason: result.reason }
199
+ },
200
+ }
201
+ : {}),
202
+ onDegrade: (scope, reason) => console.warn(`[fatal-guard] ${scope} degraded: ${reason}`),
203
+ })
204
+
205
+ // Both process-global disposers are surrendered to the wrapper as one unit the
206
+ // instant they exist, so a throw anywhere below detaches them; `stop()` calls
207
+ // the same disposer on the success path.
208
+ let processGlobalsDisposed = false
209
+ const disposeProcessGlobals = (): void => {
210
+ if (processGlobalsDisposed) return
211
+ processGlobalsDisposed = true
212
+ uninstallCodexFetchObserver()
213
+ fatalGuard.dispose()
214
+ }
215
+ onProcessGlobalsInstalled(disposeProcessGlobals)
216
+
160
217
  const { config: cwdConfig, pluginConfigs: pluginConfigsByName } = loadConfigBundleSync(cwd)
161
218
  // Vector agents omit the system-prompt `# Memory` section and inject memory
162
219
  // per-turn instead. Derived once here: `memory.vector.enabled` is
@@ -875,19 +932,26 @@ export async function startAgent({
875
932
  const stop = async () => {
876
933
  if (stopped) return
877
934
  stopped = true
878
- scheduler?.stop()
879
- cronConsumer.stop()
880
- subagentConsumer.stop()
881
- server.stop(true)
882
- void disposeMaterializedSkills(pluginRuntime)
883
- tunnelBridge.stop()
884
- subagentCompletionBridge.stop()
885
- prVerdictActivityBridge.stop()
886
- setReviewObserver(null)
887
- await tunnelManager.stop()
888
- await channelManager.stop()
889
- await mcpManager?.closeAll()
890
- uninstallCodexFetchObserver()
935
+ // The crash-guard and codex-observer disposers run in `finally` so an
936
+ // earlier async teardown rejection (tunnel/channel/mcp stop) cannot strand
937
+ // the process-global listeners they removed — a stranded fatal-guard
938
+ // listener would survive into the next `startAgent` and double-fire.
939
+ try {
940
+ scheduler?.stop()
941
+ cronConsumer.stop()
942
+ subagentConsumer.stop()
943
+ server.stop(true)
944
+ void disposeMaterializedSkills(pluginRuntime)
945
+ tunnelBridge.stop()
946
+ subagentCompletionBridge.stop()
947
+ prVerdictActivityBridge.stop()
948
+ setReviewObserver(null)
949
+ await tunnelManager.stop()
950
+ await channelManager.stop()
951
+ await mcpManager?.closeAll()
952
+ } finally {
953
+ disposeProcessGlobals()
954
+ }
891
955
  }
892
956
 
893
957
  if (!attachTui) {