Bifrost Bridge

Bifrost is the bridge for GameCult agent work that needs to cross into GitHub, Discord, or another governed external surface.

That means Bifrost owns the operational meaning of the crossing:

what action is being requested
which repo, channel, PR, or discussion surface it targets
which agent or account is acting
what permission or review state made the action acceptable
what receipt proves the crossing happened

It does not mean Bifrost should own OAuth sludge. Heimdall owns OAuth, linked identities, token custody, grants, and signed account claims. Bifrost consumes Heimdall identity and permission facts, then decides whether a bridge action is allowed in the Bifrost domain.

Ownership

Heimdall owns provider OAuth and account-linked credentials.
Bifrost owns bridge action policy, routing, execution receipts, and governance transport.
VoidBot observes Discord, packages conversation, and speaks through registered personas. It should not be the durable authority that mutates GitHub.
CultCache stores lightweight agent transport packets when the bridge needs file-native state.
CultNet carries those packets between runtimes.

Local Bridge CLI

tools/bifrost-bridge.mjs is the current local bridge executor.

It intentionally uses boring local credentials while Heimdall's managed GitHub credential runtime is still unfinished:

GitHub actions use the local gh authenticated account.
Discord posts use BIFROST_DISCORD_BOT_TOKEN or DISCORD_BOT_TOKEN.

The CLI is not the final permission system. It is the working bridge actuator Bifrost owns now, so VoidBot and repo Faces can stop carrying this machinery themselves.

GitHub Draft PR

node .\tools\bifrost-bridge.mjs github-draft-pr `
  --repo-root E:\Projects\AetheriaLore `
  --identity nibu `
  --title "Nibu: Glitchcraft and reset-loop continuity" `
  --path Aetheria/Articles/Nibu/glitchcraft-and-reset-loops.md `
  --content-file E:\tmp\article.md `
  --body "Drafted from recent Aquarium consensus." `
  --base main

The command:

checks the target repo is clean unless --allow-dirty is set
creates a branch
writes the target file
commits and pushes
opens a draft PR through gh pr create
restores the original branch
prints a JSON receipt

Use --dry-run to print the planned action without writing or posting.

GitHub PR Comment

node .\tools\bifrost-bridge.mjs github-pr-comment `
  --repo-root E:\Projects\AetheriaLore `
  --identity nibu `
  --pr 12 `
  --content "This proposal needs a sharper leash before it becomes canon-shaped."

The command leaves a signed PR comment through gh and prints a JSON receipt. Repo Faces should use this when the argument belongs on the review artifact instead of dissolving into Discord scrollback.

Discord Post

node .\tools\bifrost-bridge.mjs discord-post `
  --channel-id 1501196543150264332 `
  --persona-name Nibu `
  --persona-avatar-url https://example.invalid/nibu.png `
  --content "Nibu drafted the article and put it in a PR: https://github.com/..."

The command posts through Discord's REST API using the configured bot token and prints a JSON receipt. When --persona-name is provided, Bifrost uses the shared webhook persona pattern so repo Faces can speak with their own display name and avatar instead of collapsing back into the base bot identity. Configure BIFROST_DISCORD_PERSONA_WEBHOOK_URL_<channelId> or DISCORD_PERSONA_WEBHOOK_URL when the bot should use an existing webhook; otherwise it creates and caches a Bifrost Persona Pipe webhook for the channel when Discord permissions allow it.

Heimdall Integration Target

The correct future credential path is:

Heimdall implements GitHub OAuth callback/runtime and managed credential custody.
Heimdall issues Bifrost-verifiable claims for account identity and bridge capabilities.
Bifrost records a bridge action request and checks the Heimdall-derived permission facts.
Bifrost executes or queues the action through the appropriate bridge executor.
Bifrost records the GitHub/Discord receipt and exposes it back to the requesting agent/runtime.

In that shape, Bifrost is the shiny bridge. Heimdall is the gatehouse with the keys. VoidBot is not hiding a bolt cutter in its coat.

4.2 KiB Raw Blame History