typeclaw 0.44.0 → 0.45.1

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 (45) hide show
  1. package/package.json +7 -6
  2. package/src/agent/index.ts +42 -3
  3. package/src/agent/loop-guard.ts +208 -10
  4. package/src/agent/model-fallback.ts +59 -40
  5. package/src/agent/multimodal/look-at.ts +2 -1
  6. package/src/agent/plugin-tools.ts +59 -5
  7. package/src/agent/provider-error.ts +78 -18
  8. package/src/agent/retry-same-ref.ts +205 -0
  9. package/src/agent/subagents.ts +34 -4
  10. package/src/agent/tools/channel-edit.ts +144 -0
  11. package/src/agent/tools/channel-fetch-attachment.ts +6 -5
  12. package/src/agent/tools/channel-reply.ts +15 -1
  13. package/src/agent/tools/channel-send.ts +17 -1
  14. package/src/agent/tools/curl-impersonate.ts +40 -1
  15. package/src/agent/tools/webfetch/fetch.ts +86 -3
  16. package/src/agent/tools/webfetch/tool.ts +26 -3
  17. package/src/agent/tools/webfetch/types.ts +8 -0
  18. package/src/agent/turn-runner.ts +79 -36
  19. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +28 -11
  20. package/src/bundled-plugins/reviewer/skills/code-review.ts +27 -2
  21. package/src/channels/adapters/discord-bot-edit.ts +49 -0
  22. package/src/channels/adapters/discord-bot.ts +30 -4
  23. package/src/channels/adapters/discord-edit.ts +51 -0
  24. package/src/channels/adapters/discord.ts +4 -0
  25. package/src/channels/adapters/kakaotalk-channel-resolver.ts +10 -1
  26. package/src/channels/adapters/kakaotalk-typing.ts +125 -0
  27. package/src/channels/adapters/kakaotalk.ts +19 -0
  28. package/src/channels/adapters/slack-bot-edit.ts +58 -0
  29. package/src/channels/adapters/slack-bot.ts +18 -6
  30. package/src/channels/adapters/slack-edit.ts +47 -0
  31. package/src/channels/adapters/slack.ts +5 -0
  32. package/src/channels/adapters/teams-edit.ts +61 -0
  33. package/src/channels/adapters/teams.ts +4 -0
  34. package/src/channels/adapters/telegram-bot-edit.ts +51 -0
  35. package/src/channels/adapters/telegram-bot.ts +5 -0
  36. package/src/channels/adapters/webex-bot.ts +5 -0
  37. package/src/channels/adapters/webex-edit.ts +47 -0
  38. package/src/channels/adapters/webex.ts +5 -0
  39. package/src/channels/continuation-willingness.ts +227 -35
  40. package/src/channels/router.ts +500 -20
  41. package/src/channels/schema.ts +24 -0
  42. package/src/channels/types.ts +36 -0
  43. package/src/run/llm-fetch-observer.ts +147 -9
  44. package/src/server/command-runner.ts +2 -1
  45. package/src/server/index.ts +2 -1
@@ -42,6 +42,30 @@ export const ADAPTER_READ_CAPABILITIES: Record<AdapterId, readonly ReadCapabilit
42
42
  'webex-bot': ['history'],
43
43
  }
44
44
 
45
+ export type WriteCapability = 'message-edit'
46
+
47
+ // Mirror of ADAPTER_READ_CAPABILITIES for write-side capabilities that must
48
+ // survive a failed start(). Only adapters whose underlying SDK exposes a
49
+ // message-edit primitive appear here; the router uses this to answer
50
+ // `adapter-unavailable` (configured but not running — re-auth may help) vs
51
+ // `not-supported` (this adapter never edits) for a missing callback. The
52
+ // schema.test.ts guard re-derives each entry from the adapter's
53
+ // `.registerEditMessage(` call and fails if the table drifts.
54
+ export const ADAPTER_WRITE_CAPABILITIES: Record<AdapterId, readonly WriteCapability[]> = {
55
+ discord: ['message-edit'],
56
+ 'discord-bot': ['message-edit'],
57
+ github: [],
58
+ instagram: [],
59
+ line: [],
60
+ kakaotalk: [],
61
+ slack: ['message-edit'],
62
+ 'slack-bot': ['message-edit'],
63
+ teams: ['message-edit'],
64
+ 'telegram-bot': ['message-edit'],
65
+ webex: ['message-edit'],
66
+ 'webex-bot': ['message-edit'],
67
+ }
68
+
45
69
  const engagementTriggerSchema = z.enum(['mention', 'reply', 'dm'])
46
70
 
47
71
  const stickinessSchema = z.union([
@@ -272,6 +272,42 @@ export type SendResult =
272
272
 
273
273
  export type OutboundCallback = (msg: OutboundMessage) => Promise<SendResult>
274
274
 
275
+ // A request to edit (replace the text of) a message the bot already posted.
276
+ // `messageId` is the platform-native id the send handed back as
277
+ // `SendResult.messageId` (Slack `ts`, Discord snowflake, Telegram `message_id`,
278
+ // Webex message id) — the same id shape an inbound carries as
279
+ // `externalMessageId`. `thread` is context only: none of the supported SDK edit
280
+ // calls require it (Slack/Discord/Telegram/Webex address the message by
281
+ // channel+id or room+id), so adapters may ignore it. Editing is opt-in per
282
+ // adapter — only adapters whose SDK exposes an edit primitive register a
283
+ // callback; the rest resolve to `code: 'not-supported'`.
284
+ export type EditMessageRequest = {
285
+ adapter: AdapterId
286
+ workspace: string
287
+ chat: string
288
+ thread?: string | null
289
+ messageId: string
290
+ text: string
291
+ }
292
+
293
+ // `not-found` is an expected miss (message deleted, wrong id, or too old to
294
+ // edit) the tool surfaces as a soft error. `not-supported` means the adapter
295
+ // does not implement editing at all. `adapter-unavailable` means the adapter IS
296
+ // configured and DOES implement editing, but currently has no live callback
297
+ // (e.g. it failed to start), mirroring `getMessage`'s three-way distinction so
298
+ // the agent only sees the actionable re-auth hint when re-auth would help.
299
+ // `permission-denied` is a hard refusal from the platform (e.g. editing a
300
+ // message the bot does not own).
301
+ export type EditMessageResult =
302
+ | { ok: true }
303
+ | {
304
+ ok: false
305
+ error: string
306
+ code?: 'not-found' | 'not-supported' | 'adapter-unavailable' | 'permission-denied'
307
+ }
308
+
309
+ export type EditMessageCallback = (req: EditMessageRequest) => Promise<EditMessageResult>
310
+
275
311
  export type TypingTarget = {
276
312
  adapter: AdapterId
277
313
  workspace: string
@@ -77,6 +77,9 @@ export type LlmFetchObserverOptions = {
77
77
  // Schedule fn for tests. Receives (delayMs, callback) and returns a handle
78
78
  // the wrapper can pass to `clear`. Default: `setTimeout`/`clearTimeout`.
79
79
  scheduler?: TimeoutScheduler
80
+ // Test-only: inject a pre-seeded adaptive tracker to assert widening/probe/
81
+ // cooldown behaviour deterministically. Production always constructs its own.
82
+ adaptiveTracker?: AdaptiveTtfbTracker
80
83
  }
81
84
 
82
85
  export type TimeoutScheduler = {
@@ -103,6 +106,124 @@ const DEFAULT_IDLE_MS = 120_000
103
106
  const DEFAULT_OVERALL_MS = 300_000
104
107
  const LOG_PREFIX = '[llm-fetch]'
105
108
 
109
+ // Adaptive TTFB: give a provider that is OBSERVED to be slow-but-healthy more
110
+ // pre-headers room, without blunting silent-hang detection for fast providers.
111
+ // A fixed 15s guillotine kills legitimately-slow providers (e.g. GLM cold-start
112
+ // TTFB ~16.5s while its p50 is ~1s); a uniform higher default would let a truly
113
+ // hung FAST provider stall for the same widened window. So widening is scoped to
114
+ // the specific origin whose recent successful header latency is actually high.
115
+ //
116
+ // Signal: rolling p95 of successful header latency (not EWMA — the distributions
117
+ // are bimodal, mostly-1s with occasional 10–16s, so a mean-tracker sits low and
118
+ // never widens for the spike). Nearest-rank p95 over the last ADAPTIVE_WINDOW_MS
119
+ // of samples reacts to the current upper tail and forgets stale slowness.
120
+ const ADAPTIVE_TTFB_FLOOR_MS = 15_000
121
+ const ADAPTIVE_TTFB_CEIL_MS = 30_000
122
+ const ADAPTIVE_TTFB_MULTIPLIER = 2
123
+ const ADAPTIVE_MIN_SAMPLES = 8
124
+ const ADAPTIVE_MAX_SAMPLES = 32
125
+ const ADAPTIVE_WINDOW_MS = 5 * 60_000
126
+ // After a timeout at the CEIL budget, the origin is treated as slow-then-hung:
127
+ // suppress all widening (learned + probe) and fail closed to the floor for this
128
+ // long, so five rapid retries can't each inherit the 30s budget. A sub-floor
129
+ // success clears the suppression early.
130
+ const ADAPTIVE_COOLDOWN_MS = 5 * 60_000
131
+
132
+ function clampMs(value: number, floor: number, ceil: number): number {
133
+ return Math.min(ceil, Math.max(floor, value))
134
+ }
135
+
136
+ function p95(samples: readonly number[]): number {
137
+ const sorted = [...samples].sort((a, b) => a - b)
138
+ const rank = Math.ceil(0.95 * sorted.length)
139
+ return sorted[Math.min(rank, sorted.length) - 1]!
140
+ }
141
+
142
+ type AdaptiveSample = { at: number; headersMs: number }
143
+
144
+ // Per-origin adaptive-TTFB state. One instance lives in the first-installed
145
+ // observer's closure and is shared across every in-flight fetch in the process
146
+ // (single-threaded event loop → plain mutable maps are safe, no locking). Keyed
147
+ // by `${label}|${origin}` so unrelated OpenAI-compatible providers/proxies never
148
+ // inherit each other's latency budget.
149
+ export class AdaptiveTtfbTracker {
150
+ private readonly samples = new Map<string, AdaptiveSample[]>()
151
+ // Whether the origin's next request may spend one CEIL-budget recovery probe.
152
+ // Granted after a below-CEIL timeout (the killed request yielded only a
153
+ // right-censored "≥floor" bound, never a usable sample — a bounded probe is
154
+ // the only way to observe a genuinely-slow header latency past the floor).
155
+ private readonly probeGrant = new Set<string>()
156
+ // Origin → wall-clock time until which widening is suppressed (fail-closed).
157
+ private readonly cooldownUntil = new Map<string, number>()
158
+
159
+ constructor(private readonly now: () => number) {}
160
+
161
+ // Consumes the probe grant atomically so exactly one request gets the ceil.
162
+ resolve(key: string): number {
163
+ if (this.isInCooldown(key)) return ADAPTIVE_TTFB_FLOOR_MS
164
+ const learned = this.learnedTtfb(key)
165
+ if (this.probeGrant.has(key)) {
166
+ this.probeGrant.delete(key)
167
+ return Math.max(learned, ADAPTIVE_TTFB_CEIL_MS)
168
+ }
169
+ return learned
170
+ }
171
+
172
+ recordHeaders(key: string, headersMs: number): void {
173
+ // Any arrived-headers response (200/429/500) proves the origin is
174
+ // responsive, so it's a valid latency sample and clears fail-closed state.
175
+ if (headersMs < ADAPTIVE_TTFB_FLOOR_MS) this.cooldownUntil.delete(key)
176
+ const list = this.samples.get(key) ?? []
177
+ list.push({ at: this.now(), headersMs })
178
+ this.prune(list)
179
+ if (list.length > ADAPTIVE_MAX_SAMPLES) list.splice(0, list.length - ADAPTIVE_MAX_SAMPLES)
180
+ this.samples.set(key, list)
181
+ }
182
+
183
+ // A TTFB timeout at `usedMs`. Below the ceil → grant one recovery probe.
184
+ // At/above the ceil → the widened budget already failed; fail closed.
185
+ recordTimeout(key: string, usedMs: number): void {
186
+ if (usedMs >= ADAPTIVE_TTFB_CEIL_MS) {
187
+ this.probeGrant.delete(key)
188
+ this.cooldownUntil.set(key, this.now() + ADAPTIVE_COOLDOWN_MS)
189
+ return
190
+ }
191
+ this.probeGrant.add(key)
192
+ }
193
+
194
+ reset(): void {
195
+ this.samples.clear()
196
+ this.probeGrant.clear()
197
+ this.cooldownUntil.clear()
198
+ }
199
+
200
+ private learnedTtfb(key: string): number {
201
+ const list = this.samples.get(key)
202
+ if (list === undefined) return ADAPTIVE_TTFB_FLOOR_MS
203
+ this.prune(list)
204
+ if (list.length < ADAPTIVE_MIN_SAMPLES) return ADAPTIVE_TTFB_FLOOR_MS
205
+ const target = Math.ceil(ADAPTIVE_TTFB_MULTIPLIER * p95(list.map((s) => s.headersMs)))
206
+ return clampMs(target, ADAPTIVE_TTFB_FLOOR_MS, ADAPTIVE_TTFB_CEIL_MS)
207
+ }
208
+
209
+ private isInCooldown(key: string): boolean {
210
+ const until = this.cooldownUntil.get(key)
211
+ if (until === undefined) return false
212
+ if (this.now() >= until) {
213
+ this.cooldownUntil.delete(key)
214
+ return false
215
+ }
216
+ return true
217
+ }
218
+
219
+ private prune(list: AdaptiveSample[]): void {
220
+ const cutoff = this.now() - ADAPTIVE_WINDOW_MS
221
+ let drop = 0
222
+ while (drop < list.length && list[drop]!.at < cutoff) drop++
223
+ if (drop > 0) list.splice(0, drop)
224
+ }
225
+ }
226
+
106
227
  const defaultScheduler: TimeoutScheduler = {
107
228
  set: (delayMs, cb) => setTimeout(cb, delayMs),
108
229
  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
@@ -153,6 +274,7 @@ type InstallState = {
153
274
  originalFetch: typeof fetch
154
275
  wrapped: typeof fetch
155
276
  claimants: number
277
+ adaptive: AdaptiveTtfbTracker
156
278
  }
157
279
 
158
280
  // Ref-counted so multiple agents in one process (compose, tests) share one
@@ -169,7 +291,7 @@ function matchEndpoint(
169
291
  input: RequestInfo | URL,
170
292
  init: RequestInit | undefined,
171
293
  endpoints: readonly LlmFetchEndpoint[],
172
- ): LlmFetchEndpoint | null {
294
+ ): { endpoint: LlmFetchEndpoint; origin: string } | null {
173
295
  const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase()
174
296
  let urlString: string
175
297
  if (typeof input === 'string') urlString = input
@@ -182,7 +304,7 @@ function matchEndpoint(
182
304
  return null
183
305
  }
184
306
  for (const endpoint of endpoints) {
185
- if (endpoint.match(parsed, method)) return endpoint
307
+ if (endpoint.match(parsed, method)) return { endpoint, origin: parsed.origin }
186
308
  }
187
309
  return null
188
310
  }
@@ -454,6 +576,15 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
454
576
  overallMs: readEnvMs(process.env, ENV_OVERALL_MS, DEFAULT_OVERALL_MS),
455
577
  }
456
578
  const originalFetch = globalThis.fetch
579
+ const adaptive = opts.adaptiveTracker ?? new AdaptiveTtfbTracker(now)
580
+ // Adaptation is a property of the built-in floor default only. Any explicit
581
+ // static TTFB (observer opt, per-endpoint value, or a set TYPECLAW_*_TTFB_MS)
582
+ // means the operator pinned a deadline — honour it verbatim, no widening.
583
+ const adaptiveEligible =
584
+ timeoutsEnabled &&
585
+ opts.ttfbMs === undefined &&
586
+ readEnvMsOptional(process.env, ENV_TTFB_MS) === undefined &&
587
+ envDefaults.ttfbMs === DEFAULT_TTFB_MS
457
588
 
458
589
  // Precedence per timer: explicit observer-level option wins over the endpoint's
459
590
  // own value, which wins over the generic env/default. An explicit `opts.*` means
@@ -476,25 +607,29 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
476
607
  input: Parameters<typeof fetch>[0],
477
608
  init?: Parameters<typeof fetch>[1],
478
609
  ): Promise<Response> => {
479
- const endpoint = matchEndpoint(input, init, endpoints)
480
- if (endpoint === null) {
610
+ const matched = matchEndpoint(input, init, endpoints)
611
+ if (matched === null) {
481
612
  return originalFetch(input, init)
482
613
  }
614
+ const { endpoint, origin } = matched
483
615
  const perRequest = (init as LlmFetchObservedRequestInit | undefined)?.[LLM_FETCH_OBSERVER_TIMEOUTS]
484
616
  const timeouts = resolveTimeouts(endpoint, perRequest)
485
617
  const provider = endpoint.label
618
+ const adaptiveKey = `${provider}|${origin}`
619
+ const usesAdaptiveTtfb = adaptiveEligible && perRequest?.ttfbMs === undefined && endpoint.ttfbMs === undefined
620
+ const effectiveTtfbMs = usesAdaptiveTtfb ? adaptive.resolve(adaptiveKey) : timeouts.ttfbMs
486
621
  const start = now()
487
622
 
488
623
  let ttfbCause: 'ttfb_timeout' | null = null
489
624
  let ttfbHandle: unknown = null
490
625
  let initWithSignal: RequestInit | undefined = init
491
- if (timeouts.ttfbMs > 0) {
626
+ if (effectiveTtfbMs > 0) {
492
627
  const ttfbController = new AbortController()
493
- ttfbHandle = scheduler.set(timeouts.ttfbMs, () => {
628
+ ttfbHandle = scheduler.set(effectiveTtfbMs, () => {
494
629
  ttfbCause = 'ttfb_timeout'
495
630
  ttfbController.abort(
496
631
  new Error(
497
- `${provider} fetch timed out before response headers after ${timeouts.ttfbMs}ms (typeclaw observer timeout)`,
632
+ `${provider} fetch timed out before response headers after ${effectiveTtfbMs}ms (typeclaw observer timeout)`,
498
633
  ),
499
634
  )
500
635
  })
@@ -508,9 +643,10 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
508
643
  } catch (err) {
509
644
  if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
510
645
  const isTtfbAbort = ttfbCause === 'ttfb_timeout'
646
+ if (isTtfbAbort && usesAdaptiveTtfb) adaptive.recordTimeout(adaptiveKey, effectiveTtfbMs)
511
647
  const surfacedError = isTtfbAbort
512
648
  ? new Error(
513
- `${provider} fetch timed out before response headers after ${timeouts.ttfbMs}ms (typeclaw observer timeout)`,
649
+ `${provider} fetch timed out before response headers after ${effectiveTtfbMs}ms (typeclaw observer timeout)`,
514
650
  )
515
651
  : err
516
652
  const message = surfacedError instanceof Error ? surfacedError.message : String(surfacedError)
@@ -532,6 +668,7 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
532
668
  }
533
669
  if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
534
670
  const headersMs = now() - start
671
+ if (usesAdaptiveTtfb) adaptive.recordHeaders(adaptiveKey, headersMs)
535
672
  const retryAfter = response.headers.get('retry-after')
536
673
  const requestId = response.headers.get('x-request-id')
537
674
  return attachBodyTimingTap(response, start, headersMs, response.status, retryAfter, requestId, now, logger, {
@@ -550,7 +687,7 @@ export function installLlmFetchObserver(opts: LlmFetchObserverOptions = {}): ()
550
687
 
551
688
  globalThis.fetch = wrapped
552
689
 
553
- installed = { originalFetch, wrapped, claimants: 1 }
690
+ installed = { originalFetch, wrapped, claimants: 1, adaptive }
554
691
  return makeRelease(wrapped)
555
692
  }
556
693
 
@@ -564,6 +701,7 @@ function makeRelease(wrapped: typeof fetch): () => void {
564
701
  released = true
565
702
  installed.claimants--
566
703
  if (installed.claimants > 0) return
704
+ installed.adaptive.reset()
567
705
  if (globalThis.fetch === installed.wrapped) {
568
706
  globalThis.fetch = installed.originalFetch
569
707
  }
@@ -8,6 +8,7 @@ import {
8
8
  type SessionOrigin,
9
9
  } from '@/agent'
10
10
  import { applyTurnThinkingLevel } from '@/agent/attention-escalation'
11
+ import { promptWithSameRefRetryOnly } from '@/agent/retry-same-ref'
11
12
  import type { ChannelRouter } from '@/channels/router'
12
13
  import type { McpManager } from '@/mcp'
13
14
  import type { PermissionService } from '@/permissions'
@@ -427,7 +428,7 @@ export async function runPromptForCommand(args: {
427
428
  : `${renderTurnTimeAnchor()}\n\n${args.text}`
428
429
  applyTurnThinkingLevel(session, args.text, session.thinkingLevel)
429
430
  try {
430
- await session.prompt(turnText)
431
+ await promptWithSameRefRetryOnly(session, turnText)
431
432
  } finally {
432
433
  await snapshot.hooks.runSessionTurnEnd(turnEvent)
433
434
  }
@@ -18,6 +18,7 @@ import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
18
18
  import { detectProviderError, isFailoverWorthy } from '@/agent/provider-error'
19
19
  import { requestContainerRestart } from '@/agent/restart'
20
20
  import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-handoff'
21
+ import { promptWithSameRefRetryOnly } from '@/agent/retry-same-ref'
21
22
  import { sessionMetaPayload } from '@/agent/session-meta'
22
23
  import type { SessionOrigin } from '@/agent/session-origin'
23
24
  import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
@@ -816,7 +817,7 @@ export function createServer({
816
817
  ? `${renderTurnTimeAnchor()}\n\n${msg.text}\n\n${retrievalContext.results}`
817
818
  : `${renderTurnTimeAnchor()}\n\n${msg.text}`
818
819
  applyTurnThinkingLevel(state.session, msg.text, state.turnThinkingDefault, state.lastQuestionSignal)
819
- await state.session.prompt(turnText)
820
+ await promptWithSameRefRetryOnly(state.session, turnText)
820
821
  // A usable turn seeds the next turn's escalation; a failed leaf must
821
822
  // CLEAR the prior signal (not just skip), else an older question
822
823
  // leaks across the failed turn and wrongly escalates the next one.