@veil-runtime/core 0.1.1 → 0.1.3

package/README.md

@@ -353,67 +353,101 @@ Optional:
 
 ---
 
-## Installation
-
-Install the public runtime package in an application:
-
-```bash
-npm install @veil-runtime/core
-```
-
-Create and execute a capability through the public API:
-
-```ts
-import {
-  createCapability,
-  OperatorRuntime,
-  type CapabilityModule,
-  type ExecutionPlan,
-} from '@veil-runtime/core';
-
-const echo = createCapability<{ value: string }, string>({
-  name: 'example.echo',
-  version: '1.0.0',
-  description: 'Return the provided value',
-  risk: 'read',
-  async execute({ input }) {
-    return input.value;
-  },
-});
-
-const module: CapabilityModule = {
-  manifest: {
-    name: 'example',
-    version: '1.0.0',
-    capabilities: [echo.name],
-  },
-  capabilities: [echo],
-};
-
-const plan: ExecutionPlan = {
-  version: '1.0',
-  steps: [{
-    id: 'echo',
-    capability: echo.name,
-    capabilityVersion: echo.version,
-    input: { value: 'Hello from Veil' },
-  }],
-};
-
-const runtime = new OperatorRuntime();
-runtime.use(module);
-
-const job = await runtime.executePlan(plan);
-console.log(job.status, job.result);
-```
-
-This public-package usage is compile- and execution-verified by the release
-consumer fixture. Internal `src`, `dist`, registry, provider, and storage
-subpaths are intentionally unavailable.
-
-## Repository development
-
-Clone the repository:
+## Installation
+
+Install the public runtime package in an application:
+
+```bash
+npm install @veil-runtime/core
+```
+
+Create and execute a capability through the public API:
+
+```ts
+import {
+  createCapability,
+  OperatorRuntime,
+  type CapabilityModule,
+  type ExecutionPlan,
+} from '@veil-runtime/core';
+
+const echo = createCapability<{ value: string }, string>({
+  name: 'example.echo',
+  version: '1.0.0',
+  description: 'Return the provided value',
+  risk: 'read',
+  async execute({ input }) {
+    return input.value;
+  },
+});
+
+const module: CapabilityModule = {
+  manifest: {
+    name: 'example',
+    version: '1.0.0',
+    capabilities: [echo.name],
+  },
+  capabilities: [echo],
+};
+
+const plan: ExecutionPlan = {
+  version: '1.0',
+  steps: [{
+    id: 'echo',
+    capability: echo.name,
+    capabilityVersion: echo.version,
+    input: { value: 'Hello from Veil' },
+  }],
+};
+
+const runtime = new OperatorRuntime();
+runtime.use(module);
+
+const job = await runtime.executePlan(plan);
+console.log(job.status, job.result);
+```
+
+This public-package usage is compile- and execution-verified by the release
+consumer fixture. Internal `src`, `dist`, registry, provider, and storage
+subpaths are intentionally unavailable.
+
+### Contextual execution authorization
+
+An application may supply a runtime-scoped authorizer. Veil resolves and
+validates the step input before invoking it, and does not start a denied
+capability:
+
+```ts
+import {
+  OperatorRuntime,
+  type ExecutionAuthorizer,
+} from '@veil-runtime/core';
+
+const authorizer: ExecutionAuthorizer = {
+  async authorize({ capability, input }) {
+    if (
+      capability.name === 'deploy.trigger' &&
+      typeof input === 'object' &&
+      input !== null &&
+      'environment' in input &&
+      input.environment === 'production'
+    ) {
+      return {
+        decision: 'deny',
+        reason: 'Production deployment is not allowed.',
+      };
+    }
+
+    return { decision: 'allow' };
+  },
+};
+
+const runtime = new OperatorRuntime({ authorizer });
+```
+
+## Repository development
+
+Clone the repository:
 
 ```bash
 git clone git@github.com:veil-runtime/veil.git
@@ -478,11 +512,11 @@ Veil will:
 3. Generate an `ExecutionPlan`.
 4. Execute the plan through `OperatorRuntime`.
 5. Return the completed job.
-
----
-
-# License and branding
-
-Veil Core is licensed under Apache-2.0. Copyright 2026 Mustapha Keraan.
-Veil names, logos, and branding are governed separately; see
-[TRADEMARKS.md](TRADEMARKS.md) for the brand policy.
+
+---
+
+# License and branding
+
+Veil Core is licensed under Apache-2.0. Copyright 2026 Mustapha Keraan.
+Veil names, logos, and branding are governed separately; see
+[TRADEMARKS.md](TRADEMARKS.md) for the brand policy.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { OperatorRuntime, operatorRuntime } from './runtime/operator-runtime.js';
 export type { ExecutePlanOptions, RunJobOptions } from './runtime/operator-runtime.js';
+export type { OperatorRuntimeOptions } from './runtime/operator-runtime.js';
+export type { CapabilityAuthorizationContext, CapabilityAuthorizationDecision, ExecutionAuthorizer, } from './runtime/permissions/execution-authorizer.js';
 export type { ExecutionPlan, ExecutionStep, Planner, PlannerContext, ResultReference, } from './runtime/planner/planner.js';
 export type { ExecutionCaller, ExecutionContext } from './runtime/execution/execution-context.js';
 export type { Capability, CapabilityInputField, CapabilityRisk, } from './runtime/registry/capability.js';
@@ -10,4 +12,5 @@ export type { JobStep, JobStepStatus } from './runtime/jobs/job-step.js';
 export type { JobStatus } from './runtime/jobs/job-status.js';
 export type { JobEvent } from './runtime/jobs/job-event.js';
 export type { RuntimeEvent } from './runtime/events/runtime-event.js';
+export { McpAdapter } from './integrations/mcp/inbound/mcp-adapter.js';
 export * from './sdk/index.js';

package/dist/index.js

@@ -14,8 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.operatorRuntime = exports.OperatorRuntime = void 0;
+exports.McpAdapter = exports.operatorRuntime = exports.OperatorRuntime = void 0;
 var operator_runtime_js_1 = require("./runtime/operator-runtime.js");
 Object.defineProperty(exports, "OperatorRuntime", { enumerable: true, get: function () { return operator_runtime_js_1.OperatorRuntime; } });
 Object.defineProperty(exports, "operatorRuntime", { enumerable: true, get: function () { return operator_runtime_js_1.operatorRuntime; } });
+var mcp_adapter_js_1 = require("./integrations/mcp/inbound/mcp-adapter.js");
+Object.defineProperty(exports, "McpAdapter", { enumerable: true, get: function () { return mcp_adapter_js_1.McpAdapter; } });
 __exportStar(require("./sdk/index.js"), exports);

package/dist/integrations/mcp/inbound/capability-schema.d.ts

@@ -0,0 +1,3 @@
+import * as z from 'zod/v4';
+import { CapabilityInputField } from '../../../runtime/registry/capability.js';
+export declare function createMcpInputSchema(inputSchema: Record<string, CapabilityInputField>): Record<string, z.ZodType>;

package/dist/integrations/mcp/inbound/capability-schema.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpInputSchema = createMcpInputSchema;
+const z = __importStar(require("zod/v4"));
+function createFieldSchema(field) {
+    let schema;
+    switch (field.type) {
+        case 'string':
+            schema = z.string();
+            break;
+        case 'number':
+            schema = z.number();
+            break;
+        case 'boolean':
+            schema = z.boolean();
+            break;
+        case 'array':
+            schema = z.array(z.unknown());
+            break;
+        case 'object':
+            schema = z.record(z.string(), z.unknown());
+            break;
+        default:
+            schema = z.unknown();
+            break;
+    }
+    if (field.description) {
+        schema = schema.describe(field.description);
+    }
+    if (!field.required) {
+        schema = schema.optional();
+    }
+    return schema;
+}
+function createMcpInputSchema(inputSchema) {
+    return Object.fromEntries(Object.entries(inputSchema).map(([name, field]) => [
+        name,
+        createFieldSchema(field),
+    ]));
+}

package/dist/integrations/mcp/inbound/mcp-adapter.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { OperatorRuntime } from '../../../runtime/operator-runtime.js';
+export declare class McpAdapter {
+    private readonly runtime;
+    readonly server: McpServer;
+    constructor(runtime: OperatorRuntime);
+    private registerCapabilities;
+}

package/dist/integrations/mcp/inbound/mcp-adapter.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpAdapter = void 0;
+const node_crypto_1 = require("node:crypto");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const capability_schema_js_1 = require("./capability-schema.js");
+class McpAdapter {
+    runtime;
+    server;
+    constructor(runtime) {
+        this.runtime = runtime;
+        this.server =
+            new mcp_js_1.McpServer({
+                name: 'veil',
+                version: '0.1.0',
+            });
+        this.registerCapabilities();
+    }
+    registerCapabilities() {
+        const capabilities = this.runtime.listCapabilities();
+        for (const capability of capabilities) {
+            this.server.registerTool(capability.name, {
+                description: capability.description,
+                inputSchema: (0, capability_schema_js_1.createMcpInputSchema)(capability.inputSchema),
+            }, async (input) => {
+                try {
+                    const plan = {
+                        version: '1.0',
+                        goal: `Execute MCP tool ${capability.name}`,
+                        metadata: {
+                            source: 'mcp',
+                            tool: capability.name,
+                        },
+                        steps: [
+                            {
+                                id: (0, node_crypto_1.randomUUID)(),
+                                capability: capability.name,
+                                input,
+                                reason: 'Requested through MCP',
+                            },
+                        ],
+                    };
+                    const job = await this.runtime.executePlan(plan);
+                    const step = job.steps[0];
+                    if (!step) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Veil execution completed without a job step result',
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    if (step.status ===
+                        'failed') {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: step.error ??
+                                        'Veil capability execution failed',
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(step.result ??
+                                    null, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    const message = error instanceof Error
+                        ? error.message
+                        : 'Unknown Veil execution error';
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: message,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            });
+        }
+    }
+}
+exports.McpAdapter = McpAdapter;

package/dist/runtime/jobs/job-event.d.ts

@@ -1,4 +1,4 @@
-export type JobEventType = 'job.created' | 'planning.started' | 'planning.completed' | 'approval.requested' | 'approval.granted' | 'execution.started' | 'capability.started' | 'capability.completed' | 'capability.failed' | 'job.completed' | 'job.failed' | 'job.cancelled' | 'job.reviewed';
+export type JobEventType = 'job.created' | 'planning.started' | 'planning.completed' | 'approval.requested' | 'approval.granted' | 'execution.started' | 'capability.denied' | 'capability.started' | 'capability.completed' | 'capability.failed' | 'job.completed' | 'job.failed' | 'job.cancelled' | 'job.reviewed';
 export interface JobEvent {
     id: string;
     jobId: string;

package/dist/runtime/jobs/job-manager.d.ts

@@ -1,15 +1,16 @@
+import { ExecutionAuthorizer } from '../permissions/execution-authorizer.js';
 import { ExecutionPlan } from '../planner/planner.js';
 import { ExecutionCaller } from '../execution/execution-context.js';
 import { Job, JobOutcome } from './job.js';
 import { JobStatus } from './job-status.js';
 import { JobListFilter } from './job-store.js';
 declare class JobManager {
-    executePlan(plan: ExecutionPlan, caller?: ExecutionCaller): Promise<Job>;
+    executePlan(plan: ExecutionPlan, caller?: ExecutionCaller, authorizer?: ExecutionAuthorizer): Promise<Job>;
     create(goal: string, planner?: string): Promise<Job>;
     get(id: string): Promise<Job | undefined>;
     list(filter?: JobListFilter): Promise<Job[]>;
     setStatus(id: string, status: JobStatus): Promise<Job>;
-    execute(id: string, caller?: ExecutionCaller): Promise<Job>;
+    execute(id: string, caller?: ExecutionCaller, authorizer?: ExecutionAuthorizer): Promise<Job>;
     review(id: string, outcome: JobOutcome, notes?: string): Promise<Job>;
     private addEvent;
 }

package/dist/runtime/jobs/job-manager.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.jobManager = void 0;
 const node_crypto_1 = require("node:crypto");
 const registry_js_1 = require("../registry/registry.js");
-const permissions_js_1 = require("../permissions/permissions.js");
+const execution_authorizer_js_1 = require("../permissions/execution-authorizer.js");
 const plan_validator_js_1 = require("../execution/plan-validator.js");
 const result_reference_js_1 = require("../execution/result-reference.js");
 const memory_event_bus_js_1 = require("../events/memory-event-bus.js");
@@ -13,7 +13,7 @@ const console_log_sink_js_1 = require("../logging/console-log-sink.js");
 const composite_log_sink_js_1 = require("../logging/composite-log-sink.js");
 const sqlite_log_sink_js_1 = require("../logging/sqlite-log-sink.js");
 class JobManager {
-    async executePlan(plan, caller) {
+    async executePlan(plan, caller, authorizer = execution_authorizer_js_1.defaultExecutionAuthorizer) {
         if (!plan.steps.length) {
             throw new Error('Execution plan contains no steps');
         }
@@ -35,7 +35,7 @@ class JobManager {
         job.updatedAt =
             new Date().toISOString();
         await job_store_js_1.jobStore.update(job);
-        return this.execute(job.id, caller);
+        return this.execute(job.id, caller, authorizer);
     }
     async create(goal, planner) {
         if (!goal?.trim()) {
@@ -74,7 +74,7 @@ class JobManager {
         await job_store_js_1.jobStore.update(job);
         return job;
     }
-    async execute(id, caller) {
+    async execute(id, caller, authorizer = execution_authorizer_js_1.defaultExecutionAuthorizer) {
         const job = await job_store_js_1.jobStore.get(id);
         if (!job) {
             throw new Error(`Job not found: ${id}`);
@@ -92,17 +92,6 @@ class JobManager {
                 if (!capability) {
                     throw new Error(`Capability not found: ${step.capability}`);
                 }
-                const permission = (0, permissions_js_1.checkPermission)(capability.risk);
-                if (!permission.allowed) {
-                    throw new Error(permission.reason ??
-                        `Capability not permitted: ${step.capability}`);
-                }
-                step.status = 'running';
-                step.startedAt = new Date().toISOString();
-                this.addEvent(job, 'capability.started', {
-                    stepId: step.id,
-                    capability: step.capability,
-                });
                 try {
                     const completedSteps = job.steps.slice(0, job.steps.indexOf(step));
                     const resolvedInput = (0, result_reference_js_1.resolveResultReferences)(step.input, completedSteps);
@@ -112,6 +101,37 @@ class JobManager {
                             .map((validationError) => validationError.message)
                             .join('; '));
                     }
+                    const authorization = await authorizer.authorize({
+                        jobId: job.id,
+                        stepId: step.id,
+                        capability: {
+                            name: capability.name,
+                            version: capability.version,
+                            risk: capability.risk,
+                        },
+                        input: resolvedInput,
+                        caller,
+                    });
+                    if (authorization.decision === 'deny') {
+                        const message = authorization.reason ??
+                            `Capability not permitted: ${step.capability}`;
+                        step.status = 'failed';
+                        step.error = message;
+                        step.completedAt = new Date().toISOString();
+                        this.addEvent(job, 'capability.denied', {
+                            stepId: step.id,
+                            capability: capability.name,
+                            risk: capability.risk,
+                            reason: authorization.reason,
+                        });
+                        throw new AuthorizationDeniedError(message);
+                    }
+                    step.status = 'running';
+                    step.startedAt = new Date().toISOString();
+                    this.addEvent(job, 'capability.started', {
+                        stepId: step.id,
+                        capability: step.capability,
+                    });
                     const logger = new console_execution_logger_js_1.ConsoleExecutionLogger(job.id, step.id, new composite_log_sink_js_1.CompositeLogSink([
                         new console_log_sink_js_1.ConsoleLogSink(),
                         new sqlite_log_sink_js_1.SQLiteLogSink(),
@@ -131,6 +151,9 @@ class JobManager {
                     });
                 }
                 catch (error) {
+                    if (error instanceof AuthorizationDeniedError) {
+                        throw error;
+                    }
                     const message = error instanceof Error
                         ? error.message
                         : 'Unknown capability execution error';
@@ -211,4 +234,6 @@ class JobManager {
         return event;
     }
 }
+class AuthorizationDeniedError extends Error {
+}
 exports.jobManager = new JobManager();

package/dist/runtime/operator-runtime.d.ts

@@ -1,6 +1,7 @@
 import { Job } from './jobs/job.js';
 import { JobListFilter } from './jobs/job-store.js';
 import { ExecutionCaller } from './execution/execution-context.js';
+import { ExecutionAuthorizer } from './permissions/execution-authorizer.js';
 import { CapabilityModule } from './modules/capability-module.js';
 import { ExecutionPlan } from './planner/planner.js';
 export interface RunJobOptions {
@@ -11,7 +12,12 @@ export interface RunJobOptions {
 export interface ExecutePlanOptions {
     caller?: ExecutionCaller;
 }
+export interface OperatorRuntimeOptions {
+    readonly authorizer?: ExecutionAuthorizer;
+}
 export declare class OperatorRuntime {
+    private readonly authorizer;
+    constructor(options?: OperatorRuntimeOptions);
     use(module: CapabilityModule): void;
     executePlan(plan: ExecutionPlan, options?: ExecutePlanOptions): Promise<Job>;
     run(goal: string, options?: RunJobOptions): Promise<Job>;

package/dist/runtime/operator-runtime.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.operatorRuntime = exports.OperatorRuntime = void 0;
 const job_manager_js_1 = require("./jobs/job-manager.js");
 const job_memory_js_1 = require("./jobs/job-memory.js");
+const execution_authorizer_js_1 = require("./permissions/execution-authorizer.js");
 const registry_js_1 = require("./registry/registry.js");
 const planner_registry_js_1 = require("./planner/planner-registry.js");
 const planner_router_registry_js_1 = require("./planner/planner-router-registry.js");
@@ -21,6 +22,12 @@ function immutableCaller(caller) {
     });
 }
 class OperatorRuntime {
+    authorizer;
+    constructor(options = {}) {
+        this.authorizer =
+            options.authorizer ??
+                execution_authorizer_js_1.defaultExecutionAuthorizer;
+    }
     use(module) {
         const declared = new Set(module.manifest.capabilities);
         for (const capability of module.capabilities) {
@@ -31,7 +38,7 @@ class OperatorRuntime {
         }
     }
     async executePlan(plan, options = {}) {
-        return job_manager_js_1.jobManager.executePlan(plan, immutableCaller(options.caller));
+        return job_manager_js_1.jobManager.executePlan(plan, immutableCaller(options.caller), this.authorizer);
     }
     async run(goal, options = {}) {
         const router = planner_router_registry_js_1.plannerRouterRegistry.getDefault();

package/dist/runtime/permissions/execution-authorizer.d.ts

@@ -0,0 +1,23 @@
+import { ExecutionCaller } from '../execution/execution-context.js';
+import { CapabilityRisk } from '../registry/capability.js';
+export interface CapabilityAuthorizationContext {
+    readonly jobId: string;
+    readonly stepId: string;
+    readonly capability: {
+        readonly name: string;
+        readonly version: string;
+        readonly risk: CapabilityRisk;
+    };
+    readonly input: unknown;
+    readonly caller?: ExecutionCaller;
+}
+export type CapabilityAuthorizationDecision = {
+    readonly decision: 'allow';
+} | {
+    readonly decision: 'deny';
+    readonly reason?: string;
+};
+export interface ExecutionAuthorizer {
+    authorize(context: CapabilityAuthorizationContext): Promise<CapabilityAuthorizationDecision>;
+}
+export declare const defaultExecutionAuthorizer: ExecutionAuthorizer;

package/dist/runtime/permissions/execution-authorizer.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultExecutionAuthorizer = void 0;
+const permissions_js_1 = require("./permissions.js");
+exports.defaultExecutionAuthorizer = {
+    async authorize({ capability }) {
+        const permission = (0, permissions_js_1.checkPermission)(capability.risk);
+        if (permission.allowed) {
+            return { decision: 'allow' };
+        }
+        return {
+            decision: 'deny',
+            reason: permission.reason,
+        };
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-runtime/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A governed, capability-driven execution runtime",
   "license": "Apache-2.0",
   "repository": {
@@ -56,16 +56,16 @@
   ],
   "author": "Mustapha",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3",
     "better-sqlite3": "^13.0.3"
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.2.0",
     "fastify": "^5.11.3",
     "playwright": "^1.62.1",
     "tsx": "^4.23.12",
-    "typescript": "^7.0.2",
-    "zod": "^4.4.3"
+    "typescript": "^7.0.2"
   }
 }