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.
- package/package.json +1 -1
- package/src/agent/index.ts +1 -2
- package/src/agent/loop-guard.ts +71 -41
- package/src/agent/plugin-tools.ts +167 -50
- package/src/agent/system-prompt.ts +1 -1
- package/src/agent/turn-runner.ts +12 -2
- package/src/bundled-plugins/agent-browser/index.ts +0 -38
- package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
- package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
- package/src/bundled-plugins/memory/append-tool.ts +75 -2
- package/src/bundled-plugins/memory/frontmatter.ts +13 -2
- package/src/bundled-plugins/memory/load-memory.ts +1 -1
- package/src/bundled-plugins/memory/memory-logger.ts +5 -1
- package/src/bundled-plugins/memory/secret-detector.ts +7 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
- package/src/bundled-plugins/memory/vector/passages.ts +5 -1
- package/src/bundled-plugins/security/index.ts +148 -98
- package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
- package/src/channels/adapters/discord-bot-edit.ts +3 -5
- package/src/channels/adapters/discord-bot-reactions.ts +4 -6
- package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
- package/src/channels/adapters/discord-bot.ts +20 -23
- package/src/channels/adapters/discord-edit.ts +3 -5
- package/src/channels/adapters/discord-reactions.ts +4 -6
- package/src/channels/adapters/discord.ts +1 -1
- package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
- package/src/channels/adapters/github/history.ts +2 -1
- package/src/channels/adapters/github/inbound.ts +4 -11
- package/src/channels/adapters/github/index.ts +6 -9
- package/src/channels/adapters/github/outbound.ts +3 -6
- package/src/channels/adapters/github/reactions.ts +3 -2
- package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
- package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
- package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
- package/src/channels/adapters/github/review-state.ts +3 -2
- package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
- package/src/channels/adapters/github/webhook-register.ts +5 -8
- package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
- package/src/channels/adapters/instagram.ts +1 -1
- package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
- package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
- package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
- package/src/channels/adapters/kakaotalk-membership.ts +2 -5
- package/src/channels/adapters/kakaotalk-typing.ts +1 -1
- package/src/channels/adapters/kakaotalk.ts +1 -1
- package/src/channels/adapters/line-channel-resolver.ts +3 -5
- package/src/channels/adapters/line.ts +1 -1
- package/src/channels/adapters/slack-bot-edit.ts +1 -1
- package/src/channels/adapters/slack-bot-reactions.ts +4 -6
- package/src/channels/adapters/slack-bot.ts +8 -8
- package/src/channels/adapters/slack-edit.ts +3 -5
- package/src/channels/adapters/slack-reactions.ts +4 -6
- package/src/channels/adapters/slack.ts +1 -1
- package/src/channels/adapters/teams-edit.ts +2 -5
- package/src/channels/adapters/teams.ts +1 -1
- package/src/channels/adapters/telegram-bot-edit.ts +4 -7
- package/src/channels/adapters/telegram-bot.ts +1 -1
- package/src/channels/adapters/webex-bot.ts +1 -1
- package/src/channels/adapters/webex-edit.ts +3 -5
- package/src/channels/adapters/webex.ts +1 -1
- package/src/channels/github-review-claim.ts +89 -4
- package/src/channels/github-token-bridge.ts +2 -1
- package/src/channels/manager.ts +478 -64
- package/src/channels/membership-cache.ts +2 -5
- package/src/channels/persistence.ts +3 -6
- package/src/channels/reloadable.ts +23 -6
- package/src/channels/router.ts +134 -56
- package/src/channels/tunnel-bridge.ts +2 -1
- package/src/channels/types.ts +6 -3
- package/src/cli/hostd.ts +56 -28
- package/src/config/config.ts +10 -0
- package/src/config/providers.ts +179 -0
- package/src/dependencies/bin-resolver.ts +88 -0
- package/src/dependencies/bins.ts +227 -0
- package/src/dependencies/index.ts +17 -0
- package/src/doctor/checks.ts +2 -0
- package/src/doctor/operational-incidents.ts +32 -0
- package/src/hostd/credential-rotation-apply.ts +94 -0
- package/src/init/models-dev.ts +17 -3
- package/src/init/validate-api-key.ts +26 -4
- package/src/operations/classify-tool-outcome.ts +151 -0
- package/src/operations/incidents.ts +274 -0
- package/src/operations/index.ts +3 -0
- package/src/operations/remediations.ts +41 -0
- package/src/reload/client.ts +8 -2
- package/src/reload/docker-exec-client.ts +10 -2
- package/src/reload/index.ts +1 -1
- package/src/reload/recover.ts +5 -3
- package/src/reload/registry.ts +5 -5
- package/src/reload/types.ts +9 -1
- package/src/run/index.ts +5 -0
- package/src/sandbox/dependency-bins.ts +125 -0
- package/src/sandbox/errors.ts +32 -0
- package/src/sandbox/hidden-paths.ts +4 -1
- package/src/sandbox/index.ts +8 -0
- package/src/sandbox/policy.ts +1 -1
- package/src/sandbox/privileged-runtime.ts +88 -7
- package/src/sandbox/runtime-private.ts +4 -0
- package/src/sandbox/writable-zones.ts +4 -4
- package/src/server/index.ts +7 -5
- package/src/shared/protocol.ts +6 -1
- package/typeclaw.schema.json +35 -5
- package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
- package/src/bundled-plugins/agent-browser/shim.ts +0 -108
- /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
|
+
}
|
package/src/init/models-dev.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
+
}
|