twinclaw 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# 🦅 TwinClaw
+
+**Native Agentic Gateway | Multi-Modal Hooks | Proactive Memory**
+
+TwinClaw is a highly autonomous local-first AI agent designed for power users who want an "unstoppable" personal assistant that navigates between multiple LLMs, messaging platforms (Telegram/WhatsApp), and its own persistent RAG memory.
+
+---
+
+## ⚡ Quick Start (Windows Only)
+
+To install and run TwinClaw with a single command, run the following in your terminal:
+
+### **Windows (PowerShell)**
+```powershell
+npm twinclaw install
+```
+
+---
+
+## 🛠 Features
+
+- **Double-Layered Intelligence**: Native model routing through **OpenRouter**, **Gemini**, and **Modal** with automatic 429 retries and fallbacks.
+- **Voice-First**: Seamless integration with **ElevenLabs** (Text-to-Speech) and **Groq** (Speech-to-Text).
+- **Ubiquitous Access**: Control your agent or receive proactive notifications via **Telegram** and **WhatsApp**.
+- **Agentic Skills**: Extensible Skill system (MCP-compatible) allowing the agent to read files, search the web, and manage its own memory.
+- **Local Persistence**: Zero-cloud knowledge graph and memory storage using **SQLite** with **sqlite-vec**.
+
+---
+
+## 📖 Guided Setup
+
+When you first run TwinClaw, it will automatically start a **Guided Setup Wizard**. You don't need to manually create any `.env` files. The wizard will prompt you for:
+
+1.  **API Keys**: Groq, OpenRouter, Gemini, ElevenLabs.
+2.  **Messaging**: Telegram Bot Token and optional bootstrap allowlist IDs.
+3.  **Security**: Generates a master encryption key for your local vault.
+4.  **Skills**: Auto-registers built-in skills for immediate use.
+
+TwinClaw now defaults to `dmPolicy: "pairing"` for Telegram/WhatsApp DMs. Unknown senders receive a pairing code and must be explicitly approved:
+
+```powershell
+twinclaw pairing list telegram
+twinclaw pairing approve telegram <CODE>
+```
+
+---
+
+## 🏗 Developer Architecture
+
+TwinClaw is built with:
+- **Runtime**: Node.js (v22+)
+- **ORCH**: AntiGravity / OpenClaw-inspired
+- **Database**: SQLite (Vector-ready)
+- **Framework**: TypeScript (ESM)
+
+For detailed technical specifications, see [docs/TwinBot-blueprint.md](docs/TwinBot-blueprint.md).
+
+Operational runbooks:
+- [MVP Release Checklist](docs/mvp-release-checklist.md)
+- [Release & Rollback Runbook](docs/release-rollback-runbook.md)
+- [Credential Rotation Runbook](docs/rotation-runbook.md)
+
+---
+
+## License
+ISC

package/bin/npm-twinclaw.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { runTwinbotCli } from './run-twinbot-cli.js';
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+  console.log(`npm twinclaw usage:
+  npm twinclaw install [--non-interactive] [--skip-onboard] [--json]
+`);
+  process.exit(0);
+}
+
+if (args[0] === 'install') {
+  runTwinbotCli(['install', ...args.slice(1)]);
+} else {
+  runTwinbotCli(args);
+}

package/bin/run-twinbot-cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function resolvePackageRoot() {
+  const currentFile = fileURLToPath(import.meta.url);
+  return path.resolve(path.dirname(currentFile), '..');
+}
+
+export function runTwinbotCli(args) {
+  const packageRoot = resolvePackageRoot();
+  const sourceEntry = path.join(packageRoot, 'src', 'index.ts');
+  const tsxCli = path.join(packageRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+  const distEntry = path.join(packageRoot, 'dist', 'index.js');
+
+  let nodeArgs;
+  if (existsSync(sourceEntry) && existsSync(tsxCli)) {
+    nodeArgs = [tsxCli, sourceEntry, ...args];
+  } else if (existsSync(distEntry)) {
+    nodeArgs = [distEntry, ...args];
+  } else {
+    console.error('[TwinClaw] Unable to locate CLI entrypoint (expected src/index.ts or dist/index.js).');
+    process.exit(1);
+    return;
+  }
+
+  const result = spawnSync(process.execPath, nodeArgs, {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: 'inherit',
+  });
+
+  process.exit(result.status ?? 1);
+}

package/bin/twinbot.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runTwinbotCli } from './run-twinbot-cli.js';
+
+runTwinbotCli(process.argv.slice(2));

package/bin/twinclaw.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runTwinbotCli } from './run-twinbot-cli.js';
+
+runTwinbotCli(process.argv.slice(2));

package/dist/api/handlers/browser.js

@@ -0,0 +1,160 @@
+import { BrowserReferenceError } from '../../services/browser-service.js';
+import { sendOk, sendError, mapError } from '../shared.js';
+import { logThought } from '../../utils/logger.js';
+import path from 'node:path';
+/**
+ * POST /browser/snapshot
+ *
+ * Takes a screenshot and returns the accessibility tree of the current
+ * (or newly navigated) page.
+ *
+ * Body:
+ *   url?:      string  — Navigate to this URL before taking a snapshot.
+ *   fullPage?: boolean — Whether to capture the full page. Default true.
+ */
+export function handleBrowserSnapshot(deps) {
+    return async (req, res) => {
+        try {
+            const body = (req.body ?? {});
+            if (body.url !== undefined && typeof body.url !== 'string') {
+                sendError(res, 'Field "url" must be a string.', 400);
+                return;
+            }
+            if (body.fullPage !== undefined && typeof body.fullPage !== 'boolean') {
+                sendError(res, 'Field "fullPage" must be a boolean.', 400);
+                return;
+            }
+            if (body.url) {
+                await deps.browserService.navigate(body.url);
+                await logThought(`[API] Browser navigated to: ${body.url}`);
+            }
+            const screenshotPath = path.resolve('memory', `snapshot_${Date.now()}.png`);
+            const fullPage = body.fullPage !== false;
+            const result = await deps.browserService.takeScreenshotForVlm(screenshotPath, fullPage);
+            const tree = await deps.browserService.getAccessibilityTree();
+            const referenceContext = await deps.browserService.captureSnapshotReferenceContext();
+            const data = {
+                snapshotId: referenceContext.snapshotId,
+                screenshotPath: result.path,
+                viewport: result.viewport,
+                accessibilityTree: typeof tree === 'string' ? tree : JSON.stringify(tree),
+                references: referenceContext.references,
+            };
+            await logThought(`[API] Browser snapshot taken: ${screenshotPath} (snapshotId=${referenceContext.snapshotId}, refs=${referenceContext.references.length}).`);
+            sendOk(res, data, 200);
+        }
+        catch (err) {
+            const mapped = mapError(err);
+            await logThought(`[API] Browser snapshot failed: ${mapped.message}`);
+            sendError(res, mapped.message, mapped.status);
+        }
+    };
+}
+/**
+ * POST /browser/click
+ *
+ * Clicks an element on the current browser page.
+ *
+ * Body (one of):
+ *   selector?: string — CSS selector to click.
+ *   x?, y?:   number — Absolute viewport coordinates to click.
+ */
+export function handleBrowserClick(deps) {
+    return async (req, res) => {
+        try {
+            const body = (req.body ?? {});
+            if (body.selector !== undefined && typeof body.selector !== 'string') {
+                sendError(res, 'Field "selector" must be a string when provided.', 400);
+                return;
+            }
+            if (body.ref !== undefined && typeof body.ref !== 'string') {
+                sendError(res, 'Field "ref" must be a string when provided.', 400);
+                return;
+            }
+            if (body.snapshotId !== undefined && typeof body.snapshotId !== 'string') {
+                sendError(res, 'Field "snapshotId" must be a string when provided.', 400);
+                return;
+            }
+            if (body.x !== undefined && typeof body.x !== 'number') {
+                sendError(res, 'Field "x" must be a number when provided.', 400);
+                return;
+            }
+            if (body.y !== undefined && typeof body.y !== 'number') {
+                sendError(res, 'Field "y" must be a number when provided.', 400);
+                return;
+            }
+            const hasReferenceMode = typeof body.ref === 'string' && body.ref.trim().length > 0;
+            const hasSelectorMode = typeof body.selector === 'string' && body.selector.trim().length > 0;
+            const hasCoordinateMode = typeof body.x === 'number' && typeof body.y === 'number';
+            const selectedModes = [hasReferenceMode, hasSelectorMode, hasCoordinateMode].filter(Boolean).length;
+            if (selectedModes > 1) {
+                sendError(res, 'Provide only one click mode: "ref", "selector", or both "x" and "y".', 400);
+                return;
+            }
+            if (hasReferenceMode && body.ref) {
+                const result = await deps.browserService.clickByReference({
+                    ref: body.ref,
+                    snapshotId: body.snapshotId,
+                });
+                await logThought(`[API] Browser clicked reference ${body.ref} on snapshot ${result.snapshotId} (selector=${result.reference.selector}).`);
+                const data = {
+                    clicked: true,
+                    method: 'reference',
+                    detail: result.reference.selector,
+                    ref: result.reference.ref,
+                    snapshotId: result.snapshotId,
+                };
+                sendOk(res, data, 200);
+                return;
+            }
+            if (hasSelectorMode && body.selector) {
+                await deps.browserService.click(body.selector);
+                await logThought(`[API] Browser clicked selector: ${body.selector}. Prefer reference mode from /browser/snapshot for deterministic actions.`);
+                const data = {
+                    clicked: true,
+                    method: 'selector',
+                    detail: `${body.selector} (selector mode; prefer ref mode for deterministic targeting)`,
+                };
+                sendOk(res, data, 200);
+                return;
+            }
+            if (hasCoordinateMode && typeof body.x === 'number' && typeof body.y === 'number') {
+                await deps.browserService.clickAt({ x: body.x, y: body.y });
+                await logThought(`[API] Browser clicked at (${body.x}, ${body.y}). Prefer reference mode from /browser/snapshot when available.`);
+                const data = {
+                    clicked: true,
+                    method: 'coordinates',
+                    detail: `(${body.x}, ${body.y}) (coordinates mode; prefer ref mode for deterministic targeting)`,
+                };
+                sendOk(res, data, 200);
+                return;
+            }
+            sendError(res, 'Provide one click mode: "ref" (string), "selector" (string), or "x" and "y" (number).', 400);
+        }
+        catch (err) {
+            if (err instanceof BrowserReferenceError) {
+                const mapped = mapBrowserReferenceError(err);
+                await logThought(`[API] Browser click reference failed: ${mapped.message}`);
+                sendError(res, mapped.message, mapped.status);
+                return;
+            }
+            const mapped = mapError(err);
+            await logThought(`[API] Browser click failed: ${mapped.message}`);
+            sendError(res, mapped.message, mapped.status);
+        }
+    };
+}
+function mapBrowserReferenceError(error) {
+    switch (error.code) {
+        case 'snapshot_context_missing':
+            return { status: 409, message: error.message };
+        case 'snapshot_context_stale':
+            return { status: 409, message: error.message };
+        case 'reference_not_found':
+            return { status: 404, message: error.message };
+        case 'reference_unresolved':
+            return { status: 422, message: error.message };
+        default:
+            return { status: 500, message: error.message };
+    }
+}

package/dist/api/handlers/callback.js

@@ -0,0 +1,80 @@
+import { sendOk, sendError } from '../shared.js';
+import { logThought } from '../../utils/logger.js';
+import { recordCallbackReceipt, getCallbackReceipt, getDelivery, updateDeliveryState } from '../../services/db.js';
+/**
+ * POST /callback/webhook
+ *
+ * Ingests completion events from long-running external tasks.
+ * This endpoint is protected by the `requireSignature` middleware.
+ *
+ * Body:
+ *   eventType: string                       — e.g. 'deploy.complete', 'scrape.done'
+ *   taskId:    string                       — Correlating task identifier.
+ *   status:    'completed' | 'failed' | 'progress'
+ *   result?:   unknown                      — Arbitrary payload on success.
+ *   error?:    string                       — Error description on failure.
+ */
+export function handleWebhookCallback(deps) {
+    return async (req, res) => {
+        const body = req.body;
+        // ── Validate required fields ────────────────────────────────────────────
+        if (!body.eventType || typeof body.eventType !== 'string') {
+            sendError(res, 'Missing or invalid "eventType" (string).', 400);
+            return;
+        }
+        if (!body.taskId || typeof body.taskId !== 'string') {
+            sendError(res, 'Missing or invalid "taskId" (string).', 400);
+            return;
+        }
+        const validStatuses = new Set(['completed', 'failed', 'progress']);
+        if (!body.status || !validStatuses.has(body.status)) {
+            sendError(res, 'Missing or invalid "status" (completed | failed | progress).', 400);
+            return;
+        }
+        // ── Idempotency Check ───────────────────────────────────────────────────
+        const idempotencyKey = `${body.taskId}:${body.eventType}:${body.status}`;
+        const existingReceipt = getCallbackReceipt(idempotencyKey);
+        if (existingReceipt) {
+            await logThought(`[API] Webhook rejected — duplicate payload detected for key: ${idempotencyKey}`);
+            const data = {
+                accepted: true,
+                eventType: body.eventType,
+                taskId: body.taskId,
+                outcome: 'duplicate',
+            };
+            sendOk(res, data, 200);
+            return;
+        }
+        await logThought(`[API] Webhook received — event: ${body.eventType}, task: ${body.taskId}, status: ${body.status}`);
+        // ── Forward into the gateway as a system-level message ──────────────────
+        try {
+            const sessionId = `webhook:${body.taskId}`;
+            const summaryText = `[Webhook Callback] Event: ${body.eventType} | Task: ${body.taskId} | Status: ${body.status}` +
+                (body.result ? `\nResult: ${JSON.stringify(body.result)}` : '') +
+                (body.error ? `\nError: ${body.error}` : '');
+            // ── Reconciliation ───────────────────────────────────────────────────
+            const delivery = getDelivery(body.taskId);
+            if (delivery) {
+                const newState = body.status === 'completed' ? 'sent' : body.status === 'failed' ? 'failed' : delivery.state;
+                updateDeliveryState(body.taskId, newState, newState === 'sent' ? new Date().toISOString() : null);
+                await logThought(`[API] Webhook reconciled delivery queue item: ${body.taskId} -> ${newState}`);
+            }
+            // Fire-and-forget: process the webhook payload as a conversation turn
+            void deps.gateway.processText(sessionId, summaryText);
+            recordCallbackReceipt(idempotencyKey, 202, 'accepted');
+            const data = {
+                accepted: true,
+                eventType: body.eventType,
+                taskId: body.taskId,
+                outcome: 'accepted',
+            };
+            sendOk(res, data, 202);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await logThought(`[API] Webhook processing error: ${message}`);
+            recordCallbackReceipt(idempotencyKey, 500, 'rejected');
+            sendError(res, `Webhook processing error: ${message}`, 500);
+        }
+    };
+}

package/dist/api/handlers/config-validate.js

@@ -0,0 +1,19 @@
+import { validateRuntimeConfig } from '../../config/env-validator.js';
+import { sendOk } from '../shared.js';
+/** GET /config/validate — Returns a full runtime config validation report. */
+export function handleConfigValidate() {
+    return (_req, res) => {
+        const result = validateRuntimeConfig();
+        const data = {
+            ok: result.ok,
+            presentKeys: result.presentKeys,
+            issues: result.issues,
+            activeFeatures: result.activeFeatures,
+            fatalIssues: result.fatalIssues,
+            validatedAt: result.validatedAt,
+        };
+        // Use 200 even when validation has issues; the `ok` field in the body
+        // communicates the config health to callers.
+        sendOk(res, data);
+    };
+}

package/dist/api/handlers/health.js

@@ -0,0 +1,117 @@
+import { getSecretVaultService } from '../../services/secret-vault.js';
+import { sendOk } from '../shared.js';
+const startTime = Date.now();
+/** GET /health — Returns system health status and subsystem summaries. */
+export function handleHealth(deps) {
+    return async (_req, res) => {
+        const summary = deps.skillRegistry.summary();
+        const servers = deps.mcpManager.listServers();
+        const packageDiagnostics = await deps.mcpManager.getSkillPackageDiagnostics();
+        const secretDiagnostics = getSecretVaultService().getDiagnostics(['API_SECRET']);
+        const budgetSnapshot = deps.budgetGovernor?.getSnapshot('health');
+        const routingSnapshot = deps.modelRouter?.getHealthSnapshot();
+        const backupDiagnostics = deps.localStateBackup
+            ? await deps.localStateBackup.getDiagnostics(5)
+            : null;
+        const heartbeatRunning = deps.heartbeat.scheduler
+            .listJobs()
+            .some((j) => j.status === 'running');
+        const data = {
+            status: servers.some((s) => s.state === 'error') ||
+                packageDiagnostics.blockedPackageCount > 0 ||
+                secretDiagnostics.health.hasIssues ||
+                budgetSnapshot?.directive.severity === 'hard_limit' ||
+                (routingSnapshot?.consecutiveFailures ?? 0) >= 3 ||
+                backupDiagnostics?.status === 'degraded'
+                ? 'degraded'
+                : 'ok',
+            uptimeSec: Math.floor((Date.now() - startTime) / 1000),
+            memoryUsageMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
+            heartbeat: { running: heartbeatRunning },
+            skills: {
+                builtin: summary.builtin ?? 0,
+                mcp: summary.mcp ?? 0,
+                total: deps.skillRegistry.size,
+            },
+            skillPackages: {
+                installed: packageDiagnostics.installed.length,
+                active: packageDiagnostics.activePackageCount,
+                blocked: packageDiagnostics.blockedPackageCount,
+                warnings: packageDiagnostics.warnings,
+                violations: packageDiagnostics.violations.map((violation) => ({
+                    packageName: violation.packageName,
+                    version: violation.version,
+                    code: violation.code,
+                    message: violation.message,
+                    remediation: violation.remediation,
+                })),
+            },
+            secrets: {
+                status: secretDiagnostics.health.hasIssues ? 'degraded' : 'ok',
+                missingRequired: secretDiagnostics.health.missingRequired,
+                expired: secretDiagnostics.health.expired,
+                warnings: secretDiagnostics.health.warnings,
+                total: secretDiagnostics.total,
+                active: secretDiagnostics.active,
+                dueForRotation: secretDiagnostics.dueForRotation,
+            },
+            budget: budgetSnapshot
+                ? {
+                    severity: budgetSnapshot.directive.severity,
+                    profile: budgetSnapshot.directive.profile,
+                    pacingDelayMs: budgetSnapshot.directive.pacingDelayMs,
+                    manualProfile: budgetSnapshot.manualProfile,
+                    daily: budgetSnapshot.daily,
+                    session: budgetSnapshot.session,
+                    providers: budgetSnapshot.providers,
+                }
+                : undefined,
+            routing: routingSnapshot,
+            backups: backupDiagnostics
+                ? {
+                    status: backupDiagnostics.status,
+                    lastSnapshotAt: backupDiagnostics.lastSnapshotAt,
+                    lastRestoreAt: backupDiagnostics.lastRestoreAt,
+                    validationFailureCount: backupDiagnostics.validationFailureCount,
+                    recommendationCount: backupDiagnostics.recommendations.length,
+                }
+                : undefined,
+            mcpServers: servers.map((s) => ({
+                id: s.id,
+                name: s.name,
+                state: s.state,
+                toolCount: s.toolCount,
+                health: {
+                    circuit: s.health.state,
+                    failureCount: s.health.metrics.failureCount,
+                    remainingCooldownMs: s.health.remainingCooldownMs,
+                },
+            })),
+        };
+        sendOk(res, data);
+    };
+}
+/** GET /health/live — Fast liveness probe for orchestrators (e.g. k8s) */
+export function handleLiveness() {
+    return (_req, res) => {
+        sendOk(res, { status: 'alive', uptimeSec: Math.floor((Date.now() - startTime) / 1000) });
+    };
+}
+/** GET /health/ready — Readiness probe for load balancers */
+export function handleReadiness(deps) {
+    return (_req, res) => {
+        const heartbeatRunning = deps.heartbeat.scheduler
+            .listJobs()
+            .some((j) => j.status === 'running');
+        if (!heartbeatRunning) {
+            res.status(503).json({ status: 'not_ready', reason: 'Heartbeat scheduler offline' });
+            return;
+        }
+        const secretDiagnostics = getSecretVaultService().getDiagnostics(['API_SECRET']);
+        if (secretDiagnostics.health.missingRequired.length > 0) {
+            res.status(503).json({ status: 'not_ready', reason: 'Missing critical secrets' });
+            return;
+        }
+        sendOk(res, { status: 'ready' });
+    };
+}

package/dist/api/handlers/local-state-backup.js

@@ -0,0 +1,118 @@
+import { sendError, sendOk } from '../shared.js';
+const ALLOWED_SCOPES = new Set([
+    'identity',
+    'memory',
+    'runtime-db',
+    'policy-profiles',
+    'mcp-config',
+    'skill-packages',
+]);
+function requireBackupService(deps, res) {
+    if (!deps.backupService) {
+        sendError(res, 'Local state backup service is not initialized.', 503);
+        return null;
+    }
+    return deps.backupService;
+}
+function parseSnapshotRequestBody(body) {
+    if (!body || typeof body !== 'object') {
+        return {};
+    }
+    const candidate = body;
+    if (candidate.retentionLimit === undefined) {
+        return {};
+    }
+    if (typeof candidate.retentionLimit !== 'number' ||
+        !Number.isFinite(candidate.retentionLimit) ||
+        candidate.retentionLimit <= 0) {
+        throw new Error("Field 'retentionLimit' must be a positive number.");
+    }
+    return { retentionLimit: Math.floor(candidate.retentionLimit) };
+}
+function parseRestoreRequestBody(body) {
+    if (!body || typeof body !== 'object') {
+        return {};
+    }
+    const candidate = body;
+    const request = {};
+    if (candidate.snapshotId !== undefined) {
+        if (typeof candidate.snapshotId !== 'string' || candidate.snapshotId.trim().length === 0) {
+            throw new Error("Field 'snapshotId' must be a non-empty string when provided.");
+        }
+        request.snapshotId = candidate.snapshotId.trim();
+    }
+    if (candidate.dryRun !== undefined) {
+        if (typeof candidate.dryRun !== 'boolean') {
+            throw new Error("Field 'dryRun' must be boolean when provided.");
+        }
+        request.dryRun = candidate.dryRun;
+    }
+    if (candidate.scopes !== undefined) {
+        if (!Array.isArray(candidate.scopes)) {
+            throw new Error("Field 'scopes' must be an array when provided.");
+        }
+        const scopes = [];
+        for (const scope of candidate.scopes) {
+            if (typeof scope !== 'string' || !ALLOWED_SCOPES.has(scope)) {
+                throw new Error(`Unsupported backup scope '${String(scope)}'.`);
+            }
+            scopes.push(scope);
+        }
+        request.scopes = [...new Set(scopes)];
+    }
+    return request;
+}
+export function handleLocalStateBackupDiagnostics(deps) {
+    return async (_req, res) => {
+        const service = requireBackupService(deps, res);
+        if (!service) {
+            return;
+        }
+        const diagnostics = await service.getDiagnostics();
+        const data = { diagnostics };
+        sendOk(res, data);
+    };
+}
+export function handleLocalStateCreateSnapshot(deps) {
+    return async (req, res) => {
+        const service = requireBackupService(deps, res);
+        if (!service) {
+            return;
+        }
+        try {
+            const request = parseSnapshotRequestBody(req.body);
+            const snapshot = await service.createSnapshot({
+                trigger: 'manual',
+                retentionLimit: request.retentionLimit,
+            });
+            const data = { snapshot };
+            sendOk(res, data, 201);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, message, 400);
+        }
+    };
+}
+export function handleLocalStateRestoreSnapshot(deps) {
+    return async (req, res) => {
+        const service = requireBackupService(deps, res);
+        if (!service) {
+            return;
+        }
+        try {
+            const request = parseRestoreRequestBody(req.body);
+            const result = await service.restoreSnapshot(request);
+            const data = { request, result };
+            if (result.status === 'failed') {
+                sendError(res, result.validationErrors.join(' | ') || 'Restore failed.', 409);
+                return;
+            }
+            sendOk(res, data);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, message, 400);
+        }
+    };
+}