typeclaw 0.41.0 → 0.42.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 (91) hide show
  1. package/README.md +3 -2
  2. package/auth.schema.json +57 -0
  3. package/package.json +4 -4
  4. package/secrets.schema.json +57 -0
  5. package/src/agent/adaptive-thinking-compat.ts +79 -0
  6. package/src/agent/index.ts +89 -107
  7. package/src/agent/plugin-tools.ts +77 -130
  8. package/src/agent/provider-error.ts +37 -0
  9. package/src/agent/reload-tool.ts +1 -1
  10. package/src/agent/session-origin.ts +1 -0
  11. package/src/agent/subagents.ts +2 -2
  12. package/src/agent/system-prompt.ts +19 -5
  13. package/src/agent/tool-result-budget.ts +1 -1
  14. package/src/agent/tools/channel-history-render.ts +21 -0
  15. package/src/agent/tools/channel-history.ts +2 -17
  16. package/src/agent/tools/channel-read.ts +206 -0
  17. package/src/agent/tools/stream-snapshot.ts +8 -3
  18. package/src/bundled-plugins/agent-browser/index.ts +18 -8
  19. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +26 -2
  20. package/src/bundled-plugins/github-cli-auth/index.ts +25 -6
  21. package/src/bundled-plugins/memory/README.md +4 -1
  22. package/src/bundled-plugins/memory/belief-sentence.ts +50 -0
  23. package/src/bundled-plugins/memory/dreaming.ts +13 -6
  24. package/src/bundled-plugins/memory/load-memory.ts +22 -2
  25. package/src/bundled-plugins/memory/memory-logger.ts +1 -1
  26. package/src/bundled-plugins/memory/vector/hybrid.ts +73 -6
  27. package/src/bundled-plugins/memory/vector/passages.ts +2 -24
  28. package/src/bundled-plugins/memory/vector/truncation.ts +28 -0
  29. package/src/bundled-plugins/tool-result-cap/README.md +10 -1
  30. package/src/bundled-plugins/tool-result-cap/cap-result.ts +8 -0
  31. package/src/capabilities/control-plane.ts +24 -0
  32. package/src/capabilities/index.ts +2 -0
  33. package/src/capabilities/runtime.ts +30 -0
  34. package/src/channels/adapters/discord-bot.ts +112 -0
  35. package/src/channels/adapters/instagram-channel-resolver.ts +113 -0
  36. package/src/channels/adapters/instagram-classify.ts +69 -0
  37. package/src/channels/adapters/instagram-format.ts +8 -0
  38. package/src/channels/adapters/instagram.ts +346 -0
  39. package/src/channels/adapters/slack-bot.ts +147 -0
  40. package/src/channels/manager.ts +96 -44
  41. package/src/channels/router.ts +75 -2
  42. package/src/channels/schema.ts +5 -0
  43. package/src/channels/types.ts +46 -0
  44. package/src/cli/channel.ts +121 -9
  45. package/src/cli/hostd.ts +4 -3
  46. package/src/cli/init.ts +1 -0
  47. package/src/cli/logs.ts +2 -2
  48. package/src/cli/restart.ts +5 -3
  49. package/src/cli/shell.ts +2 -2
  50. package/src/cli/start.ts +2 -2
  51. package/src/cli/status.ts +37 -14
  52. package/src/cli/stop.ts +2 -2
  53. package/src/compose/restart.ts +4 -3
  54. package/src/compose/start.ts +2 -2
  55. package/src/compose/stop.ts +2 -2
  56. package/src/config/channels-mutation.ts +2 -1
  57. package/src/config/config.ts +10 -1
  58. package/src/config/providers.ts +61 -9
  59. package/src/container/controller.ts +104 -0
  60. package/src/container/index.ts +9 -0
  61. package/src/doctor/channel-checks.ts +28 -0
  62. package/src/hostd/daemon.ts +11 -7
  63. package/src/hostd/protocol.ts +2 -0
  64. package/src/init/index.ts +51 -2
  65. package/src/init/instagram-auth.ts +289 -0
  66. package/src/init/run-owner-claim.ts +1 -0
  67. package/src/inspect/logs-item.ts +2 -2
  68. package/src/mcp/client.ts +1 -1
  69. package/src/permissions/match-rule.ts +1 -1
  70. package/src/permissions/resolve.ts +1 -0
  71. package/src/role-claim/match-rule.ts +2 -1
  72. package/src/run/index.ts +21 -9
  73. package/src/run/{codex-fetch-observer.ts → llm-fetch-observer.ts} +182 -82
  74. package/src/sandbox/availability.ts +2 -2
  75. package/src/sandbox/build.ts +1 -1
  76. package/src/sandbox/policy.ts +2 -2
  77. package/src/secrets/discord-store.ts +4 -13
  78. package/src/secrets/instagram-store.ts +103 -0
  79. package/src/secrets/kakao-store.ts +4 -13
  80. package/src/secrets/line-store.ts +4 -13
  81. package/src/secrets/schema.ts +18 -0
  82. package/src/secrets/secrets-provider.ts +86 -0
  83. package/src/secrets/slack-store.ts +4 -13
  84. package/src/secrets/webex-store.ts +4 -13
  85. package/src/server/index.ts +2 -2
  86. package/src/skills/typeclaw-channel-instagram/SKILL.md +30 -0
  87. package/src/skills/typeclaw-config/SKILL.md +5 -3
  88. package/src/skills/typeclaw-plugins/SKILL.md +1 -1
  89. package/src/stream/broker.ts +4 -3
  90. package/src/stream/types.ts +1 -0
  91. package/typeclaw.schema.json +175 -1
@@ -4,8 +4,10 @@ import { join } from 'node:path'
4
4
  import type { PermissionService } from '@/permissions'
5
5
  import type { GithubSecretsBlock } from '@/secrets'
6
6
  import { SecretsDiscordCredentialStore } from '@/secrets/discord-store'
7
+ import { SecretsInstagramCredentialStore } from '@/secrets/instagram-store'
7
8
  import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
8
9
  import { SecretsLineCredentialStore } from '@/secrets/line-store'
10
+ import type { RuntimeSecretsProvider } from '@/secrets/secrets-provider'
9
11
  import { SecretsSlackCredentialStore } from '@/secrets/slack-store'
10
12
  import { SecretsBackend } from '@/secrets/storage'
11
13
  import { SecretsWebexCredentialStore } from '@/secrets/webex-store'
@@ -14,6 +16,7 @@ import type { Stream } from '@/stream'
14
16
  import { createDiscordAdapter, type DiscordAdapter } from './adapters/discord'
15
17
  import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
16
18
  import { createGithubAdapter, type GithubAdapter } from './adapters/github'
19
+ import { createInstagramAdapter, type InstagramAdapter } from './adapters/instagram'
17
20
  import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
18
21
  import { createLineAdapter, type LineAdapter } from './adapters/line'
19
22
  import { createSlackAdapter, type SlackAdapter } from './adapters/slack'
@@ -64,6 +67,13 @@ export type ChannelManagerOptions = {
64
67
  aliasesRef?: () => readonly string[]
65
68
  logger?: ChannelManagerLogger
66
69
  env?: NodeJS.ProcessEnv
70
+ // The container-stage secrets provider for personal-account adapters
71
+ // (line/kakaotalk/slack/discord/webex/instagram write-back + read). Resolved
72
+ // ONCE at the composition root (createRuntimeCapabilities in src/run/index.ts)
73
+ // and threaded in here — the manager never resolves it from env itself. Null
74
+ // (or omitted) skips those adapters; see the note above the
75
+ // createContainer*CredentialStore factories.
76
+ secretsProvider?: RuntimeSecretsProvider | null
67
77
  // Production wiring passes a factory that builds sessions with the full
68
78
  // runtime plumbing (channelRouter, stream, plugins, reloadRegistry). When
69
79
  // omitted, the router falls back to a hollow factory that creates sessions
@@ -75,6 +85,7 @@ export type ChannelManagerOptions = {
75
85
  createDiscordAdapter?: typeof createDiscordBotAdapter
76
86
  createDiscordUserAdapter?: typeof createDiscordAdapter
77
87
  createGithubAdapter?: typeof createGithubAdapter
88
+ createInstagramAdapter?: typeof createInstagramAdapter
78
89
  createKakaotalkAdapter?: typeof createKakaotalkAdapter
79
90
  createLineAdapter?: typeof createLineAdapter
80
91
  createSlackAdapter?: typeof createSlackBotAdapter
@@ -145,6 +156,7 @@ type AnyAdapter =
145
156
  | DiscordAdapter
146
157
  | DiscordBotAdapter
147
158
  | GithubAdapter
159
+ | InstagramAdapter
148
160
  | LineAdapter
149
161
  | KakaotalkAdapter
150
162
  | SlackAdapter
@@ -188,6 +200,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
188
200
  const createDiscordBot = options.createDiscordAdapter ?? createDiscordBotAdapter
189
201
  const createDiscordUser = options.createDiscordUserAdapter ?? createDiscordAdapter
190
202
  const createGithub = options.createGithubAdapter ?? createGithubAdapter
203
+ const createInstagram = options.createInstagramAdapter ?? createInstagramAdapter
191
204
  const createKakaotalk = options.createKakaotalkAdapter ?? createKakaotalkAdapter
192
205
  const createLine = options.createLineAdapter ?? createLineAdapter
193
206
  const createSlackBot = options.createSlackAdapter ?? createSlackBotAdapter
@@ -219,6 +232,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
219
232
 
220
233
  const buildCredentialSignature = (name: AdapterId): { signature: string; missing: string[] } => {
221
234
  if (name === 'line') return buildLineSignature(options.agentDir)
235
+ if (name === 'instagram') return buildInstagramSignature(options.agentDir)
222
236
  if (name === 'kakaotalk') return buildKakaotalkSignature(options.agentDir)
223
237
  if (name === 'webex') return buildWebexSignature(options.agentDir)
224
238
  if (name === 'slack') return buildSlackSignature(options.agentDir)
@@ -261,7 +275,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
261
275
  })
262
276
  }
263
277
  if (name === 'line') {
264
- const credentialsStore = createContainerLineCredentialStore(options.agentDir, env)
278
+ const credentialsStore = createContainerLineCredentialStore(options.agentDir, options.secretsProvider ?? null)
265
279
  if (credentialsStore === null) return null
266
280
  return createLine({
267
281
  router,
@@ -271,8 +285,22 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
271
285
  credentialsStore,
272
286
  })
273
287
  }
288
+ if (name === 'instagram') {
289
+ const credentialsStore = createContainerInstagramCredentialStore(
290
+ options.agentDir,
291
+ options.secretsProvider ?? null,
292
+ )
293
+ if (credentialsStore === null) return null
294
+ return createInstagram({
295
+ router,
296
+ configRef: () => options.channelsConfigRef()[name] ?? cfg,
297
+ logger,
298
+ selfAliasesRef: () => router.getSelfAliases(),
299
+ credentialsStore,
300
+ })
301
+ }
274
302
  if (name === 'kakaotalk') {
275
- const credentialsStore = createContainerKakaoCredentialStore(options.agentDir, env)
303
+ const credentialsStore = createContainerKakaoCredentialStore(options.agentDir, options.secretsProvider ?? null)
276
304
  if (credentialsStore === null) return null
277
305
  return createKakaotalk({
278
306
  router,
@@ -283,7 +311,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
283
311
  })
284
312
  }
285
313
  if (name === 'slack') {
286
- const credentialsStore = createContainerSlackCredentialStore(options.agentDir, env)
314
+ const credentialsStore = createContainerSlackCredentialStore(options.agentDir, options.secretsProvider ?? null)
287
315
  if (credentialsStore === null) return null
288
316
  return createSlackUser({
289
317
  router,
@@ -294,7 +322,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
294
322
  })
295
323
  }
296
324
  if (name === 'discord') {
297
- const credentialsStore = createContainerDiscordCredentialStore(options.agentDir, env)
325
+ const credentialsStore = createContainerDiscordCredentialStore(options.agentDir, options.secretsProvider ?? null)
298
326
  if (credentialsStore === null) return null
299
327
  return createDiscordUser({
300
328
  router,
@@ -305,7 +333,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
305
333
  })
306
334
  }
307
335
  if (name === 'webex') {
308
- const credentialsStore = createContainerWebexCredentialStore(options.agentDir, env)
336
+ const credentialsStore = createContainerWebexCredentialStore(options.agentDir, options.secretsProvider ?? null)
309
337
  if (credentialsStore === null) return null
310
338
  return createWebex({
311
339
  router,
@@ -522,7 +550,12 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
522
550
  stopped.push(name)
523
551
  } else if (signature !== current.credentialSignature) {
524
552
  const reason =
525
- name === 'kakaotalk' || name === 'line' || name === 'webex' || name === 'slack' || name === 'discord'
553
+ name === 'kakaotalk' ||
554
+ name === 'line' ||
555
+ name === 'instagram' ||
556
+ name === 'webex' ||
557
+ name === 'slack' ||
558
+ name === 'discord'
526
559
  ? 'credential rotation'
527
560
  : 'token rotation'
528
561
  restartRequired.push(`${name} (${reason})`)
@@ -539,7 +572,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
539
572
  // secrets.json#channels.<adapter>, not in env, so they go through
540
573
  // structured-block signatures instead.
541
574
  const TOKEN_ENV: Record<
542
- Exclude<AdapterId, 'kakaotalk' | 'line' | 'github' | 'webex' | 'slack' | 'discord'>,
575
+ Exclude<AdapterId, 'kakaotalk' | 'line' | 'instagram' | 'github' | 'webex' | 'slack' | 'discord'>,
543
576
  readonly string[]
544
577
  > = {
545
578
  'discord-bot': ['DISCORD_BOT_TOKEN'],
@@ -548,33 +581,21 @@ const TOKEN_ENV: Record<
548
581
  'webex-bot': ['WEBEX_BOT_TOKEN'],
549
582
  }
550
583
 
551
- // Personal-account adapters (line/kakaotalk/slack/discord/webex) need the hostd
552
- // triple the host CLI injects at `docker run` time, gated on a successful daemon
553
- // registration (src/container/start.ts). If the daemon wasn't reachable at
554
- // launch (e.g. a lost first-boot spawn race) the triple is absent; null lets
555
- // buildAdapter skip the adapter instead of throwing and crashing the whole
556
- // channel manager. startAdapter's signature pre-check only reads secrets.json,
557
- // so this is the only place the missing triple is caught.
558
- type HostdContainerCredentials = { hostdUrl: string; restartToken: string; containerName: string }
559
-
560
- function resolveHostdContainerCredentials(env: NodeJS.ProcessEnv): HostdContainerCredentials | null {
561
- const hostdUrl = env.TYPECLAW_HOSTD_URL
562
- const restartToken = env.TYPECLAW_HOSTD_TOKEN
563
- const containerName = env.TYPECLAW_CONTAINER_NAME
564
- if (!hostdUrl || !restartToken || !containerName) return null
565
- return { hostdUrl, restartToken, containerName }
566
- }
567
-
584
+ // Personal-account adapters (line/kakaotalk/slack/discord/webex) need a
585
+ // container-stage secrets provider. It's resolved ONCE at the composition root
586
+ // (createRuntimeCapabilities in src/run/index.ts) and threaded in via
587
+ // `secretsProvider`; a null value (hostd triple absent — e.g. a lost first-boot
588
+ // spawn race, or a managed profile with no write-back wired) lets buildAdapter
589
+ // skip the adapter instead of crashing the whole channel manager.
568
590
  function createContainerDiscordCredentialStore(
569
591
  agentDir: string,
570
- env: NodeJS.ProcessEnv,
592
+ secretsProvider: RuntimeSecretsProvider | null,
571
593
  ): SecretsDiscordCredentialStore | null {
572
- const creds = resolveHostdContainerCredentials(env)
573
- if (creds === null) return null
594
+ if (secretsProvider === null) return null
574
595
  return new SecretsDiscordCredentialStore({
575
596
  mode: 'container',
576
597
  secretsPath: join(agentDir, 'secrets.json'),
577
- ...creds,
598
+ hostProvider: secretsProvider,
578
599
  })
579
600
  }
580
601
 
@@ -594,14 +615,13 @@ function buildDiscordSignature(agentDir: string): { signature: string; missing:
594
615
 
595
616
  function createContainerSlackCredentialStore(
596
617
  agentDir: string,
597
- env: NodeJS.ProcessEnv,
618
+ secretsProvider: RuntimeSecretsProvider | null,
598
619
  ): SecretsSlackCredentialStore | null {
599
- const creds = resolveHostdContainerCredentials(env)
600
- if (creds === null) return null
620
+ if (secretsProvider === null) return null
601
621
  return new SecretsSlackCredentialStore({
602
622
  mode: 'container',
603
623
  secretsPath: join(agentDir, 'secrets.json'),
604
- ...creds,
624
+ hostProvider: secretsProvider,
605
625
  })
606
626
  }
607
627
 
@@ -621,14 +641,13 @@ function buildSlackSignature(agentDir: string): { signature: string; missing: st
621
641
 
622
642
  function createContainerWebexCredentialStore(
623
643
  agentDir: string,
624
- env: NodeJS.ProcessEnv,
644
+ secretsProvider: RuntimeSecretsProvider | null,
625
645
  ): SecretsWebexCredentialStore | null {
626
- const creds = resolveHostdContainerCredentials(env)
627
- if (creds === null) return null
646
+ if (secretsProvider === null) return null
628
647
  return new SecretsWebexCredentialStore({
629
648
  mode: 'container',
630
649
  secretsPath: join(agentDir, 'secrets.json'),
631
- ...creds,
650
+ hostProvider: secretsProvider,
632
651
  })
633
652
  }
634
653
 
@@ -648,14 +667,13 @@ function buildWebexSignature(agentDir: string): { signature: string; missing: st
648
667
 
649
668
  function createContainerKakaoCredentialStore(
650
669
  agentDir: string,
651
- env: NodeJS.ProcessEnv,
670
+ secretsProvider: RuntimeSecretsProvider | null,
652
671
  ): SecretsKakaoCredentialStore | null {
653
- const creds = resolveHostdContainerCredentials(env)
654
- if (creds === null) return null
672
+ if (secretsProvider === null) return null
655
673
  return new SecretsKakaoCredentialStore({
656
674
  mode: 'container',
657
675
  secretsPath: join(agentDir, 'secrets.json'),
658
- ...creds,
676
+ hostProvider: secretsProvider,
659
677
  })
660
678
  }
661
679
 
@@ -675,14 +693,13 @@ function buildKakaotalkSignature(agentDir: string): { signature: string; missing
675
693
 
676
694
  function createContainerLineCredentialStore(
677
695
  agentDir: string,
678
- env: NodeJS.ProcessEnv,
696
+ secretsProvider: RuntimeSecretsProvider | null,
679
697
  ): SecretsLineCredentialStore | null {
680
- const creds = resolveHostdContainerCredentials(env)
681
- if (creds === null) return null
698
+ if (secretsProvider === null) return null
682
699
  return new SecretsLineCredentialStore({
683
700
  mode: 'container',
684
701
  secretsPath: join(agentDir, 'secrets.json'),
685
- ...creds,
702
+ hostProvider: secretsProvider,
686
703
  })
687
704
  }
688
705
 
@@ -700,6 +717,32 @@ function buildLineSignature(agentDir: string): { signature: string; missing: str
700
717
  }
701
718
  }
702
719
 
720
+ function createContainerInstagramCredentialStore(
721
+ agentDir: string,
722
+ secretsProvider: RuntimeSecretsProvider | null,
723
+ ): SecretsInstagramCredentialStore | null {
724
+ if (secretsProvider === null) return null
725
+ return new SecretsInstagramCredentialStore({
726
+ mode: 'container',
727
+ secretsPath: join(agentDir, 'secrets.json'),
728
+ hostProvider: secretsProvider,
729
+ })
730
+ }
731
+
732
+ function buildInstagramSignature(agentDir: string): { signature: string; missing: string[] } {
733
+ const path = join(agentDir, 'secrets.json')
734
+ try {
735
+ const block = new SecretsBackend(path).tryReadChannelsSync()?.instagram
736
+ if (!isInstagramCredentialBlock(block)) {
737
+ return { signature: '', missing: ['secrets.json#channels.instagram'] }
738
+ }
739
+ const digest = createHash('sha256').update(JSON.stringify(block)).digest('hex')
740
+ return { signature: `secrets.json#channels.instagram@sha256:${digest}`, missing: [] }
741
+ } catch (err) {
742
+ return { signature: '', missing: [`secrets.json#channels.instagram (${describe(err)})`] }
743
+ }
744
+ }
745
+
703
746
  function buildGithubSignature(agentDir: string): { signature: string; missing: string[] } {
704
747
  const block = readGithubSecrets(agentDir)
705
748
  if (block === null) return { signature: '', missing: ['secrets.json#channels.github'] }
@@ -744,6 +787,15 @@ function isLineCredentialBlock(value: unknown): value is { accounts: Record<stri
744
787
  )
745
788
  }
746
789
 
790
+ function isInstagramCredentialBlock(value: unknown): value is { accounts: Record<string, unknown> } {
791
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
792
+ if (!('accounts' in value)) return false
793
+ const accounts = value.accounts
794
+ return (
795
+ typeof accounts === 'object' && accounts !== null && !Array.isArray(accounts) && Object.keys(accounts).length > 0
796
+ )
797
+ }
798
+
747
799
  function isSlackCredentialBlock(value: unknown): value is { accounts: Record<string, unknown> } {
748
800
  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
749
801
  if (!('accounts' in value)) return false
@@ -9,7 +9,7 @@ import { applyTurnThinkingLevel, getQuestionSignal, type QuestionSignal } from '
9
9
  import { resolveFallbackChain } from '@/agent/model-fallback'
10
10
  import { applyModelRuntimeOverrides } from '@/agent/model-overrides'
11
11
  import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
12
- import { isThrottleOrOverload, subscribeProviderErrors } from '@/agent/provider-error'
12
+ import { detectHardProviderError, isFailoverWorthy, subscribeProviderErrors } from '@/agent/provider-error'
13
13
  import type { RestartHandoff } from '@/agent/restart-handoff'
14
14
  import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
15
15
  import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
@@ -74,10 +74,16 @@ import type {
74
74
  FetchAttachmentResult,
75
75
  FetchHistoryArgs,
76
76
  FetchHistoryResult,
77
+ GetMessageArgs,
78
+ GetMessageResult,
77
79
  HistoryCallback,
78
80
  InboundAttachment,
79
81
  InboundMessage,
80
82
  InboundReferenceContext,
83
+ ListCallback,
84
+ ListChannelsArgs,
85
+ ListChannelsResult,
86
+ MessageGetCallback,
81
87
  RemoveReactionCallback,
82
88
  RemoveReactionRequest,
83
89
  OutboundCallback,
@@ -1049,6 +1055,16 @@ export type ChannelRouter = {
1049
1055
  registerHistory: (adapter: ChannelKey['adapter'], cb: HistoryCallback) => void
1050
1056
  unregisterHistory: (adapter: ChannelKey['adapter'], cb: HistoryCallback) => void
1051
1057
  fetchHistory: (adapter: ChannelKey['adapter'], args: FetchHistoryArgs) => Promise<FetchHistoryResult>
1058
+ // Single-message-get and channel-list are opt-in per adapter and last-write-
1059
+ // wins (one bot account per adapter). When unregistered, `getMessage` /
1060
+ // `listChannels` answer `code: 'not-supported'`, matching `fetchHistory`'s
1061
+ // 'history-not-supported' fallback.
1062
+ registerMessageGet: (adapter: ChannelKey['adapter'], cb: MessageGetCallback) => void
1063
+ unregisterMessageGet: (adapter: ChannelKey['adapter'], cb: MessageGetCallback) => void
1064
+ getMessage: (adapter: ChannelKey['adapter'], args: GetMessageArgs) => Promise<GetMessageResult>
1065
+ registerList: (adapter: ChannelKey['adapter'], cb: ListCallback) => void
1066
+ unregisterList: (adapter: ChannelKey['adapter'], cb: ListCallback) => void
1067
+ listChannels: (adapter: ChannelKey['adapter'], args: ListChannelsArgs) => Promise<ListChannelsResult>
1052
1068
  registerFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
1053
1069
  unregisterFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
1054
1070
  fetchAttachment: (adapter: ChannelKey['adapter'], args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
@@ -1385,6 +1401,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
1385
1401
  const selfIdentityResolvers = new Map<ChannelKey['adapter'], ChannelSelfIdentityResolver>()
1386
1402
  const membershipCaches = new Map<ChannelKey['adapter'], MembershipCache>()
1387
1403
  const historyCallbacks = new Map<ChannelKey['adapter'], Set<HistoryCallback>>()
1404
+ const messageGetCallbacks = new Map<ChannelKey['adapter'], MessageGetCallback>()
1405
+ const listCallbacks = new Map<ChannelKey['adapter'], ListCallback>()
1388
1406
  const fetchAttachmentCallbacks = new Map<ChannelKey['adapter'], Set<FetchAttachmentCallback>>()
1389
1407
  const reviewThreadResolvers = new Map<ChannelKey['adapter'], ReviewThreadResolver>()
1390
1408
  const reviewStateResolvers = new Map<ChannelKey['adapter'], ReviewStateResolver>()
@@ -2636,7 +2654,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
2636
2654
  currentModelRef: live.activeModelRef,
2637
2655
  session: live.session,
2638
2656
  text: promptText,
2639
- shouldFailover: (err) => isThrottleOrOverload(err.message),
2657
+ shouldFailover: (err) => isFailoverWorthy(err.message),
2640
2658
  setModelForRef: async (ref) => {
2641
2659
  await live.session.setModel(applyModelRuntimeOverrides(resolveModel(ref), ref))
2642
2660
  live.activeModelRef = ref
@@ -2676,6 +2694,15 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
2676
2694
  logger.info(`[channels] ${live.keyId} prompted elapsed_ms=${now() - promptStart}`)
2677
2695
  } catch (err) {
2678
2696
  logger.error(`[channels] ${live.keyId}: prompt threw: ${describe(err)}`)
2697
+ // Fallback is exhausted by now (promptPersistentTurnWithFallback only
2698
+ // throws after rotating every eligible ref), so a recognizable provider
2699
+ // failure is terminal for this turn. Stage a redacted notice for the
2700
+ // `finally` poster — but never clobber a soft error already captured for
2701
+ // this turnSeq by subscribeProviderErrors (first-detected wins).
2702
+ const hardProviderError = detectHardProviderError(err)
2703
+ if (hardProviderError !== null && live.pendingProviderError?.turnSeq !== live.turnSeq) {
2704
+ live.pendingProviderError = { turnSeq: live.turnSeq, safeMessage: hardProviderError.safeMessage }
2705
+ }
2679
2706
  live.consecutiveSends.clear()
2680
2707
  live.lastSentText.clear()
2681
2708
  live.lastSendLeafId = null
@@ -3374,6 +3401,44 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
3374
3401
  return lastError
3375
3402
  }
3376
3403
 
3404
+ const registerMessageGet = (adapter: ChannelKey['adapter'], cb: MessageGetCallback): void => {
3405
+ messageGetCallbacks.set(adapter, cb)
3406
+ }
3407
+
3408
+ const unregisterMessageGet = (adapter: ChannelKey['adapter'], cb: MessageGetCallback): void => {
3409
+ if (messageGetCallbacks.get(adapter) === cb) messageGetCallbacks.delete(adapter)
3410
+ }
3411
+
3412
+ const getMessage = async (adapter: ChannelKey['adapter'], args: GetMessageArgs): Promise<GetMessageResult> => {
3413
+ const cb = messageGetCallbacks.get(adapter)
3414
+ if (cb === undefined) return { ok: false, error: 'message-get-not-supported', code: 'not-supported' }
3415
+ try {
3416
+ return await raceWithTimeout(cb(args), fetchHistoryTimeoutMs, `[channels] ${adapter} message get`)
3417
+ } catch (err) {
3418
+ logger.warn(`[channels] message get threw for ${adapter}: ${describe(err)}`)
3419
+ return { ok: false, error: 'message-get-not-supported', code: 'not-supported' }
3420
+ }
3421
+ }
3422
+
3423
+ const registerList = (adapter: ChannelKey['adapter'], cb: ListCallback): void => {
3424
+ listCallbacks.set(adapter, cb)
3425
+ }
3426
+
3427
+ const unregisterList = (adapter: ChannelKey['adapter'], cb: ListCallback): void => {
3428
+ if (listCallbacks.get(adapter) === cb) listCallbacks.delete(adapter)
3429
+ }
3430
+
3431
+ const listChannels = async (adapter: ChannelKey['adapter'], args: ListChannelsArgs): Promise<ListChannelsResult> => {
3432
+ const cb = listCallbacks.get(adapter)
3433
+ if (cb === undefined) return { ok: false, error: 'list-not-supported', code: 'not-supported' }
3434
+ try {
3435
+ return await raceWithTimeout(cb(args), fetchHistoryTimeoutMs, `[channels] ${adapter} list channels`)
3436
+ } catch (err) {
3437
+ logger.warn(`[channels] list channels threw for ${adapter}: ${describe(err)}`)
3438
+ return { ok: false, error: 'list-not-supported', code: 'not-supported' }
3439
+ }
3440
+ }
3441
+
3377
3442
  const registerFetchAttachment = (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback): void => {
3378
3443
  let set = fetchAttachmentCallbacks.get(adapter)
3379
3444
  if (!set) {
@@ -4798,6 +4863,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
4798
4863
  registerHistory,
4799
4864
  unregisterHistory,
4800
4865
  fetchHistory,
4866
+ registerMessageGet,
4867
+ unregisterMessageGet,
4868
+ getMessage,
4869
+ registerList,
4870
+ unregisterList,
4871
+ listChannels,
4801
4872
  registerFetchAttachment,
4802
4873
  unregisterFetchAttachment,
4803
4874
  fetchAttachment,
@@ -5158,6 +5229,7 @@ export function formatAuthorAttribution(adapter: AdapterId, authorId: string, au
5158
5229
  case 'telegram-bot':
5159
5230
  case 'webex':
5160
5231
  case 'webex-bot':
5232
+ case 'instagram':
5161
5233
  case 'line':
5162
5234
  case 'kakaotalk':
5163
5235
  return hasDisplayName ? `${displayName} <${id}>` : id
@@ -5190,6 +5262,7 @@ function formatAuthorReference(adapter: AdapterId, authorId: string, authorName:
5190
5262
  case 'telegram-bot':
5191
5263
  case 'webex':
5192
5264
  case 'webex-bot':
5265
+ case 'instagram':
5193
5266
  case 'line':
5194
5267
  case 'kakaotalk':
5195
5268
  return displayName
@@ -4,6 +4,7 @@ export const ADAPTER_IDS = [
4
4
  'discord',
5
5
  'discord-bot',
6
6
  'github',
7
+ 'instagram',
7
8
  'line',
8
9
  'kakaotalk',
9
10
  'slack',
@@ -266,6 +267,10 @@ export const channelsSchema = z
266
267
  discord: adapterSchema.optional(),
267
268
  'discord-bot': adapterSchema.optional(),
268
269
  github: githubChannelSchema.optional(),
270
+ // Instagram is a personal-account channel: plain-text sends only,
271
+ // alias-only engagement in groups, and DM/group buckets backed by
272
+ // secrets.json#channels.instagram credentials rather than env vars.
273
+ instagram: adapterSchema.optional(),
269
274
  // LINE is a personal-account channel like KakaoTalk: plain-text only,
270
275
  // alias-only engagement (no native @-mention), credentials in
271
276
  // secrets.json#channels.line (not env). Unlike KakaoTalk it has no
@@ -358,6 +358,52 @@ export type FetchHistoryResult =
358
358
  // 'history-not-supported' for those.
359
359
  export type HistoryCallback = (args: FetchHistoryArgs) => Promise<FetchHistoryResult>
360
360
 
361
+ // Fetch a single message by its platform id from an arbitrary chat. Backs the
362
+ // `channel_read` tool's `mode: "message"`. `thread` narrows the lookup on
363
+ // platforms where a message id is only addressable within a thread (Slack
364
+ // thread replies); pass null for channel-root lookups. Reuses
365
+ // `ChannelHistoryMessage` as the result shape — a single message is just a
366
+ // one-element history with the same author/ts/isBot fields.
367
+ export type GetMessageArgs = {
368
+ chat: string
369
+ thread: string | null
370
+ messageId: string
371
+ }
372
+
373
+ export type GetMessageResult =
374
+ | { ok: true; message: ChannelHistoryMessage }
375
+ // `code: 'not-found'` is an expected miss (deleted/wrong id) the tool surfaces
376
+ // as a soft error; `code: 'not-supported'` means no adapter callback is
377
+ // registered, mirroring `fetchHistory`'s 'history-not-supported' contract.
378
+ | { ok: false; error: string; code?: 'not-found' | 'not-supported' }
379
+
380
+ export type MessageGetCallback = (args: GetMessageArgs) => Promise<GetMessageResult>
381
+
382
+ // One channel/chat the bot account can see, returned by `ListCallback`. `chat`
383
+ // is the id the agent passes back to `channel_read`/`channel_send`; `name` is a
384
+ // human label for the agent to recognize. `isMember` is best-effort — omitted
385
+ // when the adapter can't cheaply determine membership.
386
+ export type ChannelListEntry = {
387
+ chat: string
388
+ name: string
389
+ kind: 'channel' | 'dm' | 'group' | 'thread'
390
+ isMember?: boolean
391
+ }
392
+
393
+ export type ListChannelsArgs = {
394
+ workspace: string
395
+ limit: number
396
+ cursor?: string
397
+ }
398
+
399
+ export type ListChannelsResult =
400
+ | { ok: true; entries: ChannelListEntry[]; nextCursor?: string }
401
+ | { ok: false; error: string; code?: 'not-supported' }
402
+
403
+ // Backs the `channel_read` tool's `mode: "list"`. Opt-in per adapter like
404
+ // history; the router answers 'list-not-supported' when none is registered.
405
+ export type ListCallback = (args: ListChannelsArgs) => Promise<ListChannelsResult>
406
+
361
407
  export type FetchAttachmentArgs = {
362
408
  ref: string
363
409
  filename?: string