Lenso

Build products from replaceable Plugins.

Lenso is a local-first, language-independent runtime for applications whose behavior must be added, replaced, and removed without turning composition into hidden framework magic.

Define product roles as typed Capabilities, implement them as Plugins, and let each Host resolve one exact application before it boots. Humans and coding agents work against the same inspectable Plugin Root and the runtime executes the resulting immutable Plan with explicit lifecycle and failure semantics.

Get started · Read the documentation · Contributing · Explore executable examples · Install the Agent skills

What Lenso gives you

• Replaceable product behavior. Plugins own their configuration, state, lifecycle, failure policy, and provided or required Capabilities.
• Typed collaboration. Capability Interfaces make Plugin relationships explicit across request, stream, and event Operations.
• Reviewable composition. An App owner changes only the visible plugins/ directory; the Host supplies defaults and rejects ambiguous or incompatible selections.
• Deterministic execution. Every accepted App becomes an immutable Resolved App Plan before the Kernel starts it.
• Agent-ready workflows. Public skills route planning, Capability, Plugin, App configuration, and runtime work to checkable artifacts and evidence.

Lenso is designed for long-lived products with evolving boundaries: business systems, developer tools, automation products, and Agent applications. It is not a Web framework, a distributed control plane, or a promise that every Plugin can run unchanged in every environment.

Try one Plugin

From this repository's source checkout, build the candidate CLI and exercise a typed Plugin through a real Execution Adapter. The npm CLI is not yet a supported installation path for this candidate: its release still needs the platform-specific native executables.

cargo build --locked -p lenso-cli --bin lenso
LENSO_CLI="$(pwd)/target/debug/lenso"

"$LENSO_CLI" plugin new example.echo
cd example.echo
"$LENSO_CLI" plugin check
"$LENSO_CLI" plugin dev \
  --operation execute \
  --request-json '{"name":"example.echo","arguments_json":"{\"text\":\"hello\"}"}'
"$LENSO_CLI" plugin pack

The default Rust project produces a trusted Process implementation. Select --runtime multi when creating the project to produce both portable Wasm and Process implementations from the same source. plugin dev selects the fastest local implementation; plugin pack builds and verifies the distributable .lenso-plugin Release. A Bun / TypeScript path is also available with lenso plugin new example.echo --runtime bun.

Read the complete quickstart to understand how the verified Bundle connects to a compatible product Host.

For small applications built from this checkout, run the three application examples: task CRUD, background jobs with local notifications, and a typed metadata pipeline. Their automated smokes exercise real HTTP and Plugin lifecycle behavior.

How it works

Plugin source -> generated Descriptor -> Host + Plugin Root -> Resolved App Plan
                                                             |
                                                             v
Runtime Driver -> portable Kernel -> Execution Adapters -> Plugin Instances

The Plan records exact Plugin identities, Capability bindings, execution choices, and policy inputs. The Kernel validates and runs that Plan; it does not discover packages, choose versions, or rewrite the application graph while booting.

The main branch contains the Lenso runtime and its design evidence. The final v0.3.x source remains available from the lenso@0.3.47 tag and Git history.

Workspace

The Rust workspace is the shared home for the framework's frequently co-evolving main chain:

• Plan, Kernel, Runtime Driver interfaces, and deterministic conformance;
• native, Process, Wasm, QuickJS, Bun, and remote Execution Adapters;
• Engine authoring, configuration, resolution, and embedding APIs;
• the lenso CLI and Rust Plugin authoring SDKs;
• portable contract tooling plus language-neutral fixtures under spec/; and
• optional Rust Web packages and focused executable examples.

Internal crates use workspace or path dependencies so a framework change can be validated atomically without publishing temporary versions. Public crate names and versions remain stable, and packaged-consumer validation remains a separate release gate.

The repository boundary follows language and product ownership rather than runtime mechanics. Bun/Node SDKs, Bun fixtures, Web client integration, and the @lenso/contract-runtime and @lenso/process-protocol sources and tests are in lenso-js. This source move has not published a new npm version. Already published versions retain their original lenso-protocols provenance and cannot be replaced with packages built from the new checkout.

The Site, Lenso UI, Marketplace backend, and downstream products remain independent. Optional product Plugins such as Auth stay with their product owner unless frequent shared Rust evolution provides a concrete reason to move them here. See ADR 0077.

The Kernel has no Service, Provider, System Plane, Console, Story, Auth, PostgreSQL, Outbox, Workflow, migration, release, or discovery implementation. Those concerns can return only as ordinary Plugins, Execution Adapters, authoring tools, or separate repositories when an architecture decision assigns them an owner.

Agent skills

The project skill pack turns the Lenso architecture into cross-repository planning, Capability, Plugin, App configuration, and runtime workflows without relocating implementation ownership. List the six workflows with:

npx skills add LioRael/lenso --list

Start with lenso-start when the owning seam is not yet clear. The Agents and skills guide documents invocation, installation, progressive disclosure, contributor validation, and behavioral forward testing.

Contributing

CONTRIBUTING.md is the human contribution entry point. Editors and AI tools are optional: contributors can use any development setup that produces a reviewable immutable commit. Maintainers run the one necessary upstream candidate gate before fast-forward integration.

Choose focused checks for prose, Rust code, or workflow/build changes rather than running every workspace and platform command for every edit. The portable Plan, Kernel, and conformance Interface are compile-checked for wasm32-unknown-unknown and wasm32-wasip2 when the final candidate requires that proof. Driver and Adapter crates in this workspace own their target-specific checks; external products separately validate packaged framework releases.

Architecture

• CONTEXT.md is the canonical vocabulary and invariant set.
• docs/architecture/lenso-vnext.md is the runtime overview.
• docs/architecture/lenso-authoring.md documents project authoring and Plan resolution.
• docs/adr/README.md routes the normative ADRs 0030–0077.
• docs/architecture/execution-target-capability-matrix.md defines target-admission facts separately from qualification.

Branches

main is the integration and release line. Work starts from origin/main; maintainers validate an immutable candidate and fast-forward that exact revision. Landing, CI, package publication, and deployment remain separate operations.