@otto-assistant/bridge 0.4.92

package/src/message-preprocessing.ts

@@ -0,0 +1,455 @@
+// Message pre-processing pipeline for incoming Discord messages.
+// Extracts prompt text, voice transcription, file/text attachments, and
+// session context from a Discord Message before handing off to the runtime.
+//
+// This module exists so discord-bot.ts stays a thin event router and the
+// expensive async work (voice transcription, context fetch, attachment
+// download) runs inside the runtime's serialized preprocessChain —
+// preserving arrival order without a separate threadIngressQueue.
+
+import type { Message, ThreadChannel } from 'discord.js'
+import type { DiscordFileAttachment } from './message-formatting.js'
+import type { PreprocessResult } from './session-handler/thread-session-runtime.js'
+import type { AgentInfo, RepliedMessageContext } from './system-message.js'
+import {
+  resolveMentions,
+  getFileAttachments,
+  getTextAttachments,
+} from './message-formatting.js'
+import { processVoiceAttachment } from './voice-handler.js'
+import { isVoiceAttachment } from './voice-attachment.js'
+import { initializeOpencodeForDirectory } from './opencode.js'
+import { getCompactSessionContext, getLastSessionId } from './markdown.js'
+import { getThreadSession } from './database.js'
+import * as errore from 'errore'
+import { createLogger, LogPrefix } from './logger.js'
+import { notifyError } from './sentry.js'
+
+const logger = createLogger(LogPrefix.SESSION)
+const voiceLogger = createLogger(LogPrefix.VOICE)
+
+export const VOICE_MESSAGE_TRANSCRIPTION_PREFIX =
+  'Voice message transcription from Discord user:\n'
+
+/** Fetch available agents from OpenCode for voice transcription agent selection. */
+async function fetchAvailableAgents(
+  getClient: Awaited<ReturnType<typeof initializeOpencodeForDirectory>>,
+): Promise<AgentInfo[]> {
+  if (getClient instanceof Error) {
+    return []
+  }
+  const result = await errore.tryAsync(() => {
+    return getClient().app.agents({})
+  })
+  if (result instanceof Error) {
+    return []
+  }
+  return (result.data || [])
+    .filter((a) => {
+      return (a.mode === 'primary' || a.mode === 'all') && !a.hidden
+    })
+    .map((a) => {
+      return { name: a.name, description: a.description }
+    })
+}
+
+export type { PreprocessResult }
+
+// Matches punctuation + "queue" at the end of a message (case-insensitive).
+// Supports any common punctuation before "queue" (. ! ? , ; :) and an optional
+// trailing period: ". queue", "! queue", ". queue.", "!queue." etc.
+// When present the suffix is stripped and the message is routed through
+// kimaki's local queue (same as /queue command).
+const QUEUE_SUFFIX_RE = /[.!?,;:]\s*queue\.?\s*$/i
+const REPLIED_MESSAGE_TEXT_LIMIT = 1_000
+
+function extractQueueSuffix(prompt: string): { prompt: string; forceQueue: boolean } {
+  if (!QUEUE_SUFFIX_RE.test(prompt)) {
+    return { prompt, forceQueue: false }
+  }
+  return { prompt: prompt.replace(QUEUE_SUFFIX_RE, '').trimEnd(), forceQueue: true }
+}
+
+function shouldSkipEmptyPrompt({
+  message,
+  prompt,
+  images,
+  hasVoiceAttachment,
+}: {
+  message: Message
+  prompt: string
+  images?: DiscordFileAttachment[]
+  hasVoiceAttachment: boolean
+}): boolean {
+  if (prompt.trim()) {
+    return false
+  }
+  if ((images?.length || 0) > 0) {
+    return false
+  }
+
+  const inferredVoiceAttachment = message.attachments.some((attachment) => {
+    return isVoiceAttachment(attachment)
+  })
+  if (!hasVoiceAttachment && !inferredVoiceAttachment && message.attachments.size === 0) {
+    return false
+  }
+
+  voiceLogger.warn(
+    `[INGRESS] Skipping empty prompt after preprocessing attachments=${message.attachments.size} hasVoiceAttachment=${hasVoiceAttachment} inferredVoiceAttachment=${inferredVoiceAttachment}`,
+  )
+  return true
+}
+
+async function getRepliedMessageContext({
+  message,
+}: {
+  message: Message
+}): Promise<RepliedMessageContext | undefined> {
+  if (!message.reference?.messageId) {
+    return undefined
+  }
+
+  const referencedMessage = await errore.tryAsync(() => {
+    return message.fetchReference()
+  })
+  if (referencedMessage instanceof Error) {
+    logger.warn(
+      `[INGRESS] Failed to fetch replied message ${message.reference.messageId} for ${message.id}: ${referencedMessage.message}`,
+    )
+    return undefined
+  }
+
+  const repliedText = resolveMentions(referencedMessage)
+    .trim()
+    .slice(0, REPLIED_MESSAGE_TEXT_LIMIT)
+  if (!repliedText) {
+    return undefined
+  }
+
+  return {
+    authorUsername: referencedMessage.author.username,
+    text: repliedText,
+  }
+}
+
+/**
+ * Pre-process a message in an existing thread (thread already has a session or
+ * needs a new one). Handles voice transcription, text/file attachments, and
+ * session context fetching for voice messages.
+ *
+ * For threads with an existing session, voice transcription is enriched with
+ * current + last session context (used by the transcription model to better
+ * understand domain-specific terms).
+ */
+export async function preprocessExistingThreadMessage({
+  message,
+  thread,
+  projectDirectory,
+  channelId,
+  isCliInjected,
+  hasVoiceAttachment,
+  appId,
+}: {
+  message: Message
+  thread: ThreadChannel
+  projectDirectory: string
+  channelId: string | undefined
+  isCliInjected: boolean
+  hasVoiceAttachment: boolean
+  appId: string | undefined
+}): Promise<PreprocessResult> {
+  const sessionId = await getThreadSession(thread.id)
+
+  // ── No existing session: new session in an existing thread ──
+  if (!sessionId) {
+    return preprocessNewSessionMessage({
+      message,
+      thread,
+      projectDirectory,
+      hasVoiceAttachment,
+      appId,
+    })
+  }
+
+  // ── Existing session path ──
+  voiceLogger.log(`[SESSION] Found session ${sessionId} for thread ${thread.id}`)
+
+  let messageContent = isCliInjected
+    ? (message.content || '')
+    : resolveMentions(message)
+  const repliedMessage = await getRepliedMessageContext({ message })
+
+  // Fetch session context and available agents for voice transcription enrichment
+  let currentSessionContext: string | undefined
+  let lastSessionContext: string | undefined
+  let agents: AgentInfo[] = []
+
+  if (projectDirectory) {
+    try {
+      const getClient = await initializeOpencodeForDirectory(
+        projectDirectory,
+        { channelId },
+      )
+      if (getClient instanceof Error) {
+        voiceLogger.error(
+          `[SESSION] Failed to initialize OpenCode client:`,
+          getClient.message,
+        )
+        throw new Error(getClient.message)
+      }
+      const client = getClient()
+
+      const [sessionContextResult, lastSessionResult, fetchedAgents] = await Promise.all([
+        getCompactSessionContext({
+          client,
+          sessionId,
+          includeSystemPrompt: false,
+          maxMessages: 15,
+        }),
+        getLastSessionId({
+          client,
+          excludeSessionId: sessionId,
+        }),
+        fetchAvailableAgents(getClient),
+      ])
+
+      if (errore.isOk(sessionContextResult)) {
+        currentSessionContext = sessionContextResult
+      }
+      agents = fetchedAgents
+
+      const lastSessionId = errore.unwrapOr(lastSessionResult, null)
+      if (lastSessionId) {
+        const result = await getCompactSessionContext({
+          client,
+          sessionId: lastSessionId,
+          includeSystemPrompt: true,
+          maxMessages: 10,
+        })
+        if (errore.isOk(result)) {
+          lastSessionContext = result
+        }
+      }
+    } catch (e) {
+      voiceLogger.error(`Could not get session context:`, e)
+      void notifyError(e, 'Failed to get session context')
+    }
+  }
+
+  const voiceResult = await processVoiceAttachment({
+    message,
+    thread,
+    projectDirectory,
+    appId,
+    currentSessionContext,
+    lastSessionContext,
+    agents,
+  })
+  if (voiceResult) {
+    messageContent = `${VOICE_MESSAGE_TRANSCRIPTION_PREFIX}${voiceResult.transcription}`
+  }
+
+  // Voice transcription failed and no text — drop silently
+  if (hasVoiceAttachment && !voiceResult && !messageContent.trim()) {
+    return { prompt: '', mode: 'opencode', skip: true }
+  }
+
+  // Extract queue suffix from raw message content BEFORE appending text
+  // attachments. Otherwise a text file attachment pushes "? queue" away from
+  // the end of the string and the regex fails to match.
+  const qs = extractQueueSuffix(messageContent)
+
+  const fileAttachments = await getFileAttachments(message)
+  const textAttachmentsContent = await getTextAttachments(message)
+  const prompt = textAttachmentsContent
+    ? `${qs.prompt}\n\n${textAttachmentsContent}`
+    : qs.prompt
+
+  if (
+    shouldSkipEmptyPrompt({
+      message,
+      prompt,
+      images: fileAttachments,
+      hasVoiceAttachment,
+    })
+  ) {
+    return { prompt: '', mode: 'opencode', skip: true }
+  }
+
+  return {
+    prompt,
+    images: fileAttachments.length > 0 ? fileAttachments : undefined,
+    repliedMessage,
+    mode: qs.forceQueue || voiceResult?.queueMessage ? 'local-queue' : 'opencode',
+    agent: voiceResult?.agent,
+  }
+}
+
+/**
+ * Pre-process a message that starts a new session in a thread (no existing
+ * session). Handles starter message context, voice transcription, and
+ * text/file attachments.
+ */
+export async function preprocessNewSessionMessage({
+  message,
+  thread,
+  projectDirectory,
+  hasVoiceAttachment,
+  appId,
+}: {
+  message: Message
+  thread: ThreadChannel
+  projectDirectory: string
+  hasVoiceAttachment: boolean
+  appId?: string
+}): Promise<PreprocessResult> {
+  logger.log(`No session for thread ${thread.id}, starting new session`)
+
+  // Fetch available agents only for voice messages to avoid unnecessary SDK
+  // roundtrips on plain text messages.
+  let agents: AgentInfo[] = []
+  if (hasVoiceAttachment && projectDirectory) {
+    try {
+      const getClient = await initializeOpencodeForDirectory(projectDirectory)
+      agents = await fetchAvailableAgents(getClient)
+    } catch (e) {
+      voiceLogger.error(`Could not fetch agents for voice transcription:`, e)
+    }
+  }
+
+  let prompt = resolveMentions(message)
+  const repliedMessage = await getRepliedMessageContext({ message })
+  const voiceResult = await processVoiceAttachment({
+    message,
+    thread,
+    projectDirectory,
+    appId,
+    agents,
+  })
+  if (voiceResult) {
+    prompt = `${VOICE_MESSAGE_TRANSCRIPTION_PREFIX}${voiceResult.transcription}`
+  }
+
+  // Voice transcription failed and no text — drop silently
+  if (hasVoiceAttachment && !voiceResult && !prompt.trim()) {
+    return { prompt: '', mode: 'opencode', skip: true }
+  }
+
+  // Fetch starter message for thread context
+  const starterMessage = await thread
+    .fetchStarterMessage()
+    .catch((error) => {
+      logger.warn(
+        `[SESSION] Failed to fetch starter message for thread ${thread.id}:`,
+        error instanceof Error ? error.stack : String(error),
+      )
+      return null
+    })
+  if (starterMessage && starterMessage.content !== message.content) {
+    const starterTextAttachments = await getTextAttachments(starterMessage)
+    const starterContent = resolveMentions(starterMessage)
+    const starterText = starterTextAttachments
+      ? `${starterContent}\n\n${starterTextAttachments}`
+      : starterContent
+    if (starterText) {
+      prompt = `Context from thread:\n${starterText}\n\nUser request:\n${prompt}`
+    }
+  }
+
+  const qs = extractQueueSuffix(prompt)
+  if (
+    shouldSkipEmptyPrompt({
+      message,
+      prompt: qs.prompt,
+      hasVoiceAttachment,
+    })
+  ) {
+    return { prompt: '', mode: 'opencode', skip: true }
+  }
+
+  return {
+    prompt: qs.prompt,
+    repliedMessage,
+    mode: qs.forceQueue || voiceResult?.queueMessage ? 'local-queue' : 'opencode',
+    agent: voiceResult?.agent,
+  }
+}
+
+/**
+ * Pre-process a message from a text channel (creates a new thread).
+ * Handles voice transcription and file/text attachments.
+ */
+export async function preprocessNewThreadMessage({
+  message,
+  thread,
+  projectDirectory,
+  hasVoiceAttachment,
+  appId,
+}: {
+  message: Message
+  thread: ThreadChannel
+  projectDirectory: string
+  hasVoiceAttachment: boolean
+  appId?: string
+}): Promise<PreprocessResult> {
+  // Fetch available agents only for voice messages to avoid unnecessary SDK
+  // roundtrips on plain text messages.
+  let agents: AgentInfo[] = []
+  if (hasVoiceAttachment && projectDirectory) {
+    try {
+      const getClient = await initializeOpencodeForDirectory(projectDirectory)
+      agents = await fetchAvailableAgents(getClient)
+    } catch (e) {
+      voiceLogger.error(`Could not fetch agents for voice transcription:`, e)
+    }
+  }
+
+  let messageContent = resolveMentions(message)
+  const repliedMessage = await getRepliedMessageContext({ message })
+  const voiceResult = await processVoiceAttachment({
+    message,
+    thread,
+    projectDirectory,
+    isNewThread: true,
+    appId,
+    agents,
+  })
+  if (voiceResult) {
+    messageContent = `${VOICE_MESSAGE_TRANSCRIPTION_PREFIX}${voiceResult.transcription}`
+  }
+
+  // Voice transcription failed and no text — drop silently
+  if (hasVoiceAttachment && !voiceResult && !messageContent.trim()) {
+    return { prompt: '', mode: 'opencode', skip: true }
+  }
+
+  // Extract queue suffix from raw message content BEFORE appending text
+  // attachments (same fix as preprocessExistingThreadMessage).
+  const qs = extractQueueSuffix(messageContent)
+
+  const fileAttachments = await getFileAttachments(message)
+  const textAttachmentsContent = await getTextAttachments(message)
+  const prompt = textAttachmentsContent
+    ? `${qs.prompt}\n\n${textAttachmentsContent}`
+    : qs.prompt
+
+  if (
+    shouldSkipEmptyPrompt({
+      message,
+      prompt,
+      images: fileAttachments,
+      hasVoiceAttachment,
+    })
+  ) {
+    return { prompt: '', mode: 'opencode', skip: true }
+  }
+
+  return {
+    prompt,
+    images: fileAttachments.length > 0 ? fileAttachments : undefined,
+    repliedMessage,
+    mode: qs.forceQueue || voiceResult?.queueMessage ? 'local-queue' : 'opencode',
+    agent: voiceResult?.agent,
+  }
+}

package/src/onboarding-tutorial.ts

@@ -0,0 +1,176 @@
+// Onboarding tutorial system instructions injected by the plugin when the
+// user starts a 3D game tutorial session. The `markdown` tag is a no-op
+// identity function — it exists only for editor syntax highlighting.
+//
+// This file has no discord.js deps so it can be safely imported by both
+// the welcome message (discord side) and the opencode plugin.
+
+// Unique text used in the welcome message and detected by the plugin to
+// trigger tutorial instruction injection. Shared constant so they can't
+// drift out of sync.
+export const TUTORIAL_WELCOME_TEXT =
+  'Want to build an example browser game? Respond in this thread.'
+
+const markdown = String.raw
+const backticks = '```'
+
+export const ONBOARDING_TUTORIAL_INSTRUCTIONS = markdown`
+You are helping a new user try Kimaki for the first time. The default suggestion is building a 3D game, but if the user asks to build something else, build that instead. Adapt all instructions below to whatever the user wants.
+
+## Prerequisites
+
+Before doing anything else, check that these are installed:
+
+**Bun** (v1.2 or later) — runtime and bundler:
+
+${backticks}bash
+bun --version
+${backticks}
+
+If missing or below 1.2, tell the user to install it: https://bun.sh — or run:
+
+${backticks}bash
+curl -fsSL https://bun.sh/install | bash
+${backticks}
+
+**tmux** — needed to run the dev server in the background with kimaki tunnel:
+
+${backticks}bash
+tmux -V
+${backticks}
+
+If missing, tell the user to install it: https://github.com/tmux/tmux/wiki/Installing — or:
+
+${backticks}bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+${backticks}
+
+Do NOT use Node.js, npm, or npx. Use Bun for everything.
+
+## Goal
+
+Build a simple but visually impressive 3D game using Three.js that runs in the browser. The user should be able to play it within a few minutes of starting. If the user asked for something different, build that instead.
+
+## Game idea
+
+Build a "Space Dodge" game:
+- The player controls a spaceship that flies forward through space
+- Asteroids/obstacles come toward the player
+- The player dodges left/right/up/down using arrow keys or WASD
+- Touch/swipe controls for mobile — the user is on Discord and may open the link on their phone
+- Score increases over time, speed gradually increases
+- Particle effects for explosions when hit
+- Starfield background for atmosphere
+- Simple start screen and game over screen with score
+
+If the game idea doesn't match what the user asked for, adapt to their request instead.
+
+## Project setup
+
+Create these files:
+
+**package.json** — install three as a dependency:
+${backticks}json
+{
+  "dependencies": {
+    "three": "^0.170.0"
+  }
+}
+${backticks}
+
+Run bun install after creating it.
+
+**tsconfig.json**:
+${backticks}json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "types": ["three"]
+  }
+}
+${backticks}
+
+**index.html** — the entry point, references the TypeScript source:
+${backticks}html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Space Dodge</title>
+    <style>
+      body { margin: 0; overflow: hidden; }
+      canvas { display: block; }
+    </style>
+  </head>
+  <body>
+    <script type="module" src="./game.ts"></script>
+  </body>
+</html>
+${backticks}
+
+**game.ts** — all game logic in TypeScript, importing from "three":
+${backticks}ts
+import * as THREE from "three"
+// ... game code here
+${backticks}
+
+Write the full game code in game.ts. Import Three.js with normal imports (Bun bundles it automatically). Add basic mobile touch controls (swipe to move) so it works on phones too.
+
+**server.ts** — Bun fullstack dev server (reads port from PORT env var):
+${backticks}ts
+import homepage from "./index.html"
+
+Bun.serve({
+  port: Number(process.env.PORT) || 3000,
+  routes: { "/": homepage },
+  development: true,
+})
+${backticks}
+
+## Dev server and tunnel
+
+After creating all files and running bun install, start the dev server and expose it via kimaki tunnel so the user can play immediately from their browser or phone. The user is on Discord, not at a terminal — localhost URLs are useless to them.
+
+Pick a random port between 3000-9000 to avoid conflicts:
+
+${backticks}bash
+PORT=$((RANDOM % 6000 + 3000))
+tmux kill-session -t game-dev 2>/dev/null
+tmux new-session -d -s game-dev -c "$PWD"
+tmux send-keys -t game-dev "PORT=$PORT kimaki tunnel -p $PORT -- bun run server.ts" Enter
+${backticks}
+
+Wait a moment, then get the tunnel URL:
+
+${backticks}bash
+sleep 1 && tmux capture-pane -t game-dev -p
+${backticks}
+
+If the tunnel URL is not visible yet, run the capture command again — it usually appears within a few seconds.
+
+After the tunnel is up, also generate a diff URL so the user can browse the code:
+
+${backticks}bash
+git init && git add -A && critique --url
+${backticks}
+
+Share both URLs prominently so the user can play the game and browse the code. Put each URL on its own line, not buried in text.
+
+## Behavior
+
+- Be friendly and casual in the conversation. Sound like a helpful teammate, not a formal tutorial.
+- Be concise and direct. Show the code, start the server, share the URL.
+- After the game is working and the user can play it, ask what they'd like to change by using the question tool. Do not present a manual numbered list in plain text. Offer a few short button/dropdown options like sound effects, ship design, leaderboard, power-ups, and multiplayer, while still allowing a custom answer.
+- Never mention this is a tutorial, onboarding, or demo. Act like a normal coding session.
+- Never apologize or over-explain. Just build and iterate.
+- If the user asks to change something, do it quickly and share the updated URL.
+`

package/src/onboarding-welcome.ts

@@ -0,0 +1,49 @@
+// Onboarding welcome message for the default kimaki channel.
+// Sends a message explaining what Kimaki is, then creates a thread from it
+// so the user can respond there to start a tutorial session.
+// Sends a smaller follow-up message inside the thread with the installer
+// mention so the notification is less noisy.
+// Posted once when the default channel is first created.
+
+import { ThreadAutoArchiveDuration, type TextChannel } from 'discord.js'
+import { createLogger, LogPrefix } from './logger.js'
+import { TUTORIAL_WELCOME_TEXT } from './onboarding-tutorial.js'
+
+const logger = createLogger(LogPrefix.CHANNEL)
+
+function buildWelcomeText(): string {
+  return `**Kimaki** lets you code from Discord. Send a message in any project channel and an AI agent edits code, runs commands, and searches your codebase — all on your machine.
+**What you can do:**
+- Use \`/add-project\` to create a Discord channel linked to one OpenCode project (git repo)
+- Collaborate with teammates in the same session
+- Upload images and files, the bot can share screenshots back
+${TUTORIAL_WELCOME_TEXT}`
+}
+
+function buildThreadPrompt({ mentionUserId }: { mentionUserId?: string }): string {
+  const mentionSuffix = mentionUserId ? ` <@${mentionUserId}>` : ''
+  return `Want to build an example browser game? Respond in this thread.${mentionSuffix}`
+}
+
+export async function sendWelcomeMessage({
+  channel,
+  mentionUserId,
+}: {
+  channel: TextChannel
+  mentionUserId?: string
+}): Promise<void> {
+  try {
+    const message = await channel.send(buildWelcomeText())
+    const thread = await message.startThread({
+      name: 'Kimaki tutorial',
+      autoArchiveDuration: ThreadAutoArchiveDuration.OneDay,
+      reason: 'Onboarding tutorial thread',
+    })
+    await thread.send(buildThreadPrompt({ mentionUserId }))
+    logger.log(`Sent welcome message with thread to #${channel.name}`)
+  } catch (error) {
+    logger.warn(
+      `Failed to send welcome message to #${channel.name}: ${error instanceof Error ? error.stack : String(error)}`,
+    )
+  }
+}