@unson/brainbase-mcp 0.44.2 → 0.45.0

package/dist/automation-run.d.ts

@@ -1,4 +1,5 @@
 import { type NormalizedRunReceipt } from './run-receipt.js';
+import { type RunReceiptPersistenceInput, type RunReceiptPort } from './run-receipt-port.js';
 import { type Awaitable, type RuntimeHostContext, type RuntimeHostPorts } from './runtime-host.js';
 export type AutomationRunOperation = 'automation.start' | 'automation.retry';
 export type AutomationRunPhase = 'claimed' | 'runner_started' | 'receipt_persisted' | 'completed' | 'retryable' | 'uncertain' | 'unknown';
@@ -46,18 +47,8 @@ export interface AutomationRunnerPort {
     start(input: AutomationRunnerStartInput): Awaitable<AutomationRunnerResult>;
     retry?(input: AutomationRunnerRetryInput): Awaitable<AutomationRunnerResult>;
 }
-export interface AutomationReceiptPersistenceInput {
-    payload: unknown;
-    normalized: NormalizedRunReceipt;
-    context: RuntimeHostContext;
-}
-export interface AutomationReceiptPort {
-    persist(input: AutomationReceiptPersistenceInput): Awaitable<unknown>;
-    query(input: {
-        request: AutomationRunRequest;
-        context: RuntimeHostContext;
-    }): Awaitable<unknown>;
-}
+export type AutomationReceiptPersistenceInput = RunReceiptPersistenceInput<RuntimeHostContext>;
+export type AutomationReceiptPort = RunReceiptPort<AutomationRunRequest, RuntimeHostContext>;
 export type AutomationRunClaim = {
     status: 'claimed';
     claimToken: string;

package/dist/automation-run.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { normalizeRunReceipt } from './run-receipt.js';
+import { assertRunReceiptPort } from './run-receipt-port.js';
 import { resolveRuntimeHostContext } from './runtime-host.js';
 function assertRequest(request) {
     if (!request || typeof request !== 'object') {
@@ -16,11 +17,7 @@ function assertPorts(ports) {
     if (!ports.runner || typeof ports.runner !== 'object' || typeof ports.runner.start !== 'function') {
         throw new Error('automation runner port with start is required');
     }
-    if (!ports.receipt || typeof ports.receipt !== 'object'
-        || typeof ports.receipt.persist !== 'function'
-        || typeof ports.receipt.query !== 'function') {
-        throw new Error('automation receipt port with persist and query is required');
-    }
+    assertRunReceiptPort(ports.receipt, 'automation receipt');
     if (!ports.runStore || typeof ports.runStore !== 'object'
         || typeof ports.runStore.claim !== 'function'
         || typeof ports.runStore.markRunnerStarted !== 'function'

package/dist/meeting-source-mcp-adapters.d.ts

@@ -0,0 +1,76 @@
+import { type MeetingSourceProvider } from './meeting-source-sync.js';
+/**
+ * Provider adapters only translate provider-specific MCP responses into the
+ * provider-neutral artifact shape consumed by the sync core.  Transport,
+ * OAuth, credentials, filesystem paths, and persistence stay with the host
+ * and are supplied through this client port.
+ */
+export declare const MEETING_SOURCE_MCP_ADAPTER_VERSION: "brainbase.meeting-source-mcp-adapters.v1";
+type UnknownRecord = Record<string, unknown>;
+type MaybePromise<T> = T | Promise<T>;
+export type MeetingSourceMcpCallTool = (name: string, args: Record<string, unknown>) => MaybePromise<unknown>;
+export interface MeetingSourceMcpClient {
+    readonly callTool: MeetingSourceMcpCallTool;
+    readonly listTools?: () => MaybePromise<unknown>;
+    readonly listResources?: () => MaybePromise<unknown>;
+}
+export interface MeetingSourceMcpAdapterConfig {
+    readonly tool?: string;
+    readonly poll_tool?: string;
+    readonly list_tool?: string;
+    readonly detail_tool?: string;
+    readonly transcript_tool?: string;
+    readonly note_tool?: string;
+    readonly provider_poll?: boolean;
+    readonly limit?: number;
+    readonly page_size?: number;
+    readonly arguments?: Readonly<Record<string, unknown>>;
+    readonly resource_prefix?: string;
+    readonly resourcePrefix?: string;
+}
+export interface MeetingSourceMcpAdapterOptions {
+    readonly provider: MeetingSourceProvider;
+    readonly client: MeetingSourceMcpClient;
+    readonly config?: MeetingSourceMcpAdapterConfig;
+    readonly log?: {
+        readonly warn?: (...args: unknown[]) => void;
+    };
+}
+export interface MeetingSourceMcpPollInput {
+    /** The provider state is accepted for Host compatibility and is not persisted here. */
+    readonly provider?: UnknownRecord;
+    readonly cursor?: UnknownRecord;
+    readonly since?: string | null;
+    readonly until?: string | null;
+}
+export interface MeetingSourceMcpTestResult {
+    readonly ok: true;
+    readonly auth_status: 'connected';
+    readonly capabilities: readonly string[];
+    readonly configured_tool: string | null;
+}
+export type MeetingSourceMcpArtifact = UnknownRecord;
+/** Extracts an array from the common MCP tool response envelopes. */
+export declare function extractMeetingSourceArtifactList(payload: unknown): MeetingSourceMcpArtifact[];
+/** Returns the structured payload or the textual payload from a CallToolResult. */
+export declare function extractMeetingSourceToolPayload(payload: unknown): unknown;
+/** Reads transcript/note text from provider-specific nested envelopes. */
+export declare function extractMeetingSourceToolText(value: unknown): string;
+export declare function meetingSourceArtifactInWindow(value: unknown, window?: {
+    readonly since?: string | null;
+    readonly until?: string | null;
+}): boolean;
+export declare class MeetingSourceMcpAdapter {
+    readonly provider: MeetingSourceProvider;
+    readonly client: MeetingSourceMcpClient;
+    readonly config: MeetingSourceMcpAdapterConfig;
+    readonly log: MeetingSourceMcpAdapterOptions['log'];
+    constructor(options: MeetingSourceMcpAdapterOptions);
+    private toolArgs;
+    private pollTactiq;
+    private pollPlaud;
+    test(_input?: unknown): Promise<MeetingSourceMcpTestResult>;
+    poll(input?: MeetingSourceMcpPollInput): Promise<MeetingSourceMcpArtifact[]>;
+}
+export declare function createMeetingSourceMcpAdapter(options: MeetingSourceMcpAdapterOptions): MeetingSourceMcpAdapter;
+export {};

package/dist/meeting-source-mcp-adapters.js

@@ -0,0 +1,294 @@
+import { SUPPORTED_MEETING_SOURCE_PROVIDERS } from './meeting-source-sync.js';
+/**
+ * Provider adapters only translate provider-specific MCP responses into the
+ * provider-neutral artifact shape consumed by the sync core.  Transport,
+ * OAuth, credentials, filesystem paths, and persistence stay with the host
+ * and are supplied through this client port.
+ */
+export const MEETING_SOURCE_MCP_ADAPTER_VERSION = 'brainbase.meeting-source-mcp-adapters.v1';
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function parseJsonMaybe(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+/** Extracts an array from the common MCP tool response envelopes. */
+export function extractMeetingSourceArtifactList(payload) {
+    if (!payload)
+        return [];
+    if (Array.isArray(payload))
+        return payload.filter((item) => Boolean(asRecord(item)));
+    const record = asRecord(payload);
+    if (!record) {
+        const parsed = parseJsonMaybe(payload);
+        return parsed === payload ? [] : extractMeetingSourceArtifactList(parsed);
+    }
+    for (const key of ['artifacts', 'items', 'records', 'results', 'files', 'data', 'transcripts', 'recordings']) {
+        const value = record[key];
+        if (Array.isArray(value))
+            return value.filter((item) => Boolean(asRecord(item)));
+    }
+    if (record.structuredContent !== undefined)
+        return extractMeetingSourceArtifactList(record.structuredContent);
+    if (Array.isArray(record.content)) {
+        const parsedItems = record.content.flatMap((item) => {
+            const entry = asRecord(item);
+            if (!entry || entry.type !== 'text' || typeof entry.text !== 'string')
+                return [];
+            const parsed = parseJsonMaybe(entry.text);
+            return parsed === null ? [] : extractMeetingSourceArtifactList(parsed);
+        });
+        if (parsedItems.length)
+            return parsedItems;
+    }
+    return [];
+}
+/** Returns the structured payload or the textual payload from a CallToolResult. */
+export function extractMeetingSourceToolPayload(payload) {
+    if (!payload)
+        return null;
+    const record = asRecord(payload);
+    if (!record)
+        return parseJsonMaybe(payload);
+    if (record.structuredContent !== undefined)
+        return record.structuredContent;
+    if (Array.isArray(record.content)) {
+        const textItems = record.content
+            .map((item) => asRecord(item))
+            .filter((item) => Boolean(item && item.type === 'text' && typeof item.text === 'string'));
+        for (const item of textItems) {
+            const parsed = parseJsonMaybe(item.text);
+            if (parsed !== null)
+                return parsed;
+        }
+        return textItems.map((item) => item.text).join('\n');
+    }
+    return payload;
+}
+/** Reads transcript/note text from provider-specific nested envelopes. */
+export function extractMeetingSourceToolText(value) {
+    if (!value)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map(extractMeetingSourceToolText).filter(Boolean).join('\n');
+    const record = asRecord(value);
+    if (!record)
+        return '';
+    for (const key of ['text', 'transcript', 'transcript_text', 'data_content', 'content', 'markdown', 'summary']) {
+        if (typeof record[key] === 'string')
+            return record[key];
+    }
+    return extractMeetingSourceToolText(record.detailedSummary ?? record.data);
+}
+export function meetingSourceArtifactInWindow(value, window = {}) {
+    if (!value)
+        return true;
+    const timestamp = Date.parse(String(value));
+    if (Number.isNaN(timestamp))
+        return true;
+    if (window.since && timestamp < Date.parse(window.since))
+        return false;
+    if (window.until && timestamp > Date.parse(window.until))
+        return false;
+    return true;
+}
+function extractResourceList(payload) {
+    const record = asRecord(payload);
+    if (Array.isArray(payload))
+        return payload.filter((item) => Boolean(asRecord(item)));
+    if (!record)
+        return [];
+    if (Array.isArray(record.resources))
+        return record.resources.filter((item) => Boolean(asRecord(item)));
+    if (record.structuredContent !== undefined)
+        return extractResourceList(record.structuredContent);
+    return [];
+}
+function configuredTool(config) {
+    return config.tool ?? config.poll_tool ?? config.list_tool ?? null;
+}
+function boundedNumber(value, fallback, maximum) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(Math.max(Math.trunc(parsed), 1), maximum);
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function logFailure(logger, provider, kind, externalId) {
+    // Do not include provider response/error text: it can contain an access token.
+    logger?.warn?.(`[meeting-source] ${provider} ${kind} fetch failed for ${externalId}`);
+}
+function toolNames(payload) {
+    const record = asRecord(payload);
+    const tools = record && Array.isArray(record.tools) ? record.tools : [];
+    return tools
+        .map((tool) => asRecord(tool)?.name)
+        .filter((name) => typeof name === 'string' && name.trim().length > 0);
+}
+export class MeetingSourceMcpAdapter {
+    provider;
+    client;
+    config;
+    log;
+    constructor(options) {
+        if (!options?.client || typeof options.client.callTool !== 'function') {
+            throw new TypeError('client.callTool is required');
+        }
+        if (!SUPPORTED_MEETING_SOURCE_PROVIDERS.includes(options.provider)) {
+            throw new Error(`unsupported meeting source provider adapter: ${String(options.provider)}`);
+        }
+        this.provider = options.provider;
+        this.client = options.client;
+        this.config = Object.freeze({ ...(options.config ?? {}) });
+        this.log = options.log;
+    }
+    toolArgs(input) {
+        return {
+            ...(this.config.arguments ?? {}),
+            since: input.since ?? null,
+            until: input.until ?? null,
+            updated_since: input.since ?? null,
+            cursor: input.cursor ?? {},
+        };
+    }
+    async pollTactiq(input) {
+        const result = await this.client.callTool(this.config.tool ?? this.config.poll_tool ?? 'list_recent_meetings', {
+            ...(this.config.arguments ?? {}),
+            limit: boundedNumber(this.config.limit ?? this.config.page_size, 50, 50),
+        });
+        const meetings = extractMeetingSourceArtifactList(result).filter((meeting) => meetingSourceArtifactInWindow(meeting.createdAt ?? meeting.created_at ?? meeting.started_at, input));
+        const artifacts = [];
+        for (const meeting of meetings) {
+            const meetingId = stringValue(meeting.id ?? meeting.external_id);
+            let detail = null;
+            if (meetingId) {
+                try {
+                    detail = asRecord(extractMeetingSourceToolPayload(await this.client.callTool(this.config.detail_tool ?? 'get_meeting', { id: meetingId })));
+                }
+                catch {
+                    logFailure(this.log, this.provider, 'detail', meetingId);
+                }
+            }
+            const summary = asRecord(detail?.detailedSummary ?? meeting.detailedSummary);
+            const noteText = summary?.status === 'ready'
+                ? extractMeetingSourceToolText(summary.content)
+                : extractMeetingSourceToolText(summary);
+            artifacts.push({
+                ...meeting,
+                ...(detail ?? {}),
+                ...(meetingId ? { external_id: meetingId } : {}),
+                title: detail?.title ?? meeting.title,
+                started_at: meeting.createdAt ?? detail?.createdAt ?? meeting.created_at ?? detail?.created_at ?? null,
+                updated_at: meeting.createdAt ?? detail?.createdAt ?? meeting.updated_at ?? detail?.updated_at ?? null,
+                participants: meeting.attendees ?? detail?.attendees ?? meeting.participants ?? [],
+                note_text: noteText,
+                meeting_mode: 'online',
+                resource_uri: meeting.url ?? detail?.url ?? meeting.resource_uri ?? null,
+            });
+        }
+        return artifacts;
+    }
+    async pollPlaud(input) {
+        const result = await this.client.callTool(this.config.tool ?? this.config.poll_tool ?? 'list_files', {
+            page: 1,
+            page_size: boundedNumber(this.config.page_size, 20, 200),
+            ...(input.since ? { date_from: input.since.slice(0, 10) } : {}),
+            ...(input.until ? { date_to: input.until.slice(0, 10) } : {}),
+            ...(this.config.arguments ?? {}),
+        });
+        const files = extractMeetingSourceArtifactList(result).filter((file) => meetingSourceArtifactInWindow(file.start_at ?? file.created_at ?? file.started_at, input));
+        const artifacts = [];
+        for (const file of files) {
+            const fileId = stringValue(file.id ?? file.file_id ?? file.fileId);
+            let transcriptText = '';
+            let noteText = '';
+            if (fileId) {
+                try {
+                    transcriptText = extractMeetingSourceToolText(extractMeetingSourceToolPayload(await this.client.callTool(this.config.transcript_tool ?? 'get_transcript', { file_id: fileId })));
+                }
+                catch {
+                    logFailure(this.log, this.provider, 'transcript', fileId);
+                }
+                try {
+                    noteText = extractMeetingSourceToolText(extractMeetingSourceToolPayload(await this.client.callTool(this.config.note_tool ?? 'get_note', { file_id: fileId })));
+                }
+                catch {
+                    logFailure(this.log, this.provider, 'note', fileId);
+                }
+            }
+            artifacts.push({
+                ...file,
+                ...(fileId ? { external_id: fileId } : {}),
+                title: file.name ?? file.title,
+                started_at: file.start_at ?? file.created_at ?? null,
+                updated_at: file.created_at ?? file.start_at ?? null,
+                transcript_text: transcriptText,
+                note_text: noteText,
+                meeting_mode: 'offline',
+                resource_uri: fileId ? `plaud:${fileId}` : null,
+            });
+        }
+        return artifacts;
+    }
+    async test(_input) {
+        let capabilities = [];
+        if (typeof this.client.listTools === 'function') {
+            try {
+                capabilities = toolNames(await this.client.listTools());
+            }
+            catch {
+                capabilities = [];
+            }
+        }
+        return {
+            ok: true,
+            auth_status: 'connected',
+            capabilities,
+            configured_tool: configuredTool(this.config),
+        };
+    }
+    async poll(input = {}) {
+        // Preserve the legacy Host predicate: provider polling is selected when it
+        // is explicitly enabled or when no primary tool is configured. The legacy
+        // provider path intentionally treats poll_tool/list_tool as provider
+        // configuration and only uses them inside the provider-specific adapter.
+        const providerPoll = this.config.provider_poll === true || !this.config.tool;
+        if (this.provider === 'tactiq' && providerPoll)
+            return this.pollTactiq(input);
+        if (this.provider === 'plaud' && providerPoll)
+            return this.pollPlaud(input);
+        const tool = configuredTool(this.config);
+        if (tool) {
+            return extractMeetingSourceArtifactList(await this.client.callTool(tool, this.toolArgs(input)));
+        }
+        if (typeof this.client.listResources !== 'function')
+            return [];
+        const prefix = this.config.resource_prefix ?? this.config.resourcePrefix;
+        return extractResourceList(await this.client.listResources())
+            .filter((resource) => !prefix || String(resource.uri ?? '').startsWith(prefix))
+            .map((resource) => ({
+            id: resource.uri,
+            title: resource.name ?? resource.title ?? resource.uri,
+            resource_uri: resource.uri,
+            updated_at: resource.updated_at ?? resource.modified_at ?? null,
+            provider: this.provider,
+        }));
+    }
+}
+export function createMeetingSourceMcpAdapter(options) {
+    return new MeetingSourceMcpAdapter(options);
+}

package/dist/meeting-source-sync-common-adapter.d.ts

@@ -0,0 +1,19 @@
+import { dedupeMeetingSourceArtifacts, normalizeMeetingSourceArtifact, runMeetingSourceSync, type MeetingSourceArtifact, type MeetingSourceProvider, type MeetingSourceSyncPorts, type MeetingSourceSyncResult } from './meeting-source-sync.js';
+/**
+ * Host composition seam for the already implemented provider-neutral sync
+ * core.  It deliberately delegates every operation; normalization, dedupe,
+ * durable claim/save/readback, and retry behavior remain owned by the core.
+ */
+export declare const MEETING_SOURCE_SYNC_COMMON_ADAPTER_VERSION: "brainbase.meeting-source-sync-common-adapter.v1";
+export interface MeetingSourceSyncCommonCore {
+    readonly normalizeMeetingSourceArtifact: typeof normalizeMeetingSourceArtifact;
+    readonly dedupeMeetingSourceArtifacts: typeof dedupeMeetingSourceArtifacts;
+    readonly runMeetingSourceSync: typeof runMeetingSourceSync;
+}
+export interface MeetingSourceSyncCommonAdapter {
+    normalizeSourceArtifact(raw: Record<string, unknown>, provider: MeetingSourceProvider): MeetingSourceArtifact;
+    dedupeSourceArtifacts(artifacts: readonly MeetingSourceArtifact[]): ReturnType<typeof dedupeMeetingSourceArtifacts>;
+    sync(input: Parameters<typeof runMeetingSourceSync>[0], ports: MeetingSourceSyncPorts): Promise<MeetingSourceSyncResult>;
+}
+export declare function createMeetingSourceSyncCommonAdapter(commonCore: MeetingSourceSyncCommonCore): MeetingSourceSyncCommonAdapter;
+export declare const createDefaultMeetingSourceSyncCommonAdapter: () => MeetingSourceSyncCommonAdapter;

package/dist/meeting-source-sync-common-adapter.js

@@ -0,0 +1,34 @@
+import { dedupeMeetingSourceArtifacts, normalizeMeetingSourceArtifact, runMeetingSourceSync, } from './meeting-source-sync.js';
+/**
+ * Host composition seam for the already implemented provider-neutral sync
+ * core.  It deliberately delegates every operation; normalization, dedupe,
+ * durable claim/save/readback, and retry behavior remain owned by the core.
+ */
+export const MEETING_SOURCE_SYNC_COMMON_ADAPTER_VERSION = 'brainbase.meeting-source-sync-common-adapter.v1';
+export function createMeetingSourceSyncCommonAdapter(commonCore) {
+    if (!commonCore || typeof commonCore.runMeetingSourceSync !== 'function') {
+        throw new TypeError('meeting source sync common core is required');
+    }
+    if (typeof commonCore.normalizeMeetingSourceArtifact !== 'function') {
+        throw new TypeError('meeting source sync normalization export is required');
+    }
+    if (typeof commonCore.dedupeMeetingSourceArtifacts !== 'function') {
+        throw new TypeError('meeting source sync dedupe export is required');
+    }
+    return Object.freeze({
+        normalizeSourceArtifact(raw, provider) {
+            return commonCore.normalizeMeetingSourceArtifact(raw, provider);
+        },
+        dedupeSourceArtifacts(artifacts) {
+            return commonCore.dedupeMeetingSourceArtifacts(artifacts);
+        },
+        sync(input, ports) {
+            return commonCore.runMeetingSourceSync(input, ports);
+        },
+    });
+}
+export const createDefaultMeetingSourceSyncCommonAdapter = () => createMeetingSourceSyncCommonAdapter({
+    normalizeMeetingSourceArtifact,
+    dedupeMeetingSourceArtifacts,
+    runMeetingSourceSync,
+});

package/dist/mesh.d.ts

@@ -28,6 +28,16 @@ export declare function createMeshEnvelope(input: MeshEnvelopeInput, options?: {
     nonceFactory?: () => string;
 }): MeshEnvelope;
 export declare function normalizeMeshEnvelope(value: unknown): MeshEnvelope;
+/**
+ * Parse a serialized or already-decoded envelope through the same strict
+ * boundary used by the host adapter.
+ *
+ * The host runtime accepts both JSON strings and objects. Keeping that input
+ * shape here lets a host compare the local contract result before handing an
+ * envelope to its network or crypto layer without moving either dependency
+ * into the portable package.
+ */
+export declare function parseMeshEnvelope(value: unknown): MeshEnvelope;
 export interface MeshProjectPort {
     projectId: string;
     localPath?: string;

package/dist/mesh.js

@@ -21,16 +21,24 @@ function text(value, field) {
         throw new MeshContractError(field);
     return value.trim();
 }
-function isJson(value) {
-    if (value === null || ['string', 'number', 'boolean'].includes(typeof value))
+function isJson(value, ancestors = new Set()) {
+    if (value === null || ['string', 'boolean'].includes(typeof value))
         return true;
-    if (Array.isArray(value))
-        return value.every(isJson);
-    if (typeof value === 'object')
-        return Object.values(value).every(isJson);
-    return false;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    const valid = Array.isArray(value)
+        ? value.every((entry) => isJson(entry, ancestors))
+        : (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+            && Object.values(value).every((entry) => isJson(entry, ancestors));
+    ancestors.delete(value);
+    return valid;
 }
 export function createMeshEnvelope(input, options = {}) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new MeshContractError('envelope');
     const from = text(input.from, 'from');
     const to = text(input.to, 'to');
     if (!MESH_ENVELOPE_TYPES.includes(input.type))
@@ -38,16 +46,16 @@ export function createMeshEnvelope(input, options = {}) {
     if (input.payload !== undefined && !isJson(input.payload))
         throw new MeshContractError('payload');
     const ts = options.now ?? Date.now();
-    if (!Number.isFinite(ts))
+    if (!Number.isFinite(ts) || ts <= 0)
         throw new MeshContractError('ts');
     return {
-        id: options.idFactory?.() ?? randomUUID(),
+        id: text(options.idFactory?.() ?? randomUUID(), 'id'),
         from,
         to,
         type: input.type,
         payload: input.payload ?? null,
         ts,
-        nonce: options.nonceFactory?.() ?? randomUUID()
+        nonce: text(options.nonceFactory?.() ?? randomUUID(), 'nonce')
     };
 }
 export function normalizeMeshEnvelope(value) {
@@ -64,18 +72,40 @@ export function normalizeMeshEnvelope(value) {
     if (!Number.isFinite(candidate.ts) || typeof candidate.ts !== 'number' || candidate.ts <= 0) {
         throw new MeshContractError('ts');
     }
-    if (!isJson(candidate.payload))
+    const payload = candidate.payload ?? null;
+    if (!isJson(payload))
         throw new MeshContractError('payload');
     return {
         id,
         from,
         to,
         type: candidate.type,
-        payload: candidate.payload,
+        payload,
         ts: candidate.ts,
         nonce
     };
 }
+/**
+ * Parse a serialized or already-decoded envelope through the same strict
+ * boundary used by the host adapter.
+ *
+ * The host runtime accepts both JSON strings and objects. Keeping that input
+ * shape here lets a host compare the local contract result before handing an
+ * envelope to its network or crypto layer without moving either dependency
+ * into the portable package.
+ */
+export function parseMeshEnvelope(value) {
+    let decoded = value;
+    if (typeof value === 'string') {
+        try {
+            decoded = JSON.parse(value);
+        }
+        catch {
+            throw new MeshContractError('envelope', 'mesh envelope JSON is invalid');
+        }
+    }
+    return normalizeMeshEnvelope(decoded);
+}
 export function normalizeMeshNodeProfile(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new MeshContractError('profile');
@@ -94,7 +124,8 @@ export function normalizeMeshNodeProfile(value) {
         const ports = item.ports === undefined
             ? undefined
             : item.ports && typeof item.ports === 'object' && !Array.isArray(item.ports)
-                && Object.entries(item.ports).every(([key, port]) => Boolean(key) && (typeof port === 'string' || typeof port === 'number'))
+                && Object.entries(item.ports).every(([key, port]) => Boolean(key)
+                    && (typeof port === 'string' || (typeof port === 'number' && Number.isFinite(port))))
                 ? { ...item.ports }
                 : (() => { throw new MeshContractError(`projects.${index}.ports`); })();
         return { projectId, localPath, globInclude, ports };

package/dist/routine-personal-kg.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Portable batch boundary for meeting-derived Personal KG extraction.
+ *
+ * A consumer supplies the meeting rule/extraction callback because source
+ * schemas, identity, redaction policy, and candidate shape are tenant-owned.
+ * This module owns the common collection/count contract and keeps the batch
+ * boundary independent from any database or model provider.
+ */
+export interface RoutinePersonalKgMeetingResult<TCandidate = unknown> {
+    adopted?: readonly TCandidate[];
+    rejected?: readonly unknown[];
+    needs_review?: readonly unknown[];
+}
+export interface RoutinePersonalKgExtractionOptions<TMeeting, TCandidate = unknown> {
+    date: string;
+    meetings?: readonly TMeeting[];
+    sourceSystem: string;
+    extract: (input: {
+        meeting: TMeeting;
+        date: string;
+        index: number;
+    }) => RoutinePersonalKgMeetingResult<TCandidate>;
+    dedupe?: (candidates: readonly TCandidate[]) => readonly TCandidate[];
+}
+export interface RoutinePersonalKgExtractionResult<TCandidate = unknown> {
+    date: string;
+    source_system: string;
+    counts: {
+        adopted: number;
+        rejected: number;
+        needs_review: number;
+    };
+    adopted: TCandidate[];
+    rejected: unknown[];
+    needs_review: unknown[];
+}
+/**
+ * Collect meeting extraction results using the portable result shape.
+ * Extraction errors intentionally propagate to the consumer: a host decides
+ * whether a failed meeting should be retried, surfaced for review, or stop a
+ * run, and the common package must not silently convert it to success.
+ */
+export declare function extractRoutinePersonalKgCandidates<TMeeting, TCandidate = unknown>(options: RoutinePersonalKgExtractionOptions<TMeeting, TCandidate>): RoutinePersonalKgExtractionResult<TCandidate>;

package/dist/routine-personal-kg.js

@@ -0,0 +1,65 @@
+/**
+ * Portable batch boundary for meeting-derived Personal KG extraction.
+ *
+ * A consumer supplies the meeting rule/extraction callback because source
+ * schemas, identity, redaction policy, and candidate shape are tenant-owned.
+ * This module owns the common collection/count contract and keeps the batch
+ * boundary independent from any database or model provider.
+ */
+/**
+ * Collect meeting extraction results using the portable result shape.
+ * Extraction errors intentionally propagate to the consumer: a host decides
+ * whether a failed meeting should be retried, surfaced for review, or stop a
+ * run, and the common package must not silently convert it to success.
+ */
+export function extractRoutinePersonalKgCandidates(options) {
+    if (!options || typeof options !== 'object') {
+        throw new Error('routine Personal KG extraction options are required');
+    }
+    if (typeof options.date !== 'string' || options.date.trim() === '') {
+        throw new Error('routine Personal KG extraction date is required');
+    }
+    if (typeof options.sourceSystem !== 'string' || options.sourceSystem.trim() === '') {
+        throw new Error('routine Personal KG extraction sourceSystem is required');
+    }
+    if (typeof options.extract !== 'function') {
+        throw new Error('routine Personal KG extraction callback is required');
+    }
+    const adopted = [];
+    const rejected = [];
+    const needsReview = [];
+    const meetings = Array.isArray(options.meetings) ? options.meetings : [];
+    meetings.forEach((meeting, index) => {
+        const result = options.extract({ meeting, date: options.date, index });
+        if (!result || typeof result !== 'object' || Array.isArray(result)) {
+            throw new Error('routine Personal KG extraction result must be a non-null object');
+        }
+        const buckets = [
+            ['adopted', result.adopted],
+            ['rejected', result.rejected],
+            ['needs_review', result.needs_review]
+        ];
+        for (const [name, bucket] of buckets) {
+            if (bucket !== undefined && !Array.isArray(bucket)) {
+                throw new Error(`routine Personal KG extraction result ${name} must be an array`);
+            }
+        }
+        adopted.push(...(result.adopted ?? []));
+        rejected.push(...(result.rejected ?? []));
+        needsReview.push(...(result.needs_review ?? []));
+    });
+    const deduped = options.dedupe ? options.dedupe(adopted) : adopted;
+    const finalAdopted = Array.isArray(deduped) ? [...deduped] : adopted;
+    return {
+        date: options.date,
+        source_system: options.sourceSystem,
+        counts: {
+            adopted: finalAdopted.length,
+            rejected: rejected.length,
+            needs_review: needsReview.length
+        },
+        adopted: finalAdopted,
+        rejected,
+        needs_review: needsReview
+    };
+}

package/dist/routine-production-ports.d.ts

@@ -0,0 +1,30 @@
+import type { Awaitable } from './runtime-host.js';
+/**
+ * Consumer-owned operations used by the routine endpoints.
+ *
+ * The implementation belongs to the application that owns Graph, tenant,
+ * credentials, and persistence. This public contract keeps the routine
+ * cycle independent from those details while giving each consumer one
+ * explicit seam to validate at composition time.
+ */
+export interface RoutineProductionPorts {
+    reconcile(input?: unknown, context?: unknown): Awaitable<unknown>;
+    compress(input?: unknown, context?: unknown): Awaitable<unknown>;
+    buildNightOutput(input?: unknown, context?: unknown): Awaitable<unknown>;
+    verify(input?: unknown, context?: unknown): Awaitable<unknown>;
+    recallGraph(input?: unknown, context?: unknown): Awaitable<unknown>;
+    recallPersonalKg(input?: unknown, context?: unknown): Awaitable<unknown>;
+    generate(input?: unknown, context?: unknown): Awaitable<unknown>;
+    recordUsage(input?: unknown, context?: unknown): Awaitable<unknown>;
+    evaluateMetrics(input?: unknown, context?: unknown): Awaitable<unknown>;
+    createImprovementCandidates(input?: unknown, context?: unknown): Awaitable<unknown>;
+    listKnowledgeReviews(input?: unknown, context?: unknown): Awaitable<unknown>;
+}
+/**
+ * Validate a consumer's routine endpoint port set without resolving any
+ * consumer-specific dependency. The same instance is returned so class
+ * methods retain their receiver and injected state.
+ */
+export declare function assertRoutineProductionPorts(value: unknown): RoutineProductionPorts;
+/** Alias used by composition roots that prefer a constructor-shaped API. */
+export declare function createRoutineProductionPorts(value: unknown): RoutineProductionPorts;

package/dist/routine-production-ports.js

@@ -0,0 +1,34 @@
+const REQUIRED_ROUTINE_PRODUCTION_PORTS = [
+    'reconcile',
+    'compress',
+    'buildNightOutput',
+    'verify',
+    'recallGraph',
+    'recallPersonalKg',
+    'generate',
+    'recordUsage',
+    'evaluateMetrics',
+    'createImprovementCandidates',
+    'listKnowledgeReviews'
+];
+/**
+ * Validate a consumer's routine endpoint port set without resolving any
+ * consumer-specific dependency. The same instance is returned so class
+ * methods retain their receiver and injected state.
+ */
+export function assertRoutineProductionPorts(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('routine production ports are required');
+    }
+    const ports = value;
+    for (const name of REQUIRED_ROUTINE_PRODUCTION_PORTS) {
+        if (typeof ports[name] !== 'function') {
+            throw new Error(`routine production port ${name} must be a function`);
+        }
+    }
+    return value;
+}
+/** Alias used by composition roots that prefer a constructor-shaped API. */
+export function createRoutineProductionPorts(value) {
+    return assertRoutineProductionPorts(value);
+}

package/dist/routine-runtime.d.ts

@@ -1,4 +1,5 @@
 import { type NormalizedRunReceipt } from './run-receipt.js';
+import { type RunReceiptPersistenceInput, type RunReceiptPort } from './run-receipt-port.js';
 import { type Awaitable, type RuntimeHostContext, type RuntimeHostPorts } from './runtime-host.js';
 export type RoutineScheduleKind = 'daily' | 'weekly';
 export interface RoutineExpectationSchedule {
@@ -66,18 +67,8 @@ export interface RoutineRunnerPort {
     start(input: RoutineRunnerStartInput): Awaitable<RoutineRunnerResult>;
     retry?(input: RoutineRunnerRetryInput): Awaitable<RoutineRunnerResult>;
 }
-export interface RoutineReceiptPersistenceInput {
-    payload: unknown;
-    normalized: NormalizedRunReceipt;
-    context: RuntimeHostContext;
-}
-export interface RoutineReceiptPort {
-    persist(input: RoutineReceiptPersistenceInput): Awaitable<unknown>;
-    query(input: {
-        request: RoutineRunRequest;
-        context: RuntimeHostContext;
-    }): Awaitable<unknown>;
-}
+export type RoutineReceiptPersistenceInput = RunReceiptPersistenceInput<RuntimeHostContext>;
+export type RoutineReceiptPort = RunReceiptPort<RoutineRunRequest, RuntimeHostContext>;
 export interface RoutineRuntimePorts extends RuntimeHostPorts {
     runner: RoutineRunnerPort;
     receipt: RoutineReceiptPort;

package/dist/routine-runtime.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { normalizeRunReceipt } from './run-receipt.js';
+import { assertRunReceiptPort } from './run-receipt-port.js';
 import { resolveRuntimeHostContext } from './runtime-host.js';
 function fail(index, field, message) {
     throw new Error(`expectations[${index}].${field} ${message}`);
@@ -138,11 +139,7 @@ function assertRoutinePorts(ports) {
     if (!ports.runner || typeof ports.runner !== 'object' || typeof ports.runner.start !== 'function') {
         throw new Error('routine runner port with start is required');
     }
-    if (!ports.receipt || typeof ports.receipt !== 'object'
-        || typeof ports.receipt.persist !== 'function'
-        || typeof ports.receipt.query !== 'function') {
-        throw new Error('routine receipt port with persist and query is required');
-    }
+    assertRunReceiptPort(ports.receipt, 'routine receipt');
 }
 export class RoutineRuntimeService {
     ports;

package/dist/routines.d.ts

@@ -1,6 +1,8 @@
 export * from './routine-runtime.js';
 export * from './routine-cycle.js';
 export * from './routine-liveness.js';
+export * from './routine-production-ports.js';
+export * from './routine-personal-kg.js';
 export type RoutineKind = 'ohayo' | 'oyasumi' | 'retro';
 export type RoutineTarget = 'codex' | 'claude';
 export interface ScheduleOptions {

package/dist/routines.js

@@ -1,6 +1,8 @@
 export * from './routine-runtime.js';
 export * from './routine-cycle.js';
 export * from './routine-liveness.js';
+export * from './routine-production-ports.js';
+export * from './routine-personal-kg.js';
 const ALL_KINDS = ['ohayo', 'oyasumi', 'retro'];
 const DOW_TO_RRULE = {
     MON: 'MO', TUE: 'TU', WED: 'WE', THU: 'TH', FRI: 'FR', SAT: 'SA', SUN: 'SU'

package/dist/run-receipt-port.d.ts

@@ -0,0 +1,27 @@
+import type { NormalizedRunReceipt } from './run-receipt.js';
+/**
+ * Shared host boundary for durable run-receipt ingest and query.
+ *
+ * The OSS package only defines the contract and validates the port shape.
+ * Storage, authentication, organization scoping, HTTP, and readback remain
+ * owned by the consumer that supplies this port.
+ */
+export interface RunReceiptPersistenceInput<Context = unknown> {
+    payload: unknown;
+    normalized: NormalizedRunReceipt;
+    context: Context;
+}
+export interface RunReceiptQueryInput<Request = unknown, Context = unknown> {
+    request: Request;
+    context: Context;
+}
+export interface RunReceiptPort<Request = unknown, Context = unknown, Persisted = unknown, Queried = unknown> {
+    persist(input: RunReceiptPersistenceInput<Context>): Persisted | PromiseLike<Persisted>;
+    query(input: RunReceiptQueryInput<Request, Context>): Queried | PromiseLike<Queried>;
+}
+/**
+ * Validate the common receipt boundary without assuming a storage provider.
+ * A label keeps the existing routine/automation diagnostics specific to their
+ * host-facing service while sharing the actual shape check.
+ */
+export declare function assertRunReceiptPort(port: unknown, label?: string): asserts port is RunReceiptPort;

package/dist/run-receipt-port.js

@@ -0,0 +1,12 @@
+/**
+ * Validate the common receipt boundary without assuming a storage provider.
+ * A label keeps the existing routine/automation diagnostics specific to their
+ * host-facing service while sharing the actual shape check.
+ */
+export function assertRunReceiptPort(port, label = 'run receipt') {
+    if (!port || typeof port !== 'object'
+        || typeof port.persist !== 'function'
+        || typeof port.query !== 'function') {
+        throw new Error(`${label} port with persist and query is required`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.44.2",
+  "version": "0.45.0",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -163,6 +163,10 @@
       "types": "./dist/run-receipt.d.ts",
       "import": "./dist/run-receipt.js"
     },
+    "./run-receipt-port": {
+      "types": "./dist/run-receipt-port.d.ts",
+      "import": "./dist/run-receipt-port.js"
+    },
     "./routines": {
       "types": "./dist/routines.d.ts",
       "import": "./dist/routines.js"
@@ -191,6 +195,10 @@
       "types": "./dist/meeting-source-connection.d.ts",
       "import": "./dist/meeting-source-connection.js"
     },
+    "./meeting-source-mcp-adapters": {
+      "types": "./dist/meeting-source-mcp-adapters.d.ts",
+      "import": "./dist/meeting-source-mcp-adapters.js"
+    },
     "./meeting-source-reader": {
       "types": "./dist/meeting-source-reader.d.ts",
       "import": "./dist/meeting-source-reader.js"
@@ -399,6 +407,10 @@
       "types": "./dist/meeting-source-sync.d.ts",
       "import": "./dist/meeting-source-sync.js"
     },
+    "./meeting-source-sync-common-adapter": {
+      "types": "./dist/meeting-source-sync-common-adapter.d.ts",
+      "import": "./dist/meeting-source-sync-common-adapter.js"
+    },
     "./meeting-minutes-http": {
       "types": "./dist/meeting-minutes-http.d.ts",
       "import": "./dist/meeting-minutes-http.js"
@@ -608,5 +620,5 @@
     "url": "https://github.com/Unson-LLC/brainbase/issues"
   },
   "homepage": "https://github.com/Unson-LLC/brainbase#readme",
-  "gitHead": "108ed1e1c5066b088e6c61b9d6ff87149a9f2ce6"
+  "gitHead": "10ff1144069d177b6a1c3857a69182513ff55372"
 }