sv2bot-discord

Discord integration for the sv2bot / sv2pi operations agent used by the SRI community deployment.

Attribution and fork status

This project is a fork/adaptation of @venthezone/picord by VenTheZone.

Upstream package metadata from the codebase we started from:

• npm package: @venthezone/picord
• npm version: 0.2.4
• npm tarball captured locally as: vendor/venthezone-picord-0.2.4.tgz
• upstream repository metadata from package.json: https://github.com/VenTheZone/picord
• upstream license: MIT, copyright VenTheZone

This repository was bootstrapped from the locally installed npm package source that had already been patched for the sv2bot Discord deployment. The upstream GitHub repository did not expose a matching v0.2.4 release tag at bootstrap time, so this repository intentionally starts as a new Git history rather than a literal GitHub fork preserving upstream commits.

License

This project inherits the upstream MIT license. See LICENSE.

Why this exists

The sv2bot deployment uses Pi plus Picord to let SRI community humans interact with a Stratum V2 operations agent from Discord. During deployment, several local patches accumulated inside the globally installed npm package. Those edits were operationally useful but fragile: reinstalling or updating Picord could erase them.

sv2bot-discord exists to make that patch set explicit, reviewable, reproducible, and eventually publishable under the SV2-bot GitHub organization.

Bootstrap source and patch inventory

The first commit contains the current patched Picord source as deployed on /home/sv2bot.

The pristine upstream npm tarball is stored at:

vendor/venthezone-picord-0.2.4.tgz

A generated diff from pristine @venthezone/picord@0.2.4 to this patched tree is stored at:

docs/patch-inventory/picord-0.2.4-to-sv2bot-discord.patch

At bootstrap, the changed files relative to the pristine npm tarball were:

src/config.ts
src/conversation.ts
src/discord-port/discord-bot.ts
src/discord-port/extension-bridge.ts
src/index.ts
src/live-discord-renderer.ts
src/pi-session.ts
src/safe-tools.ts

Operational patch themes

The initial sv2bot patch set includes changes made while bringing the bot online in the private SRI Discord channel:

• access-policy and host-channel behavior fixes;
• explicit bot mention gating before thread/session creation;
• thread-name cleanup for bot/role mentions;
• Pi SDK tool-call execution fixes so tools execute instead of leaking literal <tool_call> text;
• Discord output noise reduction;
• Docker-capable operational use from Discord sessions;
• preliminary file attachment support via final-answer attachment directives and a send_file custom tool.

The durable operational history for these changes lives in the sv2bot vault on the VPS, especially:

/home/sv2bot/vault/interventions/2026-05-07-discord-onboarding-synthesis.md
/home/sv2bot/vault/deployments/picord-discord-agent-setup.md
/home/sv2bot/vault/interventions/2026-05-08-picord-pool-hashrate-attachment-plan.md

Sending a file to a Discord channel

sv2bot-discord includes a small channel-sending CLI for operational artifacts such as pool hashrate charts.

Example:

PICORD_CONFIG=/home/sv2bot/.picord/picord.config.json \
PICORD_DISCORD_TOKEN="$PICORD_DISCORD_TOKEN" \
npm run send:file -- \
  --channel-id 1501133804058710116 \
  --file /home/sv2bot/vault/pool-hashrate.png \
  --message "Latest pool hashrate chart"

The CLI:

• reads PICORD_DISCORD_TOKEN or DISCORD_BOT_TOKEN;
• reads PICORD_CONFIG when provided;
• defaults to PICORD_SEND_FILE_CHANNEL_ID or the first allowedChannelIds entry if --channel-id is omitted;
• sends the file as a Discord attachment with allowedMentions: { parse: [] };
• supports --dry-run for validating token/config/channel/file without posting.

Dry run:

npm run send:file -- --file /home/sv2bot/vault/pool-hashrate.png --dry-run

Near-term roadmap

Next planned work:

1. preserve and review the bootstrap patch inventory;
2. validate the existing reactive file-attachment path;
3. wire pool-monitor automation to the channel-sending CLI when desired;
4. prepare for publication at github.com/SV2-bot/sv2bot-discord once the GitHub side is ready.