Penghou.Luban
0.1.0-preview.1
dotnet add package Penghou.Luban --version 0.1.0-preview.1
NuGet\Install-Package Penghou.Luban -Version 0.1.0-preview.1
<PackageReference Include="Penghou.Luban" Version="0.1.0-preview.1" />
<PackageVersion Include="Penghou.Luban" Version="0.1.0-preview.1" />
<PackageReference Include="Penghou.Luban" />
paket add Penghou.Luban --version 0.1.0-preview.1
#r "nuget: Penghou.Luban, 0.1.0-preview.1"
#:package Penghou.Luban@0.1.0-preview.1
#addin nuget:?package=Penghou.Luban&version=0.1.0-preview.1&prerelease
#tool nuget:?package=Penghou.Luban&version=0.1.0-preview.1&prerelease
Penghou.Luban
A typed tool language and runtime for AI agents, with authorization built into execution.
Luban is designed primarily for AI tool usage and the security of those tool calls. It gives an AI agent a bounded way to express work such as reading files, finding source code, searching text, and proposing changes. It compiles supported commands into typed operations so a host can check what is requested, which resources are involved, and whether the caller is allowed to proceed.
The host supplies the workspace, caller identity, authorization implementation, and execution services. Luban supplies the language, operation contracts and runtime checks; the host composes a qualified I/O provider. This makes the authorization boundary part of how operations run, rather than a convention the agent is expected to follow.
Why use it for AI tools
An AI model can propose an operation, but that proposal is not permission to execute it. Luban gives the host a structured request it can validate and authorize before protected access. Unsupported operations fail explicitly; they do not fall back to a shell.
An agent tool can accept Luban source or construct typed requests directly. The host binds each invocation to the caller and workspace, supplies the authorization policy, and returns typed results to the agent. Bounds on input, traversal, work, and output constrain each supported operation. Concrete resource checks and, for writes, exact-state preconditions remain necessary even when the overall tool call is allowed.
The security goal is to make AI tool access explicit, bounded, and enforceable at the runtime/provider boundary. Prompts and model cooperation are not the enforcement mechanism. Applications without AI can use the same APIs.
How it works
A small read pipeline looks like this:
fd src "**/*.cs" | grep "Authority" | take 20
This finds C# files under src, searches their contents for the literal text Authority, and returns at most 20 matches. The pipe connects typed values between supported operations. The compiler validates the complete document and rejects unknown commands, options, or incompatible pipeline stages.
Luban source or typed requests
|
v
Compiled typed operations
|
v
Host authorization checks
|
v
Trusted provider + resource checks
|
v
Typed results
Static preflight checks known requirements before protected target I/O. Execution checks the operation and the concrete resources it discovers, and checks whether results may be released. An allowed search does not authorize a later write; a returned path does not carry permission to access that file. Each subsequent operation must satisfy its own checks.
Luban is a language with an authorization-aware runtime. It does not provide an OS or container sandbox. Its guarantees depend on the selected provider profile, the host's authorization decisions, and the resource and consistency checks that profile supports. The current strict language accepts a closed set of operations; arbitrary commands, shell substitutions, and process execution are unsupported.
Authorization and Hufu
Penghou.Hufu can translate Luban's typed requests and resource checks into authorization decisions. Its grants, approvals, revocation and authority evidence are maintained and qualified in Hufu's own project.
Hufu is optional. Luban's core does not depend on Hufu, Cedar, Fuwen, Zhinu, a host UI, or a particular agent. Another authorization system can implement the same interfaces and apply its own policy:
ILanguageAuthorizerchecks language preflight, effect start, concrete resource access, and result release.IEffectAuthorizerchecks direct Read/Find/SearchText admission, concrete resource access and final result release; each resource check includes its action and request identity.IFileChangeAuthorizerchecks the whole input set, each target, provider resource access and release of exact diff/merge candidates.IPreviewAuthorizerchecks target and proposal admission, resource access, and release during capture.- The separate mutation executors require host admission, live resource checks, start evidence, and outcome journaling.
Read APIs require an injected authorizer and have no permissive default. Replacing Hufu means supplying those decisions and, for mutation, the required host contracts. It does not remove the runtime's resource checks or stale-state preconditions. See the architecture and Hufu integration contract.
Current capabilities
| Area | Implemented scope |
|---|---|
| Read language | Read, find, literal search, and typed take/count pipelines; bounded parsing, versioned semantic IR, and static preflight |
| Opt-in language v2 | Authorized diff/merge, bounded line windows, and UTF-8 search match spans with optional context; separate catalogue and IR identities |
| Direct API | Typed UTF-8 Files.Read, Files.Find, and Files.SearchText with explicit authorization and bounded results |
| Change preview | Read-only Local capture of existing-file UTF-8 byte patches, exact observations, and explicit unresolved coverage |
| Patch execution | Separate single-target and sequential batch executors for 1–64 distinct exact-target patches, with required host admission and per-node start/outcome evidence |
| Recovery inspection | Host-supplied authoritative receipts; resume only a matching completed prefix, with uncertain outcomes blocking automatic retry |
| Text diff and merge | Pure deterministic diff/merge, canonical transport, display hunks/unified export, and bounded untrusted import with exact in-memory materialization |
Language execution computes and returns observations and change proposals. It performs no writes. Applying a supported candidate uses the separate programmatic capture bridge and executor with fresh host admission and evidence. There are no textual apply/write commands.
The current leaf qualification passes 338 tests on each of .NET 8 and .NET 10 on Windows. The completion ledger records feature, package and CI evidence; the consumer impact guide records dependency and migration work.
Preview, execution, and consistency
Preview captures a proposal; executing it requires separate admission. CaptureComplete means capture finished, while CanCommit remains false. WhatIf has no writer callback or mutation dispatch.
The separate executors check exact targets, payloads, original versions, current authorization, and required start evidence before mutation. Outcomes distinguish completed work, no mutation, and ambiguous results. Batches are sequential and non-atomic: earlier completed writes are not rolled back if a later patch fails.
The Local writer is qualified only for explicitly selected host-controlled Windows NTFS namespaces. The host must control aliases, mounts, and directory configuration against untrusted changes. It uses in-place writes and does not claim crash atomicity or general filesystem confinement. The read provider's path checks also do not prevent every concurrent path-replacement race. See the single-patch, batch, and shared I/O profiles for exact guarantees.
Diff and merge
Luban's text engines compute structured differences and deterministic three-way merges without filesystem I/O, Git, or authorization callbacks. They preserve UTF-8 bytes and newline state and report conflicts explicitly. A clean merge is a computed candidate; it grants no permission to apply it.
D3 adds canonical structured diff/merge transport, display hunks, unified export, and a bounded plain unified importer with exact caller-owned-source validation. Imported data remains untrusted; these APIs perform no I/O or grant authority. See the transport profile and examples. Authorized same-workspace file diff/merge now freezes exact hashes, lengths and provider versions, supports read-only candidate validation, and bridges into fresh capture and separate application. See the file-change profile and application profile. Directory/snapshot operations, broader mutation kinds, richer language transforms, and Git integration have separate delivery gates. See the diff/merge specification and roadmap.
Using Luban
The library and tests target .NET 8 and .NET 10. Neutral runtimes take an injected
IWorkspaceProvider and a logical WorkspaceReference containing only an ID.
The default build pins Penghou.IO.Abstractions and Penghou.IO.Protocols
0.1.0-preview.1; tests and the sample separately compose IO.Local. The physical
Local profile is Windows-only. Publication remains a delivery gate until the
corrective ledger
records the released packages.
For development against the coordinated source change, use sibling checkouts:
repos/
Penghou/
Penghou.Luban/
From the Luban checkout:
dotnet test Penghou.Luban.sln -c Release -p:UsePenghouSource=true
An explicit source build uses -p:UsePenghouSource=true; a different checkout
can be selected with -p:PenghouRoot=C:\source\Penghou. See
shared I/O integration for candidate-feed and
published-package qualification. Luban is packable as 0.1.0-preview.1; CI qualifies its exact dependency closure and a package-only consumer. Public NuGet publication remains a separate release gate.
For AI tool embedding, use LanguageToolRuntime: the host supplies identity, workspace, authorization and bounds, while the agent supplies Luban source. Describe() returns the supported command/profile catalogue; ExecuteAsync returns structured compilation or execution results, and ToJson preserves typed values and named status codes. See the language manual and runnable host sample, which implements a scoped policy without Hufu. The read-language profile documents the underlying runtime; the direct API profile explains its compatibility contract.
Design and delivery
Luban owns typed operations, trusted effect descriptions, language execution and its conformance. Shared resource contracts and providers live in the Penghou.IO packages. Within Penghou, Hufu supplies authority, Fuwen supplies workflow control flow, and Zhinu supplies durable execution. Hosts can integrate other authorization and orchestration systems through the corresponding contracts.
- Documentation index
- Architecture
- Current language manual and examples, language specification, and implemented read profile
- Typed-effect runtime
- Roadmap and implementation plan
Licensed under Apache-2.0.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Penghou.IO.Abstractions (= 0.1.0-preview.1)
- Penghou.IO.Protocols (= 0.1.0-preview.1)
-
net8.0
- Penghou.IO.Abstractions (= 0.1.0-preview.1)
- Penghou.IO.Protocols (= 0.1.0-preview.1)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Penghou.Luban:
| Package | Downloads |
|---|---|
|
Penghou.Hufu.Luban
Optional Hufu semantic authorization for independently usable Luban. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0-preview.1 | 890 | 10/3/2026 |
Preview package. API and profiles remain subject to qualification.