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.
Files changed (42) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +10 -14
  3. package/src/agent/model-fallback.ts +13 -4
  4. package/src/agent/provider-error.ts +36 -1
  5. package/src/agent/subagents.ts +29 -2
  6. package/src/agent/throttle-circuit.ts +50 -0
  7. package/src/agent/turn-runner.ts +162 -0
  8. package/src/bundled-plugins/memory/README.md +12 -12
  9. package/src/bundled-plugins/memory/append-tool.ts +58 -6
  10. package/src/bundled-plugins/memory/dreaming.ts +1 -1
  11. package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
  12. package/src/bundled-plugins/memory/load-memory.ts +28 -2
  13. package/src/bundled-plugins/memory/memory-logger.ts +14 -2
  14. package/src/bundled-plugins/memory/search-tool.ts +50 -7
  15. package/src/bundled-plugins/memory/stream-events.ts +23 -0
  16. package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
  17. package/src/bundled-plugins/security/index.ts +24 -1
  18. package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
  19. package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
  20. package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
  21. package/src/channels/adapters/webex-bot.ts +26 -25
  22. package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
  23. package/src/channels/adapters/webex.ts +27 -30
  24. package/src/channels/manager.ts +64 -57
  25. package/src/channels/router.ts +134 -4
  26. package/src/channels/types.ts +8 -1
  27. package/src/cli/builtins.ts +6 -32
  28. package/src/cli/command-meta.ts +93 -0
  29. package/src/cli/help.ts +24 -0
  30. package/src/cli/index.ts +34 -10
  31. package/src/config/config.ts +27 -1
  32. package/src/container/start.ts +22 -2
  33. package/src/hostd/daemon.ts +55 -26
  34. package/src/hostd/spawn.ts +53 -19
  35. package/src/permissions/permissions.ts +12 -0
  36. package/src/run/codex-fetch-observer.ts +11 -6
  37. package/src/secrets/oauth-xai.ts +2 -2
  38. package/src/server/index.ts +27 -2
  39. package/src/skills/typeclaw-channels/SKILL.md +1 -1
  40. package/src/skills/typeclaw-config/SKILL.md +1 -0
  41. package/src/skills/typeclaw-cron/SKILL.md +9 -4
  42. package/src/skills/typeclaw-permissions/SKILL.md +18 -6
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "typeclaw",
3
- "version": "0.39.3",
3
+ "version": "0.39.4",
4
4
  "homepage": "https://github.com/typeclaw/typeclaw#readme",
5
5
  "bugs": {
6
6
  "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -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 built-in `deep` default → the `default`
248
- // profile's `thinkingLevel` (the de-facto global default) → the per-provider/SDK
249
- // default for the active ref. When the requested profile was unknown, `resolved`
250
- // is already the `default` profile, so those terms coincide and the expression
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
- // The `deep` `high` default sits ABOVE `models.default.thinkingLevel` on purpose:
254
- // lowering the global default must not stop the "think hard" profile from
255
- // thinking hard. `high` (not `xhigh`) because `xhigh` ~doubles latency and token
256
- // spend for no agentic-quality gain. An explicit `models.deep.thinkingLevel`
257
- // still wins — it is the first term.
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
- const deepDefault = resolved.profile === 'deep' ? DEEP_PROFILE_DEFAULT_THINKING_LEVEL : undefined
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
- if (!isLast) opts.onAttemptFailed?.(attempt)
107
+ const stop = isLast || !failoverGate(error)
108
+ if (!stop) opts.onAttemptFailed?.(attempt)
101
109
  unsub()
102
110
  await dispose()
103
- if (isLast) {
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
- if (!isLast) opts.onAttemptFailed?.(attempt)
120
+ const stop = isLast || !failoverGate(softError)
121
+ if (!stop) opts.onAttemptFailed?.(attempt)
113
122
  unsub()
114
123
  await dispose()
115
- if (isLast) {
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 !== null) onError(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
  }
@@ -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 { subscribeProviderErrors } from './provider-error'
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 session.prompt(turnText)
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.