typeclaw 0.47.2 → 0.48.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +1 -2
  3. package/src/agent/loop-guard.ts +71 -41
  4. package/src/agent/plugin-tools.ts +167 -50
  5. package/src/agent/system-prompt.ts +1 -1
  6. package/src/agent/turn-runner.ts +12 -2
  7. package/src/bundled-plugins/agent-browser/index.ts +0 -38
  8. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
  9. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
  10. package/src/bundled-plugins/memory/append-tool.ts +75 -2
  11. package/src/bundled-plugins/memory/frontmatter.ts +13 -2
  12. package/src/bundled-plugins/memory/load-memory.ts +1 -1
  13. package/src/bundled-plugins/memory/memory-logger.ts +5 -1
  14. package/src/bundled-plugins/memory/secret-detector.ts +7 -0
  15. package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
  16. package/src/bundled-plugins/memory/vector/passages.ts +5 -1
  17. package/src/bundled-plugins/security/index.ts +148 -98
  18. package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
  19. package/src/channels/adapters/discord-bot-edit.ts +3 -5
  20. package/src/channels/adapters/discord-bot-reactions.ts +4 -6
  21. package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
  22. package/src/channels/adapters/discord-bot.ts +20 -23
  23. package/src/channels/adapters/discord-edit.ts +3 -5
  24. package/src/channels/adapters/discord-reactions.ts +4 -6
  25. package/src/channels/adapters/discord.ts +1 -1
  26. package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
  27. package/src/channels/adapters/github/history.ts +2 -1
  28. package/src/channels/adapters/github/inbound.ts +4 -11
  29. package/src/channels/adapters/github/index.ts +6 -9
  30. package/src/channels/adapters/github/outbound.ts +3 -6
  31. package/src/channels/adapters/github/reactions.ts +3 -2
  32. package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
  33. package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
  34. package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
  35. package/src/channels/adapters/github/review-state.ts +3 -2
  36. package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
  37. package/src/channels/adapters/github/webhook-register.ts +5 -8
  38. package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
  39. package/src/channels/adapters/instagram.ts +1 -1
  40. package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
  41. package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
  42. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
  43. package/src/channels/adapters/kakaotalk-membership.ts +2 -5
  44. package/src/channels/adapters/kakaotalk-typing.ts +1 -1
  45. package/src/channels/adapters/kakaotalk.ts +1 -1
  46. package/src/channels/adapters/line-channel-resolver.ts +3 -5
  47. package/src/channels/adapters/line.ts +1 -1
  48. package/src/channels/adapters/slack-bot-edit.ts +1 -1
  49. package/src/channels/adapters/slack-bot-reactions.ts +4 -6
  50. package/src/channels/adapters/slack-bot.ts +8 -8
  51. package/src/channels/adapters/slack-edit.ts +3 -5
  52. package/src/channels/adapters/slack-reactions.ts +4 -6
  53. package/src/channels/adapters/slack.ts +1 -1
  54. package/src/channels/adapters/teams-edit.ts +2 -5
  55. package/src/channels/adapters/teams.ts +1 -1
  56. package/src/channels/adapters/telegram-bot-edit.ts +4 -7
  57. package/src/channels/adapters/telegram-bot.ts +1 -1
  58. package/src/channels/adapters/webex-bot.ts +1 -1
  59. package/src/channels/adapters/webex-edit.ts +3 -5
  60. package/src/channels/adapters/webex.ts +1 -1
  61. package/src/channels/github-review-claim.ts +89 -4
  62. package/src/channels/github-token-bridge.ts +2 -1
  63. package/src/channels/manager.ts +478 -64
  64. package/src/channels/membership-cache.ts +2 -5
  65. package/src/channels/persistence.ts +3 -6
  66. package/src/channels/reloadable.ts +23 -6
  67. package/src/channels/router.ts +134 -56
  68. package/src/channels/tunnel-bridge.ts +2 -1
  69. package/src/channels/types.ts +6 -3
  70. package/src/cli/hostd.ts +56 -28
  71. package/src/config/config.ts +10 -0
  72. package/src/config/providers.ts +179 -0
  73. package/src/dependencies/bin-resolver.ts +88 -0
  74. package/src/dependencies/bins.ts +227 -0
  75. package/src/dependencies/index.ts +17 -0
  76. package/src/doctor/checks.ts +2 -0
  77. package/src/doctor/operational-incidents.ts +32 -0
  78. package/src/hostd/credential-rotation-apply.ts +94 -0
  79. package/src/init/models-dev.ts +17 -3
  80. package/src/init/validate-api-key.ts +26 -4
  81. package/src/operations/classify-tool-outcome.ts +151 -0
  82. package/src/operations/incidents.ts +274 -0
  83. package/src/operations/index.ts +3 -0
  84. package/src/operations/remediations.ts +41 -0
  85. package/src/reload/client.ts +8 -2
  86. package/src/reload/docker-exec-client.ts +10 -2
  87. package/src/reload/index.ts +1 -1
  88. package/src/reload/recover.ts +5 -3
  89. package/src/reload/registry.ts +5 -5
  90. package/src/reload/types.ts +9 -1
  91. package/src/run/index.ts +5 -0
  92. package/src/sandbox/dependency-bins.ts +125 -0
  93. package/src/sandbox/errors.ts +32 -0
  94. package/src/sandbox/hidden-paths.ts +4 -1
  95. package/src/sandbox/index.ts +8 -0
  96. package/src/sandbox/policy.ts +1 -1
  97. package/src/sandbox/privileged-runtime.ts +88 -7
  98. package/src/sandbox/runtime-private.ts +4 -0
  99. package/src/sandbox/writable-zones.ts +4 -4
  100. package/src/server/index.ts +7 -5
  101. package/src/shared/protocol.ts +6 -1
  102. package/typeclaw.schema.json +35 -5
  103. package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
  104. package/src/bundled-plugins/agent-browser/shim.ts +0 -108
  105. /package/src/channels/{adapters/describe-error.ts → describe-error.ts} +0 -0
@@ -0,0 +1,32 @@
1
+ import { readIncidentLedger } from '@/operations'
2
+
3
+ import type { DoctorCheck } from './types'
4
+
5
+ export function buildOperationalIncidentChecks(): DoctorCheck[] {
6
+ return [
7
+ {
8
+ name: 'operations.incidents',
9
+ category: 'operations',
10
+ description: 'deterministic operational incidents are resolved',
11
+ applies: (ctx) => ctx.hasAgentFolder,
12
+ async run(ctx) {
13
+ const ledger = await readIncidentLedger(ctx.cwd)
14
+ const unresolved = ledger.incidents.filter((incident) => incident.status === 'unresolved')
15
+ if (unresolved.length === 0) return { status: 'ok', message: 'no unresolved operational incidents' }
16
+ const recurrent = unresolved.filter((incident) => incident.recurrent)
17
+ return {
18
+ status: recurrent.length > 0 ? 'error' : 'warning',
19
+ message:
20
+ recurrent.length > 0
21
+ ? `${recurrent.length} recurrent TypeClaw environment issue(s) require operator repair`
22
+ : `${unresolved.length} unresolved operational incident(s)`,
23
+ details: unresolved.map(
24
+ (incident) =>
25
+ `${incident.fingerprint} count=${incident.count} first=${incident.firstSeenAt} last=${incident.lastSeenAt}`,
26
+ ),
27
+ fix: { description: 'Repair the TypeClaw environment defect, then retry the failed operation.' },
28
+ }
29
+ },
30
+ },
31
+ ]
32
+ }
@@ -0,0 +1,94 @@
1
+ import type { requestReloadWithFallback as RequestReloadWithFallback, ReloadResult } from '@/reload'
2
+
3
+ export type RenewableAdapter = 'kakaotalk' | 'webex' | 'teams'
4
+
5
+ export type CredentialRotationApplyInput = {
6
+ containerName: string
7
+ cwd: string
8
+ adapter: RenewableAdapter
9
+ }
10
+
11
+ export type CredentialRotationApplyDeps = {
12
+ resolveHostPort: (options: { cwd: string }) => Promise<number>
13
+ resolveTuiToken: (options: { cwd: string }) => Promise<string | null>
14
+ requestReloadWithFallback: typeof RequestReloadWithFallback
15
+ restartContainer: (input: { containerName: string; cwd: string }) => Promise<{ ok: boolean; reason?: string }>
16
+ timeoutMs?: number
17
+ }
18
+
19
+ export type CredentialRotationApplyResult =
20
+ | { kind: 'reloaded'; transport: 'host' | 'container-local' }
21
+ | { kind: 'restarted'; reloadError: string }
22
+ | { kind: 'failed'; reloadError: string; restartError: string }
23
+
24
+ const DEFAULT_TIMEOUT_MS = 30_000
25
+
26
+ // Applying a renewed credential used to stop, remove and recreate the whole
27
+ // container, which killed every in-flight session, cron job and subagent on
28
+ // every OTHER channel too. Teams tokens expire every ~6h, so that fired ~4x a
29
+ // day. Bounce just the one adapter over the existing reload transport instead,
30
+ // and keep the container restart only as the fallback for when neither
31
+ // transport can reach the container at all.
32
+ export async function applyCredentialRotation(
33
+ input: CredentialRotationApplyInput,
34
+ deps: CredentialRotationApplyDeps,
35
+ ): Promise<CredentialRotationApplyResult> {
36
+ const reload = await requestAdapterReload(input, deps)
37
+ if (reload.error === null) return { kind: 'reloaded', transport: reload.transport }
38
+
39
+ const restart = await deps.restartContainer({ containerName: input.containerName, cwd: input.cwd })
40
+ if (restart.ok) return { kind: 'restarted', reloadError: reload.error }
41
+ return { kind: 'failed', reloadError: reload.error, restartError: restart.reason ?? 'restart failed' }
42
+ }
43
+
44
+ type AdapterReloadAttempt = { transport: 'host' | 'container-local'; error: string | null }
45
+
46
+ async function requestAdapterReload(
47
+ { cwd, adapter }: CredentialRotationApplyInput,
48
+ deps: CredentialRotationApplyDeps,
49
+ ): Promise<AdapterReloadAttempt> {
50
+ try {
51
+ const port = await deps.resolveHostPort({ cwd })
52
+ const token = await deps.resolveTuiToken({ cwd })
53
+ const url = new URL(`ws://127.0.0.1:${port}`)
54
+ if (token !== null) url.searchParams.set('token', token)
55
+
56
+ const response = await deps.requestReloadWithFallback({
57
+ url: url.toString(),
58
+ cwd,
59
+ token,
60
+ scope: 'channels',
61
+ cause: { kind: 'credential-rotation', adapter },
62
+ timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
63
+ })
64
+ return { transport: response.transport, error: describeUnapplied(response.results, adapter) }
65
+ } catch (err) {
66
+ return { transport: 'host', error: err instanceof Error ? err.message : String(err) }
67
+ }
68
+ }
69
+
70
+ // Only `stop-failed` warrants the fallback: the adapter is still live on the
71
+ // superseded credential, so nothing was applied. Every other outcome means the
72
+ // rotation landed or is landing — including `recovery-pending`, where the
73
+ // adapter is already down holding no stale token and supervision is retrying it
74
+ // on backoff. Recreating the container cannot fix a credential the platform
75
+ // rejected, so falling back there would destroy unrelated work for nothing.
76
+ function describeUnapplied(results: ReloadResult[], adapter: RenewableAdapter): string | null {
77
+ const channels = results.find((result) => result.scope === 'channels')
78
+ if (channels === undefined) return 'channels scope missing from reload result'
79
+ if (!channels.ok) return channels.reason
80
+
81
+ const applied = readCredentialApply(channels.details)
82
+ if (applied === null || applied.adapter !== adapter) return `reload did not apply the ${adapter} credential`
83
+ if (applied.outcome === 'stop-failed') return `${adapter} adapter could not be stopped to apply the credential`
84
+ return null
85
+ }
86
+
87
+ function readCredentialApply(details: unknown): { adapter: string; outcome: string } | null {
88
+ if (typeof details !== 'object' || details === null) return null
89
+ const candidate = (details as { credentialApply?: unknown }).credentialApply
90
+ if (typeof candidate !== 'object' || candidate === null) return null
91
+ const { adapter, outcome } = candidate as { adapter?: unknown; outcome?: unknown }
92
+ if (typeof adapter !== 'string' || typeof outcome !== 'string') return null
93
+ return { adapter, outcome }
94
+ }
@@ -16,7 +16,11 @@ const REQUEST_TIMEOUT_MS = 10_000
16
16
  // KnownProviderId. Specifically, they ship Fireworks under `fireworks-ai`.
17
17
  // This map is the single place that bridges the two namespaces; every other
18
18
  // helper in this file works in OUR namespace.
19
- const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
19
+ // `null` means "never merge upstream models into this provider". Reserved for
20
+ // gateways whose ids are creator-qualified: models.dev lists bare ids like
21
+ // `gpt-5.5`, but OpenGateway only accepts `openai/gpt-5.5`, so merging would
22
+ // synthesize refs that pass `isModelRef()` and then 404 at request time.
23
+ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string | null> = {
20
24
  openai: 'openai',
21
25
  // openai-codex models live under the `openai` namespace on models.dev too
22
26
  // (Codex is a backend, not a separate provider in their taxonomy). Curated
@@ -42,6 +46,16 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
42
46
  // metadata under `moonshot`, so we route lookups there; the curated
43
47
  // `kimi-for-coding` alias is surfaced regardless of upstream membership.
44
48
  'moonshot-coding': 'moonshot',
49
+ opengateway: null,
50
+ }
51
+
52
+ function upstreamProviderFor(
53
+ data: Record<string, ModelsDevProvider>,
54
+ providerId: KnownProviderId,
55
+ ): ModelsDevProvider | undefined {
56
+ const modelsDevId = PROVIDER_TO_MODELS_DEV[providerId]
57
+ if (modelsDevId === null) return undefined
58
+ return data[modelsDevId]
45
59
  }
46
60
 
47
61
  export type ModelOption = {
@@ -156,7 +170,7 @@ function mergeWithCurated(data: Record<string, ModelsDevProvider>): ModelOption[
156
170
  const seen = new Set<string>()
157
171
  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
158
172
  const known = KNOWN_PROVIDERS[providerId]
159
- const upstream = data[PROVIDER_TO_MODELS_DEV[providerId]]
173
+ const upstream = upstreamProviderFor(data, providerId)
160
174
  const upstreamModels = upstream?.models ?? {}
161
175
  for (const modelId of Object.keys(known.models)) {
162
176
  const upstreamModel = upstreamModels[modelId]
@@ -167,7 +181,7 @@ function mergeWithCurated(data: Record<string, ModelsDevProvider>): ModelOption[
167
181
  }
168
182
 
169
183
  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
170
- const upstream = data[PROVIDER_TO_MODELS_DEV[providerId]]
184
+ const upstream = upstreamProviderFor(data, providerId)
171
185
  const upstreamModels = upstream?.models ?? {}
172
186
  for (const [fallbackModelId, upstreamModel] of Object.entries(upstreamModels)) {
173
187
  const modelId = upstreamModel.id ?? fallbackModelId
@@ -1,7 +1,20 @@
1
1
  import { effectiveBaseUrl } from '@/agent/model-overrides'
2
2
  import { KNOWN_PROVIDERS, type KnownProviderId } from '@/config/providers'
3
3
 
4
- const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader: 'bearer' | 'x-api-key' }>> = {
4
+ // `successShape` is what a 200 must look like to count as a validated key.
5
+ // Default `models-list` requires `{ data: [...] }`, which every /v1/models probe
6
+ // below returns. `json-object` is the weaker check for probes that answer with a
7
+ // bare object instead of a list — it still rejects the captive-portal HTML case
8
+ // that motivated shape-checking in the first place.
9
+ type ProbeSuccessShape = 'models-list' | 'json-object'
10
+
11
+ type Probe = {
12
+ url: string
13
+ authHeader: 'bearer' | 'x-api-key'
14
+ successShape?: ProbeSuccessShape
15
+ }
16
+
17
+ const PROVIDER_PROBE: Partial<Record<KnownProviderId, Probe>> = {
5
18
  openai: { url: 'https://api.openai.com/v1/models', authHeader: 'bearer' },
6
19
  anthropic: { url: 'https://api.anthropic.com/v1/models', authHeader: 'x-api-key' },
7
20
  fireworks: { url: 'https://api.fireworks.ai/inference/v1/models', authHeader: 'bearer' },
@@ -13,6 +26,12 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
13
26
  upstage: { url: 'https://api.upstage.ai/v1/models', authHeader: 'bearer' },
14
27
  moonshot: { url: 'https://api.moonshot.ai/v1/models', authHeader: 'bearer' },
15
28
  'moonshot-coding': { url: 'https://api.kimi.com/coding/v1/models', authHeader: 'bearer' },
29
+ // NOT /v1/models: OpenGateway serves its catalog PUBLICLY (verified — HTTP 200
30
+ // with `{data:[...]}` for a missing key and for a garbage key), so probing it
31
+ // would hand back `ok` for any string the user pastes. That is worse than no
32
+ // validation, because init would vouch for a key that cannot complete a single
33
+ // request. /v1/me is the cheapest endpoint that actually 401s on a bad key.
34
+ opengateway: { url: 'https://apis.opengateway.ai/v1/me', authHeader: 'bearer', successShape: 'json-object' },
16
35
  }
17
36
 
18
37
  // When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
@@ -75,7 +94,7 @@ export async function validateApiKey(
75
94
  // Treat the response as "ok" only if it parses as the expected
76
95
  // JSON shape (`{ data: [...] }` for /v1/models on every probed
77
96
  // provider).
78
- const shapeOk = await isModelsListShape(res)
97
+ const shapeOk = await hasExpectedShape(res, probe.successShape ?? 'models-list')
79
98
  if (shapeOk) return { kind: 'ok' }
80
99
  return { kind: 'skipped', reason: 'network-error', detail: 'unexpected response shape' }
81
100
  }
@@ -125,12 +144,14 @@ function isFireworksFirePassForbidden(body: string): boolean {
125
144
  }
126
145
  }
127
146
 
128
- async function isModelsListShape(res: Response): Promise<boolean> {
147
+ async function hasExpectedShape(res: Response, shape: ProbeSuccessShape): Promise<boolean> {
129
148
  const text = await readCapped(res, MAX_BODY_BYTES)
130
149
  if (text === null) return false
131
150
  try {
132
151
  const parsed = JSON.parse(text) as unknown
133
- return typeof parsed === 'object' && parsed !== null && Array.isArray((parsed as { data?: unknown }).data)
152
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return false
153
+ if (shape === 'json-object') return true
154
+ return Array.isArray((parsed as { data?: unknown }).data)
134
155
  } catch {
135
156
  return false
136
157
  }
@@ -172,6 +193,7 @@ export const API_KEY_DASHBOARD_URL: Partial<Record<KnownProviderId, string>> = {
172
193
  upstage: 'https://console.upstage.ai/api-keys',
173
194
  moonshot: 'https://platform.moonshot.ai/console/api-keys',
174
195
  'moonshot-coding': 'https://www.kimi.com/code/console',
196
+ opengateway: 'https://opengateway.ai/docs/reference/guides/authentication',
175
197
  }
176
198
 
177
199
  // MiniMax sells the same `minimax` provider under two billing surfaces that
@@ -0,0 +1,151 @@
1
+ import { isSecretShapedToken } from '@/bundled-plugins/memory/secret-detector'
2
+
3
+ export type OperationalIncidentFact =
4
+ | { kind: 'bash-command-not-found'; bin: string }
5
+ | { kind: 'declared-skill-bin-unresolved'; bin: string }
6
+ | { kind: 'sandbox-proc-unavailable' }
7
+
8
+ export type OperationalIncidentResolutionSignal = 'successful-bin' | 'successful-sandbox-real-proc'
9
+
10
+ export type OperationalIncidentSuccessInput = {
11
+ tool: string
12
+ args: Record<string, unknown>
13
+ sandboxedRealProcSucceeded: boolean
14
+ }
15
+
16
+ export const OPERATIONAL_INCIDENT_RESOLUTION_SIGNAL_BY_KIND = {
17
+ 'bash-command-not-found': 'successful-bin',
18
+ 'declared-skill-bin-unresolved': 'successful-bin',
19
+ 'sandbox-proc-unavailable': 'successful-sandbox-real-proc',
20
+ } as const satisfies Record<OperationalIncidentFact['kind'], OperationalIncidentResolutionSignal>
21
+
22
+ export class DeclaredSkillBinUnresolvedError extends Error {
23
+ override readonly name = 'DeclaredSkillBinUnresolvedError'
24
+
25
+ constructor(readonly bin: string) {
26
+ super(`declared skill bin could not be resolved: ${bin}`)
27
+ }
28
+ }
29
+
30
+ const SAFE_BIN = '[A-Za-z0-9][A-Za-z0-9._+-]{0,127}'
31
+ const COMMAND_NOT_FOUND = new RegExp(
32
+ `^(?:/bin/bash: |bash: line [1-9][0-9]{0,5}: )(${SAFE_BIN}): command not found\\n(?:\\n){1,2}Command exited with code 127$`,
33
+ )
34
+
35
+ export function classifyToolOutcome(input: { tool: string; error: unknown }): OperationalIncidentFact | null {
36
+ if (input.error instanceof DeclaredSkillBinUnresolvedError && isSafeBin(input.error.bin)) {
37
+ return { kind: 'declared-skill-bin-unresolved', bin: input.error.bin }
38
+ }
39
+ if (input.tool !== 'bash' || !(input.error instanceof Error)) return null
40
+ if (input.error.name === 'SandboxDegradedProcError') return { kind: 'sandbox-proc-unavailable' }
41
+
42
+ const match = COMMAND_NOT_FOUND.exec(input.error.message)
43
+ const bin = match?.[1]
44
+ return bin === undefined ? null : bashCommandNotFoundFact(bin)
45
+ }
46
+
47
+ export function deriveOperationalIncidentFactsForSuccess(
48
+ input: OperationalIncidentSuccessInput,
49
+ ): OperationalIncidentFact[] {
50
+ if (input.tool !== 'bash') return []
51
+ const command = input.args.command
52
+ if (typeof command !== 'string') return []
53
+ // False resolution hides a live defect; under-resolution only leaves a visible stale warning.
54
+ // Accept only syntax where aggregate exit zero proves this exact invocation succeeded.
55
+ const commandWord = parseSingleUnconditionalInvocation(command)
56
+ if (commandWord === null) return []
57
+
58
+ const facts = successfulBinFacts(commandWord)
59
+ if (input.sandboxedRealProcSucceeded) facts.push({ kind: 'sandbox-proc-unavailable' })
60
+ return facts
61
+ }
62
+
63
+ function bashCommandNotFoundFact(bin: string): OperationalIncidentFact | null {
64
+ return isSafeBin(bin) ? { kind: 'bash-command-not-found', bin } : null
65
+ }
66
+
67
+ function successfulBinFacts(bin: string): OperationalIncidentFact[] {
68
+ if (!isSafeBin(bin)) return []
69
+ return [
70
+ { kind: 'bash-command-not-found', bin },
71
+ { kind: 'declared-skill-bin-unresolved', bin },
72
+ ]
73
+ }
74
+
75
+ function isSafeBin(bin: string): boolean {
76
+ return new RegExp(`^${SAFE_BIN}$`).test(bin) && !isSecretShapedToken(bin)
77
+ }
78
+
79
+ const SHELL_CONSTRUCTS = new Set([
80
+ '!',
81
+ 'case',
82
+ 'coproc',
83
+ 'do',
84
+ 'done',
85
+ 'elif',
86
+ 'else',
87
+ 'esac',
88
+ 'fi',
89
+ 'for',
90
+ 'function',
91
+ 'if',
92
+ 'in',
93
+ 'select',
94
+ 'then',
95
+ 'time',
96
+ 'until',
97
+ 'while',
98
+ ])
99
+
100
+ function parseSingleUnconditionalInvocation(command: string): string | null {
101
+ const words: string[] = []
102
+ let word = ''
103
+ let quote: '"' | "'" | null = null
104
+ let active = false
105
+ const endWord = (): void => {
106
+ if (!active) return
107
+ words.push(word)
108
+ word = ''
109
+ active = false
110
+ }
111
+
112
+ for (let i = 0; i < command.length; i++) {
113
+ const character = command[i]!
114
+ if (quote !== null) {
115
+ if (character === quote) {
116
+ quote = null
117
+ } else {
118
+ if (quote === '"' && (character === '`' || (character === '$' && command[i + 1] === '('))) return null
119
+ if (character === '\\' && quote === '"' && i + 1 < command.length) word += command[++i]
120
+ else word += character
121
+ }
122
+ active = true
123
+ continue
124
+ }
125
+ if (character === '"' || character === "'") {
126
+ quote = character
127
+ active = true
128
+ continue
129
+ }
130
+ if (character === '\\') {
131
+ if (i + 1 >= command.length) return null
132
+ word += command[++i]
133
+ active = true
134
+ continue
135
+ }
136
+ if (';&|<>\n\r()'.includes(character) || character === '`' || (character === '$' && command[i + 1] === '('))
137
+ return null
138
+ if (character === '#' && !active) return null
139
+ if (character === ' ' || character === '\t') {
140
+ endWord()
141
+ continue
142
+ }
143
+ word += character
144
+ active = true
145
+ }
146
+ if (quote !== null) return null
147
+ endWord()
148
+ const commandWord = words.find((candidate) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(candidate))
149
+ if (commandWord === undefined || SHELL_CONSTRUCTS.has(commandWord)) return null
150
+ return commandWord
151
+ }
@@ -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'