@raviolelabs/engram-mcp 0.2.0

package/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: engram-semantic-memory
+description: Use EngramMCP to give yourself persistent semantic memory — write what matters with remember(), retrieve later with recall(), build connections with relate(). Works locally via 768-dim embeddings + FTS5.
+---
+
+# EngramMCP — Calling Agent Guide
+
+> **Tool naming note:** Tool names in this doc are written WITHOUT a client prefix. Your runtime may expose them as `mcp__engram__<name>` (Claude Code) or bare `<name>` (Anthropic API, OpenAI, generic MCP client). Use whichever form your runtime exposes.
+
+## Avoiding tool loops
+
+The agent MUST NOT call any single tool more than 3 times in a single turn on the same input.
+
+If a tool returns:
+- **success** → done, move on
+- **empty result** → the answer is genuinely 'no' or the input is wrong; do not retry with the same input
+- **error** → retry once with adjusted input; if still fails, surface to user
+- **'pending' (jobs)** → respect `retry_after_ms` hint, stop after `should_give_up: true` (10 polls)
+
+### Idempotent tools (safe to call multiple times — will not create duplicates)
+
+| Tool | Idempotency key |
+|---|---|
+| `remember` | content_hash + type |
+| `update` | returns `{updated: false}` if no-op |
+| `forget` | returns success even if already deleted |
+| `watch` | returns `{already_watching: true}` if already registered |
+| `create_type` | returns `{created: false}` if type already exists |
+
+### Non-retryable tools (require user action — calling again creates orphan state)
+
+| Tool | Reason |
+|---|---|
+| `connect_drive` | Starts OAuth flow — wait for user browser action |
+| `connect_notion` | Starts OAuth flow — wait for user browser action |
+
+### Cache within turn (call once, reuse result)
+
+- `list_types` — cheap but stable within a conversation
+- `list_sources` — slow on large workspaces
+
+### If you find yourself about to call the same tool with the same args 2+ times: STOP, surface to user.
+
+## When to use this skill
+
+Use Engram whenever you want information to outlast the current context window.
+
+- User shares preferences, facts, decisions, contact info, project context
+- User describes their workflow, what they're building, what they care about
+- User mentions documents or URLs that should be ingested for later context
+- Start of every conversation: call `recent({limit: 10})` to refresh stale context
+- User explicitly asks to "remember" or "save" something
+
+## Anti-patterns
+
+- **DON'T** `remember()` ephemeral chitchat. Memory should be high-signal.
+- **DON'T** `remember()` your own outputs unless the user explicitly says "remember this".
+- **DON'T** skip tags — untagged memories rarely surface in `recall`.
+- **DON'T** call `recall()` with the literal user question. Extract the *topic*. "What did I say about Alice?" → `recall({query: "alice"})`.
+- **DON'T** call `recall()` when you already have an id — use `get(id)`.
+- **DON'T** call `get()` when searching by concept — use `recall()`.
+
+## The 24 tools — quick reference
+
+All tools are public — no `--admin` flag needed.
+
+| Tool | Use when |
+|---|---|
+| `remember(content, title, tags, type?)` | User shares anything worth keeping. Idempotent on content_hash. |
+| `recall(query, types?, limit?)` | Surface past memories on a topic. Don't retry with same query if empty. |
+| `get(id)` | You already have an id and need the full record. Don't retry on not_found. |
+| `update(id, ...)` | User corrects a fact or wants to retag/rename. No-op if unchanged. |
+| `forget(id)` | User explicitly asks to erase something. Idempotent. |
+| `relate(id, limit?)` | "What else is connected to this?" Don't retry if empty. |
+| `list_types()` | First call when joining an existing Engram. Cache result for turn. |
+| `recent(limit?, types?)` | Start of conversation — fetch fresh context. |
+| `ingest(uri, type?)` | User mentions a file path, YouTube URL, Drive doc, etc. |
+| `get_ingest_status(job_id)` | Check status of async audio/video ingest. Respect retry_after_ms. |
+| `suggest_properties(id)` | A memory came in without title/tags. Call once, then update(). |
+| `watch(source_type, target_id, opts?)` | Start continuous sync. Idempotent. |
+| `unwatch(source_type?, target_id?, source_id?)` | Stop syncing a source (memories kept). Idempotent. |
+| `list_sources(source_type?)` | See what sources are being auto-synced. Cache for turn. |
+| `create_type(name, display_name?, schema?)` | Create a user-defined memory type. Idempotent on name. |
+| `delete_type(name, confirm: true)` | Remove a custom type definition. Requires confirm; shows summary first. |
+| `connect_drive` | Initiate Google Drive OAuth. Requires user browser action — DO NOT retry. |
+| `list_drive_files(query?, limit?)` | List Drive files. Cache result per query per turn. |
+| `connect_notion` | Initiate Notion OAuth. Requires user browser action — DO NOT retry. |
+| `list_notion_pages(query?, limit?)` | Search Notion workspace. Cache result per query per turn. |
+| `import_watch_later(playlistUrl, limit?)` | Bulk import YouTube playlist. Slow — never call twice. |
+| `analyze_patterns(topic, types?, limit?, lookback_days?)` | Cross-memory pattern synthesis on a topic. Returns bundle + instruction. Idempotent. |
+| `summarize_recent(days?, types?, limit?)` | Recent memory digest. Returns bundle + summarization instruction. Idempotent. |
+| `find_gaps(topic, lookback_days?)` | Gap analysis on a topic. Returns bundle + gap-finding instruction. Idempotent. |
+
+## Wikilinks
+
+Mention related memories by `[[id]]` or `[[title]]` in your `remember` content. The system auto-extracts these as graph edges.
+
+```
+remember({
+  content: "Met with [[Alice]] today about [[Project Atlas]]. She prefers async over standups.",
+  title: "Alice 1:1 May 17",
+  tags: ["alice", "atlas", "preferences"]
+})
+```
+
+When you recall a memory that mentions Atlas, `relate({id: atlasId})` will surface Alice's 1:1 as a related node.
+
+## Tagging strategy
+
+Tags are how memories cluster and surface. Good tags:
+
+- **Entities**: people (`alice`, `bob`), companies (`anthropic`), projects (`atlas`)
+- **Domains**: `programming`, `finance`, `health`, `family`
+- **Event types**: `decision`, `blocker`, `todo`, `idea`
+
+Bad tags:
+- Vague: `stuff`, `misc`, `thing`
+- Singletons that will never recur
+- Sentence fragments
+
+Aim for 2-5 tags per memory. A memory with zero tags is retrievable only by exact semantic match — it will miss topical queries.
+
+## Recall strategy
+
+`recall` does parallel fan-out across all types, then scores by semantic similarity + recency boost + MMR diversity (if private algorithms loaded). Tips:
+
+- Restrict `types` if you know the type — it's significantly faster.
+- Use short, topic-y queries. `"alice preferences"` not `"what does alice prefer about how we work together"`.
+- Default limit 10 is enough for most lookups; bump to 20-30 for exhaustive sweeps.
+- After recall, if a snippet looks relevant but incomplete, call `get(id)` for full content.
+
+## Conversation pattern
+
+```
+[user opens chat]
+→ recent({limit: 10})            -- see what's fresh, prime context
+
+[user mentions a topic]
+→ recall({query: "<noun>"})      -- retrieve relevant past memories
+
+[user shares new info]
+→ remember({content, title, tags})
+
+[user mentions a file/URL]
+→ ingest({uri: "<path or url>"})
+
+[end of conversation, milestone reached]
+→ remember({                     -- optional: capture session summary
+    content: "Summary: ...",
+    title: "Session YYYY-MM-DD",
+    tags: ["summary", "<project>"]
+  })
+```
+
+## Ingest URI routing + async behavior
+
+`ingest()` auto-routes based on the URI. No need to pick the module manually.
+
+| URI pattern | Routed to | Sync? |
+|---|---|---|
+| `file://*.md`, `*.txt` | notes (read file content) | Sync |
+| `file://*.mp3`, `*.wav`, `*.m4a`, `*.ogg`, `*.webm` | audio (Whisper transcription) | **Async** |
+| `file://*.pdf` | notes (pdf-parse text extraction) | Sync |
+| `file://*.png`, `*.jpg`, `*.gif` | images type | Sync |
+| `https://www.youtube.com/watch?*`, `https://youtu.be/*` | youtube (transcript fetch) | Sync if <5min, **Async** otherwise |
+| `https://docs.google.com/document/d/*` | drive | Sync |
+| `https://*.notion.so/*` | notion | Sync |
+| `obsidian://vault/<vault>/<path>` | obsidian | Sync |
+| Any other `https://` URL | fetch + store as note | Sync |
+
+You can override routing with `type: "audio"` etc.
+
+### Async ingest pattern
+
+`ingest()` returns one of two shapes:
+
+```ts
+// Fast paths (markdown, small pages, Drive, Notion) — synchronous:
+{ id: "01JXY...", type: "notes", title: "My Note", status: "completed" }
+
+// Slow paths (audio, YouTube) — async job:
+{ job_id: "job_01JXY...", status: "pending", estimated_ms: 30000 }
+```
+
+For async jobs, poll `get_ingest_status(job_id)` every few seconds:
+
+```
+get_ingest_status("job_01JXY...")
+// → { job_id, status: "processing", progress: 45 }
+// → { job_id, status: "completed", memory_id: "01JXZ..." }
+```
+
+Once `status === "completed"`, the `memory_id` is searchable via `recall()`.
+
+**Tip:** You can also just fire `ingest()` and move on — the job completes in the background and becomes searchable automatically. Only poll if you need the result immediately.
+
+## Watching sources
+
+`watch()` is now on the public surface — no `--admin` flag needed. It requires that the source is already authenticated (run `connect_drive` / `connect_notion` once via admin or the install wizard).
+
+```ts
+// Watch a YouTube channel for new videos
+watch({ source_type: "youtube", target_id: "UCxxxxxx", opts: { channelName: "My Channel" } })
+
+// Watch an Obsidian vault
+watch({ source_type: "obsidian", target_id: "/path/to/vault" })
+
+// List all watched sources
+list_sources()
+list_sources({ source_type: "youtube" })
+
+// Stop watching
+unwatch({ source_id: "<id from watch()>" })
+```
+
+## Custom types
+
+```ts
+// Create a new memory type
+create_type({ name: "books", display_name: "Books" })
+
+// Now use it:
+remember({ content: "...", type: "books", title: "Dune", tags: ["sci-fi"] })
+recall({ query: "space opera", types: ["books"] })
+
+// Remove type schema (memories kept):
+delete_type({ name: "books", confirm: true })
+```
+
+## Pattern analysis tools
+
+For high-level synthesis beyond single recall:
+- `analyze_patterns(topic, types?, limit?, lookback_days?)` — "what patterns in my notes about X?" Returns matching memories + pre-computed aggregations (tag freq, timeline, type distribution) + a structured instruction. You (the agent) then perform the actual analysis using the bundled data. DON'T re-call `recall()` — `analyze_patterns` already includes the matching memories.
+- `summarize_recent(days?, types?, limit?)` — "summarize my last week". Returns recent memories + summarization instruction for a digest.
+- `find_gaps(topic, lookback_days?)` — "what's missing or unanswered about X?" Returns memories on a topic + gap-analysis instruction.
+
+All three tools are **IDEMPOTENT** on their inputs — calling twice in the same turn returns the same bundle. DO NOT re-call with the same args.
+
+```ts
+// Analyze patterns across memories on a topic
+analyze_patterns({ topic: "project atlas" })
+// → { topic, memories_found, date_range, memories, aggregations, instruction }
+// You then synthesize the analysis from the bundled data.
+
+// Summarize recent activity
+summarize_recent({ days: 7 })
+// → { period, memories_count, memories, instruction }
+
+// Find gaps in documentation on a topic
+find_gaps({ topic: "alice", lookback_days: 90 })
+// → { topic, memories_found, date_range, memories, aggregations, instruction }
+```
+
+## suggest_properties workflow
+
+For memories ingested without metadata (audio drops, Drive files named `Untitled`):
+
+```
+1. suggest_properties({id})      -- returns content + extraction instruction
+2. Extract title, tags, sentiment from the returned content (you are the LLM)
+3. update({id, title, tags, sentiment})
+```
+
+## Type semantics
+
+| Type | Content |
+|---|---|
+| `notes` | Free-form notes, text files, web pages |
+| `conversations` | Full exchanges (`"user: X\nassistant: Y"`) |
+| `audio` | Whisper transcript from audio files |
+| `youtube` | YouTube video transcript |
+| `drive` | Google Drive documents |
+| `notion` | Notion pages |
+| `obsidian` | Obsidian markdown notes |
+| `images` | Image metadata (no OCR yet) |
+| custom | User-defined via admin `create_custom_type` — use `remember({type: "books", ...})` once created |
+
+## Error handling
+
+| Error | Cause | Fix |
+|---|---|---|
+| `not_found` from `get`/`update`/`forget` | Stale id | Re-recall to get fresh id |
+| `embedding_failed` | Ollama is offline | Inform user, don't retry in a loop |
+| `ingest` returns `error` key | URI routing failed or module error | Check URI format, confirm OAuth if Drive/Notion |
+
+## OAuth tools — browser action required
+
+`connect_drive` and `connect_notion` initiate OAuth flows. The agent CANNOT complete these autonomously — the user must open the returned `auth_url` in a browser.
+
+**Correct flow:**
+1. Agent calls `connect_drive()` → gets `{auth_url, instructions}`
+2. Agent tells user: "Please open this URL in your browser: [auth_url]"
+3. User completes authorization
+4. User tells agent "Done" (or drive tools start working)
+5. Agent verifies by calling `list_drive_files()`
+
+The install wizard (`engram-mcp-install`) handles OAuth interactively. The dashboard at `localhost:7777` also has OAuth buttons.
+
+**Total tool count: 24 (all public — no --admin flag needed).**

package/dist/cloud/auth.d.ts

@@ -0,0 +1,29 @@
+export interface EngramTokens {
+    jwt: string;
+    refreshToken: string;
+    apiKey: string;
+    /** Unix ms — when the JWT expires */
+    expiresAt: number;
+}
+export declare function saveTokens(tokens: EngramTokens): void;
+export declare function loadTokens(): EngramTokens | null;
+export declare function clearTokens(): void;
+/**
+ * Parse expiry from a JWT payload without verifying the signature.
+ * The server will reject an expired JWT anyway; we just need the timing.
+ */
+export declare function parseJwtExpiry(jwt: string): number;
+/**
+ * Return a valid (non-expired) JWT. Refreshes automatically if needed.
+ * Throws if tokens are not present or refresh fails.
+ */
+export declare function getValidJwt(baseUrl: string): Promise<string>;
+/**
+ * Return the stored API key. Throws if not paired.
+ */
+export declare function getApiKey(): string;
+/**
+ * Check whether the user has paired (tokens present in DB).
+ */
+export declare function isPaired(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/cloud/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/cloud/auth.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAoBrD;AAED,wBAAgB,UAAU,IAAI,YAAY,GAAG,IAAI,CAyBhD;AAED,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQlD;AA+BD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBlE;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC"}

package/dist/cloud/auth.js

@@ -0,0 +1,132 @@
+/**
+ * src/cloud/auth.ts
+ *
+ * Manages the local Engram cloud account token lifecycle:
+ * - Persists JWT + refresh token in the existing oauth_tokens table
+ *   (provider = 'engram_account').
+ * - Refreshes the JWT when it is within 2 minutes of expiry.
+ * - Exposes getValidJwt() and getApiKey() for use by transit-poller and
+ *   bridge-client.
+ *
+ * The API key is stored in `extra_json` alongside the JWT so both are in one
+ * table row. The refresh token is stored in the `refresh_token` column.
+ */
+import { getDb } from '../db/index.js';
+import { createLogger } from '../logger.js';
+const log = createLogger('cloud:auth');
+const PROVIDER = 'engram_account';
+const REFRESH_BUFFER_MS = 2 * 60 * 1000; // refresh when < 2 min remaining
+// ---------------------------------------------------------------------------
+// Persistence (oauth_tokens table)
+// ---------------------------------------------------------------------------
+export function saveTokens(tokens) {
+    const db = getDb();
+    db.prepare(`INSERT INTO oauth_tokens (provider, access_token, refresh_token, expires_at, extra_json, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(provider) DO UPDATE SET
+       access_token = excluded.access_token,
+       refresh_token = excluded.refresh_token,
+       expires_at = excluded.expires_at,
+       extra_json = excluded.extra_json,
+       updated_at = excluded.updated_at`).run(PROVIDER, tokens.jwt, tokens.refreshToken, tokens.expiresAt, JSON.stringify({ apiKey: tokens.apiKey }), Date.now());
+    log.debug('Tokens saved to oauth_tokens');
+}
+export function loadTokens() {
+    const db = getDb();
+    const row = db
+        .prepare(`SELECT access_token, refresh_token, expires_at, extra_json
+       FROM oauth_tokens WHERE provider = ?`)
+        .get(PROVIDER);
+    if (!row)
+        return null;
+    const extra = row.extra_json ? JSON.parse(row.extra_json) : {};
+    return {
+        jwt: row.access_token,
+        refreshToken: row.refresh_token ?? '',
+        apiKey: extra.apiKey ?? '',
+        expiresAt: row.expires_at ?? 0,
+    };
+}
+export function clearTokens() {
+    getDb().prepare('DELETE FROM oauth_tokens WHERE provider = ?').run(PROVIDER);
+    log.info('Engram account tokens cleared');
+}
+// ---------------------------------------------------------------------------
+// JWT refresh
+// ---------------------------------------------------------------------------
+/**
+ * Parse expiry from a JWT payload without verifying the signature.
+ * The server will reject an expired JWT anyway; we just need the timing.
+ */
+export function parseJwtExpiry(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3)
+        throw new Error('Malformed JWT');
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+    if (!payload.exp)
+        throw new Error('JWT has no exp claim');
+    return payload.exp * 1000; // convert to Unix ms
+}
+/**
+ * POST /auth/refresh to get a new JWT using the refresh token.
+ * Plan I exposes this endpoint.
+ */
+async function refreshJwt(refreshToken, baseUrl) {
+    const url = `${baseUrl.replace(/\/$/, '')}/auth/refresh`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refreshToken }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`JWT refresh failed ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const newJwt = data.jwt ?? data.token ?? '';
+    if (!newJwt)
+        throw new Error('Refresh response missing jwt field');
+    return { jwt: newJwt, expiresAt: parseJwtExpiry(newJwt) };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Return a valid (non-expired) JWT. Refreshes automatically if needed.
+ * Throws if tokens are not present or refresh fails.
+ */
+export async function getValidJwt(baseUrl) {
+    const tokens = loadTokens();
+    if (!tokens)
+        throw new Error('Not paired — run `engram-mcp-pair` to connect your account');
+    const now = Date.now();
+    if (tokens.expiresAt - now > REFRESH_BUFFER_MS) {
+        // Still valid
+        return tokens.jwt;
+    }
+    // Needs refresh
+    log.info('JWT near expiry — refreshing');
+    const { jwt, expiresAt } = await refreshJwt(tokens.refreshToken, baseUrl);
+    saveTokens({ ...tokens, jwt, expiresAt });
+    log.info('JWT refreshed successfully');
+    return jwt;
+}
+/**
+ * Return the stored API key. Throws if not paired.
+ */
+export function getApiKey() {
+    const tokens = loadTokens();
+    if (!tokens)
+        throw new Error('Not paired — run `engram-mcp-pair` to connect your account');
+    if (!tokens.apiKey)
+        throw new Error('Paired but API key missing — re-pair to fix');
+    return tokens.apiKey;
+}
+/**
+ * Check whether the user has paired (tokens present in DB).
+ */
+export function isPaired() {
+    return loadTokens() !== null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/cloud/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/cloud/auth.ts"],"names":[],"mappings":"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"}

package/dist/cloud/bridge-client.d.ts

@@ -0,0 +1,10 @@
+export interface BridgeClientOptions {
+    baseUrl: string;
+    localPort: number;
+}
+export interface BridgeClient {
+    /** Stop the client and close the WebSocket. */
+    stop: () => void;
+}
+export declare function startBridgeClient(opts: BridgeClientOptions): BridgeClient;
+//# sourceMappingURL=bridge-client.d.ts.map

package/dist/cloud/bridge-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-client.d.ts","sourceRoot":"","sources":["../../src/cloud/bridge-client.ts"],"names":[],"mappings":"AA0HA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CA8FzE"}

package/dist/cloud/bridge-client.js

@@ -0,0 +1,167 @@
+/**
+ * src/cloud/bridge-client.ts
+ *
+ * Bridge Relay WSS client.
+ *
+ * Maintains a persistent WebSocket connection to the Plan J Bridge Relay DO
+ * so that engram-mcp.com (Plan L) can proxy REST API requests to the user's local
+ * Express server without the PC needing a public IP or port-forward.
+ *
+ * Security constraints enforced on the PC side:
+ * - Only /api/* paths are forwarded (all other paths → 403)
+ * - Body size limit: 4MB (same as Express limit)
+ * - Read-only paths that mutate state (/api/reindex, DELETE /api/memories/*)
+ *   are still allowed because they require the user to be authenticated to
+ *   engram-mcp.com — the bridge is an authenticated channel, not a public one.
+ *
+ * Reconnect: exponential backoff 1s → 2s → 4s → … capped at 60s.
+ * The bridge client does NOT start if engramAccount is absent.
+ */
+import { WebSocket } from 'ws';
+import { createLogger } from '../logger.js';
+import { getValidJwt } from './auth.js';
+const log = createLogger('cloud:bridge');
+const RELAY_PATH = '/relay/pc';
+const LOCAL_API_BASE = 'http://127.0.0.1';
+const MAX_BODY_BYTES = 4 * 1024 * 1024; // 4MB
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Local HTTP forwarder
+// ---------------------------------------------------------------------------
+async function forwardToLocal(req, localPort) {
+    // Security: only /api/* paths
+    if (!req.path.startsWith('/api/')) {
+        return {
+            requestId: req.requestId,
+            status: 403,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ error: 'Bridge relay only forwards /api/* paths' }),
+        };
+    }
+    const url = `${LOCAL_API_BASE}:${localPort}${req.path}`;
+    const fetchInit = {
+        method: req.method,
+        headers: {
+            'Content-Type': 'application/json',
+            ...req.headers,
+        },
+        signal: AbortSignal.timeout(30_000),
+    };
+    if (req.body && !['GET', 'HEAD', 'DELETE'].includes(req.method.toUpperCase())) {
+        if (req.body.length > MAX_BODY_BYTES) {
+            return {
+                requestId: req.requestId,
+                status: 413,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ error: 'Request body too large (max 4MB)' }),
+            };
+        }
+        fetchInit.body = req.body;
+    }
+    let res;
+    try {
+        res = await fetch(url, fetchInit);
+    }
+    catch (e) {
+        return {
+            requestId: req.requestId,
+            status: 502,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                error: `Local API unreachable: ${e instanceof Error ? e.message : String(e)}`,
+            }),
+        };
+    }
+    const responseBody = await res.text();
+    const responseHeaders = {};
+    res.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+    });
+    return {
+        requestId: req.requestId,
+        status: res.status,
+        headers: responseHeaders,
+        body: responseBody,
+    };
+}
+export function startBridgeClient(opts) {
+    const wsUrl = opts.baseUrl
+        .replace(/^https:\/\//, 'wss://')
+        .replace(/^http:\/\//, 'ws://')
+        .replace(/\/$/, '') + RELAY_PATH;
+    let stopped = false;
+    let ws = null;
+    let reconnectDelay = RECONNECT_BASE_MS;
+    let reconnectTimer = null;
+    function connect() {
+        if (stopped)
+            return;
+        log.info(`Bridge relay: connecting to ${wsUrl}`);
+        // Resolve JWT asynchronously — if it fails, we retry later
+        getValidJwt(opts.baseUrl)
+            .then((jwt) => {
+            if (stopped)
+                return;
+            ws = new WebSocket(wsUrl, {
+                headers: { Authorization: `Bearer ${jwt}` },
+            });
+            ws.on('open', () => {
+                log.info('Bridge relay: connected');
+                reconnectDelay = RECONNECT_BASE_MS; // reset backoff on success
+                ws.send(JSON.stringify({ type: 'pc_ready' }));
+            });
+            ws.on('message', async (data) => {
+                let req;
+                try {
+                    req = JSON.parse(data.toString());
+                }
+                catch {
+                    log.warn('Bridge relay: received non-JSON message, ignoring');
+                    return;
+                }
+                log.debug(`Bridge relay: tunnel request ${req.requestId} ${req.method} ${req.path}`);
+                const response = await forwardToLocal(req, opts.localPort);
+                if (ws?.readyState === WebSocket.OPEN) {
+                    ws.send(JSON.stringify(response));
+                }
+            });
+            ws.on('close', (code, reason) => {
+                log.warn(`Bridge relay: disconnected (code=${code}, reason=${reason.toString().slice(0, 80)})`);
+                scheduleReconnect();
+            });
+            ws.on('error', (err) => {
+                log.error(`Bridge relay: WS error: ${err.message}`);
+                // 'close' event fires after 'error', so reconnect is scheduled there
+            });
+        })
+            .catch((e) => {
+            log.error(`Bridge relay: could not get JWT — ${e instanceof Error ? e.message : String(e)}`);
+            scheduleReconnect();
+        });
+    }
+    function scheduleReconnect() {
+        if (stopped)
+            return;
+        log.info(`Bridge relay: reconnecting in ${reconnectDelay}ms`);
+        reconnectTimer = setTimeout(() => {
+            reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+            connect();
+        }, reconnectDelay);
+    }
+    // Start first connection
+    connect();
+    return {
+        stop: () => {
+            stopped = true;
+            if (reconnectTimer)
+                clearTimeout(reconnectTimer);
+            if (ws) {
+                ws.close(1000, 'Bridge client stopped');
+                ws = null;
+            }
+            log.info('Bridge relay: stopped');
+        },
+    };
+}
+//# sourceMappingURL=bridge-client.js.map

package/dist/cloud/bridge-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-client.js","sourceRoot":"","sources":["../../src/cloud/bridge-client.ts"],"names":[],"mappings":"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"}