@flame0510/project-aether 1.1.9

package/app/api/gateway/provider/route.ts

@@ -0,0 +1,209 @@
+/**
+ * Gateway Provider API
+ *
+ * GET  /api/gateway/provider   — list providers and their model config
+ * POST /api/gateway/provider   — set/remove API key + sync models + sync agent
+ * PUT  /api/gateway/provider   — toggle individual model on/off + sync
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { execSync } from 'child_process';
+import { readProviderKeys, writeProviderKeys } from './keys';
+import { syncAllAgents } from '../sync';
+import { detectProviderGatewayUrl } from '@/lib/docker-utils';
+import { getPricing } from '@/lib/model-pricing';
+import { loadModelsConfig, toggleModelOverride, type ModelConfigEntry } from '@/lib/model-catalogue';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                             */
+/* ------------------------------------------------------------------ */
+
+interface ProviderEnvConfig {
+  envKey: string;
+  label: string;
+  baseUrl: string;
+  authHeader: string;
+  docsUrl: string;
+}
+
+const PROVIDER_CONFIGS: Record<string, ProviderEnvConfig> = {
+  google: {
+    envKey: 'PROVIDER_GOOGLE_API_KEY',
+    label: 'Google Gemini',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    authHeader: 'x-goog-api-key',
+    docsUrl: 'https://aistudio.google.com/app/apikey',
+  },
+  deepseek: {
+    envKey: 'PROVIDER_DEEPSEEK_API_KEY',
+    label: 'DeepSeek',
+    baseUrl: 'https://api.deepseek.com',
+    authHeader: 'Authorization',
+    docsUrl: 'https://platform.deepseek.com/api_keys',
+  },
+  openrouter: {
+    envKey: 'PROVIDER_OPENROUTER_API_KEY',
+    label: 'OpenRouter',
+    baseUrl: 'https://openrouter.ai/api',
+    authHeader: 'Authorization',
+    docsUrl: 'https://openrouter.ai/keys',
+  },
+  openai: {
+    envKey: 'PROVIDER_OPENAI_API_KEY',
+    label: 'OpenAI',
+    baseUrl: 'https://api.openai.com',
+    authHeader: 'Authorization',
+    docsUrl: 'https://platform.openai.com/api-keys',
+  },
+  anthropic: {
+    envKey: 'PROVIDER_ANTHROPIC_API_KEY',
+    label: 'Anthropic',
+    baseUrl: 'https://api.anthropic.com',
+    authHeader: 'x-api-key',
+    docsUrl: 'https://console.anthropic.com/settings/keys',
+  },
+  groq: {
+    envKey: 'PROVIDER_GROQ_API_KEY',
+    label: 'Groq',
+    baseUrl: 'https://api.groq.com/openai',
+    authHeader: 'Authorization',
+    docsUrl: 'https://console.groq.com/keys',
+  },
+  kimi: {
+    envKey: 'PROVIDER_KIMI_API_KEY',
+    label: 'Kimi',
+    baseUrl: 'https://api.moonshot.cn',
+    authHeader: 'Authorization',
+    docsUrl: 'https://platform.kimi.com/console/api-keys',
+  },
+  glm: {
+    envKey: 'PROVIDER_GLM_API_KEY',
+    label: 'GLM (Z.AI)',
+    baseUrl: 'https://api.z.ai',
+    authHeader: 'Authorization',
+    docsUrl: 'https://z.ai/manage-apikey/apikey-list',
+  },
+  qwen: {
+    envKey: 'PROVIDER_QWEN_API_KEY',
+    label: 'Qwen',
+    baseUrl: 'https://dashscope.aliyuncs.com',
+    authHeader: 'Authorization',
+    docsUrl: 'https://bailian.console.aliyun.com/cn-beijing?tab=model#/api-key',
+  },
+  rev4a: {
+    envKey: 'REV4A_API_KEY',
+    label: 'REV4A API KEY',
+    baseUrl: detectProviderGatewayUrl(),
+    authHeader: 'Authorization',
+    docsUrl: '',
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+function getProviderApiKey(providerName: string): string | null {
+  const keys = readProviderKeys();
+  return keys[providerName] || null;
+}
+
+function setProviderApiKey(providerName: string, value: string | null): void {
+  const keys = readProviderKeys();
+  if (value === null) {
+    delete keys[providerName];
+  } else {
+    keys[providerName] = value;
+  }
+  writeProviderKeys(keys);
+}
+
+function restartService(): { stdout: string; stderr: string } {
+  try {
+    const stdout = execSync('sudo systemctl restart rev4a.service 2>&1', { timeout: 15000, maxBuffer: 64 * 1024 }).toString();
+    return { stdout, stderr: '' };
+  } catch (e: unknown) {
+    const err = e as { stdout?: string; stderr?: string; message?: string };
+    return { stdout: err.stdout?.toString() || '', stderr: err.stderr?.toString() || err.message || 'Unknown error' };
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Routes                                                             */
+/* ------------------------------------------------------------------ */
+
+export async function GET(request: NextRequest) {
+  const allModels = loadModelsConfig();
+  const providerKeys = readProviderKeys();
+  const providers = Object.entries(PROVIDER_CONFIGS).map(([key, cfg]) => {
+    const providerModels = allModels.filter((m) => m.provider === key);
+    return {
+      provider: key, label: cfg.label, configured: !!providerKeys[key],
+      baseUrl: cfg.baseUrl, docsUrl: cfg.docsUrl,
+      models: providerModels.map((m) => {
+        const entry: Record<string, unknown> = { id: m.id, name: m.name, enabled: m.enabled };
+        const p = getPricing(m.id);
+        if (p) entry.pricing = p;
+        if (m.modality) entry.modality = m.modality;
+        return entry;
+      }),
+      ...(providerKeys[key] ? { apiKey: providerKeys[key] } : {}),
+    };
+  });
+  return NextResponse.json({ providers });
+}
+
+export async function POST(request: NextRequest) {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  try {
+    const body: { provider?: string; apiKey?: string; _syncOnly?: boolean } = await request.json();
+
+    if (body._syncOnly) {
+      const syncResults = syncAllAgents();
+      return NextResponse.json({ status: 'ok', sync: syncResults });
+    }
+
+    const providerName = body.provider;
+    if (!providerName || !PROVIDER_CONFIGS[providerName]) {
+      return NextResponse.json({ status: 'error', error: `Unknown provider: ${providerName}. Known: ${Object.keys(PROVIDER_CONFIGS).join(', ')}` }, { status: 400 });
+    }
+    const apiKeyValue = body.apiKey;
+    const isRemove = !apiKeyValue || apiKeyValue.trim() === '';
+    setProviderApiKey(providerName, isRemove ? null : apiKeyValue!.trim());
+    let syncResults: string[] = [];
+    try {
+      syncResults = syncAllAgents();
+    } catch (se) {
+      syncResults = [`Sync error: ${se instanceof Error ? se.message : String(se)}`];
+    }
+    return NextResponse.json({
+      status: 'ok', provider: providerName, configured: !isRemove,
+      sync: syncResults,
+    });
+  } catch (e: unknown) {
+    return NextResponse.json({ status: 'error', error: e instanceof Error ? e.message : String(e) }, { status: 500 });
+  }
+}
+
+export async function PUT(request: NextRequest) {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  try {
+    const body: { modelId?: string; enabled?: boolean } = await request.json();
+    const { modelId, enabled } = body;
+    if (!modelId) return NextResponse.json({ status: 'error', error: 'modelId is required' }, { status: 400 });
+    if (typeof enabled !== 'boolean') return NextResponse.json({ status: 'error', error: 'enabled (boolean) is required' }, { status: 400 });
+
+    const models = loadModelsConfig();
+    const idx = models.findIndex((m) => m.id === modelId);
+    if (idx === -1) return NextResponse.json({ status: 'error', error: `Model not found: ${modelId}` }, { status: 404 });
+
+    toggleModelOverride(modelId, enabled);
+    const syncResults = syncAllAgents();
+    return NextResponse.json({ status: 'ok', modelId, enabled, provider: models[idx].provider, sync: syncResults });
+  } catch (e: unknown) {
+    return NextResponse.json({ status: 'error', error: e instanceof Error ? e.message : String(e) }, { status: 500 });
+  }
+}

package/app/api/gateway/route.ts

@@ -0,0 +1,223 @@
+import { type NextRequest } from "next/server";
+/**
+ * Gateway Status API
+ *
+ * Aggregates live model/provider state from Rev4a agent containers.
+ * Only queries containers with AGENT_ID label — no hardcoded container names.
+ *
+ * GET /api/gateway
+ */
+import { NextResponse } from 'next/server';
+import { execSync } from 'child_process';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+
+interface GatewayModel {
+  key: string;
+  provider: string;
+  model: string;
+  available: boolean;
+}
+
+interface GatewayProvider {
+  provider: string;
+  kind: string;
+  detail: string;
+  profiles: number;
+  labels: string[];
+}
+
+interface GatewayAgentStatus {
+  agentId: string;
+  containerName: string;
+  state: string;
+  defaultModel: string;
+  fallbacks: string[];
+  allowed: string[];
+  aliases: Record<string, string>;
+  providers: GatewayProvider[];
+  error?: string;
+}
+
+interface ApiKeyStatus {
+  provider: string;
+  configured: boolean;
+}
+
+/** Run a command inside a Docker container */
+function dockerExec(container: string, cmd: string, timeout = 15000): string {
+  try {
+    return execSync(
+      `docker exec ${container} sh -c ${JSON.stringify(cmd)}`,
+      { timeout, maxBuffer: 1024 * 1024, encoding: 'utf-8' },
+    );
+  } catch {
+    return '';
+  }
+}
+
+/** Get Docker containers with AGENT_ID label — only Rev4a-managed agents */
+function getAgents(): { agentId: string; containerName: string; state: string }[] {
+  try {
+    const raw = execSync(
+      `docker ps --filter "label=AGENT_ID" --format '{{.Label "AGENT_ID"}}|{{.Names}}|{{.State}}'`,
+      { timeout: 5000, maxBuffer: 64 * 1024, encoding: 'utf-8' },
+    ).trim();
+    if (!raw) return [];
+    return raw.split('\n').map((line) => {
+      const [agentId, containerName, state] = line.split('|');
+      return { agentId, containerName, state };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/** Query an agent container for model status */
+function getAgentStatus(agent: { agentId: string; containerName: string; state: string }): GatewayAgentStatus | null {
+  const raw = dockerExec(agent.containerName, 'openclaw models status --json', 8000);
+  if (!raw) return null;
+  try {
+    const data = JSON.parse(raw);
+    const authProviders: Record<string, unknown>[] = data.auth?.providers ?? [];
+    const providers: GatewayProvider[] = authProviders.map((p: Record<string, unknown>) => ({
+      provider: String(p.provider ?? ''),
+      kind: String((p.effective as Record<string, unknown>)?.kind ?? ''),
+      detail: String((p.effective as Record<string, unknown>)?.detail ?? ''),
+      profiles: Number((p.profiles as Record<string, unknown>)?.count ?? 0),
+      labels: (p.profiles as Record<string, unknown>)?.labels as string[] ?? [],
+    }));
+
+    const aliasesRaw = data.aliases ?? {};
+    const aliases: Record<string, string> = {};
+    for (const [k, v] of Object.entries(aliasesRaw)) {
+      aliases[k] = String(v);
+    }
+
+    return {
+      agentId: agent.agentId,
+      containerName: agent.containerName,
+      state: agent.state,
+      defaultModel: String(data.defaultModel ?? ''),
+      fallbacks: (data.fallbacks ?? []).map(String),
+      allowed: (data.allowed ?? []).map(String),
+      aliases,
+      providers,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Get available models from an agent */
+function getAgentModels(container: string): GatewayModel[] {
+  const raw = dockerExec(container, 'openclaw models list --json', 8000);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    const models: Record<string, unknown>[] = parsed.models ?? parsed ?? [];
+    return models
+      .filter((m: Record<string, unknown>) => m.available !== false && !m.missing)
+      .map((m: Record<string, unknown>) => ({
+        key: String(m.key ?? ''),
+        provider: String(m.key ?? '').split('/')[0] || 'unknown',
+        model: String(m.name ?? String(m.key ?? '').split('/').slice(1).join('/')),
+        available: m.available !== false,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  try {
+    const timestamp = Date.now();
+
+    // Only Rev4a-managed agents (AGENT_ID label)
+    const agentsRaw = getAgents();
+    const agents = agentsRaw
+      .map((a) => getAgentStatus(a))
+      .filter(Boolean) as GatewayAgentStatus[];
+
+    // Aggregate models from all agents (deduplicated by key)
+    const modelMap = new Map<string, GatewayModel>();
+    for (const agent of agents) {
+      for (const m of getAgentModels(agent.containerName)) {
+        if (!modelMap.has(m.key)) modelMap.set(m.key, m);
+      }
+    }
+    const allModels = Array.from(modelMap.values());
+    const availableModels = allModels.filter((m) => m.available);
+
+    // Aggregate aliases from all agents
+    const combinedAliases: Record<string, string[]> = {};
+    for (const agent of agents) {
+      for (const [alias, model] of Object.entries(agent.aliases)) {
+        if (!combinedAliases[alias]) combinedAliases[alias] = [];
+        if (!combinedAliases[alias].includes(model)) {
+          combinedAliases[alias].push(model);
+        }
+      }
+    }
+
+    // First agent is the "primary" for core model settings
+    const primaryAgent = agents[0] ?? null;
+
+    // API keys from the first agent's providers
+    const apiKeys: ApiKeyStatus[] = [];
+    if (primaryAgent) {
+      for (const p of primaryAgent.providers) {
+        // We can't query apiKey presence from openclaw models status (it's redacted).
+        // Mark as configured if the provider appears in the auth list.
+        apiKeys.push({
+          provider: p.provider,
+          configured: p.profiles > 0,
+        });
+      }
+    }
+
+    // Models by provider
+    const byProvider = allModels.reduce<Record<string, number>>((acc, m) => {
+      acc[m.provider] = (acc[m.provider] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    return NextResponse.json({
+      timestamp,
+      gateway: 'Rev4a Model Gateway',
+      status: 'online',
+      models: {
+        total: allModels.length,
+        available: availableModels.length,
+        byProvider: Object.entries(byProvider).map(([provider, count]) => ({ provider, count })),
+        list: allModels,
+      },
+      agents: {
+        total: agents.length,
+        list: agents.map((a) => ({
+          agentId: a.agentId,
+          containerName: a.containerName,
+          state: a.state,
+          defaultModel: a.defaultModel,
+          fallbacks: a.fallbacks,
+          aliases: a.aliases,
+          providers: a.providers,
+        })),
+      },
+      aliases: combinedAliases,
+      coreModel: primaryAgent
+        ? {
+            defaultModel: primaryAgent.defaultModel,
+            fallbacks: primaryAgent.fallbacks,
+          }
+        : null,
+      apiKeys: {
+        configured: apiKeys.filter((k) => k.configured).map((k) => k.provider),
+        all: apiKeys,
+      },
+    });
+  } catch (e: unknown) {
+    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+  }
+}

package/app/api/gateway/sync.ts

@@ -0,0 +1,189 @@
+/**
+ * Agent Gateway Sync
+ *
+ * Syncs the models.providers.rev4a config block to all agent containers
+ * (or a single container) without touching model references (primary/fallback).
+ *
+ * Import and call:
+ *   syncAllAgents()          — sync all containers with AGENT_ID label
+ *   syncAgent('container')   — sync a single container
+ */
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import { readProviderKeys } from './provider/keys';
+import { loadModelsConfig, type ModelConfigEntry } from '@/lib/model-catalogue';
+import { detectProviderGatewayUrl } from '@/lib/docker-utils';
+
+const PROVIDER_GATEWAY_BASE_URL = detectProviderGatewayUrl();
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Convert internal modality string (e.g. "text+image+file->text") to
+ * OpenClaw `input` array. Filters out values not in the allowed set
+ * (text | image | video | audio).
+ */
+const ALLOWED_INPUT = new Set(['text', 'image', 'video', 'audio']);
+
+function modalityToInput(modality: string): string[] {
+  const arrowIdx = modality.indexOf('->');
+  const left = arrowIdx >= 0 ? modality.slice(0, arrowIdx) : modality;
+  return left.split('+').map((s) => s.trim()).filter((s) => ALLOWED_INPUT.has(s));
+}
+
+function getActiveRev4aModels(models: ModelConfigEntry[]): { id: string; name: string; input?: string[] }[] {
+  const providerKeys = readProviderKeys();
+  const configuredProviders = Object.keys(providerKeys);
+  return models
+    .filter((m) => m.enabled && configuredProviders.includes(m.provider))
+    .map((m) => {
+      const entry: { id: string; name: string; input?: string[] } = { id: m.id, name: m.name };
+      if (m.modality) entry.input = modalityToInput(m.modality);
+      return entry;
+    });
+}
+
+function getAgentContainers(): string[] {
+  try {
+    const raw = execSync(
+      `docker ps --filter "label=AGENT_ID" --format '{{.Names}}'`,
+      { timeout: 5000, maxBuffer: 64 * 1024, encoding: 'utf-8' },
+    ).trim();
+    if (!raw) return [];
+    return raw.split('\n');
+  } catch {
+    return [];
+  }
+}
+
+function readContainerJson(container: string, remotePath: string): Record<string, unknown> {
+  try {
+    const raw = execSync(
+      `docker exec ${container} cat ${remotePath}`,
+      { timeout: 8000, maxBuffer: 512 * 1024, encoding: 'utf-8' },
+    );
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function writeContainerJson(container: string, remotePath: string, data: Record<string, unknown>): void {
+  const jsonStr = JSON.stringify(data, null, 2);
+  // Use shell-quoted heredoc to avoid word-splitting on paths with spaces
+  execSync(
+    `docker exec -i ${container} sh -c "cat > '${remotePath}'"`,
+    { timeout: 10000, maxBuffer: 1024 * 1024, input: jsonStr },
+  );
+}
+
+function restartContainerGateway(container: string): string | null {
+  try {
+    execSync(`docker exec ${container} openclaw gateway restart`, { timeout: 15000, maxBuffer: 64 * 1024 });
+    return null;
+  } catch (e: unknown) {
+    const err = e as { stdout?: string; stderr?: string; message?: string };
+    return err.stderr?.toString().trim() || err.message || 'unknown error';
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Sync functions                                                     */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Build the models.providers.rev4a config object from local state.
+ * Shared between the create wizard and syncAgent — single source of truth
+ * for the provider block injected into every agent container.
+ */
+export function buildRev4aProviderConfig(): { baseUrl: string; apiKey: string; api: string; models: { id: string; name: string; input?: string[] }[] } {
+  const providerKeys = readProviderKeys();
+  const rev4aApiKey = providerKeys['rev4a'] || '';
+  const allModels = loadModelsConfig();
+  const activeModels = getActiveRev4aModels(allModels);
+  return {
+    baseUrl: PROVIDER_GATEWAY_BASE_URL,
+    apiKey: rev4aApiKey,
+    api: 'openai-completions',
+    models: activeModels,
+  };
+}
+
+/**
+ * Sync models.providers.rev4a to all agent containers.
+ * Does NOT touch agents.defaults.model or agents.list[].model.
+ */
+export function syncAllAgents(): string[] {
+  const rev4aProviderConfig = buildRev4aProviderConfig();
+  if (!rev4aProviderConfig.apiKey) {
+    return ['ERROR: REV4A_API_KEY not found in provider-keys.json (add "rev4a" key)'];
+  }
+
+  const containers = getAgentContainers();
+  const results: string[] = [`Active models: ${rev4aProviderConfig.models.length} across ${containers.length} agent(s)`];
+
+  for (const container of containers) {
+    try {
+      const result = syncContainer(container, rev4aProviderConfig);
+      results.push(result);
+    } catch (e: unknown) {
+      const err = e as { stderr?: string; message?: string };
+      results.push(`${container}: ERROR ${err.stderr || err.message || 'unknown'}`);
+    }
+  }
+
+  if (containers.length === 0) {
+    results.push('No agent containers found');
+  }
+
+  return results;
+}
+
+/**
+ * Sync models.providers.rev4a to a single agent container.
+ * Does NOT touch agents.defaults.model or agents.list[].model.
+ */
+export function syncAgent(containerName: string): string {
+  const rev4aProviderConfig = buildRev4aProviderConfig();
+  if (!rev4aProviderConfig.apiKey) {
+    throw new Error('REV4A_API_KEY not found in provider-keys.json (add "rev4a" key)');
+  }
+  return syncContainer(containerName, rev4aProviderConfig);
+}
+
+/**
+ * Internal: write models.providers.rev4a to one container and restart its gateway.
+ */
+function syncContainer(
+  container: string,
+  rev4aProviderConfig: { baseUrl: string; apiKey: string; api: string; models: { id: string; name: string }[] },
+): string {
+  const remotePath = '/root/.openclaw/openclaw.json';
+  const config = readContainerJson(container, remotePath) as Record<string, unknown>;
+
+  // Clean up stale files from old versions
+  try {
+    execSync(
+      `docker exec ${container} sh -c 'rm -f /root/.openclaw/agents/main/agent/models.json /root/.openclaw/agents/main/agent/auth-profiles.json'`,
+      { timeout: 5000 },
+    );
+  } catch {
+    // non-fatal
+  }
+
+  // Write/overwrite models.providers.rev4a — do NOT touch agents.*
+  const models = (config.models as Record<string, unknown>) || {};
+  if (!models.providers) models.providers = {};
+  (models.providers as Record<string, unknown>)['rev4a'] = rev4aProviderConfig;
+  config.models = models;
+
+  writeContainerJson(container, remotePath, config);
+
+  const gwError = restartContainerGateway(container);
+  if (gwError) {
+    return `${container}: file updated but gateway restart failed: ${gwError}`;
+  }
+  return `${container}: synced + restarted OK`;
+}

package/app/api/lineage/route.ts

@@ -0,0 +1,54 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { openDb } from '@/lib/db';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+function ensureLineageSchema(db: ReturnType<typeof openDb>): void {
+  db.prepare(
+    `CREATE TABLE IF NOT EXISTS lineage (
+      child_id TEXT PRIMARY KEY,
+      parent_id TEXT NOT NULL,
+      declared_at INTEGER NOT NULL,
+      agent_name TEXT,
+      label TEXT
+    )`,
+  ).run();
+
+  const columns = new Set<string>(
+    (db.prepare('PRAGMA table_info(lineage)').all() as Array<{ name: string }>).map(
+      (column) => column.name,
+    ),
+  );
+
+  if (!columns.has('agent_name')) {
+    db.exec('ALTER TABLE lineage ADD COLUMN agent_name TEXT');
+  }
+  if (!columns.has('label')) {
+    db.exec('ALTER TABLE lineage ADD COLUMN label TEXT');
+  }
+}
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+  try {
+    const body = (await request.json()) as { childId?: string; parentId?: string; label?: string };
+    const childId = body?.childId?.trim();
+    const parentId = body?.parentId?.trim();
+    const lineageLabel = body?.label?.trim() || null;
+
+    if (!childId || !parentId) {
+      return NextResponse.json({ error: 'childId and parentId required' }, { status: 400 });
+    }
+
+    const db = openDb(false);
+    ensureLineageSchema(db);
+    db.prepare(
+      `INSERT OR REPLACE INTO lineage (child_id, parent_id, declared_at, agent_name, label)
+       VALUES (?, ?, ?, ?, ?)`,
+    ).run(childId, parentId, Date.now(), lineageLabel, lineageLabel);
+    db.prepare('UPDATE sessions SET parent_id = ? WHERE session_id = ?').run(parentId, childId);
+    db.close();
+    return NextResponse.json({ ok: true, childId, parentId, label: lineageLabel });
+  } catch (e: unknown) {
+    return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+  }
+}

package/app/api/memory-context/route.ts

@@ -0,0 +1,15 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { getMemoryContextSnapshot } from '@/lib/memory-context';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request); if (denied) return denied as any;
+
+  try {
+    return NextResponse.json(getMemoryContextSnapshot());
+  } catch (error) {
+    return NextResponse.json({ error: (error as Error).message }, { status: 500 });
+  }
+}