@veil-runtime/core 0.1.0

package/dist/runtime/permissions/permissions.d.ts

@@ -0,0 +1,7 @@
+import { CapabilityRisk } from '../registry/capability.js';
+export interface PermissionDecision {
+    allowed: boolean;
+    requiresApproval: boolean;
+    reason?: string;
+}
+export declare function checkPermission(risk: CapabilityRisk, approved?: boolean): PermissionDecision;

package/dist/runtime/permissions/permissions.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkPermission = checkPermission;
+function checkPermission(risk, approved = false) {
+    if (risk === 'read') {
+        return {
+            allowed: true,
+            requiresApproval: false,
+        };
+    }
+    if (risk === 'write') {
+        if (approved) {
+            return {
+                allowed: true,
+                requiresApproval: false,
+            };
+        }
+        return {
+            allowed: false,
+            requiresApproval: true,
+            reason: 'Write capability requires explicit approval.',
+        };
+    }
+    if (risk === 'destructive') {
+        if (approved) {
+            return {
+                allowed: true,
+                requiresApproval: false,
+            };
+        }
+        return {
+            allowed: false,
+            requiresApproval: true,
+            reason: 'Destructive capability requires explicit approval.',
+        };
+    }
+    return {
+        allowed: false,
+        requiresApproval: false,
+        reason: 'Unknown capability risk.',
+    };
+}

package/dist/runtime/planner/planner-definition.d.ts

@@ -0,0 +1,9 @@
+import { PlannerTraits } from './planner-traits.js';
+export interface PlannerDefinition {
+    id: string;
+    type: string;
+    enabled: boolean;
+    required?: boolean;
+    traits?: PlannerTraits;
+    config?: Record<string, unknown>;
+}

package/dist/runtime/planner/planner-definition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/planner/planner-eligibility.d.ts

@@ -0,0 +1,7 @@
+import { PlannerDefinition } from './planner-definition.js';
+import { PlannerRuntimeState } from './planner-runtime-state.js';
+export interface PlannerEligibility {
+    eligible: boolean;
+    reasons: string[];
+}
+export declare function evaluatePlannerEligibility(definition: PlannerDefinition, state: PlannerRuntimeState): PlannerEligibility;

package/dist/runtime/planner/planner-eligibility.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluatePlannerEligibility = evaluatePlannerEligibility;
+function evaluatePlannerEligibility(definition, state) {
+    const reasons = [];
+    if (!definition.enabled) {
+        reasons.push('Planner is disabled');
+    }
+    if (!state.available) {
+        reasons.push('Planner is unavailable');
+    }
+    if (!state.healthy) {
+        reasons.push(state.failureReason ??
+            'Planner is unhealthy');
+    }
+    return {
+        eligible: reasons.length === 0,
+        reasons,
+    };
+}

package/dist/runtime/planner/planner-provider.d.ts

@@ -0,0 +1,11 @@
+import { ExecutionPlan, PlannerContext } from './planner.js';
+export interface PlannerHealthResult {
+    healthy: boolean;
+    available: boolean;
+    reason?: string;
+}
+export interface PlannerProvider {
+    readonly name: string;
+    plan(goal: string, context?: PlannerContext): Promise<ExecutionPlan>;
+    healthCheck?(): Promise<PlannerHealthResult>;
+}

package/dist/runtime/planner/planner-provider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/planner/planner-registry.d.ts

@@ -0,0 +1,40 @@
+import { PlannerProvider } from './planner-provider.js';
+import { PlannerDefinition } from './planner-definition.js';
+import { PlannerRuntimeState } from './planner-runtime-state.js';
+export interface RegisteredPlanner {
+    definition: PlannerDefinition;
+    provider: PlannerProvider;
+    state: PlannerRuntimeState;
+}
+interface RegisterPlannerOptions {
+    state?: Partial<PlannerRuntimeState>;
+}
+declare class PlannerRegistry {
+    private readonly planners;
+    register(definition: PlannerDefinition, provider: PlannerProvider, options?: RegisterPlannerOptions): void;
+    get(id: string): PlannerProvider | undefined;
+    getRegistered(id: string): RegisteredPlanner | undefined;
+    getEligibility(id: string): import("./planner-eligibility.js").PlannerEligibility;
+    list(): Array<{
+        name: string;
+    }>;
+    refreshHealth(id: string): Promise<RegisteredPlanner>;
+    refreshAllHealth(): Promise<void>;
+    listStatus(): {
+        id: string;
+        type: string;
+        enabled: boolean;
+        required: boolean;
+        traits: import("./planner-traits.js").PlannerTraits | undefined;
+        healthy: boolean;
+        available: boolean;
+        lastCheckedAt: string | undefined;
+        failureReason: string | undefined;
+        eligible: boolean;
+        reasons: string[];
+    }[];
+    listRegistered(): RegisteredPlanner[];
+    updateState(id: string, state: Partial<PlannerRuntimeState>): RegisteredPlanner;
+}
+export declare const plannerRegistry: PlannerRegistry;
+export {};

package/dist/runtime/planner/planner-registry.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plannerRegistry = void 0;
+const planner_eligibility_js_1 = require("./planner-eligibility.js");
+class PlannerRegistry {
+    planners = new Map();
+    register(definition, provider, options = {}) {
+        if (this.planners.has(definition.id)) {
+            throw new Error(`Planner already registered: ${definition.id}`);
+        }
+        const entry = {
+            definition,
+            provider,
+            state: {
+                healthy: true,
+                available: true,
+                ...options.state,
+            },
+        };
+        this.planners.set(definition.id, entry);
+    }
+    get(id) {
+        return this.planners.get(id)?.provider;
+    }
+    getRegistered(id) {
+        return this.planners.get(id);
+    }
+    getEligibility(id) {
+        const planner = this.planners.get(id);
+        if (!planner) {
+            throw new Error(`Planner not found: ${id}`);
+        }
+        return (0, planner_eligibility_js_1.evaluatePlannerEligibility)(planner.definition, planner.state);
+    }
+    list() {
+        return Array.from(this.planners.values()).map((entry) => ({
+            name: entry.definition.id,
+        }));
+    }
+    async refreshHealth(id) {
+        const planner = this.planners.get(id);
+        if (!planner) {
+            throw new Error(`Planner not found: ${id}`);
+        }
+        const checkedAt = new Date().toISOString();
+        if (!planner.provider.healthCheck) {
+            planner.state = {
+                ...planner.state,
+                healthy: true,
+                available: true,
+                lastCheckedAt: checkedAt,
+                failureReason: undefined,
+            };
+            return planner;
+        }
+        const health = await planner.provider.healthCheck();
+        planner.state = {
+            ...planner.state,
+            healthy: health.healthy,
+            available: health.available,
+            lastCheckedAt: checkedAt,
+            failureReason: health.reason,
+        };
+        return planner;
+    }
+    async refreshAllHealth() {
+        await Promise.all(Array.from(this.planners.keys()).map((id) => this.refreshHealth(id)));
+    }
+    listStatus() {
+        return Array.from(this.planners.values()).map((planner) => {
+            const eligibility = (0, planner_eligibility_js_1.evaluatePlannerEligibility)(planner.definition, planner.state);
+            return {
+                id: planner.definition.id,
+                type: planner.definition.type,
+                enabled: planner.definition.enabled,
+                required: planner.definition.required ??
+                    false,
+                traits: planner.definition.traits,
+                healthy: planner.state.healthy,
+                available: planner.state.available,
+                lastCheckedAt: planner.state.lastCheckedAt,
+                failureReason: planner.state.failureReason,
+                eligible: eligibility.eligible,
+                reasons: eligibility.reasons,
+            };
+        });
+    }
+    listRegistered() {
+        return Array.from(this.planners.values());
+    }
+    updateState(id, state) {
+        const planner = this.planners.get(id);
+        if (!planner) {
+            throw new Error(`Planner not found: ${id}`);
+        }
+        planner.state = {
+            ...planner.state,
+            ...state,
+        };
+        return planner;
+    }
+}
+exports.plannerRegistry = new PlannerRegistry();

package/dist/runtime/planner/planner-router-registry.d.ts

@@ -0,0 +1,17 @@
+import { PlannerRouter } from './planner-router.js';
+declare class PlannerRouterRegistry {
+    private readonly routers;
+    private defaultRouterId?;
+    register(id: string, router: PlannerRouter, options?: {
+        default?: boolean;
+    }): void;
+    get(id: string): PlannerRouter | undefined;
+    getDefault(): PlannerRouter | undefined;
+    getDefaultId(): string | undefined;
+    list(): Array<{
+        id: string;
+        default: boolean;
+    }>;
+}
+export declare const plannerRouterRegistry: PlannerRouterRegistry;
+export {};

package/dist/runtime/planner/planner-router-registry.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plannerRouterRegistry = void 0;
+class PlannerRouterRegistry {
+    routers = new Map();
+    defaultRouterId;
+    register(id, router, options = {}) {
+        if (this.routers.has(id)) {
+            throw new Error(`Planner router already registered: ${id}`);
+        }
+        this.routers.set(id, router);
+        if (options.default) {
+            this.defaultRouterId =
+                id;
+        }
+    }
+    get(id) {
+        return this.routers.get(id);
+    }
+    getDefault() {
+        if (!this.defaultRouterId) {
+            return undefined;
+        }
+        return this.routers.get(this.defaultRouterId);
+    }
+    getDefaultId() {
+        return this.defaultRouterId;
+    }
+    list() {
+        return Array.from(this.routers.keys()).map((id) => ({
+            id,
+            default: id ===
+                this.defaultRouterId,
+        }));
+    }
+}
+exports.plannerRouterRegistry = new PlannerRouterRegistry();

package/dist/runtime/planner/planner-router.d.ts

@@ -0,0 +1,14 @@
+import { PlannerContext } from './planner.js';
+export interface PlannerRoutingRequest {
+    goal: string;
+    strategy?: string;
+    planner?: string;
+    context?: PlannerContext;
+}
+export interface PlannerSelection {
+    strategy: string;
+    reason?: string;
+}
+export interface PlannerRouter {
+    select(request: PlannerRoutingRequest): Promise<PlannerSelection>;
+}

package/dist/runtime/planner/planner-router.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/planner/planner-runtime-state.d.ts

@@ -0,0 +1,6 @@
+export interface PlannerRuntimeState {
+    healthy: boolean;
+    available: boolean;
+    lastCheckedAt?: string;
+    failureReason?: string;
+}

package/dist/runtime/planner/planner-runtime-state.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/planner/planner-traits.d.ts

@@ -0,0 +1,10 @@
+export type PlannerCostClass = 'free' | 'low' | 'standard' | 'premium';
+export type StructuredOutputSupport = 'none' | 'json' | 'schema';
+export interface PlannerTraits {
+    local?: boolean;
+    costClass?: PlannerCostClass;
+    coding?: boolean;
+    structuredOutput?: StructuredOutputSupport;
+    toolReasoning?: boolean;
+    contextWindow?: number;
+}

package/dist/runtime/planner/planner-traits.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/planner/planner.d.ts

@@ -0,0 +1,29 @@
+export interface PlannerContext {
+    previousJobs?: Array<{
+        goal: string;
+        status: string;
+        capabilities: string[];
+    }>;
+}
+export interface ResultReference {
+    readonly $ref: string;
+}
+export interface ExecutionStep {
+    readonly id: string;
+    readonly capability: string;
+    readonly capabilityVersion?: string;
+    readonly input?: unknown;
+    readonly reason?: string;
+    readonly idempotencyKey?: string;
+}
+export interface ExecutionPlan {
+    readonly version: string;
+    readonly id?: string;
+    readonly goal?: string;
+    readonly steps: readonly ExecutionStep[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly idempotencyKey?: string;
+}
+export interface Planner {
+    plan(goal: string, context?: PlannerContext): Promise<ExecutionPlan>;
+}

package/dist/runtime/planner/planner.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/planner/strategies/planner-strategy-registry.d.ts

@@ -0,0 +1,12 @@
+import { PlannerStrategy } from './planner-strategy.js';
+declare class PlannerStrategyRegistry {
+    private readonly strategies;
+    register(strategy: PlannerStrategy): void;
+    get(id: string): PlannerStrategy | undefined;
+    list(): {
+        id: string;
+        type: string;
+    }[];
+}
+export declare const plannerStrategyRegistry: PlannerStrategyRegistry;
+export {};

package/dist/runtime/planner/strategies/planner-strategy-registry.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plannerStrategyRegistry = void 0;
+class PlannerStrategyRegistry {
+    strategies = new Map();
+    register(strategy) {
+        if (this.strategies.has(strategy.id)) {
+            throw new Error(`Planner strategy already registered: ${strategy.id}`);
+        }
+        this.strategies.set(strategy.id, strategy);
+    }
+    get(id) {
+        return this.strategies.get(id);
+    }
+    list() {
+        return Array.from(this.strategies.values()).map((strategy) => ({
+            id: strategy.id,
+            type: strategy.type,
+        }));
+    }
+}
+exports.plannerStrategyRegistry = new PlannerStrategyRegistry();

package/dist/runtime/planner/strategies/planner-strategy.d.ts

@@ -0,0 +1,11 @@
+import { ExecutionPlan, PlannerContext } from '../planner.js';
+export interface PlannerStrategyRequest {
+    goal: string;
+    planner?: string;
+    context?: PlannerContext;
+}
+export interface PlannerStrategy {
+    readonly id: string;
+    readonly type: string;
+    execute(request: PlannerStrategyRequest): Promise<ExecutionPlan>;
+}

package/dist/runtime/planner/strategies/planner-strategy.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/registry/capability.d.ts

@@ -0,0 +1,15 @@
+import { ExecutionContext } from '../execution/execution-context.js';
+export type CapabilityRisk = 'read' | 'write' | 'destructive';
+export interface CapabilityInputField {
+    type: string;
+    required: boolean;
+    description: string;
+}
+export interface Capability<TInput = unknown, TResult = unknown> {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly risk: CapabilityRisk;
+    inputSchema?: Record<string, CapabilityInputField>;
+    execute(input: TInput, context?: ExecutionContext): Promise<TResult>;
+}

package/dist/runtime/registry/capability.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/registry/registry.d.ts

@@ -0,0 +1,15 @@
+import { Capability } from './capability.js';
+declare class CapabilityRegistry {
+    private capabilities;
+    register(capability: Capability): void;
+    get(name: string): Capability | undefined;
+    list(): {
+        name: string;
+        version: string;
+        description: string;
+        risk: import("./capability.js").CapabilityRisk;
+        inputSchema: Record<string, import("./capability.js").CapabilityInputField>;
+    }[];
+}
+export declare const capabilityRegistry: CapabilityRegistry;
+export {};

package/dist/runtime/registry/registry.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilityRegistry = void 0;
+class CapabilityRegistry {
+    capabilities = new Map();
+    register(capability) {
+        if (this.capabilities.has(capability.name)) {
+            throw new Error(`Capability already registered: ${capability.name}`);
+        }
+        this.capabilities.set(capability.name, capability);
+    }
+    get(name) {
+        return this.capabilities.get(name);
+    }
+    list() {
+        return Array.from(this.capabilities.values()).map((capability) => ({
+            name: capability.name,
+            version: capability.version,
+            description: capability.description,
+            risk: capability.risk,
+            inputSchema: capability.inputSchema ?? {},
+        }));
+    }
+}
+exports.capabilityRegistry = new CapabilityRegistry();

package/dist/sdk/capability/capability-definition.d.ts

@@ -0,0 +1,19 @@
+import { Capability, CapabilityInputField, CapabilityRisk } from '../../runtime/registry/capability.js';
+import { ExecutionContext } from '../../runtime/execution/execution-context.js';
+import { CapabilityMiddleware } from './capability-middleware.js';
+export interface CapabilityExecution<TInput, TResult> {
+    input: TInput;
+    context?: ExecutionContext;
+}
+export interface CapabilityDefinition<TInput = unknown, TResult = unknown> {
+    name: string;
+    version: string;
+    description: string;
+    risk: CapabilityRisk;
+    inputSchema?: Record<string, CapabilityInputField>;
+    lifecycleLogging?: boolean;
+    timeoutMs?: number;
+    middleware?: CapabilityMiddleware<TInput, TResult>[];
+    execute(execution: CapabilityExecution<TInput, TResult>): Promise<TResult>;
+}
+export type CreatedCapability<TInput, TResult> = Capability<TInput, TResult>;

package/dist/sdk/capability/capability-definition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sdk/capability/capability-middleware.d.ts

@@ -0,0 +1,5 @@
+import { CapabilityExecution } from './capability-definition.js';
+export type CapabilityNext<TResult> = () => Promise<TResult>;
+export interface CapabilityMiddleware<TInput = unknown, TResult = unknown> {
+    execute(execution: CapabilityExecution<TInput, TResult>, next: CapabilityNext<TResult>): Promise<TResult>;
+}

package/dist/sdk/capability/capability-middleware.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sdk/capability/create-capability.d.ts

@@ -0,0 +1,3 @@
+import { Capability } from '../../runtime/registry/capability.js';
+import { CapabilityDefinition } from './capability-definition.js';
+export declare function createCapability<TInput = unknown, TResult = unknown>(definition: CapabilityDefinition<TInput, TResult>): Capability<TInput, TResult>;

package/dist/sdk/capability/create-capability.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCapability = createCapability;
+const lifecycle_logging_middleware_js_1 = require("./lifecycle-logging-middleware.js");
+const timeout_middleware_js_1 = require("./timeout-middleware.js");
+function createCapability(definition) {
+    return {
+        name: definition.name,
+        version: definition.version,
+        description: definition.description,
+        risk: definition.risk,
+        inputSchema: definition.inputSchema,
+        async execute(input, context) {
+            const execution = {
+                input,
+                context,
+            };
+            const middleware = [];
+            if (definition.lifecycleLogging ??
+                true) {
+                middleware.push(new lifecycle_logging_middleware_js_1.LifecycleLoggingMiddleware(definition.name));
+            }
+            if (definition.timeoutMs !==
+                undefined) {
+                middleware.push(new timeout_middleware_js_1.TimeoutMiddleware(definition.timeoutMs));
+            }
+            middleware.push(...(definition.middleware ?? []));
+            let next = () => definition.execute(execution);
+            for (let index = middleware.length - 1; index >= 0; index -= 1) {
+                const current = middleware[index];
+                const previousNext = next;
+                next = () => current.execute(execution, previousNext);
+            }
+            return next();
+        },
+    };
+}

package/dist/sdk/capability/index.d.ts

@@ -0,0 +1,5 @@
+export { createCapability, } from './create-capability.js';
+export type { CapabilityDefinition, CapabilityExecution, CreatedCapability, } from './capability-definition.js';
+export { LifecycleLoggingMiddleware, } from './lifecycle-logging-middleware.js';
+export type { CapabilityMiddleware, CapabilityNext, } from './capability-middleware.js';
+export { TimeoutMiddleware, } from './timeout-middleware.js';

package/dist/sdk/capability/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutMiddleware = exports.LifecycleLoggingMiddleware = exports.createCapability = void 0;
+var create_capability_js_1 = require("./create-capability.js");
+Object.defineProperty(exports, "createCapability", { enumerable: true, get: function () { return create_capability_js_1.createCapability; } });
+var lifecycle_logging_middleware_js_1 = require("./lifecycle-logging-middleware.js");
+Object.defineProperty(exports, "LifecycleLoggingMiddleware", { enumerable: true, get: function () { return lifecycle_logging_middleware_js_1.LifecycleLoggingMiddleware; } });
+var timeout_middleware_js_1 = require("./timeout-middleware.js");
+Object.defineProperty(exports, "TimeoutMiddleware", { enumerable: true, get: function () { return timeout_middleware_js_1.TimeoutMiddleware; } });

package/dist/sdk/capability/lifecycle-logging-middleware.d.ts

@@ -0,0 +1,7 @@
+import { CapabilityMiddleware, CapabilityNext } from './capability-middleware.js';
+import { CapabilityExecution } from './capability-definition.js';
+export declare class LifecycleLoggingMiddleware<TInput = unknown, TResult = unknown> implements CapabilityMiddleware<TInput, TResult> {
+    private readonly capabilityName;
+    constructor(capabilityName: string);
+    execute(execution: CapabilityExecution<TInput, TResult>, next: CapabilityNext<TResult>): Promise<TResult>;
+}

package/dist/sdk/capability/lifecycle-logging-middleware.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleLoggingMiddleware = void 0;
+class LifecycleLoggingMiddleware {
+    capabilityName;
+    constructor(capabilityName) {
+        this.capabilityName = capabilityName;
+    }
+    async execute(execution, next) {
+        const startedAt = Date.now();
+        execution.context?.logger.info('Capability execution started', {
+            capability: this.capabilityName,
+        });
+        try {
+            const result = await next();
+            execution.context?.logger.info('Capability execution completed', {
+                capability: this.capabilityName,
+                durationMs: Date.now() - startedAt,
+            });
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error
+                ? error.message
+                : 'Unknown capability error';
+            execution.context?.logger.error('Capability execution failed', {
+                capability: this.capabilityName,
+                durationMs: Date.now() - startedAt,
+                error: message,
+            });
+            throw error;
+        }
+    }
+}
+exports.LifecycleLoggingMiddleware = LifecycleLoggingMiddleware;