osborn 0.5.3 → 0.8.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ps:*)",
+      "Bash(osascript:*)",
+      "Bash(curl -s http://localhost:3000)"
+    ]
+  }
+}

package/.claude/skills/markdown-to-pdf/SKILL.md

@@ -0,0 +1,29 @@
+# Skill: Markdown to PDF
+
+Export Markdown documents as formatted PDF files.
+
+## When to use
+When the user wants to create a PDF from a Markdown file, spec, or research findings.
+
+## How to execute
+
+Option 1 — Using md-to-pdf (best quality):
+```bash
+npx --yes md-to-pdf "<MARKDOWN_PATH>"
+```
+This creates a PDF alongside the source file with the same name.
+
+Option 2 — Using pandoc (if available):
+```bash
+pandoc "<MARKDOWN_PATH>" -o "<OUTPUT_PATH>.pdf" --pdf-engine=wkhtmltopdf
+```
+
+Option 3 — Using markdown-pdf:
+```bash
+npx --yes markdown-pdf "<MARKDOWN_PATH>" -o "<OUTPUT_PATH>.pdf"
+```
+
+## Output
+- Save the PDF to the session workspace (e.g., `library/{name}.pdf`)
+- Confirm the output path and file size to the user
+- If the source is spec.md, name the output `spec-export.pdf`

package/.claude/skills/pdf-to-markdown/SKILL.md

@@ -0,0 +1,28 @@
+# Skill: PDF to Markdown
+
+Convert PDF documents to readable Markdown text.
+
+## When to use
+When the user provides a PDF file path and wants to read, search, or work with its contents.
+
+## How to execute
+
+Option 1 — Using the built-in Read tool:
+The Read tool can directly read PDF files. Use `pages` parameter for large PDFs (max 20 pages per request).
+
+Option 2 — Full extraction via CLI (for better formatting or batch processing):
+```bash
+npx --yes pdf-parse-cli "<PDF_PATH>"
+```
+
+Option 3 — Using pdftotext (if available):
+```bash
+pdftotext -layout "<PDF_PATH>" -
+```
+
+## Output
+Save the converted content to the session workspace as `library/{filename}.md` with:
+- Document title and source path at the top
+- Preserved heading structure where detectable
+- Tables converted to Markdown tables where possible
+- Page numbers as section markers

package/.claude/skills/playwright-browser/SKILL.md

@@ -0,0 +1,90 @@
+# Skill: Playwright Browser Automation
+
+Automate web browser interactions — navigate pages, click buttons, fill forms, take screenshots, and extract content.
+
+## When to use
+- Navigate to a URL and interact with it
+- Click buttons or links by their text or role
+- Fill form fields and submit data
+- Take screenshots of web pages
+- Extract text or structured data from pages
+- Automate multi-step web workflows (e.g. join a room, test a UI flow)
+
+## How to execute
+
+Uses `@playwright/cli` via npx — no global install needed. Token-efficient: uses element references (e.g. `e15`) instead of pixel coordinates.
+
+### First time only — install browser binaries
+```bash
+npx playwright install chromium
+```
+
+### Step 1 — Open a URL
+```bash
+npx @playwright/cli open https://localhost:3000
+```
+
+### Step 2 — Get page structure and element references
+```bash
+npx @playwright/cli snapshot
+```
+Returns an accessibility tree with element IDs like e1, e2, e15. Use these in subsequent commands.
+
+### Step 3 — Interact with elements
+```bash
+npx @playwright/cli click e15
+npx @playwright/cli fill e3 "some text"
+npx @playwright/cli press e3 Enter
+npx @playwright/cli select e7 "optionValue"
+npx @playwright/cli check e9
+npx @playwright/cli hover e12
+```
+
+### Take a screenshot
+```bash
+npx @playwright/cli screenshot --path=/tmp/page.png
+```
+
+### Take a screenshot at a specific viewport size (mobile check)
+```bash
+npx @playwright/cli screenshot --viewport-size=375,812 --path=/tmp/page-mobile.png
+```
+Common mobile sizes: `375,812` (iPhone 14), `390,844` (iPhone 14 Pro), `412,915` (Pixel 7), `768,1024` (iPad).
+
+### Close the browser
+```bash
+npx @playwright/cli close
+```
+
+### Named sessions (persistent state across commands)
+```bash
+npx @playwright/cli -s=myflow open https://localhost:3000
+npx @playwright/cli -s=myflow snapshot
+npx @playwright/cli -s=myflow fill e3 "abc123"
+npx @playwright/cli -s=myflow click e5
+npx @playwright/cli -s=myflow close
+```
+
+## Complete example — join Osborn voice room
+```bash
+npx @playwright/cli open http://localhost:3000
+npx @playwright/cli snapshot
+npx @playwright/cli fill e3 "abc123"
+npx @playwright/cli click e4
+npx @playwright/cli screenshot --path=/tmp/osborn-joined.png
+npx @playwright/cli close
+```
+
+## Complete example — check mobile layout
+```bash
+npx @playwright/cli open http://localhost:3000
+npx @playwright/cli screenshot --viewport-size=375,812 --path=/tmp/mobile-375.png
+npx @playwright/cli close
+```
+
+## Notes
+- Runs headless by default. Add --headed to see the browser window.
+- Install browsers first if needed: npx playwright install chromium
+- Element IDs are session-scoped — run snapshot again after page changes
+- Use `--viewport-size=WIDTH,HEIGHT` to simulate mobile screen sizes (e.g. `375,812` for iPhone 14)
+- Use `--storage-state=/tmp/state.json` to save and restore session state (cookies, localStorage) across runs

package/.claude/skills/shadcn/SKILL.md

@@ -0,0 +1,232 @@
+# Skill: shadcn/ui Components
+
+Add and configure shadcn/ui components in a Next.js or React project.
+
+## When to use
+When the user wants to add UI components (buttons, dialogs, cards, forms, tables, etc.) using shadcn/ui — the copy-paste component library built on Radix UI and Tailwind CSS.
+
+## Setup (first time only)
+
+Initialize shadcn in the project root (where package.json lives):
+```bash
+npx shadcn@latest init
+```
+
+This creates `components.json` and sets up `src/components/ui/`. Answer the prompts to match your project's style preferences.
+
+## Add a component
+
+```bash
+npx shadcn@latest add <component-name>
+```
+
+## Add multiple components at once
+```bash
+npx shadcn@latest add button card dialog input form
+```
+
+## Commonly used components
+
+| Component | Install name | Description |
+|-----------|-------------|-------------|
+| Button | `button` | Clickable button with variants |
+| Card | `card` | Container with header/content/footer |
+| Input | `input` | Text input field |
+| Label | `label` | Form label |
+| Textarea | `textarea` | Multi-line text input |
+| Select | `select` | Dropdown select |
+| Checkbox | `checkbox` | Checkbox with label |
+| Switch | `switch` | Toggle switch |
+| Dialog | `dialog` | Modal dialog |
+| Sheet | `sheet` | Slide-in panel (drawer) |
+| Popover | `popover` | Floating content panel |
+| Tooltip | `tooltip` | Hover tooltip |
+| Dropdown Menu | `dropdown-menu` | Contextual dropdown |
+| Command | `command` | Command palette / search |
+| Badge | `badge` | Small status indicator |
+| Avatar | `avatar` | User avatar with fallback |
+| Separator | `separator` | Visual divider |
+| Table | `table` | Data table |
+| Tabs | `tabs` | Tabbed interface |
+| Accordion | `accordion` | Collapsible sections |
+| Sonner | `sonner` | Toast notifications (preferred over toast) |
+| Alert | `alert` | Inline alert message |
+| Alert Dialog | `alert-dialog` | Confirmation dialog |
+| Progress | `progress` | Progress bar |
+| Skeleton | `skeleton` | Loading placeholder |
+| Scroll Area | `scroll-area` | Custom scrollbar container |
+| Calendar | `calendar` | Date picker calendar |
+| Form | `form` | React Hook Form integration |
+| Slider | `slider` | Range slider |
+| Toggle | `toggle` | Toggle button |
+| Navigation Menu | `navigation-menu` | Site navigation |
+| Breadcrumb | `breadcrumb` | Page navigation breadcrumbs |
+| Collapsible | `collapsible` | Expandable/collapsible section |
+| Context Menu | `context-menu` | Right-click context menu |
+| Menubar | `menubar` | Application menu bar |
+| Resizable | `resizable` | Resizable panel groups |
+
+## Import pattern
+
+```tsx
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardHeader, CardTitle, CardDescription, CardFooter } from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog"
+```
+
+## Example — Button variants
+
+```tsx
+<Button>Default</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Cancel</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="link">Link</Button>
+<Button size="sm">Small</Button>
+<Button size="lg">Large</Button>
+<Button disabled>Disabled</Button>
+```
+
+## Example — Card
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description goes here</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card content here</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+## Example — Form with validation (React Hook Form + Zod)
+
+```bash
+npx shadcn@latest add form input
+npm install zod react-hook-form @hookform/resolvers
+```
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import * as z from "zod"
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
+import { Input } from "@/components/ui/input"
+import { Button } from "@/components/ui/button"
+
+const formSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+})
+
+export function LoginForm() {
+  const form = useForm<z.infer<typeof formSchema>>({
+    resolver: zodResolver(formSchema),
+    defaultValues: { email: "", password: "" },
+  })
+
+  function onSubmit(values: z.infer<typeof formSchema>) {
+    console.log(values)
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input placeholder="you@example.com" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="password"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Password</FormLabel>
+              <FormControl>
+                <Input type="password" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit" className="w-full">Sign in</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+## Example — Toast notifications (Sonner)
+
+```bash
+npx shadcn@latest add sonner
+```
+
+```tsx
+// In your root layout — add the Toaster once
+import { Toaster } from "@/components/ui/sonner"
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
+  )
+}
+
+// Then anywhere in your app
+import { toast } from "sonner"
+
+toast("Event created")
+toast.success("Profile saved")
+toast.error("Something went wrong")
+toast.promise(saveData(), {
+  loading: "Saving...",
+  success: "Saved!",
+  error: "Failed to save",
+})
+```
+
+## The cn() utility
+
+shadcn uses `clsx` + `tailwind-merge` via a `cn()` helper for conditional classes:
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("base-class", isActive && "active-class", className)} />
+```
+
+## Notes
+- Components are **copied into your project** (not a node_modules dependency) — edit them freely
+- Requires **Tailwind CSS** configured in the project
+- Uses **Radix UI** primitives for accessibility
+- Components land in `src/components/ui/` by default
+- Run `npx shadcn@latest diff` to see if upstream components have changed
+- Check `components.json` for path and style config
+- Use Sonner (`sonner`) instead of the legacy `toast` component for notifications

package/.claude/skills/youtube-transcript/SKILL.md

@@ -0,0 +1,24 @@
+# Skill: YouTube Transcript
+
+Fetch and save transcripts from YouTube videos.
+
+## When to use
+When the user asks to get a transcript, subtitles, captions, or summary from a YouTube video URL.
+
+## How to execute
+
+yt-dlp is installed on this system. Use this exact command:
+
+```bash
+yt-dlp --skip-download --write-auto-sub --sub-lang en --convert-subs srt -o "/tmp/yt-%(id)s" "<VIDEO_URL>"
+```
+
+This downloads auto-generated English subtitles as an SRT file to /tmp/yt-{video-id}.en.srt
+
+Then read the SRT file and strip the timing markers to get clean transcript text.
+
+## Output
+Save the cleaned transcript to the session workspace as `library/youtube-{video-id}-transcript.md` with:
+- Video title and URL at the top
+- Cleaned transcript text (strip SRT timing markers and duplicate lines)
+- Key timestamps preserved as section markers if meaningful breaks exist

package/.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+.osborn
+.env
+.env.*
+*.log
+.git
+.playwright-cli
+
+# Exclude sensitive Claude config but keep skills (shipped as defaults)
+.claude/settings*
+.claude/projects
+.claude/credentials*

package/Dockerfile

@@ -0,0 +1,103 @@
+# syntax = docker/dockerfile:1
+#
+# Osborn Agent — Fly.io Deployment
+# Self-hosted voice AI research assistant with Claude Code CLI
+#
+# Build:  fly deploy
+# Local:  docker build -t osborn-agent . && docker run -p 8741:8741 --env-file .env osborn-agent
+
+ARG NODE_VERSION=20
+FROM node:${NODE_VERSION}-slim AS base
+WORKDIR /app
+ENV NODE_ENV=production
+
+# ── Build stage: native deps (node-pty, ripgrep) ──
+FROM base AS build
+
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y \
+    build-essential \
+    python-is-python3 \
+    pkg-config \
+    curl \
+    git && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+
+# ── Final stage: lean runtime ──
+FROM base
+
+# Runtime deps: python for node-pty, git for Claude Code, curl for health checks,
+# ca-certificates for HTTPS (LiveKit, Deepgram, Anthropic API connections)
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y \
+    python-is-python3 \
+    ca-certificates \
+    curl \
+    git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Claude Code CLI — installed globally so it's on PATH for the agent SDK
+RUN npm install -g @anthropic-ai/claude-code
+
+# Playwright Chromium browser for browser automation skill
+RUN npx playwright install chromium --with-deps 2>/dev/null || true
+
+# Copy built app from build stage
+COPY --from=build /app /app
+
+# Persistent workspace volume mount point (Fly.io mounts here)
+RUN mkdir -p /workspace
+
+# Config
+ENV HOST=0.0.0.0
+ENV PORT=8741
+ENV OSBORN_CWD=/workspace
+
+EXPOSE 8741
+
+# Entrypoint script: sets up Claude credential symlinks, onboarding bypass, then starts agent
+COPY <<'ENTRYPOINT' /entrypoint.sh
+#!/bin/sh
+set -e
+
+# ── Claude credential persistence ──
+# /workspace is the Fly.io persistent volume. Credentials survive deploys/restarts.
+# Remove any stale symlink or directory, then create fresh symlink.
+mkdir -p /workspace/.claude
+rm -rf /root/.claude
+ln -sf /workspace/.claude /root/.claude
+
+# ── Claude onboarding suppression (learned from claudebox) ──
+# Claude Code shows 5+ interactive prompts on first run. Pre-write config to skip all of them.
+# Must write to ALL THREE config paths (different CLI versions check different files).
+ONBOARDING_JSON='{"numStartups":10,"installMethod":"npm","autoUpdates":false,"hasCompletedOnboarding":true,"hasTrustDialogAccepted":true,"hasTrustDialogHooksAccepted":true,"hasCompletedProjectOnboarding":true,"hasAcknowledgedCostThreshold":true,"effortCalloutV2Dismissed":true,"theme":"dark","projects":{"/workspace":{"hasTrustDialogAccepted":true,"hasTrustDialogHooksAccepted":true,"hasCompletedProjectOnboarding":true}}}'
+
+echo "$ONBOARDING_JSON" > /root/.claude.json
+mkdir -p /workspace/.claude
+echo "$ONBOARDING_JSON" > /workspace/.claude/.config.json
+echo "$ONBOARDING_JSON" > /workspace/.claude/claude.json
+
+# ── Session workspace persistence ──
+# Session workspace (.osborn/sessions/) defaults to sessionBaseDir (/app).
+# Symlink to volume so spec.md, library/ files survive deploys.
+mkdir -p /workspace/.osborn
+rm -rf /app/.osborn
+ln -sf /workspace/.osborn /app/.osborn
+
+# ── Restore CLAUDE_CODE_OAUTH_TOKEN from persisted volume ──
+if [ -f /workspace/.claude/.oauth-token ]; then
+  export CLAUDE_CODE_OAUTH_TOKEN="$(cat /workspace/.claude/.oauth-token)"
+  echo "✅ Restored CLAUDE_CODE_OAUTH_TOKEN from volume"
+fi
+
+# ── Start Osborn agent ──
+exec node --import tsx/esm src/index.ts
+ENTRYPOINT
+RUN chmod +x /entrypoint.sh
+
+CMD ["/entrypoint.sh"]

package/deploy.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Osborn — Fly.io Deploy Script
+# Usage: ./deploy.sh <app-name> [region]
+# Example: ./deploy.sh osborn-agent-john iad
+#
+# Prerequisites:
+#   1. flyctl installed (curl -L https://fly.io/install.sh | sh)
+#   2. fly auth login
+#   3. API keys ready (LIVEKIT, ANTHROPIC, GOOGLE, DEEPGRAM)
+
+set -e
+
+APP_NAME=${1:-"osborn-agent"}
+REGION=${2:-"iad"}
+
+echo "🚀 Deploying Osborn to Fly.io as: $APP_NAME (region: $REGION)"
+echo ""
+
+# 1. Create app (no deploy yet)
+echo "📦 Creating Fly app..."
+fly launch --name "$APP_NAME" --region "$REGION" --no-deploy --yes
+
+# 2. Create persistent workspace volume
+echo "💾 Creating persistent volume (5GB)..."
+fly volumes create workspace --size 5 --region "$REGION" --app "$APP_NAME" --yes
+
+# 3. Set secrets
+echo ""
+echo "🔑 Setting API keys..."
+echo "   Required: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET"
+echo "   Required: DEEPGRAM_API_KEY"
+echo "   Optional: ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY"
+echo ""
+
+if [ -z "$LIVEKIT_URL" ]; then
+  echo "⚠️  Set environment variables before running, or pass them inline:"
+  echo "   LIVEKIT_URL=wss://... LIVEKIT_API_KEY=... ./deploy.sh $APP_NAME"
+  echo ""
+  echo "   Or set them manually after deploy:"
+  echo "   fly secrets set LIVEKIT_URL=wss://... --app $APP_NAME"
+  echo ""
+else
+  fly secrets set \
+    LIVEKIT_URL="$LIVEKIT_URL" \
+    LIVEKIT_API_KEY="$LIVEKIT_API_KEY" \
+    LIVEKIT_API_SECRET="$LIVEKIT_API_SECRET" \
+    DEEPGRAM_API_KEY="$DEEPGRAM_API_KEY" \
+    ${ANTHROPIC_API_KEY:+ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"} \
+    ${GOOGLE_API_KEY:+GOOGLE_API_KEY="$GOOGLE_API_KEY"} \
+    ${OPENAI_API_KEY:+OPENAI_API_KEY="$OPENAI_API_KEY"} \
+    --app "$APP_NAME"
+fi
+
+# 4. Deploy
+echo ""
+echo "🏗️  Building and deploying..."
+fly deploy --app "$APP_NAME"
+
+echo ""
+echo "✅ Deployed! Your Osborn agent is live at: https://$APP_NAME.fly.dev"
+echo ""
+echo "Next steps:"
+echo "  1. Open https://osborn.app"
+echo "  2. Enter the room code shown in: fly logs --app $APP_NAME"
+echo "  3. On first connect, authenticate Claude via the login link"
+echo ""
+echo "Useful commands:"
+echo "  fly logs --app $APP_NAME          # Watch agent logs"
+echo "  fly ssh console --app $APP_NAME   # SSH into the container"
+echo "  fly secrets set KEY=val --app $APP_NAME  # Add/update secrets"

package/dist/claude-auth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * claude-auth.ts — Claude Code CLI OAuth flow
+ *
+ * Handles authentication for Claude Code in headless/cloud environments.
+ * Learned from claudebox (etokarev/claude-code-docker, vutran1710/claudebox).
+ *
+ * Auth priority:
+ *   1. CLAUDE_CODE_OAUTH_TOKEN env var (set via `claude setup-token` on local machine)
+ *   2. ~/.claude/.credentials.json file (persisted on Fly.io volume)
+ *   3. `claude auth status --json` CLI check
+ *   4. Interactive OAuth flow via `claude setup-token` + pty
+ *
+ * On Linux/Docker, credentials go to ~/.claude/.credentials.json (file-based, no keyring).
+ * The Fly.io volume at /workspace/.claude is symlinked to ~/.claude for persistence.
+ */
+export interface ClaudeAuthCallbacks {
+    onUrl: (url: string) => void;
+    onWaitingForCode: () => void;
+    onComplete: () => void;
+    onError: (message: string) => void;
+    onOutput?: (text: string) => void;
+}
+export interface ClaudeAuthHandle {
+    submitCode: (code: string) => void;
+}
+/**
+ * Check if credentials file exists with a valid access token.
+ * On Linux/Docker, Claude Code stores OAuth creds at ~/.claude/.credentials.json
+ */
+export declare function isClaudeAuthenticated(): boolean;
+/**
+ * Check auth via `claude auth status --json` (most reliable).
+ * Uses execSync to avoid node-pty PATH issues on macOS.
+ */
+export declare function checkClaudeAuthStatus(): Promise<boolean>;
+/**
+ * Run the Claude CLI OAuth flow via `claude setup-token` in a pseudo-terminal.
+ *
+ * setup-token provides the Ink UI with a "Paste code here if prompted >" input.
+ * Unlike `auth login` which ignores pty stdin, setup-token accepts typed input.
+ *
+ * Code is written in chunks to simulate real typing (Ink reads raw keypresses).
+ */
+export declare function runClaudeAuthFlow(callbacks: ClaudeAuthCallbacks): {
+    handle: ClaudeAuthHandle;
+    done: Promise<void>;
+};
+/**
+ * Ensure Claude is authenticated before proceeding.
+ *
+ * Check order:
+ *   1. CLAUDE_CODE_OAUTH_TOKEN env var
+ *   2. ~/.claude/.credentials.json file
+ *   3. `claude auth status --json`
+ *   4. Interactive OAuth flow (setup-token)
+ */
+export declare function ensureClaudeAuth(sendToFrontend: (type: string, payload: unknown) => void): Promise<{
+    submitCode?: (code: string) => void;
+    done?: Promise<void>;
+}>;