osborn 0.9.43 → 0.9.45

package/.claude/skills/meetings/SKILL.md

@@ -1,73 +1,145 @@
 # Skill: Meetings
 
-Silent note-taking and TODO-tracking when osborn is sitting in a live meeting.
+Silent note-taking and TODO-tracking when osborn is sitting in a live meeting,
+and explicit on-demand transcript pulls from Recall.ai when the user asks.
 
 ## When to use
 
-When a user message arrives with the prefix `[MEETING — <botId>]:` (every ~30 seconds while a Recall.ai meeting bot is active). Also use this skill when the orchestrating system injects `[SYSTEM] You are now in a meeting ...`.
+Two trigger patterns:
 
-**Do NOT use this skill** for normal user messages in the voice-native chat — those still get spoken responses as usual.
+**1. Auto-tagged meeting transcript chunks** (every ~30s while a Recall bot is active):
+   Any user message that starts with `[MEETING — <botId>]:`. Also a `[SYSTEM] You are now in a meeting ...` injection on bot join.
 
-## How to behave
+**2. Explicit user request to pull / write notes** (any of these keyphrases in voice-native chat):
+   - "grab the meeting transcripts"
+   - "pull the meeting transcripts"
+   - "fetch the meeting transcripts"
+   - "what was said in the meeting"
+   - "update the meeting notes"
+   - "compile the todos"
+   - "write the todos"
+   - "summarize the meeting"
+
+**Do NOT use this skill** for normal user voice-native messages that don't fit those patterns — those get spoken responses as usual.
+
+## How to behave (auto-tagged chunks)
 
 For every `[MEETING — *]:` message:
 
-1. **Do NOT speak.** No TTS output. No `tts_say`. No conversational reply. This is a silent observer path. If you must acknowledge that you processed the message, do it via a Write/Edit tool call (writing to the workspace), not via spoken or chat output.
-2. **Update `meeting-todos.md`** in the session workspace (`{workspace}/meeting-todos.md`). Append new action items, decisions, and open questions as they emerge in the transcript. Do not rewrite existing entries unless something contradicts.
-3. **Optionally trigger background research silently.** If a topic in the meeting would benefit from a quick web/code lookup, dispatch a researcher sub-agent via the Task tool. Save its output to `{workspace}/library/meeting-research-<topic-slug>.md`. Do NOT speak the result.
-4. **Do not consume voice-native attention.** The user can still talk to you via the voice-native browser. When they do (a normal user message with no `[MEETING — *]` prefix), respond normally — speak. Treat the meeting transcript as background context they can ask about ("what did Sarah say about pricing?" → answer normally).
+1. **Do NOT speak.** No TTS output. No conversational reply.
+2. **Update `meeting-todos.md`** in the session workspace. Append new action items, decisions, open questions. One file, evolving.
+3. **Optionally trigger background research silently** via Task tool.
+4. **Don't consume voice-native attention.** The user can interrupt with a voice-native message at any time — that's the only kind that gets spoken responses.
+
+## How to pull transcripts on demand (Bash + curl)
+
+When the user explicitly asks (see triggers above), run these commands. Speak briefly first ("On it"), do the work, then speak the result.
+
+### Step 1: Get the bot ID
+
+The bot ID is in `meeting-todos.md` on the `**Bot:**` line. If `meeting-todos.md` doesn't exist (user is asking about a meeting that already ended in a prior session), ask the user for the bot ID or meeting URL.
+
+### Step 2: Fetch the bot record
+
+```bash
+curl -sS \
+  -H "Authorization: Token ${RECALL_API_KEY}" \
+  "https://us-west-2.recall.ai/api/v1/bot/<BOT_ID>"
+```
+
+**CRITICAL**: The endpoint MUST be `us-west-2.recall.ai`, NOT the default `recall.ai` or `us-east-1.recall.ai`. The osborn account is provisioned in the us-west-2 region. Using the default endpoint returns 401 "OAuth authentication is currently not supported" or region-mismatch errors.
+
+`${RECALL_API_KEY}` is preset in the agent's env — pass it through. Do NOT echo or print the raw key value in your response.
+
+### Step 3: Extract the transcript download URL
+
+Parse the JSON response. The transcript's pre-signed S3 URL lives at:
+
+```
+recordings[0].media_shortcuts.transcript.data.download_url
+```
+
+Pipe through `jq` if needed:
+
+```bash
+DOWNLOAD_URL=$(curl -sS \
+  -H "Authorization: Token ${RECALL_API_KEY}" \
+  "https://us-west-2.recall.ai/api/v1/bot/<BOT_ID>" \
+  | jq -r '.recordings[0].media_shortcuts.transcript.data.download_url')
+```
+
+If `recordings[0]` doesn't exist yet, the meeting hasn't been processed — return "the recording isn't ready yet, give it a minute" and stop.
+
+### Step 4: Download the transcript JSON
+
+```bash
+curl -sS "$DOWNLOAD_URL" -o /tmp/meeting-transcript.json
+```
+
+The download URL is a pre-signed S3 link that **expires** (typically ~6 hours after issue). If you get a 403 or AccessDenied, re-fetch the bot record (step 2) to get a fresh URL.
+
+### Step 5: Parse and distill into meeting-todos.md
+
+The transcript JSON is an array of turns. Each turn has `participant.name` and `words[]` (each word has `text` + `start_timestamp.relative`). Concatenate words per turn to get the utterance.
+
+Use `jq` to pull turns into readable lines:
+
+```bash
+jq -r '.[] | "\(.participant.name // "Unknown"): \(.words | map(.text) | join(" "))"' /tmp/meeting-transcript.json
+```
+
+Then update `meeting-todos.md` — distill into TODOs / Decisions / Open Questions sections. Don't paste the whole transcript verbatim into the file; summarize.
 
 ## The `meeting-todos.md` file
 
+Path: `{session_workspace}/meeting-todos.md` — get the workspace path from spec.md or from the `[SYSTEM]` injection.
+
 Keep it scannable. Structure:
 
 ```markdown
 # Meeting Notes
 
-**Bot:** <botId> · **Started:** <ISO timestamp>
+**Bot:** <botId>
+**Started:** <ISO timestamp>
+**URL:** <meeting URL>
 
-## TODOs
+## Summary
+<3-5 sentences distilling the meeting after it ends — added LAST>
 
+## TODOs
 - [ ] <person>: <action item> — <context>
-- [ ] <person>: <action item>
 
 ## Decisions
-
-- <date/time> — <what was decided> (raised by <person>)
+- <what was decided> (raised by <person>)
 
 ## Open Questions
-
 - <question> — raised by <person>, still unresolved
-- <question> — answered by <person>: <answer>
 
 ## Highlights
-
 - <key moment or quote worth surfacing>
 ```
 
-Update the same file across multiple poll cycles — don't create `meeting-todos-1.md`, `meeting-todos-2.md`. One file, evolving.
-
-## Workspace path
-
-The session workspace is `~/.claude/projects/<slug>/osb/<session-uuid>/`. Read the env variable or the spec.md header if you need to confirm the exact path. Write absolute paths in tool calls (e.g. `/Users/<user>/.claude/projects/.../osb/<uuid>/meeting-todos.md`).
+Update the same file across all updates — one file, evolving. Don't create `meeting-todos-1.md`, `meeting-todos-2.md`.
 
 ## On meeting end
 
-When the user leaves the meeting (the system stops sending `[MEETING — *]:` messages and may inject `[SYSTEM] meeting ended`), do a final pass on `meeting-todos.md` to:
-- Mark items the user has clearly committed to
-- Move resolved open questions to a `## Resolved` section
-- Add a `## Summary` section at the top with 3-5 lines distilling the meeting
-
-Still silent. The user will ask out loud if they want a recap.
+When `[MEETING — *]:` messages stop OR the system says `[SYSTEM] meeting ended`:
+- Pull the full final transcript (step 2-4 above)
+- Add a `## Summary` section at the top with 3-5 lines
+- Mark resolved open questions
+- The next user voice-native question may be "what was the meeting about?" — answer normally (speak) from the updated file
 
-## When the user asks about the meeting
+## When the user asks about the meeting in voice-native
 
-When a non-meeting-tagged message references the meeting ("what's on the todo list?", "what did we decide about X?", "who's handling Y?"), respond normally — speak. Read `meeting-todos.md` first to ground the response. Don't make up speaker names or decisions; only state what's recorded.
+When a non-meeting-tagged voice message references the meeting ("what's on the todo list?", "what did we decide about X?"), respond normally — **speak** the answer. Read `meeting-todos.md` first to ground the response. If `meeting-todos.md` is empty or missing relevant detail, pull a fresh transcript first (steps 2-4) and update the file, then answer.
 
 ## Anti-patterns
 
-- ❌ Speaking in response to a `[MEETING — *]:` message
-- ❌ Creating a new file per poll cycle instead of updating one
-- ❌ Trying to drive the meeting (don't add "we should..." items unless someone in the meeting said them)
-- ❌ Asking the user clarifying questions during the meeting — they're not paying attention to chat
-- ❌ Re-transcribing what's in the message into the TODO file verbatim. Distill.
+- ❌ Using `recall.ai` or `us-east-1.recall.ai` — always `us-west-2.recall.ai`
+- ❌ Using `WebFetch` for the S3 download URL — use `curl` via `Bash` (the URL has weird chars + pre-signed query strings that confuse WebFetch)
+- ❌ Pasting the full raw transcript into `meeting-todos.md`
+- ❌ Speaking in response to `[MEETING — *]:` messages
+- ❌ Asking clarifying questions during a live meeting
+- ❌ Creating a new file per pull instead of updating one
+- ❌ Re-pulling the bot record over and over inside one user turn — fetch once, parse once
+- ❌ Echoing or printing `${RECALL_API_KEY}` value in your response

package/dist/index.js

@@ -147,6 +147,24 @@ process.on('uncaughtException', (error) => {
 // ============================================================
 // Module-level room code so the HTTP server can expose it via GET /room-code
 let currentRoomCode = null;
+// Module-level LiveKit connection state. Shared between main() (which runs the
+// connect-with-retry loop) and the /health handler in startApiServer (which
+// reports it to the frontend so the user sees a meaningful error instead of a
+// dashboard redirect when LiveKit is unreachable / out of quota / etc).
+//
+// We deliberately do NOT 503 /health on connect failure — Fly's machine
+// health-check uses /health, and returning non-2xx triggers a restart loop
+// which (a) burns the same failing LiveKit calls every 30s and (b) gets the
+// machine killed after 3 failed restarts. By staying 200 OK and surfacing the
+// status as a field, we keep the container alive long enough for LiveKit to
+// recover (auto-retry) or for the user to read the error and upgrade quota.
+const livekitState = {
+    status: 'connecting',
+    error: null,
+    errorCode: null,
+    lastAttemptAt: null,
+    attemptCount: 0,
+};
 function startApiServer(workingDir, port) {
     const server = createServer(async (req, res) => {
         // CORS headers for cloud frontend
@@ -221,7 +239,22 @@ function startApiServer(workingDir, port) {
             }
             catch { /* version optional */ }
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ status: 'ok', workingDir, version }));
+            res.end(JSON.stringify({
+                status: 'ok',
+                workingDir,
+                version,
+                // LiveKit subsystem status — frontend can use this to surface a real
+                // error instead of treating the sandbox as totally broken. The HTTP
+                // status code stays 200 so Fly health-check stays green and the
+                // container isn't restart-looped while LiveKit is unreachable.
+                livekit: {
+                    status: livekitState.status,
+                    error: livekitState.error,
+                    errorCode: livekitState.errorCode,
+                    attemptCount: livekitState.attemptCount,
+                    lastAttemptAt: livekitState.lastAttemptAt,
+                },
+            }));
             return;
         }
         // POST /webhook/recall — Recall.ai real-time transcript webhooks
@@ -3931,22 +3964,87 @@ async function main() {
     // ============================================================
     // Connect to Room
     // ============================================================
-    try {
-        await room.connect(livekitUrl, jwt, {
-            autoSubscribe: true,
-            dynacast: true,
-        });
-        localParticipant = room.localParticipant;
-        console.log('✅ Connected to room:', roomName);
-        console.log('\n⏳ Waiting for user to connect...');
-        console.log(`   Room: ${roomCode}\n`);
-        // Keep process alive
-        await new Promise(() => { });
-    }
-    catch (err) {
-        console.error('❌ Failed to connect:', err);
-        process.exit(1);
-    }
+    // Connect to LiveKit with retry-on-failure.
+    //
+    // Earlier behavior: a single attempt followed by `process.exit(1)` on error.
+    // Combined with Fly's restart policy this produced a tight restart loop that
+    // (a) hit the same 429 / auth error every ~30s, (b) burned the LiveKit
+    // quota's retry budget, and (c) hit Fly's max-restart-count (3) and killed
+    // the machine — at which point the frontend's /api/sandbox probe saw the
+    // sandbox as failed and bounced the user back to the dashboard with no
+    // useful error.
+    //
+    // New behavior: bounded-backoff retry, infinite attempts. The API server
+    // stays up the whole time serving /health (which surfaces the LiveKit error
+    // as a field, NOT as an HTTP failure — see the /health handler comment).
+    // When the underlying issue is resolved (quota reset, key fixed, LiveKit
+    // service back), the next retry succeeds and the agent picks up where it
+    // left off without anyone needing to manually restart.
+    //
+    // Backoff: 5s → 10s → 20s → 40s → 60s (capped). Resets to 5s after each
+    // successful connect (so a single transient hiccup doesn't disable fast
+    // recovery on the next disconnect).
+    const connectWithRetry = async () => {
+        const backoffSchedule = [5_000, 10_000, 20_000, 40_000, 60_000];
+        let backoffIdx = 0;
+        while (true) {
+            livekitState.status = livekitState.attemptCount === 0 ? 'connecting' : 'retrying';
+            livekitState.lastAttemptAt = Date.now();
+            livekitState.attemptCount += 1;
+            try {
+                await room.connect(livekitUrl, jwt, {
+                    autoSubscribe: true,
+                    dynacast: true,
+                });
+                localParticipant = room.localParticipant;
+                livekitState.status = 'connected';
+                livekitState.error = null;
+                livekitState.errorCode = null;
+                backoffIdx = 0;
+                console.log('✅ Connected to room:', roomName);
+                console.log('\n⏳ Waiting for user to connect...');
+                console.log(`   Room: ${roomCode}\n`);
+                return;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // Categorize the error so the frontend can show specific guidance.
+                // Substring matching on the message because LiveKit's rtc-node SDK
+                // wraps the underlying HTTP status in a generic ConnectError.
+                let errorCode;
+                if (/429|connection minutes limit/i.test(msg))
+                    errorCode = 'quota_exceeded';
+                else if (/401|403|unauthorized|invalid/i.test(msg))
+                    errorCode = 'auth';
+                else if (/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network/i.test(msg))
+                    errorCode = 'network';
+                else
+                    errorCode = 'unknown';
+                livekitState.status = 'failed';
+                livekitState.error = msg;
+                livekitState.errorCode = errorCode;
+                const waitMs = backoffSchedule[Math.min(backoffIdx, backoffSchedule.length - 1)];
+                backoffIdx += 1;
+                console.error(`❌ LiveKit connect failed (${errorCode}, attempt ${livekitState.attemptCount}): ${msg.substring(0, 200)}`);
+                console.error(`   Retrying in ${waitMs / 1000}s — process staying alive; /health remains 200 with livekit.status='failed'`);
+                await new Promise(r => setTimeout(r, waitMs));
+                // loop — try again
+            }
+        }
+    };
+    // Fire and forget; the retry loop keeps the process alive on its own (so
+    // we don't need the explicit `new Promise(() => {})` keepalive anymore).
+    // Errors that escape the retry loop should never happen, but if they do,
+    // log them rather than crash.
+    connectWithRetry().catch(err => {
+        console.error('❌ Unrecoverable error in LiveKit retry loop (should not happen):', err);
+        livekitState.status = 'failed';
+        livekitState.error = err instanceof Error ? err.message : String(err);
+        livekitState.errorCode = 'unrecoverable';
+    });
+    // Keep main() alive forever — without this the await chain ends and Node
+    // exits 0, which Fly treats as a clean shutdown.
+    await new Promise(() => { });
 }
 // Run
 main().catch(console.error);

package/dist/recall-client.d.ts

@@ -84,20 +84,21 @@ export declare class RecallClient extends EventEmitter {
     }): Promise<string>;
     /**
      * Fetch the bot's current transcript. Returns an array of "transcript turns"
-     * (each turn = one speaker's utterance) sorted by start time. Use the bot's
-     * `recordings[0].id` from getBotStatus / bot record to locate the recording,
-     * then list its transcripts.
+     * (each turn = one speaker's utterance) sorted by start time.
      *
-     * Per Recall docs:
-     *   GET /api/v1/bot/{bot_id} → bot record incl. `recordings: [...]`
-     *   GET /api/v1/transcript/{transcript_id} → transcript with download_url
-     *   Download the transcript JSON from download_url to get the actual content.
+     * Verified 2026-05-22 against the real us-west-2 API: there is NO simple
+     * `GET /bot/{id}/transcript` convenience endpoint. The actual chain is:
      *
-     * For the polling use case (called every ~30s), we use the simpler combined
-     * endpoint: `GET /api/v1/bot/{bot_id}/transcript` which Recall exposes as a
-     * convenience and returns the full transcript so far in one call. The caller
-     * is responsible for de-duping (keeping a since-cursor) so the LLM only sees
-     * new turns.
+     *   1. GET /api/v1/bot/{bot_id}
+     *   2. recordings[0].media_shortcuts.transcript.data.download_url   (S3 signed URL)
+     *   3. GET that URL  →  JSON array of TranscriptTurn objects
+     *
+     * The S3 URL is pre-signed and expires (~6h). Re-fetch step 1 each poll;
+     * don't cache the URL.
+     *
+     * If `recordings[0]` doesn't exist yet (bot still joining or pre-recording),
+     * returns []. Caller (MeetingTranscriptPoller) treats that as "no new turns
+     * yet" and waits for the next tick.
      */
     getTranscript(botId: string): Promise<TranscriptTurn[]>;
     leaveMeeting(botId: string): Promise<void>;

package/dist/recall-client.js

@@ -66,30 +66,43 @@ export class RecallClient extends EventEmitter {
     }
     /**
      * Fetch the bot's current transcript. Returns an array of "transcript turns"
-     * (each turn = one speaker's utterance) sorted by start time. Use the bot's
-     * `recordings[0].id` from getBotStatus / bot record to locate the recording,
-     * then list its transcripts.
+     * (each turn = one speaker's utterance) sorted by start time.
      *
-     * Per Recall docs:
-     *   GET /api/v1/bot/{bot_id} → bot record incl. `recordings: [...]`
-     *   GET /api/v1/transcript/{transcript_id} → transcript with download_url
-     *   Download the transcript JSON from download_url to get the actual content.
+     * Verified 2026-05-22 against the real us-west-2 API: there is NO simple
+     * `GET /bot/{id}/transcript` convenience endpoint. The actual chain is:
      *
-     * For the polling use case (called every ~30s), we use the simpler combined
-     * endpoint: `GET /api/v1/bot/{bot_id}/transcript` which Recall exposes as a
-     * convenience and returns the full transcript so far in one call. The caller
-     * is responsible for de-duping (keeping a since-cursor) so the LLM only sees
-     * new turns.
+     *   1. GET /api/v1/bot/{bot_id}
+     *   2. recordings[0].media_shortcuts.transcript.data.download_url   (S3 signed URL)
+     *   3. GET that URL  →  JSON array of TranscriptTurn objects
+     *
+     * The S3 URL is pre-signed and expires (~6h). Re-fetch step 1 each poll;
+     * don't cache the URL.
+     *
+     * If `recordings[0]` doesn't exist yet (bot still joining or pre-recording),
+     * returns []. Caller (MeetingTranscriptPoller) treats that as "no new turns
+     * yet" and waits for the next tick.
      */
     async getTranscript(botId) {
-        const res = await fetch(`${RECALL_BASE_URL}/bot/${botId}/transcript`, {
+        const botRes = await fetch(`${RECALL_BASE_URL}/bot/${botId}`, {
             headers: { 'Authorization': `Token ${this.#apiKey}` },
         });
-        if (!res.ok) {
-            const err = await res.text().catch(() => '');
-            throw new Error(`Recall.ai transcript fetch failed: ${res.status} ${err.substring(0, 200)}`);
+        if (!botRes.ok) {
+            const err = await botRes.text().catch(() => '');
+            throw new Error(`Recall.ai bot fetch failed: ${botRes.status} ${err.substring(0, 200)}`);
+        }
+        const bot = await botRes.json();
+        const downloadUrl = bot.recordings?.[0]?.media_shortcuts?.transcript?.data?.download_url;
+        if (!downloadUrl) {
+            // Recording / transcript not ready yet — pre-call, just-joined, or
+            // recording_done event hasn't fired. Empty result is expected here.
+            return [];
+        }
+        const txRes = await fetch(downloadUrl);
+        if (!txRes.ok) {
+            const err = await txRes.text().catch(() => '');
+            throw new Error(`Recall.ai transcript download failed: ${txRes.status} ${err.substring(0, 200)}`);
         }
-        const turns = await res.json();
+        const turns = await txRes.json();
         return Array.isArray(turns) ? turns : [];
     }
     async leaveMeeting(botId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osborn",
-  "version": "0.9.43",
+  "version": "0.9.45",
   "description": "Voice AI coding assistant - local agent that connects to Osborn frontend",
   "type": "module",
   "bin": {