kimaki 0.4.77 → 0.4.78

package/package.json

@@ -2,7 +2,7 @@
   "name": "kimaki",
   "module": "index.ts",
   "type": "module",
-  "version": "0.4.77",
+  "version": "0.4.78",
   "repository": "https://github.com/remorses/kimaki",
   "bin": "bin.js",
   "files": [
@@ -22,9 +22,9 @@
     "eventsource-parser": "^3.0.6",
     "prisma": "7.4.2",
     "tsx": "^4.20.5",
+    "discord-digital-twin": "^0.1.0",
     "opencode-cached-provider": "^0.0.1",
     "opencode-deterministic-provider": "^0.0.1",
-    "discord-digital-twin": "^0.1.0",
     "db": "^0.0.0"
   },
   "dependencies": {
@@ -42,6 +42,7 @@
     "@prisma/client": "7.4.2",
     "@purinton/resampler": "^1.0.4",
     "@sentry/node": "^10.40.0",
+    "@types/ws": "^8.18.1",
     "cron-parser": "^5.5.0",
     "discord.js": "^14.25.1",
     "domhandler": "^5.0.3",
@@ -55,11 +56,12 @@
     "pretty-ms": "^9.3.0",
     "string-dedent": "^3.0.2",
     "undici": "^7.16.0",
+    "ws": "^8.19.0",
     "xdg-basedir": "^5.1.0",
     "zod": "^4.3.6",
     "zustand": "^5.0.11",
-    "traforo": "^0.0.9",
-    "errore": "^0.14.0"
+    "errore": "^0.14.0",
+    "traforo": "^0.0.9"
   },
   "optionalDependencies": {
     "@discordjs/opus": "^0.10.0",
@@ -69,7 +71,7 @@
     "sharp": "^0.34.5"
   },
   "scripts": {
-    "dev": "tsx --env-file .env src/cli.ts",
+    "dev": "tsx src/cli.ts",
     "dev:bun": "DEBUG=1 bun --env-file .env src/cli.ts",
     "watch": "tsx scripts/watch-session.ts",
     "generate": "prisma generate && pnpm generate:sql",

package/skills/event-sourcing-state/SKILL.md

@@ -5,7 +5,7 @@ description: >
   event logs plus pure derivation functions over mirrored mutable lifecycle
   flags. Use when state transitions are driven by events and bugs can be
   reproduced from a saved event stream.
-version: 0.1.0
+version: 0.2.0
 ---
 
 <!-- Skill for event-sourced state and fixture-driven debugging. -->
@@ -19,25 +19,103 @@ phase, status, or UI state that could instead be derived from an event log.
 
 Do not store the answer when you can store the evidence.
 
-Instead of fields like:
+Coding agents overproduce state. Every bug looks like it wants one more flag,
+one more cached answer, one more special case. Every field feels locally
+justified. Globally you are building a machine nobody can hold in their head.
+
+Every boolean you add:
+
+1. doubles your app's possible states
+2. doubles your bugs
+3. doubles the coverage you need in the worst case
+
+The fix is not a better set of flags. The fix is deleting the flags.
+
+Stop storing conclusions and store evidence instead. If a decision depends on
+what actually happened, keep the events and derive the answer from them.
+
+## Anti-pattern: mirrored flags
+
+To answer one yes/no UI question ("should the footer show?"), an agent will
+mirror facts into state:
 
 ```ts
-let isRunning = false
-let lastModel: string | undefined
-let footerVisible = false
-let wasAborted = false
+type ThreadState = {
+  wasInterrupted: boolean
+  didAssistantFinish: boolean
+  didAssistantError: boolean
+  wasToolCallOnly: boolean
+}
+
+function shouldShowFooter(state: ThreadState): boolean {
+  return state.didAssistantFinish
+    && !state.wasInterrupted
+    && !state.didAssistantError
+    && !state.wasToolCallOnly
+}
 ```
 
-store a bounded event stream and derive what you need:
+Four flags to answer one question. Each flag caches a fact already present in
+the event that produced it. Then a function recombines them back into one
+boolean. None of these fields looks insane on its own — that is the trap.
+
+## Pattern: derive from events
+
+Keep the raw events and compute the answer when needed:
 
 ```ts
-type Event =
+type SessionEvent =
   | { type: 'session.status'; status: 'busy' | 'idle' }
-  | { type: 'message.completed'; model: string; tokensUsed: number }
   | { type: 'session.aborted' }
+  | {
+      type: 'message.updated'
+      role: 'assistant'
+      completed: boolean
+      error: boolean
+      finish: 'stop' | 'tool-calls'
+    }
+
+function getLatestAssistantMessage(events: SessionEvent[]) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i]
+    if (event?.type === 'message.updated' && event.role === 'assistant') {
+      return event
+    }
+  }
+  return undefined
+}
+
+function isNaturalCompletion(message: {
+  completed: boolean
+  error: boolean
+  finish: 'stop' | 'tool-calls'
+}): boolean {
+  if (!message.completed) {
+    return false
+  }
+  if (message.error) {
+    return false
+  }
+  return message.finish !== 'tool-calls'
+}
+
+function shouldShowFooter(events: SessionEvent[]): boolean {
+  const msg = getLatestAssistantMessage(events)
+  if (!msg) {
+    return false
+  }
+  return isNaturalCompletion(msg)
+}
 ```
 
-Then compute state with pure functions.
+Notice what disappeared:
+
+1. no interruption flag
+2. no finished flag
+3. no special footer state
+4. no extra state machine to explain another state machine
+
+You keep the raw thing that happened, then compute the answer when needed.
 
 ## Rules
 
@@ -61,38 +139,114 @@ Then compute state with pure functions.
 - tiny local state better kept inside a closure
 - data that is already a stable source of truth elsewhere
 
-## Pattern
+## Testing workflow
+
+1. Export a failing event stream from production or local runtime.
+2. Save it as a fixture (jsonl file).
+3. Write a pure test around the derivation function.
+4. Fix the derivation code.
+5. Keep the fixture so the bug stays dead.
+
+Any model can one-shot these problems because the feedback loop is obvious:
+events in, answer out.
 
 ```ts
-type EventBufferEntry<TEvent> = {
-  event: TEvent
-  timestamp: number
+import fs from 'node:fs'
+
+function loadEvents(file: string): SessionEvent[] {
+  return fs
+    .readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      return JSON.parse(line) as SessionEvent
+    })
 }
 
-function isBusy(events: EventBufferEntry<Event>[]): boolean {
-  for (let i = events.length - 1; i >= 0; i--) {
-    const event = events[i]?.event
-    if (!event) {
-      continue
-    }
-    if (event.type === 'session.status') {
-      return event.status === 'busy'
+test('footer is hidden for aborted runs', () => {
+  const events = loadEvents('./fixtures/aborted-session.jsonl')
+  expect(shouldShowFooter(events)).toBe(false)
+})
+```
+
+The reproduction artifact is just data:
+
+1. no mocking the runtime
+2. no mocking timers
+3. no begging the runtime to reproduce the exact bad interleaving again
+4. just events in, answer out
+
+## Persistency
+
+If you want persistence you just store the events. Events are easily versioned
+and type-safe.
+
+The trade is this:
+
+- **Storing cached state**: if a user hits a broken state and you persist it,
+  the project is gone. Opening it crashes the app. To fix it you need migration
+  code that patches the corrupted state. Tedious and fragile.
+- **Storing the event stream**: you fix the derivation functions, release a new
+  version, the user opens the project, and it works again. What matters is
+  keeping events immutable and versioned so derivation functions are guaranteed
+  to process events from older app versions and return valid state.
+
+State is cached conclusions. Events are stored evidence. Evidence ages better.
+
+If you can derive it, don't store it.
+
+## State encapsulation
+
+The next best thing after no state is state you don't care about because it is
+encapsulated.
+
+Not everything needs event sourcing. The second-best option is state you
+successfully hide. A good example is React `useState`: state can only be
+written in event handlers within the component subtree and can only be read in
+the current component. It is local and easy to reason about.
+
+The same applies to backend code. Instead of promoting a timer or counter into
+a class field visible to all methods, encapsulate it in a closure:
+
+```ts
+// bad: timer is a class field, visible to all methods, agents will touch it
+class MessageWriter {
+  private debounceTimeout: ReturnType<typeof setTimeout> | null = null
+
+  queueSend(text: string): void {
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout)
     }
+    this.debounceTimeout = setTimeout(() => {
+      this.write(text)
+    }, 300)
   }
-  return false
 }
-```
 
-## Testing workflow
+// good: timer is trapped in a tiny box, no other consumer can touch it
+function createDebouncedAction(callback: () => void, delayMs = 300) {
+  let timeout: ReturnType<typeof setTimeout> | null = null
 
-1. export a failing event stream from production or local runtime
-2. save it as a fixture
-3. write a pure test around the derivation function
-4. fix the derivation code
-5. keep the fixture so the bug stays dead
+  function clear(): void {
+    if (!timeout) {
+      return
+    }
+    clearTimeout(timeout)
+    timeout = null
+  }
+
+  function trigger(): void {
+    clear()
+    timeout = setTimeout(() => {
+      timeout = null
+      callback()
+    }, delayMs)
+  }
 
-## State minimization rule
+  return { trigger, clear }
+}
+```
 
-The next best thing after no state is state you do not care about because it
-is encapsulated. If something must stay mutable, hide it inside a tiny closure
-or helper instead of exposing it to the whole app.
+A global variable has the potential of doubling your app state. An encapsulated
+closure can only double the states of that tiny function. Given it is so small
+you don't care — spotting a bug inside it is easy for you and agents.

package/skills/playwriter/SKILL.md

@@ -8,7 +8,7 @@ description: Control the user own Chrome browser via Playwriter extension with P
 **Before using playwriter, you MUST run this command:**
 
 ```bash
-playwriter skill
+playwriter skill # IMPORTANT! do not use | head here. read in full!
 ```
 
 This outputs the complete documentation including:

package/src/cli.ts

@@ -1089,6 +1089,16 @@ async function registerCommands({
       .setDescription('List and manage MCP servers for this project')
       .setDMPermission(false)
       .toJSON(),
+    new SlashCommandBuilder()
+      .setName('screenshare')
+      .setDescription('Start screen sharing via VNC tunnel (auto-stops after 1 hour)')
+      .setDMPermission(false)
+      .toJSON(),
+    new SlashCommandBuilder()
+      .setName('screenshare-stop')
+      .setDescription('Stop screen sharing')
+      .setDMPermission(false)
+      .toJSON(),
   ]
 
   // Add user-defined commands with source-based suffixes (-cmd / -skill)
@@ -4138,6 +4148,31 @@ cli
     },
   )
 
+cli
+  .command(
+    'screenshare',
+    'Share your screen via VNC tunnel. Auto-stops after 1 hour. Runs until Ctrl+C. Use tmux to run in background.',
+  )
+  .action(async () => {
+    const { startScreenshare } = await import(
+      './commands/screenshare.js'
+    )
+    try {
+      const session = await startScreenshare({
+        sessionKey: 'cli',
+        startedBy: 'cli',
+      })
+      cliLogger.log(`Screen sharing started: ${session.noVncUrl}`)
+      cliLogger.log('Press Ctrl+C to stop')
+    } catch (err) {
+      cliLogger.error(
+        'Failed to start screen share:',
+        err instanceof Error ? err.message : String(err),
+      )
+      process.exit(EXIT_NO_RESTART)
+    }
+  })
+
 cli
   .command('sqlitedb', 'Show the location of the SQLite database file')
   .action(() => {

package/src/commands/diff.ts

@@ -14,7 +14,7 @@ import {
   SILENT_MESSAGE_FLAGS,
 } from '../discord-utils.js'
 import { createLogger, LogPrefix } from '../logger.js'
-import { execAsync } from '../worktrees.js'
+import { uploadGitDiffViaCritique } from '../critique-utils.js'
 
 const logger = createLogger(LogPrefix.DIFF)
 
@@ -63,103 +63,29 @@ export async function handleDiffCommand({
 
   await command.deferReply({ flags: SILENT_MESSAGE_FLAGS })
 
-  try {
-    const projectName = path.basename(workingDirectory)
-    const title = `${projectName}: Discord /diff`
-    const { stdout, stderr } = await execAsync(
-      `bunx critique --web "${title}" --json`,
-      {
-        cwd: workingDirectory,
-        timeout: 30000,
-      },
-    )
-
-    // critique --json outputs JSON on the last line: {"url":"...","id":"..."} or {"error":"..."}
-    const output = stdout || stderr
-    const lines = output.trim().split('\n')
-    const jsonLine = lines[lines.length - 1]
-    if (!jsonLine) {
-      await command.editReply({
-        content: 'No changes to show',
-      })
-      return
-    }
-
-    let result: { url?: string; id?: string; error?: string }
-    try {
-      result = JSON.parse(jsonLine)
-    } catch {
-      // Fallback: try to find URL in output
-      const urlMatch = output.match(/https?:\/\/critique\.work\/[^\s]+/)
-      if (urlMatch) {
-        await command.editReply({
-          content: `[diff](${urlMatch[0]})`,
-        })
-        logger.log(`Diff shared: ${urlMatch[0]}`)
-        return
-      }
-      await command.editReply({
-        content: 'No changes to show',
-      })
-      return
-    }
-
-    if (result.error || !result.url || !result.id) {
-      await command.editReply({
-        content: result.error || 'No changes to show',
-      })
-      return
-    }
-
-    const imageUrl = `https://critique.work/og/${result.id}.png`
-    const embed = new EmbedBuilder()
-      .setTitle(title)
-      .setURL(result.url)
-      .setImage(imageUrl)
-
-    await command.editReply({
-      embeds: [embed],
-    })
-    logger.log(`Diff shared: ${result.url}`)
-  } catch (error) {
-    logger.error('[DIFF] Error:', error)
-
-    // exec error includes stdout/stderr - try to parse JSON from it
-    const execError = error as {
-      stdout?: string
-      stderr?: string
-      message?: string
-    }
-    const output = execError.stdout || execError.stderr || ''
-
-    // Check if critique output JSON even on error
-    const lines = output.trim().split('\n')
-    const jsonLine = lines[lines.length - 1]
-    if (jsonLine) {
-      try {
-        const result = JSON.parse(jsonLine) as { error?: string }
-        if (result.error) {
-          await command.editReply({
-            content: result.error,
-          })
-          return
-        }
-      } catch {
-        // not JSON, continue to generic error
-      }
-    }
-
-    // Check for common errors
-    const message = execError.message || 'Unknown error'
-    if (message.includes('command not found') || message.includes('ENOENT')) {
-      await command.editReply({
-        content: 'bunx/critique not available',
-      })
-      return
-    }
-
-    await command.editReply({
-      content: `Failed to generate diff: ${message.slice(0, 200)}`,
-    })
+  const projectName = path.basename(workingDirectory)
+  const title = `${projectName}: Discord /diff`
+  const result = await uploadGitDiffViaCritique({
+    title,
+    cwd: workingDirectory,
+  })
+
+  if (!result) {
+    await command.editReply({ content: 'No changes to show' })
+    return
   }
+
+  if (result.error || !result.url) {
+    await command.editReply({ content: result.error || 'No changes to show' })
+    return
+  }
+
+  const imageUrl = `https://critique.work/og/${result.id}.png`
+  const embed = new EmbedBuilder()
+    .setTitle(title)
+    .setURL(result.url)
+    .setImage(imageUrl)
+
+  await command.editReply({ embeds: [embed] })
+  logger.log(`Diff shared: ${result.url}`)
 }