typeclaw 0.39.3 → 0.39.4
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 +10 -14
- package/src/agent/model-fallback.ts +13 -4
- package/src/agent/provider-error.ts +36 -1
- package/src/agent/subagents.ts +29 -2
- package/src/agent/throttle-circuit.ts +50 -0
- package/src/agent/turn-runner.ts +162 -0
- package/src/bundled-plugins/memory/README.md +12 -12
- package/src/bundled-plugins/memory/append-tool.ts +58 -6
- package/src/bundled-plugins/memory/dreaming.ts +1 -1
- package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
- package/src/bundled-plugins/memory/load-memory.ts +28 -2
- package/src/bundled-plugins/memory/memory-logger.ts +14 -2
- package/src/bundled-plugins/memory/search-tool.ts +50 -7
- package/src/bundled-plugins/memory/stream-events.ts +23 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
- package/src/bundled-plugins/security/index.ts +24 -1
- package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
- package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
- package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
- package/src/channels/adapters/webex-bot.ts +26 -25
- package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
- package/src/channels/adapters/webex.ts +27 -30
- package/src/channels/manager.ts +64 -57
- package/src/channels/router.ts +134 -4
- package/src/channels/types.ts +8 -1
- package/src/cli/builtins.ts +6 -32
- package/src/cli/command-meta.ts +93 -0
- package/src/cli/help.ts +24 -0
- package/src/cli/index.ts +34 -10
- package/src/config/config.ts +27 -1
- package/src/container/start.ts +22 -2
- package/src/hostd/daemon.ts +55 -26
- package/src/hostd/spawn.ts +53 -19
- package/src/permissions/permissions.ts +12 -0
- package/src/run/codex-fetch-observer.ts +11 -6
- package/src/secrets/oauth-xai.ts +2 -2
- package/src/server/index.ts +27 -2
- package/src/skills/typeclaw-channels/SKILL.md +1 -1
- package/src/skills/typeclaw-config/SKILL.md +1 -0
- package/src/skills/typeclaw-cron/SKILL.md +9 -4
- package/src/skills/typeclaw-permissions/SKILL.md +18 -6
package/package.json
CHANGED
package/src/agent/index.ts
CHANGED
|
@@ -244,26 +244,22 @@ export type CreateSessionResult = {
|
|
|
244
244
|
}
|
|
245
245
|
|
|
246
246
|
// A session's reasoning effort layers like the model does: the resolved
|
|
247
|
-
// profile's own `thinkingLevel` → the
|
|
248
|
-
//
|
|
249
|
-
//
|
|
250
|
-
//
|
|
251
|
-
// still does the right thing.
|
|
247
|
+
// profile's own `thinkingLevel` → the `default` profile's `thinkingLevel` (the
|
|
248
|
+
// de-facto global default) → the per-provider/SDK default for the active ref.
|
|
249
|
+
// When the requested profile was unknown, `resolved` is already the `default`
|
|
250
|
+
// profile, so those terms coincide and the expression still does the right thing.
|
|
252
251
|
//
|
|
253
|
-
//
|
|
254
|
-
//
|
|
255
|
-
//
|
|
256
|
-
//
|
|
257
|
-
//
|
|
258
|
-
const DEEP_PROFILE_DEFAULT_THINKING_LEVEL: ThinkingLevel = 'high'
|
|
259
|
-
|
|
252
|
+
// Built-in per-profile defaults (e.g. `fast: 'low'`, `deep: 'high'`) are
|
|
253
|
+
// materialized onto the entry at config-parse time (see PROFILE_THINKING_LEVEL_DEFAULTS
|
|
254
|
+
// in config.ts), so they arrive here as `resolved.thinkingLevel` — the first term.
|
|
255
|
+
// That is why `deep`'s `high` still beats a lowered global default, and why there
|
|
256
|
+
// is no profile special-casing in this function.
|
|
260
257
|
export function resolveSessionThinkingLevel(
|
|
261
258
|
models: Models,
|
|
262
259
|
resolved: Pick<ResolvedProfile, 'thinkingLevel' | 'profile'>,
|
|
263
260
|
activeRef: ModelRef,
|
|
264
261
|
): ThinkingLevel | undefined {
|
|
265
|
-
|
|
266
|
-
return resolved.thinkingLevel ?? deepDefault ?? models.default.thinkingLevel ?? defaultThinkingLevelForRef(activeRef)
|
|
262
|
+
return resolved.thinkingLevel ?? models.default.thinkingLevel ?? defaultThinkingLevelForRef(activeRef)
|
|
267
263
|
}
|
|
268
264
|
|
|
269
265
|
export async function createSession(options: CreateSessionOptions = {}): Promise<AgentSession> {
|
|
@@ -71,10 +71,17 @@ export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
|
|
|
71
71
|
// Called after each non-final attempt so callers can log the per-attempt
|
|
72
72
|
// failure with their own context (sessionId, channel key, job id, ...).
|
|
73
73
|
onAttemptFailed?: (attempt: FallbackAttempt<TRef>) => void
|
|
74
|
+
// Gate that decides whether a given failure is worth advancing the chain.
|
|
75
|
+
// Omitted (cron) means "advance on any error" — the original behavior.
|
|
76
|
+
// Interactive callers pass `isThrottleOrOverload` so a one-off real error
|
|
77
|
+
// (billing, malformed response) surfaces on the active ref instead of
|
|
78
|
+
// silently switching providers.
|
|
79
|
+
shouldFailover?: (err: Error) => boolean
|
|
74
80
|
}): Promise<FallbackPromptResult<TRef>> {
|
|
75
81
|
if (opts.refs.length === 0) {
|
|
76
82
|
throw new Error('promptWithFallback: refs[] must be non-empty')
|
|
77
83
|
}
|
|
84
|
+
const failoverGate = opts.shouldFailover ?? (() => true)
|
|
78
85
|
const attempts: FallbackAttempt<TRef>[] = []
|
|
79
86
|
let lastError: Error | undefined
|
|
80
87
|
for (let i = 0; i < opts.refs.length; i++) {
|
|
@@ -97,10 +104,11 @@ export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
|
|
|
97
104
|
const attempt: FallbackAttempt<TRef> = { ref, outcome: 'hard', errorMessage: error.message }
|
|
98
105
|
attempts.push(attempt)
|
|
99
106
|
lastError = error
|
|
100
|
-
|
|
107
|
+
const stop = isLast || !failoverGate(error)
|
|
108
|
+
if (!stop) opts.onAttemptFailed?.(attempt)
|
|
101
109
|
unsub()
|
|
102
110
|
await dispose()
|
|
103
|
-
if (
|
|
111
|
+
if (stop) {
|
|
104
112
|
return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
|
|
105
113
|
}
|
|
106
114
|
continue
|
|
@@ -109,10 +117,11 @@ export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
|
|
|
109
117
|
const attempt: FallbackAttempt<TRef> = { ref, outcome: 'soft', errorMessage: softError.message }
|
|
110
118
|
attempts.push(attempt)
|
|
111
119
|
lastError = softError
|
|
112
|
-
|
|
120
|
+
const stop = isLast || !failoverGate(softError)
|
|
121
|
+
if (!stop) opts.onAttemptFailed?.(attempt)
|
|
113
122
|
unsub()
|
|
114
123
|
await dispose()
|
|
115
|
-
if (
|
|
124
|
+
if (stop) {
|
|
116
125
|
return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
|
|
117
126
|
}
|
|
118
127
|
continue
|
|
@@ -41,6 +41,17 @@ const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
|
|
|
41
41
|
/\b(401|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|authentication failed|invalid bearer)\b/i,
|
|
42
42
|
safe: 'The upstream LLM provider rejected the request as unauthorized. Operators should check the provider API key configuration and `typeclaw logs`.',
|
|
43
43
|
},
|
|
44
|
+
{
|
|
45
|
+
// Content-policy refusal: OpenAI Codex flags a prompt under its cybersecurity
|
|
46
|
+
// policy (`code: "cyber_policy"`) and rejects the whole turn with
|
|
47
|
+
// `invalid_request`. Retrying or failing over to another Codex ref can't help
|
|
48
|
+
// — it's the same account-wide policy — so this must surface with the operator
|
|
49
|
+
// action (get the account authorized) rather than collapse to the generic
|
|
50
|
+
// notice. Common for security-focused PR reviews, where the diff content trips
|
|
51
|
+
// the filter. The URL is OpenAI's own published enrollment page, safe to echo.
|
|
52
|
+
match: /\bcyber_policy\b/i,
|
|
53
|
+
safe: 'The upstream LLM provider (OpenAI Codex) refused the request under its cybersecurity content policy. Operators must enroll the account in OpenAI Trusted Access for Cyber at https://chatgpt.com/cyber, or switch the configured model.',
|
|
54
|
+
},
|
|
44
55
|
{
|
|
45
56
|
match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
|
|
46
57
|
safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',
|
|
@@ -58,6 +69,27 @@ function toSafeMessage(raw: string): string {
|
|
|
58
69
|
return GENERIC_SAFE_NOTICE
|
|
59
70
|
}
|
|
60
71
|
|
|
72
|
+
// Capacity/rate signals worth failing OVER to another model ref (vs. retrying
|
|
73
|
+
// the same one). English-only is correct — these are provider protocol tokens,
|
|
74
|
+
// the explicit system-token exception to the multi-language rule. `\b` anchors
|
|
75
|
+
// `429`/`503` so they don't match digit runs in prose (token counts,
|
|
76
|
+
// elapsed-ms); `\b` is ASCII-safe because these are ASCII-only codes.
|
|
77
|
+
const THROTTLE_OR_OVERLOAD =
|
|
78
|
+
/overloaded|server_is_overloaded|service.?unavailable|rate.?limit|rate.?limited|too many requests|\b(?:429|503)\b/i
|
|
79
|
+
|
|
80
|
+
// Account-wide faults that must SURFACE, never fail over: switching refs can't
|
|
81
|
+
// help (same account) and would mask a config error the operator must fix. This
|
|
82
|
+
// is checked BEFORE the throttle match because providers often pair a `429`
|
|
83
|
+
// status with a quota/billing/auth reason (e.g. `429 insufficient quota`) — the
|
|
84
|
+
// status code alone must not force a pointless failover.
|
|
85
|
+
const NON_FAILOVER_FAULT =
|
|
86
|
+
/\bcyber_policy\b|insufficient.*(?:quota|credit|fund|balance)|\bquota\b|billing|payment|account is not active|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|authentication failed|invalid bearer/i
|
|
87
|
+
|
|
88
|
+
export function isThrottleOrOverload(raw: string): boolean {
|
|
89
|
+
if (NON_FAILOVER_FAULT.test(raw)) return false
|
|
90
|
+
return THROTTLE_OR_OVERLOAD.test(raw)
|
|
91
|
+
}
|
|
92
|
+
|
|
61
93
|
export function detectProviderError(message: unknown): DetectedProviderError | null {
|
|
62
94
|
if (typeof message !== 'object' || message === null) return null
|
|
63
95
|
const m = message as { role?: unknown; stopReason?: unknown; errorMessage?: unknown }
|
|
@@ -81,6 +113,9 @@ export function subscribeProviderErrors(session: AgentSession, onError: Provider
|
|
|
81
113
|
return session.subscribe((event) => {
|
|
82
114
|
if (event.type !== 'message_end') return
|
|
83
115
|
const detected = detectProviderError(event.message)
|
|
84
|
-
if (detected
|
|
116
|
+
if (detected === null) return
|
|
117
|
+
const abortRetry = (session as { abortRetry?: unknown }).abortRetry
|
|
118
|
+
if (isThrottleOrOverload(detected.message) && typeof abortRetry === 'function') abortRetry.call(session)
|
|
119
|
+
onError(detected)
|
|
85
120
|
})
|
|
86
121
|
}
|
package/src/agent/subagents.ts
CHANGED
|
@@ -1,13 +1,16 @@
|
|
|
1
1
|
import type { ToolDefinition } from '@mariozechner/pi-coding-agent'
|
|
2
2
|
import type { z } from 'zod'
|
|
3
3
|
|
|
4
|
+
import { getConfig, resolveModel } from '@/config'
|
|
4
5
|
import type { PermissionService } from '@/permissions'
|
|
5
6
|
import type { HookBus } from '@/plugin'
|
|
6
7
|
import type { Stream, Unsubscribe } from '@/stream'
|
|
7
8
|
|
|
8
9
|
import { applyTurnThinkingLevel } from './attention-escalation'
|
|
9
10
|
import { type AgentSession, createSession, type PluginSessionWiring } from './index'
|
|
10
|
-
import {
|
|
11
|
+
import { resolveFallbackChain } from './model-fallback'
|
|
12
|
+
import { applyModelRuntimeOverrides } from './model-overrides'
|
|
13
|
+
import { isThrottleOrOverload, subscribeProviderErrors } from './provider-error'
|
|
11
14
|
import type { SubagentBashPolicy } from './reviewer-bash-policy'
|
|
12
15
|
import type { SessionOrigin } from './session-origin'
|
|
13
16
|
import {
|
|
@@ -18,6 +21,7 @@ import {
|
|
|
18
21
|
} from './subagent-drain'
|
|
19
22
|
import { renderTurnTimeAnchor } from './system-prompt'
|
|
20
23
|
import type { ToolResultBudget } from './tool-result-budget'
|
|
24
|
+
import { promptPersistentTurnWithFallback } from './turn-runner'
|
|
21
25
|
|
|
22
26
|
type AgentSessionTools = NonNullable<Parameters<typeof createSession>[0]>['tools']
|
|
23
27
|
|
|
@@ -294,6 +298,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
|
|
|
294
298
|
const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath, backgroundDrain } =
|
|
295
299
|
normalizeSubagentSession(await createSessionForSubagent(subagent, sessionOptions))
|
|
296
300
|
let aborted = false
|
|
301
|
+
let activeModelRef = resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions))[0]!
|
|
297
302
|
let drainWatch: SubagentDrainWatch | undefined
|
|
298
303
|
const requiredBlockTag = REQUIRED_FINAL_BLOCK[name]
|
|
299
304
|
const capture = attachFinalMessageCapture(session, requiredBlockTag, options.onFinalMessageCaptured ?? (() => {}))
|
|
@@ -334,7 +339,29 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
|
|
|
334
339
|
? `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}\n\n${retrievalContext.results}`
|
|
335
340
|
: `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`
|
|
336
341
|
applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel)
|
|
337
|
-
await
|
|
342
|
+
const result = await promptPersistentTurnWithFallback({
|
|
343
|
+
refs: resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions)),
|
|
344
|
+
currentModelRef: activeModelRef,
|
|
345
|
+
profile: resolveSubagentProfile(subagent, sessionOptions),
|
|
346
|
+
session,
|
|
347
|
+
text: turnText,
|
|
348
|
+
skipProviderErrorSubscription: true,
|
|
349
|
+
detectSoftErrorFromLeaf: true,
|
|
350
|
+
shouldFailover: (err) => isThrottleOrOverload(err.message),
|
|
351
|
+
setModelForRef: async (ref) => {
|
|
352
|
+
await session.setModel(applyModelRuntimeOverrides(resolveModel(ref), ref))
|
|
353
|
+
activeModelRef = ref
|
|
354
|
+
},
|
|
355
|
+
beforeAttempt: () => {
|
|
356
|
+
applyTurnThinkingLevel(session, userPromptForTurn, session.thinkingLevel)
|
|
357
|
+
},
|
|
358
|
+
onAttemptFailed: (attempt) => {
|
|
359
|
+
console.warn(
|
|
360
|
+
`[subagent] ${name} ${attempt.outcome} failure on ${attempt.ref}: ${attempt.errorMessage ?? 'unknown'}; falling back`,
|
|
361
|
+
)
|
|
362
|
+
},
|
|
363
|
+
})
|
|
364
|
+
if (result.success) activeModelRef = result.refUsed
|
|
338
365
|
} finally {
|
|
339
366
|
if (hooks && turnEvent !== undefined) {
|
|
340
367
|
await hooks.runSessionTurnEnd(turnEvent)
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { providerForModelRef, type ModelRef } from '@/config/providers'
|
|
2
|
+
|
|
3
|
+
export const THROTTLE_THRESHOLD = 2
|
|
4
|
+
export const THROTTLE_WINDOW_MS = 60_000
|
|
5
|
+
export const COOLDOWN_MS = 180_000
|
|
6
|
+
|
|
7
|
+
export type ThrottleCircuitKey = {
|
|
8
|
+
profile?: string
|
|
9
|
+
ref: ModelRef
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
type CircuitEntry = {
|
|
13
|
+
failures: number[]
|
|
14
|
+
openUntil: number
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export class ThrottleCircuit {
|
|
18
|
+
private readonly entries = new Map<string, CircuitEntry>()
|
|
19
|
+
private readonly now: () => number
|
|
20
|
+
|
|
21
|
+
constructor(opts: { now?: () => number } = {}) {
|
|
22
|
+
this.now = opts.now ?? Date.now
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
isOpen(key: ThrottleCircuitKey): boolean {
|
|
26
|
+
const entry = this.entries.get(this.keyId(key))
|
|
27
|
+
if (entry === undefined) return false
|
|
28
|
+
return this.now() < entry.openUntil
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
recordThrottle(key: ThrottleCircuitKey): void {
|
|
32
|
+
const id = this.keyId(key)
|
|
33
|
+
const now = this.now()
|
|
34
|
+
const entry = this.entries.get(id) ?? { failures: [], openUntil: 0 }
|
|
35
|
+
entry.failures = entry.failures.filter((ts) => now - ts <= THROTTLE_WINDOW_MS)
|
|
36
|
+
entry.failures.push(now)
|
|
37
|
+
if (entry.failures.length >= THROTTLE_THRESHOLD) entry.openUntil = now + COOLDOWN_MS
|
|
38
|
+
this.entries.set(id, entry)
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
recordSuccess(key: ThrottleCircuitKey): void {
|
|
42
|
+
this.entries.delete(this.keyId(key))
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
private keyId(key: ThrottleCircuitKey): string {
|
|
46
|
+
return `${key.profile ?? 'default'}:${providerForModelRef(key.ref)}:${key.ref}`
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export const modelThrottleCircuit = new ThrottleCircuit()
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import type { ModelRef } from '@/config/providers'
|
|
2
|
+
|
|
3
|
+
import type { AgentSession } from './index'
|
|
4
|
+
import { detectProviderError, subscribeProviderErrors } from './provider-error'
|
|
5
|
+
import { modelThrottleCircuit, type ThrottleCircuit } from './throttle-circuit'
|
|
6
|
+
|
|
7
|
+
export type PersistentTurnAttempt = {
|
|
8
|
+
ref: ModelRef
|
|
9
|
+
outcome: 'hard' | 'soft' | 'success'
|
|
10
|
+
errorMessage?: string
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export type PersistentTurnResult = {
|
|
14
|
+
success: boolean
|
|
15
|
+
refUsed: ModelRef
|
|
16
|
+
attempts: PersistentTurnAttempt[]
|
|
17
|
+
lastError?: Error
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
type AttemptActivity = {
|
|
21
|
+
producedAssistantOutput: boolean
|
|
22
|
+
startedToolExecution: boolean
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export async function promptPersistentTurnWithFallback(opts: {
|
|
26
|
+
refs: ModelRef[]
|
|
27
|
+
currentModelRef: ModelRef
|
|
28
|
+
session: AgentSession
|
|
29
|
+
text: string
|
|
30
|
+
shouldFailover: (err: Error) => boolean
|
|
31
|
+
setModelForRef: (ref: ModelRef) => Promise<void>
|
|
32
|
+
profile?: string
|
|
33
|
+
circuit?: ThrottleCircuit
|
|
34
|
+
skipProviderErrorSubscription?: boolean
|
|
35
|
+
detectSoftErrorFromLeaf?: boolean
|
|
36
|
+
beforeAttempt?: (ref: ModelRef) => void
|
|
37
|
+
onAttemptFailed?: (attempt: PersistentTurnAttempt) => void
|
|
38
|
+
}): Promise<PersistentTurnResult> {
|
|
39
|
+
if (opts.refs.length === 0) throw new Error('promptPersistentTurnWithFallback: refs[] must be non-empty')
|
|
40
|
+
const attempts: PersistentTurnAttempt[] = []
|
|
41
|
+
let lastError: Error | undefined
|
|
42
|
+
const circuit = opts.circuit ?? modelThrottleCircuit
|
|
43
|
+
// The model the session currently has loaded; only call setModel when the
|
|
44
|
+
// chosen ref differs from it. Tracked locally so successive setModel calls
|
|
45
|
+
// within a single turn stay coherent.
|
|
46
|
+
let loadedRef = opts.currentModelRef
|
|
47
|
+
// Always start from the head of the chain so a recovered primary is probed
|
|
48
|
+
// again (the circuit breaker, not a sticky start index, decides when to skip
|
|
49
|
+
// a still-throttled ref). Starting at the previous turn's fallback would make
|
|
50
|
+
// a one-time failover permanent and never let the cooldown/half-open path
|
|
51
|
+
// re-test the primary.
|
|
52
|
+
for (let i = 0; i < opts.refs.length; i++) {
|
|
53
|
+
const ref = opts.refs[i]!
|
|
54
|
+
const isLast = i === opts.refs.length - 1
|
|
55
|
+
// Skip a ref whose circuit is open, but never skip the last one — there is
|
|
56
|
+
// nowhere left to fall, so we try it regardless and let the result speak.
|
|
57
|
+
if (!isLast && circuit.isOpen({ profile: opts.profile, ref })) continue
|
|
58
|
+
if (ref !== loadedRef) {
|
|
59
|
+
await opts.setModelForRef(ref)
|
|
60
|
+
loadedRef = ref
|
|
61
|
+
}
|
|
62
|
+
opts.beforeAttempt?.(ref)
|
|
63
|
+
const activity: AttemptActivity = { producedAssistantOutput: false, startedToolExecution: false }
|
|
64
|
+
let softError: Error | undefined
|
|
65
|
+
// Activity tracking ALWAYS runs — the idempotency guard must hold even for
|
|
66
|
+
// subagents. `skipProviderErrorSubscription` only suppresses the soft-error
|
|
67
|
+
// listener (subagents capture their final message off the leaf instead, via
|
|
68
|
+
// detectSoftErrorFromLeaf, so a second listener would race that capture).
|
|
69
|
+
const unsubActivity = subscribeAttemptActivity(opts.session, activity)
|
|
70
|
+
const unsubProvider = opts.skipProviderErrorSubscription
|
|
71
|
+
? () => {}
|
|
72
|
+
: subscribeProviderErrorsIfAvailable(opts.session, (err) => {
|
|
73
|
+
if (softError === undefined) softError = new Error(err.message)
|
|
74
|
+
})
|
|
75
|
+
try {
|
|
76
|
+
try {
|
|
77
|
+
await opts.session.prompt(opts.text)
|
|
78
|
+
} catch (err) {
|
|
79
|
+
const error = err instanceof Error ? err : new Error(String(err))
|
|
80
|
+
const attempt: PersistentTurnAttempt = { ref, outcome: 'hard', errorMessage: error.message }
|
|
81
|
+
attempts.push(attempt)
|
|
82
|
+
lastError = error
|
|
83
|
+
if (opts.shouldFailover(error)) circuit.recordThrottle({ profile: opts.profile, ref })
|
|
84
|
+
if (isLast || !canAdvance(error, activity, opts.shouldFailover)) throw error
|
|
85
|
+
opts.onAttemptFailed?.(attempt)
|
|
86
|
+
continue
|
|
87
|
+
}
|
|
88
|
+
if (softError !== undefined) {
|
|
89
|
+
const attempt: PersistentTurnAttempt = { ref, outcome: 'soft', errorMessage: softError.message }
|
|
90
|
+
attempts.push(attempt)
|
|
91
|
+
lastError = softError
|
|
92
|
+
if (opts.shouldFailover(softError)) circuit.recordThrottle({ profile: opts.profile, ref })
|
|
93
|
+
if (isLast || !canAdvance(softError, activity, opts.shouldFailover)) {
|
|
94
|
+
return { success: false, refUsed: ref, attempts, lastError }
|
|
95
|
+
}
|
|
96
|
+
opts.onAttemptFailed?.(attempt)
|
|
97
|
+
continue
|
|
98
|
+
}
|
|
99
|
+
const leafSoftError = opts.detectSoftErrorFromLeaf ? detectLeafSoftError(opts.session) : undefined
|
|
100
|
+
if (leafSoftError !== undefined) {
|
|
101
|
+
const attempt: PersistentTurnAttempt = { ref, outcome: 'soft', errorMessage: leafSoftError.message }
|
|
102
|
+
attempts.push(attempt)
|
|
103
|
+
lastError = leafSoftError
|
|
104
|
+
if (opts.shouldFailover(leafSoftError)) circuit.recordThrottle({ profile: opts.profile, ref })
|
|
105
|
+
if (isLast || !canAdvance(leafSoftError, activity, opts.shouldFailover)) {
|
|
106
|
+
return { success: false, refUsed: ref, attempts, lastError }
|
|
107
|
+
}
|
|
108
|
+
opts.onAttemptFailed?.(attempt)
|
|
109
|
+
continue
|
|
110
|
+
}
|
|
111
|
+
attempts.push({ ref, outcome: 'success' })
|
|
112
|
+
circuit.recordSuccess({ profile: opts.profile, ref })
|
|
113
|
+
return { success: true, refUsed: ref, attempts }
|
|
114
|
+
} finally {
|
|
115
|
+
unsubProvider()
|
|
116
|
+
unsubActivity()
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
return { success: false, refUsed: opts.refs[opts.refs.length - 1]!, attempts, lastError }
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function canAdvance(error: Error, activity: AttemptActivity, shouldFailover: (err: Error) => boolean): boolean {
|
|
123
|
+
return shouldFailover(error) && !activity.producedAssistantOutput && !activity.startedToolExecution
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function subscribeAttemptActivity(session: AgentSession, activity: AttemptActivity): () => void {
|
|
127
|
+
const subscribe = (session as { subscribe?: unknown }).subscribe
|
|
128
|
+
if (typeof subscribe !== 'function') return () => {}
|
|
129
|
+
return session.subscribe((event: unknown) => {
|
|
130
|
+
if (!isRecord(event)) return
|
|
131
|
+
if (event.type === 'tool_execution_start' || event.type === 'tool_execution_end') {
|
|
132
|
+
activity.startedToolExecution = true
|
|
133
|
+
return
|
|
134
|
+
}
|
|
135
|
+
if (event.type !== 'message_update') return
|
|
136
|
+
const assistantMessageEvent = event.assistantMessageEvent
|
|
137
|
+
if (!isRecord(assistantMessageEvent)) return
|
|
138
|
+
if (assistantMessageEvent.type === 'text_delta' && typeof assistantMessageEvent.delta === 'string') {
|
|
139
|
+
if (assistantMessageEvent.delta.length > 0) activity.producedAssistantOutput = true
|
|
140
|
+
}
|
|
141
|
+
})
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function subscribeProviderErrorsIfAvailable(
|
|
145
|
+
session: AgentSession,
|
|
146
|
+
onError: Parameters<typeof subscribeProviderErrors>[1],
|
|
147
|
+
): () => void {
|
|
148
|
+
const subscribe = (session as { subscribe?: unknown }).subscribe
|
|
149
|
+
if (typeof subscribe !== 'function') return () => {}
|
|
150
|
+
return subscribeProviderErrors(session, onError)
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function detectLeafSoftError(session: AgentSession): Error | undefined {
|
|
154
|
+
const leaf = session.sessionManager?.getLeafEntry()
|
|
155
|
+
if (!leaf || leaf.type !== 'message') return undefined
|
|
156
|
+
const detected = detectProviderError(leaf.message)
|
|
157
|
+
return detected === null ? undefined : new Error(detected.message)
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
161
|
+
return typeof value === 'object' && value !== null
|
|
162
|
+
}
|
|
@@ -32,17 +32,17 @@ All fields are **restart-required** — the plugin reads them once at boot. The
|
|
|
32
32
|
|
|
33
33
|
## What it contributes
|
|
34
34
|
|
|
35
|
-
| Kind | Name | Notes
|
|
36
|
-
| -------- | -------------------------- |
|
|
37
|
-
| Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`.
|
|
38
|
-
| Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run.
|
|
39
|
-
| Subagent | `memory-retrieval` | On `session.turn.start` when injection plan is `index` mode, reads the user's actual prompt for this turn + shard listing, writes a focused summary to `memory/.retrieval-cache/<sessionId>.md`. Coalesced per `parentSessionId`. Declares `profile: 'fast'` (retrieval is "≤3 keyword searches + 1 write", no reasoning required) and `timeoutMs: 30_000` so a wedged provider call releases the coalescing key instead of poisoning the cache for every subsequent turn.
|
|
40
|
-
| Tool | `memory_search` | Main-agent tool. Pass `query` to search, or `topic` to look up one shard by exact slug (not both). Search is substring/regex across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Plain queries are phrase-first: the whole query is tried as one substring, and if that finds nothing the query is split on whitespace and the distinct words are OR-matched, ranked by how many words each hit contains (regex queries never fall back). Results are discriminated by `source: "topic" \| "stream"`; exact-phrase (and regex) results list topics first, then streams newest-first, while word-fallback results are ranked by matched-word count with that order as the tiebreak (so a higher-scoring stream can precede a lower-scoring topic). The `topic` mode reads `memory/topics/<slug>.md` directly via `loadShard` and returns that one shard with its full body — no fuzzy search — so a channel agent can open a topic whose slug the per-turn injection already showed it, instead of re-searching for a body the retrieval layer already located. When no topic shard matches the slug it falls back to a reference of the same slug (`memory/references/<slug>.md`), because the per-turn injection renders topic and reference entries with the same `slug:` line and the same `memory_search({ topic: "<slug>" })` recovery hint — so a reference slug surfaced in channel memory must resolve here, not dead-end. Bad slugs (path traversal) come back as a structured error; a slug matching neither a topic nor a reference is an empty match set. |
|
|
41
|
-
| Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded.
|
|
42
|
-
| Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.
|
|
43
|
-
| Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip.
|
|
44
|
-
| Hook | `session.end` | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session.
|
|
45
|
-
| Hook | `session.turn.start` | **Vector on:** renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). **Vector off:** when `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question. Fire-and-forget; failures route through the plugin logger.
|
|
35
|
+
| Kind | Name | Notes |
|
|
36
|
+
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`. |
|
|
38
|
+
| Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run. |
|
|
39
|
+
| Subagent | `memory-retrieval` | On `session.turn.start` when injection plan is `index` mode, reads the user's actual prompt for this turn + shard listing, writes a focused summary to `memory/.retrieval-cache/<sessionId>.md`. Coalesced per `parentSessionId`. Declares `profile: 'fast'` (retrieval is "≤3 keyword searches + 1 write", no reasoning required) and `timeoutMs: 30_000` so a wedged provider call releases the coalescing key instead of poisoning the cache for every subsequent turn. |
|
|
40
|
+
| Tool | `memory_search` | Main-agent tool. Pass `query` to search, or `topic` to look up one shard by exact slug (not both). Search is substring/regex across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Plain queries are phrase-first: the whole query is tried as one substring, and if that finds nothing the query is split on whitespace and the distinct words are OR-matched, ranked by how many words each hit contains (regex queries never fall back). Results are discriminated by `source: "topic" \| "stream"`; exact-phrase (and regex) results list topics first, then streams newest-first, while word-fallback results are ranked by matched-word count with that order as the tiebreak (so a higher-scoring stream can precede a lower-scoring topic). The `topic` mode reads `memory/topics/<slug>.md` directly via `loadShard` and returns that one shard with its full body — no fuzzy search — so a channel agent can open a topic whose slug the per-turn injection already showed it, instead of re-searching for a body the retrieval layer already located. When no topic shard matches the slug it falls back to a reference of the same slug (`memory/references/<slug>.md`), because the per-turn injection renders topic and reference entries with the same `slug:` line and the same `memory_search({ topic: "<slug>" })` recovery hint — so a reference slug surfaced in channel memory must resolve here, not dead-end. Bad slugs (path traversal) come back as a structured error; a slug matching neither a topic nor a reference is an empty match set. The optional `where` param scopes a query to one room (`"#incidents"` or its raw chat id): it keeps only stream fragments whose captured `where` matches the room by raw `chat` id or `chatName` (case-insensitive, leading `#` optional) and — because room is fragment-only provenance — returns ONLY stream matches, excluding topic shards and references. |
|
|
41
|
+
| Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded. |
|
|
42
|
+
| Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`. |
|
|
43
|
+
| Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip. |
|
|
44
|
+
| Hook | `session.end` | Spawns `memory-logger` immediately; also unlinks the retrieval-cache file for this session. |
|
|
45
|
+
| Hook | `session.turn.start` | **Vector on:** renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). **Vector off:** when `buildInjectionPlan` returns `mode: 'index'` and origin is not a subagent, spawns `memory-retrieval` (detached) with the turn's `userPrompt` so the cache reflects the user's current question. Fire-and-forget; failures route through the plugin logger. |
|
|
46
46
|
|
|
47
47
|
## Memory injection (two-tier, topic shards only)
|
|
48
48
|
|
|
@@ -132,7 +132,7 @@ A `[dreaming] citation-superset violation: …` warning logs the dropped ids and
|
|
|
132
132
|
## Files on disk
|
|
133
133
|
|
|
134
134
|
- **`memory/topics/<slug>.md`** — per-topic shards with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, `tags?`) + body markdown. Runtime owns the frontmatter (recomputed after every dreaming run from the body's citations); dreaming subagent writes body only. The body is a **compact belief record**: one belief sentence stating the current truth (subject + predicate + essential scope qualifier; the strength wording — "mentioned" / "consistently" / "always" — is calibrated from `days`), followed by the `fragments:` list (active evidence behind the belief) and an optional `superseded:` list (evidence overturned by a later contradiction — kept cited for GC/history but excluded from vector retrieval). One sentence (not a paragraph) keeps bodies small so more topics stay under the direct-injection budget; the citation lists are the only load-bearing part of the body, so the prose shape is free to be terse. Existing verbose shards are rewritten into this form by the next dreaming run (no migration).
|
|
135
|
-
- **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards.
|
|
135
|
+
- **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards. A `fragment` event carries optional **situational provenance** for "who said what, where, and when": `who` (display name/handle of the attributed speaker, LLM-supplied per-fragment by `memory-logger` only when one transcript speaker clearly owns the evidence), `where` (`{ adapter, workspace, workspaceName?, chat, chatName?, thread }` — runtime-stamped from the session origin in the append tool, channel origins only), and `when` (reuses the existing `ts`). Both are optional, so legacy fragments and non-channel (TUI) origins parse with them absent. `who`/`where` are deliberately NOT in `fragmentContentHash` (dedup stays content-identity) and NOT in `fragmentEmbeddableText` (provenance is retrieval metadata, not embedded — it must not burn the 512-token budget or let same-room/same-person dominate recall). **Secret-scanning covers provenance too**: `who` (LLM-supplied) clears the same `detectSecrets` guard as `topic`/`body` and a credential-shaped value is refused with the retryable error; the origin-derived `where` names (`workspaceName`/`chatName`) are external channel data the agent can't rewrite, so a credential-shaped name is silently dropped (raw id kept) rather than wedging the logger. Raw ids are platform-issued identifiers, not free text, so they are not scanned. `where` is runtime-stamped rather than LLM-supplied because the channel is stable for a whole logger run; `who` is per-fragment because a single run spans many speakers and `origin.lastInboundAuthorId` is only the spawn-time one — auto-stamping it would misattribute fragments about earlier speakers. Surfaced to the agent (not embedded) via `memory_search` (`StreamMatch.who/when/where`), `hybridSearch` (`HybridSearchResult.who/when/where` on self-resolved undreamed fragments), and the per-turn retrieval render (`renderProvenanceLine` → `_Jisoo in #incidents on 2026-06-24_`).
|
|
136
136
|
- **`memory/MEMORY.md.pre-shard.bak`** — legacy pre-shard backup left by older TypeClaw versions. Safe to delete after verifying.
|
|
137
137
|
- **`memory/skills/<name>/SKILL.md`** — muscle memory (Form A). Skills the dreaming subagent distills from repeated procedures. Auto-loaded as first-class skills. CLI/plugin suggestions (Forms B and C) are recorded as topic shards instead — see [Muscle memory](#muscle-memory-three-forms).
|
|
138
138
|
- **`memory/references/<slug>.md`** — verbatim reference artifacts (gated behind `memory.references.enabled`). Written by `store_reference`. When vector is enabled, a freshly stored reference is embedded into the vector index immediately via the `store_reference` on-write hook (`vector/reference-index-on-write.ts`), mirroring the stream-fragment on-write hook — so it is vector-retrievable within the same container uptime instead of only after the next startup index build. Chunks are derived by the same `referencePassagesForOne` the startup build uses, and re-storing a shorter body prunes the stale higher-index chunk rows.
|