@soundbi/sound-connect 0.1.0

package/dist/retry-queue.js

@@ -0,0 +1,461 @@
+/**
+ * Local ingest retry queue — STORY-013, ADR-011.
+ *
+ * When the Sound Connect backend is briefly unreachable (network error or 5xx),
+ * failed /ingest POST chunks are written to a local file-based queue so they are
+ * not silently lost. A background retry worker drains the queue with exponential
+ * backoff; the ADR-004 sha256 idempotency key makes re-sends safe.
+ *
+ * Queue state machine per item:
+ *   pending  → retry attempts < MAX_RETRY_ATTEMPTS and no permanent 4xx failure
+ *   dead     → 4xx response from backend (auth/permission error — do not retry)
+ *
+ * Queue storage: OS temp dir / sound-connect-queue / <clientSlug> /
+ *   Each item is a JSON file: <enqueuedAt>-<sha256Prefix>.json
+ *   A dead item is renamed to: <name>.dead
+ *
+ * Restart resilience: items survive a bridge restart because they live on disk.
+ *   On startup, call loadQueue() to discover and resume pending items.
+ *
+ * Permanent failures (4xx): written to disk as .dead files and surfaced via
+ *   ingest_status so the user can see them. They are never silently retried.
+ *
+ * ADR-011: fail closed on auth (4xx → dead, not retried), safe retry on transient
+ *   outages, idempotency from ADR-004 makes retries harmless.
+ */
+import { writeFile, readFile, readdir, rm, mkdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+// ── Constants ──────────────────────────────────────────────────────────────────
+/** Maximum number of retry attempts before giving up (and marking dead). */
+export const MAX_RETRY_ATTEMPTS = 8;
+/** Base delay in milliseconds for exponential backoff (doubles each attempt). */
+export const BACKOFF_BASE_MS = 1_000;
+/** Maximum backoff cap in milliseconds (~2 minutes). */
+export const BACKOFF_MAX_MS = 120_000;
+/** Interval in milliseconds between retry worker sweeps. */
+export const WORKER_INTERVAL_MS = 10_000;
+// ── Queue directory ────────────────────────────────────────────────────────────
+/**
+ * Returns the absolute path to the queue directory for a given client slug.
+ * Uses OS temp dir so the queue is writable without special permissions.
+ * Items survive bridge restarts as long as the OS does not clean temp on reboot.
+ *
+ * Overridable via SC_QUEUE_DIR env var for tests.
+ */
+export function queueDir(clientSlug) {
+    const base = process.env['SC_QUEUE_DIR'] ?? join(tmpdir(), 'sound-connect-queue');
+    return join(base, clientSlug);
+}
+/** Ensures the queue directory exists (creates it if absent). */
+async function ensureQueueDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+// ── Item serialization ─────────────────────────────────────────────────────────
+/** Returns the filename (not path) for a pending queue item. */
+function pendingFilename(item) {
+    return `${item.id}.json`;
+}
+/** Returns the filename (not path) for a dead queue item. */
+function deadFilename(item) {
+    return `${item.id}.dead`;
+}
+// ── Write item to disk ─────────────────────────────────────────────────────────
+/**
+ * Enqueue a failed ingest chunk to the local retry queue.
+ *
+ * Writes a JSON file to the queue directory. The file is named by a unique ID
+ * derived from the enqueue time and the chunk's sha256 prefix (stable, not random —
+ * so if the same chunk is enqueued twice due to a crash, we don't duplicate items;
+ * but the timestamp disambiguates distinct enqueue events for the same content).
+ *
+ * @param backendUrl  Backend URL that was unreachable.
+ * @param clientSlug  Bound client slug.
+ * @param payload     The ingest payload that failed.
+ * @param lastError   The error message from the failed attempt.
+ * @returns The created QueueItem.
+ */
+export async function enqueueFailedChunk(backendUrl, clientSlug, payload, lastError) {
+    const now = new Date().toISOString();
+    const sha256Prefix = payload.sha256.slice(0, 12);
+    const id = `${Date.now()}-${sha256Prefix}`;
+    const item = {
+        id,
+        backendUrl,
+        clientSlug,
+        enqueuedAt: now,
+        attempts: 0,
+        lastError,
+        payload,
+    };
+    const dir = queueDir(clientSlug);
+    await ensureQueueDir(dir);
+    await writeFile(join(dir, pendingFilename(item)), JSON.stringify(item, null, 2), 'utf8');
+    return item;
+}
+// ── Load queue from disk ───────────────────────────────────────────────────────
+/**
+ * Load all pending queue items from disk.
+ *
+ * Reads all .json files in the queue directory. Dead (.dead) files are NOT
+ * returned here — use loadDeadItems() for those.
+ *
+ * @param clientSlug  Bound client slug.
+ * @returns Array of pending QueueItems, sorted by enqueuedAt ascending.
+ */
+export async function loadPendingItems(clientSlug) {
+    const dir = queueDir(clientSlug);
+    await ensureQueueDir(dir);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const name of entries) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const text = await readFile(join(dir, name), 'utf8');
+            const item = JSON.parse(text);
+            items.push(item);
+        }
+        catch {
+            // Corrupted file — skip silently (do not crash the worker).
+        }
+    }
+    // Oldest first.
+    items.sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt));
+    return items;
+}
+/**
+ * Load all dead items from disk.
+ *
+ * Dead items are .dead files in the queue directory (4xx permanent failures).
+ *
+ * @param clientSlug  Bound client slug.
+ * @returns Array of dead QueueItems.
+ */
+export async function loadDeadItems(clientSlug) {
+    const dir = queueDir(clientSlug);
+    await ensureQueueDir(dir);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const name of entries) {
+        if (!name.endsWith('.dead'))
+            continue;
+        try {
+            const text = await readFile(join(dir, name), 'utf8');
+            const item = JSON.parse(text);
+            items.push(item);
+        }
+        catch {
+            // Corrupted dead file — skip.
+        }
+    }
+    items.sort((a, b) => a.enqueuedAt.localeCompare(b.enqueuedAt));
+    return items;
+}
+// ── Queue status (for ingest_status tool) ─────────────────────────────────────
+/**
+ * Returns a summary of the current queue state for the `ingest_status` MCP tool.
+ *
+ * STORY-013 AC3: reports pending/failed queue depth.
+ *
+ * @param clientSlug  Bound client slug.
+ */
+export async function getQueueStatus(clientSlug) {
+    const [pending, dead] = await Promise.all([
+        loadPendingItems(clientSlug),
+        loadDeadItems(clientSlug),
+    ]);
+    return {
+        pending: pending.length,
+        dead: dead.length,
+        deadItems: dead.map(item => ({
+            id: item.id,
+            filename: item.payload.filename,
+            enqueuedAt: item.enqueuedAt,
+            lastError: item.lastError ?? '(unknown error)',
+        })),
+        pendingItems: pending.map(item => ({
+            id: item.id,
+            filename: item.payload.filename,
+            enqueuedAt: item.enqueuedAt,
+            attempts: item.attempts,
+            lastError: item.lastError,
+        })),
+    };
+}
+// ── Retry worker helpers ───────────────────────────────────────────────────────
+/**
+ * Compute the exponential backoff delay for a given attempt number.
+ *
+ * Attempt 1 → BACKOFF_BASE_MS (1s)
+ * Attempt 2 → 2s
+ * Attempt 3 → 4s
+ * ...capped at BACKOFF_MAX_MS.
+ */
+export function backoffMs(attempt) {
+    return Math.min(BACKOFF_BASE_MS * Math.pow(2, attempt - 1), BACKOFF_MAX_MS);
+}
+/**
+ * Returns true if an item is ready to retry based on its attempt count and the
+ * time of the last attempt.
+ *
+ * An item with 0 attempts is always ready (never tried yet after enqueue).
+ * An item that has been attempted is ready once the backoff window has elapsed.
+ */
+export function isReadyToRetry(item, now = new Date()) {
+    if (item.attempts === 0)
+        return true;
+    if (!item.lastAttemptAt)
+        return true;
+    const lastAttempt = new Date(item.lastAttemptAt).getTime();
+    const delay = backoffMs(item.attempts);
+    return now.getTime() - lastAttempt >= delay;
+}
+/**
+ * Attempt to POST a queued ingest chunk to the backend.
+ *
+ * Distinguishes:
+ *   - success  (2xx)                → remove from queue
+ *   - transient (network / 5xx)    → increment attempts, retry later
+ *   - permanent (4xx)              → mark dead, surface to user (ADR-011)
+ *
+ * @param item   The queue item to retry.
+ * @param token  Current bearer token (acquired silently before calling).
+ */
+export async function attemptRetry(item, token) {
+    const { backendUrl, clientSlug, payload } = item;
+    const url = `${backendUrl}/ingest/${encodeURIComponent(clientSlug)}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${token}`,
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        // Network-level failure (DNS, timeout, ECONNREFUSED) — transient.
+        return {
+            outcome: 'transient',
+            error: `Network error: ${err.message}`,
+        };
+    }
+    // 4xx responses are permanent (auth/access errors — retrying won't help).
+    // ADR-011: these go to dead, not silently retried forever.
+    if (res.status >= 400 && res.status < 500) {
+        let hint = '';
+        try {
+            const bodyText = await res.text();
+            const parsed = JSON.parse(bodyText);
+            hint = (parsed['hint'] ?? parsed['error'] ?? parsed['message'] ?? '');
+        }
+        catch { /* ignore */ }
+        const errorMsg = res.status === 401
+            ? 'Bearer token rejected (401). Run `npx @soundbi/sound-connect login` to re-authenticate.'
+            : res.status === 403
+                ? `Access denied to client "${clientSlug}" (403). ${hint || 'Verify your Sound Connect membership.'}`
+                : `Permanent error HTTP ${res.status}${hint ? `: ${hint}` : ''}.`;
+        return { outcome: 'permanent', error: errorMsg };
+    }
+    // 5xx or other non-2xx — transient.
+    if (!res.ok) {
+        let bodySnippet = '';
+        try {
+            bodySnippet = (await res.text()).slice(0, 120);
+        }
+        catch { /* ignore */ }
+        return {
+            outcome: 'transient',
+            error: `Backend HTTP ${res.status}${bodySnippet ? `: ${bodySnippet}` : ''}`,
+        };
+    }
+    // 2xx success — check for deduplication signal.
+    let deduped = false;
+    try {
+        const bodyText = await res.text();
+        const parsed = JSON.parse(bodyText);
+        deduped = parsed['deduped'] === true;
+    }
+    catch { /* ignore */ }
+    return { outcome: 'success', deduped };
+}
+// ── Item lifecycle helpers ─────────────────────────────────────────────────────
+/** Update the item on disk after an attempt (increments attempts, records error). */
+async function persistUpdatedItem(item) {
+    const dir = queueDir(item.clientSlug);
+    await writeFile(join(dir, pendingFilename(item)), JSON.stringify(item, null, 2), 'utf8');
+}
+/**
+ * Move an item to dead status (.json → .dead).
+ *
+ * Writes the CURRENT item state (including updated lastError) to the .dead file,
+ * then removes the .json file. This ensures the dead file reflects the final error
+ * from the attempt that marked it dead, not the original enqueue error.
+ */
+async function markItemDead(item) {
+    const dir = queueDir(item.clientSlug);
+    const src = join(dir, pendingFilename(item));
+    const dst = join(dir, deadFilename(item));
+    // Write updated state to .dead first (ensures lastError is current).
+    await writeFile(dst, JSON.stringify(item, null, 2), 'utf8');
+    // Remove the .json file (best-effort — if it's already gone, that's fine).
+    await rm(src, { force: true });
+}
+/** Remove a successfully-delivered item from disk. */
+async function removeSuccessfulItem(item) {
+    const dir = queueDir(item.clientSlug);
+    await rm(join(dir, pendingFilename(item)), { force: true });
+}
+/**
+ * Run one sweep of the retry worker:
+ *   1. Load all pending items.
+ *   2. For each item that is ready to retry (backoff elapsed):
+ *      a. Acquire a fresh token (silent).
+ *      b. Attempt the POST.
+ *      c. On success  → remove from disk.
+ *      d. On transient → increment attempts; if exhausted → mark dead.
+ *      e. On permanent → mark dead.
+ *
+ * @param clientSlug    Bound client slug.
+ * @param tokenProvider Async function that returns a fresh access token or null.
+ * @returns Summary of this sweep.
+ */
+export async function runRetrySweep(clientSlug, tokenProvider) {
+    const items = await loadPendingItems(clientSlug);
+    const now = new Date();
+    let delivered = 0;
+    let exhausted = 0;
+    let skipped = 0;
+    let tokenMissing = false;
+    for (const item of items) {
+        if (!isReadyToRetry(item, now)) {
+            skipped++;
+            continue;
+        }
+        // Acquire a fresh token before each item (MSAL handles silent refresh).
+        const token = await tokenProvider();
+        if (!token) {
+            // Not signed in — skip all retries this sweep.
+            tokenMissing = true;
+            skipped += items.length - items.indexOf(item);
+            break;
+        }
+        // Record the attempt.
+        item.attempts++;
+        item.lastAttemptAt = new Date().toISOString();
+        const result = await attemptRetry(item, token);
+        if (result.outcome === 'success') {
+            await removeSuccessfulItem(item);
+            delivered++;
+        }
+        else if (result.outcome === 'permanent') {
+            item.lastError = result.error;
+            await markItemDead(item);
+            exhausted++;
+        }
+        else {
+            // Transient — update attempt count and error on disk.
+            item.lastError = result.error;
+            if (item.attempts >= MAX_RETRY_ATTEMPTS) {
+                // Exhausted all attempts → mark dead.
+                await markItemDead(item);
+                exhausted++;
+            }
+            else {
+                await persistUpdatedItem(item);
+            }
+        }
+    }
+    return { delivered, exhausted, skipped, tokenMissing };
+}
+// ── Background worker (process-lifetime) ──────────────────────────────────────
+let workerTimer = null;
+/**
+ * Start the background retry worker.
+ *
+ * Runs runRetrySweep() every WORKER_INTERVAL_MS milliseconds.
+ * Safe to call multiple times — subsequent calls are no-ops if already running.
+ *
+ * STORY-013 AC2: The worker drains the queue with exponential backoff.
+ * STORY-013 AC4: Items survive restarts; the worker picks them up on next sweep.
+ *
+ * @param clientSlug    Bound client slug.
+ * @param tokenProvider Async function that returns a fresh access token or null.
+ */
+export function startRetryWorker(clientSlug, tokenProvider) {
+    if (workerTimer !== null)
+        return; // already running
+    workerTimer = setInterval(() => {
+        runRetrySweep(clientSlug, tokenProvider).catch((err) => {
+            // Worker errors are logged to stderr — never crash the MCP server.
+            process.stderr.write(`[sound-connect] retry-worker sweep error: ${err.message}\n`);
+        });
+    }, WORKER_INTERVAL_MS);
+    // Do not keep the Node process alive solely for the worker.
+    if (workerTimer.unref)
+        workerTimer.unref();
+}
+/**
+ * Stop the background retry worker.
+ * Called during tests or graceful shutdown.
+ */
+export function stopRetryWorker() {
+    if (workerTimer !== null) {
+        clearInterval(workerTimer);
+        workerTimer = null;
+    }
+}
+// ── Utility: clear all items (for testing only) ────────────────────────────────
+/**
+ * Remove all pending and dead items from the queue directory.
+ * Intended for test teardown only — do not call in production paths.
+ *
+ * @param clientSlug  Bound client slug.
+ */
+export async function clearQueue(clientSlug) {
+    const dir = queueDir(clientSlug);
+    await rm(dir, { recursive: true, force: true });
+}
+// ── Dead letter helpers ────────────────────────────────────────────────────────
+/**
+ * Clear all dead items (permanent failures) from the queue.
+ * Useful after the user re-authenticates and wants to purge the dead letter list.
+ *
+ * @param clientSlug  Bound client slug.
+ */
+export async function clearDeadItems(clientSlug) {
+    const dir = queueDir(clientSlug);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries
+        .filter(name => name.endsWith('.dead'))
+        .map(name => rm(join(dir, name), { force: true })));
+}
+/**
+ * Get the base filename of a queue item (without extension).
+ * Exported for use in tests.
+ */
+export function itemBasename(item) {
+    return basename(pendingFilename(item), '.json');
+}
+//# sourceMappingURL=retry-queue.js.map

package/dist/retry-queue.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Tool registration for the Sound Connect bridge
+ * (STORY-006, STORY-009, STORY-010, STORY-011, STORY-012, STORY-013).
+ *
+ * STORY-010 / ADR-011: When the peer has not authenticated (no valid token at MCP
+ * startup), every tool call returns a clear MCP error directing the user to run
+ * `npx @soundbi/sound-connect login` in a terminal. The server never blocks on an
+ * interactive device-code prompt — that would cause a silent hang because Claude
+ * spawns the stdio server with stdout used for MCP framing (not displayed to the user).
+ *
+ * STORY-009 / ADR-005: One-client-per-instance isolation guard.
+ *   - The bound clientSlug is fixed at process start. There is NO tool or command
+ *     to switch clients in-session — any attempt to target a different slug is blocked.
+ *   - assertResponseSlug() validates every backend response matches the bound slug so
+ *     a misdirected backend response can never leak into this session.
+ *
+ * STORY-011 / ADR-006: ingest_file tool reads a local markdown file or transcript,
+ *   normalizes, computes sha256, attaches provenance, and POSTs to /ingest/:slug.
+ *
+ * STORY-012 / ADR-006: ingest_folder tool bulk-ingests a directory of .md and
+ *   transcript (.txt/.vtt/.srt) files, returning a per-file result table.
+ *
+ * STORY-013 / ADR-011: ingest_file and ingest_folder use queueOnFailure=true so
+ *   transient backend failures (network / 5xx) queue chunks locally for retry.
+ *   ingest_status tool reports pending/dead queue depth.
+ *   The retry worker is started when registerBridgeTools() is called with an
+ *   authenticated session.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BridgeConfig } from './config.js';
+/**
+ * Asserts that a backend response belongs to the bound client slug.
+ *
+ * The backend may return a `client_slug` or `slug` field in its JSON response.
+ * If the value is present and does NOT match the bound slug, this function throws
+ * so the tool handler can reject the response as a cross-client leak.
+ *
+ * If the response carries no slug field (e.g. a list result or an error body),
+ * the check is skipped — the absence of a conflicting slug is not a violation.
+ *
+ * @param responseSlug  The slug found in the backend response (may be undefined).
+ * @param boundSlug     The slug this bridge instance is bound to.
+ * @throws Error if responseSlug is present and does not match boundSlug.
+ */
+export declare function assertResponseSlug(responseSlug: string | undefined, boundSlug: string): void;
+/**
+ * Parses a JSON response body from the backend and asserts the slug matches.
+ * Returns the parsed body so callers do not have to parse twice.
+ *
+ * @param text       Raw response text from the backend.
+ * @param boundSlug  The slug this bridge instance is bound to.
+ * @returns Parsed JSON object (or null if parsing fails — slug check is skipped).
+ */
+export declare function parseAndAssertResponseSlug(text: string, boundSlug: string): unknown;
+/**
+ * Register bridge tools on the MCP server.
+ *
+ * All tools are visible in tools/list immediately (required by Claude Desktop/Code
+ * to show the server as functional). When `isAuthenticated` is false, every tool
+ * call returns the NOT_SIGNED_IN_TEXT error — never blocks or hangs (STORY-010).
+ * When `isAuthenticated` is true, tool calls return NOT_YET_IMPLEMENTED_TEXT until
+ * STORY-008 wires real proxy behaviour.
+ *
+ * STORY-009 / ADR-005: There is deliberately NO "select_client", "switch_client",
+ * or equivalent tool registered here. The bound slug is fixed at process start and
+ * cannot be changed in-session. Any outbound call that receives a response for a
+ * different slug must call assertResponseSlug() / parseAndAssertResponseSlug() to
+ * reject the response before returning it to Claude.
+ *
+ * @param server          The McpServer instance.
+ * @param config          Bridge config (backendUrl, clientSlug) — fixed at startup.
+ * @param isAuthenticated Whether a valid cached token was found at startup (STORY-010).
+ */
+export declare function registerBridgeTools(server: McpServer, config: BridgeConfig, isAuthenticated: boolean): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,MAAM,GAChB,IAAI,CAQN;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAqBT;AA+BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,OAAO,GACvB,IAAI,CA8SN"}