@openpalm/discord-portal 0.12.7

package/src/oc-event-hub.test.ts

@@ -0,0 +1,100 @@
+/**
+ * OcEventHub — one shared /event stream per principal, fanned out to turns.
+ *
+ * The bug this fixes: concurrent Discord threads from one user each opened a
+ * redundant principal-scoped /event stream and tripped the guardian's
+ * concurrent-stream cap (429 too_many_event_streams). The hub guarantees exactly
+ * ONE upstream stream per principal regardless of concurrent turns, and delivers
+ * every frame to every subscriber (each filters by its own sessionId).
+ *
+ * We stub OcClient.events with a controllable async generator so the test never
+ * needs a live guardian.
+ */
+import { describe, test, expect } from "bun:test";
+import { OcEventHub } from "./oc-event-hub.ts";
+
+/** A fake OcClient whose events() yields from a manually-fed queue per call. */
+function fakeClient() {
+  let opens = 0;
+  const feeders: Array<(frame: unknown) => void> = [];
+  const closers: Array<() => void> = [];
+  const client = {
+    events(_userId: string, signal: AbortSignal) {
+      opens++;
+      const queue: unknown[] = [];
+      let waiting: ((r: IteratorResult<unknown>) => void) | null = null;
+      let done = false;
+      const push = (frame: unknown) => {
+        if (waiting) { const w = waiting; waiting = null; w({ value: frame, done: false }); }
+        else queue.push(frame);
+      };
+      const finish = () => { done = true; if (waiting) { const w = waiting; waiting = null; w({ value: undefined, done: true }); } };
+      feeders.push(push);
+      closers.push(finish);
+      signal.addEventListener("abort", finish, { once: true });
+      return {
+        [Symbol.asyncIterator]() {
+          return {
+            next(): Promise<IteratorResult<unknown>> {
+              if (queue.length) return Promise.resolve({ value: queue.shift(), done: false });
+              if (done) return Promise.resolve({ value: undefined, done: true });
+              return new Promise((res) => { waiting = res; });
+            },
+          };
+        },
+      };
+    },
+  };
+  return { client, get opens() { return opens; }, feed: (i: number, f: unknown) => feeders[i]?.(f), closeUpstream: (i: number) => closers[i]?.() };
+}
+
+async function take(iter: AsyncIterable<unknown>, n: number): Promise<unknown[]> {
+  const out: unknown[] = [];
+  for await (const ev of iter) { out.push(ev); if (out.length >= n) break; }
+  return out;
+}
+
+describe("OcEventHub", () => {
+  test("two concurrent subscribers for one principal share ONE upstream stream", async () => {
+    const f = fakeClient();
+    const hub = new OcEventHub(f.client as never);
+
+    const subA = hub.subscribe("discord:u1");
+    const subB = hub.subscribe("discord:u1");
+    expect(f.opens).toBe(1);            // a single upstream open
+    expect(hub.openStreamCount).toBe(1);
+
+    // One upstream frame reaches BOTH subscribers (each filters by sessionId itself).
+    const gotA = take(subA, 1);
+    const gotB = take(subB, 1);
+    f.feed(0, { type: "message.part.delta", properties: { sessionID: "s1", delta: "hi" } });
+    expect(await gotA).toEqual([{ type: "message.part.delta", properties: { sessionID: "s1", delta: "hi" } }]);
+    expect(await gotB).toEqual([{ type: "message.part.delta", properties: { sessionID: "s1", delta: "hi" } }]);
+
+    subA.close();
+    subB.close();
+  });
+
+  test("separate principals get separate upstream streams", () => {
+    const f = fakeClient();
+    const hub = new OcEventHub(f.client as never);
+    hub.subscribe("discord:u1");
+    hub.subscribe("discord:u2");
+    expect(f.opens).toBe(2);
+    expect(hub.openStreamCount).toBe(2);
+  });
+
+  test("an upstream close/error ends all subscribers so their turns finalize", async () => {
+    const f = fakeClient();
+    const hub = new OcEventHub(f.client as never);
+    const sub = hub.subscribe("discord:u1");
+
+    // Drain to completion: when the upstream finishes, the subscriber iterator ends.
+    const drained = (async () => { for await (const _ of sub) { /* ignore */ } return "ended"; })();
+    f.closeUpstream(0);
+    expect(await drained).toBe("ended");
+    // Stream is forgotten → a new subscribe reopens a fresh upstream.
+    hub.subscribe("discord:u1");
+    expect(f.opens).toBe(2);
+  });
+});

package/src/oc-event-hub.ts

@@ -0,0 +1,161 @@
+/**
+ * Per-process shared OpenCode /event subscription (fixes guardian 429
+ * `too_many_event_streams`).
+ *
+ * The guardian's /event stream is PRINCIPAL-scoped: a single subscription already
+ * carries every event for every session the principal owns (ownership-filtered
+ * fan-out). The guardian therefore caps concurrent /event streams per principal
+ * at 1 (oc-bounds.ts) — a second open is a leaked/duplicated stream.
+ *
+ * But a Discord user can run several threads at once (the ConversationQueue
+ * serializes turns PER sessionKey, so different threads stream concurrently). If
+ * each turn opened its OWN /event stream, the 2nd concurrent thread would 429.
+ *
+ * This hub opens exactly ONE upstream /event stream per principal (userId) and
+ * BROADCASTS every frame to all active per-turn subscribers, which each already
+ * filter by their own sessionId (extractTextDelta/isTurnEnd/... are sessionID-
+ * scoped). Refcounted: the upstream stays open while ≥1 turn is subscribed and
+ * idle-closes a short grace after the last unsubscribes (absorbing between-turn
+ * gaps without churning opens). If the upstream errors/closes, all subscribers
+ * are ended so their turns finalize, and the next subscribe reopens.
+ */
+import { OcClient } from './runtime.ts';
+
+/** Grace period to keep the upstream open after the last turn unsubscribes, so
+ * back-to-back turns in a thread don't churn open/close (and re-pay the 429
+ * reconnect budget). Short — just bridges the gap between turns. */
+const IDLE_CLOSE_GRACE_MS = Number(Bun.env.DISCORD_EVENT_HUB_IDLE_MS) || 30_000;
+
+/** A single turn's view of the shared stream: a push-driven async iterator. */
+class Subscriber implements AsyncIterable<unknown> {
+  private queue: unknown[] = [];
+  private waiting: ((r: IteratorResult<unknown>) => void) | null = null;
+  private done = false;
+
+  push(frame: unknown): void {
+    if (this.done) return;
+    if (this.waiting) {
+      const resolve = this.waiting;
+      this.waiting = null;
+      resolve({ value: frame, done: false });
+    } else {
+      this.queue.push(frame);
+    }
+  }
+
+  end(): void {
+    if (this.done) return;
+    this.done = true;
+    if (this.waiting) {
+      const resolve = this.waiting;
+      this.waiting = null;
+      resolve({ value: undefined, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return {
+      next: () => {
+        if (this.queue.length) return Promise.resolve({ value: this.queue.shift(), done: false });
+        if (this.done) return Promise.resolve({ value: undefined, done: true });
+        return new Promise<IteratorResult<unknown>>((resolve) => {
+          this.waiting = resolve;
+        });
+      },
+      return: () => {
+        this.end();
+        return Promise.resolve({ value: undefined, done: true });
+      },
+    };
+  }
+}
+
+/** The single upstream /event stream for one principal, fanned out to turns. */
+class SharedStream {
+  readonly subscribers = new Set<Subscriber>();
+  private readonly ac = new AbortController();
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly client: OcClient,
+    private readonly userId: string,
+    private readonly onClosed: () => void,
+  ) {}
+
+  start(): void {
+    void this.pump();
+  }
+
+  private async pump(): Promise<void> {
+    try {
+      for await (const ev of this.client.events(this.userId, this.ac.signal)) {
+        for (const sub of this.subscribers) sub.push(ev);
+      }
+    } catch {
+      // aborted (idle close) or upstream error — fall through to teardown
+    } finally {
+      for (const sub of this.subscribers) sub.end();
+      this.subscribers.clear();
+      this.onClosed();
+    }
+  }
+
+  add(sub: Subscriber): void {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    this.subscribers.add(sub);
+  }
+
+  remove(sub: Subscriber): void {
+    if (!this.subscribers.delete(sub)) return;
+    sub.end();
+    if (this.subscribers.size === 0 && !this.idleTimer) {
+      this.idleTimer = setTimeout(() => this.ac.abort(), IDLE_CLOSE_GRACE_MS);
+      this.idleTimer.unref?.();
+    }
+  }
+}
+
+/** A turn's subscription handle: iterate it for frames, close() when done. */
+export interface EventSubscription extends AsyncIterable<unknown> {
+  close(): void;
+}
+
+/** Opens at most one upstream /event stream per principal and fans it out. */
+export class OcEventHub {
+  private readonly streams = new Map<string, SharedStream>();
+
+  constructor(private readonly client: OcClient) {}
+
+  /**
+   * Subscribe a turn to its principal's shared /event stream. Every frame is
+   * delivered; the caller filters by sessionId (as the renderers already do).
+   * MUST call close() when the turn ends (the render loop's finally does).
+   */
+  subscribe(userId: string): EventSubscription {
+    let shared = this.streams.get(userId);
+    if (!shared) {
+      shared = new SharedStream(this.client, userId, () => {
+        // Only forget this stream if it's still the current one (a fresh
+        // subscribe during teardown may have already replaced it).
+        if (this.streams.get(userId) === shared) this.streams.delete(userId);
+      });
+      this.streams.set(userId, shared);
+      shared.start();
+    }
+    const sub = new Subscriber();
+    shared.add(sub);
+    const owner = shared;
+    return {
+      [Symbol.asyncIterator]: () => sub[Symbol.asyncIterator](),
+      close: () => owner.remove(sub),
+    };
+  }
+
+  /** Number of open upstream streams (for tests / introspection). */
+  get openStreamCount(): number {
+    return this.streams.size;
+  }
+}

package/src/oc-events.ts

@@ -0,0 +1,157 @@
+export interface RawEvent {
+  type: string;
+  properties?: Record<string, unknown>;
+}
+
+export function asRaw(ev: unknown): RawEvent {
+  const e = ev as RawEvent;
+  return {
+    type: typeof e?.type === 'string' ? e.type : '',
+    properties: (e?.properties ?? {}) as Record<string, unknown>,
+  };
+}
+
+function propStr(props: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = props?.[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function partSnapshotType(e: RawEvent): { partID: string; type: string } | null {
+  if (e.type !== 'message.part.updated') return null;
+  const part = e.properties?.part as { id?: unknown; type?: unknown } | undefined;
+  if (part && typeof part.id === 'string' && typeof part.type === 'string') {
+    return { partID: part.id, type: part.type };
+  }
+  return null;
+}
+
+export function extractTextDelta(e: RawEvent, sessionId: string, reasoningPartIds?: ReadonlySet<string>): string | null {
+  const props = e.properties ?? {};
+  if (propStr(props, 'sessionID') !== sessionId) return null;
+
+  if (e.type === 'session.next.text.delta') {
+    return propStr(props, 'delta') ?? propStr(props, 'text') ?? null;
+  }
+  if (e.type === 'message.part.delta') {
+    if (propStr(props, 'field') && propStr(props, 'field') !== 'text') return null;
+    const partID = propStr(props, 'partID');
+    if (partID && reasoningPartIds?.has(partID)) return null;
+    return propStr(props, 'delta') ?? null;
+  }
+  return null;
+}
+
+export const TURN_IDLE_STATUSES: ReadonlySet<string> = new Set(['idle']);
+
+export function statusName(status: unknown): string | undefined {
+  if (typeof status === 'string') return status;
+  if (status && typeof status === 'object' && typeof (status as { type?: unknown }).type === 'string') {
+    return (status as { type: string }).type;
+  }
+  return undefined;
+}
+
+export function isTurnEnd(e: RawEvent, sessionId: string): boolean {
+  if (propStr(e.properties, 'sessionID') !== sessionId) return false;
+  if (e.type === 'session.idle') return true;
+  if (e.type === 'session.status') {
+    const name = statusName(e.properties?.status);
+    return name !== undefined && TURN_IDLE_STATUSES.has(name);
+  }
+  return false;
+}
+
+export interface ToolUpdate {
+  callID: string;
+  tool: string;
+  status: string;
+  title?: string;
+  error?: string;
+}
+
+export function extractToolUpdate(e: RawEvent, sessionId: string): ToolUpdate | null {
+  if (propStr(e.properties, 'sessionID') !== sessionId) return null;
+  const part = (e.properties?.part ?? e.properties?.tool) as Record<string, unknown> | undefined;
+  if (e.type === 'message.part.updated' && part && (part.type === 'tool' || part.state)) {
+    const state = (part.state ?? {}) as Record<string, unknown>;
+    return {
+      callID: String(part.callID ?? part.id ?? ''),
+      tool: String(part.tool ?? 'tool'),
+      status: String(state.status ?? 'running'),
+      title: typeof state.title === 'string' ? state.title : undefined,
+      error: typeof state.error === 'string' ? state.error : undefined,
+    };
+  }
+  if (e.type.startsWith('session.next.tool.')) {
+    return {
+      callID: propStr(e.properties, 'callID') ?? '',
+      tool: propStr(e.properties, 'tool') ?? 'tool',
+      status: e.type === 'session.next.tool.called' ? 'running' : (propStr(e.properties, 'status') ?? 'running'),
+      title: propStr(e.properties, 'title'),
+    };
+  }
+  return null;
+}
+
+export interface PermissionAsk {
+  requestID: string;
+  permission: string;
+  patterns: string[];
+}
+
+export function extractPermissionAsk(e: RawEvent, sessionId: string): PermissionAsk | null {
+  if (e.type !== 'permission.asked') return null;
+  if (propStr(e.properties, 'sessionID') !== sessionId) return null;
+  const id = propStr(e.properties, 'id');
+  if (!id) return null;
+  const patterns = Array.isArray(e.properties?.patterns)
+    ? (e.properties.patterns as unknown[]).filter((pattern): pattern is string => typeof pattern === 'string')
+    : [];
+  return { requestID: id, permission: propStr(e.properties, 'permission') ?? 'tool', patterns };
+}
+
+export function isSessionError(e: RawEvent, sessionId: string): boolean {
+  return e.type === 'session.error' && propStr(e.properties, 'sessionID') === sessionId;
+}
+
+export interface QuestionOption {
+  label: string;
+  description: string;
+}
+
+export interface QuestionInfo {
+  question: string;
+  header: string;
+  options: QuestionOption[];
+}
+
+export interface QuestionAsk {
+  requestID: string;
+  questions: QuestionInfo[];
+}
+
+export function extractQuestionAsk(e: RawEvent, sessionId: string): QuestionAsk | null {
+  if (e.type !== 'question.asked') return null;
+  if (propStr(e.properties, 'sessionID') !== sessionId) return null;
+  const id = propStr(e.properties, 'id');
+  if (!id) return null;
+  const rawQuestions = Array.isArray(e.properties?.questions) ? (e.properties.questions as unknown[]) : [];
+  const questions: QuestionInfo[] = [];
+  for (const rawQuestion of rawQuestions) {
+    const questionData = rawQuestion as { question?: unknown; header?: unknown; options?: unknown };
+    const question = typeof questionData.question === 'string' ? questionData.question : '';
+    const header = typeof questionData.header === 'string' ? questionData.header : '';
+    const options: QuestionOption[] = Array.isArray(questionData.options)
+      ? (questionData.options as unknown[])
+          .map((option) => option as { label?: unknown; description?: unknown })
+          .filter((option) => typeof option.label === 'string')
+          .map((option) => ({
+            label: option.label as string,
+            description: typeof option.description === 'string' ? option.description : '',
+          }))
+      : [];
+    questions.push({ question, header, options });
+  }
+  if (questions.length === 0) return null;
+  return { requestID: id, questions };
+}

package/src/opencode.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Regression test for the 0.12.0 "Discord portal stopped working" bug.
+ *
+ * The @opencode-ai/sdk client (1.17.x) resolves every session.* call to a
+ * { data, error } envelope. The adapter used to read the session object off the
+ * envelope directly, so `createSession().id` was `undefined`; the subsequent
+ * `prompt({ path: { id: undefined } })` left the path template un-substituted and
+ * sent the LITERAL `/session/{id}/message`. The guardian denied it with
+ * `no_route` (403), so every Discord message silently failed.
+ *
+ * This test drives the REAL SDK through a fake transport (the `fetch` the adapter
+ * accepts) and asserts the prompt request carries the actual session id — i.e.
+ * the path is `/session/<real-id>/message`, never the literal `{id}` / `%7Bid%7D`.
+ */
+import { describe, it, expect } from 'bun:test';
+import { OcClient } from './opencode.js';
+
+const REAL_SESSION_ID = 'ses_real_abc123';
+
+/** A fake transport standing in for guardian → OpenCode. Records every request
+ *  URL and answers session.create / session.prompt with realistic envelopes. */
+function makeFakeTransport() {
+  const urls: string[] = [];
+  const fetchFn = (async (input: Request | string | URL): Promise<Response> => {
+    const url = input instanceof Request ? input.url : String(input);
+    urls.push(url);
+    if (/\/session$/.test(new URL(url).pathname) || /\/session$/.test(url)) {
+      // POST /session → the created session lives in the JSON body.
+      return new Response(JSON.stringify({ id: REAL_SESSION_ID, title: 'chat' }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+    // POST /session/<id>/message → accept and echo an empty assistant message.
+    return new Response(JSON.stringify({ info: {}, parts: [] }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as unknown as typeof fetch;
+  return { urls, fetchFn };
+}
+
+describe('OcClient (discord) — SDK envelope handling', () => {
+  it('createSession returns the real session id from the { data } envelope', async () => {
+    const { fetchFn } = makeFakeTransport();
+    const client = new OcClient({ principalId: 'discord', secret: 's', baseUrl: 'http://guardian:8080/oc', fetch: fetchFn });
+
+    const session = await client.createSession('discord:123');
+    // Pre-fix this was `undefined` (read off the envelope instead of `.data`).
+    expect(session.id).toBe(REAL_SESSION_ID);
+  });
+
+  it('prompt substitutes the session id into the path (never the literal {id})', async () => {
+    const { urls, fetchFn } = makeFakeTransport();
+    const client = new OcClient({ principalId: 'discord', secret: 's', baseUrl: 'http://guardian:8080/oc', fetch: fetchFn });
+
+    const session = await client.createSession('discord:123');
+    await client.prompt('discord:123', session.id, 'hello');
+
+    const promptUrl = urls.find((u) => u.includes('/message'));
+    expect(promptUrl, 'a /message request must have been made').toBeDefined();
+    // The exact prod failure: the un-substituted template reaching the guardian.
+    expect(promptUrl).not.toContain('%7Bid%7D');
+    expect(promptUrl).not.toContain('{id}');
+    expect(promptUrl).toContain(`/session/${REAL_SESSION_ID}/message`);
+  });
+
+  it('createSession throws when the SDK returns an error envelope', async () => {
+    const fetchFn = (async () =>
+      new Response(JSON.stringify({ message: 'denied' }), {
+        status: 403,
+        headers: { 'content-type': 'application/json' },
+      })) as unknown as typeof fetch;
+    const client = new OcClient({ principalId: 'discord', secret: 's', baseUrl: 'http://guardian:8080/oc', fetch: fetchFn });
+
+    await expect(client.createSession('discord:123')).rejects.toThrow(/createSession failed/);
+  });
+});

package/src/opencode.ts

@@ -0,0 +1,130 @@
+import type { Event } from '@opencode-ai/sdk';
+import { createOpencodeClient } from '@opencode-ai/sdk';
+
+const DEFAULT_OPENCODE_BASE_URL = 'http://guardian:8080/oc';
+const H_USER = 'x-openpalm-user';
+const H_SESSION_KEY = 'x-openpalm-session-key';
+
+export interface OcClientOptions {
+  principalId: string;
+  secret: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export interface OcSession {
+  id: string;
+  title?: string;
+}
+
+export class OcClient {
+  private readonly principalId: string;
+  private readonly secret: string;
+  private readonly base: string;
+  private readonly fetchFn: typeof fetch;
+  private readonly client: ReturnType<typeof createOpencodeClient>;
+
+  constructor(opts: OcClientOptions) {
+    this.principalId = opts.principalId;
+    this.secret = opts.secret;
+    this.base = opts.baseUrl ?? Bun.env.OPENCODE_BASE_URL ?? DEFAULT_OPENCODE_BASE_URL;
+    this.fetchFn = opts.fetch ?? globalThis.fetch;
+    this.client = createOpencodeClient({ baseUrl: this.base, fetch: this.fetchFn });
+  }
+
+  private headers(userId: string, extra?: Record<string, string>): Record<string, string> {
+    const credentials = Buffer.from(`${this.principalId}:${this.secret}`, 'utf-8').toString('base64');
+    return {
+      [H_USER]: userId,
+      authorization: `Basic ${credentials}`,
+      ...(extra ?? {}),
+    };
+  }
+
+  async createSession(userId: string, sessionKey?: string): Promise<OcSession> {
+    // The @opencode-ai/sdk client resolves to a { data, error } envelope
+    // (ThrowOnError defaults to false). The session lives in `.data` — reading
+    // the envelope directly yields an undefined id, which then renders the
+    // prompt path as the literal `/session/{id}/message`, and the guardian
+    // denies it with no_route. Always pull the session out of `.data`.
+    const { data, error } = await this.client.session.create({
+      body: {},
+      headers: this.headers(userId, sessionKey ? { [H_SESSION_KEY]: sessionKey } : undefined),
+    });
+    if (error || !data?.id) {
+      throw new Error(`createSession failed: ${error ? JSON.stringify(error) : 'no session id in response'}`);
+    }
+    return data as OcSession;
+  }
+
+  async prompt(userId: string, sessionId: string, text: string): Promise<void> {
+    // ThrowOnError is false, so a denied/failed prompt surfaces as `.error`
+    // rather than a throw — check it so failures aren't silently swallowed.
+    const { error } = await this.client.session.prompt({
+      path: { id: sessionId },
+      body: { parts: [{ type: 'text', text }] },
+      headers: this.headers(userId),
+    });
+    if (error) throw new Error(`prompt failed: ${JSON.stringify(error)}`);
+  }
+
+  async replyPermission(userId: string, requestID: string, reply: 'once' | 'always' | 'reject', message?: string): Promise<boolean> {
+    const body: Record<string, unknown> = { reply };
+    if (message) body.message = message;
+    const response = await this.fetchFn(`${this.base}/permission/${requestID}/reply`, {
+      method: 'POST',
+      headers: {
+        ...this.headers(userId),
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) throw new Error(`replyPermission failed: ${response.status}`);
+    return true;
+  }
+
+  async replyQuestion(userId: string, requestID: string, answers: string[][]): Promise<boolean> {
+    const response = await this.fetchFn(`${this.base}/question/${requestID}/reply`, {
+      method: 'POST',
+      headers: {
+        ...this.headers(userId),
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ answers }),
+    });
+    if (!response.ok) throw new Error(`replyQuestion failed: ${response.status}`);
+    return true;
+  }
+
+  async rejectQuestion(userId: string, requestID: string): Promise<void> {
+    const response = await this.fetchFn(`${this.base}/question/${requestID}/reject`, {
+      method: 'POST',
+      headers: {
+        ...this.headers(userId),
+        'content-type': 'application/json',
+      },
+      body: '{}',
+    });
+    if (!response.ok) throw new Error(`rejectQuestion failed: ${response.status}`);
+  }
+
+  async abort(userId: string, sessionId: string): Promise<void> {
+    await this.client.session.abort({
+      path: { id: sessionId },
+      headers: this.headers(userId),
+    });
+  }
+
+  async *events(userId: string, signal: AbortSignal): AsyncGenerator<Event> {
+    const subscription = await this.client.event.subscribe({
+      headers: {
+        ...this.headers(userId),
+        accept: 'text/event-stream',
+      },
+      signal,
+    });
+    for await (const event of subscription.stream as AsyncIterable<Event>) {
+      yield event;
+    }
+  }
+}

package/src/permissions.ts

@@ -0,0 +1,55 @@
+import { createLogger, parseIdList } from './runtime.ts';
+import type { PermissionResult } from './types.ts';
+import type { PermissionConfig, UserInfo } from "./types.ts";
+
+export { parseIdList };
+
+const log = createLogger("channel-discord");
+
+export function loadPermissionConfig(env: Record<string, string | undefined> = Bun.env): PermissionConfig {
+  const config: PermissionConfig = {
+    allowedGuilds: parseIdList(env.DISCORD_ALLOWED_GUILDS),
+    allowedRoles: parseIdList(env.DISCORD_ALLOWED_ROLES),
+    allowedUsers: parseIdList(env.DISCORD_ALLOWED_USERS),
+    blockedUsers: parseIdList(env.DISCORD_BLOCKED_USERS),
+  };
+
+  log.info("permissions_loaded", {
+    allowedGuilds: config.allowedGuilds.size || "unrestricted",
+    allowedRoles: config.allowedRoles.size || "unrestricted",
+    allowedUsers: config.allowedUsers.size || "unrestricted",
+    blockedUsers: config.blockedUsers.size || "none",
+  });
+
+  return config;
+}
+
+export function checkPermissions(config: PermissionConfig, user: UserInfo): PermissionResult {
+  const { userId, guildId, roles, username } = user;
+
+  if (userId && config.blockedUsers.has(userId)) {
+    log.warn("permission_denied", { userId, username, reason: "blocked_user" });
+    return { allowed: false, reason: "user_blocked" };
+  }
+
+  if (config.allowedUsers.size > 0) {
+    if (!userId || !config.allowedUsers.has(userId)) {
+      return { allowed: false, reason: "user_not_allowed" };
+    }
+  }
+
+  if (config.allowedGuilds.size > 0) {
+    if (!guildId || !config.allowedGuilds.has(guildId)) {
+      return { allowed: false, reason: "guild_not_allowed" };
+    }
+  }
+
+  if (config.allowedRoles.size > 0) {
+    const hasMatchingRole = roles.some((r) => config.allowedRoles.has(r));
+    if (!hasMatchingRole) {
+      return { allowed: false, reason: "role_not_allowed" };
+    }
+  }
+
+  return { allowed: true };
+}