@unson/brainbase-mcp 0.44.0 → 0.44.1

package/dist/routine-runtime.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeRunReceipt } from './run-receipt.js';
+import { resolveRuntimeHostContext } from './runtime-host.js';
+function fail(index, field, message) {
+    throw new Error(`expectations[${index}].${field} ${message}`);
+}
+function requireString(value, index, field) {
+    if (typeof value !== 'string' || value.trim() === '' || value !== value.trim()) {
+        fail(index, field, 'must be a non-empty trimmed string');
+    }
+    return value;
+}
+function requireInteger(value, index, field, minimum, maximum) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        fail(index, field, `must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+/**
+ * Parse a routine expectation document without assuming an organization,
+ * tenant, timezone, or scheduler. Consumers that need those constraints pass
+ * them explicitly, which keeps the common package portable.
+ */
+export function parseRoutineExpectations(value, constraints = {}) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error('expectations must be a non-empty array');
+    }
+    const routines = new Set();
+    const automationIds = new Set();
+    return value.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error(`expectations[${index}] must be an object`);
+        }
+        const record = entry;
+        const routine = requireString(record.routine, index, 'routine');
+        const automationId = requireString(record.automation_id, index, 'automation_id');
+        if (routines.has(routine))
+            fail(index, 'routine', 'must be unique');
+        if (automationIds.has(automationId))
+            fail(index, 'automation_id', 'must be unique');
+        routines.add(routine);
+        automationIds.add(automationId);
+        const sourceType = requireString(record.source_type, index, 'source_type');
+        const projectId = requireString(record.project_id, index, 'project_id');
+        const timezone = requireString(record.timezone, index, 'timezone');
+        if (constraints.sourceType !== undefined && sourceType !== constraints.sourceType) {
+            fail(index, 'source_type', `must be ${constraints.sourceType}`);
+        }
+        if (constraints.projectId !== undefined && projectId !== constraints.projectId) {
+            fail(index, 'project_id', `must be ${constraints.projectId}`);
+        }
+        if (constraints.timezone !== undefined && timezone !== constraints.timezone) {
+            fail(index, 'timezone', `must be ${constraints.timezone}`);
+        }
+        const scheduleValue = record.schedule;
+        if (!scheduleValue || typeof scheduleValue !== 'object' || Array.isArray(scheduleValue)) {
+            fail(index, 'schedule', 'must be an object');
+        }
+        const scheduleRecord = scheduleValue;
+        const kind = requireString(scheduleRecord.kind, index, 'schedule.kind');
+        if (kind !== 'daily' && kind !== 'weekly') {
+            fail(index, 'schedule.kind', 'must be daily or weekly');
+        }
+        const schedule = {
+            kind,
+            hour: requireInteger(scheduleRecord.hour, index, 'schedule.hour', 0, 23),
+            minute: requireInteger(scheduleRecord.minute, index, 'schedule.minute', 0, 59)
+        };
+        if (kind === 'weekly') {
+            schedule.day_of_week = requireInteger(scheduleRecord.day_of_week, index, 'schedule.day_of_week', 0, 6);
+        }
+        const graceMinutes = requireInteger(record.grace_minutes, index, 'grace_minutes', 1, 24 * 60);
+        if (!Array.isArray(record.required_artifacts) || record.required_artifacts.length === 0) {
+            fail(index, 'required_artifacts', 'must be a non-empty array');
+        }
+        const requiredArtifacts = record.required_artifacts.map((artifact, artifactIndex) => requireString(artifact, index, `required_artifacts[${artifactIndex}]`));
+        if (new Set(requiredArtifacts).size !== requiredArtifacts.length) {
+            fail(index, 'required_artifacts', 'must not contain duplicates');
+        }
+        return {
+            routine,
+            automation_id: automationId,
+            source_type: sourceType,
+            project_id: projectId,
+            timezone,
+            schedule,
+            grace_minutes: graceMinutes,
+            required_artifacts: requiredArtifacts
+        };
+    });
+}
+export function loadRoutineExpectations(filePath, constraints = {}) {
+    return parseRoutineExpectations(JSON.parse(fs.readFileSync(filePath, 'utf8')), constraints);
+}
+/** Read routine dead-letter files without interpreting organization data. */
+export async function listRoutineDeadLetters({ directory }) {
+    if (!fs.existsSync(directory))
+        return [];
+    const items = [];
+    for (const name of fs.readdirSync(directory).filter((entry) => entry.endsWith('.json')).sort()) {
+        const filePath = path.resolve(directory, name);
+        const receipt = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        const workflowId = receipt.source?.workflow_id;
+        const automationId = workflowId && workflowId !== '__connector_observation__'
+            ? workflowId
+            : receipt.source?.name;
+        if (typeof automationId !== 'string' || automationId.trim() === '')
+            continue;
+        items.push({
+            automation_id: automationId,
+            created_at: fs.statSync(filePath).mtime.toISOString(),
+            path: name
+        });
+    }
+    return items.sort((left, right) => right.created_at.localeCompare(left.created_at)
+        || left.automation_id.localeCompare(right.automation_id));
+}
+export async function countRoutineOutbox({ directory }) {
+    if (!fs.existsSync(directory))
+        return 0;
+    return fs.readdirSync(directory).filter((entry) => entry.endsWith('.json')).length;
+}
+function assertRoutineRequest(request) {
+    if (!request || typeof request !== 'object') {
+        throw new Error('routine request is required');
+    }
+    for (const [name, value] of [
+        ['routine', request.routine],
+        ['automationId', request.automationId]
+    ]) {
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new Error(`routine request ${name} must be a non-empty string`);
+        }
+    }
+}
+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');
+    }
+}
+export class RoutineRuntimeService {
+    ports;
+    constructor(ports) {
+        assertRoutinePorts(ports);
+        this.ports = ports;
+    }
+    async start(request) {
+        return this.execute('routine.start', request, (context) => this.ports.runner.start({ request, context }));
+    }
+    async retry(request, previousRunId) {
+        assertRoutineRequest(request);
+        if (typeof previousRunId !== 'string' || previousRunId.trim() === '') {
+            throw new Error('previousRunId must be a non-empty string');
+        }
+        if (typeof this.ports.runner.retry !== 'function') {
+            throw new Error('routine runner retry port is required');
+        }
+        return this.execute('routine.retry', request, (context) => this.ports.runner.retry({ request, context, previousRunId }));
+    }
+    async history(request) {
+        assertRoutineRequest(request);
+        const input = {
+            operation: 'routine.history',
+            routine: request.routine,
+            automationId: request.automationId,
+            request
+        };
+        const context = await resolveRuntimeHostContext(this.ports, input);
+        return this.ports.receipt.query({ request, context });
+    }
+    async execute(operation, request, run) {
+        assertRoutineRequest(request);
+        const input = {
+            operation,
+            routine: request.routine,
+            automationId: request.automationId,
+            request
+        };
+        const context = await resolveRuntimeHostContext(this.ports, input);
+        const runnerResult = await run(context);
+        if (!runnerResult || typeof runnerResult !== 'object' || !('receipt' in runnerResult)) {
+            throw new Error(`routine runner ${operation} must return a receipt`);
+        }
+        const result = runnerResult;
+        const normalizedReceipt = normalizeRunReceipt(result.receipt);
+        const persistedReceipt = await this.ports.receipt.persist({
+            payload: result.receipt,
+            normalized: normalizedReceipt,
+            context
+        });
+        return {
+            runnerResult: result.result,
+            normalizedReceipt,
+            persistedReceipt,
+            context
+        };
+    }
+}
+export function createRoutineRuntime(ports) {
+    return new RoutineRuntimeService(ports);
+}
+const WEEKDAY_TO_NUMBER = {
+    Sunday: 0,
+    Monday: 1,
+    Tuesday: 2,
+    Wednesday: 3,
+    Thursday: 4,
+    Friday: 5,
+    Saturday: 6
+};
+/** Return whether an expectation's scheduled minute matches the supplied instant. */
+export function routineScheduleMatches(expectation, instant) {
+    if (!(instant instanceof Date) || Number.isNaN(instant.getTime())) {
+        throw new Error('instant must be a valid Date');
+    }
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: expectation.timezone,
+        hour12: false,
+        weekday: 'long',
+        hour: '2-digit',
+        minute: '2-digit'
+    }).formatToParts(instant);
+    const values = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+    const hour = Number(values.hour);
+    const minute = Number(values.minute);
+    if (hour !== expectation.schedule.hour || minute !== expectation.schedule.minute)
+        return false;
+    if (expectation.schedule.kind === 'daily')
+        return true;
+    return WEEKDAY_TO_NUMBER[values.weekday] === expectation.schedule.day_of_week;
+}

package/dist/routines.d.ts

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

package/dist/routines.js

@@ -1,3 +1,6 @@
+export * from './routine-runtime.js';
+export * from './routine-cycle.js';
+export * from './routine-liveness.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.d.ts

@@ -0,0 +1,40 @@
+export type RunReceiptSourceType = 'mana' | 'codex_automations' | 'github_actions' | 'salestailor' | 'openryoko' | 'openclaw';
+export type RunReceiptStatus = 'success' | 'failed' | 'blocked' | 'waiting_human' | 'cancelled';
+export type RunReceiptEvidenceState = 'confirmed' | 'unconfirmed' | 'no_data';
+export type RunReceiptObservationKind = 'source_run' | 'connector_observation';
+export type RunReceiptAction = 'none' | 'check_error' | 'resolve_blocker' | 'review_run' | 'retry_run' | 'reauthorize' | 'contact_owner';
+export type RunReceiptEvidenceKind = 'url' | 'artifact_ref' | 'log_ref';
+export interface RunReceiptIdentity {
+    digest: string;
+    idempotency_key: string;
+    run_id: string;
+    workflow_id: string;
+}
+export interface RunReceiptProjection {
+    status: string;
+    closure_state: string;
+    action_required: string;
+    human_waiting: boolean;
+}
+export interface NormalizedRunReceipt {
+    contract_version: 'run_receipt.v1';
+    source: Record<string, unknown>;
+    run: Record<string, unknown>;
+    delivery: Record<string, unknown>;
+    immutable: Record<string, unknown>;
+    identity: RunReceiptIdentity;
+    payload_digest: string;
+    projection: RunReceiptProjection;
+}
+export declare class RunReceiptContractError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function createRunReceiptIdentity({ projectId, sourceType, externalRunId, sourceWorkflowId }: {
+    projectId: string;
+    sourceType: RunReceiptSourceType;
+    externalRunId: string;
+    sourceWorkflowId: string;
+}): RunReceiptIdentity;
+export declare function normalizeRunReceipt(payload: unknown): NormalizedRunReceipt;