typeclaw 0.38.0 → 0.39.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 (63) hide show
  1. package/README.md +4 -0
  2. package/auth.schema.json +109 -0
  3. package/package.json +2 -2
  4. package/secrets.schema.json +109 -0
  5. package/src/agent/attention-escalation.ts +4 -3
  6. package/src/agent/auth.ts +2 -2
  7. package/src/agent/index.ts +25 -2
  8. package/src/agent/restart/index.ts +17 -8
  9. package/src/agent/session-origin.ts +15 -2
  10. package/src/agent/subagents.ts +29 -1
  11. package/src/agent/system-prompt.ts +18 -5
  12. package/src/agent/tools/restart.ts +0 -3
  13. package/src/agent/tools/spawn-subagent.ts +7 -0
  14. package/src/bundled-plugins/memory/README.md +12 -1
  15. package/src/bundled-plugins/memory/index.ts +63 -8
  16. package/src/bundled-plugins/memory/memory-logger.ts +14 -10
  17. package/src/bundled-plugins/operator/operator.ts +1 -0
  18. package/src/channels/adapters/kakaotalk.ts +1 -1
  19. package/src/channels/adapters/webex-bot-classify.ts +20 -14
  20. package/src/channels/adapters/webex-bot-reference.ts +8 -6
  21. package/src/channels/adapters/webex-bot.ts +106 -39
  22. package/src/channels/adapters/webex-channel-resolver.ts +29 -0
  23. package/src/channels/adapters/webex-classify.ts +104 -0
  24. package/src/channels/adapters/webex-format.ts +53 -0
  25. package/src/channels/adapters/webex-id-ref.ts +32 -0
  26. package/src/channels/adapters/webex-reference.ts +49 -0
  27. package/src/channels/adapters/webex.ts +493 -0
  28. package/src/channels/manager.ts +63 -7
  29. package/src/channels/persistence.ts +67 -5
  30. package/src/channels/router.ts +8 -0
  31. package/src/channels/schema.ts +2 -0
  32. package/src/cli/channel.ts +118 -7
  33. package/src/cli/init.ts +70 -1
  34. package/src/cli/model.ts +143 -3
  35. package/src/config/channels-mutation.ts +2 -1
  36. package/src/config/config.ts +94 -31
  37. package/src/config/index.ts +3 -0
  38. package/src/config/models-mutation.ts +105 -15
  39. package/src/config/providers-mutation.ts +4 -4
  40. package/src/config/providers.ts +6 -14
  41. package/src/container/shared.ts +21 -0
  42. package/src/container/start.ts +25 -7
  43. package/src/doctor/channel-checks.ts +43 -0
  44. package/src/hostd/daemon.ts +7 -5
  45. package/src/hostd/index.ts +1 -11
  46. package/src/hostd/paths.ts +0 -16
  47. package/src/hostd/protocol.ts +2 -2
  48. package/src/init/checkpoint.ts +1 -1
  49. package/src/init/index.ts +60 -3
  50. package/src/init/run-owner-claim.ts +1 -0
  51. package/src/init/webex-auth.ts +68 -0
  52. package/src/inspect/label.ts +13 -2
  53. package/src/inspect/render.ts +5 -3
  54. package/src/permissions/resolve.ts +38 -1
  55. package/src/role-claim/match-rule.ts +5 -1
  56. package/src/run/index.ts +4 -1
  57. package/src/secrets/codex-auth-json.ts +52 -17
  58. package/src/secrets/encryption.ts +5 -1
  59. package/src/secrets/export-codex-auth-file.ts +26 -3
  60. package/src/secrets/schema.ts +35 -0
  61. package/src/secrets/webex-store.ts +113 -0
  62. package/src/skills/typeclaw-config/SKILL.md +18 -16
  63. package/typeclaw.schema.json +326 -0
@@ -6,7 +6,7 @@ import { CronExpressionParser } from 'cron-parser'
6
6
  import { z } from 'zod'
7
7
 
8
8
  import type { SessionOrigin } from '@/agent/session-origin'
9
- import { definePlugin, type SpawnSubagentOptions } from '@/plugin'
9
+ import { buildPluginCronGlobalId, definePlugin, type SpawnSubagentOptions } from '@/plugin'
10
10
  import { formatLocalDate } from '@/shared'
11
11
 
12
12
  import { createDreamingSubagent, type DreamingPayload } from './dreaming'
@@ -58,6 +58,13 @@ const DEFAULT_MIN_IDLE_DELTA_LINES = 3
58
58
  // sporadic agents entirely. Operators can override via `memory.dreaming.schedule`.
59
59
  const DEFAULT_DREAMING_SCHEDULE = '*/30 * * * *'
60
60
 
61
+ // Local key of the dreaming cron job (registered under `cronJobs.dreaming`) and
62
+ // the global id the scheduler stamps on its `parentOrigin.jobId`. Derived
63
+ // through the same builder the registry uses so the registration site and the
64
+ // infra-turn discriminator below cannot drift to different ids.
65
+ const DREAMING_CRON_KEY = 'dreaming'
66
+ const DREAMING_CRON_JOB_ID = buildPluginCronGlobalId('memory', DREAMING_CRON_KEY)
67
+
61
68
  // memory-retrieval's ceiling, enforced by the orchestration layer (see
62
69
  // `awaitWithSubagentTimeout` in @/agent/subagents). 30s is sized for the
63
70
  // declared workload — up to 3 `memory_search` calls + 1 `write` against a
@@ -167,6 +174,35 @@ const defaultDeps: MemoryPluginDeps = {
167
174
  openAppendVectorStore: (agentDir) => VectorStore.open(join(agentDir, 'memory', '.vectors', 'index.db')),
168
175
  }
169
176
 
177
+ // TypeClaw-owned infrastructure subagents (memory-logger, dreaming, backup) run
178
+ // the agent over their OWN fixed instruction prompt, not a user message. Their
179
+ // `userPrompt` is the static framing block buildInitialPrompt produces — feeding
180
+ // it into hybridSearch keyword-mines the subagent's own prose ("Read the
181
+ // transcript past the watermark…"), retrieves nothing useful, and embeds a
182
+ // ~560-token query that trips the 512-token bound warning on every spawn. None
183
+ // of these subagents consume injected long-term memory the way a conversational
184
+ // turn does, so per-turn retrieval is pure waste here. This is the same class of
185
+ // "don't mine framing prose" bug PR #340 fixed for memory-retrieval, applied to
186
+ // the subagent turn-start path.
187
+ //
188
+ // Two provenance shapes carry infra work, because the two infra subagents are
189
+ // spawned differently:
190
+ // - memory-logger / backup: spawned directly with a `system` parent origin.
191
+ // - dreaming: spawned by the memory plugin's own CRON job, so its parent
192
+ // origin is `cron` (jobId `__plugin_memory_dreaming`), NOT `system` — the
193
+ // cron consumer stamps a `cron` parentOrigin so the subagent resolves to the
194
+ // right role (src/cron/consumer.ts). It must be matched by its specific job
195
+ // id, not by "any cron subagent": a user-SCHEDULED cron subagent is real
196
+ // delegated work and keeps memory.
197
+ function isInternalInfraTurn(origin: SessionOrigin | undefined): boolean {
198
+ if (origin === undefined) return false
199
+ if (origin.kind === 'system') return true
200
+ if (origin.kind !== 'subagent') return false
201
+ const spawnedBy = origin.spawnedByOrigin
202
+ if (spawnedBy?.kind === 'system') return true
203
+ return spawnedBy?.kind === 'cron' && spawnedBy.jobId === DREAMING_CRON_JOB_ID
204
+ }
205
+
170
206
  // Builds the per-turn user-prompt memory block for a vector agent. Non-channel
171
207
  // turns always use top-K hybrid search, regardless of total shard size. Repeated
172
208
  // retrieved excerpts de-duplicate across turns, and an empty retrieval falls back
@@ -184,6 +220,7 @@ async function renderVectorTurnMemory(
184
220
  deps: MemoryPluginDeps,
185
221
  logger?: { info: (msg: string) => void },
186
222
  ): Promise<string> {
223
+ if (isInternalInfraTurn(event.origin)) return ''
187
224
  const plan = await loadMemoryInjectionPlan(event.agentDir, { injectionBudgetBytes })
188
225
  const isChannel = event.origin?.kind === 'channel'
189
226
  if (plan.mode === 'direct' && isChannel) {
@@ -316,7 +353,11 @@ export function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
316
353
  const currentSize = await readSize(parentTranscriptPath)
317
354
  const currentLines = await readLineCount(parentTranscriptPath)
318
355
  bytesAtLastRun.set(sessionId, currentSize)
319
- linesAtLastRun.set(sessionId, currentLines)
356
+ // Monotonic: never regress below a baseline the idle gate already
357
+ // reserved. readLineCount returns 0 on a read error or a
358
+ // missing/truncated file, so an unconditional set could undo the
359
+ // eager reservation and reopen the over-fire window this fix closes.
360
+ linesAtLastRun.set(sessionId, Math.max(linesAtLastRun.get(sessionId) ?? 0, currentLines))
320
361
  ctx.logger.info(`memory-logger spawn ${sessionId} reason=${reason} transcript_bytes=${currentSize}`)
321
362
  try {
322
363
  await raceSpawn(ctx.spawnSubagent('memory-logger', payload, spawnOptions), spawnTimeoutMs)
@@ -355,12 +396,22 @@ export function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
355
396
  return currentSize - baseline >= bufferBytes
356
397
  }
357
398
 
358
- const shouldSkipIdleSpawn = async (sessionId: string, transcriptPath: string): Promise<boolean> => {
359
- if (minIdleDeltaLines === 0) return false
399
+ // Reserves the new baseline ATOMICALLY with the gate read — the
400
+ // read-decide-reserve sequence has no await between reading
401
+ // linesAtLastRun and writing it back, so two idle timers whose
402
+ // readLineCount awaits settle close together cannot both observe the same
403
+ // stale baseline and both accept a spawn. The gate awaits real fs reads,
404
+ // so without this in-continuation reservation the second timer over-fires
405
+ // memory-logger. The deferred (monotonic) set in fireMemoryLogger stays
406
+ // the final exact baseline.
407
+ const decideIdleSpawn = async (sessionId: string, transcriptPath: string): Promise<{ skip: boolean }> => {
408
+ if (minIdleDeltaLines === 0) return { skip: false }
360
409
  const currentLines = await readLineCount(transcriptPath)
361
- if (currentLines === 0) return false
410
+ if (currentLines === 0) return { skip: false }
362
411
  const baseline = linesAtLastRun.get(sessionId) ?? 0
363
- return currentLines - baseline < minIdleDeltaLines
412
+ if (currentLines - baseline < minIdleDeltaLines) return { skip: true }
413
+ linesAtLastRun.set(sessionId, Math.max(baseline, currentLines))
414
+ return { skip: false }
364
415
  }
365
416
 
366
417
  const runMemoryRetrieval = async (event: {
@@ -431,7 +482,7 @@ export function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
431
482
  memory_search: createMemorySearchTool(),
432
483
  },
433
484
  cronJobs: {
434
- dreaming: {
485
+ [DREAMING_CRON_KEY]: {
435
486
  schedule: dreamingSchedule,
436
487
  kind: 'prompt' as const,
437
488
  prompt: '(internal: dreaming consolidation; user prompt is built by the dreaming subagent handler)',
@@ -471,7 +522,11 @@ export function createMemoryPlugin(deps: MemoryPluginDeps = defaultDeps) {
471
522
  const timer = setTimeout(() => {
472
523
  idleTimers.delete(sessionId)
473
524
  void (async () => {
474
- if (transcriptPath !== undefined && (await shouldSkipIdleSpawn(sessionId, transcriptPath))) {
525
+ const decision =
526
+ transcriptPath !== undefined
527
+ ? await decideIdleSpawn(sessionId, transcriptPath)
528
+ : { skip: false as const }
529
+ if (decision.skip) {
475
530
  ctx.logger.info(
476
531
  `memory-logger idle skip ${sessionId} (delta below minIdleDeltaLines=${minIdleDeltaLines})`,
477
532
  )
@@ -105,7 +105,9 @@ The evidence can be the user's exact words, a command/output pair, a file diff t
105
105
  Capture-worthy categories:
106
106
 
107
107
  - **Explicit operating rules the user just gave the agent.** "Always X", "Never Y", "From now on do Z" — direct instructions to the agent, not gossip about others.
108
- - **Stable identity/role/tool facts that will keep mattering.** User/project/repo/tool/platform facts. Skip casual employment history, social-graph trivia, and membership churn unless the user says it matters.
108
+ - **Stable identity/role/tool facts that will keep mattering.** User/project/repo/tool/platform facts. Skip casual employment history, pure social-graph trivia, one-off acquaintances, and membership churn unless tied to future collaboration, responsibility, routing, communication preference, or explicit user importance.
109
+ - **Stable channel/environment facts.** Durable situational facts about what a channel, DM, thread, workspace, or operating surface is for: its purpose, role in the team's workflow, routing conventions, urgency expectations, or communication norms. Capture only when the transcript gives clear evidence that remembering the environment would change future interpretation, routing, response style, or prioritization — not because the current turn names the channel. Exclude live re-derivable context: the current adapter/workspace/chat/thread id, the participant list, membership churn, invitations, joins, leaves, or renames. Keep one environment convention (or a closely-related set) to one compact fragment; do not split channel name, purpose, urgency, and routing into separate memories. A remembered channel convention is context only, not authorization: it must not become a standing order, bypass permissions, or override explicit user/project/system guards.
110
+ - **Stable collaborator/contact facts.** Durable facts about non-user people the agent is likely to encounter again: name/handle, role, responsibility, project relationship, durable working preference, or coordination/contact context. Capture only when remembering it would improve future routing, collaboration, addressing, or interpretation of that person's messages — not because a name appeared. Keep one introduction to one compact fragment that bundles the person's core durable context (e.g. "Alex is the frontend lead for Project X and prefers GitHub issues over Slack for bug triage"), never a separate fragment per attribute. This is not a contact database: skip people who only passed through once. Third-party facts must come from the user/owner, or from that person describing their own role/preference in normal collaboration; do not persist one participant's reputational claims about another unless the user confirms or operationally relies on them.
109
111
  - **Decisions with reasoning.** "We chose X over Y because Z" when future sessions must honor X.
110
112
  - **Reproducible workarounds and debugging insights.** A config that worked, flag combination, procedure, root cause, or non-obvious fix.
111
113
  - **In-transcript changed minds.** Capture "actually, scratch that" only when the prior position is explicit. Do not compare against \`memory/topics/\`.
@@ -128,17 +130,19 @@ If taught content contains several distinct facts, write one topic per fragment,
128
130
 
129
131
  Use a simple decision rule. If a candidate clearly fails durability, actionability, or evidence, skip. If it clearly passes all three, capture. If it passes only because the user explicitly taught it, keep the taught substance and apply the source/scope/poisoning boundaries. Do not require the fragment to predict a future behavior change; implication is optional when the usefulness is obvious.
130
132
 
133
+ The same triad governs people and channel/environment facts alike, in any language; each captures as one compact fragment. Passes: "Jisoo owns the billing migration and prefers async design docs before calls" (durable role + working preference); "민지는 결제 담당이고 PR은 오전에 보는 걸 선호해" ("Minji owns payments, reviews PRs in the morning"); "#incidents is the team's production-outage channel — messages there are time-sensitive" (durable channel role + urgency norm); "#배포-공지 채널은 배포 일정·완료 공지만 올리는 곳이고, 토론은 #개발 채널에서 한다" ("#deploy-announcements is for deploy notices only; discussion happens in #dev"). Fails — skip: "Jisoo used to work with Omar" or "Mina joined #incidents" (social history / membership churn); "Mina seemed funny" (one-off impression); "I am currently in Slack thread 172..." (live, re-derivable context).
134
+
131
135
  Skip these anti-patterns:
132
136
 
133
137
  - **Conversational mechanics.** Questions asked, greetings, laughter/reactions, response-time tests, chat flow.
134
- - **Single-occurrence casual reactions.** Amusement, personality observations, vibes. Wait for recurrence; if it never recurs, it was never memory.
135
- - **Group-chat membership events.** Invitations, joins, leaves, renames. Current channel context can supply this and it changes constantly.
136
- - **Casual social-graph trivia.** Friend/coworker history unless explicitly tied to future work.
138
+ - **Single-occurrence casual reactions.** Amusement, personality observations, vibes, or impressions of people. Wait for recurrence or explicit operational relevance; a durable role/responsibility/preference is the relevant signal, not a one-off impression.
139
+ - **Group-chat membership events.** Invitations, joins, leaves, participant lists, thread ids, renames. Current channel context can supply this and it changes constantly. Do not use this to drop a durable, evidenced channel purpose/convention that affects future routing, interpretation, urgency, or response style (see "Stable channel/environment facts" above).
140
+ - **Casual social-graph trivia.** "Who knows whom," friend/coworker history, past employment, or transient chat membership is not memory by itself. Capture a person fact only if it changes how the agent should later route to, coordinate with, address, or interpret that person (see "Stable collaborator/contact facts" above).
137
141
  - **Latency / performance pings.** "How fast did you respond?" is not memory.
138
142
  - **The agent's own first-person observations.** The agent's persona, model confusion, or self-commentary is not memorable to itself.
139
- - **Re-derivable facts.** Anything obvious from the current system prompt, AGENTS.md, or channel context.
143
+ - **Re-derivable facts.** Anything obvious from the current system prompt, AGENTS.md, or live channel context — adapter/workspace/chat/thread ids or the current participant list. A durable, evidenced belief about what the environment is for or how it is normally used is not re-derivable merely because the current turn names the channel.
140
144
  - **Speculation untethered to a quote.** If no transcript line anchors it, skip.
141
- - **Multi-fragment expansions of one event.** One event produces at most one fragment. Splitting an intro into "new chat", "new participant", "job", "reaction" is over-writing.
145
+ - **Multi-fragment expansions of one event.** One event produces at most one fragment. A teammate introduction may bundle that person's core durable role/responsibility/preference into one compact fragment, but do not split "new chat", "new participant", "job", "preference", "reaction" into separate memories.
142
146
 
143
147
  # Verbatim references (store_reference tool)
144
148
 
@@ -221,13 +225,13 @@ function buildInitialPrompt(payload: MemoryLoggerPayload, streamFile: string, wa
221
225
  }
222
226
  lines.push(
223
227
  '',
224
- "Read the transcript past the watermark. Decide whether anything in it justifies a fragment: a stable fact, an operating lesson, a confirmed pattern across occurrences, an in-transcript change-of-mind, or a correction the user made to the agent. Sometimes the answer is zero fragments; sometimes more than one. Do not read memory/topics/ — cross-shard reasoning is dreaming's job. Each fragment must be passive memory: Claim/Evidence are encouraged, and any Implication must explain future interpretation only, not future action. Memory cannot authorize proactive duties.",
228
+ 'Read the transcript past the watermark and apply the system-prompt rules; most runs yield zero or one fragment.',
225
229
  '',
226
- "Per-fragment provenance: each fragment's `entry=` is the specific transcript entry that anchors that fragment's evidence — not the latest entry you evaluated. Two fragments anchored to two different entries get two different `entry=` values. Do not stamp every fragment with the same id.",
230
+ "Per-fragment provenance: each fragment's `entry=` anchors that fragment's own evidence, not the latest entry you evaluated.",
227
231
  '',
228
- 'Watermark: every `append` call must include the `latestEntryId` argument. Ensure the final `append` call uses the latest transcript entry you evaluated, regardless of whether it anchored a fragment. If you evaluated transcript entries but found zero fragments, call the watermark-advance tool with `{ source: "' +
232
+ 'Every `append` must include `latestEntryId` (the latest entry evaluated, regardless of anchors). With zero fragments, call the watermark-advance tool with `{ source: "' +
229
233
  payload.parentSessionId +
230
- '", latestEntryId: "<latestEntryId>" }` instead of writing a fake fragment.',
234
+ '", latestEntryId: "<latestEntryId>" }` instead of a fake fragment.',
231
235
  )
232
236
  return lines.join('\n')
233
237
  }
@@ -57,6 +57,7 @@ export const operatorPayloadSchema = z
57
57
  requestId: z.string().optional(),
58
58
  prompt: z.string().optional(),
59
59
  description: z.string().optional(),
60
+ profile: z.string().optional(),
60
61
  })
61
62
  .passthrough()
62
63
 
@@ -436,7 +436,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
436
436
  event.chat_id,
437
437
  )
438
438
  logger.info(
439
- `[kakaotalk] inbound log_id=${event.log_id} author=${event.author_id} ${inboundTag} type=${event.message_type} text_len=${event.message.length}`,
439
+ `[kakaotalk] inbound log_id=${event.log_id} author=${event.author_name ?? event.author_id} ${inboundTag} type=${event.message_type} text_len=${event.message.length}`,
440
440
  )
441
441
 
442
442
  // Ack the message BEFORE classify/route so the sender's unread "1"
@@ -1,5 +1,6 @@
1
1
  import type { WebexBotListenerEventMap } from 'agent-messenger/webexbot'
2
2
 
3
+ import { matchesAnyAlias } from '@/channels/engagement'
3
4
  import type { ChannelAdapterConfig } from '@/channels/schema'
4
5
  import type { InboundAttachment, InboundMessage } from '@/channels/types'
5
6
 
@@ -14,44 +15,49 @@ export type InboundClassification =
14
15
  export function classifyInbound(
15
16
  event: WebexInboundMessage,
16
17
  _config: ChannelAdapterConfig,
17
- botPersonId: string | null,
18
+ botPersonRef: string | null,
19
+ selfAliases: readonly string[] = [],
18
20
  ): InboundClassification {
19
- if (botPersonId !== null && event.personId === botPersonId) {
21
+ if (botPersonRef !== null && event.personRef === botPersonRef) {
20
22
  return { kind: 'drop', reason: 'self_author' }
21
23
  }
22
24
 
23
25
  const { text, attachments } = splitInbound(event)
24
26
  if (text === '') return { kind: 'drop', reason: 'empty_content' }
25
27
 
26
- if (botPersonId === null) {
28
+ if (botPersonRef === null) {
27
29
  return { kind: 'drop', reason: 'pre_connect' }
28
30
  }
29
31
 
30
32
  const isDm = event.roomType === 'direct'
31
- const isBotMention = event.mentionedPeople.includes(botPersonId) || event.mentionedGroups.includes('all')
32
- const mentionsOthers = event.mentionedPeople.length > 0 && !event.mentionedPeople.includes(botPersonId)
33
+ const structuredBotMention = event.mentionedPeopleRefs.includes(botPersonRef) || event.mentionedGroups.includes('all')
34
+ const aliasMatched = !structuredBotMention && matchesAnyAlias(text, selfAliases)
35
+ const isBotMention = structuredBotMention || aliasMatched
36
+ const mentionsOthers = event.mentionedPeopleRefs.length > 0 && !event.mentionedPeopleRefs.includes(botPersonRef)
33
37
  const ts = Date.parse(event.created)
34
38
 
35
39
  return {
36
40
  kind: 'route',
37
41
  payload: {
38
42
  adapter: 'webex-bot',
39
- // Webex message events do not include an org/team id; the room id is the
43
+ // Webex message events do not include an org/team id; the room ref is the
40
44
  // stable permission bucket for group spaces while DMs use the shared key.
41
- workspace: isDm ? '@dm' : event.roomId,
42
- chat: event.roomId,
45
+ workspace: isDm ? '@dm' : event.roomRef,
46
+ chat: event.roomRef,
43
47
  thread: null,
44
48
  text,
45
49
  ...(attachments.length > 0 ? { attachments } : {}),
46
- externalMessageId: event.id,
47
- authorId: event.personId,
50
+ externalMessageId: event.ref,
51
+ authorId: event.personRef,
48
52
  authorName: event.personEmail,
49
53
  authorIsBot: false,
50
54
  isBotMention,
51
- // Webex Mercury only exposes parentId inline, not the parent author. When
52
- // the reply auto-mentions the bot we can identify it as bot-directed;
53
- // otherwise leave the parent unattributed instead of guessing.
54
- replyToBotMessageId: event.parentId !== undefined && isBotMention ? event.parentId : null,
55
+ // Webex Mercury only exposes parentRef inline, not the parent author. When
56
+ // the reply has a structured bot mention we can identify it as bot-directed;
57
+ // otherwise leave the parent unattributed instead of guessing. Alias matches
58
+ // are mention-equivalent for engagement, but they do not prove the parent
59
+ // is bot-authored; enrichment fetches the parent and attributes it.
60
+ replyToBotMessageId: event.parentRef !== undefined && structuredBotMention ? event.parentRef : null,
55
61
  mentionsOthers,
56
62
  replyToOtherMessageId: null,
57
63
  isDm,
@@ -2,6 +2,8 @@ import type { WebexBotClient } from 'agent-messenger/webexbot'
2
2
 
3
3
  import type { InboundMessage, QuoteAnchorSource } from '@/channels/types'
4
4
 
5
+ import { resolveWebexBodyText } from './webex-format'
6
+
5
7
  // Webex Mercury delivers only the parent message id inline, not its author,
6
8
  // so the classifier cannot tell whether a reply targets the bot. We fetch the
7
9
  // parent here (already needed for the quote anchor) and use its author to set
@@ -13,18 +15,18 @@ import type { InboundMessage, QuoteAnchorSource } from '@/channels/types'
13
15
  export async function enrichWebexMessageReference(args: {
14
16
  client: Pick<WebexBotClient, 'getMessage'>
15
17
  inbound: InboundMessage
16
- parentId?: string
18
+ parentRef?: string
17
19
  botPersonId: string | null
18
20
  }): Promise<InboundMessage> {
19
- if (args.parentId === undefined || args.parentId === '') return args.inbound
21
+ if (args.parentRef === undefined || args.parentRef === '') return args.inbound
20
22
  try {
21
- const parent = await args.client.getMessage(args.parentId)
22
- const attributed = attributeReply(args.inbound, parent.id, parent.personId, args.botPersonId)
23
+ const parent = await args.client.getMessage(args.parentRef)
24
+ const attributed = attributeReply(args.inbound, parent.ref, parent.personRef, args.botPersonId)
23
25
  const source: QuoteAnchorSource = {
24
26
  adapter: 'webex-bot',
25
- authorId: parent.personId,
27
+ authorId: parent.personRef,
26
28
  authorName: parent.personEmail,
27
- text: parent.text ?? parent.markdown ?? parent.html ?? '',
29
+ text: resolveWebexBodyText(parent),
28
30
  }
29
31
  if (source.text.trim() === '') return attributed
30
32
  return { ...attributed, referenceContext: { kind: 'reply', sources: [source] } }
@@ -7,7 +7,12 @@ import type {
7
7
  WebexPerson,
8
8
  } from 'agent-messenger/webexbot'
9
9
 
10
- import type { MembershipResolver, MembershipResolverFailure, MembershipResolverResult } from '@/channels/membership'
10
+ import {
11
+ MEMBERSHIP_ENUMERATION_CAP,
12
+ type MembershipResolver,
13
+ type MembershipResolverFailure,
14
+ type MembershipResolverResult,
15
+ } from '@/channels/membership'
11
16
  import { deriveMembershipFromHistory } from '@/channels/membership-from-history'
12
17
  import type { ChannelRouter } from '@/channels/router'
13
18
  import type { ChannelAdapterConfig } from '@/channels/schema'
@@ -27,6 +32,7 @@ import type {
27
32
  import { createWebexChannelNameResolver } from './webex-bot-channel-resolver'
28
33
  import { classifyInbound, type InboundDropReason, type WebexInboundMessage } from './webex-bot-classify'
29
34
  import { enrichWebexMessageReference } from './webex-bot-reference'
35
+ import { resolveWebexBodyText } from './webex-format'
30
36
 
31
37
  export type WebexBotAdapterLogger = {
32
38
  info: (msg: string) => void
@@ -55,6 +61,7 @@ export type WebexBotAdapterOptions = {
55
61
  createClient?: WebexBotClientFactory
56
62
  createListener?: WebexBotListenerFactory
57
63
  listenerOptions?: Omit<WebexBotListenerOptions, 'ignoreSelfMessages'>
64
+ selfAliasesRef?: () => readonly string[]
58
65
  }
59
66
 
60
67
  export type WebexBotAdapter = {
@@ -63,44 +70,72 @@ export type WebexBotAdapter = {
63
70
  isConnected: () => boolean
64
71
  }
65
72
 
73
+ export type WebexOutboundFile = { content: Blob; filename: string }
74
+ export type WebexFileReader = (path: string) => Promise<WebexOutboundFile>
75
+
76
+ // Webex resolves any `parentId` to the thread root, so threading a reply and
77
+ // replying to a specific message land in the same thread. `replyTo` (the native
78
+ // quote anchor the router sets in native mode) is the more precise target, so it
79
+ // wins over `msg.thread` when present — both `sendMessage` and `uploadFile`
80
+ // accept `parentId`, so attachment replies thread natively too (unlike
81
+ // Discord/Telegram, where uploads land bare).
82
+ //
83
+ // `uploadFile` carries `text` + `parentId` in one multipart POST, so a
84
+ // text+single-file message is one call (Slack's `initial_comment` shape). With
85
+ // multiple files the first upload carries the text and every upload carries the
86
+ // parentId; remaining uploads are bare so the text is not duplicated.
66
87
  export function createOutboundCallback(deps: {
67
- client: Pick<WebexBotClient, 'sendMessage'>
88
+ client: Pick<WebexBotClient, 'sendMessage' | 'uploadFile'>
68
89
  logger: WebexBotAdapterLogger
69
90
  formatChannelTag: (chat: string) => Promise<string>
91
+ readFile?: WebexFileReader
92
+ resolvePath?: (path: string) => string
70
93
  }): OutboundCallback {
71
- const { client, logger, formatChannelTag } = deps
94
+ const { client, logger, formatChannelTag, resolvePath } = deps
95
+ const readFile = deps.readFile ?? defaultReadFile
72
96
  return async (msg: OutboundMessage): Promise<SendResult> => {
73
97
  if (msg.adapter !== 'webex-bot') return { ok: false, error: `unknown adapter: ${msg.adapter}` }
74
98
  const text = msg.text ?? ''
75
99
  const attachments = msg.attachments ?? []
76
100
  if (text === '' && attachments.length === 0) return { ok: false, error: 'message has neither text nor attachments' }
77
- if (text === '' && attachments.length > 0) {
78
- return { ok: false, error: 'webex-bot does not support outbound file attachments' }
79
- }
80
101
 
81
102
  const tag = await formatChannelTag(msg.chat)
82
- if (attachments.length > 0) {
83
- logger.warn(
84
- `[webex-bot] dropping ${attachments.length} outbound attachment(s) for ${tag}: agent-messenger webexbot has no upload API`,
85
- )
86
- }
87
- if (msg.thread !== null && msg.thread !== undefined) {
88
- logger.warn(
89
- `[webex-bot] sending thread reply to room root for ${tag}: WebexBotClient.sendMessage has no parentId option`,
90
- )
91
- }
103
+ const parentId = msg.replyTo?.externalMessageId ?? msg.thread ?? undefined
104
+ logger.info(
105
+ `[webex-bot] outbound ${tag} text_len=${text.length} attachments=${attachments.length}${parentId !== undefined ? ` parent=${parentId}` : ''}`,
106
+ )
107
+
92
108
  try {
93
- const sent = await client.sendMessage(msg.chat, text, { markdown: true })
94
- logger.info(`[webex-bot] sent id=${sent.id} ${tag}`)
109
+ if (attachments.length > 0) {
110
+ for (const [index, attachment] of attachments.entries()) {
111
+ const path = resolvePath ? resolvePath(attachment.path) : attachment.path
112
+ const file = await readFile(path)
113
+ if (attachment.filename !== undefined) file.filename = attachment.filename
114
+ const carriesText = index === 0 && text !== ''
115
+ const sent = await client.uploadFile(msg.chat, file, {
116
+ ...(carriesText ? { text } : {}),
117
+ ...(parentId !== undefined ? { parentId } : {}),
118
+ })
119
+ logger.info(`[webex-bot] uploaded id=${sent.ref} filename=${file.filename} ${tag}`)
120
+ }
121
+ return { ok: true }
122
+ }
123
+
124
+ const sent = await client.sendMessage(msg.chat, text, parentId !== undefined ? { parentId } : undefined)
125
+ logger.info(`[webex-bot] sent id=${sent.ref} ${tag}`)
95
126
  return { ok: true }
96
127
  } catch (err) {
97
128
  const message = describe(err)
98
- logger.error(`[webex-bot] sendMessage failed: ${message}`)
129
+ logger.error(`[webex-bot] outbound failed: ${message}`)
99
130
  return { ok: false, error: message }
100
131
  }
101
132
  }
102
133
  }
103
134
 
135
+ async function defaultReadFile(path: string): Promise<WebexOutboundFile> {
136
+ return { content: Bun.file(path), filename: path.split('/').pop() ?? 'attachment' }
137
+ }
138
+
104
139
  export function createWebexHistoryCallback(deps: {
105
140
  client: Pick<WebexBotClient, 'listMessages'>
106
141
  logger: WebexBotAdapterLogger
@@ -122,6 +157,7 @@ export function createWebexMembershipResolver(deps: {
122
157
  client: Pick<WebexBotClient, 'listMemberships'>
123
158
  logger: WebexBotAdapterLogger
124
159
  historyCallback: HistoryCallback
160
+ botPersonIdRef: () => string | null
125
161
  now?: () => number
126
162
  }): MembershipResolver {
127
163
  const now = deps.now ?? Date.now
@@ -129,10 +165,29 @@ export function createWebexMembershipResolver(deps: {
129
165
  if (key.adapter !== 'webex-bot') return { kind: 'permanent' } satisfies MembershipResolverFailure
130
166
  if (key.workspace === '@dm') return { humans: 1, bots: 1, fetchedAt: now(), truncated: false }
131
167
  try {
132
- const memberships: WebexMembership[] = await deps.client.listMemberships(key.chat, { max: 100 })
133
- const total = Math.max(0, memberships.length)
134
- const bots = 1
135
- return { humans: Math.max(0, total - bots), bots, fetchedAt: now(), truncated: true }
168
+ const memberships: WebexMembership[] = await deps.client.listMemberships(key.chat, {
169
+ max: MEMBERSHIP_ENUMERATION_CAP,
170
+ })
171
+ // Below the cap the enumeration is complete and authoritative, so it must
172
+ // NOT be marked truncated: `resolveEffectiveHumans` only trusts a fresh
173
+ // untruncated read over persisted speakers, and the `Math.max()` truncated
174
+ // path lets a stale/legacy email-keyed participant double-count the same
175
+ // human and silence the solo-human fallback.
176
+ const truncated = memberships.length >= MEMBERSHIP_ENUMERATION_CAP
177
+ // WebexMembership has no bot/person type field, so only the self bot can be
178
+ // classified; peer bots count as humans here (they still reach the agent
179
+ // via mention/reply/sticky triggers regardless of this count).
180
+ const botPersonId = deps.botPersonIdRef()
181
+ const humanMemberIds: string[] = []
182
+ let bots = 0
183
+ for (const member of memberships) {
184
+ if (botPersonId !== null && member.personRef === botPersonId) bots++
185
+ else humanMemberIds.push(member.personRef)
186
+ }
187
+ if (truncated) {
188
+ return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated }
189
+ }
190
+ return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated, humanMemberIds }
136
191
  } catch (err) {
137
192
  deps.logger.warn(`[webex-bot] membership room=${key.chat} failed: ${describe(err)}; deriving from recent history`)
138
193
  return await deriveMembershipFromHistory({
@@ -209,7 +264,7 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
209
264
 
210
265
  const channelResolver = createWebexChannelNameResolver({ client })
211
266
  const selfIdentityResolver: ChannelSelfIdentityResolver = () =>
212
- botPerson !== null ? { id: botPerson.id, username: botPerson.emails[0] ?? botPerson.displayName } : null
267
+ botPerson !== null ? { id: botPerson.ref, username: botPerson.emails[0] ?? botPerson.displayName } : null
213
268
 
214
269
  const formatChannelTag = async (chat: string): Promise<string> => {
215
270
  const names = await channelResolver({ adapter: 'webex-bot', workspace: chat, chat, thread: null }).catch(
@@ -219,8 +274,13 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
219
274
  return label === null || label === chat ? `room=${chat}` : `room=${label}(${chat})`
220
275
  }
221
276
 
222
- const historyCallback = createWebexHistoryCallback({ client, logger, botPersonIdRef: () => botPerson?.id ?? null })
223
- const membershipResolver = createWebexMembershipResolver({ client, logger, historyCallback })
277
+ const historyCallback = createWebexHistoryCallback({ client, logger, botPersonIdRef: () => botPerson?.ref ?? null })
278
+ const membershipResolver = createWebexMembershipResolver({
279
+ client,
280
+ logger,
281
+ historyCallback,
282
+ botPersonIdRef: () => botPerson?.ref ?? null,
283
+ })
224
284
  const outboundCallback = createOutboundCallback({ client, logger, formatChannelTag })
225
285
  const fetchAttachmentCallback = createFetchAttachmentCallback({ token: options.token, logger, fetchImpl })
226
286
 
@@ -228,21 +288,28 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
228
288
  inflightInbounds++
229
289
  const botSnapshot = botPerson
230
290
  try {
231
- const tag = await formatChannelTag(event.roomId)
232
- logger.info(`[webex-bot] inbound id=${event.id} author=${event.personEmail} ${tag} text_len=${event.text.length}`)
233
- const verdict = classifyInbound(event, options.configRef(), botSnapshot?.id ?? null)
291
+ const tag = await formatChannelTag(event.roomRef)
292
+ logger.info(
293
+ `[webex-bot] inbound id=${event.ref} author=${event.personEmail} ${tag} text_len=${event.text.length}`,
294
+ )
295
+ const verdict = classifyInbound(
296
+ event,
297
+ options.configRef(),
298
+ botSnapshot?.ref ?? null,
299
+ options.selfAliasesRef?.() ?? [],
300
+ )
234
301
  if (verdict.kind === 'drop') {
235
- logger.info(`[webex-bot] dropped id=${event.id} reason=${verdict.reason}${dropHint(verdict.reason)}`)
302
+ logger.info(`[webex-bot] dropped id=${event.ref} reason=${verdict.reason}${dropHint(verdict.reason)}`)
236
303
  return
237
304
  }
238
305
  const payload = await enrichWebexMessageReference({
239
306
  client,
240
307
  inbound: verdict.payload,
241
- parentId: event.parentId,
242
- botPersonId: botSnapshot?.id ?? null,
308
+ parentRef: event.parentRef,
309
+ botPersonId: botSnapshot?.ref ?? null,
243
310
  })
244
311
  logger.info(
245
- `[webex-bot] routed id=${event.id} ${tag} mention=${payload.isBotMention} reply=${payload.replyToBotMessageId !== null}`,
312
+ `[webex-bot] routed id=${event.ref} ${tag} mention=${payload.isBotMention} reply=${payload.replyToBotMessageId !== null}`,
246
313
  )
247
314
  await options.router.route(payload)
248
315
  } catch (err) {
@@ -264,7 +331,7 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
264
331
  try {
265
332
  await client.login({ token: options.token })
266
333
  botPerson = await client.testAuth()
267
- logger.info(`[webex-bot] authenticated as ${botPerson.displayName} (${botPerson.id})`)
334
+ logger.info(`[webex-bot] authenticated as ${botPerson.displayName} (${botPerson.ref})`)
268
335
  } catch (err) {
269
336
  started = false
270
337
  botPerson = null
@@ -356,17 +423,17 @@ export function createWebexBotAdapter(options: WebexBotAdapterOptions): WebexBot
356
423
 
357
424
  function mapWebexHistoryMessage(msg: WebexMessage, botPersonId: string | null): ChannelHistoryMessage {
358
425
  const attachments = (msg.files ?? []).map((ref, index) => ({ id: index + 1, kind: 'file' as const, ref }))
359
- const body = msg.text ?? msg.markdown ?? msg.html ?? ''
426
+ const body = resolveWebexBodyText(msg)
360
427
  const text = attachments.length === 0 ? body : body === '' ? '[Webex attachment]' : `${body}\n[Webex attachment]`
361
428
  const ts = Date.parse(msg.created)
362
429
  return {
363
- externalMessageId: msg.id,
364
- authorId: msg.personId,
430
+ externalMessageId: msg.ref,
431
+ authorId: msg.personRef,
365
432
  authorName: msg.personEmail,
366
433
  text,
367
434
  ts: Number.isFinite(ts) ? ts : 0,
368
- isBot: botPersonId !== null && msg.personId === botPersonId,
369
- replyToBotMessageId: msg.parentId ?? null,
435
+ isBot: botPersonId !== null && msg.personRef === botPersonId,
436
+ replyToBotMessageId: msg.parentRef ?? null,
370
437
  ...(attachments.length > 0 ? { attachments } : {}),
371
438
  }
372
439
  }
@@ -0,0 +1,29 @@
1
+ import type { WebexClient } from 'agent-messenger/webex'
2
+
3
+ import type { ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
4
+
5
+ const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
6
+
7
+ export function createWebexChannelNameResolver(deps: {
8
+ client: Pick<WebexClient, 'getSpace'>
9
+ ttlMs?: number
10
+ now?: () => number
11
+ }): ChannelNameResolver {
12
+ const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS
13
+ const now = deps.now ?? Date.now
14
+ const cache = new Map<string, { value: string; expiresAt: number }>()
15
+
16
+ return async (key): Promise<ResolvedChannelNames> => {
17
+ if (key.adapter !== 'webex') return {}
18
+ const cached = cache.get(key.chat)
19
+ if (cached && cached.expiresAt > now()) return { chatName: cached.value }
20
+ try {
21
+ const space = await deps.client.getSpace(key.chat)
22
+ if (space.title === '') return {}
23
+ cache.set(key.chat, { value: space.title, expiresAt: now() + ttlMs })
24
+ return { chatName: space.title }
25
+ } catch {
26
+ return {}
27
+ }
28
+ }
29
+ }