typeclaw 0.39.6 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/package.json +1 -1
  2. package/scripts/dump-system-prompt.ts +4 -50
  3. package/src/agent/auth-reloadable.ts +24 -0
  4. package/src/agent/auth.ts +12 -0
  5. package/src/agent/index.ts +18 -58
  6. package/src/agent/todo/continuation-policy.ts +8 -0
  7. package/src/agent/todo/continuation-state.ts +41 -7
  8. package/src/agent/todo/continuation-wiring.ts +26 -0
  9. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +0 -2
  10. package/src/bundled-plugins/guard/policy.ts +0 -5
  11. package/src/bundled-plugins/memory/README.md +26 -37
  12. package/src/bundled-plugins/memory/index.ts +32 -144
  13. package/src/bundled-plugins/memory/load-memory.ts +7 -121
  14. package/src/bundled-plugins/memory/memory-logger.ts +12 -6
  15. package/src/bundled-plugins/memory/search-command.ts +124 -0
  16. package/src/bundled-plugins/memory/vector/doctor.ts +1 -1
  17. package/src/bundled-plugins/memory/vector/embedder.ts +4 -5
  18. package/src/bundled-plugins/memory/vector/hybrid.ts +47 -5
  19. package/src/bundled-plugins/memory/vector/relevance-gate.ts +11 -7
  20. package/src/bundled-plugins/memory/vector/script.ts +87 -0
  21. package/src/channels/adapters/describe-error.ts +40 -0
  22. package/src/channels/adapters/discord.ts +9 -12
  23. package/src/channels/adapters/kakaotalk.ts +14 -17
  24. package/src/channels/adapters/line.ts +11 -14
  25. package/src/channels/adapters/slack-bot.ts +15 -18
  26. package/src/channels/adapters/slack.ts +45 -21
  27. package/src/channels/adapters/telegram-bot.ts +15 -18
  28. package/src/channels/adapters/webex-bot.ts +13 -14
  29. package/src/channels/adapters/webex.ts +14 -15
  30. package/src/channels/router.ts +60 -1
  31. package/src/cli/command-meta.ts +7 -16
  32. package/src/cli/compose.ts +21 -1
  33. package/src/cli/cron.ts +1 -1
  34. package/src/cli/docker-preflight.ts +42 -0
  35. package/src/cli/doctor.ts +1 -1
  36. package/src/cli/dreams.ts +1 -1
  37. package/src/cli/hostd.ts +12 -3
  38. package/src/cli/index.ts +1 -1
  39. package/src/cli/init.ts +24 -22
  40. package/src/cli/inspect.ts +1 -1
  41. package/src/cli/logs.ts +7 -0
  42. package/src/cli/memory.ts +85 -0
  43. package/src/cli/model.ts +1 -1
  44. package/src/cli/provider.ts +8 -1
  45. package/src/cli/reload.ts +6 -0
  46. package/src/cli/restart.ts +7 -0
  47. package/src/cli/shell.ts +7 -0
  48. package/src/cli/start.ts +7 -0
  49. package/src/cli/status.ts +9 -0
  50. package/src/cli/stop.ts +7 -0
  51. package/src/cli/tui.ts +6 -0
  52. package/src/config/config.ts +31 -8
  53. package/src/container/docker-app.ts +253 -0
  54. package/src/container/index.ts +11 -0
  55. package/src/container/start.ts +85 -41
  56. package/src/hostd/current-host-daemon.ts +21 -0
  57. package/src/hostd/daemon.ts +27 -3
  58. package/src/hostd/supervisor.ts +18 -3
  59. package/src/plugin/hooks.ts +3 -4
  60. package/src/plugin/types.ts +1 -1
  61. package/src/role-claim/client.ts +6 -1
  62. package/src/run/channel-session-factory.ts +3 -5
  63. package/src/run/index.ts +50 -17
  64. package/src/server/command-runner.ts +2 -11
  65. package/src/server/index.ts +8 -0
  66. package/src/skills/typeclaw-memory/SKILL.md +2 -2
  67. package/src/skills/typeclaw-plugins/SKILL.md +1 -1
  68. package/typeclaw.schema.json +1 -23
  69. package/src/bundled-plugins/guard/policies/memory-retrieval-cache-write.ts +0 -43
  70. package/src/bundled-plugins/memory/memory-retrieval.ts +0 -111
  71. package/src/bundled-plugins/memory/vector/cache-write.ts +0 -19
  72. package/src/bundled-plugins/memory/vector/config.ts +0 -28
@@ -16,6 +16,7 @@ import type {
16
16
  TypingTarget,
17
17
  } from '@/channels/types'
18
18
 
19
+ import { describeError } from './describe-error'
19
20
  import { classifyInbound, type InboundDropReason, TELEGRAM_WORKSPACE } from './telegram-bot-classify'
20
21
  import { toTelegramMarkdownV2 } from './telegram-bot-format'
21
22
 
@@ -105,7 +106,7 @@ export function createTypingCallback(deps: {
105
106
  logger.warn(`[telegram-bot] typing ${tag} status=${response.status}`)
106
107
  }
107
108
  } catch (err) {
108
- logger.warn(`[telegram-bot] typing ${tag} failed: ${describe(err)}`)
109
+ logger.warn(`[telegram-bot] typing ${tag} failed: ${describeError(err)}`)
109
110
  }
110
111
  }
111
112
  }
@@ -187,7 +188,7 @@ export function createTelegramMembershipResolver(deps: {
187
188
  truncated: true,
188
189
  }
189
190
  } catch (err) {
190
- deps.logger.warn(`[telegram-bot] membership chat=${key.chat} failed: ${describe(err)}`)
191
+ deps.logger.warn(`[telegram-bot] membership chat=${key.chat} failed: ${describeError(err)}`)
191
192
  return { kind: 'transient' } satisfies MembershipResolverFailure
192
193
  }
193
194
  }
@@ -240,7 +241,7 @@ export function createOutboundCallback(deps: {
240
241
  )
241
242
  }
242
243
  } catch (err) {
243
- const message = describe(err)
244
+ const message = describeError(err)
244
245
  logger.error(`[telegram-bot] sendDocument failed for ${path}: ${message}`)
245
246
  return { ok: false, error: `sendDocument failed: ${message}` }
246
247
  }
@@ -263,7 +264,7 @@ export function createOutboundCallback(deps: {
263
264
  const id = String(sent.message_id)
264
265
  return { ok: true, messageId: id, messageIds: [id] }
265
266
  } catch (err) {
266
- const message = describe(err)
267
+ const message = describeError(err)
267
268
  logger.error(`[telegram-bot] sendMessage failed: ${message}`)
268
269
  return { ok: false, error: message }
269
270
  }
@@ -319,7 +320,7 @@ export function createFetchAttachmentCallback(deps: {
319
320
  try {
320
321
  metaResponse = await fetchImpl(`${TELEGRAM_API_BASE}/bot${token}/getFile?file_id=${encodeURIComponent(ref)}`)
321
322
  } catch (err) {
322
- const message = describe(err)
323
+ const message = describeError(err)
323
324
  logger.error(`[telegram-bot] getFile failed for ${ref}: ${message}`)
324
325
  return { ok: false, error: `getFile failed: ${message}` }
325
326
  }
@@ -333,7 +334,7 @@ export function createFetchAttachmentCallback(deps: {
333
334
  try {
334
335
  meta = (await metaResponse.json()) as TelegramFileResponse
335
336
  } catch (err) {
336
- return { ok: false, error: `getFile parse failed: ${describe(err)}` }
337
+ return { ok: false, error: `getFile parse failed: ${describeError(err)}` }
337
338
  }
338
339
  if (!meta.ok || meta.result === undefined || meta.result.file_path === undefined) {
339
340
  const message = meta.description ?? 'getFile returned no file_path'
@@ -345,7 +346,7 @@ export function createFetchAttachmentCallback(deps: {
345
346
  try {
346
347
  response = await fetchImpl(downloadUrl)
347
348
  } catch (err) {
348
- const message = describe(err)
349
+ const message = describeError(err)
349
350
  logger.error(`[telegram-bot] download failed for ${ref}: ${message}`)
350
351
  return { ok: false, error: message }
351
352
  }
@@ -449,7 +450,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
449
450
  )
450
451
  await options.router.route(verdict.payload)
451
452
  } catch (err) {
452
- logger.error(`[telegram-bot] handleInbound failed: ${describe(err)}`)
453
+ logger.error(`[telegram-bot] handleInbound failed: ${describeError(err)}`)
453
454
  } finally {
454
455
  inflightInbounds--
455
456
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -468,7 +469,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
468
469
  await client.login({ token: options.token })
469
470
  } catch (err) {
470
471
  started = false
471
- logger.error(`[telegram-bot] login failed: ${describe(err)}`)
472
+ logger.error(`[telegram-bot] login failed: ${describeError(err)}`)
472
473
  throw err
473
474
  }
474
475
 
@@ -486,7 +487,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
486
487
  } catch (err) {
487
488
  started = false
488
489
  botUser = null
489
- logger.error(`[telegram-bot] getMe failed (likely invalid token): ${describe(err)}`)
490
+ logger.error(`[telegram-bot] getMe failed (likely invalid token): ${describeError(err)}`)
490
491
  throw err
491
492
  }
492
493
 
@@ -515,11 +516,11 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
515
516
  logger.warn('[telegram-bot] disconnected; SDK will reconnect with backoff')
516
517
  })
517
518
  listener.on('error', (err) => {
518
- const error = err instanceof Error ? err : new Error(String(err))
519
+ const error = err instanceof Error ? err : new Error(describeError(err))
519
520
  if (!listenerConnected && listenerStartupError === null) {
520
521
  listenerStartupError = error
521
522
  }
522
- logger.error(`[telegram-bot] listener error: ${describe(error)}`)
523
+ logger.error(`[telegram-bot] listener error: ${describeError(err)}`)
523
524
  })
524
525
  listener.on('message', (event) => {
525
526
  void handleMessage(event)
@@ -548,14 +549,14 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
548
549
  listener = null
549
550
  botUser = null
550
551
  started = false
551
- logger.error(`[telegram-bot] ${reason}: ${describe(cause)}`)
552
+ logger.error(`[telegram-bot] ${reason}: ${describeError(cause)}`)
552
553
  throw cause
553
554
  }
554
555
 
555
556
  try {
556
557
  await listener.start()
557
558
  } catch (err) {
558
- rollbackStart('listener start threw', err instanceof Error ? err : new Error(String(err)))
559
+ rollbackStart('listener start threw', err instanceof Error ? err : new Error(describeError(err)))
559
560
  }
560
561
  if (!listenerConnected) {
561
562
  const cause = listenerStartupError ?? new Error('listener.start() returned without emitting connected')
@@ -599,10 +600,6 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
599
600
  }
600
601
  }
601
602
 
602
- function describe(err: unknown): string {
603
- return err instanceof Error ? err.message : String(err)
604
- }
605
-
606
603
  function dropHint(reason: InboundDropReason): string {
607
604
  switch (reason) {
608
605
  case 'no_user':
@@ -29,6 +29,7 @@ import type {
29
29
  SendResult,
30
30
  } from '@/channels/types'
31
31
 
32
+ import { describeError } from './describe-error'
32
33
  import { createWebexChannelNameResolver } from './webex-bot-channel-resolver'
33
34
  import { classifyInbound, type InboundDropReason, type WebexInboundMessage } from './webex-bot-classify'
34
35
  import { enrichWebexMessageReference } from './webex-bot-reference'
@@ -129,7 +130,7 @@ export function createOutboundCallback(deps: {
129
130
  logger.info(`[webex-bot] sent id=${sent.ref} ${tag}`)
130
131
  return { ok: true, messageId: sent.ref, messageIds: [sent.ref] }
131
132
  } catch (err) {
132
- const message = describe(err)
133
+ const message = describeError(err)
133
134
  logger.error(`[webex-bot] outbound failed: ${message}`)
134
135
  return { ok: false, error: message }
135
136
  }
@@ -168,7 +169,7 @@ export function createWebexHistoryCallback(deps: {
168
169
  }
169
170
  return toHistory(outcome.value)
170
171
  } catch (err) {
171
- const message = describe(err)
172
+ const message = describeError(err)
172
173
  if (args.prefetch === true && isWebexRateLimitError(err)) {
173
174
  deps.logger.info(`[webex-bot] history prefetch skipped: rate limited (${message})`)
174
175
  return { ok: false, error: message, skipReason: 'rate-limited' }
@@ -215,7 +216,9 @@ export function createWebexMembershipResolver(deps: {
215
216
  }
216
217
  return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated, humanMemberIds }
217
218
  } catch (err) {
218
- deps.logger.warn(`[webex-bot] membership room=${key.chat} failed: ${describe(err)}; deriving from recent history`)
219
+ deps.logger.warn(
220
+ `[webex-bot] membership room=${key.chat} failed: ${describeError(err)}; deriving from recent history`,
221
+ )
219
222
  return await deriveMembershipFromHistory({
220
223
  fetchHistory: (limit) => deps.historyCallback({ chat: key.chat, thread: key.thread, limit, prefetch: true }),
221
224
  now,
@@ -267,7 +270,7 @@ export function createFetchAttachmentCallback(deps: {
267
270
  size: buffer.length,
268
271
  }
269
272
  } catch (err) {
270
- const message = describe(err)
273
+ const message = describeError(err)
271
274
  deps.logger.error(`[webex-bot] fetchAttachment failed for ${url.toString()}: ${message}`)
272
275
  return { ok: false, error: message }
273
276
  }
@@ -340,7 +343,7 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
340
343
  )
341
344
  await options.router.route(payload)
342
345
  } catch (err) {
343
- logger.error(`[webex-bot] handleInbound failed: ${describe(err)}`)
346
+ logger.error(`[webex-bot] handleInbound failed: ${describeError(err)}`)
344
347
  } finally {
345
348
  inflightInbounds--
346
349
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -362,7 +365,7 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
362
365
  } catch (err) {
363
366
  started = false
364
367
  botPerson = null
365
- logger.error(`[webex-bot] login failed: ${describe(err)}`)
368
+ logger.error(`[webex-bot] login failed: ${describeError(err)}`)
366
369
  throw err
367
370
  }
368
371
 
@@ -378,9 +381,9 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
378
381
  logger.warn(`[webex-bot] disconnected: ${reason}`)
379
382
  })
380
383
  listener.on('error', (err) => {
381
- const error = err instanceof Error ? err : new Error(String(err))
384
+ const error = err instanceof Error ? err : new Error(describeError(err))
382
385
  if (!listenerConnected && listenerStartupError === null) listenerStartupError = error
383
- logger.error(`[webex-bot] listener error: ${describe(error)}`)
386
+ logger.error(`[webex-bot] listener error: ${describeError(err)}`)
384
387
  })
385
388
  listener.on('message_created', (event: WebexBotListenerEventMap['message_created'][0]) => {
386
389
  void handleMessage(event)
@@ -405,14 +408,14 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
405
408
  botPerson = null
406
409
  connected = false
407
410
  started = false
408
- logger.error(`[webex-bot] ${reason}: ${describe(cause)}`)
411
+ logger.error(`[webex-bot] ${reason}: ${describeError(cause)}`)
409
412
  throw cause
410
413
  }
411
414
 
412
415
  try {
413
416
  await listener.start()
414
417
  } catch (err) {
415
- rollbackStart('listener start threw', err instanceof Error ? err : new Error(String(err)))
418
+ rollbackStart('listener start threw', err instanceof Error ? err : new Error(describeError(err)))
416
419
  }
417
420
  if (!listenerConnected) {
418
421
  rollbackStart(
@@ -474,10 +477,6 @@ function clampLimit(requested: number, max: number): number {
474
477
  return Math.min(Math.floor(requested), max)
475
478
  }
476
479
 
477
- function describe(err: unknown): string {
478
- return err instanceof Error ? err.message : String(err)
479
- }
480
-
481
480
  function dropHint(reason: InboundDropReason): string {
482
481
  switch (reason) {
483
482
  case 'empty_content':
@@ -34,6 +34,7 @@ import type {
34
34
  } from '@/channels/types'
35
35
  import type { WebexAccountRecord } from '@/secrets/schema'
36
36
 
37
+ import { describeError } from './describe-error'
37
38
  import { createWebexChannelNameResolver } from './webex-channel-resolver'
38
39
  import { classifyInbound, type InboundDropReason, type WebexInboundMessage } from './webex-classify'
39
40
  import { resolveWebexBodyText } from './webex-format'
@@ -136,7 +137,7 @@ export function createOutboundCallback(deps: {
136
137
  logger.info(`[webex] sent id=${sent.ref} ${tag}`)
137
138
  return { ok: true, messageId: sent.ref, messageIds: [sent.ref] }
138
139
  } catch (err) {
139
- const message = describe(err)
140
+ const message = describeError(err)
140
141
  logger.error(`[webex] outbound failed: ${message}`)
141
142
  return { ok: false, error: message }
142
143
  }
@@ -178,7 +179,7 @@ export function createTypingCallback(deps: {
178
179
  .then(() => client.setTyping(target.chat, typing))
179
180
  .catch(async (err: unknown) => {
180
181
  const tag = formatChannelTag ? await formatChannelTag(target.chat) : `room=${target.chat}`
181
- logger.warn(`[webex] typing ${tag} phase=${target.phase} failed: ${describe(err)}`)
182
+ logger.warn(`[webex] typing ${tag} phase=${target.phase} failed: ${describeError(err)}`)
182
183
  })
183
184
  queues.set(target.chat, next)
184
185
  void next.finally(() => {
@@ -217,7 +218,7 @@ export function createWebexHistoryCallback(deps: {
217
218
  }
218
219
  return toHistory(outcome.value)
219
220
  } catch (err) {
220
- const message = describe(err)
221
+ const message = describeError(err)
221
222
  if (args.prefetch === true && isWebexRateLimitError(err)) {
222
223
  deps.logger.info(`[webex] history prefetch skipped: rate limited (${message})`)
223
224
  return { ok: false, error: message, skipReason: 'rate-limited' }
@@ -264,7 +265,9 @@ export function createWebexMembershipResolver(deps: {
264
265
  }
265
266
  return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated, humanMemberIds }
266
267
  } catch (err) {
267
- deps.logger.warn(`[webex] membership room=${key.chat} failed: ${describe(err)}; deriving from recent history`)
268
+ deps.logger.warn(
269
+ `[webex] membership room=${key.chat} failed: ${describeError(err)}; deriving from recent history`,
270
+ )
268
271
  return await deriveMembershipFromHistory({
269
272
  fetchHistory: (limit) => deps.historyCallback({ chat: key.chat, thread: key.thread, limit, prefetch: true }),
270
273
  now,
@@ -318,7 +321,7 @@ export function createFetchAttachmentCallback(deps: {
318
321
  size: buffer.length,
319
322
  }
320
323
  } catch (err) {
321
- const message = describe(err)
324
+ const message = describeError(err)
322
325
  deps.logger.error(`[webex] fetchAttachment failed for ${url.toString()}: ${message}`)
323
326
  return { ok: false, error: message }
324
327
  }
@@ -391,7 +394,7 @@ export function createWebexAdapter(options: WebexAdapterOptions): WebexAdapter {
391
394
  )
392
395
  await options.router.route(payload)
393
396
  } catch (err) {
394
- logger.error(`[webex] handleInbound failed: ${describe(err)}`)
397
+ logger.error(`[webex] handleInbound failed: ${describeError(err)}`)
395
398
  } finally {
396
399
  inflightInbounds--
397
400
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -419,7 +422,7 @@ export function createWebexAdapter(options: WebexAdapterOptions): WebexAdapter {
419
422
  started = false
420
423
  currentToken = null
421
424
  botPerson = null
422
- logger.error(`[webex] login failed: ${describe(err)}`)
425
+ logger.error(`[webex] login failed: ${describeError(err)}`)
423
426
  throw err
424
427
  }
425
428
 
@@ -438,9 +441,9 @@ export function createWebexAdapter(options: WebexAdapterOptions): WebexAdapter {
438
441
  logger.warn(`[webex] disconnected: ${reason}`)
439
442
  })
440
443
  listener.on('error', (err: unknown) => {
441
- const error = err instanceof Error ? err : new Error(String(err))
444
+ const error = err instanceof Error ? err : new Error(describeError(err))
442
445
  if (!listenerConnected && listenerStartupError === null) listenerStartupError = error
443
- logger.error(`[webex] listener error: ${describe(error)}`)
446
+ logger.error(`[webex] listener error: ${describeError(err)}`)
444
447
  })
445
448
  listener.on('message_created', (event: WebexListenerEventMap['message_created'][0]) => {
446
449
  void handleMessage(event)
@@ -470,14 +473,14 @@ export function createWebexAdapter(options: WebexAdapterOptions): WebexAdapter {
470
473
  currentToken = null
471
474
  connected = false
472
475
  started = false
473
- logger.error(`[webex] ${reason}: ${describe(cause)}`)
476
+ logger.error(`[webex] ${reason}: ${describeError(cause)}`)
474
477
  throw cause
475
478
  }
476
479
 
477
480
  try {
478
481
  await listener.start()
479
482
  } catch (err) {
480
- rollbackStart('listener start threw', err instanceof Error ? err : new Error(String(err)))
483
+ rollbackStart('listener start threw', err instanceof Error ? err : new Error(describeError(err)))
481
484
  }
482
485
  if (!listenerConnected) {
483
486
  rollbackStart(
@@ -554,10 +557,6 @@ function clampLimit(requested: number, max: number): number {
554
557
  return Math.min(Math.floor(requested), max)
555
558
  }
556
559
 
557
- function describe(err: unknown): string {
558
- return err instanceof Error ? err.message : String(err)
559
- }
560
-
561
560
  function dropHint(reason: InboundDropReason): string {
562
561
  switch (reason) {
563
562
  case 'empty_content':
@@ -15,7 +15,9 @@ import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
15
15
  import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
16
16
  import {
17
17
  armRestartKickForOrigin,
18
+ clearAbortSuppressionForOrigin,
18
19
  extractTurnUsage,
20
+ markRestartAbortPendingForOrigin,
19
21
  recordTurnOutcome,
20
22
  recordTurnStart,
21
23
  runIdleContinuation,
@@ -1168,6 +1170,9 @@ export type ChannelRouter = {
1168
1170
  resumeRestartHandoff: (handoff: RestartHandoff) => Promise<void>
1169
1171
  stop: () => Promise<void>
1170
1172
  tearDownAllLive: () => Promise<void>
1173
+ // Graceful-restart shutdown: mark + abort every live channel session so each
1174
+ // scope's incomplete todos auto-continue on the next boot. See the impl.
1175
+ markRestartAbortForAllLive: () => Promise<void>
1171
1176
  liveCount: () => number
1172
1177
  __testing?: {
1173
1178
  flushDebounce: (key: ChannelKey) => Promise<void>
@@ -4393,6 +4398,23 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
4393
4398
  closing = false
4394
4399
  }
4395
4400
 
4401
+ // Graceful-restart shutdown: mark every live channel session's todo scope so
4402
+ // the turn the restart is about to abort does not arm the durable user-abort
4403
+ // block, then abort the in-flight turns. On the next boot each scope's resume
4404
+ // continues its incomplete todos instead of waiting for a human. Best-effort
4405
+ // and bounded by the caller's shutdown deadline.
4406
+ const markRestartAbortForAllLive = async (): Promise<void> => {
4407
+ for (const live of Array.from(liveSessions.values())) {
4408
+ const origin = buildLiveOrigin(live)
4409
+ await markRestartAbortPendingForOrigin(options.agentDir, origin).catch((err) =>
4410
+ logger.error(`[channels] graceful-restart mark abort failed: ${describe(err)}`),
4411
+ )
4412
+ await live.session
4413
+ .abort()
4414
+ .catch((err) => logger.error(`[channels] graceful-restart abort failed: ${describe(err)}`))
4415
+ }
4416
+ }
4417
+
4396
4418
  // Boot-time resume for a restart that originated from a channel session, in
4397
4419
  // two phases to close the race with adapters that begin receiving inbounds.
4398
4420
  //
@@ -4494,6 +4516,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
4494
4516
  await armRestartKickForOrigin(options.agentDir, buildLiveOrigin(live)).catch((err) =>
4495
4517
  logger.error(`[channels] ${keyId}: restart-resume arm restart-kick failed: ${describe(err)}`),
4496
4518
  )
4519
+ // A restart-aborted turn arms the durable user-abort block; this resume
4520
+ // IS the restart, so clear it or the resumed session never auto-resumes
4521
+ // its incomplete todos. Gated to this restart-handoff path.
4522
+ await clearAbortSuppressionForOrigin(options.agentDir, buildLiveOrigin(live)).catch((err) =>
4523
+ logger.error(`[channels] ${keyId}: restart-resume clear abort suppression failed: ${describe(err)}`),
4524
+ )
4497
4525
 
4498
4526
  live.pendingSystemReminders.push(RESTART_RESUME_WAKE_REMINDER)
4499
4527
  logger.info(`[channels] ${keyId}: restart-resume waking session ${live.sessionId}`)
@@ -4792,6 +4820,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
4792
4820
  resumeRestartHandoff,
4793
4821
  stop,
4794
4822
  tearDownAllLive,
4823
+ markRestartAbortForAllLive,
4795
4824
  liveCount: () => liveSessions.size,
4796
4825
  __testing: {
4797
4826
  flushDebounce: async (key: ChannelKey) => {
@@ -5062,7 +5091,7 @@ function formatAuthorLine(
5062
5091
  ): string {
5063
5092
  const tag = authorIsBot ? ' [bot]' : ''
5064
5093
  const stamp = ts > 0 ? `[${new Date(ts).toISOString()}] ` : ''
5065
- return `${stamp}${formatAuthorReference(adapter, authorId, authorName)} (${authorName})${tag}: ${capObservedText(text, maxChars)}`
5094
+ return `${stamp}${formatAuthorAttribution(adapter, authorId, authorName)}${tag}: ${capObservedText(text, maxChars)}`
5066
5095
  }
5067
5096
 
5068
5097
  // Cap by whole code points so truncation never splits a surrogate pair (emoji,
@@ -5105,6 +5134,36 @@ function formatInboundPromptLines(
5105
5134
 
5106
5135
  export type { QuoteAnchorSource } from './types'
5107
5136
 
5137
+ export function formatAuthorAttribution(adapter: AdapterId, authorId: string, authorName: string): string {
5138
+ const displayName = authorName.trim()
5139
+ const hasDisplayName = displayName !== ''
5140
+ const id = authorId.trim()
5141
+ if (id === '') return hasDisplayName ? displayName : authorId
5142
+
5143
+ switch (adapter) {
5144
+ case 'slack':
5145
+ case 'slack-bot':
5146
+ case 'discord':
5147
+ case 'discord-bot': {
5148
+ const mention = `<@${id}>`
5149
+ return hasDisplayName ? `${displayName} ${mention}` : mention
5150
+ }
5151
+ case 'github': {
5152
+ const login = /^\d+$/.test(id) && hasDisplayName ? displayName : id
5153
+ const handle = login.startsWith('@') ? login : `@${login}`
5154
+ if (!hasDisplayName) return handle
5155
+ const normalizedDisplayName = displayName.startsWith('@') ? displayName : `@${displayName}`
5156
+ return normalizedDisplayName === handle ? handle : `${displayName} (${handle})`
5157
+ }
5158
+ case 'telegram-bot':
5159
+ case 'webex':
5160
+ case 'webex-bot':
5161
+ case 'line':
5162
+ case 'kakaotalk':
5163
+ return hasDisplayName ? `${displayName} <${id}>` : id
5164
+ }
5165
+ }
5166
+
5108
5167
  // Picks the right author syntax for the platform so prompts and rendered
5109
5168
  // quote anchors use the same form the user would type in that channel.
5110
5169
  // Slack/Discord need id mentions (`<@U…>`), GitHub needs handle mentions
@@ -19,7 +19,7 @@ export type BuiltinCommandName =
19
19
  | 'reload'
20
20
  | 'logs'
21
21
  | 'inspect'
22
- | 'dreams'
22
+ | 'memory'
23
23
  | 'shell'
24
24
  | 'compose'
25
25
  | 'channel'
@@ -51,27 +51,18 @@ export const BUILTIN_COMMANDS: readonly BuiltinCommandMeta[] = [
51
51
  { name: 'status', description: 'show the agent container and host daemon status (host stage)' },
52
52
  { name: 'reload', description: "reload the running agent's reloadable subsystems (cron, ...)" },
53
53
  { name: 'logs', description: 'show the agent container logs (host stage)' },
54
- {
55
- name: 'inspect',
56
- description: 'session viewer: pick a session, the live TUI, or container logs to observe (host stage)',
57
- },
58
- {
59
- name: 'dreams',
60
- description: "browse the dreaming subagent's memory-consolidation journal from git history (host stage)",
61
- },
54
+ { name: 'inspect', description: 'session viewer: a session, the live TUI, or container logs' },
55
+ { name: 'memory', description: "browse and search the agent's long-term memory" },
62
56
  { name: 'shell', description: 'open an interactive shell in the agent container (host stage)' },
63
- { name: 'compose', description: 'orchestrate every typeclaw agent in immediate subdirectories of cwd' },
57
+ { name: 'compose', description: 'orchestrate every typeclaw agent in subdirectories of cwd' },
64
58
  { name: 'channel', description: 'manage channel adapters wired into the agent' },
65
- {
66
- name: 'cron',
67
- description: 'inspect cron jobs registered in the running agent (user-authored + plugin-contributed)',
68
- },
59
+ { name: 'cron', description: 'inspect cron jobs in the running agent (user + plugin)' },
69
60
  { name: 'tunnel', description: 'manage public tunnels for channels and manual upstreams' },
70
61
  { name: 'role', description: 'manage role memberships on this agent' },
71
62
  { name: 'provider', description: 'manage LLM provider credentials in secrets.json' },
72
- { name: 'model', description: 'manage model profiles in typeclaw.json (models.default, models.fast, …)' },
63
+ { name: 'model', description: 'manage model profiles in typeclaw.json (models.default, ...)' },
73
64
  { name: 'mount', description: 'manage host files and directories mounted into the agent container' },
74
- { name: 'doctor', description: 'diagnose the host, agent folder, and plugins; surface remediation steps' },
65
+ { name: 'doctor', description: 'diagnose host, agent folder, and plugins; suggest fixes' },
75
66
  { name: 'usage', description: 'report LLM token usage and cost for this agent folder' },
76
67
  { name: 'update', description: 'update the installed typeclaw CLI (auto-detects global vs local)' },
77
68
  { name: '_hostd', description: 'internal: host-side typeclaw daemon (do not invoke directly)', hidden: true },
@@ -17,9 +17,23 @@ import { formatJson, formatReport } from '@/doctor'
17
17
 
18
18
  import { formatComposeStatus } from './compose-status'
19
19
  import { formatComposeUsage, formatComposeUsageJson } from './compose-usage'
20
+ import { preflightDocker, printDockerGuidance } from './docker-preflight'
20
21
  import { c, errorLine, spinner } from './ui'
21
22
  import { parseSince, parseUntil } from './usage-args'
22
23
 
24
+ // Compose fans a docker command out across every agent folder. A down daemon
25
+ // would otherwise surface as N identical raw-stderr rows (one per agent) instead
26
+ // of one actionable message, so gate the whole fleet operation on a single
27
+ // preflight up front. usage reads only local session files and never touches
28
+ // docker, so it is intentionally not gated.
29
+ async function requireDockerOrExit(): Promise<void> {
30
+ const preflight = await preflightDocker()
31
+ if (!preflight.ok) {
32
+ printDockerGuidance(preflight)
33
+ process.exit(1)
34
+ }
35
+ }
36
+
23
37
  const startSub = defineCommand({
24
38
  meta: { name: 'start', description: 'start every agent in immediate subdirectories of cwd' },
25
39
  args: {
@@ -35,6 +49,7 @@ const startSub = defineCommand({
35
49
  },
36
50
  },
37
51
  async run({ args }) {
52
+ await requireDockerOrExit()
38
53
  const board = makeBoard('Starting agents')
39
54
  const s = spinner()
40
55
  const { agents, results } = await composeStart({
@@ -63,6 +78,7 @@ const startSub = defineCommand({
63
78
  const stopSub = defineCommand({
64
79
  meta: { name: 'stop', description: 'stop every agent in immediate subdirectories of cwd' },
65
80
  async run() {
81
+ await requireDockerOrExit()
66
82
  const board = makeBoard('Stopping agents')
67
83
  const s = spinner()
68
84
  const { agents, results } = await composeStop({
@@ -100,6 +116,7 @@ const restartSub = defineCommand({
100
116
  },
101
117
  },
102
118
  async run({ args }) {
119
+ await requireDockerOrExit()
103
120
  const board = makeBoard('Restarting agents')
104
121
  const s = spinner()
105
122
  const { agents, results } = await composeRestart({
@@ -130,6 +147,7 @@ const restartSub = defineCommand({
130
147
  const statusSub = defineCommand({
131
148
  meta: { name: 'status', description: 'show status of every agent in immediate subdirectories of cwd' },
132
149
  async run() {
150
+ await requireDockerOrExit()
133
151
  const result = await composeStatus(process.cwd())
134
152
  const useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined
135
153
  process.stdout.write(`${formatComposeStatus(result, { useColor })}\n`)
@@ -162,6 +180,8 @@ const logsSub = defineCommand({
162
180
  tail = parsed.value
163
181
  }
164
182
 
183
+ await requireDockerOrExit()
184
+
165
185
  const controller = new AbortController()
166
186
  const onSig = (): void => controller.abort()
167
187
  process.once('SIGINT', onSig)
@@ -257,7 +277,7 @@ const doctorSub = defineCommand({
257
277
  export const composeCommand = defineCommand({
258
278
  meta: {
259
279
  name: 'compose',
260
- description: 'orchestrate every typeclaw agent in immediate subdirectories of cwd',
280
+ description: 'orchestrate every typeclaw agent in subdirectories of cwd',
261
281
  },
262
282
  subCommands: {
263
283
  start: startSub,
package/src/cli/cron.ts CHANGED
@@ -65,7 +65,7 @@ const listSub = defineCommand({
65
65
  export const cronCommand = defineCommand({
66
66
  meta: {
67
67
  name: 'cron',
68
- description: 'inspect cron jobs registered in the running agent (user-authored + plugin-contributed)',
68
+ description: 'inspect cron jobs in the running agent (user + plugin)',
69
69
  },
70
70
  subCommands: {
71
71
  list: listSub,
@@ -0,0 +1,42 @@
1
+ import {
2
+ checkDockerAvailable,
3
+ detectInstalledDockerApps,
4
+ pickRuntimeToNudge,
5
+ renderDockerUnavailableGuidance,
6
+ type DockerExec,
7
+ } from '@/container'
8
+
9
+ import { c, errorLine } from './ui'
10
+
11
+ export type DockerPreflightResult = { ok: true } | { ok: false; summary: string; guidance: string[] }
12
+
13
+ // Single host-side gate every Docker-dependent CLI command calls before it
14
+ // spawns docker. Without it the raw daemon-down stderr (an unactionable socket
15
+ // path) leaks straight to the user. This probes once via checkDockerAvailable,
16
+ // then hands the friendly, runtime-specific guidance back to the caller so each
17
+ // command renders it in its own style (spinner vs console) — no process.exit
18
+ // here, that belongs to the command.
19
+ export async function preflightDocker(exec?: DockerExec): Promise<DockerPreflightResult> {
20
+ const availability = exec ? await checkDockerAvailable(exec) : await checkDockerAvailable()
21
+ if (availability.ok) return { ok: true }
22
+
23
+ const detail = availability.reason === 'daemon-down' ? availability.detail : undefined
24
+ const installed = detectInstalledDockerApps()
25
+ const nudge = pickRuntimeToNudge(process.env, detail, installed)
26
+ const { summary, lines } = renderDockerUnavailableGuidance(availability, {
27
+ platform: process.platform,
28
+ nudge,
29
+ installed,
30
+ })
31
+ return { ok: false, summary, guidance: lines }
32
+ }
33
+
34
+ // Prints the friendly guidance to stderr in the standard CLI error style
35
+ // (red ✖ summary, then dimmed guidance lines). Shared by every command's
36
+ // non-spinner failure path so the look is identical everywhere.
37
+ export function printDockerGuidance(failure: Extract<DockerPreflightResult, { ok: false }>): void {
38
+ console.error(errorLine(failure.summary))
39
+ for (const line of failure.guidance) {
40
+ console.error(line === '' ? '' : c.dim(line))
41
+ }
42
+ }
package/src/cli/doctor.ts CHANGED
@@ -6,7 +6,7 @@ import { findAgentDir } from '@/init'
6
6
  export const doctorCommand = defineCommand({
7
7
  meta: {
8
8
  name: 'doctor',
9
- description: 'diagnose the host, agent folder, and plugins; surface remediation steps',
9
+ description: 'diagnose host, agent folder, and plugins; suggest fixes',
10
10
  },
11
11
  args: {
12
12
  verbose: {
package/src/cli/dreams.ts CHANGED
@@ -12,7 +12,7 @@ const QUIT_KEY = 0x71
12
12
  export const dreamsCommand = defineCommand({
13
13
  meta: {
14
14
  name: 'dreams',
15
- description: "browse the dreaming subagent's memory-consolidation journal from git history (host stage)",
15
+ description: "browse the dreaming subagent's memory-consolidation journal",
16
16
  },
17
17
  args: {
18
18
  limit: {