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.
- package/package.json +1 -1
- package/src/agent/attention-escalation.ts +11 -1
- package/src/agent/subagents.ts +6 -2
- package/src/agent/tools/channel-reply.ts +48 -3
- package/src/agent/tools/ddg.ts +40 -5
- package/src/agent/tools/keyed-semaphore.ts +114 -0
- package/src/agent/tools/search-retry.ts +82 -0
- package/src/bundled-plugins/explorer/explorer.ts +5 -0
- package/src/bundled-plugins/memory/README.md +2 -2
- package/src/bundled-plugins/memory/append-tool.ts +42 -4
- package/src/bundled-plugins/memory/memory-logger.ts +7 -3
- package/src/bundled-plugins/reviewer/reviewer.ts +3 -1
- package/src/bundled-plugins/scout/scout.ts +5 -0
- package/src/channels/adapters/github/permission-guidance.ts +18 -0
- package/src/channels/engagement.ts +17 -2
- package/src/cli/channel.ts +7 -11
- package/src/cli/init.ts +2 -2
- package/src/cli/plugin-commands-dispatch.ts +7 -1
- package/src/cli/ui.ts +32 -22
- package/src/inspect/index.ts +2 -3
- package/src/run/codex-fetch-observer.ts +26 -10
- package/src/run/fatal-guard.ts +230 -0
- package/src/run/index.ts +90 -26
- package/src/secrets/oauth-xai.ts +8 -2
- package/src/secrets/webex-renewal.ts +3 -0
- package/src/skills/typeclaw-channel-github/SKILL.md +59 -13
|
@@ -22,11 +22,22 @@ export class StickyLedger {
|
|
|
22
22
|
inner.set(authorId, expiresAt)
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
-
|
|
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 (
|
|
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
|
|
package/src/cli/channel.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
'
|
|
1201
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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' | '
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
//
|
|
20
|
-
//
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
|
package/src/inspect/index.ts
CHANGED
|
@@ -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
|
|
89
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
344
|
-
return installed.
|
|
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
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
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) {
|