@unson/brainbase-mcp 0.43.0 → 0.44.1

package/dist/judgment-event-adapter.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { normalizeJudgmentExecutionOutcome } from './judgment-execution-outcome.js';
+const MAX_SUMMARY_LENGTH = 2000;
+const AUDIT_LINE = /^(?:🧠 |📚 |⚠️ |🔁 |🛠️ )/u;
+const SENSITIVE_CONTENT = [
+    /\b(?:api[_-]?key|password|passwd|secret|token)\s*[:=]\s*\S+/iu,
+    /\bsk-[a-z0-9_-]{8,}\b/iu,
+    /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/iu
+];
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error(`${field} is required`);
+    return value;
+}
+function eventIdFor(episode) {
+    const digest = createHash('sha256')
+        .update(JSON.stringify([
+        episode.episode_id,
+        episode.session_id,
+        episode.turn_id,
+        episode.finalized_at,
+        episode.answer_digest
+    ]))
+        .digest('hex');
+    return `kev_${digest}`;
+}
+/** Remove audit lines and quarantine likely secrets from a judgment answer. */
+export function sanitizeJudgmentAnswer(value) {
+    if (typeof value !== 'string')
+        return null;
+    const summary = value
+        .split(/\r?\n/u)
+        .filter((line) => !AUDIT_LINE.test(line))
+        .join('\n')
+        .trim();
+    if (!summary)
+        return null;
+    if (SENSITIVE_CONTENT.some((pattern) => pattern.test(summary))) {
+        return { sensitive: true, redaction_status: 'needs_redaction' };
+    }
+    return { sensitive: false, summary: summary.slice(0, MAX_SUMMARY_LENGTH) };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Project a completed Host episode into a non-authoritative knowledge event.
+ *
+ * This is a portable projection only. Organization identity, Task binding,
+ * transcript storage, and delivery/outbox behavior remain adapter concerns.
+ */
+export function toKnowledgeEventFromJudgmentEpisode(episode) {
+    if (!episode || episode.completion_status !== 'complete')
+        return null;
+    const payload = isRecord(episode.payload) ? episode.payload : undefined;
+    const answer = episode.final_summary || episode.final_answer || payload?.summary || episode.summary;
+    const sanitized = episode.redaction_status === 'needs_redaction'
+        ? { sensitive: true, redaction_status: 'needs_redaction' }
+        : sanitizeJudgmentAnswer(answer);
+    if (!sanitized)
+        return null;
+    const episodeId = requiredString(episode.episode_id, 'episode_id');
+    const sessionId = requiredString(episode.session_id, 'session_id');
+    const turnId = requiredString(episode.turn_id, 'turn_id');
+    const completedAt = requiredString(episode.finalized_at, 'finalized_at');
+    const bodyHash = requiredString(episode.answer_digest, 'answer_digest');
+    const hasPortableOutcome = Boolean(episode.execution_outcome);
+    const outcome = hasPortableOutcome
+        ? normalizeJudgmentExecutionOutcome(episode.execution_outcome)
+        : null;
+    if (outcome && outcome.status !== 'completed')
+        return null;
+    const sourceType = outcome?.host.type === 'claude-code' ? 'agent_judgment' : 'codex_judgment';
+    return {
+        schema_version: 'knowledge_event.v1',
+        contract_version: 'knowledge_event.v1',
+        event_id: eventIdFor(episode),
+        occurred_at: completedAt,
+        captured_at: completedAt,
+        source: {
+            type: sourceType,
+            ref: outcome ? `${outcome.execution_id}:${outcome.turn_id}` : `${sessionId}:${turnId}`
+        },
+        subject: { type: 'judgment_episode', id: episodeId },
+        decision_authority: {
+            kind: 'judgment_receipt',
+            authorized: false,
+            graph_promotion_allowed: false
+        },
+        applicability_scope: { scope: 'judgment_episode', project_code: 'brainbase' },
+        permission_snapshot: { knowledge_registration: true, external_action: false },
+        source_pointer: {
+            uri: outcome
+                ? `brainbase-judgment://${encodeURIComponent(outcome.host.type)}/${encodeURIComponent(outcome.execution_id)}#turn=${encodeURIComponent(outcome.turn_id)}`
+                : `codex://threads/${sessionId}#turn=${turnId}`
+        },
+        body_hash: bodyHash,
+        parent_episode_id: episodeId,
+        ...(sanitized.sensitive
+            ? {
+                semantic_state: 'quarantined',
+                payload: {
+                    redaction_status: 'needs_redaction',
+                    ...(outcome ? { execution_outcome: outcome } : {})
+                }
+            }
+            : {
+                payload: {
+                    summary: sanitized.summary,
+                    ...(outcome ? { execution_outcome: outcome } : {})
+                }
+            })
+    };
+}

package/dist/judgment-event-outbox.d.ts

@@ -0,0 +1,182 @@
+import type { JudgmentKnowledgeEvent } from './judgment-event-adapter.js';
+/** The queue format is intentionally independent of a Host, Task, or tenant. */
+export declare const JUDGMENT_EVENT_OUTBOX_SCHEMA_VERSION: "judgment_event_outbox.v1";
+export declare const JUDGMENT_EVENT_DELIVERY_RECEIPT_SCHEMA_VERSION: "knowledge_event_delivery_receipt.v1";
+export declare const JUDGMENT_EVENT_READBACK_SCHEMA_VERSION: "knowledge_cycle_receipt.v1";
+export interface JudgmentOutboxPaths {
+    outboxDir: string;
+    deadLetterDir: string;
+    deliveryReceiptDir: string;
+    lockPath: string;
+}
+export interface ResolveJudgmentOutboxPathsOptions {
+    /** Repository/application root. Its `var/` directory is used when varDir is omitted. */
+    root?: string;
+    /** Explicit shared runtime state directory. This is the preferred production input. */
+    varDir?: string;
+    outboxDir?: string;
+    deadLetterDir?: string;
+    deliveryReceiptDir?: string;
+    lockPath?: string;
+}
+export interface JudgmentOutboxStorage {
+    mkdir(path: string, options: {
+        recursive: true;
+        mode: number;
+    }): void;
+    readFile(path: string): string;
+    readdir(path: string): string[];
+    rename(from: string, to: string): void;
+    unlink(path: string): void;
+    writeFile(path: string, value: string, options: {
+        mode: number;
+    }): void;
+    writeExclusive(path: string, value: string, mode: number): void;
+    /** Publish a fully written file without replacing an existing path. */
+    link(from: string, to: string): void;
+    stat(path: string): {
+        mtimeMs: number;
+    };
+}
+/** Resolve shared state paths without importing any runtime or repository code. */
+export declare function resolveJudgmentKnowledgeEventOutboxPaths(options?: ResolveJudgmentOutboxPathsOptions): JudgmentOutboxPaths;
+export interface JudgmentOutboxPostAck {
+    event_id: string;
+    candidate_id: string;
+    http_status?: number | null;
+    received_at: string;
+    [key: string]: unknown;
+}
+export interface JudgmentOutboxReadback {
+    schema_version: typeof JUDGMENT_EVENT_READBACK_SCHEMA_VERSION;
+    event_id: string;
+    candidate_id: string;
+    processing_stage: 'retrievable';
+    semantic_state: 'active';
+    readback_at: string;
+    [key: string]: unknown;
+}
+/**
+ * Runtime adapters own HTTP/auth/org/Task concerns. The common core only
+ * asks an adapter to post and to perform the canonical readback.
+ */
+export interface JudgmentOutboxDeliveryPort {
+    post(event: JudgmentKnowledgeEvent): Promise<JudgmentOutboxPostAck>;
+    readback(input: {
+        event: JudgmentKnowledgeEvent;
+        post: JudgmentOutboxPostAck;
+    }): Promise<JudgmentOutboxReadback>;
+}
+export interface JudgmentOutboxDeliveryError extends Error {
+    code?: string;
+    phase?: 'post' | 'readback';
+    transport?: boolean;
+    httpStatus?: number | null;
+}
+export interface JudgmentQueuedEvent {
+    event: JudgmentKnowledgeEvent;
+    delivery: {
+        attempt: number;
+        queued_at: string;
+        post_ack?: JudgmentOutboxPostAck;
+        phase?: 'readback_pending';
+        readback_attempt?: number;
+        ack_saved_at?: string;
+        last_failed_at?: string;
+        last_status?: number | null;
+        last_error_code?: string;
+        consecutive_failures?: number;
+        next_attempt_at?: string;
+    };
+}
+export interface JudgmentOutboxOperationResult {
+    status: 'queued' | 'existing';
+    path: string;
+}
+export interface JudgmentOutboxDeliveryResult {
+    status: 'unavailable' | 'busy' | 'processed';
+    delivered: number;
+    failed: number;
+    retryable: number;
+    dead_lettered: number;
+    pending: number;
+    deferred?: number;
+    last_error_code?: string;
+}
+export interface JudgmentOutboxDeliveryOptions {
+    paths: JudgmentOutboxPaths;
+    delivery?: JudgmentOutboxDeliveryPort;
+    storage?: JudgmentOutboxStorage;
+    maxAttempts?: number;
+    limit?: number;
+    backoff?: {
+        baseMs: number;
+        maxMs: number;
+    } | null;
+    now?: () => Date;
+    staleLockAfterMs?: number;
+    /** Set false only for an adapter that already owns a surrounding lock. */
+    acquireLock?: boolean;
+}
+/** Queue one event. Repeating the same event is idempotent; changing its body is a conflict. */
+export declare function enqueueJudgmentKnowledgeEvent(event: JudgmentKnowledgeEvent, options: {
+    directory: string;
+    now?: () => Date;
+    storage?: JudgmentOutboxStorage;
+}): JudgmentOutboxOperationResult;
+/** Execute an operation under the shared sender lock, or return busy. */
+export declare function withJudgmentOutboxSenderLock<T>(options: {
+    lockPath: string;
+    run: () => Promise<T> | T;
+    storage?: JudgmentOutboxStorage;
+    now?: () => Date;
+    staleAfterMs?: number;
+}): Promise<T | {
+    status: 'busy';
+}>;
+/** Deliver queued events while keeping retry, receipt, and lock behavior in the common core. */
+export declare function deliverJudgmentKnowledgeEventOutbox(options: JudgmentOutboxDeliveryOptions): Promise<JudgmentOutboxDeliveryResult>;
+export interface JudgmentOutboxSummary {
+    pending: number;
+    failing: number;
+    dead_lettered: number;
+    last_error_code: string | null;
+}
+/** Local summary used by Host diagnostics; it never calls the network. */
+export declare function summarizeJudgmentKnowledgeEventOutbox(options: {
+    paths: Pick<JudgmentOutboxPaths, 'outboxDir' | 'deadLetterDir'>;
+    now?: () => Date;
+    overdueAfterMs?: number;
+    storage?: JudgmentOutboxStorage;
+}): JudgmentOutboxSummary;
+export declare function listJudgmentKnowledgeEventOutboxExceptions(options: {
+    directory: string;
+    storage?: JudgmentOutboxStorage;
+}): Promise<Array<{
+    code: string;
+    event_id?: string;
+    path: string;
+    created_at?: string;
+}>>;
+export declare function listKnowledgeEventDeadLetters(options: {
+    directory: string;
+    storage?: JudgmentOutboxStorage;
+}): Promise<Array<{
+    code: string;
+    event_id: string;
+    path: string;
+    created_at: string;
+}>>;
+export interface JudgmentKnowledgeEventSink {
+    enqueue(event: JudgmentKnowledgeEvent): JudgmentOutboxOperationResult | Promise<JudgmentOutboxOperationResult>;
+}
+/**
+ * Host adapter candidate: the Host supplies only a completed event; runtime
+ * path selection is injected here and can later be replaced without changing
+ * the Host lifecycle or public response.
+ */
+export declare function createJudgmentKnowledgeEventOutboxSink(options: {
+    paths: JudgmentOutboxPaths;
+    storage?: JudgmentOutboxStorage;
+    now?: () => Date;
+}): JudgmentKnowledgeEventSink;