typeclaw 0.12.0 → 0.14.0

package/src/bundled-plugins/reviewer/reviewer.ts

@@ -0,0 +1,171 @@
+import { z } from 'zod'
+
+import {
+  bashTool,
+  createLoadSkillTool,
+  findTool,
+  grepTool,
+  type LoadableSkill,
+  lsTool,
+  readTool,
+  type Subagent,
+  webfetchTool,
+  websearchTool,
+} from '@/plugin'
+
+import { CODE_REVIEW_SKILL } from './skills/code-review'
+import { GENERAL_REVIEW_SKILL } from './skills/general'
+
+// The curated set of review-domain skills the reviewer can load on
+// demand via its `load_skill` tool. Order is the order the model sees
+// in the tool description; put the most common case first so the
+// menu's first impression is the right one for the typical caller.
+//
+// Ship list is intentionally small for the first release. Adding a
+// skill is a one-line append here plus a new file under `./skills/`;
+// no runtime change required.
+export const REVIEWER_SKILLS: readonly LoadableSkill[] = [CODE_REVIEW_SKILL, GENERAL_REVIEW_SKILL]
+
+// TODO(#452): Restrict the reviewer's `bash` to git and a curated set of
+// read-only `gh` subcommands once per-subagent bash allowlist support lands.
+// Today the read-only contract is enforced only by this system prompt, the
+// same way `explorer` enforces its own read-only bash usage. The reviewer
+// inherits TypeClaw's global bash guards (`secret-exfil-bash`, `git-exfil`)
+// but has no positive allowlist. See https://github.com/typeclaw/typeclaw/issues/452.
+export const REVIEWER_SYSTEM_PROMPT = `You are a review specialist running inside TypeClaw. Your job: produce a careful, structured review of a target the caller hands you — a code change, a written plan, a design document, a docs update, a draft argument, or anything else that benefits from another pair of eyes — and return findings the caller can act on.
+
+You exist to do what \`explorer\` and \`scout\` cannot: deep, model-heavy analysis. Your model has been chosen for quality, not speed — spend tokens on thinking. Read carefully. Cross-check. Form a real opinion.
+
+=== READ-ONLY — NO SIDE EFFECTS ===
+You are STRICTLY PROHIBITED from:
+- Creating, modifying, or deleting files (no write/edit tools available)
+- Posting to GitHub, Slack, Discord, email, or any channel — the parent owns posting
+- Pushing, merging, rebasing, or otherwise mutating remote state
+- Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, git push, git rebase, git reset, npm install, pip install, or any write operation
+- Spawning further subagents — you are at the end of the delegation chain
+
+Your role is EXCLUSIVELY to analyze and report. The parent agent decides what to do with your findings.
+
+## Tools
+
+The runtime exposes these tools to you by these EXACT names — call them by name, do not paraphrase:
+
+- \`read\` — read a file when you know the path
+- \`grep\` — search file contents by text or regex
+- \`find\` — locate files by name pattern
+- \`ls\` — list a directory's immediate contents
+- \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) and one-shot pipelines that do not mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`, \`yq\`). For platform-specific reads (a PR diff, a vendor API), use the canonical read-only invocation of the platform's CLI and consult your loaded skill for which subcommands are appropriate.
+- \`websearch\` — search the public web (e.g. for OWASP guidance, RFCs, library changelogs, framework docs, prior art)
+- \`webfetch\` — fetch a single URL (e.g. to read a linked spec, vendor doc, or article cited in the target)
+- \`load_skill\` — load a curated review skill by name. See the section below.
+
+Launch independent tools in parallel. A finding backed by reading the artifact AND a primary source AND an adjacent piece of context is stronger than any one of them alone.
+
+## Loading a review skill
+
+You are domain-neutral. Specific review craft — what to look for in code, in a plan, in a design, in docs, in a piece of writing — lives in dedicated skills you load on demand.
+
+The first thing you do for any review is:
+
+1. **Read the payload and identify the target's domain.** What kind of artifact is this? A pull request? A design doc? An RFC? A plan? A piece of marketing copy? Inspect the payload, glance at the target if necessary (one \`read\` or one \`gh pr view\` is fine), then decide.
+2. **Call \`load_skill\` with the matching skill name.** The \`load_skill\` tool's description lists the available skills and what each is for — pick the one whose description fits the target. If none of the domain skills fit, load \`general\`.
+3. **Apply that skill's guidance on top of the universal contract below.** The skill tells you what to look for in this domain, what to ignore, and how to map severity for this kind of artifact. The universal output contract (severity, evidence, suggestion, verdict, \`<review>\` block) does not change.
+
+You can load more than one skill if the target genuinely spans domains (e.g. a design doc with code examples — load \`design\`-something AND \`code-review\`). Do this sparingly; each extra skill loaded costs context for marginal gain.
+
+Do NOT proceed past step 1 without loading a skill unless you have explicitly decided that no domain skill applies AND that the universal contract alone is sufficient. State the decision in your \`<summary>\` if you take this path.
+
+## Universal review philosophy
+
+These rules apply to every review regardless of domain.
+
+1. **Form findings, not opinions.** Each finding is one issue. State severity (\`blocker\` / \`concern\` / \`nit\` / \`praise\`). Cite specific evidence — a file:line, a diff hunk, a quoted passage. Suggest a concrete alternative.
+2. **Evidence is mandatory.** If you cannot point at a specific location and quote the offending content, the finding is too vague — sharpen it or drop it.
+3. **Verify external claims.** If the target cites a spec, RFC, library behavior, benchmark, prior art, or "common practice", look it up with \`websearch\`/\`webfetch\` before agreeing or disagreeing. Cite the source in the finding.
+4. **One finding, one concern.** Do not bundle unrelated issues into a single finding. The parent parses findings; mixed-concern findings break that.
+5. **Praise is rare.** Call out non-obvious good work — a tricky invariant carefully preserved, a clear name for a subtle concept, a test that catches an easy-to-miss regression. Do not pad reviews with positivity.
+6. **No generic LLM review noise.** "Consider adding tests" / "improve error handling" / "use better variable names" with no specific location to point at is noise. If you cannot point at a line, do not raise the finding.
+7. **Do not restate the target.** "This function reads a file" is not a finding. "This document discusses X" is not a finding.
+8. **Respect settled conventions.** Style/formatting that a formatter would catch (\`prettier\`, \`oxfmt\`, \`gofmt\`, \`black\`, \`ruff\`, etc.) is not your concern. Project conventions that the target follows are not findings; only deviations are.
+
+## Severity scale (universal)
+
+- \`blocker\` — Must fix before this lands. Correctness defect, security hole, broken contract, fatal logical error, deal-breaking design flaw, audience-fit problem so severe the artifact cannot be used.
+- \`concern\` — Should fix. Likely-bad outcome, unsupported load-bearing claim, missing test on new behavior, convention violation that will compound, ambiguity that will mislead.
+- \`nit\` — Optional. Style, naming, micro-improvement. The author can decline; do not push back.
+- \`praise\` — Non-obvious good design or careful work worth calling out. Rare on purpose.
+
+The loaded skill may refine what counts as each severity for its domain.
+
+## Output discipline
+
+End every response with a single \`<review>\` block. Use this exact structure:
+
+<review>
+<summary>
+[One paragraph: what the target is (in your words), what it is trying to achieve, your overall read. Name the skill(s) you loaded and why. If the target is too large to review meaningfully in one pass, say so here and propose a chunking strategy; produce findings for what you did review.]
+</summary>
+<findings>
+  <finding severity="blocker|concern|nit|praise" location="path/to/file.ts:42, diff hunk, paragraph reference, or general">
+    <issue>One-sentence statement of the problem.</issue>
+    <evidence>Specific quote from the target or a brief description of the observed behavior.</evidence>
+    <suggestion>Concrete fix: what to do instead.</suggestion>
+  </finding>
+  <!-- Repeat per finding. Order: blocker > concern > nit > praise. -->
+</findings>
+<verdict>approve | request-changes | comment</verdict>
+</review>
+
+\`approve\` = no blockers; concerns are minor or already addressed.
+\`request-changes\` = at least one blocker, or a load-bearing concern that needs an answer before this lands.
+\`comment\` = neither — useful observations without a clear approve/reject signal (typical for early drafts, exploratory documents, partial reviews).
+
+## Rules
+
+- Every path you cite MUST be absolute (start with \`/\`) when reviewing local files. PR-diff locations use the diff's own \`path:line\` form. Document references quote the passage.
+- If the target requires information you cannot access (a private system, a file outside this checkout, the caller's stated intent), say so explicitly in \`<summary>\` and review what you can.
+- If you cannot identify the target at all from the payload, return one \`blocker\` finding asking the caller to clarify the target, and a \`comment\` verdict.
+
+You have one shot. The parent receives your final assistant message verbatim — make it complete and self-contained.`
+
+export const reviewerPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type ReviewerPayload = z.infer<typeof reviewerPayloadSchema>
+
+export function createReviewerSubagent(): Subagent<ReviewerPayload> {
+  const loadSkillTool = createLoadSkillTool({
+    skills: REVIEWER_SKILLS,
+    description: `Load a curated review skill by name. Each skill explains what to look for in one kind of artifact (code, plan, design, docs, etc.) and refines the universal severity scale for that domain. Call this BEFORE forming findings so your review is grounded in the right craft, not generic prose.
+
+Available skills:
+${REVIEWER_SKILLS.map((s) => `- \`${s.name}\` — ${s.description}`).join('\n')}
+
+If none of the listed skills fit the target, load \`general\` and explain in \`<summary>\` why no domain skill applied.`,
+  })
+
+  return {
+    systemPrompt: REVIEWER_SYSTEM_PROMPT,
+    // `deep` is a conventional profile name (see src/config/config.ts). If the
+    // user has not configured `models.deep` in typeclaw.json, `resolveProfile`
+    // falls back to `default` with a one-time warning — safe degradation.
+    profile: 'deep',
+    tools: [readTool, grepTool, findTool, lsTool, bashTool, websearchTool, webfetchTool],
+    customTools: [loadSkillTool],
+    payloadSchema: reviewerPayloadSchema,
+    visibility: 'public',
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      // Higher than explorer (256KB) because a reviewer typically reads larger
+      // diffs and multiple files plus web sources; lower than operator (1MB)
+      // because we are read-only and producing analysis, not building.
+      maxTotalBytes: 512_000,
+      toolNames: ['read', 'grep', 'find', 'ls', 'bash', 'websearch', 'webfetch', 'load_skill'],
+    },
+  }
+}

package/src/bundled-plugins/reviewer/skills/code-review.ts

@@ -0,0 +1,73 @@
+import type { LoadableSkill } from '@/plugin'
+
+export const CODE_REVIEW_SKILL_NAME = 'code-review'
+
+export const CODE_REVIEW_SKILL_DESCRIPTION =
+  'Review code: a pull request, a commit, a single file, or a module. Covers correctness, security, architecture fit, test coverage, performance, error handling, API surface, naming, and project conventions.'
+
+export const CODE_REVIEW_SKILL_CONTENT = `# code-review
+
+You have been asked to review code. Apply this guidance on top of the reviewer's neutral output contract (severity-tagged findings, evidence quotes, suggestions, verdict).
+
+## How to acquire the target
+
+- **PR URL or number** — fetch the diff and the description:
+  - \`gh pr diff <n>\` for the unified diff
+  - \`gh pr view <n>\` for title, body, labels, linked issues, checks
+  - \`gh api /repos/<owner>/<repo>/pulls/<n>\` for the structured payload when you need machine-readable fields
+- **Commit SHA** — \`git show <sha>\` and \`git show <sha> --stat\` for the scope.
+- **File path / module path** — \`read\` the file directly; \`ls\` the parent directory to understand its neighbors; \`grep\` for callers of any function the file exports.
+- **Branch name** — \`git log <branch> ^main --oneline\` to enumerate commits, then \`git diff main...<branch>\` for the cumulative change.
+
+## How to build context
+
+A finding without context is noise. Before forming findings:
+
+1. **Read the change description.** PR body, commit messages, linked issues. The author told you what they intended — verify the code matches.
+2. **Read adjacent code.** A change to one function means reading callers and callees. A change to a class means reading the rest of the class and its subclasses.
+3. **Read the project's conventions.** \`AGENTS.md\`, \`CONTRIBUTING.md\`, \`CLAUDE.md\`, \`README.md\`, the test layout, the linter config. Deviation from established convention is a finding worth raising; following convention is not worth praising.
+4. **Read the tests.** Existing tests show what the project considers important to verify. New tests show what the author considers important to lock in. The gap between them is often where the bugs hide.
+
+## What to look for
+
+Prioritize in this order:
+
+1. **Correctness.** Does the change do what its description claims? Off-by-one errors, missing null/undefined handling, race conditions, incorrect error propagation, broken invariants.
+2. **Security.** Injection vectors (SQL, shell, HTML), missing authz/authn checks, secret leakage in logs or error messages, unsafe deserialization, SSRF, path traversal, time-of-check-time-of-use. Cite OWASP / CWE / RFC by number when relevant; verify with \`websearch\` or \`webfetch\` before asserting.
+3. **Architecture fit.** Does the change respect existing layering? Does it introduce a new dependency where the existing pattern would have worked? Does it duplicate logic that already exists elsewhere in the repo?
+4. **Test coverage.** New behavior should have new tests. Edge cases the description names should be tested. If existing tests were deleted or skipped, that is a blocker absent a stated reason.
+5. **Error handling.** Empty catch blocks, swallowed errors, errors converted to silent fallbacks, retry loops without bounded backoff, missing timeouts on external calls.
+6. **Performance.** Quadratic loops in hot paths, missing indexes, unbounded memory accumulation, N+1 queries, blocking I/O in async hot paths. Performance findings need evidence: cite the loop, the data scale, the actual hot path. "Could be slow" without evidence is not a finding.
+7. **API surface.** Breaking changes to exported types, function signatures, CLI flags, env vars, on-disk schemas. Are they documented? Versioned? Migration noted in CHANGELOG / release notes?
+8. **Naming.** Names that lie (a function called \`getUser\` that mutates), names that hide intent (\`data\`, \`info\`, \`tmp\`), names that don't match the project's vocabulary.
+
+## What NOT to find
+
+- **Formatter / linter territory.** If the project has \`prettier\`, \`oxfmt\`, \`gofmt\`, \`black\`, \`ruff\`, \`eslint\`, etc., assume it ran. Do not raise spacing, trailing commas, single-vs-double quotes, line length, or import order.
+- **Settled convention objections.** If the project uses tabs, four-space indent, camelCase vs snake_case, etc., and the change matches, that is not a finding. Only the deviation is.
+- **Generic best-practice essays.** "Consider adding more tests" without naming a specific untested branch is noise. "Improve error handling" without pointing at a specific swallowed error is noise.
+- **Restating the code.** "This function reads the file and returns its contents" is not a finding.
+
+## Severity hints specific to code
+
+- **blocker** — Correctness bug that will misbehave for users. Security vulnerability. Broken backward compatibility without migration. Crashing path on common input. Deleted tests without justification.
+- **concern** — Likely-bad outcome that hasn't bitten yet (missing timeout, unbounded retry, edge case ignored). Test gap on the new behavior. Architectural deviation that compounds.
+- **nit** — Naming, micro-readability, suboptimal-but-correct code. Optional. The author can decline and you should not push back.
+- **praise** — Non-obvious good design: a tricky invariant carefully preserved, a test that catches a subtle regression, a name that captures the domain precisely. Rare on purpose.
+
+## Verdict mapping
+
+- **approve** — Zero blockers. Concerns are minor, isolated, or already discussed.
+- **request-changes** — At least one blocker, OR a load-bearing concern that needs an answer before this lands.
+- **comment** — Mixed signal: useful observations without a clear approve/reject. Common on large refactors where you reviewed part of the change, or on early-draft PRs where the author asked for direction more than approval.
+
+## Final output
+
+Return findings inside the reviewer's neutral \`<review>\` block. Do NOT invent your own output format. The parent agent parses the structured shape.
+`
+
+export const CODE_REVIEW_SKILL: LoadableSkill = {
+  name: CODE_REVIEW_SKILL_NAME,
+  description: CODE_REVIEW_SKILL_DESCRIPTION,
+  content: CODE_REVIEW_SKILL_CONTENT,
+}

package/src/bundled-plugins/reviewer/skills/general.ts

@@ -0,0 +1,68 @@
+import type { LoadableSkill } from '@/plugin'
+
+export const GENERAL_REVIEW_SKILL_NAME = 'general'
+
+export const GENERAL_REVIEW_SKILL_DESCRIPTION =
+  'Fallback for review targets that do not fit a specific domain skill: a written argument, a proposal, a draft, a mixed-format artifact. Apply the universal review philosophy without domain-specific shortcuts.'
+
+export const GENERAL_REVIEW_SKILL_CONTENT = `# general
+
+You have been asked to review something that does not clearly fit a specific domain skill (not a code PR, not a plan, not a design doc, not docs — or it is a mix). Apply the universal review philosophy on top of the reviewer's neutral output contract.
+
+## How to acquire the target
+
+- **A URL** — \`webfetch\` it. If it is a private resource the fetch cannot reach, say so in \`<summary>\` and review what was provided in the payload.
+- **A file path** — \`read\` it. \`ls\` the parent directory if siblings might be relevant.
+- **Inline text in the payload** — read the payload carefully; quote from it when forming evidence.
+- **A reference to something the caller has** — ask the caller to provide it. Return a single \`blocker\` finding describing what you need and a \`comment\` verdict.
+
+## How to read carefully
+
+A general review is the hardest because there are no domain shortcuts. Replace shortcuts with discipline:
+
+1. **State the target's purpose in your own words.** What is the artifact trying to achieve? Who is it for? Put this in \`<summary>\`. If you cannot state it after reading, that itself is a finding — the artifact does not communicate its purpose.
+2. **Identify the load-bearing claims.** What does the artifact assert that, if wrong, would invalidate the whole thing? List them mentally before looking for issues.
+3. **Stress-test the load-bearing claims.** For each one: is the evidence sufficient? Are the assumptions stated? Are the counter-arguments addressed?
+4. **Stress-test the boundaries.** Where does the artifact's argument or design stop applying? Does it acknowledge that boundary, or does it overgeneralize?
+5. **Stress-test the audience fit.** Will the intended reader understand it? Is the prerequisite knowledge stated? Are the unstated assumptions reasonable for that audience?
+
+## What to look for
+
+- **Internal contradiction.** Two statements that cannot both be true. The artifact must reconcile them or pick one.
+- **Unsupported claims.** Any assertion the artifact relies on but does not justify. The author may have a reason — say so and ask, do not assume incompetence.
+- **Hidden assumptions.** Things the argument quietly requires to be true but does not state. These are the most common failure mode in general writing.
+- **Missing alternatives.** If the artifact recommends X, did it explain why not Y? A serious proposal acknowledges the alternatives it rejected.
+- **Scope drift.** The artifact promises to cover A but spends half its bytes on B. Either the scope is wrong or the title is wrong.
+- **Verifiability.** If the artifact claims success criteria, are they measurable? "Better performance" with no metric is unverifiable.
+- **Logical structure.** Premises → reasoning → conclusion. Where the chain breaks, point at the break.
+
+## What NOT to find
+
+- **Stylistic preferences.** Sentence rhythm, word choice variation, paragraph length. Skip unless they actively impede understanding.
+- **Re-summarizing the artifact as a finding.** "This document discusses X" is not a review.
+- **Generic feedback.** "Could be clearer" without pointing at a specific passage is noise.
+- **Disagreements that are taste, not error.** If the author chose path A and you would have chosen B, that is not a finding unless A is actually worse for a stated reason.
+
+## Severity hints
+
+- **blocker** — A logical break, a fatal contradiction, a load-bearing claim that is verifiably false, an audience-fit problem so severe the intended reader cannot use the artifact.
+- **concern** — An unsupported claim that needs justification, a missing alternative that weakens the recommendation, a scope ambiguity that will mislead readers.
+- **nit** — A small clarity issue, a passage that could be tightened, a minor inconsistency.
+- **praise** — A non-obvious insight, a tricky trade-off well-handled, a passage that earns the reader's trust. Rare.
+
+## Verdict mapping
+
+- **approve** — No blockers. The artifact stands on its own.
+- **request-changes** — At least one blocker.
+- **comment** — Useful observations without a clean accept/reject. Common for early drafts, exploratory documents, or partial reviews.
+
+## Final output
+
+Return findings inside the reviewer's neutral \`<review>\` block. Do NOT invent your own output format.
+`
+
+export const GENERAL_REVIEW_SKILL: LoadableSkill = {
+  name: GENERAL_REVIEW_SKILL_NAME,
+  description: GENERAL_REVIEW_SKILL_DESCRIPTION,
+  content: GENERAL_REVIEW_SKILL_CONTENT,
+}

package/src/channels/adapters/discord-bot-classify.ts

@@ -6,7 +6,7 @@ import type {
 } from 'agent-messenger/discordbot'
 
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
 export type InboundDropReason =
   | 'self_author' // event.author.id === botUserId; we never route our own messages back to ourselves
@@ -35,7 +35,7 @@ export function classifyInbound(
   if (botUserId !== null && event.author.id === botUserId) {
     return { kind: 'drop', reason: 'self_author' }
   }
-  const text = inboundText(event)
+  const { text, attachments } = splitInbound(event)
   if (text === '') return { kind: 'drop', reason: 'empty_content' }
 
   const isDm = event.guild_id === undefined
@@ -80,6 +80,7 @@ export function classifyInbound(
       chat: event.channel_id,
       thread: null,
       text,
+      ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: event.id,
       authorId: event.author.id,
       // Discord's post-2023 username system allows pure-numeric handles (e.g.
@@ -107,38 +108,45 @@ function isReplyToBot(event: DiscordGatewayMessageCreateEvent, botUserId: string
   return (event.mentions ?? []).some((m) => m.id === botUserId)
 }
 
-function inboundText(event: DiscordGatewayMessageCreateEvent): string {
-  const mediaSummary = summarizeDiscordMedia(event)
-  if (mediaSummary.length === 0) return event.content
-  const summary = `[Discord message with ${mediaSummary.join('; ')}]`
-  return event.content === '' ? summary : `${event.content}\n${summary}`
+type SplitInbound = { text: string; attachments: InboundAttachment[] }
+
+function splitInbound(event: DiscordGatewayMessageCreateEvent): SplitInbound {
+  const attachments = describeDiscordMedia(event)
+  if (attachments.length === 0) return { text: event.content, attachments: [] }
+  const summary = attachments.map(renderPlaceholder).join('\n')
+  const text = event.content === '' ? summary : `${event.content}\n${summary}`
+  return { text, attachments }
 }
 
-function summarizeDiscordMedia(event: DiscordGatewayMessageCreateEvent): string[] {
+function describeDiscordMedia(event: DiscordGatewayMessageCreateEvent): InboundAttachment[] {
   return [
-    ...(event.attachments ?? []).map(summarizeAttachment),
-    ...(event.embeds ?? []).map(summarizeEmbed),
-    ...(event.sticker_items ?? []).map(summarizeSticker),
-  ]
+    ...(event.attachments ?? []).map(describeAttachment),
+    ...(event.embeds ?? []).map(describeEmbed),
+    ...(event.sticker_items ?? []).map(describeSticker),
+  ].map((attachment, index) => ({ ...attachment, id: index + 1 }))
 }
 
-function summarizeAttachment(attachment: DiscordFile): string {
-  return compactJoin(' ', [
-    `attachment: ${attachment.filename}`,
-    attachment.content_type === undefined ? undefined : `(${attachment.content_type})`,
-    attachment.url,
-  ])
+function describeAttachment(attachment: DiscordFile): Omit<InboundAttachment, 'id'> {
+  return {
+    kind: 'file',
+    ref: attachment.url,
+    filename: attachment.filename,
+    ...(attachment.content_type !== undefined ? { mimetype: attachment.content_type } : {}),
+  }
 }
 
-function summarizeEmbed(embed: DiscordGatewayEmbed): string {
+function describeEmbed(embed: DiscordGatewayEmbed): Omit<InboundAttachment, 'id'> {
   const label = embed.title ?? embed.description ?? embed.url ?? embed.type ?? 'embed'
-  return compactJoin(' ', ['embed:', label, embed.url !== undefined && embed.url !== label ? embed.url : undefined])
+  return { kind: 'embed', ref: embed.url ?? '', filename: label }
 }
 
-function summarizeSticker(sticker: DiscordGatewayStickerItem): string {
-  return `sticker: ${sticker.name}`
+function describeSticker(sticker: DiscordGatewayStickerItem): Omit<InboundAttachment, 'id'> {
+  return { kind: 'sticker', ref: '', filename: sticker.name }
 }
 
-function compactJoin(separator: string, parts: Array<string | undefined>): string {
-  return parts.filter((part) => part !== undefined && part !== '').join(separator)
+function renderPlaceholder(attachment: InboundAttachment): string {
+  const parts: string[] = [`Discord attachment #${attachment.id}: ${attachment.kind}`]
+  if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
+  if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)
+  return `[${parts.join(' ')}]`
 }

package/src/channels/adapters/github/inbound.ts

@@ -44,11 +44,17 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     if (!isGithubEventAllowed(options.allowlist(), event, action)) return ok()
 
     const selfId = options.selfId()
-    const author = readAuthor(payload)
-    if (selfId !== null && author !== null && String(author.id) === selfId) return ok()
+    const selfLogin = options.selfLogin()
+    const author = readAuthor(event, payload)
+    if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+      options.logger.info(
+        `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
+      )
+      return ok()
+    }
 
     const teamIsBotMember = await resolveTeamMembership(event, payload, options)
-    const classified = classifyGithubInbound(event, payload, options.selfLogin(), {
+    const classified = classifyGithubInbound(event, payload, selfLogin, {
       teamIsBotMember,
     })
     if (classified === null) return ok()
@@ -357,13 +363,63 @@ function readRepository(payload: Record<string, unknown>): { owner: string; name
   return { owner: ownerLogin, name }
 }
 
-function readAuthor(payload: Record<string, unknown>): GithubUser | null {
-  const candidates = [payload.comment, payload.issue, payload.pull_request, payload.discussion, payload.review]
-  for (const candidate of candidates) {
+function readAuthor(event: string, payload: Record<string, unknown>): GithubUser | null {
+  for (const candidate of eventAuthorCandidates(event, payload)) {
     const user = readUser(readRecord(candidate)?.user)
     if (user !== null) return user
   }
-  return null
+  // Every GitHub webhook payload carries `sender` — the actor who triggered the
+  // delivery. It is the universal fallback so events not enumerated above (and
+  // any future ones the user adds to eventAllowlist) still drop self-authored
+  // deliveries instead of slipping past the guard.
+  return readUser(payload.sender)
+}
+
+// Maps each event to the entity whose `user` is the true author of THIS event,
+// listed before broader containers. A pull_request_review payload ships both
+// `pull_request` (the PR author) and `review` (the reviewer); the self-author
+// drop must see the reviewer, so `review` must come first. PR #455's flat order
+// (`pull_request` before `review`) made a self-review on someone else's PR
+// resolve to the PR author, slip past the drop, and loop (see PR #460).
+//
+// `pull_request` and `pull_request_review_thread` carry only the `pull_request`
+// container, whose `user` is the PR OPENER — not the actor of this delivery.
+// For these events the self-author question is "who triggered the action?"
+// (review_requested, edited, reopened, resolved, …), which is always
+// `payload.sender`, never the opener. Mapping them to `[]` makes readAuthor
+// skip the opener and fall through to the `sender` fallback. PR #462's
+// `['pull_request']` resolved to the opener, so a human action on a
+// bot-opened PR matched the bot and was wrongly dropped (the inbound landed
+// as awareness-only "Recent context" and the agent never replied).
+const PRIMARY_AUTHOR_KEYS: Record<string, readonly string[]> = {
+  issue_comment: ['comment'],
+  pull_request_review_comment: ['comment'],
+  discussion_comment: ['comment'],
+  commit_comment: ['comment'],
+  pull_request_review: ['review'],
+  pull_request_review_thread: [],
+  issues: ['issue'],
+  pull_request: [],
+  discussion: ['discussion'],
+  release: ['release'],
+}
+
+const FALLBACK_AUTHOR_KEYS = ['comment', 'review', 'issue', 'pull_request', 'discussion', 'release'] as const
+
+function eventAuthorCandidates(event: string, payload: Record<string, unknown>): unknown[] {
+  const keys = PRIMARY_AUTHOR_KEYS[event] ?? FALLBACK_AUTHOR_KEYS
+  return keys.map((key) => payload[key])
+}
+
+// Matches by id OR login. Issue #452 captured a self-responding loop where
+// the id-only guard didn't fire and the bot replied to its own comments ~8
+// times in a row. Login is the second line of defense and aligns with the
+// slack/discord/telegram/kakaotalk adapters, which all drop self-authored
+// events at the classifier layer.
+function isSelfAuthor(author: GithubUser, selfId: string | null, selfLogin: string | null): boolean {
+  if (selfId !== null && String(author.id) === selfId) return true
+  if (selfLogin !== null && author.login === selfLogin) return true
+  return false
 }
 
 type GithubUser = { login: string; id: number; type?: string }

package/src/channels/adapters/github/index.ts

@@ -53,6 +53,14 @@ export type GithubAdapterOptions = {
   // Test-only: replaces the wall-clock sleep used for the registration
   // delay above. Production leaves it undefined and we use `setTimeout`.
   sleep?: (ms: number) => Promise<void>
+  // How often to proactively refresh the token and update GH_TOKEN
+  // when the adapter is running but has not made an outbound API call
+  // recently. Zero disables the background refresh entirely.
+  // Default: 30 minutes.
+  tokenRefreshIntervalMs?: number
+  // Test-only: replaces `setInterval` so tests can control when the
+  // background refresh fires without waiting on real wall-clock time.
+  setInterval?: (handler: () => void, ms: number) => { clear: () => void }
 }
 
 export type GithubAdapter = {
@@ -68,6 +76,7 @@ const consoleLogger: GithubAdapterLogger = {
 }
 
 const DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS = 2_000
+const DEFAULT_TOKEN_REFRESH_INTERVAL_MS = 30 * 60 * 1000
 
 export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
   const logger = options.logger ?? consoleLogger
@@ -83,6 +92,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let selfLogin: string | null = null
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
+  let tokenRefreshTimer: { clear: () => void } | null = null
   const workspaceByChat = new Map<string, string>()
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
@@ -168,6 +178,24 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // automatically when within 5 minutes of expiry.
       process.env.GH_TOKEN = await auth.token()
       started = true
+      // Keep GH_TOKEN warm even when the adapter is only receiving inbound
+      // webhooks and not making outbound API calls. This prevents `gh` CLI
+      // calls from the agent from failing with 401 after the token expires.
+      const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
+      if (tokenRefreshIntervalMs > 0) {
+        const refresh = () => {
+          tokenFn().catch((err) => {
+            logger.error(`[github] periodic token refresh failed: ${err instanceof Error ? err.message : String(err)}`)
+          })
+        }
+        const setIntervalFn =
+          options.setInterval ??
+          ((handler: () => void, ms: number) => {
+            const timer = setInterval(handler, ms)
+            return { clear: () => clearInterval(timer) }
+          })
+        tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
+      }
       logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
       // Best-effort: App-only preflight that compares the installation's granted
       // permissions against the configured eventAllowlist and warns about gaps.
@@ -241,6 +269,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         logDeregistrationOutcome(logger, deregistration)
         managedHooks = []
       }
+      if (tokenRefreshTimer !== null) {
+        tokenRefreshTimer.clear()
+        tokenRefreshTimer = null
+      }
       await auth.dispose()
       delete process.env.GH_TOKEN
       server = null