@unson/brainbase-mcp 0.44.0 → 0.44.1

package/dist/judgment-runtime-resolution.public.d.ts

@@ -0,0 +1,255 @@
+export { JudgmentResolutionError, canonicalJson, computeRequestDigest, sha256Hex } from './judgment-resolution-contract.js';
+
+export type JudgmentRuntimeIntent =
+    | 'answer'
+    | 'investigate'
+    | 'diagnose'
+    | 'design'
+    | 'implement'
+    | 'review'
+    | 'operate';
+export type JudgmentRuntimeDomain =
+    | 'general'
+    | 'knowledge'
+    | 'personal_judgment'
+    | 'engineering'
+    | 'organization'
+    | 'operations';
+export type JudgmentRuntimeSignal =
+    | 'cumulative_effect'
+    | 'complexity_growth'
+    | 'threshold_proposal'
+    | 'parallel_exploration'
+    | 'authority_boundary'
+    | 'problem_frame_uncertain'
+    | 'external_outcome';
+export type JudgmentRuntimeActionKind = 'none' | 'read' | 'write' | 'external';
+export type JudgmentRuntimeRisk = 'low' | 'medium' | 'high' | 'critical';
+export type JudgmentRuntimeConfidence = 'confirmed' | 'inferred' | 'unknown';
+export type JudgmentRuntimeStatus = 'resolved' | 'needs_classification' | 'needs_policy_resolution';
+export type JudgmentRuntimeAutonomyDecision = 'continue' | 'escalate';
+
+export interface JudgmentRuntimeClassification {
+    intent: JudgmentRuntimeIntent;
+    domains: JudgmentRuntimeDomain[];
+    action_kind: JudgmentRuntimeActionKind;
+    risk: JudgmentRuntimeRisk;
+    confidence: JudgmentRuntimeConfidence;
+    signals: JudgmentRuntimeSignal[];
+}
+
+export interface JudgmentRuntimeMessage {
+    sequence: number;
+    turn_id: string | null;
+    role: 'user' | 'assistant';
+    phase: string | null;
+    text: string;
+}
+
+export interface JudgmentRuntimePriorReceipt {
+    turn_id: string;
+    resolution_id: string;
+    request_digest: string;
+    context_digest: string | null;
+    plan_digest: string;
+    classification: JudgmentRuntimeClassification;
+    selected_dag_ids: string[];
+}
+
+export interface JudgmentRuntimeRuntimeContext {
+    host: 'codex' | 'claude-code';
+    entrypoint?: 'codex' | 'claude_code' | 'mana' | 'company_os' | 'unknown';
+    model: string | null;
+    permission_mode: string | null;
+    project_binding: string | null;
+}
+
+export interface JudgmentRuntimeConversationContext {
+    schema_version: 'brainbase-conversation-context-v1';
+    session_ref: string;
+    messages: JudgmentRuntimeMessage[];
+    prior_receipts: JudgmentRuntimePriorReceipt[];
+    runtime: JudgmentRuntimeRuntimeContext;
+    instruction_bindings: Array<{ scope: string; source_ref: string; digest: string }>;
+    completeness: 'complete' | 'partial';
+    source_digest: string;
+}
+
+export interface JudgmentRuntimeInput {
+    request: string;
+    turn_id: string;
+    project_code: string | null;
+    conversation_context: JudgmentRuntimeConversationContext;
+    model_interpretation: JudgmentRuntimeClassification | null;
+}
+
+export interface JudgmentRuntimeManifestLock {
+    schema_version: 'brainbase-judgment-manifest-lock-v1';
+    entries: Array<{ runtime_version: string; manifest_digest: string }>;
+}
+
+export interface JudgmentRuntimePolicy {
+    id: string;
+    version: string;
+    priority: number;
+    strength: 'hard' | 'soft';
+    scope: { type: 'global' | 'organization' | 'project' | 'owner'; id: string | null };
+    visibility: 'organization' | 'owner';
+    owner_person_id: string | null;
+    evidence_requirement: string;
+    effect: { target: string; decision: 'require' | 'forbid' | 'prefer' };
+    instruction: string;
+    human_approval?: {
+        action_kinds?: JudgmentRuntimeActionKind[];
+        risks?: JudgmentRuntimeRisk[];
+    };
+    [key: string]: unknown;
+}
+
+export interface JudgmentRuntimeManifest {
+    schema_version: 'brainbase-judgment-runtime-v1';
+    runtime_version: string;
+    host_bindings: Array<{ adapter_id: string; adapter_version: string; status?: string; [key: string]: unknown }>;
+    policies: JudgmentRuntimePolicy[];
+    nodes: Array<{
+        id: string;
+        kind: 'common' | 'judgment' | 'capability' | 'constraint' | 'fail_closed';
+        instruction: string;
+        required_capability_template: string | null;
+        execution_contract?: string;
+        [key: string]: unknown;
+    }>;
+    dags: Array<{
+        id: string;
+        kind: 'domain' | 'constraint' | 'fail_closed';
+        path: string[];
+        policy_ids: string[];
+        [key: string]: unknown;
+    }>;
+    composition_edges: Array<[string, string]>;
+    selectors: {
+        domain_order: JudgmentRuntimeDomain[];
+        signal_order: JudgmentRuntimeSignal[];
+        domain_dags: Record<JudgmentRuntimeDomain, string>;
+        signal_dags: Record<JudgmentRuntimeSignal, string>;
+        engineering_implementation_dag?: string;
+        authority_dag: string;
+        clarification_dag: string;
+        [key: string]: unknown;
+    };
+    semantic_matchers: {
+        intents: Record<JudgmentRuntimeIntent, string[]>;
+        domains: Record<Exclude<JudgmentRuntimeDomain, 'general'>, string[]>;
+        signals: Record<JudgmentRuntimeSignal, string[]>;
+        safety: Record<'write' | 'external' | 'critical', string[]>;
+        positive_commands: string[];
+        follow_up: string[];
+        [key: string]: unknown;
+    };
+    autonomy: {
+        schema_version: 'brainbase-autonomy-policy-v1';
+        continue_risks: JudgmentRuntimeRisk[];
+        escalate_risks: JudgmentRuntimeRisk[];
+        escalate_action_kinds: JudgmentRuntimeActionKind[];
+        runtime_escalation_reasons: string[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+export interface JudgmentRuntimeReconciliation {
+    status: 'resolved' | 'needs_classification';
+    classification: JudgmentRuntimeClassification | null;
+    assurance: 'verified' | 'bounded' | 'unknown';
+    reasons: string[];
+    evidence: Record<string, unknown>;
+}
+
+export interface JudgmentRuntimeResolutionPlan {
+    status: JudgmentRuntimeStatus;
+    autonomy_decision: JudgmentRuntimeAutonomyDecision;
+    autonomy_reason_code: 'routine_in_scope' | 'classification_missing' | 'policy_conflict' | 'risk_or_external';
+    allowed_runtime_escalation_reasons: string[];
+    autonomy_policy_ids: string[];
+    reconciliation: JudgmentRuntimeReconciliation;
+    selected_dag_ids: string[];
+    applicable_policies: JudgmentRuntimePolicy[];
+    suppressed_policies: Array<{ policy_id: string; suppressed_by_policy_id: string; reason: string }>;
+    policy_conflict: boolean;
+    required_capabilities: Array<{
+        capability: string;
+        status: string;
+        input: Record<string, unknown>;
+        receipt_required: boolean;
+        [key: string]: unknown;
+    }>;
+    active_nodes: string[];
+    active_edges: Array<[string, string]>;
+    active_node_definitions: JudgmentRuntimeManifest['nodes'];
+    unresolved: string[];
+    rationale: string[];
+}
+
+export interface JudgmentRuntimeCoreInput {
+    input: JudgmentRuntimeInput;
+    manifest: JudgmentRuntimeManifest;
+    /** Policies already filtered by the Organization/Host authorization adapter. */
+    applicablePolicies?: JudgmentRuntimePolicy[];
+    ownerPersonId?: string | null;
+    clientCapabilities?: string[];
+}
+
+export declare function validateManifestLock(
+    lock: JudgmentRuntimeManifestLock,
+    previous?: JudgmentRuntimeManifestLock | null,
+    current?: { runtimeVersion: string; manifestDigest: string } | null,
+): true;
+export declare function validateManifest(manifest: JudgmentRuntimeManifest, lock: JudgmentRuntimeManifestLock): string;
+export declare function validateRuntimeInput(rawInput: unknown, manifest: JudgmentRuntimeManifest): JudgmentRuntimeInput;
+export declare function autonomyResolution(
+    status: JudgmentRuntimeStatus,
+    classification: JudgmentRuntimeClassification | null,
+    manifest: JudgmentRuntimeManifest,
+    applicablePolicies?: JudgmentRuntimePolicy[],
+): {
+    autonomy_decision: JudgmentRuntimeAutonomyDecision;
+    autonomy_reason_code: JudgmentRuntimeResolutionPlan['autonomy_reason_code'];
+    allowed_runtime_escalation_reasons: string[];
+    autonomy_policy_ids: string[];
+};
+export declare function reconcileModelInterpretation(
+    input: JudgmentRuntimeInput,
+    manifest: JudgmentRuntimeManifest,
+): JudgmentRuntimeReconciliation;
+export declare function classify(input: JudgmentRuntimeInput, manifest: JudgmentRuntimeManifest): JudgmentRuntimeReconciliation;
+export declare function materializePolicy(policy: JudgmentRuntimePolicy, ownerPersonId: string | null): JudgmentRuntimePolicy;
+export declare function mergePolicies(policies: JudgmentRuntimePolicy[]): {
+    applicable: JudgmentRuntimePolicy[];
+    suppressed: Array<{ policy_id: string; suppressed_by_policy_id: string; reason: string }>;
+    conflict: boolean;
+};
+export declare function selectedDags(classification: JudgmentRuntimeClassification, manifest: JudgmentRuntimeManifest): string[];
+export declare function buildGraph(
+    dagIds: string[],
+    manifest: JudgmentRuntimeManifest,
+    options?: { clarification?: boolean },
+): { active_nodes: string[]; active_edges: Array<[string, string]> };
+export declare function materializeActiveNodeDefinitions(
+    activeNodes: string[],
+    manifest: JudgmentRuntimeManifest,
+    options?: { evidenceRequired?: boolean },
+): JudgmentRuntimeManifest['nodes'];
+export declare function topologicallySortNodes(nodes: string[], edges: Array<[string, string]>): string[];
+export declare const JUDGMENT_FRAME_CAPABILITY: 'judgment.frame';
+export declare function isJudgmentBearing(classification: JudgmentRuntimeClassification | null): boolean;
+export declare function frameCapabilities(
+    input: JudgmentRuntimeInput,
+    classification: JudgmentRuntimeClassification | null,
+    clientCapabilities: ReadonlySet<string>,
+    status: JudgmentRuntimeStatus,
+): JudgmentRuntimeResolutionPlan['required_capabilities'];
+export declare function knowledgeCapabilities(
+    input: JudgmentRuntimeInput,
+    classification: JudgmentRuntimeClassification | null,
+): JudgmentRuntimeResolutionPlan['required_capabilities'];
+export declare function resolveJudgmentRuntimeCore(args: JudgmentRuntimeCoreInput): JudgmentRuntimeResolutionPlan;

package/dist/knowledge-event.d.ts

@@ -0,0 +1,28 @@
+/** Stable common boundary for host-provided knowledge-event adapters. */
+export declare const KNOWLEDGE_EVENT_CONTRACT_VERSION: "knowledge_event.v1";
+export declare const KNOWLEDGE_EVENT_REQUIRED_FIELDS: readonly ["schema_version", "event_id", "occurred_at", "captured_at", "source", "subject", "decision_authority", "applicability_scope", "permission_snapshot", "source_pointer", "body_hash", "parent_episode_id"];
+export type KnowledgeEventRequiredField = typeof KNOWLEDGE_EVENT_REQUIRED_FIELDS[number];
+export type KnowledgeEventRecord = Record<string, unknown>;
+export declare class KnowledgeEventContractError extends Error {
+    readonly field: string;
+    readonly code = "knowledge_event_invalid";
+    constructor(field: string, message?: string);
+}
+/**
+ * Canonical JSON used for idempotency and conflict checks. Host repositories
+ * may store additional fields, but the common identity never depends on
+ * property insertion order.
+ */
+export declare function canonicalKnowledgeEventJson(value: unknown): string;
+export declare function knowledgeEventSha256(value: string): string;
+/**
+ * Validate only the portable event envelope. Subject semantics, decision
+ * authority, tenant identity, and persistence remain host responsibilities.
+ */
+export declare function normalizeKnowledgeEvent(value: unknown): KnowledgeEventRecord;
+declare const IDENTITY_FIELDS: readonly ["body_hash", "source_pointer", "subject", "decision_authority", "applicability_scope", "permission_snapshot", "parent_episode_id", "organization_id", "sensitivity", "role_min", "venue"];
+export type KnowledgeEventIdentity = Pick<KnowledgeEventRecord, typeof IDENTITY_FIELDS[number]>;
+export declare function knowledgeEventIdentity(value: unknown): KnowledgeEventIdentity;
+export declare function knowledgeEventFingerprint(value: unknown): string;
+export declare function sameKnowledgeEventIdentity(left: unknown, right: unknown): boolean;
+export {};

package/dist/knowledge-event.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+/** Stable common boundary for host-provided knowledge-event adapters. */
+export const KNOWLEDGE_EVENT_CONTRACT_VERSION = 'knowledge_event.v1';
+export const KNOWLEDGE_EVENT_REQUIRED_FIELDS = [
+    'schema_version',
+    'event_id',
+    'occurred_at',
+    'captured_at',
+    'source',
+    'subject',
+    'decision_authority',
+    'applicability_scope',
+    'permission_snapshot',
+    'source_pointer',
+    'body_hash',
+    'parent_episode_id'
+];
+export class KnowledgeEventContractError extends Error {
+    field;
+    code = 'knowledge_event_invalid';
+    constructor(field, message = `knowledge_event.v1 field is required: ${field}`) {
+        super(message);
+        this.field = field;
+        this.name = 'KnowledgeEventContractError';
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function clone(value) {
+    if (Array.isArray(value))
+        return value.map(clone);
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, clone(child)]));
+    }
+    return value;
+}
+function hasValue(value) {
+    return value !== undefined && value !== null && value !== '';
+}
+/**
+ * Canonical JSON used for idempotency and conflict checks. Host repositories
+ * may store additional fields, but the common identity never depends on
+ * property insertion order.
+ */
+export function canonicalKnowledgeEventJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalKnowledgeEventJson).join(',')}]`;
+    if (isRecord(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalKnowledgeEventJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function knowledgeEventSha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+/**
+ * Validate only the portable event envelope. Subject semantics, decision
+ * authority, tenant identity, and persistence remain host responsibilities.
+ */
+export function normalizeKnowledgeEvent(value) {
+    if (!isRecord(value))
+        throw new KnowledgeEventContractError('event', 'knowledge event must be an object');
+    for (const field of KNOWLEDGE_EVENT_REQUIRED_FIELDS) {
+        if (!hasValue(value[field]))
+            throw new KnowledgeEventContractError(field);
+    }
+    if (value.schema_version !== KNOWLEDGE_EVENT_CONTRACT_VERSION) {
+        throw new KnowledgeEventContractError('schema_version', `schema_version must be ${KNOWLEDGE_EVENT_CONTRACT_VERSION}`);
+    }
+    if (typeof value.event_id !== 'string' || !value.event_id.trim()) {
+        throw new KnowledgeEventContractError('event_id', 'event_id must be a non-empty string');
+    }
+    for (const field of ['occurred_at', 'captured_at']) {
+        if (typeof value[field] !== 'string' || !Number.isFinite(Date.parse(value[field]))) {
+            throw new KnowledgeEventContractError(field, `${field} must be an ISO timestamp`);
+        }
+    }
+    if (typeof value.body_hash !== 'string' || !/^(?:sha256:)?[a-f0-9]{64}$/u.test(value.body_hash)) {
+        throw new KnowledgeEventContractError('body_hash', 'body_hash must be a SHA-256 digest');
+    }
+    return clone(value);
+}
+const IDENTITY_FIELDS = [
+    'body_hash',
+    'source_pointer',
+    'subject',
+    'decision_authority',
+    'applicability_scope',
+    'permission_snapshot',
+    'parent_episode_id',
+    'organization_id',
+    'sensitivity',
+    'role_min',
+    'venue'
+];
+export function knowledgeEventIdentity(value) {
+    const event = normalizeKnowledgeEvent(value);
+    return Object.fromEntries(IDENTITY_FIELDS
+        .filter((field) => event[field] !== undefined)
+        .map((field) => [field, event[field]]));
+}
+export function knowledgeEventFingerprint(value) {
+    return knowledgeEventSha256(canonicalKnowledgeEventJson(knowledgeEventIdentity(value)));
+}
+export function sameKnowledgeEventIdentity(left, right) {
+    try {
+        return canonicalKnowledgeEventJson(knowledgeEventIdentity(left))
+            === canonicalKnowledgeEventJson(knowledgeEventIdentity(right));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mcp-runtime.d.ts

@@ -0,0 +1,75 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type CallToolResult, type ServerNotification, type ServerRequest, type Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const MCP_RUNTIME_CONTRACT_VERSION: "mcp_runtime.v1";
+export interface LocalMcpRuntimeDescriptor {
+    packageName: string;
+    command: string;
+    transport: 'stdio';
+    storage: 'local';
+    hostedDependency: false;
+}
+export interface McpToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface McpToolReceipt {
+    tool: string;
+    status: 'accepted' | 'completed' | 'failed' | 'unknown';
+    receiptKind: 'tool_result' | 'send_ack' | 'error';
+    verified: boolean;
+}
+export type LocalMcpToolHandler = (arguments_: Record<string, unknown>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
+/**
+ * Optional host-owned fallback for calls that are intentionally absent from
+ * the advertised tools/list surface. The runtime only performs the SDK
+ * dispatch; the host decides whether the call is a retired tool, an unknown
+ * name, or an authenticated request that must be rejected.
+ */
+export type LocalMcpUnknownToolHandler = (name: string, arguments_: Record<string, unknown>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
+export interface LocalMcpRuntimeTool {
+    definition: Tool;
+    handler: LocalMcpToolHandler;
+}
+export interface LocalMcpRuntimeOptions {
+    name: string;
+    version: string;
+    instructions?: string;
+    tools: readonly LocalMcpRuntimeTool[];
+    /** The host may observe the exact SDK tools/list surface for its audit trail. */
+    onListTools?: (tools: readonly Tool[]) => void | Promise<void>;
+    /** The host may preserve behavior for calls outside the advertised surface. */
+    onUnknownTool?: LocalMcpUnknownToolHandler;
+    /** The host may inject HTTP, stdio, or an in-memory SDK transport. */
+    transport?: Transport;
+}
+export interface LocalMcpRuntimeHandle {
+    readonly server: Server;
+    readonly transport: Transport;
+    close(): Promise<void>;
+}
+export declare class McpRuntimeContractError extends Error {
+    readonly code = "mcp_runtime_contract_invalid";
+    constructor(field: string, message?: string);
+}
+/**
+ * Create an SDK MCP server with a host-independent tool registry.
+ *
+ * The returned Server is intentionally transport agnostic. A host can connect
+ * it to stdio, Streamable HTTP, or an in-memory transport without the OSS
+ * package importing auth, tenant, deployment, or provider code.
+ */
+export declare function createLocalMcpServer(options: LocalMcpRuntimeOptions): Server;
+/**
+ * Start a local SDK runtime and return an explicit lifecycle handle.
+ *
+ * The default is stdio for local clients. Hosts that own HTTP/auth may inject
+ * their transport and retain the same engine and tool contract.
+ */
+export declare function runLocalMcpServer(options: LocalMcpRuntimeOptions): Promise<LocalMcpRuntimeHandle>;
+export declare const createMcpRuntimeServer: typeof createLocalMcpServer;
+export declare const startLocalMcpRuntime: typeof runLocalMcpServer;
+export declare function normalizeLocalMcpRuntimeDescriptor(value: unknown): LocalMcpRuntimeDescriptor;
+export declare function normalizeMcpToolCall(value: unknown): McpToolCall;
+export declare function createMcpToolReceipt(input: Pick<McpToolReceipt, 'tool' | 'status' | 'receiptKind' | 'verified'>): McpToolReceipt;

package/dist/mcp-runtime.js

@@ -0,0 +1,188 @@
+/**
+ * Local MCP process and tool-call contracts.
+ *
+ * The runtime in this module deliberately owns only the SDK server and its
+ * tool dispatch. HTTP, bearer tokens, tenant selection, graph/index access,
+ * and provider I/O stay in the host and are supplied through tool callbacks
+ * or an injected SDK transport.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+export const MCP_RUNTIME_CONTRACT_VERSION = 'mcp_runtime.v1';
+export class McpRuntimeContractError extends Error {
+    code = 'mcp_runtime_contract_invalid';
+    constructor(field, message = `MCP runtime field is invalid: ${field}`) {
+        super(message);
+        this.name = 'McpRuntimeContractError';
+    }
+}
+function cloneToolDefinition(definition) {
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+        throw new McpRuntimeContractError('tool.definition');
+    }
+    if (typeof definition.name !== 'string' || !definition.name.trim()) {
+        throw new McpRuntimeContractError('tool.definition.name');
+    }
+    if (!definition.inputSchema || definition.inputSchema.type !== 'object') {
+        throw new McpRuntimeContractError('tool.definition.inputSchema');
+    }
+    try {
+        return structuredClone(definition);
+    }
+    catch {
+        throw new McpRuntimeContractError('tool.definition', 'tool definition must be structured-cloneable');
+    }
+}
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(isError ? { isError: true } : {})
+    };
+}
+function normalizeRuntimeOptions(options) {
+    const name = text(options.name, 'name');
+    const version = text(options.version, 'version');
+    if (!Array.isArray(options.tools))
+        throw new McpRuntimeContractError('tools');
+    const tools = [];
+    const names = new Set();
+    for (const tool of options.tools) {
+        if (!tool || typeof tool !== 'object' || typeof tool.handler !== 'function') {
+            throw new McpRuntimeContractError('tool.handler');
+        }
+        const definition = cloneToolDefinition(tool.definition);
+        if (names.has(definition.name)) {
+            throw new McpRuntimeContractError('tools', `duplicate MCP tool name: ${definition.name}`);
+        }
+        names.add(definition.name);
+        tools.push({ definition, handler: tool.handler });
+    }
+    return {
+        name,
+        version,
+        ...(options.instructions === undefined ? {} : { instructions: text(options.instructions, 'instructions') }),
+        tools,
+        ...(options.onListTools === undefined ? {} : { onListTools: options.onListTools }),
+        ...(options.onUnknownTool === undefined ? {} : { onUnknownTool: options.onUnknownTool }),
+        transport: options.transport
+    };
+}
+/**
+ * Create an SDK MCP server with a host-independent tool registry.
+ *
+ * The returned Server is intentionally transport agnostic. A host can connect
+ * it to stdio, Streamable HTTP, or an in-memory transport without the OSS
+ * package importing auth, tenant, deployment, or provider code.
+ */
+export function createLocalMcpServer(options) {
+    const normalized = normalizeRuntimeOptions(options);
+    const toolsByName = new Map(normalized.tools.map((tool) => [tool.definition.name, tool]));
+    const server = new Server({ name: normalized.name, version: normalized.version }, {
+        capabilities: { tools: {} },
+        ...(normalized.instructions ? { instructions: normalized.instructions } : {})
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = normalized.tools.map((tool) => structuredClone(tool.definition));
+        await normalized.onListTools?.(tools);
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const registered = toolsByName.get(request.params.name);
+        const arguments_ = request.params.arguments ?? {};
+        if (!registered) {
+            if (normalized.onUnknownTool) {
+                try {
+                    return await normalized.onUnknownTool(request.params.name, structuredClone(arguments_), extra);
+                }
+                catch {
+                    return textResult(`Tool execution failed: ${request.params.name}`, true);
+                }
+            }
+            return textResult(`Unknown tool: ${request.params.name}`, true);
+        }
+        try {
+            return await registered.handler(structuredClone(arguments_), extra);
+        }
+        catch {
+            return textResult(`Tool execution failed: ${request.params.name}`, true);
+        }
+    });
+    return server;
+}
+/**
+ * Start a local SDK runtime and return an explicit lifecycle handle.
+ *
+ * The default is stdio for local clients. Hosts that own HTTP/auth may inject
+ * their transport and retain the same engine and tool contract.
+ */
+export async function runLocalMcpServer(options) {
+    const normalized = normalizeRuntimeOptions(options);
+    const server = createLocalMcpServer(normalized);
+    const transport = normalized.transport ?? new StdioServerTransport();
+    try {
+        await server.connect(transport);
+    }
+    catch (error) {
+        await transport.close().catch(() => undefined);
+        throw error;
+    }
+    let closed = false;
+    return {
+        server,
+        transport,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await server.close();
+        }
+    };
+}
+export const createMcpRuntimeServer = createLocalMcpServer;
+export const startLocalMcpRuntime = runLocalMcpServer;
+function text(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new McpRuntimeContractError(field);
+    return value.trim();
+}
+export function normalizeLocalMcpRuntimeDescriptor(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new McpRuntimeContractError('descriptor');
+    const candidate = value;
+    if (candidate.transport !== 'stdio')
+        throw new McpRuntimeContractError('transport', 'local MCP transport must be stdio');
+    if (candidate.storage !== 'local')
+        throw new McpRuntimeContractError('storage', 'local MCP storage must be local');
+    if (candidate.hostedDependency !== false)
+        throw new McpRuntimeContractError('hostedDependency', 'local MCP must not require a hosted dependency');
+    return {
+        packageName: text(candidate.packageName, 'packageName'),
+        command: text(candidate.command, 'command'),
+        transport: 'stdio',
+        storage: 'local',
+        hostedDependency: false
+    };
+}
+export function normalizeMcpToolCall(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new McpRuntimeContractError('call');
+    const candidate = value;
+    if (!candidate.arguments || typeof candidate.arguments !== 'object' || Array.isArray(candidate.arguments)) {
+        throw new McpRuntimeContractError('arguments');
+    }
+    return {
+        name: text(candidate.name, 'name'),
+        arguments: structuredClone(candidate.arguments)
+    };
+}
+export function createMcpToolReceipt(input) {
+    const tool = text(input.tool, 'tool');
+    if (!['accepted', 'completed', 'failed', 'unknown'].includes(input.status))
+        throw new McpRuntimeContractError('status');
+    if (!['tool_result', 'send_ack', 'error'].includes(input.receiptKind))
+        throw new McpRuntimeContractError('receiptKind');
+    if (typeof input.verified !== 'boolean')
+        throw new McpRuntimeContractError('verified');
+    return { tool, status: input.status, receiptKind: input.receiptKind, verified: input.verified };
+}