@tequila99/githuman 0.2.2 → 0.3.0

package/README.md

@@ -18,23 +18,14 @@ staged/unstaged diff, сравнение веток и коммитов, бра
   синтаксиса (shiki).
 - Live-обновления через SSE: интерфейс сам обновляется при изменении
   файлов в репозитории — удобно смотреть, как редактирует код AI-агент.
+  После перезапуска `serve` уже открытые вкладки перезагружаются сами.
+- Чаты с ACP-агентами (Claude Code, Cursor, Codex, pi): до 5 чатов во
+  вкладках, контекст — diff, файл целиком, ревью, вложения и `@`-файлы из
+  репозитория. Подробнее — в разделе «Агенты» ниже.
 - Ручной/авто выбор тёмной-светлой темы.
 - CLI: `serve` (поднять сервер), `list`/`export` (быстрый доступ к
   сохранённым ревью без веб-интерфейса).
 
-## Известное ограничение (WIP)
-
-Бэкенд полностью поддерживает модель "ревью" — создание ревью
-(staged/branch/commits), инлайн-комментарии, статусы
-(`in_progress`/`approved`/`changes_requested`), экспорт в Markdown/JSON — всё
-это покрыто тестами (`src/server/routes/reviews.ts`, `comments.ts`,
-`export.ts`). **Соответствующий экран во фронтенде пока не реализован** —
-`ReviewsPage.vue` сейчас заглушка. Работает только просмотр diff/файлов;
-создание ревью и комментирование через UI недоступно. Это следующий
-логический кусок работы, не забытая функциональность — трекается в
-`.claude/docs/adr/0014-quasar-frontend-migration.md` (не публикуется, файл
-только для локальной разработки).
-
 ## Установка и запуск
 
 Требуется Node.js ≥ 24 (используется нативный `node:sqlite`).
@@ -79,6 +70,29 @@ node dist/cli/index.js export last --format markdown -o review.md
 > аутентификации. Открывая его в локальной сети, любой в этой сети сможет
 > просматривать содержимое репозитория.
 
+### Агенты
+
+Иконка робота в шапке открывает панель чатов. Агенты запускаются как
+подпроцессы по протоколу [ACP](https://agentclientprotocol.com) в корне
+репозитория; нужные адаптеры подтягиваются через `npx` при первом запуске.
+
+- **Контекст.** «Add to chat» в меню файла и diff, кнопка у активного
+  ревью; в поле ввода `@` + часть имени + Tab вставляет файл из репозитория.
+  Shift+Tab переключает режим агента, модель и режим выбираются под полем.
+- **Подтверждения.** Запросы разрешений приходят карточкой в чат. Для
+  отдельного чата можно включить автоподтверждение (кнопка-щит) — агент
+  тогда меняет файлы и выполняет команды без вашего ответа; включайте его
+  только для работы, которую готовы проверить и откатить. pi вообще не
+  спрашивает.
+- **Свои команды запуска** — `<репозиторий>/.githuman/ght-agents.json`:
+  `{ "cursor": { "args": ["--model", "<модель>", "acp"] } }`. Допустимы поля
+  `command`, `args`, `env`; любое другое (в том числе опечатка) — ошибка
+  при запуске сервера.
+- **Только локально.** Агентские маршруты работают лишь при `--host`
+  localhost/127.0.0.1/::1 (иначе это удалённое выполнение команд для всей
+  сети) и отклоняют чужие `Origin`/`Host`. Открывайте приложение по
+  `http://localhost:<порт>`.
+
 ### Данные и совместимость с оригинальным mcollina/githuman
 
 Ревью хранятся в `.githuman/ght-reviews.db` (SQLite) в корне анализируемого

package/dist/cli/commands/export.js

@@ -1,5 +1,6 @@
 import { parseArgs } from 'node:util';
-import { exportAsJson, exportAsMarkdown, ExportNotFoundError } from "../../server/services/export.service.js";
+import { exportAsJson, exportAsMarkdown } from "../../server/services/export.service.js";
+import { ExportNotFoundError } from "../../server/errors/export.js";
 import { getReviews } from "../../server/services/review.service.js";
 import { resolveDbPrefix } from "../config.js";
 export class ExportCliError extends Error {
@@ -39,12 +40,12 @@ function resolveReviewId(db, id) {
     }
     return latest.id;
 }
-export function runExport(db, id, format = 'markdown') {
+export async function runExport(db, id, format, repositoryPath) {
     const reviewId = resolveReviewId(db, id);
     try {
         return format === 'json'
             ? JSON.stringify(exportAsJson(db, reviewId), null, 2)
-            : exportAsMarkdown(db, reviewId);
+            : await exportAsMarkdown(db, reviewId, repositoryPath);
     }
     catch (error) {
         if (error instanceof ExportNotFoundError) {

package/dist/cli/index.js

@@ -10,7 +10,10 @@ import { getAppVersion } from "../server/app-version.js";
 /** Opens the reviews DB for the repo at cwd, shared by `list` and `export`. */
 async function openReviewsDb(dbPrefix) {
     const repositoryPath = await resolveRepositoryPath(process.cwd());
-    return createFileDatabase(resolveReviewsDbPath(repositoryPath, dbPrefix));
+    return {
+        db: createFileDatabase(resolveReviewsDbPath(repositoryPath, dbPrefix)),
+        repositoryPath
+    };
 }
 async function main(argv) {
     console.log(`githuman v${getAppVersion()}`);
@@ -24,14 +27,14 @@ async function main(argv) {
         }
         case 'list': {
             const options = parseListArgs(rest);
-            const db = await openReviewsDb(options.dbPrefix);
+            const { db } = await openReviewsDb(options.dbPrefix);
             console.log(runList(db, options));
             return;
         }
         case 'export': {
             const options = parseExportArgs(rest);
-            const db = await openReviewsDb(options.dbPrefix);
-            const output = runExport(db, options.id, options.format);
+            const { db, repositoryPath } = await openReviewsDb(options.dbPrefix);
+            const output = await runExport(db, options.id, options.format, repositoryPath);
             if (options.output) {
                 writeFileSync(options.output, output);
             }

package/dist/cli/server-runtime.js

@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url';
 import { buildApp } from "../server/app.js";
 import { createFileDatabase } from "../server/db/index.js";
 import { resolveDbPrefix } from "./config.js";
+import { isLoopbackHost } from "../shared/network/loopback.js";
+import { loadAgentPresets } from "../server/config/agents.js";
 const execFileAsync = promisify(execFile);
 function resolveStaticRoot() {
     // Compiled layout: dist/cli/server-runtime.js sits next to dist/web/.
@@ -49,6 +51,10 @@ export function resolveReviewsDbPath(repositoryPath, dbPrefix) {
     const prefix = resolveDbPrefix(dbPrefix);
     return join(repositoryPath, '.githuman', `${prefix}reviews.db`);
 }
+/** `.githuman/<prefix>agents.json` — the user's agent launch-command overrides (ADR 0023). */
+export function resolveAgentsConfigPath(repositoryPath, dbPrefix) {
+    return join(repositoryPath, '.githuman', `${resolveDbPrefix(dbPrefix)}agents.json`);
+}
 export async function startServer(options) {
     const repositoryPath = await resolveRepositoryPath(process.cwd());
     const db = createFileDatabase(resolveReviewsDbPath(repositoryPath, options.dbPrefix));
@@ -56,7 +62,13 @@ export async function startServer(options) {
         staticRoot: resolveStaticRoot(),
         repositoryPath,
         db,
-        watchFiles: true
+        watchFiles: true,
+        // Agents can run commands, so they are only offered on a loopback bind.
+        ...(isLoopbackHost(options.host)
+            ? {
+                agentPresets: loadAgentPresets(resolveAgentsConfigPath(repositoryPath, options.dbPrefix))
+            }
+            : {})
     });
     const address = await app.listen({ port: options.port, host: options.host });
     if (options.open) {

package/dist/cli/startup-message.js

@@ -1,7 +1,8 @@
+import { isLoopbackHost } from "../shared/network/loopback.js";
 export function formatStartupMessage(url, host) {
     const lines = [`githuman listening on ${url}`];
-    if (host !== 'localhost' && host !== '127.0.0.1') {
-        lines.push('Warning: server is reachable from your local network without authentication.');
+    if (!isLoopbackHost(host)) {
+        lines.push('Warning: server is reachable from your local network without authentication.', 'Agent chat is disabled: it is only available when listening on localhost.');
     }
     return lines.join('\n');
 }

package/dist/server/adapters/agents/event-mapper.js

@@ -0,0 +1,140 @@
+import { toAgentToolStatus } from "../../../shared/agents/types.js";
+import { truncateText } from "../../utils/text.js";
+/** Cap on tool output forwarded to the browser; agents can dump whole files. */
+const MAX_TOOL_OUTPUT_CHARS = 20_000;
+/** Cap on each text of a diff in a tool event. The chat shows 200 lines at most. */
+const MAX_TOOL_DIFF_CHARS = 20_000;
+/** Cap for a permission request: the user decides on what the diff shows. */
+const MAX_PERMISSION_DIFF_CHARS = 100_000;
+/** Flattens ACP select options (plain or grouped) into one list. */
+function flattenChoices(options) {
+    const choices = [];
+    for (const entry of options) {
+        const members = 'group' in entry ? entry.options : [entry];
+        const group = 'group' in entry ? entry.name : undefined;
+        for (const member of members) {
+            choices.push({
+                value: member.value,
+                name: member.name,
+                ...(member.description ? { description: member.description } : {}),
+                ...(group === undefined ? {} : { group })
+            });
+        }
+    }
+    return choices;
+}
+export function mapConfigOptions(options) {
+    return (options ?? []).map(option => ({
+        id: option.id,
+        name: option.name,
+        ...(option.category ? { category: option.category } : {}),
+        ...(option.description ? { description: option.description } : {}),
+        type: option.type,
+        currentValue: option.currentValue,
+        ...(option.type === 'select'
+            ? { options: flattenChoices(option.options) }
+            : {})
+    }));
+}
+/** Cuts both texts of a diff; `truncated` tells the reader that the diff is partial. */
+function capDiff(diff, max) {
+    const oldText = diff.oldText === null ? null : diff.oldText.slice(0, max);
+    const newText = diff.newText.slice(0, max);
+    return oldText === diff.oldText && newText === diff.newText
+        ? diff
+        : { ...diff, oldText, newText, truncated: true };
+}
+export function extractToolContent(content, maxDiffChars = MAX_TOOL_DIFF_CHARS) {
+    const diffs = [];
+    const texts = [];
+    for (const item of content ?? []) {
+        if (item.type === 'diff') {
+            diffs.push(capDiff({
+                path: item.path,
+                oldText: item.oldText ?? null,
+                newText: item.newText
+            }, maxDiffChars));
+        }
+        else if (item.type === 'content' && item.content.type === 'text') {
+            texts.push(item.content.text);
+        }
+        // 'terminal' content needs the terminal capability, which we don't declare.
+    }
+    return {
+        diffs,
+        output: texts.length > 0
+            ? truncateText(texts.join('\n'), MAX_TOOL_OUTPUT_CHARS)
+            : undefined
+    };
+}
+/**
+ * Maps one ACP `session/update` to a chat event, or null for updates the UI
+ * doesn't show. Sticks to the standard fields (`kind`, `status`, `locations`,
+ * `content`) — `_meta` differs per agent (ADR 0023 spike).
+ */
+export function mapSessionUpdate(update) {
+    switch (update.sessionUpdate) {
+        case 'agent_message_chunk':
+        case 'agent_thought_chunk':
+            return {
+                type: 'message',
+                role: update.sessionUpdate === 'agent_message_chunk' ? 'agent' : 'thought',
+                text: update.content.type === 'text'
+                    ? update.content.text
+                    : `[${update.content.type}]`
+            };
+        case 'tool_call':
+        case 'tool_call_update': {
+            const { diffs, output } = extractToolContent(update.content);
+            const status = toAgentToolStatus(update.status);
+            return {
+                type: 'tool',
+                toolCallId: update.toolCallId,
+                ...(update.title ? { title: update.title } : {}),
+                ...(update.kind ? { kind: update.kind } : {}),
+                ...(status ? { status } : {}),
+                ...(update.locations
+                    ? { locations: update.locations.map(l => l.path) }
+                    : {}),
+                ...(diffs.length > 0 ? { diffs } : {}),
+                ...(output === undefined ? {} : { output })
+            };
+        }
+        case 'plan':
+            return {
+                type: 'plan',
+                entries: update.entries.map(e => ({
+                    content: e.content,
+                    status: e.status
+                }))
+            };
+        case 'usage_update':
+            return {
+                type: 'usage',
+                used: update.used,
+                size: update.size,
+                ...(update.cost ? { cost: update.cost.amount } : {})
+            };
+        case 'config_option_update':
+            return { type: 'config', options: mapConfigOptions(update.configOptions) };
+        default:
+            // user_message_chunk (we already know what the user typed), command/mode/
+            // config/session-info updates, …
+            return null;
+    }
+}
+export function mapPermissionRequest(requestId, params) {
+    const { diffs } = extractToolContent(params.toolCall.content, MAX_PERMISSION_DIFF_CHARS);
+    return {
+        type: 'permission',
+        requestId,
+        toolCallId: params.toolCall.toolCallId,
+        title: params.toolCall.title ?? 'Tool call',
+        options: params.options.map(o => ({
+            optionId: o.optionId,
+            name: o.name,
+            kind: o.kind
+        })),
+        diffs
+    };
+}

package/dist/server/app.js

@@ -1,3 +1,5 @@
+import { NotFoundError } from "./errors/http.js";
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import Fastify from 'fastify';
@@ -14,6 +16,8 @@ import { reviewRoutes } from "./routes/reviews.js";
 import { commentRoutes } from "./routes/comments.js";
 import { exportRoutes } from "./routes/export.js";
 import { eventRoutes } from "./routes/events.js";
+import { agentRoutes } from "./routes/agent.js";
+import { createSessionRegistry } from "./services/agent/session-registry.js";
 import { createTestDatabase } from "./db/index.js";
 import { createEventBus } from "./event-bus.js";
 import { watchRepository } from "./services/file-watcher.service.js";
@@ -31,8 +35,22 @@ export function buildApp(options = {}) {
     app.register(gitRoutes, { repositoryPath });
     app.register(reviewRoutes, { repositoryPath, db, eventBus });
     app.register(commentRoutes, { db, eventBus });
-    app.register(exportRoutes, { db });
-    app.register(eventRoutes, { eventBus });
+    app.register(exportRoutes, { db, repositoryPath });
+    app.register(eventRoutes, {
+        eventBus,
+        instanceId: options.instanceId ?? randomUUID()
+    });
+    if (options.agentPresets) {
+        app.register(agentRoutes, {
+            registry: createSessionRegistry({
+                presets: options.agentPresets,
+                repositoryPath
+            }),
+            db,
+            repositoryPath,
+            eventBus
+        });
+    }
     if (options.watchFiles) {
         const watcher = watchRepository(repositoryPath, () => {
             eventBus.publish({ type: 'files:changed' });
@@ -47,18 +65,13 @@ export function buildApp(options = {}) {
             root: staticRoot,
             wildcard: false
         });
-        app.setNotFoundHandler((request, reply) => {
-            if (request.url.startsWith('/api/')) {
-                reply.code(404).send({
-                    error: 'Not Found',
-                    message: `Route ${request.url} not found`,
-                    statusCode: 404
-                });
-                return;
-            }
-            const indexHtml = readFileSync(join(staticRoot, 'index.html'), 'utf-8');
-            reply.code(200).type('text/html').send(indexHtml);
-        });
     }
+    app.setNotFoundHandler((request, reply) => {
+        if (request.url.startsWith('/api/') || !options.staticRoot) {
+            throw new NotFoundError(`Route ${request.url} not found`);
+        }
+        const indexHtml = readFileSync(join(options.staticRoot, 'index.html'), 'utf-8');
+        reply.code(200).type('text/html').send(indexHtml);
+    });
     return app;
 }

package/dist/server/config/agents.js

@@ -0,0 +1,141 @@
+import { readFileSync } from 'node:fs';
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { isOnPath } from "../utils/executable.js";
+import { isRecord } from "../../shared/utils/guards.js";
+/**
+ * Packages are pinned to the versions the ADR 0023 spike was run against —
+ * `npx -y` otherwise executes whatever was published last. Cursor and Codex
+ * are not verified yet (Codex's adapter moved to the agentclientprotocol org
+ * after zed-industries/codex-acp was archived) and stay unpinned.
+ */
+export const DEFAULT_AGENT_PRESETS = [
+    {
+        id: 'claude',
+        title: 'Claude Code',
+        command: 'npx',
+        args: ['-y', '@agentclientprotocol/claude-agent-acp@0.84.0'],
+        autoApprovesEdits: false
+    },
+    {
+        id: 'pi',
+        title: 'pi',
+        command: 'npx',
+        args: ['-y', 'pi-acp@0.0.34'],
+        requires: 'pi',
+        autoApprovesEdits: true
+    },
+    {
+        id: 'cursor',
+        title: 'Cursor',
+        command: 'agent',
+        args: ['acp'],
+        autoApprovesEdits: false
+    },
+    {
+        id: 'codex',
+        title: 'Codex',
+        command: 'npx',
+        args: ['-y', '@agentclientprotocol/codex-acp'],
+        autoApprovesEdits: false
+    }
+];
+/** The keys the schema allows; named in the "unknown field" message. */
+const OVERRIDE_FIELDS = ['command', 'args', 'env'];
+/**
+ * One entry of the user's overrides file. Closed on purpose: a misspelt key
+ * (`arg` for `args`) must fail loudly, not be ignored.
+ */
+const AgentOverrideSchema = Type.Object({
+    command: Type.Optional(Type.String({ minLength: 1 })),
+    args: Type.Optional(Type.Array(Type.String())),
+    env: Type.Optional(Type.Record(Type.String(), Type.String()))
+}, { additionalProperties: false });
+export function describePreset(preset) {
+    // The agent starts with `preset.env` on top of ours, so look in its PATH.
+    const pathEnv = preset.env?.PATH ?? process.env.PATH;
+    return {
+        id: preset.id,
+        title: preset.title,
+        available: isOnPath(preset.command, pathEnv) &&
+            (preset.requires === undefined || isOnPath(preset.requires, pathEnv)),
+        autoApprovesEdits: preset.autoApprovesEdits
+    };
+}
+/** A JSON Pointer segment (`~1` is `/`, `~0` is `~`) as the plain field name. */
+function fieldOf(pointer) {
+    const [segment = ''] = pointer.split('/').filter(part => part !== '');
+    return segment.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+/** Names the first schema violation of one override entry; `pointer` is relative to that entry. */
+function overrideProblem(where, pointer) {
+    const field = fieldOf(pointer);
+    if (field === 'command')
+        return `${where} needs a "command" string`;
+    if (field === 'args')
+        return `${where}: "args" must be an array of strings`;
+    if (field === 'env')
+        return `${where}: "env" must map names to strings`;
+    // Any other field name in the path is a key the schema does not allow.
+    return `${where} has an unknown field "${field}" (allowed: ${OVERRIDE_FIELDS.join(', ')})`;
+}
+function readOverrides(overridesPath) {
+    let raw;
+    try {
+        raw = readFileSync(overridesPath, 'utf-8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in ${overridesPath}`, { cause: error });
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`${overridesPath} must contain a JSON object keyed by agent id`);
+    }
+    return parsed;
+}
+/**
+ * Applies the user's overrides file (`.githuman/<prefix>agents.json`) over
+ * the built-in presets: `{ "<id>": { "command": "...", "args": [...], "env": {...} } }`.
+ * A preset id not among the defaults defines a new agent. This file is the
+ * only place a launch command can come from besides the defaults — the HTTP
+ * API only ever selects a preset by id (ADR 0023).
+ */
+export function loadAgentPresets(overridesPath, defaults = DEFAULT_AGENT_PRESETS) {
+    const merged = new Map(defaults.map(preset => [preset.id, { ...preset }]));
+    for (const [id, override] of Object.entries(readOverrides(overridesPath))) {
+        const where = `Agent "${id}" in ${overridesPath}`;
+        if (!isRecord(override)) {
+            throw new Error(`${where} must be an object`);
+        }
+        if (!Value.Check(AgentOverrideSchema, override)) {
+            const problem = Value.Errors(AgentOverrideSchema, override).First();
+            throw new Error(overrideProblem(where, problem?.path ?? ''));
+        }
+        const base = merged.get(id);
+        const command = override.command ?? base?.command;
+        if (command === undefined) {
+            throw new Error(`${where} needs a "command" string`);
+        }
+        const args = override.args ?? base?.args ?? [];
+        const env = override.env ?? base?.env;
+        merged.set(id, {
+            id,
+            title: base?.title ?? id,
+            command,
+            args,
+            ...(base?.requires === undefined ? {} : { requires: base.requires }),
+            autoApprovesEdits: base?.autoApprovesEdits ?? false,
+            ...(env === undefined ? {} : { env })
+        });
+    }
+    return [...merged.values()];
+}

package/dist/server/errors/agents.js

@@ -0,0 +1,12 @@
+import createError from '@fastify/error';
+export const AgentSessionError = createError('GHT_AGENT_SESSION', '%s', 502);
+export const AgentSessionStateError = createError('GHT_AGENT_STATE', '%s', 409, 
+// Node's ErrorConstructor requires static fields; createError only reads Base.prototype.
+// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- @fastify/error's Base type is stricter than its runtime contract
+AgentSessionError);
+export const AgentConfigError = createError('GHT_AGENT_CONFIG', '%s', 400, 
+// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- same Base.prototype contract as AgentSessionStateError
+AgentSessionError);
+export const AgentContextError = createError('GHT_AGENT_CONTEXT', '%s', 400);
+export const UnknownAgentPresetError = createError('GHT_AGENT_PRESET_NOT_FOUND', '%s', 404);
+export const TooManyAgentSessionsError = createError('GHT_AGENT_SESSION_LIMIT', '%s', 409);

package/dist/server/errors/comments.js

@@ -0,0 +1,2 @@
+import createError from '@fastify/error';
+export const ValidationError = createError('GHT_COMMENT_VALIDATION', '%s', 400);

package/dist/server/errors/export.js

@@ -0,0 +1,2 @@
+import createError from '@fastify/error';
+export const ExportNotFoundError = createError('GHT_EXPORT_NOT_FOUND', '%s', 404);

package/dist/server/errors/http.js

@@ -0,0 +1,4 @@
+import createError from '@fastify/error';
+export const BadRequestError = createError('GHT_HTTP_BAD_REQUEST', '%s', 400);
+export const NotFoundError = createError('GHT_HTTP_NOT_FOUND', '%s', 404);
+export const ForbiddenError = createError('GHT_HTTP_FORBIDDEN', '%s', 403);

package/dist/server/errors/reviews.js

@@ -0,0 +1,3 @@
+import createError from '@fastify/error';
+export const ValidationError = createError('GHT_REVIEW_VALIDATION', '%s', 400);
+export const UniqueNameError = createError('GHT_REVIEW_NAME_CONFLICT', '%s', 409);

package/dist/server/hooks/agents/local-origin.js

@@ -0,0 +1,33 @@
+import { ForbiddenError } from "../../errors/http.js";
+import { isLoopbackHost } from "../../../shared/network/loopback.js";
+function hostnameOf(hostWithPort) {
+    // "[::1]:3847" → "[::1]"; "localhost:3847" → "localhost"
+    return hostWithPort.startsWith('[')
+        ? hostWithPort.slice(0, hostWithPort.indexOf(']') + 1)
+        : (hostWithPort.split(':')[0] ?? '');
+}
+/**
+ * `onRequest` hook for the agent routes (ADR 0023). They are an RCE surface,
+ * so besides only being registered on a loopback bind, each request must
+ * prove it came from a page served by this very server: a loopback `Host`
+ * (defeats DNS rebinding, where a hostile domain resolves to 127.0.0.1) and,
+ * when the browser sends an `Origin`, one identical to that `Host`.
+ * Non-browser clients (curl, tests) send no `Origin` and pass.
+ */
+export async function requireLocalOrigin(request) {
+    const host = request.headers.host ?? '';
+    const origin = request.headers.origin;
+    let ok = isLoopbackHost(hostnameOf(host));
+    if (ok && origin !== undefined) {
+        try {
+            ok = new URL(origin).host === host;
+        }
+        catch {
+            ok = false;
+        }
+    }
+    if (ok) {
+        return;
+    }
+    throw new ForbiddenError(`Agent endpoints only accept requests from this local server (Host: ${host || '-'}, Origin: ${origin ?? '-'}). Open the app via localhost.`);
+}

package/dist/server/repositories/review.repo.js

@@ -1,3 +1,4 @@
+import { UniqueNameError } from "../errors/reviews.js";
 function rowToReview(row) {
     return {
         id: row.id,
@@ -13,9 +14,6 @@ function rowToReview(row) {
         updatedAt: row.updated_at
     };
 }
-/** Thrown by `createReview` when `(name, branch)` collides with an existing review — see ADR 0017. */
-export class UniqueNameError extends Error {
-}
 export function createReview(db, review) {
     try {
         db.prepare(`INSERT INTO reviews (id, repository_path, base_ref, source_type, source_ref, snapshot_data, status, name, branch, created_at, updated_at)