@openagentpack/sdk 0.6.0 → 0.7.1

package/dist/project-workspace.js

@@ -0,0 +1,1774 @@
+import {
+  LocalFileStateBackend,
+  executePlannedProject,
+  planProjectContext,
+  planProjectWithStateBackend,
+  writeProjectRuntime
+} from "./chunk-HIK5DY4I.js";
+import {
+  createDirectoryProjectVersionService
+} from "./chunk-56BB46YT.js";
+import {
+  UserError,
+  inspectProjectSource,
+  resolveProjectConfig,
+  resolveProjectConfigFromObject,
+  validateProjectConfig
+} from "./chunk-ZBJDMUJT.js";
+import "./chunk-6PDVAFLK.js";
+import "./chunk-CHGDM6TX.js";
+
+// src/internal/project-workspace/index.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import {
+  chmod as chmod2,
+  cp,
+  lstat as lstat2,
+  mkdir,
+  readdir,
+  readFile as readFile2,
+  realpath,
+  rename as rename2,
+  rm as rm2,
+  rmdir,
+  stat,
+  writeFile as writeFile2
+} from "fs/promises";
+import { basename, dirname, extname, isAbsolute, relative, resolve as resolve2, sep } from "path";
+import { parse, stringify } from "yaml";
+
+// src/internal/project-workspace/scaffold.ts
+var RESOURCE_EXAMPLES_DIRECTORY = "_examples";
+function directoryProjectScaffold() {
+  const agentRoot = "agents/assistant";
+  const json = (value) => `${JSON.stringify(value, null, 2)}
+`;
+  return {
+    "project.json": json({ version: "1" }),
+    [`${agentRoot}/agent.json`]: json({
+      name: "Assistant",
+      model: "qwen3.7-max"
+    }),
+    [`${agentRoot}/instructions.md`]: "You are a helpful assistant.\n",
+    [`${agentRoot}/skills/${RESOURCE_EXAMPLES_DIRECTORY}/example-skill/skill.json`]: json({
+      id: "example-skill",
+      name: "Example Skill",
+      description: "Summarize user-provided text. / \u603B\u7ED3\u7528\u6237\u63D0\u4F9B\u7684\u6587\u672C\u3002"
+    }),
+    [`${agentRoot}/skills/${RESOURCE_EXAMPLES_DIRECTORY}/example-skill/SKILL.md`]: `---
+name: example-skill
+description: Summarize user-provided text into concise key points. \u603B\u7ED3\u7528\u6237\u63D0\u4F9B\u7684\u6587\u672C\u3002
+---
+
+# Summarize text / \u6587\u672C\u603B\u7ED3
+
+Use this Skill when the user asks to summarize text.
+\u7528\u6237\u8981\u6C42\u603B\u7ED3\u6587\u672C\u65F6\uFF0C\u4F7F\u7528\u6B64 Skill\u3002
+
+1. Read the provided text. / \u9605\u8BFB\u7528\u6237\u63D0\u4F9B\u7684\u6587\u672C\u3002
+2. Extract the main ideas without adding unsupported facts. / \u63D0\u70BC\u8981\u70B9\uFF0C\u4E0D\u6DFB\u52A0\u672A\u7ECF\u652F\u6301\u7684\u4E8B\u5B9E\u3002
+3. Respond in the user's language with a brief summary. / \u4F7F\u7528\u7528\u6237\u7684\u8BED\u8A00\u7ED9\u51FA\u7B80\u77ED\u603B\u7ED3\u3002
+`,
+    [`${agentRoot}/skills/${RESOURCE_EXAMPLES_DIRECTORY}/example-skill/README.md`]: `# Skill example / Skill \u914D\u7F6E\u793A\u4F8B
+
+- \`skill.json\` defines the resource ID and display fields. Keep its \`id\` unique across the project.
+  \`skill.json\` \u58F0\u660E\u8D44\u6E90 ID \u548C\u5C55\u793A\u5B57\u6BB5\uFF0CID \u5728\u9879\u76EE\u7684 Skill \u4E2D\u5FC5\u987B\u552F\u4E00\u3002
+- \`SKILL.md\` contains the Skill instructions. Put scripts/assets in this same directory if needed;
+  the directory is the upload source. Do not put secrets in these files.
+  \`SKILL.md\` \u662F Skill \u6307\u4EE4\uFF0C\u9700\u8981\u7684\u811A\u672C\u548C\u7D20\u6750\u4E5F\u653E\u5728\u6B64\u76EE\u5F55\uFF1B\u6574\u4E2A\u76EE\u5F55\u4F5C\u4E3A\u4E0A\u4F20\u6E90\uFF0C\u8BF7\u52FF\u653E\u5165\u5BC6\u94A5\u3002
+- This example is ignored by Build/Publish. Copy it from \`skills/_examples/example-skill/\`
+  to \`skills/example-skill/\`, then Build adds \`"example-skill"\` to \`agent.json.skills\` automatically.
+  \u6B64\u793A\u4F8B\u4E0D\u53C2\u4E0E\u6784\u5EFA/\u53D1\u5E03\u3002\u590D\u5236\u5230 \`skills/example-skill/\` \u540E\uFF0CBuild \u4F1A\u81EA\u52A8\u8865\u9F50 Agent \u5F15\u7528\u3002
+- To add another Skill, copy this directory, change the directory name and \`skill.json.id\`,
+  then run Build to add its ID to \`agent.json.skills\`. A new directory with only \`SKILL.md\` is also discovered by Build.
+  \u65B0\u589E Skill \u65F6\u590D\u5236\u6B64\u76EE\u5F55\u3001\u4FEE\u6539\u76EE\u5F55\u540D\u548C ID\uFF0C\u518D\u8FD0\u884C Build \u81EA\u52A8\u5173\u8054\uFF1B\u53EA\u653E \`SKILL.md\` \u7684\u65B0\u76EE\u5F55\u4E5F\u80FD\u7531 Build \u81EA\u52A8\u5173\u8054\u3002
+- Delete this ignored example directory if not needed. For an enabled Skill, also remove its Agent reference.
+  \u4E0D\u9700\u8981\u65F6\u53EF\u76F4\u63A5\u5220\u9664\u672C\u793A\u4F8B\u76EE\u5F55\uFF1B\u82E5\u5DF2\u7ECF\u542F\u7528\uFF0C\u8FD8\u9700\u5220\u9664 Agent \u5F15\u7528\u3002
+`,
+    [`${agentRoot}/files/${RESOURCE_EXAMPLES_DIRECTORY}/example-file/file.json`]: json({
+      id: "example-file",
+      name: "example.md",
+      source: "./example.md"
+    }),
+    [`${agentRoot}/files/${RESOURCE_EXAMPLES_DIRECTORY}/example-file/example.md`]: `# Example reference / \u793A\u4F8B\u53C2\u8003\u6587\u4EF6
+
+Replace this file with the reference material your Agent needs.
+\u8BF7\u5C06\u6B64\u6587\u4EF6\u66FF\u6362\u4E3A Agent \u9700\u8981\u7684\u53C2\u8003\u8D44\u6599\u3002
+
+This is an ignored example. After you explicitly enable it, configure a new-Session mount
+at \`/mnt/example.md\` in agent.json.
+\u8FD9\u662F\u672A\u542F\u7528\u7684\u793A\u4F8B\u3002\u663E\u5F0F\u542F\u7528\u540E\uFF0C\u53EF\u5728 agent.json \u4E2D\u914D\u7F6E\u65B0 Session \u7684\u6302\u8F7D\u8DEF\u5F84 \`/mnt/example.md\`\u3002
+`,
+    [`${agentRoot}/files/${RESOURCE_EXAMPLES_DIRECTORY}/example-file/README.md`]: `# File example / File \u914D\u7F6E\u793A\u4F8B
+
+- \`file.json\` is metadata; \`example.md\` is the content uploaded by Publish.
+  \`file.json\` \u662F\u5143\u6570\u636E\uFF1BPublish \u4E0A\u4F20\u7684\u662F \`example.md\` \u5185\u5BB9\uFF0C\u4E0D\u662F\u672C README\u3002
+- \`source\` is relative to this resource directory. Keep \`id\` equal to the directory name.
+  \`source\` \u76F8\u5BF9\u6B64\u8D44\u6E90\u76EE\u5F55\u89E3\u6790\uFF0C\`id\` \u5E94\u4E0E\u76EE\u5F55\u540D\u4E00\u81F4\u3002
+- Build/Publish ignore this example. Copy \`files/_examples/example-file/\` to \`files/example-file/\`
+  to enable its declaration; Build adds \`{"file": "example-file", "mount_path": "/mnt/example.md"}\` to \`agent.json.files\`.
+  \u6B64\u793A\u4F8B\u4E0D\u53C2\u4E0E\u6784\u5EFA/\u53D1\u5E03\u3002\u590D\u5236\u5230 \`files/example-file/\` \u540E\uFF0CBuild \u81EA\u52A8\u6DFB\u52A0\u4E0A\u8FF0\u6302\u8F7D\u5F15\u7528\uFF1B\u5DF2\u6709\u81EA\u5B9A\u4E49\u6302\u8F7D\u8DEF\u5F84\u4F1A\u4FDD\u7559\uFF0C\u6302\u8F7D\u8DEF\u5F84\u5FC5\u987B\u5728 \`/mnt/\` \u4E0B\u3002
+- Uploading a File does not permanently attach it to the remote Agent. These declarations
+  supply default mounts for new Sessions; existing Sessions are unchanged.
+  \u4E0A\u4F20 File \u4E0D\u7B49\u4E8E\u6C38\u4E45\u7ED1\u5B9A\u5230\u8FDC\u7AEF Agent\uFF1B\u8FD9\u91CC\u58F0\u660E\u7684\u662F\u65B0 Session \u7684\u9ED8\u8BA4\u6302\u8F7D\uFF0C\u4E0D\u4FEE\u6539\u5DF2\u6709 Session\u3002
+- Build can also infer metadata and an Agent mount for a file placed directly in the parent
+  \`files/\` directory, or a resource directory containing exactly one content file.
+  \u5728\u4E0A\u7EA7 \`files/\` \u76F4\u63A5\u653E\u6587\u4EF6\uFF0C\u6216\u5728\u65B0\u8D44\u6E90\u76EE\u5F55\u4E2D\u53EA\u653E\u4E00\u4E2A\u5185\u5BB9\u6587\u4EF6\uFF0CBuild \u4E5F\u4F1A\u81EA\u52A8\u751F\u6210\u5143\u6570\u636E\u548C\u6302\u8F7D\u5F15\u7528\u3002
+- Delete this ignored example directory if not needed. For an enabled File, also remove its Agent reference.
+  \u4E0D\u9700\u8981\u65F6\u53EF\u76F4\u63A5\u5220\u9664\u672C\u793A\u4F8B\u76EE\u5F55\uFF1B\u82E5\u5DF2\u7ECF\u542F\u7528\uFF0C\u8FD8\u9700\u5220\u9664 Agent \u4E2D\u7684 File \u5F15\u7528\u3002
+`,
+    [`${agentRoot}/vaults/${RESOURCE_EXAMPLES_DIRECTORY}/example-vault/vault.json`]: json({
+      id: "example-vault",
+      display_name: "Example Vault",
+      credentials: [
+        {
+          name: "service-token",
+          type: "environment_variable",
+          secret_name: "SERVICE_TOKEN",
+          secret_value: "${SERVICE_TOKEN}"
+        }
+      ]
+    }),
+    [`${agentRoot}/vaults/${RESOURCE_EXAMPLES_DIRECTORY}/example-vault/README.md`]: `# Vault example / Vault \u914D\u7F6E\u793A\u4F8B
+
+Build/Publish ignore this directory; no example secret is required to open Workbench.
+Copy \`vaults/_examples/example-vault/\` to \`vaults/example-vault/\` to enable the declaration,
+then supply the secret and run Build. If \`agent.json.vault\` is unset, Build selects the sole local Vault automatically.
+With multiple local Vaults, set \`"vault": "example-vault"\` explicitly; Build never overwrites an existing selection.
+\u6B64\u793A\u4F8B\u4E0D\u53C2\u4E0E\u6784\u5EFA/\u53D1\u5E03\uFF0C\u4E0D\u9700\u8981\u914D\u7F6E\u5BC6\u94A5\u5373\u53EF\u6253\u5F00 Workbench\u3002
+\u542F\u7528\u65F6\uFF0C\u590D\u5236\u5230 \`vaults/example-vault/\`\uFF0C\u914D\u7F6E\u5BC6\u94A5\u540E\u8FD0\u884C Build\u3002\u672A\u6307\u5B9A Vault \u65F6\u81EA\u52A8\u5173\u8054\u552F\u4E00\u5019\u9009\uFF1B\u591A\u4E2A\u5019\u9009\u9700\u663E\u5F0F\u9009\u62E9\uFF0C\u5DF2\u6709\u5F15\u7528\u4E0D\u8986\u76D6\u3002
+
+The example \`vault.json\` contains:
+\u793A\u4F8B \`vault.json\` \u7684\u5B8C\u6574\u914D\u7F6E\u5982\u4E0B\uFF1A
+
+\`\`\`json
+${JSON.stringify(
+      {
+        id: "example-vault",
+        display_name: "Example Vault",
+        credentials: [
+          {
+            name: "service-token",
+            type: "environment_variable",
+            secret_name: "SERVICE_TOKEN",
+            secret_value: "${SERVICE_TOKEN}"
+          }
+        ]
+      },
+      null,
+      2
+    )}
+\`\`\`
+
+- \`name\` identifies the credential; \`secret_name\` is the environment variable exposed to the runtime.
+  \`secret_value\` references a local environment variable. The two variable names may differ.
+  \`name\` \u662F\u51ED\u636E\u540D\u79F0\uFF1B\`secret_name\` \u662F\u8FD0\u884C\u65F6\u7684\u53D8\u91CF\u540D\uFF1B\`secret_value\` \u5F15\u7528\u672C\u5730\u73AF\u5883\u53D8\u91CF\uFF0C\u4E24\u8005\u53EF\u4EE5\u4E0D\u540C\u3002
+- Provide \`SERVICE_TOKEN\` in the process environment or project-root \`.env\` before runtime/Publish.
+  \u4F7F\u7528\u524D\u5728\u8FDB\u7A0B\u73AF\u5883\u6216\u9879\u76EE\u6839\u76EE\u5F55 \`.env\` \u4E2D\u914D\u7F6E \`SERVICE_TOKEN\`\uFF0C\u4E0D\u8981\u5C06\u771F\u5B9E\u503C\u5199\u5165\u672C README\u3002
+- If you put a literal secret in \`vault.json\`, Build moves it to project-root \`.env\`
+  and replaces the JSON value with an environment reference. Preview/dry-run do not write it.
+  \u82E5\u5728 \`vault.json\` \u5199\u5165\u660E\u6587\uFF0CBuild \u4F1A\u5C06\u5176\u79FB\u5165\u9879\u76EE\u6839\u76EE\u5F55 \`.env\` \u5E76\u5199\u56DE\u53D8\u91CF\u5F15\u7528\uFF1B\u9884\u89C8\u4E0D\u4F1A\u5199\u6587\u4EF6\u3002
+- \`.env\` is plaintext with owner-only permissions when created by Build. It is excluded from local
+  version snapshots, not automatically Git-ignored. Back it up securely and add it to your Git ignore rules.
+  \`.env\` \u4ECD\u662F\u672C\u5730\u660E\u6587\u6587\u4EF6\uFF1BBuild \u521B\u5EFA\u65F6\u4EC5\u6587\u4EF6\u6240\u6709\u8005\u53EF\u8BFB\u5199\u3002\u5B83\u4E0D\u8FDB\u5165\u672C\u5730\u7248\u672C\u5FEB\u7167\uFF0C\u8BF7\u5B89\u5168\u5907\u4EFD\u5E76\u81EA\u884C\u52A0\u5165 Git \u5FFD\u7565\u89C4\u5219\u3002
+- Never put real credentials into ignored examples: example files are still local versioned source.
+  Do not put secrets into this README. Only enabled Vault declarations participate in Build secret migration.
+  \u4E0D\u8981\u5728\u793A\u4F8B\u6216 README \u4E2D\u653E\u5165\u771F\u5B9E\u5BC6\u94A5\uFF1A\u793A\u4F8B\u4ECD\u5C5E\u4E8E\u672C\u5730\u7248\u672C\u6E90\u6587\u4EF6\u3002\u53EA\u6709\u5DF2\u542F\u7528\u7684 Vault \u58F0\u660E\u4F1A\u53C2\u4E0E Build \u5BC6\u94A5\u8FC1\u79FB\u3002
+- Delete this ignored example directory if not needed. For an enabled Vault, also remove \`agent.json.vault\`.
+  \u4E0D\u9700\u8981\u65F6\u53EF\u76F4\u63A5\u5220\u9664\u672C\u793A\u4F8B\u76EE\u5F55\uFF1B\u82E5\u5DF2\u7ECF\u542F\u7528\uFF0C\u8FD8\u9700\u5220\u9664 Agent \u7684 \`vault\` \u5B57\u6BB5\u3002
+`,
+    [`${agentRoot}/environments/${RESOURCE_EXAMPLES_DIRECTORY}/example-env/environment.json`]: json({
+      id: "example-env",
+      name: "Example Environment",
+      config: { type: "cloud" }
+    }),
+    [`${agentRoot}/environments/${RESOURCE_EXAMPLES_DIRECTORY}/example-env/README.md`]: `# Environment example / Environment \u914D\u7F6E\u793A\u4F8B
+
+- This is an ignored managed cloud environment example. Copy \`environments/_examples/example-env/\`
+  to \`environments/example-env/\`, then run Build. An unset \`agent.json.environment\` is linked to the sole local Environment.
+  With multiple local Environments, set \`"environment": "example-env"\` explicitly; existing selections are preserved.
+  \u8FD9\u662F\u4E0D\u53C2\u4E0E\u6784\u5EFA/\u53D1\u5E03\u7684\u6258\u7BA1\u4E91\u73AF\u5883\u793A\u4F8B\u3002\u590D\u5236\u5230 \`environments/example-env/\` \u540E\u8FD0\u884C Build\uFF1B\u672A\u6307\u5B9A\u73AF\u5883\u65F6\u81EA\u52A8\u5173\u8054\u552F\u4E00\u5019\u9009\uFF0C\u591A\u4E2A\u5019\u9009\u9700\u663E\u5F0F\u9009\u62E9\uFF0C\u5DF2\u6709\u5F15\u7528\u4E0D\u8986\u76D6\u3002
+  Keep \`id\` equal to the directory name. / ID \u5E94\u4E0E\u76EE\u5F55\u540D\u4E00\u81F4\u3002
+- Optional \`config\` fields include \`networking\`, \`packages\`, and \`setup_script\`.
+  \`config\` \u53EF\u6309\u9700\u589E\u52A0\u7F51\u7EDC\u7B56\u7565\u3001\u4F9D\u8D56\u5305\u548C\u521D\u59CB\u5316\u811A\u672C\uFF0C\u4F8B\u5982\uFF1A
+
+\`\`\`json
+${JSON.stringify({ type: "cloud", packages: { pip: ["requests"] }, setup_script: "echo 'Environment ready'" }, null, 2)}
+\`\`\`
+
+- The snippet replaces only \`config\`. Build validates declarations locally;
+  packages/scripts take effect on the remote platform, not on your computer during Init/Build.
+  \u4E0A\u9762\u7684\u7247\u6BB5\u53EA\u66FF\u6362 \`config\`\u3002Init/Build \u4E0D\u4F1A\u5728\u672C\u673A\u5B89\u88C5\u4F9D\u8D56\u6216\u6267\u884C\u811A\u672C\uFF1B\u8FDC\u7AEF\u662F\u5426\u652F\u6301\u4EE5 Provider \u4E3A\u51C6\u3002
+- Init leaves \`agent.json\` unchanged and only creates ignored resource examples.
+  Moving a declaration outside \`_examples/\` enables it for Build/Publish; Build also fills in the owning Agent's missing reference.
+  Init \u4E0D\u6DFB\u52A0 Agent \u8D44\u6E90\u5F15\u7528\u3002\u5C06\u58F0\u660E\u79FB\u5230 \`_examples/\` \u5916\u540E\uFF0CBuild \u4F1A\u8865\u9F50\u6240\u5C5E Agent \u7684\u5F15\u7528\u5E76\u7EB3\u5165\u6784\u5EFA/\u53D1\u5E03\u3002
+- Delete this ignored example directory if not needed. For an enabled Environment, also remove its Agent reference.
+  \u4E0D\u9700\u8981\u65F6\u53EF\u76F4\u63A5\u5220\u9664\u672C\u793A\u4F8B\u76EE\u5F55\uFF1B\u82E5\u5DF2\u7ECF\u542F\u7528\uFF0C\u8FD8\u9700\u5220\u9664 Agent \u7684 Environment \u5F15\u7528\u3002
+`
+  };
+}
+
+// src/internal/project-workspace/vault-secrets.ts
+import { createHash, randomUUID } from "crypto";
+import { chmod, lstat, readFile, rename, rm, writeFile } from "fs/promises";
+import { resolve } from "path";
+import * as nodeUtil from "util";
+var ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+var VAULT_PATH = /^(?:agents\/[^/]+\/vaults|resources\/vaults)\/[^/]+\/vault\.json$/;
+async function planVaultSecretMigration(root, files) {
+  const plan = { overrides: /* @__PURE__ */ new Map(), literals: [], count: 0, envBefore: null, envAfter: null };
+  const candidates = [];
+  for (const file of files.filter(
+    (candidate) => VAULT_PATH.test(candidate.path) && !candidate.path.includes(`/vaults/${RESOURCE_EXAMPLES_DIRECTORY}/`)
+  )) {
+    let metadata;
+    try {
+      metadata = JSON.parse(Buffer.from(file.content).toString("utf8"));
+    } catch {
+      throw new UserError(`${file.path}: invalid JSON; source omitted. / JSON \u65E0\u6548\uFF0C\u5DF2\u9690\u85CF\u6E90\u5185\u5BB9\u3002`);
+    }
+    if (!isRecord(metadata) || !Array.isArray(metadata.credentials)) continue;
+    for (const credential of metadata.credentials) {
+      if (!isRecord(credential)) continue;
+      for (const field of ["secret_value", "access_token"]) {
+        const value = credential[field];
+        if (typeof value !== "string" && typeof value !== "number" || String(value) === "" || ENV_REFERENCE.test(String(value)))
+          continue;
+        candidates.push({ path: file.path, metadata, credential, field, value: String(value) });
+      }
+    }
+  }
+  if (candidates.length === 0) return plan;
+  plan.envBefore = await readProjectDotEnv(root);
+  const existing = parseProjectDotEnv(plan.envBefore ?? "");
+  let content = plan.envBefore ?? "";
+  for (const candidate of candidates) {
+    const identity = `${String(candidate.metadata.id)}\0${String(candidate.credential.name)}\0${candidate.field}`;
+    const suffix = createHash("sha256").update(identity).digest("hex").slice(0, 12).toUpperCase();
+    const label = `${String(candidate.metadata.id)}_${String(candidate.credential.name)}_${candidate.field}`.replace(/[^A-Za-z0-9_]/g, "_").toUpperCase().slice(0, 80);
+    const baseName = `AGENTS_VAULT_${label}_${suffix}`;
+    let variable = baseName;
+    let sequence = 2;
+    while (existing[variable] !== void 0 && existing[variable] !== candidate.value || process.env[variable] !== void 0 && process.env[variable] !== candidate.value) {
+      variable = `${baseName}_${sequence++}`;
+    }
+    if (existing[variable] === void 0) {
+      const assignment = encodeAssignment(variable, candidate.value);
+      if (content && !content.endsWith("\n")) content += "\n";
+      content += assignment;
+      existing[variable] = candidate.value;
+    }
+    candidate.credential[candidate.field] = `\${${variable}}`;
+    plan.overrides.set(candidate.path, candidate.metadata);
+    plan.literals.push(candidate.value);
+    plan.count++;
+  }
+  const verified = parseProjectDotEnv(content);
+  for (const [name, value] of Object.entries(existing)) {
+    if (verified[name] !== value)
+      throw new UserError("Cannot safely append to project .env. Fix its syntax first. / \u8BF7\u5148\u4FEE\u590D\u9879\u76EE .env \u7684\u8BED\u6CD5\u3002");
+  }
+  plan.envAfter = content;
+  return plan;
+}
+async function applyVaultSecretMigration(root, files, plan) {
+  if (plan.count === 0) return;
+  const assertEnvironmentUnchanged = async () => {
+    if (await readProjectDotEnv(root) !== plan.envBefore)
+      throw new UserError("Project .env changed. Preview Build again. / .env \u5DF2\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u9884\u89C8\u6784\u5EFA\u3002");
+  };
+  await assertEnvironmentUnchanged();
+  const sourceByPath = new Map(files.map((file) => [file.path, file]));
+  for (const path of plan.overrides.keys()) await assertUnchanged(root, sourceByPath.get(path));
+  await writePrivateAtomic(resolve(root, ".env"), plan.envAfter, 384, assertEnvironmentUnchanged);
+  for (const [path, metadata] of plan.overrides) {
+    const source = sourceByPath.get(path);
+    await assertUnchanged(root, source);
+    await writePrivateAtomic(
+      resolve(root, path),
+      `${JSON.stringify(metadata, null, 2)}
+`,
+      source.mode,
+      () => assertUnchanged(root, source)
+    );
+  }
+}
+async function readProjectEnvironment(root) {
+  return parseProjectDotEnv(await readProjectDotEnv(root) ?? "");
+}
+async function readProjectDotEnv(root) {
+  const path = resolve(root, ".env");
+  try {
+    const details = await lstat(path);
+    if (!details.isFile() || details.isSymbolicLink()) throw new Error("unsafe file");
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (hasCode(error, "ENOENT")) return null;
+    throw new UserError(
+      "Project .env must be a readable regular file, not a symlink. / \u9879\u76EE .env \u5FC5\u987B\u662F\u53EF\u8BFB\u7684\u666E\u901A\u6587\u4EF6\uFF0C\u4E0D\u80FD\u662F\u7B26\u53F7\u94FE\u63A5\u3002"
+    );
+  }
+}
+function parseProjectDotEnv(content) {
+  try {
+    const parsed = parsePortableDotEnv(content);
+    if (typeof nodeUtil.parseEnv === "function") {
+      const native = nodeUtil.parseEnv(content);
+      if (JSON.stringify(Object.entries(parsed).sort()) !== JSON.stringify(Object.entries(native).sort()))
+        throw new Error("ambiguous syntax");
+    }
+    return parsed;
+  } catch {
+    throw new UserError("Cannot parse project .env; contents omitted. / \u65E0\u6CD5\u89E3\u6790\u9879\u76EE .env\uFF0C\u5DF2\u9690\u85CF\u5185\u5BB9\u3002");
+  }
+}
+function parsePortableDotEnv(content) {
+  const values = /* @__PURE__ */ Object.create(null);
+  let remaining = content.replace(/\r\n?/g, "\n");
+  while (remaining.trim()) {
+    remaining = remaining.trimStart();
+    if (remaining.startsWith("#")) {
+      remaining = remaining.slice(remaining.indexOf("\n") < 0 ? remaining.length : remaining.indexOf("\n") + 1);
+      continue;
+    }
+    const assignment = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=[ \t]*/.exec(remaining);
+    if (!assignment) throw new Error("invalid assignment");
+    remaining = remaining.slice(assignment[0].length);
+    let value;
+    const delimiter = remaining[0];
+    if (["'", '"', "`"].includes(delimiter ?? "")) {
+      const end = remaining.indexOf(delimiter, 1);
+      if (end < 0) throw new Error("unterminated value");
+      value = remaining.slice(1, end);
+      if (delimiter === '"') value = value.replaceAll("\\n", "\n");
+      remaining = remaining.slice(end + 1);
+      const tail = remaining.split("\n", 1)[0];
+      if (tail.trim() && !tail.trimStart().startsWith("#")) throw new Error("trailing value");
+    } else {
+      value = remaining.split("\n", 1)[0].split("#", 1)[0].trim();
+    }
+    values[assignment[1]] = value;
+    const newline = remaining.indexOf("\n");
+    remaining = newline < 0 ? "" : remaining.slice(newline + 1);
+  }
+  return values;
+}
+function encodeAssignment(name, value) {
+  for (const quote of ["'", '"', "`"]) {
+    if (value.includes(quote) || value.includes("\0")) continue;
+    const assignment = `${name}=${quote}${value}${quote}
+`;
+    try {
+      if (parseProjectDotEnv(assignment)[name] === value) return assignment;
+    } catch {
+    }
+  }
+  throw new UserError(
+    "A Vault secret cannot be represented losslessly in .env. Supply an environment variable reference instead. / Vault \u5BC6\u94A5\u65E0\u6CD5\u65E0\u635F\u5199\u5165 .env\uFF0C\u8BF7\u6539\u7528\u73AF\u5883\u53D8\u91CF\u5F15\u7528\u3002"
+  );
+}
+async function assertUnchanged(root, source) {
+  const path = resolve(root, source.path);
+  const details = await lstat(path);
+  if (!details.isFile() || details.isSymbolicLink() || (details.mode & 511) !== source.mode || !Buffer.from(source.content).equals(await readFile(path))) {
+    throw new UserError("Vault source changed. Preview Build again. / Vault \u6E90\u6587\u4EF6\u5DF2\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u9884\u89C8\u6784\u5EFA\u3002");
+  }
+}
+async function writePrivateAtomic(path, content, mode, beforeRename) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { mode: 384, flag: "wx" });
+    await chmod(temporary, mode);
+    await beforeRename();
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+function redactVaultText(text, literals) {
+  let redacted = text;
+  for (const literal of [...new Set(literals)].sort((left, right) => right.length - left.length))
+    redacted = redacted.replaceAll(literal, "[redacted]");
+  return redacted;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function hasCode(error, code) {
+  return !!error && typeof error === "object" && "code" in error && error.code === code;
+}
+
+// src/internal/project-workspace/index.ts
+var PROJECT_METADATA_FILE = "project.json";
+var PROJECT_INTERNAL_DIRECTORY = ".openagentpack";
+var PROJECT_BUILD_FILE = ".openagentpack/build/agents.yaml";
+var PROJECT_BUILD_MANIFEST = ".openagentpack/build/manifest.json";
+var PROJECT_STATE_FILE = ".openagentpack/state.json";
+var FILE_AUTO_ASSOCIATION_IGNORE_FILE = ".openagentpack-ignore";
+var DIRECTORY_PROJECT_PROVIDER = "bailian";
+var DIRECTORY_PROJECT_PROVIDER_CONFIG = {
+  api_key: `\${DASHSCOPE_API_KEY}`,
+  base_url: `\${BAILIAN_BASE_URL}`
+};
+var DIRECTORY_RESOURCE_TYPES = ["environment", "vault", "memory_store", "file"];
+var DIRECTORY_RESOURCE_SPECS = {
+  environment: { section: "environments", directory: "environments", metadataFile: "environment.json" },
+  vault: { section: "vaults", directory: "vaults", metadataFile: "vault.json" },
+  memory_store: { section: "memory_stores", directory: "memory-stores", metadataFile: "memory-store.json" },
+  file: { section: "files", directory: "files", metadataFile: "file.json" }
+};
+var IGNORED_ROOT_NAMES = /* @__PURE__ */ new Set([
+  ".git",
+  ".openagentpack",
+  "agents.yaml",
+  "agents.state.json",
+  "node_modules",
+  "dist",
+  "build",
+  ".cache",
+  ".DS_Store"
+]);
+var IGNORED_SOURCE_NAMES = /* @__PURE__ */ new Set([".env"]);
+var DirectoryProjectMutationConflictError = class extends UserError {
+  status = 409;
+  constructor(message) {
+    super(message);
+    this.name = "DirectoryProjectMutationConflictError";
+  }
+};
+async function resolveDirectoryProjectRoot(input = ".") {
+  const root = resolve2(input);
+  const details = await stat(root).catch(() => null);
+  if (!details?.isDirectory()) throw new UserError(`Project directory does not exist: ${root}`);
+  if (!await pathExists(resolve2(root, PROJECT_METADATA_FILE))) {
+    let ancestor = dirname(root);
+    while (ancestor !== root) {
+      if (await pathExists(resolve2(ancestor, PROJECT_METADATA_FILE))) {
+        const quotedRoot = `'${ancestor.replaceAll("'", "'\\''")}'`;
+        throw new UserError(
+          `Not a project root: ${root} (${PROJECT_METADATA_FILE} is missing).
+Project root: ${ancestor}
+Run from the project root: cd ${quotedRoot}
+Or specify the project directory: --project ${quotedRoot}`
+        );
+      }
+      const parent = dirname(ancestor);
+      if (parent === ancestor) break;
+      ancestor = parent;
+    }
+  }
+  return root;
+}
+async function inspectDirectoryProject(projectDirectory = ".") {
+  const projectRoot = await resolveDirectoryProjectRoot(projectDirectory);
+  const sourceFiles = await scanProjectSource(projectRoot);
+  return inspectSourceFiles(projectRoot, sourceFiles);
+}
+async function inspectSourceFiles(projectRoot, sourceFiles, metadataOverrides) {
+  const projectRevision = hashFiles(sourceFiles);
+  const diagnostics = [];
+  const warnings = [];
+  let assembled = null;
+  try {
+    assembled = await assembleProject(projectRoot, sourceFiles, metadataOverrides);
+    diagnostics.push(...assembled.diagnostics);
+    warnings.push(...assembled.warnings);
+  } catch (error) {
+    diagnostics.push(toDiagnostic(error));
+  }
+  return {
+    project_root: projectRoot,
+    project_revision: projectRevision,
+    source_manifest_hash: projectRevision,
+    canonical_yaml: assembled?.canonicalYaml ?? "",
+    yaml_hash: hash(assembled?.canonicalYaml ?? ""),
+    loaded: assembled?.loaded ?? null,
+    diagnostics,
+    warnings,
+    organization_moves: assembled?.moves ?? [],
+    source_files: sourceFiles
+  };
+}
+async function validateDirectoryProject(projectDirectory = ".") {
+  return inspectDirectoryProject(projectDirectory);
+}
+async function resolveDirectoryProjectRuntime(projectDirectory = ".") {
+  const inspection = await inspectDirectoryProject(projectDirectory);
+  const blockingDiagnostic = inspection.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+  if (blockingDiagnostic) throw new UserError(blockingDiagnostic.message);
+  const rawConfig = parse(inspection.canonical_yaml);
+  return resolveProjectConfigFromObject(rawConfig, {
+    projectName: basename(inspection.project_root),
+    basePath: resolve2(inspection.project_root, ".openagentpack/build"),
+    resolveEnv: true,
+    environment: await readProjectEnvironment(inspection.project_root)
+  });
+}
+async function getProjectBuildStatus(projectDirectory, inspection) {
+  const projectRoot = await resolveDirectoryProjectRoot(projectDirectory);
+  const current = inspection ?? await inspectDirectoryProject(projectRoot);
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile2(resolve2(projectRoot, PROJECT_BUILD_MANIFEST), "utf8"));
+  } catch (error) {
+    if (isFsError(error, "ENOENT"))
+      return { exists: false, stale: true, manifest: null, reasons: ["Project has not been built."] };
+    return { exists: false, stale: true, manifest: null, reasons: ["Build manifest is unreadable."] };
+  }
+  const reasons = [];
+  if (manifest.project_revision !== current.project_revision)
+    reasons.push("Project source changed after the last Build.");
+  if (manifest.source_manifest_hash !== current.source_manifest_hash) reasons.push("Project source manifest is stale.");
+  const builtYaml = await readFile2(resolve2(projectRoot, PROJECT_BUILD_FILE), "utf8").catch(() => null);
+  if (builtYaml === null) reasons.push("Generated agents.yaml is missing.");
+  else if (hash(builtYaml) !== manifest.yaml_hash) reasons.push("Generated agents.yaml does not match its manifest.");
+  return { exists: true, stale: reasons.length > 0, manifest, reasons };
+}
+async function previewProjectBuild(projectDirectory = ".") {
+  const projectRoot = await resolveDirectoryProjectRoot(projectDirectory);
+  const sourceFiles = await scanProjectSource(projectRoot);
+  let migration;
+  let migrationError;
+  try {
+    migration = await planVaultSecretMigration(projectRoot, sourceFiles);
+  } catch (error) {
+    migrationError = toDiagnostic(error);
+  }
+  const inspection = await inspectSourceFiles(projectRoot, sourceFiles, migration?.overrides);
+  const literals = migration?.literals ?? [];
+  if (migrationError) {
+    inspection.diagnostics = [migrationError];
+    inspection.canonical_yaml = "# Vault migration could not be previewed safely.\n";
+  } else if (migration?.count) {
+    inspection.warnings.push({
+      severity: "warning",
+      code: "project.vault.secrets.externalized",
+      message: `${migration.count} Vault secret(s) will move to project .env; vault.json will use environment references. / ${migration.count} \u4E2A Vault \u5BC6\u94A5\u5C06\u79FB\u5165\u9879\u76EE .env\uFF0Cvault.json \u5C06\u6539\u7528\u73AF\u5883\u53D8\u91CF\u5F15\u7528\u3002`
+    });
+  }
+  inspection.loaded = null;
+  inspection.diagnostics = inspection.diagnostics.map((diagnostic) => ({
+    ...diagnostic,
+    message: redactVaultText(diagnostic.message, literals)
+  }));
+  inspection.warnings = inspection.warnings.map((diagnostic) => ({
+    ...diagnostic,
+    message: redactVaultText(diagnostic.message, literals)
+  }));
+  inspection.source_files = sourceFiles.map((file) => {
+    if (hasErrors(inspection.diagnostics) && file.path.endsWith("/vault.json"))
+      return { ...file, content: Buffer.from("[omitted]") };
+    const normalized = migration?.overrides.get(file.path);
+    if (normalized) return { ...file, content: Buffer.from(JSON.stringify(normalized, null, 2)) };
+    if (!literals.some((literal) => Buffer.from(file.content).includes(literal))) return file;
+    return { ...file, content: Buffer.from("[omitted: contains a Vault secret]") };
+  });
+  const buildStatus = await getProjectBuildStatus(inspection.project_root, inspection);
+  const beforeYaml = await readFile2(resolve2(inspection.project_root, PROJECT_BUILD_FILE), "utf8").catch(() => "");
+  const safeBefore = await inspectProjectSource(beforeYaml, resolve2(projectRoot, PROJECT_BUILD_FILE));
+  return {
+    ...inspection,
+    before_yaml: safeBefore.redacted_source,
+    after_yaml: inspection.canonical_yaml,
+    build_status: buildStatus,
+    can_build: !hasErrors(inspection.diagnostics)
+  };
+}
+async function commitProjectBuild(input) {
+  return withProjectMutation(input.projectRoot, "build", async () => {
+    const before = await previewProjectBuild(input.projectRoot);
+    if (before.project_revision !== input.baseRevision)
+      throw new UserError("Project source changed. Preview Build again.");
+    if (!before.can_build) throw new UserError("Project contains errors and cannot be built.");
+    const sourceFiles = await scanProjectSource(before.project_root);
+    if (hashFiles(sourceFiles) !== input.baseRevision)
+      throw new UserError("Project source changed. Preview Build again.");
+    const migration = await planVaultSecretMigration(before.project_root, sourceFiles);
+    const assembled = await assembleProject(before.project_root, sourceFiles, migration.overrides);
+    if (hasErrors(assembled.diagnostics)) throw new UserError("Project contains errors and cannot be built.");
+    await applyVaultSecretMigration(before.project_root, sourceFiles, migration);
+    await applyProjectAutoAssociations(before.project_root, assembled.autoAssociations);
+    for (const move of before.organization_moves) await applyOrganizationMove(before.project_root, move);
+    const after = await previewProjectBuild(before.project_root);
+    if (!after.can_build) throw new UserError("Organized project contains errors and cannot be built.");
+    const materialized = await inspectDirectoryProject(before.project_root);
+    if (materialized.project_revision !== after.project_revision || materialized.yaml_hash !== after.yaml_hash) {
+      throw new UserError("Project source changed during Build. Preview Build again.");
+    }
+    const manifest = {
+      schema_version: 1,
+      project_revision: after.project_revision,
+      source_manifest_hash: after.source_manifest_hash,
+      yaml_hash: after.yaml_hash,
+      built_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeTextAtomic(resolve2(after.project_root, PROJECT_BUILD_FILE), after.canonical_yaml, 384);
+    await writeTextAtomic(
+      resolve2(after.project_root, PROJECT_BUILD_MANIFEST),
+      `${JSON.stringify(manifest, null, 2)}
+`,
+      384
+    );
+    return { ...after, manifest };
+  });
+}
+async function readValidProjectBuild(projectDirectory = ".") {
+  const inspection = await inspectDirectoryProject(projectDirectory);
+  if (hasErrors(inspection.diagnostics)) throw new UserError("Project source is invalid. Run project validate.");
+  const status = await getProjectBuildStatus(inspection.project_root, inspection);
+  if (!status.exists || status.stale || !status.manifest) {
+    throw new UserError(
+      `Project Build is missing or stale. Run project build first. ${status.reasons.join(" ")}`.trim()
+    );
+  }
+  const buildPath = resolve2(inspection.project_root, PROJECT_BUILD_FILE);
+  const yaml = await readFile2(buildPath, "utf8");
+  return { inspection, manifest: status.manifest, buildPath, yaml };
+}
+async function planProjectPublish(projectDirectory = ".", options = {}) {
+  const build = await readValidProjectBuild(projectDirectory);
+  const loaded = await (options.resolveBuild ?? resolveProjectConfig)(build.buildPath, {
+    environment: await readProjectEnvironment(build.inspection.project_root)
+  });
+  const planned = await planProjectWithStateBackend(
+    {
+      projectName: basename(build.inspection.project_root),
+      config: loaded.config,
+      configPath: build.buildPath,
+      providers: loaded.config.providers,
+      stateBackend: new LocalFileStateBackend({
+        statePath: resolve2(build.inspection.project_root, PROJECT_STATE_FILE)
+      }),
+      stateScope: { projectId: basename(build.inspection.project_root) }
+    },
+    options
+  );
+  return {
+    project_root: build.inspection.project_root,
+    project_revision: build.inspection.project_revision,
+    build_manifest: build.manifest,
+    build_path: build.buildPath,
+    plan_fingerprint: projectPublishPlanFingerprint(planned),
+    planned
+  };
+}
+async function executeProjectPublish(input) {
+  const versionService = createDirectoryWorkspaceVersionService(input.projectRoot);
+  const initial = await readValidProjectBuild(input.projectRoot);
+  if (initial.inspection.project_revision !== input.expectedProjectRevision || initial.manifest.yaml_hash !== input.expectedYamlHash) {
+    throw new UserError("Project or Build changed. Plan Publish again.");
+  }
+  const frozenSnapshot = snapshotFromInspection(initial.inspection);
+  const preparedVersion = await versionService.prepareVersion(frozenSnapshot);
+  let versionCommitted = false;
+  try {
+    const checked = await readValidProjectBuild(input.projectRoot);
+    if (checked.inspection.project_revision !== input.expectedProjectRevision || checked.manifest.yaml_hash !== input.expectedYamlHash) {
+      throw new UserError("Project or Build changed while Publish was starting.");
+    }
+    const loaded = await (input.resolveBuild ?? resolveProjectConfig)(checked.buildPath, {
+      environment: await readProjectEnvironment(checked.inspection.project_root)
+    });
+    const run = await writeProjectRuntime(
+      {
+        projectName: basename(checked.inspection.project_root),
+        config: loaded.config,
+        configPath: checked.buildPath,
+        providers: loaded.config.providers,
+        stateBackend: new LocalFileStateBackend({
+          statePath: resolve2(checked.inspection.project_root, PROJECT_STATE_FILE)
+        }),
+        stateScope: { projectId: basename(checked.inspection.project_root) }
+      },
+      async (context) => {
+        const planned = await planProjectContext(context, {
+          provider: input.provider,
+          refresh: input.refresh,
+          onFeedback: input.onFeedback
+        });
+        if (projectPublishPlanFingerprint(planned) !== input.expectedPlanFingerprint) {
+          throw new UserError("Project, remote resources, or Publish plan changed. Plan Publish again.");
+        }
+        return {
+          planned,
+          execution: await executePlannedProject(planned, {
+            concurrency: input.concurrency,
+            policy: input.policy,
+            confirm: input.confirm,
+            onFeedback: input.onFeedback
+          })
+        };
+      }
+    );
+    const incomplete = run.execution?.results.some((result) => result.status !== "success") ?? false;
+    if (incomplete) throw new UserError("Publish incomplete: one or more remote actions did not succeed.");
+    const version = preparedVersion ? await versionService.commitPrepared(preparedVersion, "Publish project") : null;
+    versionCommitted = true;
+    const working = await inspectDirectoryProject(input.projectRoot);
+    return {
+      planned: run.planned,
+      execution: run.execution,
+      version: version ? { version_id: version.version_id, short_version: version.short_version, message: version.message } : null,
+      published_revision: frozenSnapshot.project_revision,
+      working_revision: working.project_revision,
+      working_tree_changed: working.project_revision !== frozenSnapshot.project_revision
+    };
+  } finally {
+    if (!versionCommitted) await versionService.releasePrepared(preparedVersion);
+  }
+}
+async function initializeDirectoryProject(input = {}) {
+  const projectRoot = resolve2(input.projectRoot ?? ".");
+  await mkdir(projectRoot, { recursive: true });
+  const initialized = await withProjectMutation(projectRoot, "init", async () => {
+    const projectPath = resolve2(projectRoot, PROJECT_METADATA_FILE);
+    if (await pathExists(projectPath)) throw new UserError(`Directory project already exists: ${projectPath}`);
+    const yamlPath = resolve2(projectRoot, "agents.yaml");
+    let converted = false;
+    let stateMigrated = false;
+    if (await pathExists(yamlPath)) {
+      await convertYamlProject(projectRoot, yamlPath);
+      converted = true;
+      const oldState = resolve2(projectRoot, "agents.state.json");
+      if (await pathExists(oldState)) {
+        await mkdir(dirname(resolve2(projectRoot, PROJECT_STATE_FILE)), { recursive: true });
+        await cp(oldState, resolve2(projectRoot, PROJECT_STATE_FILE), { force: false });
+        stateMigrated = true;
+      }
+    } else {
+      await scaffoldProject(projectRoot);
+    }
+    return {
+      project_root: projectRoot,
+      converted_from_yaml: converted,
+      state_migrated: stateMigrated,
+      baseline_version: null
+    };
+  });
+  const enabled = await createDirectoryWorkspaceVersionService(projectRoot).enable("Initialize project");
+  return { ...initialized, baseline_version: enabled.version?.version_id ?? enabled.versioning.head_version };
+}
+function createDirectoryWorkspaceVersionService(projectDirectory) {
+  const projectRoot = resolve2(projectDirectory);
+  return createDirectoryProjectVersionService({
+    projectRoot,
+    adapter: {
+      readSnapshot: async () => snapshotFromInspection(await inspectDirectoryProject(projectRoot)),
+      restoreSnapshot: async (snapshot, baseRevision) => restoreDirectorySnapshot(projectRoot, snapshot, baseRevision)
+    }
+  });
+}
+async function assertLegacyYamlNotShadowed(configFile) {
+  const configPath = resolve2(configFile);
+  if (basename(configPath) !== "agents.yaml") return;
+  if (await pathExists(resolve2(dirname(configPath), PROJECT_METADATA_FILE))) {
+    throw new UserError(
+      "This directory is managed as a directory project. Use `agents project build` and `agents project publish`."
+    );
+  }
+}
+async function assembleProject(projectRoot, sourceFiles, metadataOverrides) {
+  if (!sourceFiles.some((file) => file.path === PROJECT_METADATA_FILE)) {
+    throw new UserError(`Missing ${PROJECT_METADATA_FILE}. Run project init first.`);
+  }
+  const project = await readJsonObject(resolve2(projectRoot, PROJECT_METADATA_FILE));
+  if ("providers" in project || isRecord2(project.defaults) && "provider" in project.defaults) {
+    throw new UserError(
+      `project.json cannot declare providers or defaults.provider; directory projects use '${DIRECTORY_PROJECT_PROVIDER}' automatically.`
+    );
+  }
+  if ("defaults" in project && !isRecord2(project.defaults)) {
+    throw new UserError("project.json defaults must be an object.");
+  }
+  const directorySections = [
+    "agents",
+    "skills",
+    ...DIRECTORY_RESOURCE_TYPES.map((type) => DIRECTORY_RESOURCE_SPECS[type].section)
+  ];
+  const misplacedSections = directorySections.filter((section) => section in project);
+  if (misplacedSections.length > 0) {
+    throw new UserError(
+      `project.json cannot declare ${misplacedSections.join(", ")}; use agents/ and Agent-local or resources/ directories.`
+    );
+  }
+  const agents = {};
+  const agentSources = /* @__PURE__ */ new Map();
+  const autoAssociations = {
+    fileMoves: [],
+    jsonWrites: /* @__PURE__ */ new Map(),
+    warnings: []
+  };
+  const agentDirectories = await childDirectories(resolve2(projectRoot, "agents"));
+  for (const agentId of agentDirectories) {
+    const agentDirectory = resolve2(projectRoot, "agents", agentId);
+    const agentPath = resolve2(agentDirectory, "agent.json");
+    if (!await pathExists(agentPath)) continue;
+    const agentSource = await readJsonObject(agentPath);
+    agentSources.set(agentId, agentSource);
+    const agent = structuredClone(agentSource);
+    if ("id" in agent && agent.id !== agentId)
+      throw new UserError(`agents/${agentId}/agent.json: id cannot differ from its directory name.`);
+    delete agent.id;
+    if ("instructions" in agent)
+      throw new UserError(`agents/${agentId}/agent.json: instructions must be stored in instructions.md.`);
+    const instructionsPath = resolve2(agentDirectory, "instructions.md");
+    if (!await pathExists(instructionsPath)) throw new UserError(`agents/${agentId}/instructions.md is required.`);
+    agents[agentId] = {
+      ...agent,
+      instructions: buildRelativePath(`agents/${agentId}/instructions.md`)
+    };
+  }
+  const skills = await discoverSkills(projectRoot, agentDirectories, autoAssociations);
+  const skillById = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    if (skillById.has(skill.id)) throw new UserError(`Duplicate local skill id: ${skill.id}`);
+    skillById.set(skill.id, skill);
+    if (skill.ownerAgent) {
+      autoAssociateSkill(skill, projectRoot, agents, agentSources, autoAssociations);
+    }
+  }
+  const referenceCounts = countSkillReferences(agents, skillById);
+  const moves = [];
+  for (const skill of skills) {
+    if (!skill.rootSkill && (referenceCounts.get(skill.id)?.size ?? 0) > 1) {
+      moves.push({
+        resource_type: "skill",
+        resource_id: skill.id,
+        from: skill.relativeDirectory,
+        to: `skills/${skill.id}`,
+        reason: "shared"
+      });
+    }
+  }
+  const warnings = autoAssociations.warnings;
+  const skillDeclarations = {};
+  for (const skill of skills) {
+    const references = referenceCounts.get(skill.id)?.size ?? 0;
+    if (references === 0) {
+      warnings.push({
+        severity: "warning",
+        code: "project.skill.unreferenced",
+        message: `${skill.location}/skill.json: skill '${skill.id}' is not referenced and is excluded from Build.`
+      });
+      continue;
+    }
+    const finalDirectory = moves.find((move) => move.resource_type === "skill" && move.resource_id === skill.id)?.to ?? skill.relativeDirectory;
+    const declaration = { ...skill.metadata };
+    delete declaration.id;
+    delete declaration.source;
+    skillDeclarations[skill.id] = { ...declaration, source: buildRelativePath(finalDirectory) };
+  }
+  const resources = await discoverDirectoryResources(
+    projectRoot,
+    agentDirectories,
+    autoAssociations,
+    metadataOverrides
+  );
+  const resourceKeys = /* @__PURE__ */ new Set();
+  for (const resource of resources) {
+    const key = `${resource.type}:${resource.id}`;
+    if (resourceKeys.has(key)) throw new UserError(`Duplicate ${resource.type} id: ${resource.id}`);
+    resourceKeys.add(key);
+    autoAssociateDirectoryResource(resource, resources, projectRoot, agents, agentSources, autoAssociations);
+    if (resource.owner_agent && isDirectoryResourceShared(resource.type, resource.id, resource.owner_agent, agents, project)) {
+      const spec = DIRECTORY_RESOURCE_SPECS[resource.type];
+      moves.push({
+        resource_type: resource.type,
+        resource_id: resource.id,
+        from: resource.relative_directory,
+        to: `resources/${spec.directory}/${resource.id}`,
+        reason: "shared"
+      });
+    }
+  }
+  const rawConfig = {
+    ...project,
+    providers: { [DIRECTORY_PROJECT_PROVIDER]: DIRECTORY_PROJECT_PROVIDER_CONFIG },
+    defaults: { ...isRecord2(project.defaults) ? project.defaults : {}, provider: DIRECTORY_PROJECT_PROVIDER },
+    agents,
+    skills: skillDeclarations
+  };
+  for (const type of DIRECTORY_RESOURCE_TYPES) {
+    const declarations = {};
+    for (const resource of resources.filter((candidate) => candidate.type === type)) {
+      const finalDirectory = moves.find((move) => move.resource_type === type && move.resource_id === resource.id)?.to ?? resource.relative_directory;
+      declarations[resource.id] = directoryResourceDeclarationForBuild(projectRoot, resource, finalDirectory);
+    }
+    if (Object.keys(declarations).length > 0) rawConfig[DIRECTORY_RESOURCE_SPECS[type].section] = declarations;
+  }
+  const loaded = await resolveProjectConfigFromObject(rawConfig, {
+    projectName: basename(projectRoot),
+    basePath: resolve2(projectRoot, ".openagentpack/build")
+  });
+  const diagnostics = validateProjectConfig(loaded.config);
+  const canonicalYaml = stringify(sortObjectDeep(rawConfig), { lineWidth: 0, sortMapEntries: true });
+  return { canonicalYaml, loaded, diagnostics, warnings, moves, autoAssociations };
+}
+function directoryResourceDeclarationForBuild(projectRoot, resource, finalDirectory) {
+  const declaration = structuredClone(resource.metadata);
+  delete declaration.id;
+  if (resource.type !== "file" || typeof declaration.source !== "string" || /^https?:\/\//i.test(declaration.source)) {
+    return declaration;
+  }
+  if (isAbsolute(declaration.source)) {
+    throw new UserError(`${resource.relative_directory}/file.json: source must be relative to the File directory.`);
+  }
+  const sourcePath = resolve2(resource.directory, declaration.source);
+  if (!isPathInside(projectRoot, sourcePath)) {
+    throw new UserError(`${resource.relative_directory}/file.json: source escapes the project root.`);
+  }
+  const sourceRelativeToResource = relative(resource.directory, sourcePath);
+  const finalSourcePath = resolve2(projectRoot, finalDirectory, sourceRelativeToResource);
+  const projectRelative = relative(projectRoot, finalSourcePath).split(sep).join("/");
+  declaration.source = buildRelativePath(projectRelative);
+  return declaration;
+}
+async function locateDirectoryProjectResource(projectDirectory, type, id) {
+  const projectRoot = await resolveDirectoryProjectRoot(projectDirectory);
+  const resources = await discoverDirectoryResources(
+    projectRoot,
+    await childDirectories(resolve2(projectRoot, "agents"))
+  );
+  const matches = resources.filter((resource) => resource.type === type && resource.id === id);
+  if (matches.length > 1) throw new UserError(`Duplicate ${type} id: ${id}`);
+  const match = matches[0];
+  if (!match) return null;
+  const { metadata: _metadata, ...source } = match;
+  return source;
+}
+async function discoverDirectoryResources(projectRoot, agentDirectories, autoAssociations = createProjectAutoAssociationPlan(), metadataOverrides) {
+  const locations = [];
+  for (const type of DIRECTORY_RESOURCE_TYPES) {
+    const spec = DIRECTORY_RESOURCE_SPECS[type];
+    for (const resourceId of await resourceDirectories(resolve2(projectRoot, "resources", spec.directory))) {
+      locations.push({
+        type,
+        id: resourceId,
+        directory: resolve2(projectRoot, "resources", spec.directory, resourceId),
+        relativeDirectory: `resources/${spec.directory}/${resourceId}`
+      });
+    }
+    for (const agentId of agentDirectories) {
+      for (const resourceId of await resourceDirectories(resolve2(projectRoot, "agents", agentId, spec.directory))) {
+        locations.push({
+          type,
+          id: resourceId,
+          directory: resolve2(projectRoot, "agents", agentId, spec.directory, resourceId),
+          relativeDirectory: `agents/${agentId}/${spec.directory}/${resourceId}`,
+          ownerAgent: agentId
+        });
+      }
+    }
+  }
+  const resources = [];
+  for (const location of locations) {
+    const metadataFile = DIRECTORY_RESOURCE_SPECS[location.type].metadataFile;
+    const metadataPath = resolve2(location.directory, metadataFile);
+    let metadata;
+    let inferred = false;
+    if (await pathExists(metadataPath)) {
+      metadata = metadataOverrides?.get(`${location.relativeDirectory}/${metadataFile}`) ?? await readJsonObject(metadataPath);
+    } else if (location.type === "file" && location.ownerAgent) {
+      if (await pathExists(resolve2(location.directory, FILE_AUTO_ASSOCIATION_IGNORE_FILE))) continue;
+      const fileNames = await directProjectFiles(location.directory);
+      if (fileNames.length === 0) continue;
+      if (fileNames.length > 1) {
+        throw new UserError(
+          `${location.relativeDirectory}/file.json is required when a File directory contains multiple files.`
+        );
+      }
+      const [fileName] = fileNames;
+      metadata = { id: location.id, name: fileName, source: `./${fileName}` };
+      inferred = true;
+      planJsonWrite(autoAssociations, projectRoot, metadataPath, metadata);
+      autoAssociations.warnings.push({
+        severity: "warning",
+        code: "project.file.metadata.inferred",
+        message: `${location.relativeDirectory}/${fileName} will become File '${location.id}'.`
+      });
+    } else {
+      if (location.type === "file") continue;
+      throw new UserError(`${location.relativeDirectory}/${metadataFile} is required.`);
+    }
+    if (metadata.id !== location.id) {
+      throw new UserError(`${location.relativeDirectory}/${metadataFile}: id must be '${location.id}'.`);
+    }
+    resources.push({
+      type: location.type,
+      id: location.id,
+      path: metadataPath,
+      directory: location.directory,
+      relative_directory: location.relativeDirectory,
+      ...location.ownerAgent ? { owner_agent: location.ownerAgent } : {},
+      metadata,
+      ...inferred ? { inferred: true } : {}
+    });
+  }
+  for (const agentId of agentDirectories) {
+    const filesDirectory = resolve2(projectRoot, "agents", agentId, DIRECTORY_RESOURCE_SPECS.file.directory);
+    for (const fileName of await directProjectFiles(filesDirectory)) {
+      const resourceId = inferFileResourceId(fileName);
+      const relativeDirectory = `agents/${agentId}/files/${resourceId}`;
+      const destinationDirectory = resolve2(projectRoot, relativeDirectory);
+      const metadata = { id: resourceId, name: fileName, source: `./${fileName}` };
+      resources.push({
+        type: "file",
+        id: resourceId,
+        path: resolve2(destinationDirectory, "file.json"),
+        directory: filesDirectory,
+        relative_directory: relativeDirectory,
+        owner_agent: agentId,
+        metadata,
+        inferred: true
+      });
+      autoAssociations.fileMoves.push({
+        from: `agents/${agentId}/files/${fileName}`,
+        to: `${relativeDirectory}/${fileName}`
+      });
+      planJsonWrite(autoAssociations, projectRoot, resolve2(destinationDirectory, "file.json"), metadata);
+      autoAssociations.warnings.push({
+        severity: "warning",
+        code: "project.file.discovered",
+        message: `agents/${agentId}/files/${fileName} will become File '${resourceId}' and be linked to Agent '${agentId}'.`
+      });
+    }
+  }
+  return resources;
+}
+function isDirectoryResourceShared(type, id, ownerAgent, agents, project) {
+  for (const [agentId, agent] of Object.entries(agents)) {
+    if (agentId !== ownerAgent && agentReferencesDirectoryResource(agent, type, id)) return true;
+  }
+  const deployments = isRecord2(project.deployments) ? project.deployments : {};
+  for (const deployment of Object.values(deployments)) {
+    if (isRecord2(deployment) && deploymentReferencesDirectoryResource(deployment, type, id)) return true;
+  }
+  return false;
+}
+function agentReferencesDirectoryResource(agent, type, id) {
+  if (type === "environment") return agent.environment === id;
+  if (type === "vault") return agent.vault === id;
+  if (type === "memory_store") return Array.isArray(agent.memory_stores) && agent.memory_stores.includes(id);
+  if (type === "file") {
+    return Array.isArray(agent.files) && agent.files.some((file) => file === id || isRecord2(file) && file.file === id);
+  }
+  return false;
+}
+function deploymentReferencesDirectoryResource(deployment, type, id) {
+  if (type === "environment") return deployment.environment === id;
+  if (type === "vault") return Array.isArray(deployment.vaults) && deployment.vaults.includes(id);
+  if (type !== "memory_store") return false;
+  if (Array.isArray(deployment.memory_stores) && deployment.memory_stores.includes(id)) return true;
+  return Array.isArray(deployment.resources) && deployment.resources.some(
+    (resource) => isRecord2(resource) && resource.type === "memory_store" && resource.memory_store === id
+  );
+}
+async function discoverSkills(projectRoot, agentDirectories, autoAssociations) {
+  const locations = [];
+  for (const skillDirectory of await resourceDirectories(resolve2(projectRoot, "skills"))) {
+    locations.push({
+      path: resolve2(projectRoot, "skills", skillDirectory),
+      relativeDirectory: `skills/${skillDirectory}`,
+      rootSkill: true
+    });
+  }
+  for (const agentId of agentDirectories) {
+    for (const skillDirectory of await resourceDirectories(resolve2(projectRoot, "agents", agentId, "skills"))) {
+      locations.push({
+        path: resolve2(projectRoot, "agents", agentId, "skills", skillDirectory),
+        relativeDirectory: `agents/${agentId}/skills/${skillDirectory}`,
+        rootSkill: false,
+        ownerAgent: agentId
+      });
+    }
+  }
+  const result = [];
+  for (const location of locations) {
+    const metadataPath = resolve2(location.path, "skill.json");
+    let metadata;
+    let inferred = false;
+    if (await pathExists(metadataPath)) {
+      metadata = await readJsonObject(metadataPath);
+    } else if (location.ownerAgent && await pathExists(resolve2(location.path, "SKILL.md"))) {
+      const skillId = basename(location.path);
+      metadata = { id: skillId };
+      inferred = true;
+      planJsonWrite(autoAssociations, projectRoot, metadataPath, metadata);
+      autoAssociations.warnings.push({
+        severity: "warning",
+        code: "project.skill.metadata.inferred",
+        message: `${location.relativeDirectory}/skill.json will be created for Skill '${skillId}'.`
+      });
+    } else {
+      continue;
+    }
+    if (typeof metadata.id !== "string" || !metadata.id.trim())
+      throw new UserError(`${relative(projectRoot, metadataPath)}: id is required.`);
+    if (!await pathExists(resolve2(location.path, "SKILL.md")))
+      throw new UserError(`${location.relativeDirectory}/SKILL.md is required.`);
+    result.push({
+      id: metadata.id,
+      metadata,
+      location: location.relativeDirectory,
+      relativeDirectory: location.relativeDirectory,
+      rootSkill: location.rootSkill,
+      ...location.ownerAgent ? { ownerAgent: location.ownerAgent } : {},
+      ...inferred ? { inferred: true } : {}
+    });
+  }
+  return result;
+}
+function autoAssociateSkill(skill, projectRoot, agents, agentSources, autoAssociations) {
+  const ownerAgent = skill.ownerAgent;
+  if (!ownerAgent) return;
+  const agent = agents[ownerAgent];
+  const agentSource = agentSources.get(ownerAgent);
+  if (!agent || !agentSource) return;
+  if (agent.skills !== void 0 && !Array.isArray(agent.skills)) return;
+  const references = Array.isArray(agent.skills) ? agent.skills : [];
+  if (references.some((reference) => skillReferenceId(reference) === skill.id)) return;
+  const nextReferences = [...references, skill.id];
+  agent.skills = nextReferences;
+  agentSource.skills = structuredClone(nextReferences);
+  planJsonWrite(autoAssociations, projectRoot, resolve2(projectRoot, "agents", ownerAgent, "agent.json"), agentSource);
+  autoAssociations.warnings.push({
+    severity: "warning",
+    code: "project.skill.agent_link.inferred",
+    message: `Skill '${skill.id}' will be added to agents/${ownerAgent}/agent.json.`
+  });
+}
+function autoAssociateDirectoryResource(resource, resources, projectRoot, agents, agentSources, autoAssociations) {
+  if (resource.type === "file") {
+    autoAssociateFile(resource, projectRoot, agents, agentSources, autoAssociations);
+    return;
+  }
+  const ownerAgent = resource.owner_agent;
+  if (!ownerAgent) return;
+  const agent = agents[ownerAgent];
+  const agentSource = agentSources.get(ownerAgent);
+  if (!agent || !agentSource) return;
+  const agentPath = `agents/${ownerAgent}/agent.json`;
+  if (resource.type === "memory_store") {
+    if (agent.memory_stores !== void 0 && !Array.isArray(agent.memory_stores)) return;
+    const references = Array.isArray(agent.memory_stores) ? agent.memory_stores : [];
+    if (references.includes(resource.id)) return;
+    agent.memory_stores = [...references, resource.id];
+    agentSource.memory_stores = structuredClone(agent.memory_stores);
+  } else {
+    if (agent[resource.type] !== void 0) return;
+    const candidates = resources.filter(
+      (candidate) => candidate.owner_agent === ownerAgent && candidate.type === resource.type
+    );
+    if (candidates.length > 1) {
+      throw new UserError(
+        `${agentPath}: multiple local ${resource.type} resources (${candidates.map((candidate) => candidate.id).join(", ")}). Set '${resource.type}' explicitly to choose one.`
+      );
+    }
+    agent[resource.type] = resource.id;
+    agentSource[resource.type] = resource.id;
+  }
+  planJsonWrite(autoAssociations, projectRoot, resolve2(projectRoot, agentPath), agentSource);
+  autoAssociations.warnings.push({
+    severity: "warning",
+    code: `project.${resource.type}.agent_link.inferred`,
+    message: `${resource.type} '${resource.id}' will be added to ${agentPath}.`
+  });
+}
+function autoAssociateFile(resource, projectRoot, agents, agentSources, autoAssociations) {
+  const ownerAgent = resource.owner_agent;
+  if (!ownerAgent) return;
+  const agent = agents[ownerAgent];
+  const agentSource = agentSources.get(ownerAgent);
+  if (!agent || !agentSource) return;
+  if (agent.files !== void 0 && !Array.isArray(agent.files)) return;
+  const references = Array.isArray(agent.files) ? agent.files : [];
+  if (references.some((reference) => reference === resource.id || isRecord2(reference) && reference.file === resource.id))
+    return;
+  const mountPath = defaultFileMountPath(resource);
+  const nextReferences = [...references, { file: resource.id, mount_path: mountPath }];
+  agent.files = nextReferences;
+  agentSource.files = structuredClone(nextReferences);
+  planJsonWrite(autoAssociations, projectRoot, resolve2(projectRoot, "agents", ownerAgent, "agent.json"), agentSource);
+  autoAssociations.warnings.push({
+    severity: "warning",
+    code: "project.file.agent_link.inferred",
+    message: `File '${resource.id}' will be mounted at '${mountPath}' in agents/${ownerAgent}/agent.json.`
+  });
+}
+function skillReferenceId(reference) {
+  if (typeof reference === "string") return reference;
+  return isRecord2(reference) && typeof reference.skill_id === "string" ? reference.skill_id : null;
+}
+function defaultFileMountPath(resource) {
+  const source = resource.metadata.source;
+  let fileName = resource.id;
+  if (typeof source === "string" && /^https?:\/\//i.test(source)) {
+    try {
+      fileName = basename(new URL(source).pathname) || resource.id;
+    } catch {
+      fileName = resource.id;
+    }
+  } else if (typeof source === "string") {
+    fileName = basename(source) || resource.id;
+  }
+  return `/mnt/${fileName}`;
+}
+function countSkillReferences(agents, skills) {
+  const result = /* @__PURE__ */ new Map();
+  for (const [agentId, agent] of Object.entries(agents)) {
+    const refs = Array.isArray(agent.skills) ? agent.skills : [];
+    for (const ref of refs) {
+      const id = skillReferenceId(ref);
+      if (!id || !skills.has(id)) continue;
+      const agentsForSkill = result.get(id) ?? /* @__PURE__ */ new Set();
+      agentsForSkill.add(agentId);
+      result.set(id, agentsForSkill);
+    }
+  }
+  return result;
+}
+async function scanProjectSource(projectRoot) {
+  const rootReal = await realpath(projectRoot);
+  const files = [];
+  async function walk(directory, relativeDirectory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (IGNORED_SOURCE_NAMES.has(entry.name) || !relativeDirectory && IGNORED_ROOT_NAMES.has(entry.name)) continue;
+      const absolute = resolve2(directory, entry.name);
+      const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      const details = await lstat2(absolute);
+      if (details.isSymbolicLink()) {
+        const target = await realpath(absolute);
+        if (target !== rootReal && !target.startsWith(`${rootReal}${sep}`))
+          throw new UserError(`${relativePath}: symlink escapes the project root.`);
+        throw new UserError(`${relativePath}: symlinks are not supported in directory projects.`);
+      }
+      if (details.isDirectory()) await walk(absolute, relativePath);
+      else if (details.isFile())
+        files.push({
+          path: relativePath,
+          mode: details.mode & 511,
+          content: new Uint8Array(await readFile2(absolute))
+        });
+    }
+  }
+  await walk(projectRoot, "");
+  return files;
+}
+async function restoreDirectorySnapshot(projectRoot, snapshot, baseRevision) {
+  const current = await inspectDirectoryProject(projectRoot);
+  if (current.project_revision !== baseRevision) throw new UserError("Project source changed before Restore.");
+  const restoreRoot = resolve2(projectRoot, PROJECT_INTERNAL_DIRECTORY, `restore-${randomUUID2()}`);
+  const historicalRoot = resolve2(restoreRoot, "historical");
+  const backupRoot = resolve2(restoreRoot, "backup");
+  const restoredPaths = [];
+  let mutationStarted = false;
+  await mkdir(restoreRoot, { recursive: true });
+  try {
+    await stageRestoreFiles(historicalRoot, snapshot.files, true);
+    await stageRestoreFiles(backupRoot, current.source_files, false);
+    const checked = await inspectDirectoryProject(projectRoot);
+    if (checked.project_revision !== baseRevision) throw new UserError("Project source changed before Restore.");
+    mutationStarted = true;
+    const currentPaths = new Set(current.source_files.map((file) => file.path));
+    for (const path of currentPaths) await rm2(resolve2(projectRoot, path), { force: true });
+    await removeEmptyProjectDirectories(projectRoot, currentPaths);
+    for (const file of snapshot.files) {
+      const source = resolve2(historicalRoot, file.path);
+      const destination = resolve2(projectRoot, file.path);
+      await removeEmptyRestoreDestination(destination, file.path);
+      await mkdir(dirname(destination), { recursive: true });
+      await rename2(source, destination);
+      restoredPaths.push(file.path);
+      await chmod2(destination, file.mode);
+    }
+    await rm2(resolve2(projectRoot, ".openagentpack/build"), { recursive: true, force: true });
+  } catch (restoreError) {
+    if (mutationStarted) {
+      try {
+        await rollbackDirectoryRestore(projectRoot, backupRoot, current.source_files, restoredPaths);
+      } catch (rollbackError) {
+        throw new UserError(
+          `Restore failed and rollback was incomplete. Restore error: ${errorMessage(restoreError)}. Rollback error: ${errorMessage(rollbackError)}.`
+        );
+      }
+    }
+    throw restoreError;
+  } finally {
+    await rm2(restoreRoot, { recursive: true, force: true });
+  }
+}
+async function stageRestoreFiles(stagingRoot, files, rejectIgnoredFiles) {
+  for (const file of files) {
+    assertSafeRelative(file.path);
+    if (rejectIgnoredFiles && file.path.split("/").some((part) => IGNORED_SOURCE_NAMES.has(part))) {
+      throw new UserError(`Project snapshot contains an ignored source file: ${file.path}`);
+    }
+    const destination = resolve2(stagingRoot, file.path);
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile2(destination, file.content, { mode: file.mode });
+  }
+}
+async function rollbackDirectoryRestore(projectRoot, backupRoot, currentFiles, restoredPaths) {
+  for (const path of restoredPaths) await rm2(resolve2(projectRoot, path), { force: true });
+  await removeEmptyProjectDirectories(projectRoot, restoredPaths);
+  for (const file of currentFiles) {
+    const source = resolve2(backupRoot, file.path);
+    const destination = resolve2(projectRoot, file.path);
+    await clearRollbackDestination(destination);
+    await mkdir(dirname(destination), { recursive: true });
+    await rename2(source, destination);
+    await chmod2(destination, file.mode);
+  }
+}
+async function removeEmptyRestoreDestination(destination, relativePath) {
+  let details;
+  try {
+    details = await lstat2(destination);
+  } catch (error) {
+    if (isFsError(error, "ENOENT")) return;
+    throw error;
+  }
+  if (!details.isDirectory()) {
+    throw new UserError(`Cannot restore ${relativePath}: destination is occupied by an unversioned file.`);
+  }
+  try {
+    await rmdir(destination);
+  } catch (error) {
+    if (isFsError(error, "ENOTEMPTY") || isFsError(error, "EEXIST")) {
+      throw new UserError(`Cannot restore ${relativePath}: destination directory contains unversioned files.`);
+    }
+    throw error;
+  }
+}
+async function clearRollbackDestination(destination) {
+  let details;
+  try {
+    details = await lstat2(destination);
+  } catch (error) {
+    if (isFsError(error, "ENOENT")) return;
+    throw error;
+  }
+  if (details.isDirectory()) await rmdir(destination);
+  else await rm2(destination, { force: true });
+}
+async function removeEmptyProjectDirectories(projectRoot, paths) {
+  const directories = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    let directory = dirname(path);
+    while (directory !== ".") {
+      directories.add(directory);
+      directory = dirname(directory);
+    }
+  }
+  for (const directory of [...directories].sort((left, right) => right.split("/").length - left.split("/").length)) {
+    try {
+      await rmdir(resolve2(projectRoot, directory));
+    } catch (error) {
+      if (!isFsError(error, "ENOENT") && !isFsError(error, "ENOTEMPTY") && !isFsError(error, "EEXIST")) throw error;
+    }
+  }
+}
+function snapshotFromInspection(inspection) {
+  return {
+    project_revision: inspection.project_revision,
+    canonical_yaml: inspection.canonical_yaml,
+    files: inspection.source_files.map((file) => ({ ...file }))
+  };
+}
+async function applyProjectAutoAssociations(projectRoot, autoAssociations) {
+  for (const move of autoAssociations.fileMoves) {
+    const source = resolve2(projectRoot, move.from);
+    const destination = resolve2(projectRoot, move.to);
+    if (await pathExists(destination)) {
+      throw new UserError(`Cannot organize discovered File: ${move.to} already exists.`);
+    }
+    await mkdir(dirname(destination), { recursive: true });
+    await rename2(source, destination);
+  }
+  for (const [relativePath, value] of autoAssociations.jsonWrites) {
+    const destination = resolve2(projectRoot, relativePath);
+    const mode = await stat(destination).then((details) => details.mode & 511).catch((error) => {
+      if (isFsError(error, "ENOENT")) return 420;
+      throw error;
+    });
+    await writeTextAtomic(destination, `${JSON.stringify(value, null, 2)}
+`, mode);
+  }
+}
+async function applyOrganizationMove(projectRoot, move) {
+  const source = resolve2(projectRoot, move.from);
+  const destination = resolve2(projectRoot, move.to);
+  if (await pathExists(destination))
+    throw new UserError(`Cannot move shared ${move.resource_type} '${move.resource_id}': ${move.to} already exists.`);
+  await mkdir(dirname(destination), { recursive: true });
+  await rename2(source, destination);
+}
+async function scaffoldProject(projectRoot) {
+  const files = directoryProjectScaffold();
+  await scanProjectSource(projectRoot);
+  for (const path of Object.keys(files)) {
+    const existing = await lstat2(resolve2(projectRoot, path)).catch((error) => {
+      if (isFsError(error, "ENOENT")) return null;
+      throw error;
+    });
+    if (existing)
+      throw new UserError(`Cannot initialize project: ${path} already exists. / \u521D\u59CB\u5316\u88AB\u963B\u6B62\uFF1A\u6587\u4EF6\u5DF2\u5B58\u5728\u3002`);
+  }
+  for (const [path, content] of Object.entries(files)) await writeTextAtomic(resolve2(projectRoot, path), content);
+}
+async function convertYamlProject(projectRoot, yamlPath) {
+  const source = await readFile2(yamlPath, "utf8");
+  const inspection = await inspectProjectSource(source, yamlPath);
+  const blockingDiagnostic = inspection.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+  if (blockingDiagnostic) throw new UserError(blockingDiagnostic.message);
+  const raw = parse(source);
+  if (!isRecord2(raw)) throw new UserError("agents.yaml must contain an object.");
+  const configuredProviders = isRecord2(raw.providers) ? Object.keys(raw.providers) : [];
+  const defaultProvider = isRecord2(raw.defaults) && typeof raw.defaults.provider === "string" ? raw.defaults.provider : null;
+  const unsupportedProviders = [
+    .../* @__PURE__ */ new Set([...configuredProviders, ...defaultProvider ? [defaultProvider] : []])
+  ].filter((provider) => provider !== DIRECTORY_PROJECT_PROVIDER);
+  if (unsupportedProviders.length > 0) {
+    throw new UserError(
+      `Directory projects use '${DIRECTORY_PROJECT_PROVIDER}' automatically and cannot convert providers: ${unsupportedProviders.join(", ")}.`
+    );
+  }
+  const agents = isRecord2(raw.agents) ? raw.agents : {};
+  const skills = isRecord2(raw.skills) ? raw.skills : {};
+  const directoryResources = Object.fromEntries(
+    DIRECTORY_RESOURCE_TYPES.map((type) => {
+      const section = DIRECTORY_RESOURCE_SPECS[type].section;
+      return [type, isRecord2(raw[section]) ? raw[section] : {}];
+    })
+  );
+  const project = { ...raw };
+  delete project.providers;
+  if (isRecord2(project.defaults)) {
+    const defaults = { ...project.defaults };
+    delete defaults.provider;
+    if (Object.keys(defaults).length > 0) project.defaults = defaults;
+    else delete project.defaults;
+  }
+  delete project.agents;
+  delete project.skills;
+  for (const type of DIRECTORY_RESOURCE_TYPES) delete project[DIRECTORY_RESOURCE_SPECS[type].section];
+  await writeTextAtomic(resolve2(projectRoot, PROJECT_METADATA_FILE), `${JSON.stringify(project, null, 2)}
+`);
+  const references = /* @__PURE__ */ new Map();
+  for (const [agentId, value] of Object.entries(agents)) {
+    if (!isRecord2(value)) throw new UserError(`agents.${agentId} must be an object.`);
+    const agent = { ...value };
+    const instructions = await materializeText(projectRoot, agent.instructions, "You are a helpful assistant.\n");
+    delete agent.instructions;
+    for (const ref of Array.isArray(agent.skills) ? agent.skills : []) {
+      const skillId = typeof ref === "string" ? ref : isRecord2(ref) && typeof ref.skill_id === "string" ? ref.skill_id : null;
+      if (!skillId) continue;
+      const set = references.get(skillId) ?? /* @__PURE__ */ new Set();
+      set.add(agentId);
+      references.set(skillId, set);
+    }
+    const directory = resolve2(projectRoot, "agents", agentId);
+    await mkdir(directory, { recursive: true });
+    await writeTextAtomic(resolve2(directory, "agent.json"), `${JSON.stringify(agent, null, 2)}
+`);
+    await writeTextAtomic(resolve2(directory, "instructions.md"), instructions);
+  }
+  for (const [skillId, value] of Object.entries(skills)) {
+    if (!isRecord2(value)) throw new UserError(`skills.${skillId} must be an object.`);
+    const owners = references.get(skillId) ?? /* @__PURE__ */ new Set();
+    const relativeDirectory = owners.size === 1 ? `agents/${[...owners][0]}/skills/${skillId}` : `skills/${skillId}`;
+    const destination = resolve2(projectRoot, relativeDirectory);
+    await mkdir(destination, { recursive: true });
+    const metadata = { id: skillId, ...value };
+    delete metadata.source;
+    await writeTextAtomic(resolve2(destination, "skill.json"), `${JSON.stringify(metadata, null, 2)}
+`);
+    await materializeSkillSource(projectRoot, value.source, destination);
+  }
+  for (const type of DIRECTORY_RESOURCE_TYPES) {
+    const spec = DIRECTORY_RESOURCE_SPECS[type];
+    for (const [resourceId, value] of Object.entries(directoryResources[type])) {
+      if (!isRecord2(value)) throw new UserError(`${spec.section}.${resourceId} must be an object.`);
+      const ownerAgent = convertedResourceOwner(type, resourceId, agents, project);
+      const relativeDirectory = ownerAgent ? `agents/${ownerAgent}/${spec.directory}/${resourceId}` : `resources/${spec.directory}/${resourceId}`;
+      const destination = resolve2(projectRoot, relativeDirectory);
+      await mkdir(destination, { recursive: true });
+      const metadata = { id: resourceId, ...value };
+      if (type === "file") await materializeFileSource(projectRoot, metadata, destination);
+      await writeTextAtomic(resolve2(destination, spec.metadataFile), `${JSON.stringify(metadata, null, 2)}
+`);
+    }
+  }
+}
+function convertedResourceOwner(type, id, agents, project) {
+  const owners = Object.entries(agents).filter(([, agent]) => isRecord2(agent) && agentReferencesDirectoryResource(agent, type, id)).map(([agentId]) => agentId);
+  if (owners.length !== 1) return void 0;
+  const deployments = isRecord2(project.deployments) ? project.deployments : {};
+  if (Object.values(deployments).some(
+    (deployment) => isRecord2(deployment) && deploymentReferencesDirectoryResource(deployment, type, id)
+  )) {
+    return void 0;
+  }
+  return owners[0];
+}
+async function materializeText(projectRoot, value, fallback) {
+  if (typeof value !== "string") return fallback;
+  if (value.startsWith("./") || value.startsWith("../") || isAbsolute(value)) {
+    return readFile2(await resolveProjectOwnedSource(projectRoot, value, "Agent instructions"), "utf8");
+  }
+  return value.endsWith("\n") ? value : `${value}
+`;
+}
+async function materializeSkillSource(projectRoot, source, destination) {
+  if (typeof source !== "string" || /^https?:\/\//i.test(source)) {
+    await writeTextAtomic(resolve2(destination, "SKILL.md"), "# Skill\n");
+    return;
+  }
+  const sourcePath = await resolveProjectOwnedSource(projectRoot, source, "Skill source");
+  const details = await stat(sourcePath);
+  if (details.isDirectory()) {
+    if (sourcePath === destination) return;
+    for (const entry of await readdir(sourcePath)) {
+      if (entry === "skill.json") continue;
+      await cp(resolve2(sourcePath, entry), resolve2(destination, entry), { recursive: true, errorOnExist: true });
+    }
+  } else {
+    await cp(sourcePath, resolve2(destination, "SKILL.md"), { errorOnExist: true });
+  }
+}
+async function materializeFileSource(projectRoot, metadata, destination) {
+  const source = metadata.source;
+  if (typeof source !== "string" || /^https?:\/\//i.test(source)) return;
+  const sourcePath = await resolveProjectOwnedSource(projectRoot, source, "File source");
+  const details = await stat(sourcePath);
+  if (!details.isFile()) throw new UserError("File source must reference a file.");
+  const originalName = basename(sourcePath);
+  const fileName = originalName === "file.json" ? "content-file.json" : originalName;
+  const destinationPath = resolve2(destination, fileName);
+  if (sourcePath !== destinationPath) await cp(sourcePath, destinationPath, { errorOnExist: true });
+  metadata.source = `./${fileName}`;
+}
+async function resolveProjectOwnedSource(projectRoot, source, label) {
+  if (isAbsolute(source)) throw new UserError(`${label} must be a relative path inside the project root.`);
+  const normalizedRoot = resolve2(projectRoot);
+  const sourcePath = resolve2(normalizedRoot, source);
+  if (!isPathInside(normalizedRoot, sourcePath)) {
+    throw new UserError(`${label} escapes the project root.`);
+  }
+  const [rootRealPath, sourceRealPath] = await Promise.all([realpath(normalizedRoot), realpath(sourcePath)]);
+  if (!isPathInside(rootRealPath, sourceRealPath)) {
+    throw new UserError(`${label} resolves outside the project root.`);
+  }
+  return sourcePath;
+}
+function isPathInside(root, candidate) {
+  const relativePath = relative(root, candidate);
+  return Boolean(relativePath) && relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+async function childDirectories(path) {
+  try {
+    return (await readdir(path, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch (error) {
+    if (isFsError(error, "ENOENT")) return [];
+    throw error;
+  }
+}
+async function resourceDirectories(path) {
+  return (await childDirectories(path)).filter((directory) => directory !== RESOURCE_EXAMPLES_DIRECTORY);
+}
+function createProjectAutoAssociationPlan() {
+  return { fileMoves: [], jsonWrites: /* @__PURE__ */ new Map(), warnings: [] };
+}
+function planJsonWrite(autoAssociations, projectRoot, path, value) {
+  if (!isPathInside(projectRoot, path))
+    throw new UserError(`Cannot write inferred project metadata outside ${projectRoot}.`);
+  autoAssociations.jsonWrites.set(relative(projectRoot, path).split(sep).join("/"), structuredClone(value));
+}
+async function directProjectFiles(directory) {
+  try {
+    return (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isFile() && !entry.name.startsWith(".") && entry.name !== "file.json").map((entry) => entry.name).sort();
+  } catch (error) {
+    if (isFsError(error, "ENOENT")) return [];
+    throw error;
+  }
+}
+function inferFileResourceId(fileName) {
+  const extension = extname(fileName);
+  const stem = extension ? fileName.slice(0, -extension.length) : fileName;
+  const normalized = stem.normalize("NFKC").trim().replace(/[^\p{L}\p{N}_-]+/gu, "-").replace(/^-+|-+$/g, "");
+  return normalized || `file-${hash(fileName).slice(0, 8)}`;
+}
+function buildRelativePath(projectRelativePath) {
+  return `../../${projectRelativePath}`;
+}
+async function readJsonObject(path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile2(path, "utf8"));
+  } catch (error) {
+    throw new UserError(`${relative(process.cwd(), path)}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord2(parsed)) throw new UserError(`${path}: expected a JSON object.`);
+  return parsed;
+}
+async function withProjectMutation(projectDirectory, kind, action) {
+  const lease = await acquireDirectoryProjectMutation(projectDirectory, kind);
+  try {
+    return await action();
+  } finally {
+    await lease.release();
+  }
+}
+async function acquireDirectoryProjectMutation(projectDirectory, kind) {
+  const projectRoot = resolve2(projectDirectory);
+  const lockDirectory = resolve2(projectRoot, PROJECT_INTERNAL_DIRECTORY, "mutation.lock");
+  await mkdir(dirname(lockDirectory), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await mkdir(lockDirectory);
+      break;
+    } catch (error) {
+      if (!isFsError(error, "EEXIST")) throw error;
+      if (attempt === 0 && await recoverDeadProjectMutation(lockDirectory)) continue;
+      throw new DirectoryProjectMutationConflictError(
+        "Project is busy with another Build, Publish, Restore, or Workbench write."
+      );
+    }
+  }
+  await writeFile2(
+    resolve2(lockDirectory, "lease.json"),
+    `${JSON.stringify({ pid: process.pid, kind, created_at: (/* @__PURE__ */ new Date()).toISOString() })}
+`
+  );
+  let released = false;
+  return {
+    async release() {
+      if (released) return;
+      released = true;
+      await rm2(lockDirectory, { recursive: true, force: true });
+    }
+  };
+}
+async function recoverDeadProjectMutation(lockDirectory) {
+  let pid;
+  try {
+    const value = JSON.parse(await readFile2(resolve2(lockDirectory, "lease.json"), "utf8"));
+    if (typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0) return false;
+    pid = value.pid;
+  } catch {
+    return false;
+  }
+  if (isProcessAlive(pid)) return false;
+  const stale = `${lockDirectory}.stale.${randomUUID2()}`;
+  try {
+    await rename2(lockDirectory, stale);
+  } catch (error) {
+    return isFsError(error, "ENOENT");
+  }
+  await rm2(stale, { recursive: true, force: true });
+  return true;
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !isFsError(error, "ESRCH");
+  }
+}
+async function writeTextAtomic(path, source, mode = 420) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID2()}.tmp`;
+  await writeFile2(temporary, source, { mode });
+  await rename2(temporary, path);
+}
+function hashFiles(files) {
+  const digest = createHash2("sha256");
+  for (const file of files)
+    digest.update(file.path).update("\0").update(String(file.mode)).update("\0").update(file.content).update("\0");
+  return digest.digest("hex");
+}
+function hash(value) {
+  return createHash2("sha256").update(value).digest("hex");
+}
+function projectPublishPlanFingerprint(planned) {
+  return hash(
+    stableStringify({
+      actions: planned.plan.actions,
+      diagnostics: planned.plan.diagnostics
+    })
+  );
+}
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function sortObjectDeep(value) {
+  if (Array.isArray(value)) return value.map(sortObjectDeep);
+  if (!isRecord2(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, sortObjectDeep(value[key])])
+  );
+}
+function hasErrors(diagnostics) {
+  return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+function toDiagnostic(error) {
+  return {
+    severity: "error",
+    code: "project.directory.invalid",
+    message: error instanceof Error ? error.message : String(error)
+  };
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function assertSafeRelative(path) {
+  if (!path || isAbsolute(path) || path.includes("\\") || path.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new UserError(`Invalid project snapshot path: ${path}`);
+  }
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isFsError(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFsError(error, code) {
+  return !!error && typeof error === "object" && "code" in error && error.code === code;
+}
+export {
+  DIRECTORY_RESOURCE_TYPES,
+  DirectoryProjectMutationConflictError,
+  FILE_AUTO_ASSOCIATION_IGNORE_FILE,
+  PROJECT_BUILD_FILE,
+  PROJECT_BUILD_MANIFEST,
+  PROJECT_INTERNAL_DIRECTORY,
+  PROJECT_METADATA_FILE,
+  PROJECT_STATE_FILE,
+  acquireDirectoryProjectMutation,
+  assertLegacyYamlNotShadowed,
+  commitProjectBuild,
+  createDirectoryWorkspaceVersionService,
+  executeProjectPublish,
+  getProjectBuildStatus,
+  initializeDirectoryProject,
+  inspectDirectoryProject,
+  locateDirectoryProjectResource,
+  planProjectPublish,
+  previewProjectBuild,
+  readValidProjectBuild,
+  resolveDirectoryProjectRoot,
+  resolveDirectoryProjectRuntime,
+  validateDirectoryProject
+};