kimaki 1.0.0 → 1.2.0

package/src/system-prompt.ts

@@ -108,28 +108,7 @@ export function baseInstructions({
 
       ## debugging kimaki issues
 
-      ALWAYS read https://kimaki.dev/docs/guides/report-bugs first before submitting any issue to Kimaki. That page is the source of truth for exporting session jsonl, sharing evidence in a gist, and filing bugs. Never open a pull request on remorses/kimaki unless remorses asked for one in a comment on the issue.
-      If there are internal kimaki issues (sessions not responding, bot errors, unexpected behavior), read the logs of the running bot and of the OpenCode service it talks to. Read them before guessing.
-
-      **Kimaki bot log**: \`${dataDir}/kimaki.log\`, only the current bot run. The run before the last restart (including the crash that caused it) is in \`${dataDir}/kimaki.previous.log\`. Each line is \`<ISO time> <LEVEL> [<MODULE>] <message>\`, and errors include their cause chain. It logs incoming messages, run start/finish/failure per thread and session, Discord and OpenCode errors, routines and crashes.
-
-      \`\`\`bash
-      tail -n 200 ${dataDir}/kimaki.log
-      grep -E ' (WARN|ERROR) ' ${dataDir}/kimaki.log | tail -n 50
-      grep '<thread_id or ses_id>' ${dataDir}/kimaki.log
-      \`\`\`
-
-      **OpenCode service log**: the shared \`opencode serve --service\` daemon appends to \`~/.local/share/opencode/log/opencode.log\` (\`$XDG_DATA_HOME/opencode/log\`; \`opencode debug paths\` prints the folder). The file is never reset and can be very large: always use \`tail\` or \`grep\`, never read it whole. Lines are logfmt. \`run=<id>\` is one daemon process, so filter by the run of the last line. The daemon pid and URL are in \`~/.local/state/opencode/service.json\`.
-
-      \`\`\`bash
-      LOG=~/.local/share/opencode/log/opencode.log
-      RUN=$(tail -n 1 $LOG | grep -o 'run=[a-z0-9]*')
-      grep "$RUN " $LOG | grep -E '^timestamp=[^ ]+ level=(ERROR|WARN)' | tail -n 50
-      grep "$RUN " $LOG | grep '<ses_id>' | tail -n 100
-      \`\`\`
-
-      \`kimaki session events <id>\` prints the recorded OpenCode events of a thread as JSONL.
-      \`kimaki restart\` restarts the bot (only when the user asks). \`kimaki profile cpu --duration 30s\` and \`kimaki profile heap\` print the profile file path.
+      When sessions do not respond, the bot shows errors, or you need the Kimaki or OpenCode logs, load the \`kimaki-debug\` skill (logs, profiling, \`kimaki login\` for provider credentials) and read the logs before guessing. Do not restart the bot unless the user explicitly asks. ALWAYS read https://kimaki.dev/docs/guides/report-bugs before submitting any issue to Kimaki. Never open a pull request on remorses/kimaki unless remorses asked for one in a comment on the issue.
 
       ## uploading files to discord
 
@@ -137,6 +116,10 @@ export function baseInstructions({
 
       kimaki upload-to-discord --session ${sessionId} <file1> [file2] ...
 
+      To send several images or files, pass them all to ONE command in the order you want them shown, not one command per file. Discord shows them in argument order with numbered labels (\`1. a.png\`, \`2. b.pdf\`), so you and the user can refer to them by number (for example "screenshot 2"). Name them in your text with the same numbers.
+
+      Files the user attaches arrive in an \`<attachments>\` block, numbered in the order the user attached them. When the user says "the second image", use that numbering.
+
       NEVER show images with markdown like \`![alt](/tmp/file.png)\` or \`![alt](file://...)\`. Discord does not render local markdown images. ALWAYS upload them with \`kimaki upload-to-discord\` so they appear as real Discord attachments. Do this for every screenshot, generated image, and visual step the user should see.
 
       ## generating audio from text
@@ -386,15 +369,25 @@ export function baseInstructions({
 
       Each row shows the session ID, status (\`busy\`, \`waiting\` for input, or \`idle\`), the title, and \`tokens: N\`. Titles prefixed with \`btw:\` are side sessions that answer a related user question in parallel. They are not duplicate sessions of the main task.
 
-      To search past sessions (supports plain text or /regex/flags). Defaults to this project and the last 14 days. Use \`--days 0\` for all time. Use \`--all\` to search every project:
+      To search past sessions, search the transcripts. Kimaki writes one markdown file per session to \`${dataDir}/transcripts/<session id>.md\` when a run ends (user messages, assistant text and short tool inputs; no tool outputs, no thinking). The first lines are \`# <title> (<session id>)\` and \`directory: <folder>\`; messages start with \`## user <time>\` or \`## assistant <time> (<agent>, <model>)\`. Use rg (or \`grep -r\` when rg is missing):
+
+      \`\`\`bash
+      rg -il 'auth timeout' ${dataDir}/transcripts                     # sessions that mention it; the file name is the session ID
+      rg -i -C3 'auth timeout' ${dataDir}/transcripts/<session id>.md  # matches with context in one session
+      rg -i -m3 'rate limit' ${dataDir}/transcripts                    # first 3 matches per session
+      rg -i 'error\\s+42|panic' ${dataDir}/transcripts                 # regex
+      rg -i '^# .*billing' ${dataDir}/transcripts                      # titles
+      rg -l '^directory: /path/to/project' ${dataDir}/transcripts      # sessions of one project
+      rg -il 'auth timeout' $(find ${dataDir}/transcripts -name '*.md' -mtime -3)   # last 3 days
+      \`\`\`
+
+      Sessions that Kimaki did not run (OpenCode TUI) and old sessions are not there until you sync. The command skips current transcripts, so it is cheap to run again:
 
       \`\`\`bash
-      kimaki session search "auth timeout"
-      kimaki session search "auth timeout" --days 0
-      kimaki session search "/error\\s+42/i"
-      kimaki session search "rate limit" --project /path/to/project
-      kimaki session search "/panic|crash/i" --channel <channel_id>
-      kimaki session search "auth timeout" --all
+      kimaki session sync                # sessions updated in the last 14 days
+      kimaki session sync --days 60
+      kimaki session sync --all          # every session, any age (slow the first time)
+      kimaki session sync --rebuild      # write all again, for example after the format changed
       \`\`\`
 
       To read a session as markdown, pipe to a file. Logs go to stderr:
@@ -469,10 +462,6 @@ export function baseInstructions({
 
       \`session list --active\` exits 0 while it finds active sessions, 1 when none remain, and 64 on errors. The loop stops only on 1, so an error never looks like "no active sessions". \`--active\` never lists the calling session (\`OPENCODE_SESSION_ID\`), so the loop does not wait for itself. Sessions can start again after the loop ends, so run the check again right before each commit. \`session wait\` returns once the model finishes responding, or when the session pauses to show the user a question (it does not finish on its own until answered).
 
-      ## provider credentials
-
-      Provider credentials belong to OpenCode. Use \`kimaki login PROVIDER\` to list login methods; \`--key\` connects an API key, \`--method\` starts OAuth, and \`--attempt\` checks or completes an attempt.
-
       ## submodules
 
       When pulling submodules and they jump to a new commit, commit that submodule pointer update right away before doing other work. Otherwise critique diffs later will include the noisy submodule jump along with the real changes.
@@ -512,31 +501,7 @@ export function baseInstructions({
 
       ## running dev servers with tunnel access
 
-      Localhost URLs are useless from Discord. When the user should open a local dev server in a browser, wrap it in \`kimaki tunnel\` to get a public URL, and run it in a named background \`tuistory\` session so you can wait for output, read logs, and stop it later. Name it descriptively (e.g. \`projectname-dev\`) so you can reuse it. Run \`bunx tuistory --help\` first. Invoke \`kimaki\` directly, not via \`npx\` or \`bunx\`.
-
-      - Use random tunnel IDs by default. Pass \`-t <id>\` only for services that are safe to be publicly discoverable.
-      - \`kimaki tunnel\` detects the local port from the child output. Pass \`--port\` only when the server prints no detectable localhost URL or port line.
-      - \`kimaki tunnel\` injects \`TRAFORO_URL\` into the child process. Wire the app to it so OAuth callbacks, webhook URLs, and absolute links use the public URL.
-
-      \`\`\`bash
-      # start in a named background session, wait for output, then read the tunnel URL
-      bunx tuistory launch "kimaki tunnel -- pnpm dev" -s myapp-dev
-      bunx tuistory -s myapp-dev wait "/ready|local|tunnel/i" --timeout 30000
-      bunx tuistory read -s myapp-dev
-
-      # pass the public URL to the app (better-auth, Next.js, Vite; node can read process.env.TRAFORO_URL)
-      bunx tuistory launch "kimaki tunnel -- sh -c 'BETTER_AUTH_URL=$TRAFORO_URL exec pnpm dev'" -s myapp-dev
-      bunx tuistory launch "kimaki tunnel -- sh -c 'APP_URL=$TRAFORO_URL exec pnpm dev'" -s myapp-dev
-      bunx tuistory launch "kimaki tunnel -- sh -c 'VITE_BASE_URL=$TRAFORO_URL exec pnpm dev'" -s myapp-dev
-
-      # custom tunnel ID (only for intentionally public-safe services)
-      bunx tuistory launch "kimaki tunnel -t holocron -- pnpm dev" -s holocron-dev
-
-      # list sessions; stop with Ctrl+C, then close
-      bunx tuistory sessions
-      bunx tuistory -s myapp-dev press ctrl c
-      bunx tuistory -s myapp-dev close
-      \`\`\`
+      Localhost URLs are useless from Discord. When the user should open a local dev server in a browser, load the \`kimaki-tunnel\` skill: it wraps the server in \`kimaki tunnel\` to get a public URL.
 
       ## markdown formatting
 
@@ -641,8 +606,19 @@ export function stripTurnContext(text: string): string {
   return text.replace(/\n\n(<local-files>\n[\s\S]*?<\/local-files>\n)?<discord-user [^\n]*\/>$/, '')
 }
 
-// Attachments the model cannot see inline: it reads them with tools.
-export function localFilesBlock(paths: readonly string[]): string {
+const PromptAttachmentSchema = z.object({ name: z.string(), path: z.string(), inline: z.boolean() })
+export type PromptAttachment = z.infer<typeof PromptAttachmentSchema>
+
+// Every attachment of the message, numbered in Discord order, so the user and the
+// model can refer to "image 2". Inline ones are already in the message.
+export function attachmentsBlock(attachments: readonly PromptAttachment[]): string {
+  if (attachments.length === 0) return ''
+  const lines = attachments.map((file, index) => `${index + 1}. ${file.name}${file.inline ? ' (inline)' : ''}: ${file.path}`)
+  return `<attachments>\nFiles of this message in the order the user attached them, saved on disk. Read the ones not marked inline with tools.\n${lines.join('\n')}\n</attachments>\n`
+}
+
+// Prompts before numbered attachments: only the files the model could not see inline.
+function localFilesBlock(paths: readonly string[]): string {
   if (paths.length === 0) return ''
   return `<local-files>\nAttachments saved on disk. OpenCode cannot show these inline; use tools to read them.\n${paths.join('\n')}\n</local-files>\n`
 }
@@ -654,7 +630,8 @@ const TurnContextSchema = z.object({
   messageId: z.string(),
   threadId: z.string(),
   threadName: z.string(),
-  localFiles: z.array(z.string()),
+  attachments: z.array(PromptAttachmentSchema).optional(),
+  localFiles: z.array(z.string()).optional(),
 })
 export type TurnContext = z.infer<typeof TurnContextSchema>
 
@@ -663,8 +640,9 @@ export type TurnContext = z.infer<typeof TurnContextSchema>
 export function turnContext(metadata: Readonly<Record<string, unknown>> | undefined): string | null {
   const parsed = TurnContextSchema.safeParse(metadata?.['discord'])
   if (!parsed.success) return null
-  const { username, userId, messageId, threadId, threadName, localFiles } = parsed.data
-  return `${localFilesBlock(localFiles)}<discord-user name="${escapeAttribute(username)}" user-id="${userId}" message-id="${messageId}" thread-id="${threadId}" thread-name="${escapeAttribute(threadName)}" />`
+  const { username, userId, messageId, threadId, threadName, attachments, localFiles } = parsed.data
+  const files = attachments ? attachmentsBlock(attachments) : localFilesBlock(localFiles ?? [])
+  return `${files}<discord-user name="${escapeAttribute(username)}" user-id="${userId}" message-id="${messageId}" thread-id="${threadId}" thread-name="${escapeAttribute(threadName)}" />`
 }
 
 export type VoiceCallUser = { id: string; username: string }
@@ -913,7 +891,8 @@ function voiceCallReference({
     kimaki project list --json                           # projects with channel ID, folder and guild ID
     kimaki session list --project <folder>               # threads of a project with status busy, waiting or idle
     kimaki session list --all --active                   # threads that run now, in every project
-    kimaki session search 'text' --all --days 0          # find threads by title or content, all time
+    rg -il 'text' ${dataDir}/transcripts                  # find threads by title or content; file name = session ID
+    kimaki session sync --days 60                        # write transcripts of older or non-Kimaki sessions first
     kimaki session read <thread ID or link> 2>/dev/null | tail -c 3000   # end of a thread transcript
     kimaki session wait <thread ID>                      # wait until a thread finishes, then print it
     kimaki session abort <thread ID>                     # stop the agent of a thread; the thread stays

package/src/voice-attachments.e2e.test.ts

@@ -39,8 +39,11 @@ const matchers: DeterministicMatcher[] = [
   {
     id: 'image',
     priority: 500,
-    // The plugin adds <local-files> and <discord-user> to the model request only.
-    when: { latestUserTextRegex: 'image-marker[\\s\\S]*<local-files>[\\s\\S]*archive\\.zip\\n</local-files>\\n<discord-user ', rawPromptIncludes: 'image/png' },
+    // The plugin adds the numbered <attachments> and <discord-user> to the model request only.
+    when: {
+      latestUserTextRegex: 'image-marker[\\s\\S]*<attachments>[\\s\\S]*1\\. dot\\.png \\(inline\\): [^\\n]*\\n2\\. notes\\.txt: [^\\n]*\\n3\\. archive\\.zip: [^\\n]*\\n</attachments>\\n<discord-user ',
+      rawPromptIncludes: 'image/png',
+    },
     then: { parts: textParts('I see an image') },
   },
   reply('voice-steer', 'voice steer ok'),
@@ -137,7 +140,7 @@ test('image and text attachments reach the model as files', async () => {
   // OpenCode drops binary files: the model gets their local paths from metadata, the stored text stays clean.
   expect(user?.type === 'user' && user.text).toBe('What is this image-marker')
   const discord = user?.type === 'user' ? user.metadata?.['discord'] : null
-  expect(JSON.stringify(discord).replaceAll(dataDir, '<data>').replace(/\/\d+\//g, '/<message>/').replace(/\d{6,}/g, 'ID')).toMatchInlineSnapshot(`"{"userId":"ID","username":"tommy","messageId":"ID","threadId":"ID","threadName":"What is this image-marker","localFiles":["<data>/attachments/<message>/1-notes.txt","<data>/attachments/<message>/2-archive.zip"]}"`)
+  expect(JSON.stringify(discord).replaceAll(dataDir, '<data>').replace(/\/\d+\//g, '/<message>/').replace(/\d{6,}/g, 'ID')).toMatchInlineSnapshot(`"{"userId":"ID","username":"tommy","messageId":"ID","threadId":"ID","threadName":"What is this image-marker","attachments":[{"name":"dot.png","path":"<data>/attachments/<message>/0-dot.png","inline":true},{"name":"notes.txt","path":"<data>/attachments/<message>/1-notes.txt","inline":false},{"name":"archive.zip","path":"<data>/attachments/<message>/2-archive.zip","inline":false}]}"`)
 })
 
 test('voice in a channel starts a session with the transcription and the spoken agent', async () => {

package/src/voice-call.ts

@@ -349,7 +349,7 @@ export function createVoiceCalls({ opencodeConfigDir }: { opencodeConfigDir: str
     const states = guild.voiceStates.cache.filter((state) => state.channelId === channelId && state.id !== bot.discord.user?.id)
     const users = new Map<string, Author>()
     for (const state of states.values()) {
-      if (!(await canUseKimaki({ guild, userId: state.id }))) continue
+      if (!(await canUseKimaki(bot, { guild, userId: state.id }))) continue
       const user = await bot.discord.users.fetch(state.id).catch(() => null)
       users.set(state.id, { id: state.id, username: user?.username ?? state.id })
     }

package/src/plugin/session-id/index.ts

@@ -1,19 +0,0 @@
-// Tells the model its own OpenCode session ID, in every session (TUI, Discord, subagents).
-//
-// The ID never changes in a session, so the system text is the same on every
-// request and the provider prompt cache keeps hitting.
-//
-// Standalone in plain OpenCode without the bot: list this directory in
-// opencode.json `plugins`. The bot then skips its shim, see installPluginShim
-// in opencode-server.ts. It imports nothing from Kimaki outside this folder.
-
-import { Plugin } from '@opencode/plugin'
-
-export default Plugin.define({
-  id: 'kimaki-session-id',
-  async setup(ctx) {
-    await ctx.session.hook('context', (event) => {
-      event.system.push({ type: 'text', text: `OpenCode session ID: ${event.sessionID}` })
-    })
-  },
-})