@veil-runtime/core 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,480 @@
+# Veil
+
+Veil is a capability-driven execution platform for AI and software systems.
+
+It separates **reasoning** from **execution**, allowing planners, language models, agents, humans and applications to safely interact with external systems through reusable capabilities while keeping execution governed, observable, auditable and independent of any specific AI provider.
+
+The goal is simple:
+
+> **Allow any planner to decide _what_ should happen, while Veil reliably decides _how_ it happens.**
+
+Or, more simply:
+
+> **Veil treats AI as a planning problem and execution as an engineering problem.**
+
+---
+
+# Vision
+
+Modern language models are exceptional at reasoning.
+
+They should not be responsible for safely interacting with production systems.
+
+Veil provides the governed execution layer between reasoning and the outside world.
+
+Instead of allowing planners to directly manipulate browsers, files, databases, infrastructure or external services, Veil executes structured plans through governed capabilities, applying validation, permissions, policies, memory, logging and runtime services before any action is performed.
+
+The result is a reusable execution platform capable of powering automation, operational intelligence, developer tooling and enterprise integrations without coupling execution to any specific reasoning system or AI provider.
+
+---
+
+# Architectural Principles
+
+Veil owns **the contract between reasoning and execution**.
+
+It does not prescribe how reasoning is performed or how capabilities are implemented.
+
+Instead, it defines stable interfaces that allow both sides to evolve independently.
+
+```text
+Reasoning
+    │
+Planner Providers
+Planner Strategies
+Planner Routing
+    │
+ExecutionPlan
+══════════════════════
+OperatorRuntime
+══════════════════════
+Capability Registry
+Capability Modules
+Providers
+    │
+Execution
+```
+
+This separation allows new planners, routing strategies, capability modules and providers to be introduced without changing Veil Core.
+
+---
+
+# Architecture
+
+```text
+                         Goal
+                          │
+                          ▼
+                    Planner Router
+                          │
+                   selects strategy
+                          │
+                          ▼
+                   Planner Strategy
+                          │
+             ┌────────────┼────────────┐
+             │            │            │
+             ▼            ▼            ▼
+      Planner Registry Runtime State Eligibility
+             │
+             └────────────┬────────────┘
+                          │
+                          ▼
+                  Planner Provider(s)
+                          │
+                          ▼
+                    ExecutionPlan
+
+══════════════════════════════════════════════
+                     VEIL
+══════════════════════════════════════════════
+
+                          │
+                          ▼
+                  OperatorRuntime
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+       Policy        Job Manager      Event Bus
+                                             │
+                                             ▼
+                                     Execution Engine
+                                             │
+                                             ▼
+                                  Capability Registry
+                                             │
+                                             ▼
+                                  Capability Modules
+                                             │
+                                             ▼
+                                         Providers
+                                             │
+           ┌──────────────┬──────────────┬──────────────┬──────────────┐
+           ▼              ▼              ▼              ▼
+        Browser      Filesystem        Shell          HTTP
+```
+
+---
+
+# Current Features
+
+## Runtime
+
+- Generic execution engine
+- OperatorRuntime façade
+- Planner router registry
+- Planner registry
+- Strategy registry
+- Capability registry
+- ExecutionPlan contract
+- Execution context
+- Event bus
+- Runtime events
+- Structured execution logging
+- Job lifecycle management
+- Persistent SQLite job store
+- Human-reviewed outcomes
+
+---
+
+## Planning
+
+- Planner router
+- Planner registry
+- Planner strategies
+- Deterministic planner
+- OpenAI-compatible planner support
+- Example local and distributed planner configurations
+- Planner health monitoring
+- Planner runtime state
+- Planner eligibility
+- Historical context retrieval
+- ExecutionPlan v1
+
+---
+
+## SDK
+
+- Capability SDK
+- Declarative capability authoring
+- Middleware pipeline
+- Lifecycle middleware
+- Timeout middleware
+- Runtime execution options
+- Capability module support
+
+---
+
+## Memory
+
+- Persistent job history
+- Planner context retrieval
+- Historical capability recall
+- Outcome recording
+- Human review workflow
+
+---
+
+## Capabilities
+
+- LinkedIn authentication
+- LinkedIn profile reader
+- Generic web page reader
+- HTTP request execution
+- Filesystem reader
+- Shell command execution
+
+---
+
+## Providers
+
+- Browser provider
+- Browser session manager
+- HTTP provider
+- Filesystem provider
+- Shell provider
+- SQLite provider
+- OpenAI-compatible AI providers
+
+---
+
+# Design Principles
+
+- Planner agnostic
+- Strategy agnostic
+- Provider agnostic
+- Capability driven
+- Runtime governed
+- Explicit permissions
+- Structured observability
+- Human review before learning
+- Small composable services
+- Extension through composition
+- Reusable by design
+
+---
+
+# What Makes Veil Different
+
+Veil does not attempt to replace language models.
+
+Instead, it provides the governed execution environment around them.
+
+Reasoning remains completely replaceable.
+
+Execution remains governed and deterministic at the capability boundary.
+
+Applications can embed Veil without coupling themselves to specific planners, capability implementations or infrastructure providers.
+
+Because these responsibilities remain independent:
+
+- Routers choose strategies.
+- Strategies orchestrate planners.
+- Planners produce execution plans.
+- OperatorRuntime governs execution.
+- Capabilities perform the work.
+- Providers interact with external systems.
+- Runtime services remain independent of planners and capabilities.
+
+This separation allows Veil to remain reusable across domains while ensuring execution remains governed, observable and consistent.
+
+---
+
+# Roadmap
+
+## Runtime
+
+- Dependency graph execution
+- Parallel capability execution
+- Live progress reporting
+- Cancellation
+- Retry policies
+- Secrets service
+- Metrics
+- Audit services
+- Resource management
+
+---
+
+## SDK
+
+- Provider SDK
+- Capability testing framework
+- Middleware library
+- Validation helpers
+- Retry middleware
+- Metrics middleware
+- Audit middleware
+- Execution decorators
+
+---
+
+## Intelligence
+
+- Planner routing policies
+- Planner evaluation
+- Cost-aware routing
+- Latency-aware routing
+- Capability recommendations
+- Historical plan optimisation
+- Outcome-aware learning
+- Runtime analytics
+- Multi-agent planning pipelines
+
+---
+
+## Capabilities
+
+- LinkedIn posting
+- GitHub
+- Docker
+- SSH
+- SQL
+- Jira
+- Confluence
+- Kubernetes
+- Cloud providers
+- Generic REST integrations
+
+---
+
+# Long-Term Direction
+
+Veil is evolving into a reusable execution platform capable of powering:
+
+- AI assistants
+- Operational intelligence platforms
+- Enterprise automation
+- Developer tooling
+- Agentic systems
+- Workflow orchestration
+- Multi-agent collaboration
+
+Reasoning remains modular through planners, strategies and routing.
+
+Execution remains governed and deterministic at the capability boundary.
+
+Veil defines the contract between them.
+
+---
+
+# Status
+
+Veil has evolved beyond a proof of concept into a reusable execution platform.
+
+The execution runtime, capability system, reasoning architecture, planner routing, planner strategies, provider model, event bus, persistent memory, module architecture and SDK foundation are now in place.
+
+The current focus is strengthening the platform itself—its SDKs, runtime services, provider ecosystem, reasoning architecture and execution model—so that new planners, strategies, capabilities and integrations become progressively simpler to build while preserving governed, observable and reliable execution.
+
+Every architectural improvement compounds across the platform, allowing Veil to grow in capability while keeping complexity contained behind stable contracts.
+
+The guiding principles remain simple:
+
+> **Veil owns the contract between reasoning and execution.**
+
+> **Planners reason. Strategies orchestrate. OperatorRuntime governs execution. Veil owns the contract between them.**
+
+> **Architecture evolves only when existing contracts can no longer express a real-world use case. Otherwise, Veil grows through extensions rather than changes to its core.**
+
+---
+---
+
+# Getting Started
+
+## Requirements
+
+- Node.js 24+
+- npm
+- Git
+
+Optional:
+
+- Docker Model Runner or another OpenAI-compatible endpoint
+- Playwright (for browser capabilities)
+
+---
+
+## 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:
+
+```bash
+git clone git@github.com:veil-runtime/veil.git
+cd veil
+```
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+---
+
+## Running Veil
+
+Start the runtime:
+
+```bash
+JOB_STORE=sqlite npm run dev
+```
+
+The runtime will start on:
+
+```
+http://127.0.0.1:3333
+```
+
+Verify it's running:
+
+```bash
+curl http://127.0.0.1:3333/health
+```
+
+Expected response:
+
+```json
+{
+  "status": "ok",
+  "service": "operator-runtime"
+}
+```
+
+---
+
+## Running Your First Job
+
+Submit a goal:
+
+```bash
+curl -X POST http://127.0.0.1:3333/api/jobs/run \
+  -H "Content-Type: application/json" \
+  -d '{
+    "goal": "Read README.md"
+  }'
+```
+
+Veil will:
+
+1. Route the request through a `PlannerRouter`.
+2. Select a `PlannerStrategy`.
+3. Generate an `ExecutionPlan`.
+4. Execute the plan through `OperatorRuntime`.
+5. Return the completed job.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { OperatorRuntime, operatorRuntime } from './runtime/operator-runtime.js';
+export type { ExecutePlanOptions, RunJobOptions } from './runtime/operator-runtime.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';
+export type { CapabilityModule } from './runtime/modules/capability-module.js';
+export type { CapabilityModuleManifest } from './runtime/modules/capability-module-manifest.js';
+export type { Job, JobOutcome } from './runtime/jobs/job.js';
+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 * from './sdk/index.js';