Standalone OpenCode-compatible portal packages (coordinate with guardian state refactor #433)

[itlackey]

Goal

Publish the portal adapters (@openpalm/discord-portal, @openpalm/slack-portal) as standalone npm packages that work against any OpenCode server, not just the OpenPalm guardian. This both serves a "power user / your own OpenCode server" use case and completes the #434 / #432 thesis that portal adapters are standard OpenCode-SDK clients (the guardian's value is validation, not transport).

Spun out of the 0.12.0 portals-rename + build/packaging review. Code is already ~90% there: zero @openpalm/* workspace deps (only @opencode-ai/sdk + discord.js/@slack/bolt), env-overridable OPENCODE_BASE_URL, no template rendering.

The architectural crux — and why this coordinates with the guardian state refactor (#433)

The guardian has two distinct state concerns today; the portals only need a client-side mirror of the first:

1. Session reuse — forward.ts:resolveSessionTarget maps ${portalId}:${sessionKey} → an existing OpenCode session (the buffered session cache, GUARDIAN_SESSION_TTL_MS). This is what makes multi-turn work. Portals currently rely on the guardian honoring the x-openpalm-session-key header to get this; a plain OpenCode server ignores the header and session.create() makes a fresh session every turn → multi-turn breaks.
2. Ownership / authz — ownership.ts maps sessionId → principal (+ requestID → principal for permissions) for per-principal isolation. Pure guardian concern; no standalone equivalent.

Proposed direction: move session-reuse client-side into the portal (a Map<threadKey, sessionId>, optionally locally persisted). Then:

• Portals work against ANY OpenCode endpoint (standalone) AND behind the guardian.
• x-openpalm-session-key becomes an optional guardian hint (for the guardian's durable, cross-restart, cross-principal reuse) rather than the mechanism multi-turn depends on — a cleaner "standard OpenCode client" contract.
• This narrows Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433 Phase 2: with reuse client-side, the guardian's durable state is scoped to ownership/authz + permission ownership (and cross-restart session continuity as an optimization), not the session-reuse cache. Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433 Phase 2 and this issue should be designed together so we don't persist the same concept in two places.

Coordination checklist

• Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433 (guardian state store, Phase 2) — decide the split: client-side session reuse (portal) vs durable ownership (guardian). Scope Guardian state store (bun:sqlite): ingress/client registry + optional restart persistence #433 Phase 2 to ownership/permission persistence accordingly; document x-openpalm-session-key as an optional optimization.
• Guardian Gateway: A2A server (in-process, optional) #487 (A2A server) — the A2A contextId → sessionId mapping is the same shape as portal session reuse; align the contract so all three front ends (portal/OpenCode-proxy/A2A) treat session continuity consistently.
• Channel adapters become official-OpenCode-SDK clients (X-to-OpenCode packages); retire channels-sdk transport #434 / Guardian Gateway: one moderation front door speaking OpenCode-proxy, MCP + A2A (in-process) #432 (adapters as standard OpenCode-SDK clients) — this issue is the concrete completion of that thesis for the two first-party portals.

Standalone packaging gaps (from the investigation)

• Session reuse client-side (the one architectural gap above) — ~20 lines/portal, or in a shared kit.
• Auth UX — readRequiredSecret() accepting a direct env var (e.g. OPENCODE_PASSWORD, DISCORD_BOT_TOKEN) with _FILE fallback (keeps Compose-secrets working). Against plain OpenCode the single Basic password is the auth; PRINCIPAL_ID becomes a free-form username.
• Branding — Slack hardcodes "Ask OpenPalm" / "OpenPalm on Slack" (modal titles, Home tab) → make configurable (SLACK_BOT_NAME).
• CLI entrypoints — bin/ wrappers + bin field (the container entrypoint instantiates the class today).
• Extract @openpalm/portal-kit (M, follow-on) — runtime.ts / oc-events.ts / OcClient / session-map are byte-identical across discord+slack; extract to one shared package (also the home for the client-side session-reuse logic).
• Publish — flip "private": true → false on both; add publish-npm-package steps; reconcile release-package-groups.json (units.portals). Decide the Bun-runtime requirement (engines.bun) — it narrows the Node audience; consider a Node-compatible build target.
• Docs — rewrite both portals/*/README.md for a standalone audience.

Security framing (must be explicit in docs)

Pointing a portal straight at OpenCode loses the guardian's per-principal isolation, rate limiting, and content moderation — every user in a server shares one session namespace. Frame as: "Runs best behind the OpenPalm guardian (or another auth/rate-limiting reverse proxy). Standalone is for personal / small-trusted-team use against your own OpenCode server."

Effort

First shippable increment: S (~half a day) — session-reuse + auth UX + branding + bin/ + private:false + publish steps + READMEs. The @openpalm/portal-kit extraction is a separate M. Recommend doing the session-reuse / state split with #433 first so the guardian and portal don't diverge.

Related: #433, #487, #434, #432, #436.

[itlackey]

Verification pass on synced main after PR #559 merge (c1eadbd30e107f76b71aa933b71edcaedaadba46).

Current state:

• Portal packages exist as @openpalm/discord-portal and @openpalm/slack-portal under portals/.
• They are not yet standalone in the sense of this issue: both still depend on the workspace @openpalm/portal-sdk, do not expose bin entrypoints, and still assume OpenPalm/Guardian-oriented runtime wiring.
• Portal session continuity still appears guardian-centered through x-openpalm-session-key/Guardian ownership semantics rather than a standalone client-side session map that works against any raw OpenCode server.

Remaining work to complete this issue:

• Move per-thread/per-channel session reuse into the portal client side so multi-turn conversations work against a plain OpenCode server.
• Keep x-openpalm-session-key only as an optional Guardian hint/optimization, not the required session-continuity mechanism.
• Add direct env secret support with _FILE fallback for standalone use: OpenCode password/token, Discord bot token, Slack tokens.
• Make branding configurable, especially Slack labels such as bot/app names.
• Add bin wrappers and publishable package metadata; decide whether Bun-only runtime is acceptable or whether a Node-compatible build is required.
• Either publish/extract @openpalm/portal-sdk as the standalone shared kit or remove private workspace coupling from the published portal packages.
• Document the security tradeoff: standalone mode lacks Guardian isolation, rate limiting, and moderation unless placed behind another protective proxy.

Suggested verification gate:

• Install each portal package outside the monorepo and run it against a raw OpenCode server.
• Prove multi-turn session reuse works without Guardian.
• Run the same portal behind Guardian and prove isolation/moderation/rate-limit behavior still works.
• Release workflow publishes the packages or explicitly marks them out of the release unit.