Penghou.Luban 0.1.0-preview.1

This is a prerelease version of Penghou.Luban.
dotnet add package Penghou.Luban --version 0.1.0-preview.1
                    
NuGet\Install-Package Penghou.Luban -Version 0.1.0-preview.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Penghou.Luban" Version="0.1.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Penghou.Luban" Version="0.1.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="Penghou.Luban" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Penghou.Luban --version 0.1.0-preview.1
                    
#r "nuget: Penghou.Luban, 0.1.0-preview.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Penghou.Luban@0.1.0-preview.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Penghou.Luban&version=0.1.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Penghou.Luban&version=0.1.0-preview.1&prerelease
                    
Install as a Cake Tool

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:

  • ILanguageAuthorizer checks language preflight, effect start, concrete resource access, and result release.
  • IEffectAuthorizer checks direct Read/Find/SearchText admission, concrete resource access and final result release; each resource check includes its action and request identity.
  • IFileChangeAuthorizer checks the whole input set, each target, provider resource access and release of exact diff/merge candidates.
  • IPreviewAuthorizer checks 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.

Licensed under Apache-2.0.

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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.