🪂🔭 Ompcord — Handoff & Ecosystem Research Charter

Source session: amy-jun10-1631 (thread 1514275906170912769, 2026-06-10). This page is the seamless-continuation handoff: the next agent should be able to proceed without reading that conversation. Two parts: (A) Handoff — exact state + finalized rename plan; (B) Research Charter — the next session’s main job.

---

🎯 Goal

Evolve the always-on omp⇄Discord bridge toward 100% intuitive, responsive perfection. The product is being branded Ompcord (bot/persona stays Amy). Because the product is still early-stage, the next session must run exhaustive, multi-source research across the entire pi/omp/discord plugin & package ecosystem and publish a deep comparative report in these docs: what to learn or adapt from each.

---

🧱 Constraints & Preferences (established — do not relitigate)

• 🟥 Real Discord UI only. When a live Discord session exists, NEVER post Markdown/code-box mockups of embeds. Send actual embed + components via ~/pi-discord-amy/live-responsive-interview.mjs <thread-id>.
• ⏱️ Discord ACK ≤ 3s. showModal() first for a modal; deferUpdate()/deferReply() first for any slow path. The handler process must stay alive or components render dead.
• 👥 Allow-list gates everything — every inbound message, slash command, button, select, modal.
• 🔑 NEVER paste a bot token in chat. Token lives only in env / systemd EnvironmentFile, never source/commits/logs.
• 🧰 Toolchain: Bun for dev/QA/tests (bun.lock is SSOT); daemon deploys under Node (node amyd.mjs today, node ompcordd.mjs wrapper-supported). Only declared dep: discord.js@^14.26.4. typebox is host-provided (do not vendor).
• 🖥️ Emojified, compact, idiot-proof comments & docs — high-level “idiot overstanding” with // 🚀 why/what/how one-liners.
• 📚 Docs = Hugo at funday/dev/docs (content/docs/* → /*). Served by hugo-docs.service (hugo server, in-memory, auto-rebuilds on file save — no restart needed). Use {{</* relref */>}} for links, never hardcoded /... paths.
• ✅ Every change ships with docs + tests and is verified: node --check *.mjs · bun test · hugo --minify.

---

📦 Progress

✅ Done (this session + immediately prior)

• Responsive interview embed — live-proven in the coms thread (message 1514313332268597429 in thread 1514275906170912769): embed fields, single/multi select, pagination buttons, busy buttons, Custom… modal, Confirm/Cancel, in-place edits. Docs: discord-responsive-interview; sender live-responsive-interview.mjs; skill discord-live-responsive-interview.
• SSOT embed dashboard — /amy status, /amy health, /amy cancel + Refresh / Open Thread / Cancel(when busy) buttons (ACK via deferUpdate()). Pure module status.mjs (createRuntimeState/snapshotStatus/renderStatusEmbed/renderStatusComponents); streamed message_end model/provider/api + token/cache/cost usage when present; fallback stays explicitly unavailable. Docs: amy-ssot-dashboard.
• Rocket-launch channels — launch.mjs (parseLaunchChannels/shouldPrimeLaunchMessage/shouldTriggerLaunch); 🚀 react-to-run in AMY_LAUNCH_CHANNEL_IDS (default 1513664007146438666); channel dashboard → session thread → mirrored progress; double-click race fixed (source-id reserved "pending" before awaits). Docs: amy-rocket-launch.
• Session continuity (CLI ⇄ Discord) — every thread is an on-disk omp session at ~/.omp/amy-sessions/<threadId>/; resume with --session-dir … -c. Docs: amy-session-continuity (deployed live).
• Verification: bun test → 37 pass / 105 assertions; hugo --minify clean (only the pre-existing languageCode deprecation warning).

✅ Resolved in the continuation session (2026-06-10)

• 🔭 Ecosystem research report — delivered: agents/ompcord-ecosystem-learnings (weight 10), every charter target covered with the 5-point structure + prioritized early-stage wins; cross-linked from _index.md + this page; hugo --minify clean; live (HTTP 200).
• Redeploy amyd safely — alias/telemetry deploy moved pid 3133087 → 3136782; Phase 4 wrapper-runtime deploy dry-run found amyd.mjs idle, then node redeploy.mjs moved pid 3136782 → 3429641 and relaunched the same legacy entrypoint. Final process: /usr/bin/node amyd.mjs; final log: ONLINE as Amy#0305, registered 2 slash command(s): amy,ompcord, ready — /amy, /ompcord, and thread chat are live. Interactive slash/button click remains human-gated (a bot cannot self-invoke its own slash commands); tests cover the logic.
• Ompcord rename — Phases 1–4 — naming callouts are consistent, /ompcord aliases are live, the bridge page is now agents/ompcord, and runtime wrapper-first cutover is shipped: ompcordd.mjs/ompcordd.service exist while amyd.mjs, amyd.service, legacy config, and ~/.omp/amy-sessions remain compatible.
• Docs link cleanup — fixed every broken /* link (homepage docs/_index.md nav ×8, audits/_index.md, agents/discord-thread-dashboard-plan.md) to {{</* relref */>}}; verified zero / remain in rendered output. (content/_index.md is outside contentDir and ignored by Hugo — left as-is.)
• Top early-stage wins #1–#2 — /amy status now consumes real message_end.message.usage (input/output/cache/total/cost + model/provider/api) instead of hardcoding unavailable when JSONL provides it, and tool_execution_end.isError marks failed tools red in the live dashboard/runtime status. Covered by stream.test.mjs + status.test.mjs; verified with node --check and bun test (42 pass / 124 assertions).
• Phase 4 verification — node --check amyd.mjs && node --check ompcordd.mjs && node --check config.mjs && node --check redeploy.mjs && node --check live-responsive-interview.mjs; bun test → 48 pass / 141 assertions across 8 files; hugo --minify --cleanDestinationDir clean except the pre-existing languageCode deprecation warning; rendered link scan found no duplicate docs-path hrefs and no stale bridge relrefs.

✅ Rename completion

• Ompcord rename Phase 5 — package identity now matches product naming (package.json.name + bun.lock workspace name are ompcord). Repo directory stays pi-discord-amy until a separate filesystem cutover can preserve local service paths and history.

---

🧭 Key Decisions

• Naming split — “Ompcord” product, “Amy” persona. Users install/use Ompcord; Amy is the bot/persona Ompcord runs.

  Layer	Name	Why
  Product / plugin	ompcord	Short, memorable, “omp + Discord”.
  Bot / persona	Amy	Human-friendly runtime identity.
  Daemon	ompcordd wrapper live; amyd compat	Product-aligned daemon name without breaking the deployed legacy entrypoint.
  Legacy compat	pi-discord-remote	Existing config/command must not break abruptly.

• Phase the rename — docs first, repo-directory last. Docs, command aliases, runtime wrapper, service wrapper, session/config compatibility, and package name now carry Ompcord; the physical repo path stays pi-discord-amy until a separate filesystem cutover can preserve local service paths/history.

• Keep tool names discord_ask_user_question / discord_send_image — they name capability, not product, and are an LLM-facing contract that skills/prompts depend on. Optional ompcord_* aliases only after tests prove identical contracts.

---

🗺️ Critical Context (paths, commands, IDs)

• Repo (→ Ompcord): ~/pi-discord-amy/ — amyd.mjs (legacy daemon + startDaemon()), ompcordd.mjs (same-process wrapper), ompcordd.service, run.mjs (headless loop + JSONL parser + ASK_PROTOCOL), dashboard.mjs (evolving embed), slash.mjs (/amy + /ompcord), ask.mjs (askViaDashboard), status.mjs (SSOT), launch.mjs (rocket), live-responsive-interview.mjs, redeploy.mjs, config.mjs, helpers.mjs, index.mjs (Pi extension). Read ~/pi-discord-amy/AGENTS.md before editing.
• Sessions: default remains ~/.omp/amy-sessions/<threadId>/*.jsonl; OMPCORD_SESSION_ROOT or an existing ~/.omp/ompcord-sessions is supported without stranding legacy threads. Continue any thread: omp --allow-home --cwd /home/usr --session-dir ~/.omp/amy-sessions/<threadId> -c.
• Docs: funday/content/docs/agents/*.md; build/validate cd ~/funday/dev/docs && hugo --minify; live server auto-rebuilds on save (hugo-docs.service, 127.0.0.1:1313 → wiki.funday.gg/).
• Live IDs: guild 1496176276933972110 · coms thread 1514275906170912769 (amy-jun10-1631) · launch channel 1513664007146438666.
• Verify trio: node --check amyd.mjs ompcordd.mjs config.mjs redeploy.mjs slash.mjs status.mjs launch.mjs · bun test · hugo --minify.

---

🏗️ Ompcord rename migration plan (finalized — execute in order)

Each phase is independently shippable and reversible. Do not skip ahead; runtime risk rises with each phase.

Phase	Scope	Actions	Risk
1	📝 Docs + vocabulary	✅ Done: state “Ompcord = the bridge, Amy = the persona” across ompcord.md, discord-responsive-interview.md, amy-ssot-dashboard.md, amy-rocket-launch.md, pi-discord-amy/AGENTS.md.	none
2	🔗 Command alias	✅ Done: Pi TUI /ompcord alongside legacy /pi-discord-remote; Discord /ompcord alongside persona /amy; old commands remain compat aliases.	low
3	📄 Page rename	✅ Done: omp-pi-discord.md → ompcord.md with Hugo aliases for the old URL before the old file was removed.	low
4	⚙️ Runtime	✅ Done wrapper-first: ompcordd.mjs imports/starts amyd.mjs’s exported startDaemon() in-process; ompcordd.service reads legacy Amy env then Ompcord env; redeploy.mjs detects/relaunches either entrypoint; session root defaults to legacy but supports OMPCORD_SESSION_ROOT/existing ~/.omp/ompcord-sessions.	medium
5	📦 Package	✅ Done: package.json.name and bun.lock workspace name are ompcord; repo directory intentionally remains pi-discord-amy for service/path compatibility until a later filesystem cutover.	medium

---

🔭 Part B — Ecosystem Research Charter (next session’s mission)

✅ DELIVERED (session continuation, 2026-06-10): the report this charter commissioned is live at Ompcord — Ecosystem Learnings — every target below covered with the 5-point structure + a prioritized early-stage wins table. The charter remains here as the spec it was built against.

Mandate (verbatim intent): ultra-deep, holistic, perpetually-looping, obsessive research — meticulously scanning ALL diverse sources EVERYWHERE — until practical, genius, idiot-proof understanding of ALL OTHER relevant pi/omp/discord plugins & packages is achieved; then publish a deep comparative report in docs on what we can learn or adapt from each, given we’re still early-stage.

📥 Deliverable

Create agents/ompcord-ecosystem-learnings.md (weight 10, cross-link from _index.md + this page). For each target below, one section answering exactly:

1. What it is / does (1–2 lines, grounded — read the actual source).
2. Key patterns & APIs worth knowing (hooks, tool registration, lifecycle, data flow, config).
3. 🟢 Adopt / 🟡 Adapt / 🔴 Skip for Ompcord — with the concrete reason.
4. Effort & risk if adopted (S/M/L · low/med/high).
5. Citation — exact file path or URL read (no unsourced claims).

End with a prioritized “early-stage wins” table: top 5–8 things to adopt now, ranked by value ÷ effort.

🎯 Target inventory (grounded — versions observed locally)

Internal omp/pi packages (.bun/install/cache/@oh-my-pi/)

Package	Ver	Why it matters to Ompcord
pi-coding-agent	15.10.7	The omp CLI + extension API Ompcord plugs into. Read examples/extensions/* and examples/hooks/*.
pi-agent-core	15.10.7	Agent loop, compaction, handoff prompts (src/compaction/prompts/handoff-document.md), plan-mode (src/plan-mode/plan-handoff.ts).
pi-ai	15.10.7	Model/provider abstraction → informs honest model/provider/usage reporting in the SSOT dashboard.
pi-tui	15.10.7	TUI rendering primitives → parity ideas for embed/component rendering.
pi-mnemopi / pi-mnemosyne	15.10.7 / 15.6.0	Memory/recall → could back Amy cross-session context.
hashline	15.10.7	Structural edit format → patterns for safe transforms.
pi-utils / pi-natives	15.10.x	Shared utilities / native bits.

Installed omp plugins (~/.omp/plugins/package.json)

Plugin	Ver	Learn / adapt angle
@oh-my-pi/omp-stats	15.10.10	Usage/stats surfacing → feed real numbers into /amy status & /amy health.
@oh-my-pi/swarm-extension	13.17.0	Multi-agent swarm orchestration → future “Amy delegates to sub-agents” mode.
pi-langfuse	1.5.1 (patched)	Observability/tracing → run telemetry for Ompcord turns.
pi-discord-remote	0.2.4	The published baseline (“each session gets its own auto-created channel”) that Ompcord forks/supersedes — diff its UX vs threads/embeds.

Discord libraries

Package	Ver	Focus
discord.js	14.26.4	Interaction lifecycle, components v2, modals, rate limits, partials/intents.
discord-api-types	0.38.48	Canonical payload shapes / limits.
@discordjs/*	—	builders, rest, ws internals.

External comparables (scan widely)

• @earendil-works/pi-coding-agent 0.78.0 — an alternate pi coding-agent fork; compare its extension/handoff model (examples/extensions/handoff.ts).
• Other LLM/agent Discord bridges on npm + GitHub (coding-agent-in-Discord, ChatGPT/Claude Discord bots, agent-ops dashboards).
• discord.js official guide patterns: interaction collectors, ephemeral flows, button/select/modal wizards, pagination.
• Adjacent chat-ops bridges (Slack/Matrix agent bots) for dashboard/approval UX ideas.

🔁 Methodology — the obsessive loop

flowchart LR
  A[🎯 Pick target] --> B[📖 Read REAL source<br/>.bun cache · npm · GitHub · docs]
  B --> C[🧪 Extract patterns/APIs]
  C --> D[⚖️ Adopt / Adapt / Skip<br/>+ effort/risk]
  D --> E[✍️ Write section + citation]
  E --> F{More targets<br/>or open questions?}
  F -- yes --> A
  F -- no --> G[🏆 Prioritized early-stage wins]

• 📂 Prefer local source-of-truth first: read packages under .bun/install/cache/... directly (they’re on disk) before reaching for the web — then corroborate with npm/GitHub/official docs.
• 🌐 Use web_search + read <url> for npm pages, GitHub READMEs, discord.js guide; cite every external claim with a link.
• 🧠 Delegate breadth with task subagents (one per target cluster), keep synthesis/judgment in the lead context. READ-ONLY agents (explore/librarian) for source spelunking; lead writes the report.
• ♻️ Loop until no open question materially reduces uncertainty — then synthesize.

✅ Acceptance criteria

• agents/ompcord-ecosystem-learnings.md exists, covers every target above, each with the 5-point structure + citation.
• Prioritized “early-stage wins” table present and defensible (value ÷ effort).
• Cross-linked from _index.md and this page; hugo --minify clean; page renders live.
• Zero unsourced claims; zero Markdown-mockup hand-waving — patterns grounded in real source/URLs.

---

🔗 Related: Ompcord — Always-on Discord Bridge · Responsive Interview Embed · SSOT Dashboard · Rocket Launch · Session Continuity.