docs: Discord bot for Electric Agents — design spec

[balegas]

Summary

Spec + implementation plan + a near-complete v1 of @electric-ax/discord-bot, a Discord bot for Electric Agents.

• Spec: docs/superpowers/specs/2026-05-13-discord-bot-design.md
• Plan: docs/superpowers/plans/2026-05-13-discord-bot.md (18 tasks)
• Code: new workspace package at factory/discord-bot/ — Discord adapter (Node) + a discord-bot entity registered into agents-server

What's in the box

• factory/discord-bot/ (new workspace package, npm name @electric-ax/discord-bot):
  • Portable Discord REST client over raw fetch (no node:*, no @discordjs/rest on the entity side)
  • Six discord.* tools: post_message, edit_message, create_thread, read_thread_history, add_reaction, read_channel_around_message
  • delegate.spawn_horton tool for handing coding tasks to a Horton entity
  • Zod-typed DiscordWakeMessage discriminated union (mention / thread_msg / interaction / thread_close)
  • System prompt + prime-context builder + registerDiscordBot(registry, opts) entity registration
  • Node adapter: Gateway WebSocket via discord.js, HTTP Interactions endpoint with Ed25519 verification via node:crypto, wake webhook poster, "start thread on bare mention" helper, host-node entrypoint, slash-command registration CLI
  • 35/35 tests passing across 15 test files (unit + integration); typecheck clean; build produces both bin entries

⚠️ Known critical issues — NOT ready to merge

The final code review identified three runtime-correctness failures that mean the bot won't function end-to-end as-is. The plan's draft assumed agents-runtime and agents-server API surfaces that don't match reality. The entity-side code is well-shaped and portable, but three integration points need fixes before this can run for real:

1. spawn_horton will throw at runtime. entity.ts accesses ctx.runtimeServerClient.spawnEntity(...), but the real HandlerContext exposes ctx.spawn(type, id, args, opts) instead. The cast resolves to undefined. Fix: pass ctx.spawn into createSpawnHortonTool and adapt the wake config to { on: 'runFinished', includeResponse: true }.

2. Wake webhook URL doesn't exist. Adapter POSTs to <agents-server>/webhook/discord-bot but agents-server's real endpoints are PUT /_electric/entities/discord-bot/:threadId (create-or-find) + POST /_electric/entities/discord-bot/:threadId/send (deliver message). Every Discord event currently 404s into the void.

3. botUserId = appId is wrong. Application ID and the bot's user-ID snowflake are distinct values. Mention filtering compares against the wrong ID, so all @mentions in non-thread channels are silently dropped. Fix: read client.user.id after client.login() returns, or accept an explicit DISCORD_BOT_USER_ID env var.

Important issues (pre-merge, not pre-runtime)

• extraMcpServers is declared in DiscordBotOptions but never consumed (silently dropped) — README is misleading.
• Thread-archive → thread_close wake never triggers (only /end slash command does; no threadUpdate listener).
• thread_close inserts a context entry but doesn't actually stop the entity.
• Messages from other bots in a thread are forwarded as thread_msg (potential noise/loop source).
• extractModelConfig re-invents the wheel rather than using resolveBuiltinModelConfig from packages/agents/src/model-catalog.ts; passes the wrong shape and silently falls through to a hardcoded claude-sonnet-4-6 default.

Minor cleanups

• pino listed in dependencies but never imported (adapter uses console.log).
• stripMentions regex broadened from \d+ to [\w]+ (incorrect, low-impact).
• Bin entries may lack a Node shebang.
• One test description is stale (?around=&limit= reads "around" but implementation uses before + after).

How this branch was built

This branch was built with the superpowers skill chain: brainstorming → writing-plans → subagent-driven-development with two-stage review per task. 18 task commits + interleaved cleanup commits. The final whole-branch review (using the superpowers:code-reviewer agent) is what surfaced the three critical integration gaps above — the per-task reviews on each individual file passed.

The plan was written before the agents-runtime/agents-server contracts were fully validated against the real types. The lesson, for next time: validate the framework integration contract (spawn, send, webhook routes) against real types before writing the plan, not during execution.

Test plan

• Per-package tests: pnpm --filter @electric-ax/discord-bot test → 35/35 ✓
• Typecheck: pnpm --filter @electric-ax/discord-bot typecheck → exit 0 ✓
• Build: pnpm --filter @electric-ax/discord-bot build → produces dist/host-node.js, dist/register-commands.js, dist/index.{js,cjs,d.ts} ✓
• TODO before merge: address Critical issues 1-3 (spawn API, webhook URL, botUserId).
• TODO before merge: address Important issues 4-9.
• End-to-end live smoke against a test Discord guild + a local agents-server.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for electric-next ready!

Name	Link
🔨 Latest commit	7986270
🔍 Latest deploy log	https://app.netlify.com/projects/electric-next/deploys/6a044bf2984bda0009be0598
😎 Deploy Preview	https://deploy-preview-4324--electric-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 56.69%. Comparing base (d8cb2bb) to head (99a27fb).
⚠️ Report is 79 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4324       +/-   ##
===========================================
- Coverage   74.30%   56.69%   -17.62%     
===========================================
  Files          42      273      +231     
  Lines        4523    25593    +21070     
  Branches     1310     6875     +5565     
===========================================
+ Hits         3361    14509    +11148     
- Misses       1157    11070     +9913     
- Partials        5       14        +9     

Flag	Coverage Δ
packages/agents	70.78% <ø> (?)
packages/agents-mcp	77.54% <ø> (?)
packages/agents-runtime	80.01% <ø> (?)
packages/agents-server	73.20% <ø> (-1.11%)	⬇️
packages/agents-server-ui	6.25% <ø> (?)
packages/electric-ax	37.59% <ø> (?)
packages/experimental	87.73% <ø> (?)
packages/react-hooks	86.48% <ø> (?)
packages/start	82.83% <ø> (?)
packages/y-electric	56.05% <ø> (?)
typescript	56.69% <ø> (-17.62%)	⬇️
unit-tests	56.69% <ø> (-17.62%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agent-horton]

Verdict

Looks good

---

Findings

No critical, important, or suggestion-level issues found.

Summary

• The change to packages/agents-runtime/src/index.ts simply exports a new type RuntimeServerClient. This is a non-breaking, incremental improvement to the public API exposure and appears correct.
• The changes in pnpm-lock.yaml update dependency pins, switching away from local packages (link:) to explicit published versions (0.2.0, 0.2.1, etc.) and reworking some dependency closure details for specific packages.

There are no behavioral changes, code logic changes, or public API breaking changes present. No issues need to be addressed prior to merge. Test and runtime risk is minimal; package manager lockfile changes are consistent with updating to new published packages. No findings requiring further review.

[agent-horton]

Verdict

Looks good

---

Findings

No critical, important, or suggestion-level issues found.

Summary

• The change to packages/agents-runtime/src/index.ts simply exports a new type RuntimeServerClient. This is a non-breaking, incremental improvement to the public API exposure and appears correct.
• The changes in pnpm-lock.yaml update dependency pins, switching away from local packages (link:) to explicit published versions (0.2.0, 0.2.1, etc.) and reworking some dependency closure details for specific packages.

There are no behavioral changes, code logic changes, or public API breaking changes present. No issues need to be addressed prior to merge. Test and runtime risk is minimal; package manager lockfile changes are consistent with updating to new published packages. No findings requiring further review.

[agent-horton]

Looks good

---

No findings.

• The only change in packages/agents-runtime/src/index.ts is to export the RuntimeServerClient type, which is a safe enhancement to the public API and does not alter functionality.
• Updates in pnpm-lock.yaml replace local package links with explicit published package versions and clarify peer dependencies—this is a standard and low-risk dependency management adjustment.
• There are no code logic changes, security implications, or architectural concerns.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The only change in packages/agents-runtime/src/index.ts is to export the RuntimeServerClient type, which is a safe enhancement to the public API and does not alter functionality.
• Updates in pnpm-lock.yaml replace local package links with explicit published package versions and clarify peer dependencies—this is a standard and low-risk dependency management adjustment.
• There are no code logic changes, security implications, or architectural concerns.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The packages/agents-runtime/src/index.ts file now additionally exports the RuntimeServerClient type, which is a straightforward and low-risk change to expand the public API.
• The changes in pnpm-lock.yaml update dependencies from local package links to published package versions, with corresponding peer dependency and snapshot updates.
• No logic or functionality changes, no security or performance impacts, and no architectural deviations were introduced.

This PR is ready to merge as is.

[agent-horton]

Looks good

---

No findings.

• The packages/agents-runtime/src/index.ts file now additionally exports the RuntimeServerClient type, which is a straightforward and low-risk change to expand the public API.
• The changes in pnpm-lock.yaml update dependencies from local package links to published package versions, with corresponding peer dependency and snapshot updates.
• No logic or functionality changes, no security or performance impacts, and no architectural deviations were introduced.

This PR is ready to merge as is.

[agent-horton]

Looks good

---

No findings.

• The PR updates packages/agents-runtime/src/index.ts to export the RuntimeServerClient type, which is a backwards-compatible enhancement to the public API surface.
• The updates in pnpm-lock.yaml adjust dependencies from local links to published package versions, and update dependency snapshots accordingly.
• There are no code logic, security, or design changes that require attention.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The PR updates packages/agents-runtime/src/index.ts to export the RuntimeServerClient type, which is a backwards-compatible enhancement to the public API surface.
• The updates in pnpm-lock.yaml adjust dependencies from local links to published package versions, and update dependency snapshots accordingly.
• There are no code logic, security, or design changes that require attention.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The only change in packages/agents-runtime/src/index.ts is exporting the RuntimeServerClient type, which is a straightforward and backward-compatible API improvement.
• The updates in pnpm-lock.yaml update dependency pins from local link: references to explicit published versions, which is standard package management maintenance. These changes do not impact runtime logic, security, or project conventions.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The only change in packages/agents-runtime/src/index.ts is exporting the RuntimeServerClient type, which is a straightforward and backward-compatible API improvement.
• The updates in pnpm-lock.yaml update dependency pins from local link: references to explicit published versions, which is standard package management maintenance. These changes do not impact runtime logic, security, or project conventions.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The PR in packages/agents-runtime/src/index.ts adds a new export for the RuntimeServerClient type. This is a safe extension to the public API and does not affect runtime behavior.
• The updates in pnpm-lock.yaml move dependencies from local package links to specific published versions, updating the dependency graph as appropriate. These changes are standard for aligning with released packages and maintaining cohesion in the dependency tree.
• No logic, security, performance, or architectural issues are introduced. There are also no test or coverage concerns.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The PR in packages/agents-runtime/src/index.ts adds a new export for the RuntimeServerClient type. This is a safe extension to the public API and does not affect runtime behavior.
• The updates in pnpm-lock.yaml move dependencies from local package links to specific published versions, updating the dependency graph as appropriate. These changes are standard for aligning with released packages and maintaining cohesion in the dependency tree.
• No logic, security, performance, or architectural issues are introduced. There are also no test or coverage concerns.

This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The PR only expands the export surface in packages/agents-runtime/src/index.ts by adding the RuntimeServerClient type, which is a safe, backwards-compatible improvement.
• Updates to pnpm-lock.yaml move dependencies from local links to explicit published package versions and update dependency subgraphs accordingly.
• There are no logic, security, performance, or architectural issues and no changes that affect functionality.

The PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The PR only expands the export surface in packages/agents-runtime/src/index.ts by adding the RuntimeServerClient type, which is a safe, backwards-compatible improvement.
• Updates to pnpm-lock.yaml move dependencies from local links to explicit published package versions and update dependency subgraphs accordingly.
• There are no logic, security, performance, or architectural issues and no changes that affect functionality.

The PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The packages/agents-runtime/src/index.ts file now exports the RuntimeServerClient type, which is a backward-compatible API improvement and poses no risk to existing consumers.
• The updates to pnpm-lock.yaml replace local package references with explicit published versions and adjust related dependency graphs. These are standard, non-disruptive package management maintenance steps.

No logic, security, performance, or architectural issues were introduced. This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The packages/agents-runtime/src/index.ts file now exports the RuntimeServerClient type, which is a backward-compatible API improvement and poses no risk to existing consumers.
• The updates to pnpm-lock.yaml replace local package references with explicit published versions and adjust related dependency graphs. These are standard, non-disruptive package management maintenance steps.

No logic, security, performance, or architectural issues were introduced. This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The only change in packages/agents-runtime/src/index.ts is a new type export (RuntimeServerClient), which is a minor, backwards-compatible API addition.
• Updates in pnpm-lock.yaml ensure that dependencies now reference explicit published versions instead of local links, and adjust peer and transitive dependencies accordingly. These updates are standard maintenance and do not pose a risk to runtime behavior or code logic.

There are no logic changes, security implications, or architectural concerns introduced by this PR. The changes are safe to merge.

[agent-horton]

Looks good

---

No findings.

• The only change in packages/agents-runtime/src/index.ts is a new type export (RuntimeServerClient), which is a minor, backwards-compatible API addition.
• Updates in pnpm-lock.yaml ensure that dependencies now reference explicit published versions instead of local links, and adjust peer and transitive dependencies accordingly. These updates are standard maintenance and do not pose a risk to runtime behavior or code logic.

There are no logic changes, security implications, or architectural concerns introduced by this PR. The changes are safe to merge.

[agent-horton]

Looks good

---

No findings.

• The PR makes a minimal, non-breaking change by exporting the RuntimeServerClient type from packages/agents-runtime/src/index.ts.
• Lockfile (pnpm-lock.yaml) updates switch dependencies from local link: refs to explicit published package versions, updating peer and transitive dependencies accordingly. No logic or runtime behavior is changed.

There are no critical, important, or suggestion-level issues. This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The PR makes a minimal, non-breaking change by exporting the RuntimeServerClient type from packages/agents-runtime/src/index.ts.
• Lockfile (pnpm-lock.yaml) updates switch dependencies from local link: refs to explicit published package versions, updating peer and transitive dependencies accordingly. No logic or runtime behavior is changed.

There are no critical, important, or suggestion-level issues. This PR is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The only code change in packages/agents-runtime/src/index.ts is to export the RuntimeServerClient type, which is a safe, backwards-compatible improvement to the public API.
• The modifications in pnpm-lock.yaml migrate package dependencies from local link: references to explicit published versions and update peer and transitive dependencies accordingly. These are standard maintenance updates and do not impact runtime code or behavior.

There are no logic, security, performance, or design concerns introduced by this PR. It is ready to merge.

[agent-horton]

Looks good

---

No findings.

• The only code change in packages/agents-runtime/src/index.ts is to export the RuntimeServerClient type, which is a safe, backwards-compatible improvement to the public API.
• The modifications in pnpm-lock.yaml migrate package dependencies from local link: references to explicit published versions and update peer and transitive dependencies accordingly. These are standard maintenance updates and do not impact runtime code or behavior.

There are no logic, security, performance, or design concerns introduced by this PR. It is ready to merge.