Feat/local versions (#103)

* feat: add agents.yaml project debugger

* feat: add Git CI and Workbench resource editing

* Apply project revision 8e88368b5b94

* Apply project revision 9ff30a1f81b6

* Apply project revision 0d6bdbe7b55b

* Apply project revision b8f89d8ab580

* feat: add Workbench resource and Git version management

* feat: replace Git versioning with local project snapshots

Migrate CLI and Workbench version management to the shared
@openagentpack/project-versions package, backed by lock-protected,
content-addressed YAML snapshots.

- remove Git-specific init/apply options and the local-git package
- share enable, list, preview, restore, and post-Apply versioning
- preserve validation, redaction, atomic restore, and mutation coordination
- update APIs, Workbench UI, documentation, tests, and release tooling

* feat: add directory projects and local snapshot versions

* feat(project): support agent-owned file mounts

Add directory-project File declarations, validate Agent mount paths, upload Files during publish, mount them in new Sessions, and expose File management in Workbench.

* fix(project): stop writing credentials during init

Remove project-local credential environment generation from directory initialization while preserving user-managed .env files and excluding them from snapshots.

* feat(project): add resource scaffolds and safe build preparation

Auto-associate Agent-local File and Skill content during Build, and scaffold inactive resource examples with bilingual guides. Externalize Vault literals into project-local dotenv references and resolve them safely without mutating process environment. Preserve source filenames for declarative uploads and cover the workflows with SDK, workspace, and Workbench regression tests.

* feat(vault): support credential networking and injection policies

* chore: release packages 0.6.0

* fix(ci): build all libraries before SDK compatibility smoke

* fix(playground): externalize project libraries and YAML in ESM bundle

* fix(ci): retry transient dependency audit failures

* fix(webui): upgrade Tiptap to address attribute prototype vulnerability

Author: chenanran555

.changeset/config.json

@@ -2,7 +2,15 @@
 	"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
 	"changelog": "@changesets/cli/changelog",
 	"commit": false,
-	"fixed": [["@openagentpack/sdk", "@openagentpack/playground", "@openagentpack/cli"]],
+	"fixed": [
+		[
+			"@openagentpack/sdk",
+			"@openagentpack/project-versions",
+			"@openagentpack/project-workspace",
+			"@openagentpack/playground",
+			"@openagentpack/cli"
+		]
+	],
 	"linked": [],
 	"access": "public",
 	"baseBranch": "main",

.dependency-cruiser.cjs

@@ -4,14 +4,14 @@ module.exports = {
 		{
 			name: "no-cli-to-server",
 			severity: "error",
-			comment: "The CLI host must consume shared behavior through @openagentpack/sdk, not by importing the API server.",
+			comment: "The CLI host must consume shared behavior through published engine packages, not the API server.",
 			from: { path: "^packages/cli/" },
 			to: { path: "^apps/server/" },
 		},
 		{
 			name: "no-server-to-cli",
 			severity: "error",
-			comment: "The API server must consume shared behavior through @openagentpack/sdk, not by importing CLI code.",
+			comment: "The API server must consume shared behavior through published engine packages, not CLI code.",
 			from: { path: "^apps/server/" },
 			to: { path: "^packages/cli/" },
 		},
@@ -22,6 +22,21 @@ module.exports = {
 			from: { path: "^packages/sdk/" },
 			to: { path: "^(packages/cli|apps/server|apps/webui)/" },
 		},
+		{
+			name: "no-project-versions-to-hosts-or-apps",
+			severity: "error",
+			comment:
+				"@openagentpack/project-versions is a shared Node engine and must not depend on host packages or applications.",
+			from: { path: "^packages/project-versions/" },
+			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
+		},
+		{
+			name: "no-project-workspace-to-hosts-or-apps",
+			severity: "error",
+			comment: "@openagentpack/project-workspace is a shared Node engine and must not depend on hosts or applications.",
+			from: { path: "^packages/project-workspace/" },
+			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
+		},
 		{
 			name: "no-sdk-deep-imports",
 			severity: "error",
@@ -42,6 +57,20 @@ module.exports = {
 			from: { path: "^apps/webui/src/" },
 			to: { path: "^packages/sdk/" },
 		},
+		{
+			name: "no-webui-project-versions-runtime-import",
+			severity: "error",
+			comment: "Browser-facing code must use Workbench APIs instead of importing the Node-only version engine.",
+			from: { path: "^apps/webui/src/" },
+			to: { path: "^packages/project-versions/" },
+		},
+		{
+			name: "no-webui-project-workspace-runtime-import",
+			severity: "error",
+			comment: "Browser-facing code must use Workbench APIs instead of importing the Node-only workspace engine.",
+			from: { path: "^apps/webui/src/" },
+			to: { path: "^packages/project-workspace/" },
+		},
 	],
 	options: {
 		doNotFollow: {

.github/workflows/ci.yml

@@ -58,13 +58,13 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # Full consumer smoke (sdk + playground + cli) on the repo baseline.
+          # Full consumer smoke (library packages + playground + cli) on the repo baseline.
           - node: 22
             scope: all
           - node: 24
             scope: all
-          # SDK-only smoke on the sdk engines floor (>=18.17.0): cli/playground
-          # require Node >=22, so only the sdk tarball is installed and imported.
+          # Library smoke on the SDK engines floor (>=18.17.0): build and install
+          # sdk, project-versions, and project-workspace; cli/playground require Node >=22.
           - node: 18.17.0
             scope: sdk
           - node: 20
@@ -86,6 +86,8 @@ jobs:
       - if: matrix.scope == 'sdk'
         run: |
           bun run build:sdk
+          bun run build:project-versions
+          bun run build:project-workspace
           bun scripts/release/smoke-packed.ts --sdk-only
 
   gate:

README.md

@@ -77,14 +77,21 @@ The mechanics are a single `agents.yaml`, a `validate → plan → apply` workfl
 ## Quick start
 
 ```bash
-agents init            # interactive wizard writes a starter agents.yaml
-agents validate        # offline YAML check, no API calls
-agents plan            # preview create / update / delete
-agents apply -y        # apply changes
-agents destroy         # tear down managed resources
+agents project init             # create a directory project (or convert agents.yaml)
+agents project validate         # validate JSON, Markdown, skills, and local files
+agents project build --dry-run  # preview organization and generated YAML
+agents project build -y         # freeze the current source into a Build
+agents project publish -y       # publish exactly that Build and record a version
+agents project workbench        # edit and debug the same directory project
 ```
 
-Run `agents playground` to launch the local WebUI, and use `--provider` to target `bailian`, `qoder`, `ark`, or `claude`. You can switch providers on the same declaration, run real sessions, and observe tool calls and artifacts.
+Directory projects keep global settings in `project.json`, each Agent under `agents/<id>/`, Agent instructions in `instructions.md`, and local Skill source either beside its Agent or under the shared `skills/` directory. Build promotes a Skill to the shared directory when multiple Agents reference it and deterministically writes `.openagentpack/build/agents.yaml`. Publish never runs Build implicitly.
+
+Fresh Init includes Skill, File, Vault, and Environment examples under each resource directory's `_examples/`, with bilingual configuration instructions. They are not linked in `agent.json`, do not enter generated YAML, and are not published remotely. Copy an example outside `_examples/` and configure its Agent reference to enable it.
+
+Workbench and CLI share `agents project version status|enable|disable|list|preview|restore`. Versions are Git-independent full source-tree snapshots: immutable manifests point to content-addressed text and binary blobs, while `.openagentpack/state.json` is always excluded. Restore writes a historical tree forward into the working directory without moving version history or remote State. Deployment and Channel declarations remain read-only in Workbench but participate in full project Publish.
+
+The original YAML workflow remains available through `agents init`, `validate`, `plan`, `apply`, and `destroy`. `agents playground -f agents.yaml` continues to open a YAML Agent Session Preview, but YAML Apply no longer creates project versions and cannot be used inside a directory-project root.
 
 ▶ [Watch the full Playground demo](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
 
@@ -172,28 +179,31 @@ The [`examples/`](./examples) directory has runnable configs for every provider,
 
 ## Using the SDK
 
-Everything the CLI does is available programmatically from `@openagentpack/sdk`:
+Cloud runtime capabilities are available from `@openagentpack/sdk`. Directory compilation, Build/Publish, and full-tree versions are exposed by `@openagentpack/project-workspace`, backed by the storage primitives in `@openagentpack/project-versions`:
 
 ```ts
-import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";
-
-const config = await resolveProjectConfig({ configPath: "agents.yaml" });
-const plan = await planProjectContext(config);
-console.log(plan);
+import { previewProjectBuild, commitProjectBuild } from "@openagentpack/project-workspace";
+
+const preview = await previewProjectBuild("./my-agent");
+const build = await commitProjectBuild({
+  projectRoot: preview.project_root,
+  baseRevision: preview.project_revision,
+});
+console.log(build.manifest);
 ```
 
 See the [SDK reference](./docs/reference/sdk.md) for the public API surface.
 
 ## WebUI
 
-`apps/webui` is a Vite single-page app for browsing playbooks and driving agent sessions; `apps/server` exposes the SDK over an OpenAPI surface. Run both from the repo root:
+`apps/webui` is a Vite directory-project Workbench; `apps/server` exposes directory editing, Build/Publish, versions, and Session debugging over an OpenAPI surface. Run both from the repo root with `AGENTS_PROJECT_ROOT` pointing at a project:
 
 ```bash
 bun install
 bun run dev        # server + webui together
 ```
 
-Or launch a packaged local UI with `agents playground --provider <bailian|qoder|ark|claude>`.
+Launch the packaged project console with `agents project workbench --project <directory>`. Use `agents playground -f <path/to/agents.yaml>` only for the legacy YAML Session Preview. Workbench edits directory source, requires an explicit Build, and publishes the reviewed Build; it never edits Provider ownership or pushes Git state.
 
 ## Contributing
 

README.zh-CN.md

@@ -81,10 +81,13 @@ agents init            # 交互式向导生成 agents.yaml
 agents validate        # 离线校验，不发起 API 调用
 agents plan            # 预览 create / update / delete
 agents apply -y        # 执行变更
+agents version enable  # 可选：成功 Apply 后版本化 YAML
 agents destroy         # 销毁托管资源
 ```
 
-运行 `agents playground` 可启动本地 WebUI，并通过 `--provider` 指定 `bailian`、`qoder`、`ark` 或 `claude`。你可以在同一份声明上切换 Provider、运行真实 Session，并观察工具调用和 Artifact。
+运行 `agents playground -f agents.yaml` 会直接打开 Agent Preview：单 Agent 项目自动选择，多 Agent 项目可传 `--agent <id>`，未指定时进入 Workbench 选择。使用 `agents workbench -f agents.yaml` 可直接打开项目控制台且不创建 Session。Playground 从 YAML 读取全部 Agent 和 Provider，并监听本地依赖文件。Workbench 的 Resources 页面可以通过服务端生成的 YAML Diff 编辑或移除已有声明；保存更新 `agents.yaml` 并自动刷新项目 Plan。本地版本默认不存在，只有用户在 Versions 页面或通过 `agents version enable` 显式启用后才会创建基线；开关启用时，成功 Apply 后自动版本化有变化的 YAML。Versions 页面与 CLI 共用开关，并浏览和恢复历史。
+
+CLI 也提供 `agents version status|enable|disable|list|preview|restore`。Workbench 与 CLI 按当前 `agents.yaml` 共用一个本地开关：`agents version enable` 会在需要时创建基线并开启两边的成功 Apply 自动版本，`version disable` 会同时关闭两边。`store.json` 只保存开关和 head，`entries/` 保存不可变链式元数据，完整 YAML 保存在内容寻址的 `blobs/` 中，因此不依赖 Git。Restore 只把历史 YAML 写回工作区，不移动版本历史；`agents.state.json` 和外部引用文件始终不进入版本。Deployment 和 Channel 声明继续只读，且不进入 Workbench 项目 Apply。配置缺失或非法时进入诊断 Workbench。
 
 ▶ [观看 Playground 完整演示](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
 
@@ -172,10 +175,11 @@ Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定
 
 ## 使用 SDK
 
-CLI 的全部能力都可通过 `@openagentpack/sdk` 以编程方式调用：
+云端项目运行能力可通过 `@openagentpack/sdk` 以编程方式调用；仅限 Node.js 的本地项目版本能力由独立包 `@openagentpack/project-versions` 提供：
 
 ```ts
 import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";
+import { createProjectVersionService } from "@openagentpack/project-versions";
 
 const config = await resolveProjectConfig({ configPath: "agents.yaml" });
 const plan = await planProjectContext(config);
@@ -186,14 +190,14 @@ console.log(plan);
 
 ## WebUI
 
-`apps/webui` 是一个 Vite 单页应用，用于浏览 playbook 和驱动 Agent Session；`apps/server` 通过 OpenAPI 暴露 SDK。从仓库根目录同时启动两者：
+`apps/webui` 是一个 Vite 单页项目工作台，用于检查和调试 `agents.yaml` 中声明的 Agent；`apps/server` 通过 OpenAPI 暴露 SDK。从仓库根目录同时启动两者：
 
 ```bash
 bun install
 bun run dev        # 同时启动 server + webui
 ```
 
-或用 `agents playground --provider <bailian|qoder|ark|claude>` 启动打包的本地 UI。
+也可以用 `agents playground -f <path/to/agents.yaml>` 打开打包后的 Preview，或用 `agents workbench -f <path/to/agents.yaml>` 打开项目控制台。Provider、模型、工具、memory、skills 和资源全部来自 YAML，UI 不提供覆盖；Deployment 声明仅只读展示。
 
 ## 参与贡献
 

apps/server/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @openagentpack/server
 
+## 0.0.11
+
+### Patch Changes
+
+- Updated dependencies [8c6a767]
+- Updated dependencies [f956bad]
+  - @openagentpack/sdk@0.6.0
+  - @openagentpack/project-versions@0.6.0
+  - @openagentpack/project-workspace@0.6.0
+
 ## 0.0.10
 
 ### Patch Changes