typeclaw 0.48.12 → 0.49.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 (213) hide show
  1. package/package.json +6 -3
  2. package/scripts/dump-system-prompt.ts +52 -110
  3. package/src/agent/attention-escalation.ts +8 -5
  4. package/src/agent/auth-reloadable.ts +2 -3
  5. package/src/agent/auth.ts +59 -79
  6. package/src/agent/compaction.ts +2 -2
  7. package/src/agent/index.ts +173 -85
  8. package/src/agent/live-sessions.ts +2 -2
  9. package/src/agent/live-subagents.ts +1 -0
  10. package/src/agent/llm-replay-sanitizer.ts +1 -1
  11. package/src/agent/model-overrides.ts +1 -1
  12. package/src/agent/multimodal/look-at.ts +3 -3
  13. package/src/agent/multimodal/read-redirect.ts +1 -1
  14. package/src/agent/plugin-tools.ts +76 -39
  15. package/src/agent/prompt-cache-key.ts +42 -0
  16. package/src/agent/provider-error.ts +179 -10
  17. package/src/agent/reload-tool.ts +1 -1
  18. package/src/agent/restart-handoff/index.ts +7 -14
  19. package/src/agent/reviewer-activity.ts +68 -0
  20. package/src/agent/session-origin.ts +33 -0
  21. package/src/agent/subagents.ts +14 -2
  22. package/src/agent/system-prompt.ts +68 -202
  23. package/src/agent/todo/continuation-policy.ts +12 -4
  24. package/src/agent/tool-error-remediation.ts +1 -1
  25. package/src/agent/tool-file-safety.ts +113 -14
  26. package/src/agent/tool-not-found-nudge.ts +1 -1
  27. package/src/agent/tool-result-budget.ts +2 -2
  28. package/src/agent/tools/channel-disengage.ts +2 -2
  29. package/src/agent/tools/channel-edit.ts +2 -2
  30. package/src/agent/tools/channel-fetch-attachment.ts +2 -2
  31. package/src/agent/tools/channel-history-render.ts +2 -1
  32. package/src/agent/tools/channel-history.ts +2 -2
  33. package/src/agent/tools/channel-react.ts +2 -2
  34. package/src/agent/tools/channel-read.ts +2 -2
  35. package/src/agent/tools/channel-reply.ts +25 -7
  36. package/src/agent/tools/channel-send.ts +51 -9
  37. package/src/agent/tools/curl-impersonate.ts +11 -2
  38. package/src/agent/tools/grant-role.ts +2 -2
  39. package/src/agent/tools/post-github-review.ts +79 -17
  40. package/src/agent/tools/restart.ts +2 -2
  41. package/src/agent/tools/skip-response.ts +4 -4
  42. package/src/agent/tools/spawn-subagent.ts +165 -14
  43. package/src/agent/tools/stream-snapshot.ts +2 -2
  44. package/src/agent/tools/subagent-cancel.ts +2 -2
  45. package/src/agent/tools/subagent-output.ts +10 -2
  46. package/src/agent/tools/todo/index.ts +2 -2
  47. package/src/agent/tools/webfetch/tool.ts +2 -2
  48. package/src/agent/tools/websearch.ts +2 -2
  49. package/src/bundled-plugins/backup/README.md +10 -9
  50. package/src/bundled-plugins/backup/runner.ts +140 -58
  51. package/src/bundled-plugins/backup/subagents.ts +58 -26
  52. package/src/bundled-plugins/github-cli-auth/gh-command.ts +34 -2
  53. package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
  54. package/src/bundled-plugins/github-cli-auth/index.ts +83 -11
  55. package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
  56. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
  57. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
  58. package/src/bundled-plugins/operator/operator.ts +15 -4
  59. package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
  60. package/src/bundled-plugins/security/index.ts +50 -2
  61. package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
  62. package/src/channels/adapters/discord-bot-reactions.ts +18 -0
  63. package/src/channels/adapters/discord-bot.ts +122 -67
  64. package/src/channels/adapters/discord-reactions.ts +18 -0
  65. package/src/channels/adapters/discord.ts +114 -8
  66. package/src/channels/adapters/github/inbound.ts +103 -8
  67. package/src/channels/adapters/github/index.ts +251 -19
  68. package/src/channels/adapters/github/last-alive.ts +27 -0
  69. package/src/channels/adapters/github/outbound.ts +54 -18
  70. package/src/channels/adapters/github/pending-review-store.ts +141 -0
  71. package/src/channels/adapters/github/permission-guidance.ts +1 -0
  72. package/src/channels/adapters/github/reactions.ts +100 -0
  73. package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
  74. package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
  75. package/src/channels/adapters/github/recovery.ts +106 -0
  76. package/src/channels/adapters/github/review-check.ts +510 -0
  77. package/src/channels/adapters/github/review-submitter.ts +34 -2
  78. package/src/channels/adapters/instagram.ts +32 -14
  79. package/src/channels/adapters/kakaotalk.ts +22 -7
  80. package/src/channels/adapters/line.ts +18 -3
  81. package/src/channels/adapters/outbound-account.ts +20 -0
  82. package/src/channels/adapters/own-reactions.ts +66 -0
  83. package/src/channels/adapters/recovery-correlation.ts +214 -0
  84. package/src/channels/adapters/slack-bot-classify.ts +18 -11
  85. package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
  86. package/src/channels/adapters/slack-bot-reactions.ts +18 -0
  87. package/src/channels/adapters/slack-bot.ts +125 -57
  88. package/src/channels/adapters/slack-classify.ts +25 -4
  89. package/src/channels/adapters/slack-inbound-revision.ts +96 -0
  90. package/src/channels/adapters/slack-reactions.ts +18 -0
  91. package/src/channels/adapters/slack-thread-ts.ts +6 -0
  92. package/src/channels/adapters/slack.ts +48 -3
  93. package/src/channels/adapters/teams.ts +14 -4
  94. package/src/channels/adapters/telegram-bot.ts +56 -10
  95. package/src/channels/adapters/webex-bot.ts +12 -2
  96. package/src/channels/adapters/webex.ts +12 -2
  97. package/src/channels/background-handoff.ts +434 -0
  98. package/src/channels/background-obligations.ts +893 -0
  99. package/src/channels/continuity-types.ts +271 -0
  100. package/src/channels/github-review-check.ts +598 -0
  101. package/src/channels/github-review-turn-ledger.ts +102 -28
  102. package/src/channels/github-review-verdict-coordinator.ts +96 -13
  103. package/src/channels/github-token-bridge.ts +11 -5
  104. package/src/channels/inbound-journal.ts +1738 -0
  105. package/src/channels/index.ts +6 -1
  106. package/src/channels/manager.ts +17 -7
  107. package/src/channels/recovery-dispatcher.ts +264 -0
  108. package/src/channels/recovery-notice.ts +94 -0
  109. package/src/channels/recovery-outbox.ts +459 -0
  110. package/src/channels/router.ts +2582 -633
  111. package/src/channels/schema.ts +8 -1
  112. package/src/channels/subagent-completion-bridge.ts +17 -14
  113. package/src/channels/types.ts +121 -16
  114. package/src/channels/waiting-reactions.ts +664 -0
  115. package/src/cli/compose.ts +7 -4
  116. package/src/cli/hostd.ts +49 -3
  117. package/src/cli/inspect.ts +11 -14
  118. package/src/cli/model.ts +7 -5
  119. package/src/cli/oauth-callbacks.ts +38 -23
  120. package/src/coding-agent/broker-body.ts +38 -0
  121. package/src/coding-agent/broker.ts +290 -0
  122. package/src/coding-agent/claude.ts +95 -0
  123. package/src/coding-agent/codex.ts +104 -0
  124. package/src/coding-agent/index.ts +506 -0
  125. package/src/coding-agent/omo-state.ts +69 -0
  126. package/src/coding-agent/omo-stream.ts +98 -0
  127. package/src/coding-agent/omo.ts +192 -0
  128. package/src/coding-agent/runner.ts +263 -0
  129. package/src/coding-agent/tool.ts +62 -0
  130. package/src/coding-agent/worktree.ts +355 -0
  131. package/src/compose/restart.ts +10 -3
  132. package/src/compose/start.ts +20 -3
  133. package/src/config/config.ts +70 -26
  134. package/src/config/providers.ts +278 -50
  135. package/src/container/exit-reason.ts +44 -0
  136. package/src/container/index.ts +5 -0
  137. package/src/container/log-archive.ts +51 -13
  138. package/src/container/memory-limit.ts +1 -1
  139. package/src/container/memory-oversubscription.ts +36 -6
  140. package/src/container/oom-events.ts +86 -0
  141. package/src/container/restart.ts +2 -0
  142. package/src/container/shared.ts +8 -1
  143. package/src/container/start.ts +25 -13
  144. package/src/container/stop.ts +6 -2
  145. package/src/container/tool-oom-priority.ts +32 -0
  146. package/src/cron/consumer.ts +10 -4
  147. package/src/cron/reloadable.ts +23 -2
  148. package/src/doctor/checks.ts +14 -2
  149. package/src/hostd/daemon.ts +20 -10
  150. package/src/hostd/spawn.ts +106 -5
  151. package/src/hostd/version.ts +20 -0
  152. package/src/hostd/watchdog.ts +241 -0
  153. package/src/init/dockerfile.ts +57 -592
  154. package/src/init/index.ts +6 -7
  155. package/src/init/oauth-login.ts +57 -17
  156. package/src/inspect/transcript-view.ts +6 -3
  157. package/src/mcp/client.ts +3 -1
  158. package/src/operations/classify-tool-outcome.ts +45 -1
  159. package/src/operations/incidents.ts +10 -5
  160. package/src/plugin/core-tool-names.ts +1 -1
  161. package/src/plugin/define.ts +1 -0
  162. package/src/plugin/index.ts +1 -0
  163. package/src/plugin/types.ts +6 -1
  164. package/src/run/background-handoff-boot.ts +86 -0
  165. package/src/run/channel-session-factory.ts +5 -4
  166. package/src/run/index.ts +93 -93
  167. package/src/run/resource-sample.ts +19 -0
  168. package/src/sandbox/build.ts +4 -0
  169. package/src/sandbox/coding-agent.ts +214 -0
  170. package/src/sandbox/policy.ts +1 -0
  171. package/src/sandbox/runtime-private.ts +4 -1
  172. package/src/secrets/coding-agent-auth.ts +97 -0
  173. package/src/secrets/index.ts +0 -16
  174. package/src/secrets/refresh-provider-oauth.ts +30 -76
  175. package/src/secrets/schema.ts +3 -4
  176. package/src/secrets/storage.ts +133 -234
  177. package/src/server/command-runner.ts +6 -2
  178. package/src/server/index.ts +102 -41
  179. package/src/sessions/index.ts +1 -1
  180. package/src/skills/typeclaw-channel-github/SKILL.md +7 -5
  181. package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
  182. package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
  183. package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
  184. package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
  185. package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
  186. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
  187. package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
  188. package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
  189. package/src/skills/typeclaw-config/SKILL.md +24 -24
  190. package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
  191. package/src/skills/typeclaw-cron/SKILL.md +1 -1
  192. package/src/skills/typeclaw-github-contributing/SKILL.md +2 -2
  193. package/src/skills/typeclaw-memory/SKILL.md +3 -3
  194. package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
  195. package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
  196. package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
  197. package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
  198. package/src/skills/typeclaw-plugins/SKILL.md +20 -20
  199. package/src/skills/typeclaw-skills/SKILL.md +19 -2
  200. package/src/skills/typeclaw-troubleshooting/SKILL.md +15 -2
  201. package/src/tui/index.ts +5 -3
  202. package/src/tui/theme.ts +1 -1
  203. package/typeclaw.schema.json +44 -2
  204. package/src/agent/adaptive-thinking-compat.ts +0 -79
  205. package/src/secrets/claude-credentials-json.ts +0 -129
  206. package/src/secrets/codex-auth-json.ts +0 -102
  207. package/src/secrets/export-claude-credentials-file.ts +0 -270
  208. package/src/secrets/export-codex-auth-file.ts +0 -250
  209. package/src/secrets/oauth-xai.ts +0 -348
  210. package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
  211. package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
  212. package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
  213. package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
@@ -295,12 +295,19 @@ export const DEFAULT_GITHUB_REVIEW_ON: GithubReviewOn = 'review_requested'
295
295
  // Enforced in the inbound text rather than at the bash layer because the
296
296
  // review posts via `gh api --input <file>`, so the `event` value lives in a
297
297
  // temp file the command interceptor never sees.
298
+ //
299
+ // `check` shows the agent's own review as a check named after the agent's
300
+ // GitHub login (`slug` for an App's `slug[bot]`) on the
301
+ // reviewed commit (in progress while reviewing, then the verdict). On by
302
+ // default; a token without check/status write permission skips it silently
303
+ // after one operator warning.
298
304
  const githubReviewSchema = z
299
305
  .object({
300
306
  on: z.enum(GITHUB_REVIEW_ON_VALUES).default(DEFAULT_GITHUB_REVIEW_ON),
301
307
  approve: z.boolean().default(true),
308
+ check: z.boolean().default(true),
302
309
  })
303
- .default({ on: DEFAULT_GITHUB_REVIEW_ON, approve: true })
310
+ .default({ on: DEFAULT_GITHUB_REVIEW_ON, approve: true, check: true })
304
311
 
305
312
  const githubChannelSchema = adapterSchema.extend({
306
313
  // Optional now (PR 2): when omitted and a `tunnels[]` entry with
@@ -47,8 +47,8 @@ const consoleLogger: SubagentCompletionBridgeLogger = {
47
47
  // `LiveSession`, so the lookup is O(N) over live sessions with N small
48
48
  // (one per active conversation).
49
49
  //
50
- // On `no-live-session`, we drop the reminder. When the parent was a
51
- // channel session, the broadcast now carries the channel-key coordinate
50
+ // On `no-live-session`, live routing stops but the durable response remains owed.
51
+ // For a channel session, the broadcast carries the channel-key coordinate
52
52
  // `{ adapter, workspace, chat, thread }`, and the router first tries to
53
53
  // reroute to the live successor session for that key — covering the two
54
54
  // common drop paths where the exact sessionId is gone but the
@@ -62,22 +62,25 @@ const consoleLogger: SubagentCompletionBridgeLogger = {
62
62
  // A reminder still reaching this branch means there is no live session
63
63
  // for the key at all (the whole conversation went idle), or the parent
64
64
  // was a TUI session (handled by the TUI bridge in src/server/index.ts).
65
- // Logged at warn with the channel key so an undelivered completion is
66
- // diagnosable from logs alone.
65
+ // Logged at warn so absent-parent completion routing remains diagnosable.
67
66
  export function createSubagentCompletionBridge(options: SubagentCompletionBridgeOptions): SubagentCompletionBridge {
68
67
  const logger = options.logger ?? consoleLogger
69
- const unsubscribe = options.stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
68
+ const unsubscribe = options.stream.subscribe({ target: { kind: 'broadcast' } }, async (msg) => {
70
69
  const parsed = parseSubagentCompletedPayload(msg.payload)
71
70
  if (parsed === null) return
72
- const result = options.router.injectSubagentCompletionReminder(parsed)
73
- if (result.kind === 'no-live-session') {
74
- const keyInfo =
75
- parsed.channelKey !== undefined
76
- ? ` channelKey=${parsed.channelKey.adapter}:${parsed.channelKey.workspace}:${parsed.channelKey.chat}:${parsed.channelKey.thread ?? ''}`
77
- : ''
78
- logger.warn(
79
- `[channels] subagent-completion reminder dropped: no live session for parentSessionId=${parsed.parentSessionId} task=${parsed.taskId}${keyInfo}`,
80
- )
71
+ try {
72
+ const result = await options.router.injectSubagentCompletionReminder(parsed)
73
+ if (result.kind === 'no-live-session') {
74
+ const keyInfo =
75
+ parsed.channelKey !== undefined
76
+ ? ` channelKey=${parsed.channelKey.adapter}:${parsed.channelKey.workspace}:${parsed.channelKey.chat}:${parsed.channelKey.thread ?? ''}`
77
+ : ''
78
+ logger.warn(
79
+ `[channels] subagent-completion reminder not routed: no live session for parentSessionId=${parsed.parentSessionId} task=${parsed.taskId}${keyInfo}`,
80
+ )
81
+ }
82
+ } catch {
83
+ logger.warn(`[channels] subagent-completion admission failed: task=${parsed.taskId}; response remains owed`)
81
84
  }
82
85
  })
83
86
  return { stop: unsubscribe }
@@ -1,3 +1,4 @@
1
+ import type { RecoveryFailure, RecoveryRecord } from './continuity-types'
1
2
  import type { AdapterId } from './schema'
2
3
 
3
4
  export type ChannelKey = {
@@ -6,6 +7,15 @@ export type ChannelKey = {
6
7
  chat: string
7
8
  thread: string | null
8
9
  }
10
+ // Matches the router's existing self-identity fallback and persisted background
11
+ // account identity. Adapters with platform-specific resolvers retain those IDs.
12
+ export function fallbackChannelAccountIdentity(
13
+ adapter: AdapterId,
14
+ workspace: string,
15
+ userId: string | null | undefined,
16
+ ): string | undefined {
17
+ return userId == null ? undefined : `${adapter}:${workspace}:${userId}`
18
+ }
9
19
 
10
20
  // Inbound (non-text) media that the user attached to a channel message.
11
21
  // The classifier produces these alongside `InboundMessage.text`; the router
@@ -62,12 +72,21 @@ export type GithubReviewThreadCloseout = {
62
72
  deferUntil?: { kind: 'review-state-unknown'; expiresAt: number }
63
73
  }
64
74
 
75
+ export type RouteReceipt =
76
+ | { kind: 'accepted'; inputId: string; generation: number }
77
+ | { kind: 'duplicate'; inputId: string; outcome?: 'delivered' | 'intentionally-suppressed' }
78
+ | { kind: 'observed' }
79
+ | { kind: 'denied' }
80
+ | { kind: 'control' }
81
+
65
82
  export type InboundMessage = {
66
83
  adapter: AdapterId
67
84
  workspace: string
68
85
  chat: string
69
86
  thread: string | null
70
87
  githubReviewRound?: GithubReviewFollowupRound
88
+ // Only dedicated adapter-classified review triggers create durable PR work.
89
+ githubPendingReview?: { prId: number; headSha: string; kind: 'review' | 'rereview' }
71
90
  // Adapter-authoritative obligation created only for a non-self reply whose
72
91
  // review-thread ROOT comment was authored by this agent. Kept separate from
73
92
  // replyToBotMessageId, which describes only the immediate parent.
@@ -92,6 +111,12 @@ export type InboundMessage = {
92
111
  // resolve `attachment_id` → ref without the agent ever seeing the ref.
93
112
  attachments?: readonly InboundAttachment[]
94
113
  externalMessageId: string
114
+ // Authenticated adapter account, never a credential or its fingerprint.
115
+ accountIdentity?: string
116
+ eventKind?: string
117
+ revision?: string
118
+ // Local receipt identity when upstream supplies no stable event identity.
119
+ receiptId?: string
95
120
  authorId: string
96
121
  authorName: string
97
122
  // Set true when the inbound is from another bot (NOT this typeclaw
@@ -209,6 +234,39 @@ export type ReactionCallback = (req: ReactionRequest) => Promise<ReactionResult>
209
234
 
210
235
  export type RemoveReactionCallback = (req: RemoveReactionRequest) => Promise<ReactionResult>
211
236
 
237
+ export type OwnReactionTarget = {
238
+ // Authenticated platform actor identity, not a credential/token hash.
239
+ accountIdentity: string
240
+ // Canonical message target, not the per-reaction-instance removal ref.
241
+ target: ReactionRef
242
+ // Canonical platform emoji: aliases resolve before persisting the tuple.
243
+ emoji: string
244
+ }
245
+
246
+ export type PrepareOwnReactionCallback = (req: ReactionRequest) => Promise<OwnReactionTarget | null>
247
+
248
+ export type RemoveOwnReactionRequest = {
249
+ adapter: AdapterId
250
+ workspace: string
251
+ chat: string
252
+ thread?: string | null
253
+ target: ReactionRef
254
+ emoji: string
255
+ expectedAccountIdentity: string
256
+ }
257
+
258
+ export type RemoveOwnReactionResult =
259
+ | { ok: true }
260
+ | {
261
+ ok: false
262
+ code: 'unsupported' | 'transient' | 'rate-limit' | 'permission' | 'identity'
263
+ error: string
264
+ // Suggested retry delay in milliseconds.
265
+ retryAfter?: number
266
+ }
267
+
268
+ export type RemoveOwnReactionCallback = (req: RemoveOwnReactionRequest) => Promise<RemoveOwnReactionResult>
269
+
212
270
  // File on disk that the agent wants to attach to an outbound message. The
213
271
  // agent runs inside a container with /agent bind-mounted from the host;
214
272
  // `path` should be an absolute path the container can `readFile`. The
@@ -222,6 +280,40 @@ export type OutboundAttachment = {
222
280
  filename?: string
223
281
  }
224
282
 
283
+ export type SendOptions =
284
+ | {
285
+ accounting?: 'live-turn'
286
+ sessionId?: string
287
+ turnId?: string
288
+ claimGeneration?: number
289
+ expectedAccountIdentity?: string
290
+ coveredIds?: readonly string[]
291
+ }
292
+ | { accounting: 'recovery'; deliveryId: string; coveredIds: readonly string[]; expectedAccountIdentity: string }
293
+
294
+ export type RecoveryReconcileResult =
295
+ | { status: 'found'; messageId?: string; messageIds?: readonly string[] }
296
+ | { status: 'unknown' | 'unreconcilable' }
297
+
298
+ export class RecoveryTransportError extends Error {
299
+ constructor(readonly failure: RecoveryFailure) {
300
+ super(failure.safeReason)
301
+ }
302
+ }
303
+
304
+ export type RecoveryAdapterCallbacks = {
305
+ accountIdentity: (workspace?: string) => Promise<string | undefined>
306
+ cachedAccountIdentity?: (workspace?: string) => string | undefined
307
+ reconcile: (record: RecoveryRecord) => Promise<RecoveryReconcileResult>
308
+ /**
309
+ * Whether this adapter has already re-admitted the interrupted work itself, so the restart
310
+ * notice would be wrong. `pending` defers the notice while that answer is still being decided.
311
+ */
312
+ redelivery?: (record: RecoveryRecord, eventKinds: readonly string[]) => RecoveryRedelivery
313
+ }
314
+
315
+ export type RecoveryRedelivery = 'redelivered' | 'pending' | 'not-redelivered'
316
+
225
317
  export type OutboundMessage = {
226
318
  adapter: AdapterId
227
319
  workspace: string
@@ -231,6 +323,8 @@ export type OutboundMessage = {
231
323
  // Adapters that always need text (e.g. some webhook backends in the
232
324
  // future) must validate this themselves.
233
325
  text?: string
326
+ // false suppresses URL previews where the adapter supports them; otherwise ignored.
327
+ link_previews?: boolean
234
328
  // Each attachment is uploaded once. Order is preserved. For Slack, the
235
329
  // first attachment carries `text` as the file's `initial_comment` so
236
330
  // both arrive in a single API call; subsequent attachments are uploaded
@@ -250,6 +344,7 @@ export type OutboundMessage = {
250
344
  // send time (KakaoTalk: payload built from a source message that may have
251
345
  // scrolled out of history) degrade to the same blockquote fallback.
252
346
  replyTo?: OutboundReplyTo
347
+ sendOptions?: SendOptions
253
348
  }
254
349
 
255
350
  export type OutboundReplyTo = {
@@ -280,26 +375,24 @@ export type SendErrorCode =
280
375
  | 'callback-rejected'
281
376
  | 'skip-locked'
282
377
 
283
- // `messageId` is the platform-native id of the posted message (Slack `ts`,
284
- // Discord snowflake, Telegram `message_id`, Webex/GitHub comment id, KakaoTalk
285
- // `log_id`, LINE `message_id`). It is the SAME id shape an inbound carries as
286
- // `externalMessageId`, so an agent can feed it straight back into a follow-up
287
- // `thread` / `replyTo` to keep posting into one conversation. For a send the
288
- // adapter splits into multiple posts (long text chunked, or attachments +
289
- // text), `messageId` is the post a reply should anchor to — usually the FIRST
290
- // post, but adapter-specific: KakaoTalk uploads files BEFORE the text, so the
291
- // text post (the message a human replies to) is the anchor even though it is
292
- // last. `messageIds` always lists every post in send order, so a caller that
293
- // needs a specific post (rather than the reply anchor) can index it directly.
294
- // Optional throughout: an adapter whose SDK does not hand back an id (legacy
295
- // slack/discord user-account adapters) omits both, and callers must treat a
296
- // missing id as "not available", never as an error.
378
+ // `messageId` is an adapter-reported id of a posted message (e.g. Slack `ts`,
379
+ // Discord snowflake, Telegram `message_id`, Webex/GitHub comment id). The
380
+ // optional `messageIds` lists reported posted-message ids in send order,
381
+ // including when a send is split; some adapters do not report attachment ids.
382
+ // `messageId` is adapter-selected, not necessarily the first post (KakaoTalk
383
+ // reports the text id after attachments). Neither field is universally a
384
+ // `thread` coordinate: Discord uses a thread channel id, Telegram a topic id,
385
+ // GitHub review replies a root comment id, and Slack replies keep the original
386
+ // thread root rather than their own new `ts`. Reuse existing conversation
387
+ // coordinates for follow-ups; a newly posted id can start a thread only when
388
+ // that adapter accepts a message id as `thread` (e.g. a top-level Slack post).
389
+ // Adapters with no reported ids omit the fields; missing ids are not an error.
297
390
  // `reactionRef` is the outbound message's adapter-owned TARGET ref — the entity
298
391
  // a later ReactionRequest reacts to. It is explicitly NOT the per-reaction
299
392
  // removal-instance ref returned by `ReactionResult.reactionRef` after an add.
300
393
  export type SendResult =
301
394
  | { ok: true; messageId?: string; messageIds?: readonly string[]; reactionRef?: ReactionRef }
302
- | { ok: false; error: string; code?: SendErrorCode }
395
+ | { ok: false; error: string; code?: SendErrorCode; recoveryFailure?: RecoveryFailure }
303
396
 
304
397
  export type OutboundCallback = (msg: OutboundMessage) => Promise<SendResult>
305
398
 
@@ -599,10 +692,22 @@ export type SubmitReviewRequest = {
599
692
  event: 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT'
600
693
  body: string
601
694
  comments: ReviewFinding[]
695
+ // The commit the review describes. When set, the submitter refuses to post
696
+ // unless the PR head is still exactly this commit.
697
+ expectedHeadSha?: string
698
+ expectedAccountIdentity?: string
699
+ sourceSessionId?: string
602
700
  }
603
701
 
604
702
  export type SubmitReviewResult =
605
- | { ok: true; reviewId: number; state: string; downgraded?: boolean; reanchored?: ReviewFinding[] }
703
+ | {
704
+ ok: true
705
+ reviewId: number
706
+ state: string
707
+ commitSha?: string
708
+ downgraded?: boolean
709
+ reanchored?: ReviewFinding[]
710
+ }
606
711
  | { ok: false; error: string; code: SubmitReviewErrorCode; submitted?: boolean }
607
712
 
608
713
  export type SubmitReviewErrorCode = 'unsupported' | 'permission-denied' | 'bad-anchor' | 'not-found' | 'transient'