@openpalm/discord-portal 0.12.7

package/src/runtime.ts

@@ -0,0 +1,211 @@
+import { readFileSync } from 'node:fs';
+
+export { OcClient, type OcClientOptions, type OcSession } from './opencode.ts';
+export {
+  asRaw,
+  extractPermissionAsk,
+  extractQuestionAsk,
+  extractTextDelta,
+  extractToolUpdate,
+  isSessionError,
+  isTurnEnd,
+  partSnapshotType,
+  statusName,
+  TURN_IDLE_STATUSES,
+  type PermissionAsk,
+  type QuestionAsk,
+  type QuestionInfo,
+  type QuestionOption,
+  type RawEvent,
+  type ToolUpdate,
+} from './oc-events.ts';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export function createLogger(service: string) {
+  function log(level: LogLevel, msg: string, extra?: Record<string, unknown>): void {
+    const entry = { ts: new Date().toISOString(), level, service, msg, ...(extra ? { extra } : {}) };
+    (level === 'error' || level === 'warn' ? console.error : console.log)(JSON.stringify(entry));
+  }
+
+  return {
+    info: (msg: string, extra?: Record<string, unknown>) => log('info', msg, extra),
+    warn: (msg: string, extra?: Record<string, unknown>) => log('warn', msg, extra),
+    error: (msg: string, extra?: Record<string, unknown>) => log('error', msg, extra),
+    debug: (msg: string, extra?: Record<string, unknown>) => log('debug', msg, extra),
+  };
+}
+
+export class SecretFileError extends Error {
+  constructor(public readonly envKey: string, reason: string) {
+    super(`${envKey}: ${reason}`);
+    this.name = 'SecretFileError';
+  }
+}
+
+function stripTrailingNewline(value: string): string {
+  return value.replace(/[\r\n]+$/, '');
+}
+
+export function readRequiredSecretFile(envKey: string, env: Record<string, string | undefined> = Bun.env): string {
+  const path = env[envKey]?.trim();
+  if (!path) {
+    throw new SecretFileError(envKey, 'secret file env var is not set');
+  }
+
+  let value: string;
+  try {
+    value = stripTrailingNewline(readFileSync(path, 'utf8'));
+  } catch {
+    throw new SecretFileError(envKey, 'secret file is unreadable');
+  }
+
+  if (!value) {
+    throw new SecretFileError(envKey, 'secret file is empty');
+  }
+
+  return value;
+}
+
+export function parseIdList(raw: string | undefined): Set<string> {
+  if (!raw) return new Set();
+  return new Set(
+    raw
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+}
+
+export function splitMessage(content: string, maxLength: number): string[] {
+  if (!content) return [];
+  if (content.length <= maxLength) return [content];
+
+  const chunks: string[] = [];
+  let remaining = content;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let splitIndex = maxLength;
+    const beforeSplit = remaining.slice(0, splitIndex);
+    const codeBlockStarts = (beforeSplit.match(/```/g) || []).length;
+    const inCodeBlock = codeBlockStarts % 2 === 1;
+
+    if (inCodeBlock) {
+      const newlineIndex = remaining.lastIndexOf('\n', splitIndex);
+      if (newlineIndex > maxLength / 2) splitIndex = newlineIndex;
+    } else {
+      const doubleNewline = remaining.lastIndexOf('\n\n', splitIndex);
+      const singleNewline = remaining.lastIndexOf('\n', splitIndex);
+      if (doubleNewline > maxLength / 2) splitIndex = doubleNewline + 2;
+      else if (singleNewline > maxLength / 2) splitIndex = singleNewline + 1;
+    }
+
+    let chunk = remaining.slice(0, splitIndex);
+    remaining = remaining.slice(splitIndex);
+
+    const chunkCodeBlocks = (chunk.match(/```/g) || []).length;
+    if (chunkCodeBlocks % 2 === 1) {
+      chunk += '\n```';
+      const match = chunk.match(/```(\w+)?/);
+      const lang = match?.[1] || '';
+      remaining = '```' + lang + '\n' + remaining;
+    }
+
+    chunks.push(chunk.trim());
+  }
+
+  return chunks.filter((c) => c.length > 0);
+}
+
+type SessionTask = {
+  run: () => Promise<void>;
+  onQueued?: () => Promise<void>;
+};
+
+type SessionState = {
+  processing: boolean;
+  queue: SessionTask[];
+};
+
+export class ConversationQueue {
+  private states = new Map<string, SessionState>();
+
+  isProcessing(sessionKey: string): boolean {
+    return this.states.get(sessionKey)?.processing ?? false;
+  }
+
+  queuedCount(sessionKey: string): number {
+    return this.states.get(sessionKey)?.queue.length ?? 0;
+  }
+
+  clear(sessionKey: string): number {
+    const state = this.states.get(sessionKey);
+    if (!state) return 0;
+
+    const dropped = state.queue.length;
+    state.queue.length = 0;
+
+    if (!state.processing) {
+      this.states.delete(sessionKey);
+    }
+
+    return dropped;
+  }
+
+  async runOrQueue(sessionKey: string, task: SessionTask): Promise<'started' | 'queued'> {
+    const state = this.states.get(sessionKey) ?? { processing: false, queue: [] };
+    this.states.set(sessionKey, state);
+
+    if (state.processing) {
+      state.queue.push(task);
+      try {
+        await task.onQueued?.();
+      } catch {
+      }
+      return 'queued';
+    }
+
+    state.processing = true;
+    try {
+      await task.run();
+    } finally {
+      state.processing = false;
+      if (state.queue.length > 0) {
+        void this.drain(sessionKey);
+      } else {
+        this.states.delete(sessionKey);
+      }
+    }
+
+    return 'started';
+  }
+
+  private async drain(sessionKey: string): Promise<void> {
+    const state = this.states.get(sessionKey);
+    if (!state || state.processing) return;
+
+    const next = state.queue.shift();
+    if (!next) {
+      this.states.delete(sessionKey);
+      return;
+    }
+
+    state.processing = true;
+    try {
+      await next.run();
+    } catch {
+    } finally {
+      state.processing = false;
+      if (state.queue.length > 0) {
+        void this.drain(sessionKey);
+      } else {
+        this.states.delete(sessionKey);
+      }
+    }
+  }
+}

package/src/session.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "bun:test";
+import { ConversationQueue } from './runtime.ts';
+
+function deferred(): { promise: Promise<void>; resolve: () => void } {
+  let resolve = () => {};
+  const promise = new Promise<void>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return { promise, resolve };
+}
+
+describe("ConversationQueue", () => {
+  it("runs queued work sequentially", async () => {
+    const queue = new ConversationQueue();
+    const blocker = deferred();
+    const events: string[] = [];
+
+    const first = queue.runOrQueue("session-1", {
+      run: async () => {
+        events.push("first:start");
+        await blocker.promise;
+        events.push("first:end");
+      },
+    });
+
+    const second = queue.runOrQueue("session-1", {
+      onQueued: async () => {
+        events.push("second:queued");
+      },
+      run: async () => {
+        events.push("second:run");
+      },
+    });
+
+    expect(await second).toBe("queued");
+    expect(queue.queuedCount("session-1")).toBe(1);
+
+    blocker.resolve();
+    expect(await first).toBe("started");
+
+    await Bun.sleep(0);
+    expect(events).toEqual(["first:start", "second:queued", "first:end", "second:run"]);
+    expect(queue.isProcessing("session-1")).toBe(false);
+  });
+
+  it("drops queued work when cleared", async () => {
+    const queue = new ConversationQueue();
+    const blocker = deferred();
+    const events: string[] = [];
+
+    const first = queue.runOrQueue("session-1", {
+      run: async () => {
+        events.push("first:start");
+        await blocker.promise;
+        events.push("first:end");
+      },
+    });
+
+    await queue.runOrQueue("session-1", {
+      run: async () => {
+        events.push("second:run");
+      },
+    });
+
+    expect(queue.clear("session-1")).toBe(1);
+
+    blocker.resolve();
+    await first;
+    await Bun.sleep(0);
+
+    expect(events).toEqual(["first:start", "first:end"]);
+    expect(queue.queuedCount("session-1")).toBe(0);
+  });
+});

package/src/stream-render.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Discord stream renderer — PURE event-narrowing unit tests (design §4.1, §4.2).
+ *
+ * The Discord rendering side-effects (thread.send/edit, ActionRow clicks) need a
+ * live Discord gateway and are stated in needsLiveVerification. What IS unit-
+ * provable is the native-OpenCode-event correlation/narrowing logic, which is
+ * the security- and correctness-load-bearing part: a delta must be attributed to
+ * the right session AND messageID, a foreign session's frames must be ignored,
+ * permission.asked must surface the requestID, and turn-end must be detected.
+ */
+import { describe, test, expect } from "bun:test";
+import { _internal } from "./stream-render.ts";
+
+const { extractTextDelta, isTurnEnd, extractToolUpdate, extractPermissionAsk, toolEmoji, asRaw } = _internal;
+
+const SID = "ses_target";
+const MID = "^msgcorrelation";
+
+function ev(type: string, properties: Record<string, unknown>) {
+  return asRaw({ type, properties });
+}
+
+describe("extractTextDelta — sessionID-only correlation (§4.2, corrected)", () => {
+  test("message.part.delta for our session yields the delta", () => {
+    expect(extractTextDelta(ev("message.part.delta", { sessionID: SID, messageID: MID, delta: "hi" }), SID)).toBe("hi");
+  });
+
+  test("session.next.text.delta (preferred 1.15.13 family) yields the delta", () => {
+    expect(extractTextDelta(ev("session.next.text.delta", { sessionID: SID, messageID: MID, delta: "yo" }), SID)).toBe("yo");
+  });
+
+  test("delta for a DIFFERENT session is ignored", () => {
+    expect(extractTextDelta(ev("message.part.delta", { sessionID: "other", messageID: MID, delta: "x" }), SID)).toBeNull();
+  });
+
+  test("a SERVER-generated messageID (≠ client id) still renders — session is the key (live-verified)", () => {
+    expect(extractTextDelta(ev("message.part.delta", { sessionID: SID, messageID: "msg_server", delta: "x" }), SID)).toBe("x");
+  });
+
+  test("non-text field delta is ignored", () => {
+    expect(extractTextDelta(ev("message.part.delta", { sessionID: SID, messageID: MID, field: "reasoning", delta: "x" }), SID)).toBeNull();
+  });
+
+  test("a non-delta event yields null", () => {
+    expect(extractTextDelta(ev("session.status", { sessionID: SID, status: { type: "busy" } }), SID)).toBeNull();
+  });
+});
+
+describe("isTurnEnd — session.status idle, fallback session.idle (§1.1)", () => {
+  test("session.idle for our session ends the turn", () => {
+    expect(isTurnEnd(ev("session.idle", { sessionID: SID }), SID)).toBe(true);
+  });
+
+  test("session.status idle ends the turn", () => {
+    expect(isTurnEnd(ev("session.status", { sessionID: SID, status: "idle" }), SID)).toBe(true);
+  });
+
+  test("session.status busy does NOT end the turn", () => {
+    expect(isTurnEnd(ev("session.status", { sessionID: SID, status: "busy" }), SID)).toBe(false);
+  });
+
+  test("turn-end for a DIFFERENT session is ignored", () => {
+    expect(isTurnEnd(ev("session.idle", { sessionID: "other" }), SID)).toBe(false);
+  });
+});
+
+describe("extractToolUpdate — colored by state.status (§4.1)", () => {
+  test("message.part.updated tool part yields a tool update", () => {
+    const t = extractToolUpdate(
+      ev("message.part.updated", { sessionID: SID, part: { type: "tool", callID: "c1", tool: "bash", state: { status: "running", title: "echo hi" } } }),
+      SID,
+    );
+    expect(t).not.toBeNull();
+    expect(t!.callID).toBe("c1");
+    expect(t!.tool).toBe("bash");
+    expect(t!.status).toBe("running");
+    expect(t!.title).toBe("echo hi");
+  });
+
+  test("session.next.tool.called yields a running update", () => {
+    const t = extractToolUpdate(ev("session.next.tool.called", { sessionID: SID, callID: "c2", tool: "edit" }), SID);
+    expect(t).not.toBeNull();
+    expect(t!.callID).toBe("c2");
+    expect(t!.status).toBe("running");
+  });
+
+  test("a tool update for a foreign session is ignored", () => {
+    expect(extractToolUpdate(ev("message.part.updated", { sessionID: "other", part: { type: "tool", callID: "c", tool: "bash", state: { status: "running" } } }), SID)).toBeNull();
+  });
+
+  test("toolEmoji maps tool kind → a reaction emoji", () => {
+    expect(toolEmoji("akm_curate")).toBe("🔎");
+    expect(toolEmoji("akm_remember")).toBe("🧠");
+    expect(toolEmoji("bash")).toBe("🐚");
+    expect(toolEmoji("edit")).toBe("✏️");
+    expect(toolEmoji("something_unknown")).toBe("🔧");
+  });
+});
+
+describe("extractPermissionAsk — surfaces requestID for our session (§4.1)", () => {
+  test("permission.asked yields the requestID + permission + patterns", () => {
+    const ask = extractPermissionAsk(
+      ev("permission.asked", { sessionID: SID, id: "per_1", permission: "bash", patterns: ["echo *"], always: ["echo *"] }),
+      SID,
+    );
+    expect(ask).not.toBeNull();
+    expect(ask!.requestID).toBe("per_1");
+    expect(ask!.permission).toBe("bash");
+    expect(ask!.patterns).toEqual(["echo *"]);
+  });
+
+  test("permission.asked for a foreign session is ignored", () => {
+    expect(extractPermissionAsk(ev("permission.asked", { sessionID: "other", id: "per_2", permission: "bash" }), SID)).toBeNull();
+  });
+
+  test("a permission.asked missing an id yields null", () => {
+    expect(extractPermissionAsk(ev("permission.asked", { sessionID: SID, permission: "bash" }), SID)).toBeNull();
+  });
+});
+
+describe("DISCORD_SESSION_PREAMBLE — channel-level question-tool nudge", () => {
+  test("is a non-empty default that mentions the question tool (so the API channel never gets it — it lives here)", async () => {
+    const { DISCORD_SESSION_PREAMBLE } = await import("./stream-render.ts");
+    expect(DISCORD_SESSION_PREAMBLE.length).toBeGreaterThan(0);
+    expect(DISCORD_SESSION_PREAMBLE).toContain("question");
+  });
+});