@skaile/workspaces 5.4.0 → 5.6.0

package/dist/{chunk-6IGFSUTE.js → chunk-2W4LBLIN.js}

@@ -1,9 +1,9 @@
 import { globalCacheRoot, globalSkaileDir, mergeLegacyEntriesInto, mergeLegacyEntriesKeyed } from './chunk-MFHKHXDE.js';
-import { SUPPORTED_DRIVER_TARGETS, globalHarnessRoot } from './chunk-TOSHZX4C.js';
-import { decodeSkaileManifest, compositeSha256, listAssetFiles, SKAILE_MANIFEST_FILENAME, sha256Hex } from './chunk-SR4RFKHM.js';
+import { SUPPORTED_DRIVER_TARGETS, globalHarnessRoot } from './chunk-CPSIPIX7.js';
+import { decodeSkaileManifest, compositeSha256, listAssetFiles, SKAILE_MANIFEST_FILENAME, sha256Hex } from './chunk-7ZHLYXTI.js';
 import { readPluginGroupings } from './chunk-RVRB27AN.js';
-import { scanDirectory, parseFrontmatter, bundleDepRefs, fromMcpServerMdContent, withFsDeadline, tryWithFsDeadline, fsDeadlineMs } from './chunk-LFMX2UEF.js';
-import { isValidAssetName, slugifyAssetName, parseAssetRef, assetRefToStr } from './chunk-WX74MVNA.js';
+import { scanDirectory, parseFrontmatter, assetDepRefs, fromMcpServerMdContent, withFsDeadline, tryWithFsDeadline, fsDeadlineMs } from './chunk-PA7WLID3.js';
+import { isValidAssetName, slugifyAssetName, parseAssetRef, assetRefToStr } from './chunk-AO7VJ6G6.js';
 import { isRetentionValue } from './chunk-C3CAXQMA.js';
 import { existsSync, readFileSync, mkdirSync, writeFileSync, lstatSync, symlinkSync, rmSync, readdirSync, constants, statSync } from 'fs';
 import { readdir, stat, cp, rm, open, readFile } from 'fs/promises';
@@ -13,6 +13,247 @@ import { spawnSync } from 'child_process';
 import semver from 'semver';
 import fg from 'fast-glob';
 
+// core/src/type-guards.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// core/src/agent-instances.ts
+var AGENT_INSTANCE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+var DEFAULT_AGENT_INSTANCE_ID = "default";
+var AGENT_INSTANCE_LIFECYCLES = ["standing", "role"];
+var AGENT_INSTANCE_MEMORY_SCOPES = ["instance", "user", "workspace", "none"];
+var AGENT_INSTANCE_TRIGGER_KINDS = ["schedule", "webhook", "channel", "event"];
+var INSTANCE_KEYS = {
+  ref: true,
+  lifecycle: true,
+  model: true,
+  permissions: true,
+  memory: true,
+  triggers: true,
+  connectors: true,
+  budget: true
+};
+function normalizeAgentInstances(raw, diagnostics) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (!isRecord(raw)) {
+    diagnostics.push({
+      code: "invalid_agents_section",
+      severity: "error",
+      message: "`agents:` must be a mapping of instance id \u2192 { ref, \u2026 }.",
+      path: "agents"
+    });
+    return void 0;
+  }
+  const out = {};
+  for (const [id, value] of Object.entries(raw)) {
+    const path = `agents.${id}`;
+    if (!AGENT_INSTANCE_ID_PATTERN.test(id)) {
+      diagnostics.push({
+        code: "invalid_agent_instance_id",
+        severity: "error",
+        message: `Agent instance id "${id}" must match [a-z][a-z0-9_-]* (lowercase, starts with a letter).`,
+        path
+      });
+      continue;
+    }
+    if (!isRecord(value) || typeof value.ref !== "string" || value.ref.trim() === "") {
+      diagnostics.push({
+        code: "invalid_agent_instance",
+        severity: "error",
+        message: `Agent instance "${id}" needs a non-empty string \`ref\` (e.g. "agent:@publisher/name" or a local path).`,
+        path: `${path}.ref`
+      });
+      continue;
+    }
+    out[id] = normalizeInstance(id, value, value.ref, diagnostics);
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function normalizeInstance(id, raw, ref, diagnostics) {
+  const path = `agents.${id}`;
+  const instance = { ref };
+  for (const key of Object.keys(raw)) {
+    if (INSTANCE_KEYS[key]) continue;
+    diagnostics.push({
+      code: "unknown_agent_instance_key",
+      severity: "warning",
+      message: `Unknown key "${key}" on agent instance "${id}" is ignored \u2014 expected one of: ${Object.keys(INSTANCE_KEYS).join(", ")}.`,
+      path: `${path}.${key}`
+    });
+  }
+  if (raw.lifecycle !== void 0) {
+    if (AGENT_INSTANCE_LIFECYCLES.includes(raw.lifecycle)) {
+      instance.lifecycle = raw.lifecycle;
+    } else {
+      diagnostics.push({
+        code: "invalid_agent_instance_lifecycle",
+        severity: "error",
+        message: `Agent instance "${id}": lifecycle "${String(raw.lifecycle)}" \u2014 expected one of: ${AGENT_INSTANCE_LIFECYCLES.join(", ")}.`,
+        path: `${path}.lifecycle`
+      });
+    }
+  }
+  if (isRecord(raw.model)) {
+    const model = {};
+    if (typeof raw.model.preferred === "string") model.preferred = raw.model.preferred;
+    if (Array.isArray(raw.model.fallback)) {
+      model.fallback = raw.model.fallback.filter((m) => typeof m === "string");
+    }
+    if (Object.keys(model).length > 0) instance.model = model;
+  }
+  if (isRecord(raw.permissions)) instance.permissions = raw.permissions;
+  if (raw.memory !== void 0) {
+    const scope = isRecord(raw.memory) ? raw.memory.scope : void 0;
+    if (AGENT_INSTANCE_MEMORY_SCOPES.includes(scope)) {
+      instance.memory = { scope };
+    } else {
+      diagnostics.push({
+        code: "invalid_agent_instance_memory_scope",
+        severity: "error",
+        message: `Agent instance "${id}": memory.scope ${scope === void 0 ? "is required" : `"${String(scope)}" is unknown`} \u2014 expected one of: ${AGENT_INSTANCE_MEMORY_SCOPES.join(", ")}.`,
+        path: `${path}.memory.scope`
+      });
+    }
+  }
+  if (Array.isArray(raw.triggers)) {
+    const triggers = normalizeTriggers(id, raw.triggers, diagnostics);
+    if (triggers.length > 0) instance.triggers = triggers;
+  } else if (raw.triggers !== void 0) {
+    diagnostics.push({
+      code: "invalid_agent_instance_triggers",
+      severity: "error",
+      message: `Agent instance "${id}": triggers must be a list of { id, \u2026 } entries.`,
+      path: `${path}.triggers`
+    });
+  }
+  if (isRecord(raw.connectors)) {
+    const connectors = {};
+    for (const [slot, connectorId] of Object.entries(raw.connectors)) {
+      if (typeof connectorId === "string" && connectorId !== "") {
+        connectors[slot] = connectorId;
+      } else {
+        diagnostics.push({
+          code: "invalid_agent_instance_connector",
+          severity: "error",
+          message: `Agent instance "${id}": connectors.${slot} must name a skaile.yaml connectors[].id.`,
+          path: `${path}.connectors.${slot}`
+        });
+      }
+    }
+    if (Object.keys(connectors).length > 0) instance.connectors = connectors;
+  } else if (raw.connectors !== void 0) {
+    diagnostics.push({
+      code: "invalid_agent_instance_connector",
+      severity: "error",
+      message: `Agent instance "${id}": connectors must map compose slot ids to connectors[].id.`,
+      path: `${path}.connectors`
+    });
+  }
+  if (isRecord(raw.budget)) {
+    const budget = {};
+    if (typeof raw.budget.max_turns === "number") budget.max_turns = raw.budget.max_turns;
+    if (typeof raw.budget.max_tokens === "number") budget.max_tokens = raw.budget.max_tokens;
+    if (Object.keys(budget).length > 0) instance.budget = budget;
+  }
+  return instance;
+}
+function normalizeTriggers(instanceId, raw, diagnostics) {
+  const out = [];
+  raw.forEach((item, i) => {
+    const path = `agents.${instanceId}.triggers[${i}]`;
+    if (!isRecord(item) || typeof item.id !== "string" || !AGENT_INSTANCE_ID_PATTERN.test(item.id)) {
+      diagnostics.push({
+        code: "invalid_agent_instance_trigger",
+        severity: "error",
+        message: `Agent instance "${instanceId}": trigger ${i} needs an \`id\` matching [a-z][a-z0-9_-]*.`,
+        path: `${path}.id`
+      });
+      return;
+    }
+    if (item.kind !== void 0 && !AGENT_INSTANCE_TRIGGER_KINDS.includes(item.kind)) {
+      diagnostics.push({
+        code: "invalid_agent_instance_trigger",
+        severity: "error",
+        message: `Agent instance "${instanceId}": trigger "${item.id}" kind "${String(item.kind)}" \u2014 expected one of: ${AGENT_INSTANCE_TRIGGER_KINDS.join(", ")}.`,
+        path: `${path}.kind`
+      });
+      return;
+    }
+    out.push({ ...item });
+  });
+  return out;
+}
+function definedEntries(obj) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj ?? {})) {
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+function mergeAgentPermissions(base, overlay) {
+  return {
+    ...base,
+    ...definedEntries(overlay),
+    deny_write: [.../* @__PURE__ */ new Set([...base?.deny_write ?? [], ...overlay?.deny_write ?? []])],
+    deny_read: [.../* @__PURE__ */ new Set([...base?.deny_read ?? [], ...overlay?.deny_read ?? []])]
+  };
+}
+function mergeTriggers(base, overlay) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const t of [...base ?? [], ...overlay ?? []]) {
+    byId.set(t.id, { ...byId.get(t.id), ...definedEntries(t) });
+  }
+  return [...byId.values()];
+}
+function mergeInstance(base, overlay) {
+  const merged = { ref: overlay.ref };
+  const lifecycle = overlay.lifecycle ?? base.lifecycle;
+  if (lifecycle) merged.lifecycle = lifecycle;
+  if (base.model || overlay.model)
+    merged.model = { ...base.model, ...definedEntries(overlay.model) };
+  if (base.permissions || overlay.permissions) {
+    merged.permissions = mergeAgentPermissions(base.permissions, overlay.permissions);
+  }
+  const memory = overlay.memory ?? base.memory;
+  if (memory) merged.memory = memory;
+  if (base.triggers || overlay.triggers)
+    merged.triggers = mergeTriggers(base.triggers, overlay.triggers);
+  if (base.connectors || overlay.connectors) {
+    merged.connectors = { ...base.connectors, ...overlay.connectors };
+  }
+  if (base.budget || overlay.budget)
+    merged.budget = { ...base.budget, ...definedEntries(overlay.budget) };
+  return merged;
+}
+function mergeAgentInstances(base, overlay) {
+  if (!base && !overlay) return void 0;
+  const out = { ...base };
+  for (const [id, instance] of Object.entries(overlay ?? {})) {
+    const existing = out[id];
+    out[id] = existing ? mergeInstance(existing, instance) : instance;
+  }
+  return out;
+}
+function effectiveAgentInstances(config) {
+  const out = { ...config.agent?.instances };
+  const definition = config.agent?.definition;
+  if (definition) out[DEFAULT_AGENT_INSTANCE_ID] = { ref: definition };
+  return out;
+}
+function agentInstanceDiagnostics(config) {
+  if (config.agent?.definition && config.agent.instances?.[DEFAULT_AGENT_INSTANCE_ID]) {
+    return [
+      {
+        code: "agent_default_conflict",
+        severity: "error",
+        message: "`agent:` and `agents.default` both declare the primary agent \u2014 `agent:` is the default instance. Remove one of them.",
+        path: `agents.${DEFAULT_AGENT_INSTANCE_ID}`
+      }
+    ];
+  }
+  return [];
+}
 function fileSha256(p) {
   return sha256Hex(readFileSync(p));
 }
@@ -29,7 +270,6 @@ function syntheticVersion(commit) {
 var KIND_DIRS = [
   { dir: "skills", kind: "skill", mdName: "SKILL.md" },
   { dir: "agents", kind: "agent", mdName: "AGENT.md" },
-  { dir: "bundles", kind: "bundle", mdName: "BUNDLE.md" },
   { dir: "mcp-servers", kind: "mcp-server", mdName: "MCP.md" },
   { dir: "connectors", kind: "connector", mdName: "CONNECTOR.md" },
   { dir: "prompts", kind: "prompt", mdName: "PROMPT.md" },
@@ -38,25 +278,25 @@ var KIND_DIRS = [
 var MD_FILE_BY_KIND = Object.fromEntries(
   KIND_DIRS.map((k) => [k.kind, k.mdName])
 );
-async function buildProvenanceIndex(clones, _opts) {
+async function buildProvenanceIndex(clones, opts) {
   const index = /* @__PURE__ */ new Map();
-  for (const clone of clones) await walkOne(clone, index);
+  for (const clone of clones) await walkOne(clone, index, opts.knownKinds);
   return index;
 }
-async function walkOne(clone, index) {
+async function walkOne(clone, index, knownKinds) {
   if (clone.overlayManifestPath && existsSync(clone.overlayManifestPath)) {
     if (await walkWithManifest(clone, clone.overlayManifestPath, index)) return;
   }
   const manifestPaths = findManifestFiles(clone.localPath);
   if (manifestPaths.length === 0) {
-    await walkFilenameConvention(clone, index);
+    await walkFilenameConvention(clone, index, knownKinds);
     return;
   }
   let produced = false;
   for (const p of manifestPaths) {
     if (await walkWithManifest(clone, p, index)) produced = true;
   }
-  if (!produced) await walkFilenameConvention(clone, index);
+  if (!produced) await walkFilenameConvention(clone, index, knownKinds);
 }
 function findManifestFiles(root) {
   const found = [];
@@ -101,7 +341,7 @@ async function walkWithManifest(clone, manifestPath, index) {
       files,
       sha256: a.sha256 ?? compositeSha256(files),
       metadata: resolved.metadata,
-      deps: a.dependencies ?? await manifestDeps(repoRoot, files, a.kind)
+      ...a.dependencies ? { deps: a.dependencies } : await manifestDeps(repoRoot, files, a.kind)
     };
     applyStoreListingMetadata(candidate, a, manifest, resolved.frontmatter);
     push(index, `${assetPublisher}/${a.kind}:${name}`, candidate);
@@ -190,7 +430,7 @@ var DIR_SCOPED_KINDS = /* @__PURE__ */ new Set([
   "connector",
   "knowledge"
 ]);
-async function walkFilenameConvention(clone, index) {
+async function walkFilenameConvention(clone, index, knownKinds) {
   const publisher = publisherFromGithubUrl(clone.sourceUrl);
   if (!publisher) {
     throw new Error(
@@ -198,7 +438,7 @@ async function walkFilenameConvention(clone, index) {
     );
   }
   const version = (clone.tag ? clone.tag.replace(/^v/, "") : void 0) ?? syntheticVersion(clone.commit);
-  for (const e of await scanDirectory(clone.localPath, publisher)) {
+  for (const e of await scanDirectory(clone.localPath, publisher, { knownKinds })) {
     const manifestAbs = e.source;
     const manifestRel = relative(clone.localPath, manifestAbs).replace(/\\/g, "/");
     const files = DIR_SCOPED_KINDS.has(e.kind) ? hashedFilesUnder(clone.localPath, posix.dirname(manifestRel)) : [{ path: manifestRel, sha256: fileSha256(manifestAbs) }];
@@ -212,7 +452,7 @@ async function walkFilenameConvention(clone, index) {
       files,
       sha256: compositeSha256(files),
       metadata: readMetadata(clone.localPath, files, e.kind),
-      deps: await manifestDeps(clone.localPath, files, e.kind)
+      ...await manifestDeps(clone.localPath, files, e.kind)
     };
     push(index, `${publisher}/${e.kind}:${e.name}`, candidate);
   }
@@ -249,10 +489,12 @@ function readContentFrontmatter(repoRoot, files, kind) {
   }
 }
 async function manifestDeps(repoRoot, files, kind) {
-  const ext = kind === "bundle" ? [".bundle.yaml", "BUNDLE.md"] : kind === "flow" ? [".flow.yaml", ".flow.json"] : null;
-  if (!ext) return void 0;
+  const ext = kind === "preset" ? [".preset.yaml"] : kind === "flow" ? [".flow.yaml", ".flow.json"] : null;
+  if (!ext) return {};
   const mf = files.find((f) => ext.some((e) => f.path.endsWith(e)));
-  return mf ? await bundleDepRefs(join(repoRoot, mf.path)) : void 0;
+  if (!mf) return {};
+  const { refs, skipped } = await assetDepRefs(join(repoRoot, mf.path));
+  return kind === "preset" ? { deps: refs, skippedItems: skipped } : { deps: refs };
 }
 function push(index, key, candidate) {
   const arr = index.get(key) ?? [];
@@ -535,11 +777,11 @@ function resolveSourcePublisher(repoDir) {
   const org = repoSlugFromGitRemote(repoDir)?.split("/")[0];
   return org ? normalizeGithubOrg(org) : void 0;
 }
-async function scanRepo(repoDir, repoName) {
+async function scanRepo(repoDir, repoName, options) {
   const repo = repoSlugFromGitRemote(repoDir);
   const publisher = resolveSourcePublisher(repoDir) ?? repoName;
   const groupings = readPluginGroupings(repoDir);
-  return (await scanDirectory(repoDir, repoName)).map((e) => {
+  return (await scanDirectory(repoDir, repoName, options)).map((e) => {
     const plugin = groupings.get(relative(repoDir, dirname(e.source)).split(sep).join("/"));
     return {
       ...e,
@@ -553,7 +795,7 @@ async function resolveAsset(ref, repositories, reposDir, opts) {
   let repoNames;
   if (ref.publisher) {
     repoNames = [ref.publisher];
-  } else if (opts?.preferRepo && opts.preferRepo in repositories) {
+  } else if (opts.preferRepo && opts.preferRepo in repositories) {
     const rest = Object.keys(repositories).filter((n) => n !== opts.preferRepo);
     repoNames = [opts.preferRepo, ...rest];
   } else {
@@ -562,9 +804,9 @@ async function resolveAsset(ref, repositories, reposDir, opts) {
   for (const repoName of repoNames) {
     const decl = repositories[repoName];
     if (!decl) continue;
-    const repoDir = resolveRepoDir(decl, repoName, reposDir, opts?.projectDir);
+    const repoDir = resolveRepoDir(decl, repoName, reposDir, opts.projectDir);
     if (!repoDir || !existsSync(repoDir)) continue;
-    const entries = await scanRepo(repoDir, repoName);
+    const entries = await scanRepo(repoDir, repoName, { knownKinds: opts.knownKinds });
     const match = entries.find((e) => e.kind === ref.kind && e.name === ref.name);
     if (match) return match;
   }
@@ -621,6 +863,43 @@ var CanonicalRefConflictError = class extends Error {
   candidates;
   depChain;
 };
+var MAX_PRESET_DEPTH = 3;
+var PresetDepthError = class extends Error {
+  constructor(reason, ref, depChain) {
+    super(
+      `preset_depth_exceeded: ${reason === "cycle" ? `preset ${ref} lists itself (cycle)` : `preset ${ref} nests deeper than ${MAX_PRESET_DEPTH} presets`} \u2014 via ${depChain.join(" \u2192 ")}`
+    );
+    this.reason = reason;
+    this.ref = ref;
+    this.depChain = depChain;
+    this.name = "PresetDepthError";
+  }
+  reason;
+  ref;
+  depChain;
+  code = "preset_depth_exceeded";
+};
+var REMOVED_KIND_REPLACEMENTS = { bundle: "preset", mount: "connector" };
+var UnknownAssetKindError = class extends Error {
+  constructor(kind, ref, replacement) {
+    super(
+      replacement ? `unknown_asset_kind: asset kind "${kind}" (in "${ref}") no longer exists \u2014 use \`${ref.replace(`${kind}:`, `${replacement}:`)}\` (\`${replacement}:\`) instead` : `unknown_asset_kind: asset kind "${kind}" (in "${ref}") is not registered`
+    );
+    this.kind = kind;
+    this.ref = ref;
+    this.replacement = replacement;
+    this.name = "UnknownAssetKindError";
+  }
+  kind;
+  ref;
+  replacement;
+  code = "unknown_asset_kind";
+};
+function assertKnownKind(ref, refStr, knownKinds) {
+  const replacement = Object.hasOwn(REMOVED_KIND_REPLACEMENTS, ref.kind) ? REMOVED_KIND_REPLACEMENTS[ref.kind] : void 0;
+  if (replacement !== void 0) throw new UnknownAssetKindError(ref.kind, refStr, replacement);
+  if (knownKinds && !knownKinds.has(ref.kind)) throw new UnknownAssetKindError(ref.kind, refStr);
+}
 var SHA_PIN_RE = /^[0-9a-f]{40}$/i;
 function qualifyPublisher(ref, fallback) {
   const hashIdx = ref.indexOf("#");
@@ -639,10 +918,19 @@ async function resolveAll(deps, opts) {
   const resolvedBy = /* @__PURE__ */ new Map();
   const overridesApplied = /* @__PURE__ */ new Set();
   const overridesByRef = new Map(opts.overrides.map((o) => [o.ref, o]));
-  async function visit(refStr, parent, depChain) {
+  const presets = [];
+  async function visit(refStr, parent, depChain, presetChain) {
     const ref = parseAssetRef(refStr);
     if (!ref.publisher) throw new Error(`dep "${refStr}" missing publisher`);
+    assertKnownKind(ref, refStr, opts.knownKinds);
     const key = `${ref.publisher}/${ref.kind}:${ref.name}`;
+    if (ref.kind === "preset") {
+      if (presetChain.includes(key))
+        throw new PresetDepthError("cycle", refStr, [...depChain, refStr]);
+      if (presetChain.length >= MAX_PRESET_DEPTH) {
+        throw new PresetDepthError("depth", refStr, [...depChain, refStr]);
+      }
+    }
     if (seen.has(key)) return;
     seen.add(key);
     const sourceCandidates = opts.provenanceIndex.get(key) ?? [];
@@ -678,16 +966,32 @@ async function resolveAll(deps, opts) {
       opts,
       [...depChain, refStr]
     );
-    resolved.push(chosen);
+    const isPreset = chosen.kind === "preset";
+    if (isPreset) {
+      const members = chosen.deps ?? [];
+      presets.push({
+        ref: canonicalRef,
+        assets: members.filter((m) => !m.startsWith("preset:")).length,
+        skipped: chosen.skippedItems ?? 0
+      });
+    } else {
+      resolved.push(chosen);
+    }
     resolvedBy.set(key, parent);
+    const childPresets = isPreset ? [...presetChain, key] : presetChain;
     for (const depRef of chosen.deps ?? []) {
-      await visit(qualifyPublisher(depRef, chosen.publisher), key, [...depChain, refStr]);
+      await visit(
+        qualifyPublisher(depRef, chosen.publisher),
+        key,
+        [...depChain, refStr],
+        childPresets
+      );
     }
   }
   for (const dep of deps) {
-    await visit(dep, "direct", []);
+    await visit(dep, "direct", [], []);
   }
-  return { resolved, missing, resolvedBy, overridesApplied };
+  return { resolved, missing, resolvedBy, overridesApplied, presets };
 }
 async function gatherStoreCandidates(ref, publisher, sourceCandidates, opts) {
   const storeCandidates = [];
@@ -715,7 +1019,8 @@ async function gatherStoreCandidates(ref, publisher, sourceCandidates, opts) {
           sourceUrl: m.sourceUrl,
           commit: m.commit,
           files: m.files,
-          sha256: m.sha256
+          sha256: m.sha256,
+          deps: m.deps
         });
       }
     }
@@ -1074,22 +1379,8 @@ function mergeAgentConfig(base, overlay) {
     context: overlay?.context ?? base?.context,
     // Whole-block overlay: a partial file list merged across scopes would change caps silently.
     ...overlay?.home ?? base?.home ? { home: overlay?.home ?? base?.home } : {},
-    permissions: {
-      ...base?.permissions,
-      ...stripUndefined(overlay?.permissions),
-      deny_write: dedupe([
-        ...base?.permissions?.deny_write ?? [],
-        ...overlay?.permissions?.deny_write ?? []
-      ]),
-      deny_read: dedupe([
-        ...base?.permissions?.deny_read ?? [],
-        ...overlay?.permissions?.deny_read ?? []
-      ])
-    },
-    subagents: {
-      ...base?.subagents ?? {},
-      ...overlay?.subagents ?? {}
-    },
+    permissions: mergeAgentPermissions(base?.permissions, overlay?.permissions),
+    ...base?.instances ?? overlay?.instances ? { instances: mergeAgentInstances(base?.instances, overlay?.instances) } : {},
     hooks: {
       pre_flow: [...base?.hooks?.pre_flow ?? [], ...overlay?.hooks?.pre_flow ?? []],
       post_flow: [...base?.hooks?.post_flow ?? [], ...overlay?.hooks?.post_flow ?? []],
@@ -1256,6 +1547,11 @@ function assertNoLegacyTopLevelKeys(raw) {
       );
     }
   }
+  if (isRecord(raw.agent) && raw.agent.subagents !== void 0) {
+    throw new Error(
+      "skaile.yaml: `agent.subagents:` was removed \u2014 inline prompt-only subagents had no driver consumer. Declare each one as an agent asset (`.skaile/agents/<name>/agent.yaml`) and bind it under the root `agents:` map (`agents.<name>: { ref: ./.skaile/agents/<name>, lifecycle: role }`). See MIGRATION.md."
+    );
+  }
 }
 function normalizeOverrideEntry(item) {
   if (!item || typeof item !== "object" || Array.isArray(item)) return null;
@@ -1298,6 +1594,23 @@ function normalizeConsumptionSection(raw, config) {
   normalizeStoresSection(raw, config);
   normalizeOverridesSection(raw, config);
 }
+function normalizeAgentSection(raw, config, diagnostics) {
+  if (raw.agent) {
+    config.agent = isRecord(raw.agent) ? { ...raw.agent } : raw.agent;
+  }
+  if (config.agent?.instances !== void 0) {
+    diagnostics.push({
+      code: "misplaced_agent_instances",
+      severity: "error",
+      message: "`agent.instances` is not a skaile.yaml key \u2014 declare instances under root `agents:`.",
+      path: "agent.instances"
+    });
+    delete config.agent.instances;
+  }
+  const instances = normalizeAgentInstances(raw.agents, diagnostics);
+  if (instances) config.agent = { ...config.agent, instances };
+  diagnostics.push(...agentInstanceDiagnostics(config));
+}
 function normalizeStructuralSections(raw, config, diagnostics) {
   if (Array.isArray(raw.mounts)) {
     config.mounts = raw.mounts;
@@ -1331,7 +1644,7 @@ function normalizeStructuralSections(raw, config, diagnostics) {
       if (d.config !== void 0) config.deploy.config = d.config;
     }
   }
-  if (raw.agent) config.agent = raw.agent;
+  normalizeAgentSection(raw, config, diagnostics);
   if (raw.workspace) config.workspace = raw.workspace;
   if (raw.secrets && typeof raw.secrets === "object") {
     config.secrets = raw.secrets;
@@ -1508,14 +1821,23 @@ function validateConfigValues(config, diagnostics) {
     checkUnavailable(c, diagnostics);
   }
   for (const m of config.mounts ?? []) checkAccess(m.access, `mounts.${m.id}.access`);
-  const network = config.agent?.permissions?.network;
-  if (network) {
+  const networks = [
+    [config.agent?.permissions?.network, "agent.permissions.network"],
+    ...Object.entries(config.agent?.instances ?? {}).map(
+      ([id, instance]) => [
+        instance.permissions?.network,
+        `agents.${id}.permissions.network`
+      ]
+    )
+  ];
+  for (const [network, path] of networks) {
+    if (!network) continue;
     if (network.mode && !KNOWN_NETWORK_MODES.includes(network.mode)) {
       diagnostics.push({
         code: "unknown_network_mode",
         severity: "warning",
         message: `Unknown network mode "${network.mode}" \u2014 expected one of: ${KNOWN_NETWORK_MODES.join(", ")}.`,
-        path: "agent.permissions.network.mode"
+        path: `${path}.mode`
       });
     }
     if (network.allowlist && network.allowlist.length > 0 && network.mode !== "allowlist") {
@@ -1523,7 +1845,7 @@ function validateConfigValues(config, diagnostics) {
         code: "unexpected_network_allowlist",
         severity: "warning",
         message: `network.allowlist is set but mode is "${network.mode}" \u2014 the allowlist is ignored unless mode is "allowlist".`,
-        path: "agent.permissions.network.allowlist"
+        path: `${path}.allowlist`
       });
     }
   }
@@ -1575,6 +1897,12 @@ function toCanonicalObject(config) {
   const emit = (key) => {
     const value = config[key];
     if (value === void 0) return;
+    if (key === "agent") {
+      const { instances, ...agent } = config.agent ?? {};
+      if (Object.keys(agent).length > 0) out.agent = agent;
+      if (instances) out.agents = instances;
+      return;
+    }
     out[CONFIG_KEY_TO_YAML[key] ?? key] = value;
   };
   for (const key of CANONICAL_KEY_ORDER) emit(key);
@@ -1617,14 +1945,6 @@ function mergeById(base, overlay) {
   for (const r of overlay) map.set(r.id, r);
   return [...map.values()];
 }
-function stripUndefined(obj) {
-  if (!obj) return {};
-  const result = {};
-  for (const [k, v] of Object.entries(obj)) {
-    if (v !== void 0) result[k] = v;
-  }
-  return result;
-}
 function mcpDeclFromCatalogEntry(entry) {
   const m = entry.metadata;
   if (!m) return null;
@@ -2026,8 +2346,12 @@ function collectMcpRefStrings(dependencies) {
   }
   return mcpRefStrings;
 }
+var MCP_LOOKUP_KINDS = /* @__PURE__ */ new Set(["mcp-server"]);
 async function buildMcpProvenanceIndex(sources, projectDir) {
-  return sources.length > 0 ? await buildProvenanceIndex(buildSourceClones(sources)) : /* @__PURE__ */ new Map();
+  return sources.length > 0 ? await buildProvenanceIndex(buildSourceClones(sources), {
+    // Only `mcp-server` refs are looked up in this index.
+    knownKinds: MCP_LOOKUP_KINDS
+  }) : /* @__PURE__ */ new Map();
 }
 function upsertCatalogMcpDecls(mcpRefStrings, provenanceIndex, upsert) {
   const seen = /* @__PURE__ */ new Set();
@@ -2204,6 +2528,9 @@ function resolveAgentDir(projectDir) {
   const config = resolveSkWorkspaceConfig(projectDir);
   const definition = config.agent?.definition;
   if (!definition) return void 0;
+  return resolveAgentDefinitionDir(projectDir, definition);
+}
+function resolveAgentDefinitionDir(projectDir, definition) {
   if (definition.startsWith("ai-assets://")) {
     const relPath = definition.slice("ai-assets://".length);
     const aiAssetsDir = findAiAssetsDir(projectDir);
@@ -2216,6 +2543,6 @@ function resolveAgentDir(projectDir) {
   return resolve(projectDir, definition);
 }
 
-export { AgentRefResolutionError, COMPACTION_DEFAULTS, CanonicalRefConflictError, DEFAULT_RECIPE_ATTR, SKAILE_YAML_DEFAULT, SKAILE_YAML_SUFFIX, SKILL_ALLOWLIST_FILE, SKILL_ALLOWLIST_VERSION, SK_WORKSPACE_DEFAULT_NAME, SK_WORKSPACE_SUFFIX, STAGED_SKILL_MARKER, buildProvenanceIndex, checkRepoStatus, checkoutPin, cloneRepo, coerceVersion, decodeSkaileYaml, deriveSingleMaterializedMcpDeclaration, encodeSkaileYaml, ensureRepo, findWorkspaceRoot, getGlobalCacheDir, getRepoCommit, isStagedSkillMarkerFor, isWorkspaceConfigFilename, linkRepo, listSkWorkspaceConfigs, loadMcpServerDeclarations, loadSkWorkspaceConfig, matchPin, mergeSkWorkspaceConfigs, normalizeConfig, pullRepo, pullRepoResult, readLinks, readSkillAllowList, resolveAgentDir, resolveAll, resolveAsset, resolveCompactionThresholdPercent, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, resolveSkWorkspaceConfig, resolveSourcePublisher, saveSkWorkspaceConfig, scanRepo, sourceCacheKey, sourceShortName, stageMaterializedSkills, stagedSkillMarkerState, storeManifestSlug, unlinkRepo, unstageSkill, validateAssetRecipeAttr, validateAssetRecipeFlake, workspaceConfigFilename, workspaceNameFromFilename, writeLinks };
-//# sourceMappingURL=chunk-6IGFSUTE.js.map
-//# sourceMappingURL=chunk-6IGFSUTE.js.map
+export { AGENT_INSTANCE_ID_PATTERN, AGENT_INSTANCE_LIFECYCLES, AGENT_INSTANCE_MEMORY_SCOPES, AGENT_INSTANCE_TRIGGER_KINDS, AgentRefResolutionError, COMPACTION_DEFAULTS, CanonicalRefConflictError, DEFAULT_AGENT_INSTANCE_ID, DEFAULT_RECIPE_ATTR, PresetDepthError, SKAILE_YAML_DEFAULT, SKAILE_YAML_SUFFIX, SKILL_ALLOWLIST_FILE, SKILL_ALLOWLIST_VERSION, SK_WORKSPACE_DEFAULT_NAME, SK_WORKSPACE_SUFFIX, STAGED_SKILL_MARKER, UnknownAssetKindError, agentInstanceDiagnostics, buildProvenanceIndex, checkRepoStatus, checkoutPin, cloneRepo, coerceVersion, decodeSkaileYaml, deriveSingleMaterializedMcpDeclaration, effectiveAgentInstances, encodeSkaileYaml, ensureRepo, findWorkspaceRoot, getGlobalCacheDir, getRepoCommit, isStagedSkillMarkerFor, isWorkspaceConfigFilename, linkRepo, listSkWorkspaceConfigs, loadMcpServerDeclarations, loadSkWorkspaceConfig, matchPin, mergeAgentInstances, mergeAgentPermissions, mergeSkWorkspaceConfigs, normalizeAgentInstances, normalizeConfig, pullRepo, pullRepoResult, readLinks, readSkillAllowList, resolveAgentDefinitionDir, resolveAgentDir, resolveAll, resolveAsset, resolveCompactionThresholdPercent, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, resolveSkWorkspaceConfig, resolveSourcePublisher, saveSkWorkspaceConfig, scanRepo, sourceCacheKey, sourceShortName, stageMaterializedSkills, stagedSkillMarkerState, storeManifestSlug, unlinkRepo, unstageSkill, validateAssetRecipeAttr, validateAssetRecipeFlake, workspaceConfigFilename, workspaceNameFromFilename, writeLinks };
+//# sourceMappingURL=chunk-2W4LBLIN.js.map
+//# sourceMappingURL=chunk-2W4LBLIN.js.map