@unson/brainbase-mcp 0.23.1 → 0.23.3

package/dist/judgment-history-http.js

@@ -0,0 +1,170 @@
+import { JUDGMENT_HISTORY_ENTRYPOINTS, createJudgmentHistoryReader, JudgmentHistoryFeedbackConflictError } from './judgment-history.js';
+import { LocalWebHttpError, readJsonObjectBody, writeJson } from './local-web-security.js';
+export const JUDGMENT_HISTORY_HTTP_VERSION = 'judgment-history-http.v1';
+export const JUDGMENT_HISTORY_HTTP_PREFIX = '/api/judgment-history';
+export const JUDGMENT_HISTORY_FEEDBACK_BODY_LIMIT_BYTES = 64 * 1024;
+function methodNotAllowed() {
+    const error = new Error('Use GET or POST');
+    error.statusCode = 405;
+    error.code = 'method_not_allowed';
+    return error;
+}
+function matchRoute(pathname, basePath) {
+    if (pathname === `${basePath}/home`)
+        return { name: 'home' };
+    if (pathname === `${basePath}/feedback`)
+        return { name: 'feedback' };
+    if (!pathname.startsWith(`${basePath}/records/`))
+        return null;
+    const encoded = pathname.slice(`${basePath}/records/`.length);
+    if (!encoded || encoded.includes('/'))
+        return null;
+    let recordId;
+    try {
+        recordId = decodeURIComponent(encoded);
+    }
+    catch {
+        const error = new Error('record_id is not valid percent-encoding');
+        error.statusCode = 400;
+        error.code = 'invalid_record_id';
+        throw error;
+    }
+    return { name: 'detail', recordId };
+}
+function queryValue(url, key) {
+    const value = url.searchParams.get(key);
+    return value === null ? undefined : value;
+}
+function parseLimit(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/u.test(value))
+        throw readerError(400, 'invalid_limit', 'limit must be between 1 and 100');
+    return Number(value);
+}
+function readerError(statusCode, code, message) {
+    const error = new Error(message);
+    error.statusCode = statusCode;
+    error.code = code;
+    return error;
+}
+function parseQuery(url) {
+    const allowed = new Set(['period', 'project', 'entrypoint', 'cursor', 'limit']);
+    for (const key of url.searchParams.keys()) {
+        if (!allowed.has(key))
+            throw readerError(400, 'unknown_query', `Unknown query parameter: ${key}`);
+    }
+    const periodValue = queryValue(url, 'period');
+    const period = periodValue === undefined ? undefined : periodValue;
+    const entrypointValue = queryValue(url, 'entrypoint');
+    const entrypoint = entrypointValue === undefined ? undefined : entrypointValue;
+    if (period !== undefined && period !== 'week' && period !== 'past30days' && period !== 'all') {
+        throw readerError(400, 'invalid_period', 'period is invalid');
+    }
+    if (entrypoint !== undefined && !JUDGMENT_HISTORY_ENTRYPOINTS.includes(entrypoint)) {
+        throw readerError(400, 'invalid_entrypoint', 'entrypoint is invalid');
+    }
+    const project = queryValue(url, 'project');
+    const cursor = queryValue(url, 'cursor');
+    const limit = parseLimit(queryValue(url, 'limit'));
+    return {
+        ...(period === undefined ? {} : { period }),
+        ...(project === undefined ? {} : { project }),
+        ...(entrypoint === undefined ? {} : { entrypoint }),
+        ...(cursor === undefined ? {} : { cursor }),
+        ...(limit === undefined ? {} : { limit })
+    };
+}
+function toError(error) {
+    if (error && typeof error === 'object'
+        && typeof error.statusCode === 'number'
+        && typeof error.code === 'string') {
+        return error;
+    }
+    return readerError(500, 'judgment_history_failed', error instanceof Error ? error.message : 'Judgment history read failed');
+}
+/** Node-style GET route for the common normal-judgment history contract. */
+export function createJudgmentHistoryHttpHandler(options) {
+    if (!options?.reader || typeof options.reader.home !== 'function' || typeof options.reader.detail !== 'function') {
+        throw new TypeError('reader is required');
+    }
+    const basePath = (options.basePath ?? JUDGMENT_HISTORY_HTTP_PREFIX).replace(/\/+$/u, '');
+    const reader = options.reader;
+    return async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        let route;
+        try {
+            route = matchRoute(url.pathname, basePath);
+        }
+        catch (error) {
+            const normalized = toError(error);
+            writeJson(response, normalized.statusCode, {
+                error: { code: normalized.code, message: normalized.message }
+            });
+            return true;
+        }
+        if (!route)
+            return false;
+        try {
+            if (route.name === 'feedback') {
+                if (request.method !== 'POST')
+                    throw methodNotAllowed();
+                if (!options.assertWriteAllowed) {
+                    throw new LocalWebHttpError(403, 'feedback_write_unconfigured', 'Feedback writes are not configured for this host');
+                }
+                if (!options.writeFeedback) {
+                    throw new LocalWebHttpError(503, 'feedback_write_unavailable', 'Feedback writes are unavailable');
+                }
+                await options.assertWriteAllowed(request);
+                const input = await readJsonObjectBody(request, JUDGMENT_HISTORY_FEEDBACK_BODY_LIMIT_BYTES);
+                const result = await options.writeFeedback(input);
+                const responseBody = {
+                    status: result.status,
+                    saved: true,
+                    created: result.created,
+                    feedback_event: result.event,
+                    ...result.event
+                };
+                writeJson(response, result.created ? 201 : 200, responseBody);
+            }
+            else {
+                if (request.method !== 'GET')
+                    throw methodNotAllowed();
+                if (route.name === 'home') {
+                    writeJson(response, 200, await reader.home(parseQuery(url)));
+                }
+                else {
+                    const result = await reader.detail(route.recordId);
+                    if (result.status === 'unavailable') {
+                        writeJson(response, 200, result);
+                    }
+                    else if (result.status === 'available' && !result.record) {
+                        throw readerError(404, 'judgment_history_not_found', 'No judgment history record matches this id');
+                    }
+                    else {
+                        writeJson(response, 200, result);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const normalized = toError(error);
+            if (error instanceof JudgmentHistoryFeedbackConflictError) {
+                writeJson(response, normalized.statusCode, {
+                    error: { code: normalized.code, message: normalized.message },
+                    feedback_event: error.existing
+                });
+            }
+            else {
+                writeJson(response, normalized.statusCode, {
+                    error: { code: normalized.code, message: normalized.message }
+                });
+            }
+        }
+        return true;
+    };
+}
+/** Convenience composition seam for adapters that want the HTTP contract without a local journal. */
+export function createJudgmentHistoryHttpReader(options) {
+    return createJudgmentHistoryReader(options);
+}

package/dist/judgment-history.d.ts

@@ -0,0 +1,178 @@
+/** Public normal-judgment history contract. Value-proof records use a separate contract. */
+export declare const JUDGMENT_HISTORY_RECORD_SCHEMA: "brainbase-judgment-history-record-v1";
+export declare const JUDGMENT_HISTORY_CONTRACT_VERSION: "brainbase.judgment-history.v1";
+export declare const JUDGMENT_HISTORY_FEEDBACK_SCHEMA: "brainbase-judgment-history-feedback-v1";
+export declare const JUDGMENT_HISTORY_ENTRYPOINTS: readonly ["codex", "claude_code", "mana", "company_os", "unknown"];
+export type JudgmentHistoryEntrypoint = typeof JUDGMENT_HISTORY_ENTRYPOINTS[number];
+export type JudgmentHistoryStatus = 'available' | 'partial' | 'unavailable';
+export type JudgmentHistoryStorage = 'local' | 'server';
+export type JudgmentHistoryPeriod = 'week' | 'past30days' | 'all';
+export type JudgmentHistoryReferenceAvailability = 'recorded' | 'permission_denied' | 'unavailable' | 'unknown';
+export type JudgmentHistoryExecutionStatus = 'pending' | 'completed' | 'failed' | 'held' | 'cancelled' | 'unknown';
+export type JudgmentHistoryOutcomeStatus = 'unconfirmed' | 'confirmed' | 'unknown';
+export type JudgmentHistoryFeedbackKind = 'feedback' | 'result' | 'correction';
+export interface JudgmentHistoryFeedbackContent {
+    readonly summary: string;
+    readonly outcome_status?: JudgmentHistoryOutcomeStatus;
+}
+/** Public feedback event. Storage timestamps and digests are deliberately omitted. */
+export interface JudgmentHistoryFeedbackEvent {
+    readonly record_id: string;
+    readonly event_id: string;
+    readonly kind: JudgmentHistoryFeedbackKind;
+    readonly content: JudgmentHistoryFeedbackContent;
+}
+export interface JudgmentHistoryFeedbackWriteResult {
+    readonly event: JudgmentHistoryFeedbackEvent;
+    readonly created: boolean;
+    readonly status: 'saved' | 'already_saved';
+}
+export interface JudgmentHistoryReference {
+    readonly ref: string;
+    readonly kind: string | null;
+    readonly version: string | null;
+    readonly digest: string | null;
+    readonly why: string | null;
+    readonly usage: string | null;
+    readonly availability: JudgmentHistoryReferenceAvailability;
+}
+export interface JudgmentHistoryAlternative {
+    readonly label: string;
+    readonly evaluation: string | null;
+    readonly adopted: boolean | null;
+}
+export interface JudgmentHistoryJudgment {
+    readonly status: 'resolved' | 'needs_clarification' | 'unknown';
+    readonly summary: string | null;
+    readonly reason: string | null;
+    readonly selected_references: readonly JudgmentHistoryReference[] | null;
+    readonly alternatives: readonly JudgmentHistoryAlternative[] | null;
+}
+export interface JudgmentHistoryExecution {
+    readonly status: JudgmentHistoryExecutionStatus;
+    readonly result_summary: string | null;
+    readonly outcome_status: JudgmentHistoryOutcomeStatus;
+}
+export interface JudgmentHistoryRecord {
+    readonly schema_version: typeof JUDGMENT_HISTORY_RECORD_SCHEMA;
+    readonly record_id: string;
+    readonly entrypoint: JudgmentHistoryEntrypoint;
+    readonly recorded_at: string;
+    readonly project_code: string | null;
+    readonly turn_ref: string;
+    readonly judgment: JudgmentHistoryJudgment;
+    readonly execution: JudgmentHistoryExecution;
+    readonly missing_fields: readonly string[];
+    /** Append-only result/correction events linked to this normal record. */
+    readonly feedback_events?: readonly JudgmentHistoryFeedbackEvent[];
+}
+export interface JudgmentHistorySourceInfo {
+    readonly entrypoint: JudgmentHistoryEntrypoint;
+    readonly status: JudgmentHistoryStatus;
+    readonly reason: string | null;
+}
+export interface JudgmentHistoryCoverage {
+    readonly complete: boolean;
+    readonly storage: JudgmentHistoryStorage;
+    readonly reason: string | null;
+    readonly sources: readonly JudgmentHistorySourceInfo[];
+    /** Null means the adapter cannot prove the total under this scope/filter. */
+    readonly total: number | null;
+}
+export interface JudgmentHistorySourceSnapshot {
+    readonly status: JudgmentHistoryStatus;
+    readonly records: readonly JudgmentHistoryRecord[] | null;
+    readonly coverage: JudgmentHistoryCoverage;
+    /** Stable source revision used to bind pagination cursors. */
+    readonly snapshot_id?: string;
+}
+export interface JudgmentHistorySource {
+    readonly storage: JudgmentHistoryStorage;
+    readonly read: () => Promise<JudgmentHistorySourceSnapshot>;
+}
+export interface JudgmentHistoryQuery {
+    readonly period?: JudgmentHistoryPeriod;
+    readonly project?: string;
+    readonly entrypoint?: JudgmentHistoryEntrypoint;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface JudgmentHistoryFilters {
+    readonly period: JudgmentHistoryPeriod;
+    readonly project: string | null;
+    readonly entrypoint: JudgmentHistoryEntrypoint | null;
+}
+export interface JudgmentHistoryPagination {
+    readonly cursor: string | null;
+    readonly next_cursor: string | null;
+    readonly limit: number;
+    readonly has_more: boolean;
+}
+export interface JudgmentHistoryHome {
+    readonly contract_version: typeof JUDGMENT_HISTORY_CONTRACT_VERSION;
+    readonly status: JudgmentHistoryStatus;
+    readonly records: readonly JudgmentHistoryRecord[] | null;
+    readonly coverage: JudgmentHistoryCoverage;
+    readonly pagination: JudgmentHistoryPagination;
+    readonly filters: JudgmentHistoryFilters;
+}
+export interface JudgmentHistoryDetail {
+    readonly contract_version: typeof JUDGMENT_HISTORY_CONTRACT_VERSION;
+    readonly status: JudgmentHistoryStatus;
+    readonly record: JudgmentHistoryRecord | null;
+    readonly coverage: JudgmentHistoryCoverage;
+}
+export interface JudgmentHistoryReaderOptions {
+    readonly source: JudgmentHistorySource;
+    readonly now?: () => Date;
+    /** Organization adapters provide trusted scope authorization here. */
+    readonly authorizeProject?: (project: string) => boolean | Promise<boolean>;
+}
+export interface JudgmentHistoryReader {
+    readonly home: (query?: JudgmentHistoryQuery) => Promise<JudgmentHistoryHome>;
+    readonly detail: (recordId: string) => Promise<JudgmentHistoryDetail>;
+}
+export declare class JudgmentHistoryReaderError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+export interface LocalJudgmentHistorySourceOptions {
+    readonly root: string;
+    readonly entrypoint?: JudgmentHistoryEntrypoint;
+    /** Maximum number of candidate journal files inspected in one read. */
+    readonly max_files?: number;
+    /** Maximum size of one journal artifact, in bytes. */
+    readonly max_record_bytes?: number;
+}
+export interface LocalJudgmentHistoryFeedbackWriterOptions {
+    readonly root: string;
+    readonly reader: JudgmentHistoryReader;
+    readonly now?: () => Date;
+}
+export type JudgmentHistoryFeedbackWriter = (input: unknown) => Promise<JudgmentHistoryFeedbackWriteResult>;
+export declare class JudgmentHistoryFeedbackError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+export declare class JudgmentHistoryFeedbackConflictError extends JudgmentHistoryFeedbackError {
+    readonly existing: JudgmentHistoryFeedbackEvent;
+    constructor(existing: JudgmentHistoryFeedbackEvent);
+}
+export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_SCAN_CAP = 4096;
+export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_RECORD_BYTES: number;
+export declare function canonicalJson(value: unknown): string;
+/** Reads only the configured local owner journal; it never searches or uploads another journal. */
+export declare function createLocalJudgmentHistorySource(options: LocalJudgmentHistorySourceOptions): JudgmentHistorySource;
+/**
+ * Append-only local feedback writer for normal judgment records. It writes a
+ * separate immutable event file below the configured journal and always
+ * confirms the event through the same reader before returning success.
+ */
+export declare function createLocalJudgmentHistoryFeedbackWriter(options: LocalJudgmentHistoryFeedbackWriterOptions): JudgmentHistoryFeedbackWriter;
+export declare function appendLocalJudgmentHistoryFeedback(options: LocalJudgmentHistoryFeedbackWriterOptions & {
+    readonly input: unknown;
+}): Promise<JudgmentHistoryFeedbackWriteResult>;
+/** Reader shared by local, organization, Mana, and Company OS adapters. */
+export declare function createJudgmentHistoryReader(options: JudgmentHistoryReaderOptions): JudgmentHistoryReader;