shraga 0.0.3 → 0.1.2

package/src/client/lib/slots.tsx

@@ -0,0 +1,79 @@
+import { createContext, useContext, type ReactNode } from 'react';
+
+/**
+ * Typed extension SLOTS: the seam between the core client and any add-on bundle.
+ *
+ * The core ships an empty slot set ({}), so no core component statically imports an add-on module —
+ * the built core bundle therefore contains zero add-on code. An add-on build fills these slots at its
+ * composition root.
+ *
+ * Slot arg types are intentionally minimal + local: never import an add-on type here, or the seam
+ * leaks back into the core. Loose shapes keep the contract stable while add-ons supply the real widgets.
+ */
+export interface ClientSlots {
+  /** MessageInput: extra controls rendered beside the input. Arg = an opaque per-pane handle. */
+  inputAdornments?: (ctx: unknown) => ReactNode;
+  /** ConfigPanel: extra settings sub-sections. Arg = { getToken, sessionId }. */
+  settingsSections?: (ctx: { getToken: () => Promise<string | null>; sessionId?: string }) => ReactNode;
+  /** ChatView: extra renderers appended to a tool block. Arg = { block (the tool_use), result (the
+   *  paired tool_result output, if any), screens }. An add-on can reconstruct a resource handle from
+   *  the result. Core interprets none of it. */
+  toolRenderers?: (ctx: { block: unknown; result?: unknown; screens?: Map<string, string[]> }) => ReactNode;
+  /** ChatView: renderer for a NON-CORE (extension) message block — any block whose `type` the core
+   *  doesn't recognize is handed here verbatim. Core renders such blocks as nothing on its own. */
+  extensionBlocks?: (ctx: { block: unknown; onImageClick?: (src: string) => void }) => ReactNode;
+  /** ConversationPane: a headless per-conversation controller, mounted with the pane and unmounted
+   *  with it (its own effects are the conversation lifecycle hook). It may register an opaque input
+   *  handle + per-send options, drive the composer, inject messages, and set status items — the seam
+   *  an add-on uses to bind per-conversation resources. Core ships none, so nothing extra runs. */
+  conversationController?: (ctx: ConversationControllerCtx) => ReactNode;
+  /** ChatView + ConversationPane: inline status chips for background items. Arg = the item list. */
+  statusChips?: (items: unknown[]) => ReactNode;
+  /** ChatView (question card): subscribe external interactions → selection. Returns a cleanup. */
+  onCardInteraction?: (api: {
+    id: string;
+    questions: { question: string }[];
+    onAnswers: (answers: Record<string, string | string[]>) => void;
+  }) => (() => void) | void;
+  /** Sidebar: extra footer content. */
+  sidebarExtras?: () => ReactNode;
+  /** LoginPage: extra pre-login content. */
+  loginExtras?: () => ReactNode;
+  /** App header: extra action buttons. */
+  headerActions?: () => ReactNode;
+}
+
+/**
+ * Context handed to a {@link ClientSlots.conversationController}. Every field is generic — the core
+ * never names what an add-on does with them. The add-on's controller renders as
+ * a headless component, so its React effects run for the pane's lifetime.
+ */
+export interface ConversationControllerCtx {
+  sessionId: string | undefined;
+  busy: boolean;
+  /** the shared agent socket (for add-on events that aren't in the core event union). */
+  socket: unknown;
+  getToken: () => Promise<string | null>;
+  /** register an opaque per-pane handle forwarded to {@link ClientSlots.inputAdornments}. */
+  setInputCtx: (handle: unknown) => void;
+  /** register a provider of opaque send options merged into every send from this pane (read at send
+   *  time). The core passes the bag straight to the server without interpreting it. */
+  setSendOptions: (get: (() => Record<string, unknown> | undefined) | undefined) => void;
+  /** set the composer text without stealing focus (e.g. live external transcription). */
+  setInputText: (text: string) => void;
+  /** send from this pane programmatically. `options` is the opaque server bag; `meta.echo === false`
+   *  suppresses the user bubble (an agent-first / synthetic opener). */
+  send: (text: string, options?: Record<string, unknown>, meta?: { echo?: boolean }) => void;
+  /** append an assistant message (core or extension blocks) to this pane's transcript. */
+  appendAssistant: (blocks: Array<{ type: string; [key: string]: unknown }>) => void;
+  /** replace this pane's live status items (rendered via {@link ClientSlots.statusChips}). */
+  setStatusItems: (items: unknown[]) => void;
+}
+
+const SlotsContext = createContext<ClientSlots>({});
+
+export const SlotsProvider = SlotsContext.Provider;
+
+export function useSlots(): ClientSlots {
+  return useContext(SlotsContext);
+}

package/src/client/lib/storage.ts

@@ -0,0 +1,39 @@
+const LEGACY_PREFIX = 'unclaw:';
+const PREFIX = 'shraga:';
+
+// Deliberately NOT migrated: the legacy `unclaw_auth_token` key (underscore, so it falls outside
+// LEGACY_PREFIX by design — not an oversight).
+//   - It's a LOCAL-auth-only key on both sides (`shraga_token` here is read only in the local
+//     branch of useAuth; Firebase mode uses the SDK's own persistence, which this never touches).
+//   - The two token formats differ and are signed with different secrets. This app's local token
+//     is `sha_<sig>.<base64url(email:exp)>` and `decodeLocalEmail` assumes that 4-char prefix,
+//     while verifyLocalToken hard-rejects anything not starting with `sha_`.
+// Carrying it over would seat a token this server rejects into the "I'm logged in" slot — a broken
+// half-authed state until the first 401 — instead of a clean login prompt. Re-login is correct.
+
+/**
+ * One-time rename of legacy `unclaw:*` localStorage keys to `shraga:*`.
+ *
+ * UI prefs (sidebar, drafts, artifact panel) are keyed by prefix, so a plain rename in code would
+ * silently reset every existing user. Migrating by prefix — rather than an explicit key list —
+ * also covers dynamic keys like `unclaw:draft:<id>`.
+ *
+ * Runs before first render. Existing canonical keys always win, so this can never clobber newer
+ * state, and re-running is a no-op.
+ */
+export function migrateLegacyStorageKeys(): void {
+  try {
+    const legacy = Object.keys(localStorage).filter(k => k.startsWith(LEGACY_PREFIX));
+    for (const oldKey of legacy) {
+      const newKey = PREFIX + oldKey.slice(LEGACY_PREFIX.length);
+      if (localStorage.getItem(newKey) === null) {
+        const v = localStorage.getItem(oldKey);
+        if (v !== null) localStorage.setItem(newKey, v);
+      }
+      localStorage.removeItem(oldKey);
+    }
+  } catch (e) {
+    // Storage can throw (disabled/full/private mode). A failed migration only costs reset prefs.
+    console.warn('[storage] legacy key migration skipped:', e instanceof Error ? e.message : String(e));
+  }
+}

package/src/client/lib/utils.ts

@@ -0,0 +1,26 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+// crypto.randomUUID requires a secure context (HTTPS/localhost); fall back for plain HTTP
+export function randomUUID(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}
+
+// Same-origin compare tolerant of malformed URLs (used by push tap-routing + instance dedup).
+export function sameOrigin(a: string, b: string): boolean {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return a === b;
+  }
+}

package/src/client/lib/workspaceContext.tsx

@@ -0,0 +1,54 @@
+import { createContext, useContext } from 'react';
+import type { AgentSocket } from '@/lib/ws';
+import type { ConnectionStatus } from '@/hooks/useAgentSocket';
+
+export interface AgentConfig {
+  engine?: string;
+  model?: string;
+  permissionMode?: string;
+  maxTurns?: number;
+  allowedTools?: string[];
+  systemPrompt?: string;
+  thinking?: 'adaptive' | 'enabled' | 'disabled';
+  effort?: 'low' | 'medium' | 'high' | 'max';
+}
+
+/**
+ * Shell-stable values shared with every {@link ConversationPane}, plus the minimal session
+ * actions a pane needs (adopt a new session id, rename its tab, open another session). This build
+ * ships a single pane, but the context stays the prop-drill escape hatch. Add-on-only wiring (extra
+ * panes, per-conversation resources, feature flags) lives behind {@link ClientSlots}, not here.
+ */
+export interface WorkspaceContextValue {
+  socket: AgentSocket | null;
+  connectionStatus: ConnectionStatus;
+  getToken: () => Promise<string | null>;
+  token: string | null;
+  agentConfig: AgentConfig;
+  setAgentConfig: (c: AgentConfig) => void;
+  /** The currently focused conversation — a pane uses it to know when it has become active. */
+  activeSessionId: string | undefined;
+  skills: string[];
+  workspaceFiles: string[];
+  openSchedules: () => void;
+  /** Clear unread state for a session (called when a pane becomes the active/focused one). */
+  markRead: (sessionId: string) => void;
+  /** Nudge the sidebar/session list to refresh (new session, title change, turn finished). */
+  bumpSidebar: () => void;
+  /** A pane adopted/changed its session id (fresh chat → real id, or fork). */
+  assignSession: (nodeId: string, sessionId: string) => void;
+  /** Update a tab's display title. */
+  renameTab: (nodeId: string, title: string) => void;
+  /** Open a session in a (preview) tab — used by fork, toasts, sidebar, schedules. */
+  openSession: (sessionId: string, title?: string) => void;
+}
+
+const WorkspaceContext = createContext<WorkspaceContextValue | null>(null);
+
+export const WorkspaceProvider = WorkspaceContext.Provider;
+
+export function useWorkspace(): WorkspaceContextValue {
+  const ctx = useContext(WorkspaceContext);
+  if (!ctx) throw new Error('useWorkspace must be used within a WorkspaceProvider');
+  return ctx;
+}

package/src/client/lib/ws.ts

@@ -0,0 +1,203 @@
+export type AskQuestion = {
+  question: string;
+  header: string;
+  multiSelect?: boolean;
+  options: { label: string; description: string; preview?: string }[];
+};
+export type QuestionAnswers = Record<string, string | string[]>;
+
+export type ServerEvent =
+  | { type: 'auth_ok'; uid: string; email: string; buildId?: string }
+  | { type: 'auth_error'; message: string }
+  | { type: 'thinking_delta'; text: string; sessionId?: string }
+  | { type: 'text_delta'; text: string; sessionId?: string }
+  | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown; sessionId?: string }
+  | { type: 'tool_use_input'; toolUseId: string; input: unknown; sessionId?: string }
+  | { type: 'tool_result'; toolUseId: string; output: string; sessionId?: string }
+  | { type: 'tool_result_image'; toolUseId: string; dataUrl: string; sessionId?: string }
+  | { type: 'permission_request'; id: string; tool: string; input: Record<string, unknown>; sessionId?: string }
+  | { type: 'question_request'; id: string; questions: AskQuestion[]; sessionId?: string }
+  | { type: 'session_id'; sessionId: string }
+  | { type: 'forked'; sourceSessionId: string; sessionId: string }
+  | { type: 'done'; sessionId: string; stopReason?: 'end_turn' | 'max_turns_reached' | (string & {}) }
+  | { type: 'model_resolved'; sessionId: string; model: string }
+  | { type: 'error'; message: string; sessionId?: string }
+  | { type: 'workspace_change'; action: 'created' | 'modified' | 'deleted'; path: string }
+  | { type: 'disconnected' }
+  | { type: 'reconnected' }
+  | { type: 'schedule:updated'; schedule: unknown }
+  | { type: 'schedule:deleted'; id: string }
+  | { type: 'schedule:fired'; scheduleId: string }
+  | { type: 'schedule:run_started'; scheduleId: string; sessionId: string; at: number }
+  | { type: 'schedule:run_finished'; scheduleId: string; sessionId: string; summary: unknown }
+  | { type: 'session_messages_changed'; sessionId: string }
+  | { type: 'session_title_updated'; sessionId: string; title: string }
+  | { type: 'directives'; directives: { model?: string; turns?: number; thinking?: string; engine?: string } }
+  | { type: 'session_busy'; sessionId: string; busy: boolean }
+  | { type: 'session_stream'; sessionId: string; event: { type: 'thinking_delta'; text: string } | { type: 'text_delta'; text: string } | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown } | { type: 'tool_use_input'; toolUseId: string; input: unknown } | { type: 'tool_result'; toolUseId: string; output: string } }
+  | { type: 'artifact'; id: string; sessionId: string; title: string; dimensions: [number, number]; version: number }
+  | { type: 'server_restarting' }
+  | { type: 'unread'; sessionId: string; count: number; preview: string; source: 'response' | 'proactive' | 'schedule'; title?: string }
+  | { type: 'unread_sync'; sessions: Record<string, { count: number; preview: string; since: number; lastAt: number; source: string; title?: string }> }
+  | { type: 'unread_cleared'; sessionId: string }
+  | { type: 'pty_list_changed'; sessionId: string }
+  | { type: 'workspace_layout_changed' }
+  | { type: 'stats'; sample: { t: number; cpu: number; mem: number; load: number } };
+
+type Listener = (event: ServerEvent) => void;
+
+export class AgentSocket {
+  private ws: WebSocket | null = null;
+  private listeners = new Set<Listener>();
+  private tokenProvider: () => Promise<string | null> = async () => null;
+  private intentionalClose = false;
+  private reconnecting = false;
+  private authRetries = 0;
+  private pendingMessage: object | null = null;
+  private connectAttempts = 0;
+
+  /**
+   * @param tokenProvider returns a *fresh* token on every call. Called on each
+   * (re)connect so an expired Firebase ID token is auto-refreshed instead of a
+   * stale one being resent forever.
+   */
+  connect(tokenProvider: () => Promise<string | null>) {
+    this.tokenProvider = tokenProvider;
+    this.intentionalClose = false;
+    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+    const url = `${proto}://${location.host}/ws`;
+    console.log('[ws] connecting…');
+    this.ws = new WebSocket(url);
+
+    this.ws.onopen = async () => {
+      this.connectAttempts = 0;
+      let token: string | null = null;
+      try {
+        token = await this.tokenProvider();
+      } catch (err) {
+        console.warn('[ws] token fetch failed', err);
+      }
+      if (this.ws?.readyState !== WebSocket.OPEN) return;
+      console.log('[ws] open, sending auth');
+      this.ws.send(JSON.stringify({ type: 'auth', token }));
+      if (this.reconnecting) {
+        this.reconnecting = false;
+        this.listeners.forEach((l) => l({ type: 'reconnected' }));
+      }
+    };
+
+    this.ws.onmessage = (e) => {
+      try {
+        const data = JSON.parse(e.data) as ServerEvent;
+        if (data.type !== 'text_delta') console.log('[ws] ←', data.type);
+        if (data.type === 'auth_ok') {
+          this.authRetries = 0;
+          this.flushPending();
+        }
+        if (data.type === 'auth_error') {
+          // Permanent failures (no fresh token can fix them) must STOP retrying — else the client
+          // hammers a reconnect every few seconds forever, flooding the server log. Two cases:
+          //  - whitelist rejection (this account isn't allowed), and
+          //  - token audience mismatch (the client is signed into a DIFFERENT Firebase project than the
+          //    server expects — refreshing the token re-mints the same wrong `aud`, never converging).
+          // Everything else (expired token, server restarting during deploy) is transient → keep retrying.
+          const msg = data.message?.toLowerCase() ?? '';
+          const isPermanent = msg.includes('whitelist') || msg.includes('audience mismatch') || msg.includes('sign out and sign in');
+          if (isPermanent) {
+            this.intentionalClose = true;
+          } else {
+            this.authRetries++;
+            console.log(`[ws] auth failed (attempt ${this.authRetries}), will retry with fresh token`);
+          }
+        }
+        this.listeners.forEach((l) => l(data));
+      } catch (err) {
+        console.warn('[ws] bad frame', err);
+      }
+    };
+
+    this.ws.onclose = (e) => {
+      console.log(`[ws] closed code=${e.code} intentional=${this.intentionalClose}`);
+      if (!this.intentionalClose) {
+        this.reconnecting = true;
+        this.connectAttempts++;
+        this.listeners.forEach((l) => l({ type: 'disconnected' }));
+        const base = this.authRetries > 0 ? Math.min(2000 * this.authRetries, 10000) : Math.min(1000 * 2 ** this.connectAttempts, 30000);
+        const jitter = Math.random() * 1000;
+        const delay = base + jitter;
+        console.log(`[ws] reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.connectAttempts})`);
+        setTimeout(() => this.connect(this.tokenProvider), delay);
+      }
+    };
+
+    this.ws.onerror = (e) => console.warn('[ws] error', e);
+  }
+
+  private flushPending() {
+    if (this.pendingMessage) {
+      const msg = this.pendingMessage;
+      this.pendingMessage = null;
+      console.log('[ws] flushing pending message after reconnect');
+      if (!this.send(msg)) {
+        this.pendingMessage = msg;
+      }
+    }
+  }
+
+  disconnect() {
+    this.intentionalClose = true;
+    this.ws?.close();
+    this.ws = null;
+  }
+
+  send(msg: object): boolean {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      console.log('[ws] →', (msg as any).type);
+      this.ws.send(JSON.stringify(msg));
+      return true;
+    }
+    console.warn('[ws] send failed, readyState=', this.ws?.readyState);
+    return false;
+  }
+
+  sendOrQueue(msg: object): boolean {
+    if (this.send(msg)) return true;
+    this.pendingMessage = msg;
+    console.log('[ws] message queued for reconnect');
+    return false;
+  }
+
+  cancel(sessionId?: string) {
+    this.send({ type: 'cancel', sessionId });
+  }
+
+  steer(text: string, sessionId?: string) {
+    this.send({ type: 'steer', text, sessionId });
+  }
+
+  respondPermission(id: string, allow: boolean, allowAll?: boolean) {
+    this.send({ type: 'permission_response', id, allow, allowAll });
+  }
+
+  respondQuestion(id: string, answers: QuestionAnswers) {
+    this.send({ type: 'question_response', id, answers });
+  }
+
+  sendPresence(sessionId: string | undefined, focused: boolean) {
+    this.send({ type: 'presence', sessionId: sessionId ?? null, focused });
+  }
+
+  /** Page-Visibility presence for push suppression: server skips notifying the screen in view. */
+  sendClientPresence(sessionId: string | undefined, visible: boolean) {
+    this.send({ type: 'client_presence', sessionId: sessionId ?? null, visible });
+  }
+
+  markRead(sessionId: string) {
+    this.send({ type: 'mark_read', sessionId });
+  }
+
+  on(listener: Listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}

package/src/client/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './globals.css';
+import { App } from './App';
+import { migrateLegacyStorageKeys } from './lib/storage';
+
+// Must run before first render — components read their prefs during initial state setup.
+migrateLegacyStorageKeys();
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/src/mcp-stdio-bridge.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+// stdio↔HTTP bridge for MCP (Streamable HTTP transport, maintains session ID)
+// Generic: MCP_URL + MCP_API_KEY, or legacy: UNCLAW_URL + UNCLAW_API_KEY
+const baseUrl = (process.env.MCP_URL || process.env.UNCLAW_URL || 'http://localhost:3033').replace(/\/$/, '');
+const mcpPath = process.env.MCP_PATH || '/mcp';
+const apiKey = process.env.MCP_API_KEY || process.env.UNCLAW_API_KEY;
+if (!apiKey) { console.error('[mcp-bridge] MCP_API_KEY (or UNCLAW_API_KEY) is required'); process.exit(1); }
+
+let sessionId: string | null = null;
+
+async function sendMessage(message: any): Promise<void> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${apiKey}`,
+    'Accept': 'application/json, text/event-stream',
+  };
+  if (sessionId) headers['mcp-session-id'] = sessionId;
+
+  const res = await fetch(`${baseUrl}${mcpPath}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(message),
+  });
+
+  // Capture session ID from server on initialize
+  const newSession = res.headers.get('mcp-session-id');
+  if (newSession) sessionId = newSession;
+
+  if (res.status === 204) return;
+
+  const contentType = res.headers.get('content-type') || '';
+
+  if (contentType.includes('text/event-stream')) {
+    // SSE: parse and forward each data line
+    const text = await res.text();
+    for (const line of text.split('\n')) {
+      if (line.startsWith('data: ')) {
+        const data = line.slice(6).trim();
+        if (data && data !== '[DONE]') {
+          process.stdout.write(data + '\n');
+        }
+      }
+    }
+  } else {
+    const body = await res.text();
+    if (body) process.stdout.write(body + '\n');
+  }
+}
+
+import { createInterface } from 'node:readline';
+const rl = createInterface({ input: process.stdin, terminal: false });
+let buffer = '';
+
+rl.on('line', async (line) => {
+  buffer += line;
+  let message: any;
+  try { message = JSON.parse(buffer); } catch { return; }
+  buffer = '';
+
+  try {
+    await sendMessage(message);
+  } catch (e: any) {
+    const err = {
+      jsonrpc: '2.0',
+      id: message?.id ?? null,
+      error: { code: -32603, message: `Bridge error: ${e.message}` },
+    };
+    process.stdout.write(JSON.stringify(err) + '\n');
+  }
+});

package/src/scripts/summarize-conversations.ts

@@ -0,0 +1,5 @@
+import { summarizeConversations } from '../server/conversation-summarizer.ts';
+
+const force = process.argv.includes('--force');
+const result = await summarizeConversations({ force });
+console.log(`Done: ${result.summarized} summarized, ${result.tracesGenerated} traces, ${result.skipped} skipped, ${result.errors} errors`);

package/src/scripts/typecheck.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+/**
+ * Honest typecheck. Runs `tsc --noEmit` over the whole project (client + server;
+ * see tsconfig.json "include": ["src", ...]).
+ *
+ * A fresh consumer who `bun install`s the PUBLISHED deps gets compiled `.d.ts`
+ * (skipped by skipLibCheck) and sees only the project's own errors — nothing to
+ * filter. In this repo's local dev, sibling libs are SYMLINKED into node_modules
+ * as raw `.ts` source (relink-libs.sh), so tsc follows the import graph into that
+ * source and reports errors that no real consumer ever hits. tsc can't be told to
+ * skip `.ts` under node_modules (skipLibCheck only skips `.d.ts`), and `exclude`
+ * doesn't stop import-following — so we strip exactly those dep-source lines here.
+ *
+ * This never hides a shraga error: everything that isn't a `node_modules/` or
+ * `../sibling` source path is passed through, and the exit code is non-zero if any
+ * such line remains. It only removes noise from linked dependency source.
+ */
+import { spawnSync } from 'node:child_process';
+
+const res = spawnSync('tsc', ['--noEmit', '--pretty', 'false'], {
+  encoding: 'utf8',
+  shell: true,
+});
+
+const out = (res.stdout || '') + (res.stderr || '');
+const lines = out.split('\n');
+
+// A tsc error line begins with a file path. Dep-source noise resolves either to
+// `node_modules/...` (linked raw-.ts packages) or to a `../sibling` repo path.
+const isDepSourceNoise = (line: string) =>
+  /^(?:\.\.[\\/]|node_modules[\\/])/.test(line) ||
+  /[\\/]node_modules[\\/]/.test(line.split('(')[0] ?? '');
+
+const kept = lines.filter((l) => !isDepSourceNoise(l));
+const errors = kept.filter((l) => /error TS\d+:/.test(l));
+
+process.stdout.write(kept.join('\n'));
+if (errors.length > 0) {
+  console.error(`\n${errors.length} project type error(s).`);
+  process.exit(1);
+}
+console.log('\nTypecheck clean (project sources).');
+process.exit(0);

package/src/server/agents.ts

@@ -0,0 +1,54 @@
+import { mkdirSync, readdirSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { dataPath } from './paths.ts';
+
+const AGENTS_DIR = dataPath('agents');
+const DEFAULTS_DIR = path.resolve(import.meta.dirname, '../../defaults/agents');
+
+export interface AgentDef {
+  description: string;
+  prompt: string;
+  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
+  tools?: string[];
+  maxTurns?: number;
+}
+
+function parseFrontmatter(content: string): { meta: Record<string, string>; body: string } {
+  if (!content.startsWith('---')) return { meta: {}, body: content };
+  const end = content.indexOf('---', 3);
+  if (end < 0) return { meta: {}, body: content };
+  const yaml = content.slice(3, end).trim();
+  const body = content.slice(end + 3).trim();
+  const meta: Record<string, string> = {};
+  for (const line of yaml.split('\n')) {
+    const [k, ...rest] = line.split(':');
+    if (k && rest.length) meta[k.trim()] = rest.join(':').trim();
+  }
+  return { meta, body };
+}
+
+export function loadAgents(): Record<string, AgentDef> {
+  mkdirSync(AGENTS_DIR, { recursive: true });
+
+  const agents: Record<string, AgentDef> = {};
+  const dirs = [DEFAULTS_DIR, AGENTS_DIR];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter(f => f.endsWith('.md'))) {
+      const name = f.slice(0, -3);
+      const content = readFileSync(path.join(dir, f), 'utf-8');
+      const { meta, body } = parseFrontmatter(content);
+
+      agents[name] = {
+        description: meta.description || name,
+        prompt: body,
+        model: (meta.model as AgentDef['model']) || undefined,
+        tools: meta.tools ? meta.tools.split(',').map(s => s.trim()) : undefined,
+        maxTurns: meta['max-turns'] ? parseInt(meta['max-turns'], 10) : undefined,
+      };
+    }
+  }
+
+  return agents;
+}

package/src/server/api-keys.ts

@@ -0,0 +1,63 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { dataPath } from './paths.ts';
+
+const KEYS_PATH = dataPath('api-keys.json');
+
+export interface ApiKey {
+  id: string;
+  key: string;
+  label: string;
+  uid: string;
+  email: string;
+  createdAt: number;
+}
+
+function load(): ApiKey[] {
+  if (!existsSync(KEYS_PATH)) return [];
+  try { return JSON.parse(readFileSync(KEYS_PATH, 'utf-8')); } catch { return []; }
+}
+
+function save(keys: ApiKey[]) {
+  mkdirSync(dataPath(''), { recursive: true });
+  writeFileSync(KEYS_PATH, JSON.stringify(keys, null, 2));
+}
+
+export function createApiKey(uid: string, email: string, label: string): ApiKey {
+  const keys = load();
+  const entry: ApiKey = {
+    id: randomBytes(8).toString('hex'),
+    key: `uck_${randomBytes(32).toString('hex')}`,
+    label,
+    uid,
+    email,
+    createdAt: Date.now(),
+  };
+  keys.push(entry);
+  save(keys);
+  return entry;
+}
+
+export function deleteApiKey(id: string, callerUid: string, isOwner: boolean): 'ok' | 'not_found' | 'forbidden' {
+  const keys = load();
+  const idx = keys.findIndex(k => k.id === id);
+  if (idx < 0) return 'not_found';
+  if (keys[idx].uid !== callerUid && !isOwner) return 'forbidden';
+  keys.splice(idx, 1);
+  save(keys);
+  return 'ok';
+}
+
+export function listApiKeys() {
+  return load().map(({ key, ...rest }) => ({ ...rest, keyPreview: `${key.slice(0, 8)}…` }));
+}
+
+export function validateApiKey(key: string): { uid: string; email: string } | null {
+  const keys = load();
+  for (const k of keys) {
+    if (k.key.length === key.length && timingSafeEqual(Buffer.from(k.key), Buffer.from(key))) {
+      return { uid: k.uid, email: k.email };
+    }
+  }
+  return null;
+}