@openagentpack/sdk 0.0.2 → 0.2.0-beta-ddef91c-20260720

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 import {
   defaultFileUploadPurpose,
   enrichProviderFileInfo
-} from "./chunk-TUW6XLDT.js";
+} from "./chunk-OUHQYIG4.js";
 import {
   FILE_SCAN_BACKOFF,
   SCAN_FILE_TIMEOUT_MS,
@@ -14,7 +14,7 @@ import {
   classifySkillScan,
   pollUntil,
   skillStatusFromString
-} from "./chunk-7ECSYAQA.js";
+} from "./chunk-CHGDM6TX.js";
 
 // src/internal/errors.ts
 var UserError = class extends Error {
@@ -34,6 +34,7 @@ var REQUIRED_METHODS_BY_KIND = {
   vault: ["createVault", "deleteVault"],
   skill: ["createSkill", "updateSkill", "deleteSkill"],
   agent: ["createAgent", "updateAgent", "deleteAgent"],
+  template: ["createTemplate", "updateTemplate", "archiveTemplate"],
   memory_store: ["createMemoryStore", "deleteMemoryStore"],
   deployment: ["createDeployment", "updateDeployment", "deleteDeployment", "runDeployment", "getDeployment"],
   session: ["createSession", "listSessions", "getSession", "deleteSession", "sendSessionMessage"]
@@ -88,7 +89,8 @@ var PROVIDER_ENV_VARS = {
   },
   qoder: {
     api_key: { env: ["QODER_PAT", "QODER_API_KEY"], required: true },
-    gateway: { env: ["QODER_GATEWAY"], required: false }
+    gateway: { env: ["QODER_GATEWAY"], required: false },
+    forward_gateway: { env: ["QODER_FORWARD_GATEWAY"], required: false }
   },
   claude: {
     api_key: { env: ["ANTHROPIC_API_KEY", "CLAUDE_API_KEY"], required: true },
@@ -261,11 +263,11 @@ var BaseApiClient = class {
     await this.throwIfError(res);
     return Buffer.from(await res.arrayBuffer());
   }
-  async *sse(path) {
+  async *sse(path, options) {
     const controller = new AbortController();
     const res = await fetch(`${this.baseUrl}${path}`, {
       method: "GET",
-      headers: { ...this.headers(), Accept: "text/event-stream" },
+      headers: { ...this.headers(), Accept: "text/event-stream", ...options?.headers },
       signal: controller.signal
     });
     await this.throwIfError(res);
@@ -417,6 +419,9 @@ function secretPlaceholder(vaultName, credName) {
 }
 
 // src/internal/providers/shared.ts
+function notArchived(raw) {
+  return raw.archived_at === null || raw.archived_at === void 0;
+}
 async function locateRemote(client, endpoint, name, id, accept) {
   if (!endpoint) return null;
   const ok = accept ?? (() => true);
@@ -438,6 +443,7 @@ function buildSessionInfo(res, memoryStoreIds) {
     id: res.id,
     agent_id: agent?.id ?? res.agent_id ?? "",
     environment_id: res.environment_id,
+    tunnel_id: res.tunnel_id ?? void 0,
     status: res.status,
     title: res.title,
     vault_ids: extractVaultIds(res),
@@ -1052,7 +1058,7 @@ var ClaudeAdapter = class _ClaudeAdapter {
     file: "/files"
   };
   async findResource(type, name, id) {
-    const raw = await locateRemote(this.client, _ClaudeAdapter.ENDPOINT_MAP[type], name, id);
+    const raw = await locateRemote(this.client, _ClaudeAdapter.ENDPOINT_MAP[type], name, id, notArchived);
     return raw ? toRemoteResource(raw) : null;
   }
   async listAgents(filter) {
@@ -1246,6 +1252,7 @@ var ClaudeAdapter = class _ClaudeAdapter {
     };
   }
   async createSession(bindings) {
+    if (bindings.delivery === "forward") throw new UserError("Claude does not support Forward sessions.");
     const body = mapSession(bindings);
     const res = await this.client.post("/sessions", body);
     return toSessionInfo(res);
@@ -1345,10 +1352,11 @@ var CLAUDE_CAPABILITIES = {
   vault: { tier: "native", reason: "vaults API" },
   skill: { tier: "native", reason: "skills API with files[] upload" },
   agent: { tier: "native", reason: "managed agents API" },
+  template: { tier: "unsupported", reason: "no Forward Template equivalent on Claude" },
   memory_store: {
     tier: "unsupported",
-    reason: "no memory store primitive on Claude",
-    remediation: "use skill knowledge or MCP for context persistence"
+    reason: "Claude exposes Memory Stores, but the OpenAgentPack adapter has not implemented them yet",
+    remediation: "use skill knowledge or MCP until Claude Memory Store support is added to the adapter"
   },
   mcp_server: { tier: "native", reason: "mcp_servers field on agent" },
   multiagent: { tier: "native", reason: "coordinator + roster topology" },
@@ -1390,6 +1398,9 @@ var QoderClient = class extends BaseApiClient {
     this.baseUrl = config.gateway ?? "https://api.qoder.com/api/v1/cloud";
     this.apiKey = config.apiKey;
   }
+  isConflict(status) {
+    return status === 409;
+  }
   headers() {
     return {
       "Content-Type": "application/json",
@@ -1460,14 +1471,15 @@ function normalizeToolNameFromQoder(name) {
   return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
 }
 function mapEnvironment2(name, decl, projectName) {
+  const envType = decl.config.type ?? "cloud";
+  const config = { type: envType };
+  if (decl.config.networking) config.networking = decl.config.networking;
+  else if (envType === "cloud") config.networking = { type: "unrestricted" };
+  if (decl.config.packages) config.packages = decl.config.packages;
   return {
     name,
     description: decl.description ?? "",
-    config: {
-      type: "cloud",
-      networking: decl.config.networking ?? { type: "unrestricted" },
-      packages: decl.config.packages
-    },
+    config,
     metadata: injectMetadata(decl.metadata, projectName, name)
   };
 }
@@ -1600,6 +1612,85 @@ function mapMemoryStore(name, decl) {
     description: decl.description
   };
 }
+function mapDeployment2(name, decl, refs, projectName, uploadedFiles) {
+  const body = {
+    name,
+    agent: refs.agent_version !== void 0 ? { id: refs.agent_id, type: "agent", version: refs.agent_version } : refs.agent_id,
+    environment_id: refs.environment_id,
+    initial_events: mapDeploymentInitialEvents(decl.initial_events)
+  };
+  if (refs.vault_ids.length) body.vault_ids = refs.vault_ids;
+  const resources = mapDeploymentResources2(decl, refs, uploadedFiles);
+  if (resources.length) body.resources = resources;
+  if (decl.schedule) {
+    body.schedule = {
+      type: "cron",
+      expression: decl.schedule.expression,
+      timezone: decl.schedule.timezone
+    };
+  }
+  if (decl.description) body.description = decl.description;
+  if (projectName) {
+    body.metadata = injectMetadata(decl.metadata, projectName, name);
+  } else if (decl.metadata) {
+    body.metadata = decl.metadata;
+  }
+  return body;
+}
+function mapDeploymentInitialEvents(events) {
+  return events.map((ev) => {
+    if (ev.type === "user.message" || ev.type === "system.message") {
+      return { type: ev.type, content: [{ type: "text", text: ev.content }] };
+    }
+    const out = { type: "user.define_outcome" };
+    if (ev.description) out.description = ev.description;
+    if (ev.rubric) {
+      out.rubric = { type: "text", content: ev.rubric };
+    } else if (ev.rubric_file) {
+      out.rubric = { type: "file", file_id: ev.rubric_file };
+    }
+    if (ev.max_iterations !== void 0) out.max_iterations = ev.max_iterations;
+    return out;
+  });
+}
+function mapDeploymentResources2(decl, refs, uploadedFiles) {
+  const resources = [];
+  const seenStores = /* @__PURE__ */ new Set();
+  for (const r of decl.resources ?? []) {
+    if (r.type === "file") {
+      const fileId = r.file_id ?? (r.source ? uploadedFiles?.get(r.source) : void 0);
+      if (fileId) {
+        const entry = { type: "file", file_id: fileId };
+        if (r.mount_path) entry.mount_path = r.mount_path;
+        resources.push(entry);
+      }
+    } else if (r.type === "github_repository") {
+      const entry = { type: "github_repository", url: r.url };
+      if (r.authorization_token) entry.authorization_token = r.authorization_token;
+      if (r.checkout?.branch) entry.checkout = { type: "branch", name: r.checkout.branch };
+      else if (r.checkout?.commit) entry.checkout = { type: "commit", sha: r.checkout.commit };
+      if (r.mount_path) entry.mount_path = r.mount_path;
+      resources.push(entry);
+    } else if (r.type === "memory_store") {
+      const id = refs.memory_store_ids[r.memory_store];
+      if (id && !seenStores.has(id)) {
+        seenStores.add(id);
+        const entry = { type: "memory_store", memory_store_id: id };
+        if (r.access) entry.access = r.access;
+        if (r.instructions) entry.instructions = r.instructions;
+        resources.push(entry);
+      }
+    }
+  }
+  for (const m of decl.memory_stores ?? []) {
+    const id = refs.memory_store_ids[m];
+    if (id && !seenStores.has(id)) {
+      seenStores.add(id);
+      resources.push({ type: "memory_store", memory_store_id: id });
+    }
+  }
+  return resources;
+}
 function mapAgent2(name, decl, refs, version, projectName) {
   let model;
   if (typeof decl.model === "string") {
@@ -1663,6 +1754,72 @@ function mapAgent2(name, decl, refs, version, projectName) {
   }
   return body;
 }
+function mapForwardTemplate(name, decl, refs, projectName) {
+  let model;
+  if (typeof decl.model === "string") {
+    model = decl.model;
+  } else {
+    const qoderModel = decl.model.qoder;
+    if (!qoderModel) throw new UserError(`No Qoder model specified for template '${name}'`);
+    model = typeof qoderModel === "string" ? qoderModel : qoderModel.id;
+  }
+  const body = {
+    name,
+    description: decl.description ?? "",
+    model,
+    system: decl.instructions,
+    environment_id: refs.environment_id,
+    vault_ids: refs.vault_ids
+  };
+  if (refs.tunnel_id) body.tunnel_id = refs.tunnel_id;
+  if (projectName) body.metadata = injectMetadata(decl.metadata, projectName, name);
+  else body.metadata = decl.metadata ?? {};
+  if (decl.tools) {
+    const permissions = decl.tools.permissions ?? {};
+    body.tools = [
+      {
+        type: "agent_toolset_20260401",
+        configs: decl.tools.builtin.map((tool) => {
+          const normalized = normalizeToolNameForQoder(tool);
+          const policy = permissions[tool] ?? permissions[tool.toLowerCase()] ?? permissions[normalized];
+          return {
+            name: normalized,
+            enabled: true,
+            ...policy ? { permission_policy: { type: policy === "ask" ? "always_ask" : "always_allow" } } : {}
+          };
+        })
+      }
+    ];
+  } else {
+    body.tools = [{ type: "agent_toolset_20260401" }];
+  }
+  body.mcp_servers = (decl.mcp_servers ?? []).map((server) => {
+    if (server.type === "official" || !server.url) {
+      throw new UserError(`Qoder MCP server '${server.name}' requires a url`);
+    }
+    return { name: server.name, type: "http", url: server.url };
+  });
+  if (decl.mcp_servers?.length) {
+    const tools = body.tools;
+    for (const server of decl.mcp_servers) {
+      const toolkit = decl.tools?.mcp?.find((item) => item.mcp_server_name === server.name);
+      if (toolkit) {
+        tools.push({
+          type: "mcp_toolset",
+          mcp_server_name: server.name,
+          configs: toolkit.configs
+        });
+      }
+    }
+  }
+  body.skills = refs.skill_ids.map((skill) => ({
+    type: skill.type === "official" ? "qoder" : skill.type,
+    skill_id: skill.skill_id,
+    ...skill.version ? { version: skill.version } : {},
+    enabled: true
+  }));
+  return body;
+}
 function mapSendMessage2(text) {
   return {
     events: [{ type: "user.message", content: [{ type: "text", text }] }]
@@ -1673,9 +1830,12 @@ var QODER_EVENT_MAP = {
   "user.message": "message",
   "agent.tool_use": "tool_use",
   "agent.tool_result": "tool_result",
+  "agent.mcp_tool_use": "tool_use",
+  "agent.mcp_tool_result": "tool_result",
   "agent.thinking": "thinking",
   "session.status_idle": "status",
   "session.status_running": "status",
+  "session.status_terminated": "status",
   "session.thread_status_idle": "status",
   "session.error": "error"
 };
@@ -1752,6 +1912,7 @@ function mapSession2(bindings) {
     agent: bindings.agent_id,
     environment_id: bindings.environment_id
   };
+  if (bindings.tunnel_id) body.tunnel_id = bindings.tunnel_id;
   if (bindings.title) body.title = bindings.title;
   if (bindings.metadata) body.metadata = bindings.metadata;
   if (bindings.vault_ids.length) body.vault_ids = bindings.vault_ids;
@@ -1762,36 +1923,28 @@ function mapSession2(bindings) {
   if (resources.length) body.resources = resources;
   return body;
 }
-function mapDeploymentToSession(decl, refs, fileIds) {
-  const body = {
-    agent: refs.agent_id,
-    environment_id: refs.environment_id
-  };
-  if (decl.description) body.title = decl.description;
-  if (refs.vault_ids.length) body.vault_ids = refs.vault_ids;
-  const resources = Object.values(refs.memory_store_ids).map((id) => ({
-    type: "memory_store",
-    memory_store_id: id
-  }));
-  const fileResources = (decl.resources ?? []).filter((r) => r.type === "file");
-  fileIds.forEach((id, index) => {
-    const entry = { type: "file", file_id: id };
-    const mountPath = fileResources[index]?.mount_path;
-    if (mountPath) entry.mount_path = mountPath;
-    resources.push(entry);
-  });
-  if (resources.length) body.resources = resources;
-  return body;
-}
 
 // src/internal/providers/qoder/adapter.ts
+function deriveForwardGateway(cloudGateway) {
+  if (!cloudGateway) return "https://api.qoder.com/api/v1/forward";
+  const trimmed = cloudGateway.replace(/\/$/, "");
+  return trimmed.endsWith("/cloud") ? `${trimmed.slice(0, -"/cloud".length)}/forward` : `${trimmed}/forward`;
+}
+var QODER_DEFAULT_IDENTITY_EXTERNAL_ID = "__qca_admin_identity__";
 var QoderAdapter = class _QoderAdapter {
   name = "qoder";
   eventResume = true;
   client;
+  forwardClient;
   projectName;
-  constructor(apiKey, gateway, projectName) {
+  forwardSessionIds = /* @__PURE__ */ new Set();
+  defaultForwardIdentityId;
+  constructor(apiKey, gateway, projectName, forwardGateway) {
     this.client = new QoderClient({ apiKey, gateway });
+    this.forwardClient = new QoderClient({
+      apiKey,
+      gateway: forwardGateway ?? deriveForwardGateway(gateway)
+    });
     this.projectName = projectName ?? "";
   }
   async validate() {
@@ -1807,7 +1960,11 @@ var QoderAdapter = class _QoderAdapter {
     // deployment omitted: emulated on Qoder, no remote listing endpoint
   };
   async findResource(type, name, id) {
-    const raw = await locateRemote(this.client, _QoderAdapter.ENDPOINT_MAP[type], name, id);
+    if (type === "template") {
+      const raw2 = await locateRemote(this.forwardClient, "/templates", name, id, (item) => item.status !== "archived");
+      return raw2 ? toRemoteResource(raw2) : null;
+    }
+    const raw = await locateRemote(this.client, _QoderAdapter.ENDPOINT_MAP[type], name, id, notArchived);
     return raw ? toRemoteResource(raw) : null;
   }
   async listAgents(filter) {
@@ -1852,14 +2009,21 @@ var QoderAdapter = class _QoderAdapter {
     return toRestSkillInfo(res);
   }
   getDriftSupport(type) {
-    if (type === "agent" || type === "environment") return "full";
+    if (type === "agent" || type === "environment" || type === "template") return "full";
     if (type === "deployment") return "unsupported";
     return _QoderAdapter.ENDPOINT_MAP[type] ? "existence" : "unsupported";
   }
   async readComparableResource(type, id, name) {
-    if (type !== "agent" && type !== "environment") return null;
-    const endpoint = type === "agent" ? "/agents" : "/environments";
-    const raw = await locateRemote(this.client, endpoint, name, id);
+    if (type !== "agent" && type !== "environment" && type !== "template") return null;
+    const isTemplate = type === "template";
+    const endpoint = type === "agent" ? "/agents" : type === "environment" ? "/environments" : "/templates";
+    const raw = await locateRemote(
+      isTemplate ? this.forwardClient : this.client,
+      endpoint,
+      name,
+      id,
+      isTemplate ? (item) => item.status !== "archived" : notArchived
+    );
     if (!raw) return null;
     const comparable = this.normalizeRemote(type, raw);
     return {
@@ -1883,6 +2047,7 @@ var QoderAdapter = class _QoderAdapter {
         mapAgent2(name, decl, { skill_ids: [] }, void 0, this.projectName)
       );
     }
+    if (type === "template") return null;
     return null;
   }
   normalizeRemote(type, raw) {
@@ -1898,6 +2063,24 @@ var QoderAdapter = class _QoderAdapter {
         metadata: stripAgentsMetadata(raw.metadata)
       });
     }
+    if (type === "template") {
+      return compactDeep({
+        name: raw.name,
+        description: raw.description,
+        model: raw.model,
+        system: raw.system,
+        tools: raw.tools,
+        mcp_servers: raw.mcp_servers,
+        skills: raw.skills,
+        multiagent: raw.multiagent,
+        environment_id: raw.environment_id,
+        tunnel_id: raw.tunnel_id,
+        vault_ids: Array.isArray(raw.vault_ids) ? raw.vault_ids : Object.keys(raw.vaults ?? {}),
+        files: raw.files,
+        environment_variables: raw.environment_variables,
+        metadata: stripAgentsMetadata(raw.metadata)
+      });
+    }
     return compactDeep({
       description: raw.description,
       model: normalizeModel(raw.model),
@@ -1991,6 +2174,30 @@ var QoderAdapter = class _QoderAdapter {
   async deleteAgent(id) {
     await this.client.delete(`/agents/${id}`);
   }
+  async createTemplate(name, decl, refs) {
+    await this.registerForwardVaults(refs.vault_ids);
+    const body = mapForwardTemplate(name, decl, refs, this.projectName);
+    const res = await this.forwardClient.post("/templates", body);
+    return toRemoteResource(res);
+  }
+  async updateTemplate(id, name, decl, refs) {
+    await this.registerForwardVaults(refs.vault_ids);
+    const body = mapForwardTemplate(name, decl, refs, this.projectName);
+    if (!refs.tunnel_id) body.tunnel_id = null;
+    const res = await this.forwardClient.post(`/templates/${id}`, body);
+    return toRemoteResource(res);
+  }
+  async archiveTemplate(id) {
+    await this.forwardClient.post(`/templates/${id}/archive`, {});
+  }
+  async registerForwardVaults(vaultIds) {
+    for (const id of vaultIds) {
+      await this.forwardClient.post("/resources/registry", {
+        type: "vault",
+        resource: { id }
+      });
+    }
+  }
   async createMemoryStore(name, decl) {
     const body = mapMemoryStore(name, decl);
     const res = await this.client.post("/memory_stores", body);
@@ -2008,46 +2215,58 @@ var QoderAdapter = class _QoderAdapter {
   async deleteMemoryStore(id) {
     await this.client.delete(`/memory_stores/${id}`);
   }
-  async createDeployment(_name, _decl, _refs, _basePath) {
-    return { id: null, type: "deployment" };
+  async createDeployment(name, decl, refs, basePath) {
+    const uploaded = await this.uploadDeploymentFiles(decl, basePath);
+    const body = mapDeployment2(name, decl, refs, this.projectName, uploaded);
+    const res = await this.client.post("/deployments", body);
+    return toRemoteResource(res);
   }
-  async updateDeployment(_id, _name, _decl, _refs, _basePath) {
-    return { id: null, type: "deployment" };
+  async updateDeployment(id, name, decl, refs, basePath) {
+    const uploaded = await this.uploadDeploymentFiles(decl, basePath);
+    const body = mapDeployment2(name, decl, refs, this.projectName, uploaded);
+    const res = await this.client.post(`/deployments/${id}`, body);
+    return toRemoteResource(res);
   }
-  async deleteDeployment(_id) {
+  async deleteDeployment(id) {
+    await this.client.post(`/deployments/${id}/archive`, {});
   }
   async runDeployment(ctx) {
-    const fileIds = [];
-    for (const r of ctx.decl.resources ?? []) {
-      if (r.type === "file") {
-        if (r.file_id) {
-          fileIds.push(r.file_id);
-        } else if (r.source) {
-          fileIds.push(await this.uploadSessionFile(r.source, ctx.basePath));
-        }
-      }
-    }
-    const body = mapDeploymentToSession(ctx.decl, ctx.refs, fileIds);
-    const sessionRes = await this.client.post("/sessions", body);
-    const sessionId = sessionRes.id;
-    const events = ctx.decl.initial_events.filter((e) => e.type === "user.message" || e.type === "system.message").map((e) => ({
-      type: "user.message",
-      content: [{ type: "text", text: e.content }]
-    }));
-    if (events.length) {
-      await this.client.post(`/sessions/${sessionId}/events`, { events });
+    if (!ctx.id) {
+      throw new UserError(`Deployment '${ctx.name}' has no remote id; run \`agents apply\` first.`);
     }
-    return { session_id: sessionId };
+    const res = await this.client.post(`/deployments/${ctx.id}/run`, {});
+    return {
+      run_id: res.id,
+      session_id: res.session_id ?? null,
+      error: res.error ?? void 0
+    };
   }
   async getDeployment(ctx) {
-    const plan = mapDeploymentToSession(ctx.decl, ctx.refs, []);
+    if (!ctx.id) {
+      throw new UserError(`Deployment '${ctx.name}' has no remote id; run \`agents apply\` first.`);
+    }
+    const res = await this.client.get(`/deployments/${ctx.id}`);
+    const sched = res.schedule;
     return {
-      id: ctx.id,
-      status: "emulated (local)",
-      schedule: ctx.decl.schedule,
-      attributes: { materialization_plan: plan }
+      id: res.id,
+      status: res.status ?? "unknown",
+      paused_reason: res.paused_reason,
+      schedule: sched ? {
+        expression: sched.expression,
+        timezone: sched.timezone
+      } : void 0,
+      attributes: res
     };
   }
+  async uploadDeploymentFiles(decl, basePath) {
+    const map = /* @__PURE__ */ new Map();
+    for (const r of decl.resources ?? []) {
+      if (r.type === "file" && !r.file_id && r.source && !map.has(r.source)) {
+        map.set(r.source, await this.uploadSessionFile(r.source, basePath));
+      }
+    }
+    return map;
+  }
   async uploadSessionFile(source, basePath) {
     const fullPath = resolve2(dirname2(basePath), source);
     const content = readFileSync2(fullPath);
@@ -2058,11 +2277,73 @@ var QoderAdapter = class _QoderAdapter {
     return res.file_id ?? res.id;
   }
   async createSession(bindings) {
+    if (bindings.delivery === "forward") {
+      const identityId = bindings.identity_id ?? await this.resolveDefaultForwardIdentityId();
+      const body2 = {
+        identity_id: identityId,
+        template_id: bindings.template_id,
+        incremental_streaming_enabled: false
+      };
+      if (bindings.title) body2.title = bindings.title;
+      if (bindings.metadata) body2.metadata = bindings.metadata;
+      if (bindings.files?.length) {
+        body2.resources = bindings.files.map((file) => ({
+          type: "file",
+          file_id: file.file_id,
+          mount_path: file.mount_path
+        }));
+      }
+      const res2 = await this.forwardClient.post("/sessions", body2);
+      const info = toForwardSessionInfo(res2, bindings);
+      this.forwardSessionIds.add(info.id);
+      return info;
+    }
     const body = mapSession2(bindings);
     const res = await this.client.post("/sessions", body);
     return toSessionInfo2(res);
   }
+  async resolveDefaultForwardIdentityId() {
+    if (this.defaultForwardIdentityId) return this.defaultForwardIdentityId;
+    let afterId;
+    do {
+      const params = new URLSearchParams({ limit: "100" });
+      if (afterId) params.set("after_id", afterId);
+      const res = await this.forwardClient.get(`/identities?${params}`);
+      const identities = res.data ?? [];
+      const match = identities.find(
+        (identity) => identity.external_id === QODER_DEFAULT_IDENTITY_EXTERNAL_ID && identity.enabled !== false && identity.archived !== true
+      );
+      if (typeof match?.id === "string") {
+        this.defaultForwardIdentityId = match.id;
+        return match.id;
+      }
+      const hasMore = res.has_more ?? false;
+      const nextId = hasMore ? res.last_id ?? void 0 : void 0;
+      if (!nextId || nextId === afterId) break;
+      afterId = nextId;
+    } while (afterId);
+    throw new UserError(
+      `Qoder default Forward Identity '${QODER_DEFAULT_IDENTITY_EXTERNAL_ID}' was not found. Ask Qoder to provision it, set defaults.session.qoder.identity_id, or pass --identity-id.`
+    );
+  }
   async listSessions(filter) {
+    if (filter?.agent_id?.startsWith("tmpl_")) {
+      const params2 = new URLSearchParams({ template_id: filter.agent_id });
+      if (filter.limit) params2.set("limit", String(filter.limit));
+      if (filter.page) params2.set("after_id", filter.page);
+      const res2 = await this.forwardClient.get(`/sessions?${params2}`);
+      const data2 = res2.data ?? [];
+      const hasMore = res2.has_more ?? false;
+      const nextPage2 = hasMore ? res2.last_id ?? void 0 : void 0;
+      for (const item of data2) {
+        if (typeof item.id === "string") this.forwardSessionIds.add(item.id);
+      }
+      return {
+        sessions: data2.map((item) => toForwardSessionInfo(item)),
+        has_more: hasMore,
+        next_page: nextPage2
+      };
+    }
     const params = new URLSearchParams();
     if (filter?.agent_id) params.set("agent_id", filter.agent_id);
     if (filter?.limit) params.set("limit", String(filter.limit));
@@ -2077,34 +2358,105 @@ var QoderAdapter = class _QoderAdapter {
     };
   }
   async getSession(id) {
-    const res = await this.client.get(`/sessions/${id}`);
-    return toSessionInfo2(res);
+    if (this.forwardSessionIds.has(id)) return this.getForwardSession(id);
+    try {
+      const res = await this.client.get(`/sessions/${id}`);
+      return toSessionInfo2(res);
+    } catch (error) {
+      if (!ApiError.isNotFound(error)) throw error;
+      return this.getForwardSession(id);
+    }
   }
   async deleteSession(id) {
-    await this.client.delete(`/sessions/${id}`);
+    if (this.forwardSessionIds.has(id)) {
+      await this.forwardClient.post(`/sessions/${id}/archive`, {});
+      return;
+    }
+    try {
+      await this.client.delete(`/sessions/${id}`);
+    } catch (error) {
+      if (!ApiError.isNotFound(error)) throw error;
+      await this.forwardClient.post(`/sessions/${id}/archive`, {});
+      this.forwardSessionIds.add(id);
+    }
   }
   async sendSessionMessage(sessionId, message) {
     const body = mapSendMessage2(message);
-    const res = await this.client.post(`/sessions/${sessionId}/events`, body);
-    return extractCreatedEventId(res);
+    if (this.forwardSessionIds.has(sessionId)) {
+      const res = await this.forwardClient.post(`/sessions/${sessionId}/events`, body);
+      return extractCreatedEventId(res);
+    }
+    try {
+      const res = await this.client.post(`/sessions/${sessionId}/events`, body);
+      return extractCreatedEventId(res);
+    } catch (error) {
+      if (!ApiError.isNotFound(error)) throw error;
+      const res = await this.forwardClient.post(`/sessions/${sessionId}/events`, body);
+      this.forwardSessionIds.add(sessionId);
+      return extractCreatedEventId(res);
+    }
   }
   async *streamSessionEvents(sessionId, options) {
+    if (this.forwardSessionIds.has(sessionId)) {
+      yield* this.streamForwardSessionEvents(sessionId, options);
+      return;
+    }
     const path = `/sessions/${sessionId}/events/stream`;
     let skipping = !!options?.after_id;
     const afterId = options?.after_id;
-    for await (const raw of this.client.sse(path)) {
-      if (skipping) {
-        const eventId = raw.id;
-        if (eventId === afterId) {
-          skipping = false;
+    try {
+      for await (const raw of this.client.sse(path)) {
+        if (skipping) {
+          const eventId = raw.id;
+          if (eventId === afterId) {
+            skipping = false;
+          }
+          continue;
         }
-        continue;
+        yield toSessionEvent3(raw);
       }
-      yield toSessionEvent3(raw);
+    } catch (error) {
+      if (!ApiError.isNotFound(error)) throw error;
+      this.forwardSessionIds.add(sessionId);
+      yield* this.streamForwardSessionEvents(sessionId, options);
     }
   }
   async listSessionEvents(sessionId, options) {
-    return listSessionEventsPaged(this.client, sessionId, options, toSessionEvent3, { forwardAfterId: true });
+    if (this.forwardSessionIds.has(sessionId)) return this.listForwardSessionEvents(sessionId, options);
+    try {
+      return await listSessionEventsPaged(this.client, sessionId, options, toSessionEvent3, { forwardAfterId: true });
+    } catch (error) {
+      if (!ApiError.isNotFound(error)) throw error;
+      this.forwardSessionIds.add(sessionId);
+      return this.listForwardSessionEvents(sessionId, options);
+    }
+  }
+  async getForwardSession(id) {
+    const res = await this.forwardClient.get(`/sessions/${id}`);
+    this.forwardSessionIds.add(id);
+    return toForwardSessionInfo(res);
+  }
+  async *streamForwardSessionEvents(sessionId, options) {
+    const headers = options?.after_id ? { "Last-Event-ID": options.after_id } : void 0;
+    for await (const raw of this.forwardClient.sse(`/sessions/${sessionId}/events/stream`, { headers })) {
+      yield toSessionEvent3(raw);
+    }
+  }
+  async listForwardSessionEvents(sessionId, options) {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.order) params.set("order", options.order);
+    const afterId = options?.after_id ?? options?.page_token ?? options?.page;
+    if (afterId) params.set("after_id", afterId);
+    const query = params.toString();
+    const res = await this.forwardClient.get(`/sessions/${sessionId}/events${query ? `?${query}` : ""}`);
+    const data = res.data ?? [];
+    const hasMore = res.has_more ?? false;
+    return {
+      events: data.map(toSessionEvent3),
+      has_more: hasMore,
+      next_page: hasMore ? res.last_id ?? void 0 : void 0
+    };
   }
   async listModels() {
     const res = await this.client.get("/models");
@@ -2138,6 +2490,24 @@ var QoderAdapter = class _QoderAdapter {
 function toSessionInfo2(res) {
   return buildSessionInfo(res, (r) => r.memory_store_ids ?? []);
 }
+function toForwardSessionInfo(res, bindings) {
+  const template = res.template ?? {};
+  const templateId = res.template_id ?? template.id ?? bindings?.template_id ?? "";
+  const environmentId = res.environment_id ?? template.environment_id ?? "";
+  return {
+    id: res.id,
+    agent_id: templateId,
+    environment_id: environmentId,
+    tunnel_id: res.tunnel_id ?? template.tunnel_id,
+    status: res.status ?? "unknown",
+    title: res.title,
+    vault_ids: res.vault_ids ?? [],
+    memory_store_ids: res.memory_store_ids ?? [],
+    created_at: res.created_at ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+    updated_at: res.updated_at ?? res.created_at ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+    attributes: res
+  };
+}
 function normalizeModel(value) {
   if (value && typeof value === "object" && "id" in value) {
     return value.id;
@@ -2191,6 +2561,7 @@ var QODER_CAPABILITIES = {
   vault: { tier: "native", reason: "vaults + MCP credentials" },
   skill: { tier: "native", reason: "skills API with zip upload" },
   agent: { tier: "native", reason: "agents API" },
+  template: { tier: "native", reason: "Forward Templates API" },
   memory_store: { tier: "native", reason: "memory_stores API" },
   mcp_server: { tier: "native", reason: "mcp_servers field on agent" },
   multiagent: {
@@ -2199,9 +2570,8 @@ var QODER_CAPABILITIES = {
     remediation: "deploy agents independently and orchestrate via MCP"
   },
   deployment: {
-    tier: "emulated",
-    reason: "no deployment primitive on Qoder; expanded into a session at run time",
-    remediation: "scheduling and outcome rubrics are not enforced server-side \u2014 use external cron/CI for always-on or scheduled runs"
+    tier: "native",
+    reason: "deployments API with scheduled and manual runs"
   },
   session: { tier: "native", reason: "sessions API" }
 };
@@ -2210,7 +2580,8 @@ var QODER_CAPABILITIES = {
 import { z as z2 } from "zod";
 var qoderConfigSchema = z2.object({
   api_key: z2.string(),
-  gateway: z2.string().optional()
+  gateway: z2.string().optional(),
+  forward_gateway: z2.string().optional()
 });
 
 // src/internal/providers/qoder/index.ts
@@ -2220,7 +2591,7 @@ registerProvider({
   capabilities: QODER_CAPABILITIES,
   createAdapter: (config, projectName) => {
     const c = config;
-    return new QoderAdapter(c.api_key, c.gateway, projectName);
+    return new QoderAdapter(c.api_key, c.gateway, projectName, c.forward_gateway);
   }
 });
 
@@ -2488,7 +2859,7 @@ function mapSession3(bindings) {
   if (bindings.memory_store_ids.length) body.memory_store_ids = bindings.memory_store_ids;
   return body;
 }
-function mapDeploymentToSession2(decl, refs, fileIds) {
+function mapDeploymentToSession(decl, refs, fileIds) {
   const body = {
     agent: refs.agent_id,
     environment_id: refs.environment_id
@@ -2908,7 +3279,7 @@ var BailianAdapter = class _BailianAdapter {
         }
       }
     }
-    const body = mapDeploymentToSession2(ctx.decl, ctx.refs, fileIds);
+    const body = mapDeploymentToSession(ctx.decl, ctx.refs, fileIds);
     const sessionRes = await this.client.post("/sessions", body);
     const sessionId = sessionRes.id;
     const eventsBody = mapInitialEvents2(ctx.decl.initial_events);
@@ -2919,7 +3290,7 @@ var BailianAdapter = class _BailianAdapter {
     return { session_id: sessionId };
   }
   async getDeployment(ctx) {
-    const plan = mapDeploymentToSession2(ctx.decl, ctx.refs, []);
+    const plan = mapDeploymentToSession(ctx.decl, ctx.refs, []);
     return {
       id: ctx.id,
       status: "emulated (local)",
@@ -2939,6 +3310,7 @@ var BailianAdapter = class _BailianAdapter {
   }
   // --- Session ---
   async createSession(bindings) {
+    if (bindings.delivery === "forward") throw new UserError("Bailian does not support Forward sessions.");
     const body = mapSession3(bindings);
     const res = await this.client.post("/sessions", body);
     return toSessionInfo3(res);
@@ -3106,6 +3478,7 @@ var BAILIAN_CAPABILITIES = {
   vault: { tier: "native", reason: "vaults + credentials API (static_bearer MCP credentials)" },
   skill: { tier: "native", reason: "skills API with 2-step zip upload via Files API" },
   agent: { tier: "native", reason: "agents API with versioned updates" },
+  template: { tier: "unsupported", reason: "no Forward Template equivalent on Bailian" },
   memory_store: {
     tier: "unsupported",
     reason: "no memory store primitive on Bailian"
@@ -3418,7 +3791,7 @@ function mapAgent4(name, decl, refs, version, projectName) {
   }
   return body;
 }
-function mapDeploymentToSession3(decl, refs, fileIds) {
+function mapDeploymentToSession2(decl, refs, fileIds) {
   const body = {
     agent: refs.agent_id,
     environment_id: refs.environment_id
@@ -3736,7 +4109,7 @@ var ArkAdapter = class _ArkAdapter {
         }
       }
     }
-    const body = mapDeploymentToSession3(ctx.decl, ctx.refs, fileIds);
+    const body = mapDeploymentToSession2(ctx.decl, ctx.refs, fileIds);
     const sessionRes = await this.client.post("/sessions", body);
     const sessionId = sessionRes.id;
     const events = ctx.decl.initial_events.filter((e) => e.type === "user.message" || e.type === "system.message").map((e) => ({
@@ -3749,7 +4122,7 @@ var ArkAdapter = class _ArkAdapter {
     return { session_id: sessionId };
   }
   async getDeployment(ctx) {
-    const plan = mapDeploymentToSession3(ctx.decl, ctx.refs, []);
+    const plan = mapDeploymentToSession2(ctx.decl, ctx.refs, []);
     return {
       id: ctx.id,
       status: "emulated (local)",
@@ -3767,6 +4140,7 @@ var ArkAdapter = class _ArkAdapter {
     return res.file_id ?? res.id;
   }
   async createSession(bindings) {
+    if (bindings.delivery === "forward") throw new UserError("Ark does not support Forward sessions.");
     const body = mapSession4(bindings);
     const res = await this.client.post("/sessions", body);
     return toSessionInfo4(res);
@@ -3866,6 +4240,7 @@ var ARK_CAPABILITIES = {
   vault: { tier: "native", reason: "vaults API" },
   skill: { tier: "native", reason: "skills API with single-zip upload (create + get + attach only)" },
   agent: { tier: "native", reason: "managed agents API" },
+  template: { tier: "unsupported", reason: "no Forward Template equivalent on Ark" },
   memory_store: { tier: "native", reason: "memory_stores API" },
   mcp_server: { tier: "native", reason: "mcp_servers field on agent" },
   multiagent: { tier: "native", reason: "coordinator + roster topology" },
@@ -4021,13 +4396,22 @@ var environmentSchema = z5.object({
   name: z5.string().optional(),
   description: z5.string().optional(),
   provider: z5.string().optional(),
+  /** Pre-existing provider environment id (e.g. env_00xxxx). When set, the environment is treated as an external reference and will not be created/updated/deleted by OpenCMA. */
+  environment_id: z5.string().optional(),
   config: z5.object({
-    type: z5.literal("cloud"),
+    type: z5.enum(["cloud", "self_hosted"]),
     networking: networkingSchema.optional(),
     packages: packagesSchema.optional()
   }),
   metadata: z5.record(z5.string(), z5.string()).optional()
 });
+var tunnelSchema = z5.object({
+  name: z5.string().optional(),
+  description: z5.string().optional(),
+  /** Pre-existing Qoder tunnel id (e.g. tnl_00xxxx). Tunnels are allocated by Qoder BYOC admin and referenced, not created. */
+  tunnel_id: z5.string(),
+  metadata: z5.record(z5.string(), z5.string()).optional()
+});
 var coerceString = z5.union([z5.string(), z5.number()]).transform(String);
 var staticBearerCredentialSchema = z5.object({
   name: z5.string(),
@@ -4136,12 +4520,16 @@ var agentSkillRefSchema = z5.object({
   skill_id: String(s.skill_id ?? s.code),
   version: s.version
 }));
+var agentDeliverySchema = z5.object({
+  type: z5.enum(["managed", "forward"])
+});
 var agentSchema = z5.object({
   name: z5.string().optional(),
   description: z5.string().optional(),
   model: z5.union([z5.string(), z5.record(z5.string(), z5.string())]),
   instructions: z5.string(),
   environment: z5.string().optional(),
+  tunnel: z5.string().optional(),
   provider: z5.string().optional(),
   tools: toolsSchema.optional(),
   mcp_servers: z5.array(mcpServerSchema).optional(),
@@ -4149,7 +4537,8 @@ var agentSchema = z5.object({
   vault: z5.string().optional(),
   memory_stores: z5.array(z5.string()).optional(),
   multiagent: multiagentSchema.optional(),
-  metadata: z5.record(z5.string(), z5.string()).optional()
+  metadata: z5.record(z5.string(), z5.string()).optional(),
+  delivery: z5.record(z5.string(), agentDeliverySchema).optional()
 });
 var deploymentFileResourceSchema = z5.object({
   type: z5.literal("file"),
@@ -4196,6 +4585,7 @@ var deploymentSchema = z5.object({
   agent: z5.string(),
   agent_version: z5.number().int().optional(),
   environment: z5.string().optional(),
+  tunnel: z5.string().optional(),
   vaults: z5.array(z5.string()).optional(),
   memory_stores: z5.array(z5.string()).optional(),
   resources: z5.array(deploymentResourceSchema).optional(),
@@ -4209,9 +4599,15 @@ var projectConfigSchema = z5.object({
   version: z5.string(),
   providers: z5.record(z5.string(), z5.unknown()),
   defaults: z5.object({
-    provider: z5.string().optional()
+    provider: z5.string().optional(),
+    session: z5.object({
+      qoder: z5.object({
+        identity_id: z5.string().min(1).optional()
+      }).optional()
+    }).optional()
   }).optional(),
   environments: z5.record(z5.string(), environmentSchema).optional(),
+  tunnels: z5.record(z5.string(), tunnelSchema).optional(),
   vaults: z5.record(z5.string(), vaultSchema).optional(),
   memory_stores: z5.record(z5.string(), memoryStoreSchema).optional(),
   skills: z5.record(z5.string(), skillSchema).optional(),
@@ -4328,6 +4724,7 @@ function getResourceDeclaration(address, config) {
     case "skill":
       return config.skills?.[name] ?? null;
     case "agent":
+    case "template":
       return config.agents?.[name] ?? null;
     case "file":
       return config.files?.[name] ?? null;
@@ -4369,7 +4766,7 @@ function collectFiles(dir, base) {
 }
 
 // src/internal/planner/hasher.ts
-async function computeResourceHash(address, config, basePath) {
+async function computeResourceHash(address, config, basePath, state) {
   const decl = getDeclaration(address, config);
   if (!decl) return "";
   if (address.type === "skill") {
@@ -4379,8 +4776,42 @@ async function computeResourceHash(address, config, basePath) {
       return contentHash({ decl, fileHash });
     }
   }
+  if (address.type === "deployment") {
+    const refs = resolveDeploymentReferenceIds(decl, config, address.provider, state);
+    if (refs) return contentHash({ decl, refs });
+  }
+  if (address.type === "template") {
+    const refs = resolveTemplateReferenceIds(decl, config, address.provider, state);
+    return contentHash({ decl, refs });
+  }
   return contentHash(decl);
 }
+function resolveTemplateReferenceIds(decl, config, provider, state) {
+  const environment = decl.environment ? config.environments?.[decl.environment] : void 0;
+  const tunnel = decl.tunnel ? config.tunnels?.[decl.tunnel] : void 0;
+  const skillIds = (decl.skills ?? []).map((skill) => {
+    if (typeof skill === "string") {
+      return state?.getResource({ type: "skill", name: skill, provider })?.remote_id ?? skill;
+    }
+    if (skill.type === "official") return `${skill.type}:${skill.skill_id}:${skill.version ?? ""}`;
+    return state?.getResource({ type: "skill", name: skill.skill_id, provider })?.remote_id ?? `${skill.type}:${skill.skill_id}:${skill.version ?? ""}`;
+  });
+  return {
+    environment_id: environment?.environment_id ?? (decl.environment ? state?.getResource({ type: "environment", name: decl.environment, provider })?.remote_id ?? void 0 : void 0),
+    tunnel_id: tunnel?.tunnel_id,
+    vault_ids: decl.vault ? [state?.getResource({ type: "vault", name: decl.vault, provider })?.remote_id ?? decl.vault] : [],
+    skill_ids: skillIds
+  };
+}
+function resolveDeploymentReferenceIds(decl, config, provider, state) {
+  const agent = config.agents?.[decl.agent];
+  const envName = decl.environment ?? agent?.environment;
+  if (!envName) return void 0;
+  const envDecl = config.environments?.[envName];
+  return {
+    environment_id: envDecl?.environment_id ?? (envDecl ? state?.getResource({ type: "environment", name: envName, provider })?.remote_id ?? void 0 : void 0)
+  };
+}
 function getDeclaration(address, config) {
   return getResourceDeclaration(address, config);
 }
@@ -4402,15 +4833,65 @@ function computeSkillContentHash(source, basePath) {
   return "";
 }
 
+// src/internal/planner/plan-semantics.ts
+var NON_BLOCKING_ROOT_FIELDS = /* @__PURE__ */ new Set(["description", "metadata"]);
+function diffChangedPaths(before, after, prefix = "") {
+  if (Object.is(before, after)) return [];
+  if (Array.isArray(before) || Array.isArray(after)) {
+    return structurallyEqual(before, after) ? [] : [prefix || "$root"];
+  }
+  if (isRecord(before) && isRecord(after)) {
+    const paths = [];
+    const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of [...keys].sort()) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      paths.push(...diffChangedPaths(before[key], after[key], path));
+    }
+    return paths;
+  }
+  return [prefix || "$root"];
+}
+function classifyReadinessImpact(action, changedPaths) {
+  if (action === "no-op") return "none";
+  if (action !== "update" || !changedPaths || changedPaths.length === 0) return "blocking";
+  return changedPaths.every(isNonBlockingPath) ? "non_blocking" : "blocking";
+}
+function buildReadinessBaseline(declaration) {
+  const record = isRecord(declaration) ? declaration : {};
+  const { description: _description, metadata: _metadata, ...operational } = record;
+  return {
+    operational_hash: contentHash(operational),
+    description_hash: contentHash(record.description ?? null),
+    metadata_hash: contentHash(record.metadata ?? null)
+  };
+}
+function diffReadinessBaseline(before, after) {
+  const paths = [];
+  if (before.operational_hash !== after.operational_hash) paths.push("$operational");
+  if (before.description_hash !== after.description_hash) paths.push("description");
+  if (before.metadata_hash !== after.metadata_hash) paths.push("metadata");
+  return paths;
+}
+function isNonBlockingPath(path) {
+  const root = path.split(".", 1)[0];
+  return root !== void 0 && NON_BLOCKING_ROOT_FIELDS.has(root);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function structurallyEqual(left, right) {
+  return contentHash(left) === contentHash(right);
+}
+
 // src/internal/providers/drift-support.ts
 function supportsFullDrift(adapter, type) {
   return adapter.getDriftSupport?.(type) === "full" && typeof adapter.readComparableResource === "function";
 }
 async function readComparableIfSupported(adapter, type, id, name) {
-  const read = adapter.readComparableResource;
-  if (typeof read !== "function" || !supportsFullDrift(adapter, type)) return null;
+  if (!supportsFullDrift(adapter, type)) return null;
+  if (typeof adapter.readComparableResource !== "function") return null;
   try {
-    return await read(type, id, name);
+    return await adapter.readComparableResource(type, id, name);
   } catch {
     return null;
   }
@@ -4473,6 +4954,22 @@ function resolveAgentRefs(agentName, config, provider, state) {
   }
   return refs;
 }
+function resolveTemplateRefs(agentName, config, provider, state) {
+  const agent = config.agents?.[agentName];
+  if (!agent) throw new UserError(`Agent '${agentName}' not found in config`);
+  if (!agent.environment) {
+    throw new UserError(`Forward template '${agentName}' must declare an environment.`);
+  }
+  const environment = config.environments?.[agent.environment];
+  if (!environment) throw new UserError(`Environment '${agent.environment}' is not defined in config.`);
+  const agentRefs = resolveAgentRefs(agentName, config, provider, state);
+  return {
+    ...agentRefs,
+    environment_id: environment.environment_id ?? requireRef(state, { type: "environment", name: agent.environment, provider }),
+    ...agent.tunnel ? { tunnel_id: resolveTunnelIdFromConfig(config, agent.tunnel, provider) } : {},
+    vault_ids: agent.vault ? [requireRef(state, { type: "vault", name: agent.vault, provider })] : []
+  };
+}
 function resolveDeploymentRefs(deploymentName, config, provider, state) {
   const dep = config.deployments?.[deploymentName];
   if (!dep) throw new UserError(`Deployment '${deploymentName}' not found in config`);
@@ -4491,11 +4988,17 @@ function resolveDeploymentRefs(deploymentName, config, provider, state) {
       `Deployment '${deploymentName}' has no environment and agent '${dep.agent}' does not declare one`
     );
   }
-  const environment_id = requireRef(state, {
+  const envDecl = config.environments?.[envName];
+  if (!envDecl) {
+    throw new UserError(`Environment '${envName}' is not defined in config.`);
+  }
+  const environment_id = envDecl.environment_id ?? requireRef(state, {
     type: "environment",
     name: envName,
     provider
   });
+  const tunnelName = dep.tunnel ?? agent.tunnel;
+  const tunnel_id = tunnelName ? resolveTunnelIdFromConfig(config, tunnelName, provider) : void 0;
   const vaultNames = dep.vaults ?? (agent.vault ? [agent.vault] : []);
   const vault_ids = vaultNames.map((v) => requireRef(state, { type: "vault", name: v, provider }));
   const msNames = /* @__PURE__ */ new Set();
@@ -4518,10 +5021,21 @@ function resolveDeploymentRefs(deploymentName, config, provider, state) {
     agent_id,
     agent_version: dep.agent_version,
     environment_id,
+    tunnel_id,
     vault_ids,
     memory_store_ids
   };
 }
+function resolveTunnelIdFromConfig(config, tunnelName, provider) {
+  if (provider !== "qoder") {
+    throw new UserError("Tunnels are supported only by Qoder BYOC sessions.");
+  }
+  const tunnel = config.tunnels?.[tunnelName];
+  if (!tunnel) {
+    throw new UserError(`Tunnel '${tunnelName}' is not defined in config. Declare it under the 'tunnels:' section.`);
+  }
+  return tunnel.tunnel_id;
+}
 
 // src/internal/executor/skill-resolver.ts
 import { readFileSync as readFileSync7, statSync as statSync3 } from "fs";
@@ -4562,6 +5076,17 @@ async function executePlan(plan, ctx, options = {}) {
   const concurrency = clampConcurrency(options.concurrency);
   const resultsByKey = /* @__PURE__ */ new Map();
   const failed = /* @__PURE__ */ new Set();
+  let stateUpdated = false;
+  for (const action of plan.actions) {
+    if (action.address.type !== "environment") continue;
+    const decl = ctx.config.environments?.[action.address.name];
+    const existing = ctx.state.getResource(action.address);
+    if (decl?.environment_id && existing && !existing.externally_managed) {
+      ctx.state.setResource({ ...existing, externally_managed: true });
+      stateUpdated = true;
+    }
+  }
+  if (stateUpdated) await ctx.state.save();
   const actionable = plan.actions.filter((a) => a.action !== "no-op");
   const mutations = actionable.filter((a) => a.action !== "delete");
   const deletions = actionable.filter((a) => a.action === "delete");
@@ -4677,6 +5202,22 @@ function buildActionLevels(actions) {
   return levels;
 }
 async function executeAction(action, provider, ctx) {
+  try {
+    return await executeActionInner(action, provider, ctx);
+  } catch (err) {
+    if (action.action !== "update" || !ApiError.isNotFound(err)) throw err;
+    emitRuntimeFeedback(ctx.onFeedback, {
+      type: "resource_already_gone",
+      level: "warning",
+      action,
+      resource: action.address,
+      message: `update ${action.address.type}.${action.address.name} (${action.address.provider}) \u2014 not found remotely, recreating`
+    });
+    ctx.state.removeResource(action.address);
+    return executeActionInner({ ...action, action: "create" }, provider, ctx);
+  }
+}
+async function executeActionInner(action, provider, ctx) {
   const { address } = action;
   const { type, name } = address;
   let adopted = false;
@@ -4684,6 +5225,13 @@ async function executeAction(action, provider, ctx) {
     const existing = ctx.state.getResource(address);
     if (!existing) return false;
     const id = existing.remote_id;
+    if (type === "environment") {
+      const decl = ctx.config.environments?.[name];
+      if (existing.externally_managed || decl?.environment_id) {
+        ctx.state.removeResource(address);
+        return false;
+      }
+    }
     if (id !== null) {
       try {
         switch (type) {
@@ -4699,6 +5247,11 @@ async function executeAction(action, provider, ctx) {
           case "agent":
             await provider.deleteAgent(id);
             break;
+          case "template":
+            if (!provider.archiveTemplate)
+              throw new UserError(`Provider '${address.provider}' does not support templates`);
+            await provider.archiveTemplate(id);
+            break;
           case "memory_store":
             if (!provider.deleteMemoryStore) throw memoryStoreUnsupported(address.provider);
             await provider.deleteMemoryStore(id);
@@ -4730,7 +5283,22 @@ async function executeAction(action, provider, ctx) {
     case "environment": {
       const decl = ctx.config.environments[name];
       const remoteName = decl.name ?? name;
-      if (isUpdate) {
+      if (decl.environment_id) {
+        result = { id: decl.environment_id, type: "environment" };
+        emitRuntimeFeedback(ctx.onFeedback, {
+          type: "resource_action_success",
+          level: "info",
+          action,
+          resource: action.address,
+          message: `${action.action} ${action.address.type}.${action.address.name} (${action.address.provider}) \u2014 external reference, no remote mutation`
+        });
+      } else if (isUpdate) {
+        const prior = ctx.state.getResource(address);
+        if (prior?.externally_managed) {
+          throw new UserError(
+            `environment.${name} is recorded as an external reference (${prior.remote_id ?? "unknown id"}); refusing to modify it remotely. Restore 'environment_id' to keep it as a reference, or release it first with 'agents state rm environment.${name}' (then 'agents state import' to adopt it as a managed resource).`
+          );
+        }
         result = await provider.updateEnvironment(existingId, remoteName, decl);
       } else {
         try {
@@ -4860,6 +5428,29 @@ async function executeAction(action, provider, ctx) {
       }
       break;
     }
+    case "template": {
+      const createTemplate = provider.createTemplate?.bind(provider);
+      const updateTemplate = provider.updateTemplate?.bind(provider);
+      if (!createTemplate || !updateTemplate) {
+        throw new UserError(`Provider '${address.provider}' does not support templates`);
+      }
+      const decl = ctx.config.agents[name];
+      const remoteName = decl.name ?? name;
+      const refs = resolveTemplateRefs(name, ctx.config, address.provider, ctx.state);
+      if (isUpdate) {
+        result = await updateTemplate(existingId, remoteName, decl, refs);
+      } else {
+        try {
+          result = await createTemplate(remoteName, decl, refs);
+        } catch (err) {
+          result = await adoptOnConflict(err, address, provider, ctx.onFeedback, {
+            onExisting: (existing) => updateTemplate(existing.id, remoteName, decl, refs)
+          });
+          adopted = true;
+        }
+      }
+      break;
+    }
     case "deployment": {
       const decl = ctx.config.deployments[name];
       const refs = resolveDeploymentRefs(name, ctx.config, address.provider, ctx.state);
@@ -4899,7 +5490,7 @@ async function executeAction(action, provider, ctx) {
     default:
       throw new UserError(`Unknown resource type: ${type}`);
   }
-  const hash = await computeResourceHash(address, ctx.config, ctx.configPath);
+  const hash = await computeResourceHash(address, ctx.config, ctx.configPath, ctx.state);
   const comparableHash = computeComparableDesiredHash(address, ctx.config, provider);
   let remoteHash = comparableHash;
   let remoteSnapshot;
@@ -4908,15 +5499,19 @@ async function executeAction(action, provider, ctx) {
     remoteHash = contentHash(remote.comparable);
     remoteSnapshot = remote.snapshot ?? remote.comparable;
   }
+  const priorResource = ctx.state.getResource(address);
   ctx.state.setResource({
     address,
     remote_id: result.id,
+    externally_managed: priorResource?.externally_managed || type === "environment" && ctx.config.environments?.[name]?.environment_id ? true : void 0,
     version: result.version,
     content_hash: hash,
     desired_hash: hash,
     desired_comparable_hash: remoteHash,
+    desired_readiness_baseline: buildReadinessBaseline(getResourceDeclaration(address, ctx.config)),
     remote_hash: remoteHash,
     remote_snapshot: remoteSnapshot,
+    drift_paths: [],
     drift_status: remoteHash ? "in_sync" : void 0
   });
   return adopted;
@@ -5037,6 +5632,7 @@ function resolveTargetProviders(config) {
 }
 function collectReferenceDiagnostics(config, diagnostics) {
   const envNames = new Set(Object.keys(config.environments ?? {}));
+  const tunnelNames = new Set(Object.keys(config.tunnels ?? {}));
   const skillNames = new Set(Object.keys(config.skills ?? {}));
   const vaultNames = new Set(Object.keys(config.vaults ?? {}));
   const memoryNames = new Set(Object.keys(config.memory_stores ?? {}));
@@ -5048,6 +5644,9 @@ function collectReferenceDiagnostics(config, diagnostics) {
         `agent.${name}: references unknown environment '${agent.environment}'`
       );
     }
+    if (agent.tunnel && !tunnelNames.has(agent.tunnel)) {
+      diagnostics.error("config.agent.tunnel.unknown", `agent.${name}: references unknown tunnel '${agent.tunnel}'`);
+    }
     for (const skill of agent.skills ?? []) {
       if (typeof skill !== "string") continue;
       if (!skillNames.has(skill)) {
@@ -5079,6 +5678,14 @@ function collectReferenceDiagnostics(config, diagnostics) {
       }
     }
   }
+  for (const [name, deployment] of Object.entries(config.deployments ?? {})) {
+    if (deployment.tunnel && !tunnelNames.has(deployment.tunnel)) {
+      diagnostics.error(
+        "config.deployment.tunnel.unknown",
+        `deployment.${name}: references unknown tunnel '${deployment.tunnel}'`
+      );
+    }
+  }
 }
 function collectProviderCapabilities(config, providers, diagnostics) {
   for (const providerName of providers) {
@@ -5091,6 +5698,91 @@ function collectProviderCapabilities(config, providers, diagnostics) {
       continue;
     }
     const caps = def.capabilities;
+    for (const [name, agent] of Object.entries(config.agents ?? {})) {
+      if (agent.provider && agent.provider !== providerName) continue;
+      const delivery = agent.delivery?.[providerName]?.type ?? "managed";
+      if (delivery === "forward" && !isSupported(caps, "template")) {
+        diagnostics.error(
+          `${providerName}.agent.delivery.forward.unsupported`,
+          `agent.${name}: provider '${providerName}' does not support delivery type 'forward'. Supported delivery types: managed.`,
+          { type: "agent", name, provider: providerName }
+        );
+      }
+      if (delivery === "forward" && providerName === "qoder") {
+        if (!agent.environment) {
+          diagnostics.error(
+            "qoder.template.environment.required",
+            `agent.${name}: Qoder Forward delivery requires an environment.`,
+            { type: "template", name, provider: providerName }
+          );
+        }
+        if (agent.memory_stores?.length) {
+          diagnostics.error(
+            "qoder.template.memory_store.unsupported",
+            `agent.${name}: memory_stores are not yet supported by Qoder Forward Template delivery.`,
+            { type: "template", name, provider: providerName }
+          );
+        }
+        if (agent.multiagent) {
+          diagnostics.error(
+            "qoder.template.multiagent.unsupported",
+            `agent.${name}: multiagent is not yet supported by Qoder Forward Template delivery.`,
+            { type: "template", name, provider: providerName }
+          );
+        }
+      }
+    }
+    if (providerName === "qoder") {
+      for (const [name, deployment] of Object.entries(config.deployments ?? {})) {
+        if (deployment.provider && deployment.provider !== providerName) continue;
+        const tunnel = deployment.tunnel ?? config.agents?.[deployment.agent]?.tunnel;
+        const referencedAgent = config.agents?.[deployment.agent];
+        if (referencedAgent?.delivery?.qoder?.type === "forward") {
+          diagnostics.error(
+            "qoder.deployment.forward_template.unsupported",
+            `deployment.${name}: managed deployments cannot reference Forward-delivered agent '${deployment.agent}'.`,
+            { type: "deployment", name, provider: providerName }
+          );
+        }
+        if (tunnel) {
+          diagnostics.warning(
+            `${providerName}.deployment.tunnel.unsupported`,
+            `deployment.${name}: Qoder's deployment API does not accept tunnel_id; scheduled and triggered runs execute in the deployment's environment but without the BYOC tunnel. Create sessions directly for private-network MCP access.`,
+            { type: "deployment", name, provider: providerName }
+          );
+        }
+      }
+    }
+    if (providerName !== "qoder") {
+      for (const [name, env] of Object.entries(config.environments ?? {})) {
+        if (env.environment_id) continue;
+        if (env.config.type === "self_hosted" && (!env.provider || env.provider === providerName)) {
+          diagnostics.error(
+            `${providerName}.environment.self_hosted.unsupported`,
+            `environment.${name}: self_hosted environments are supported only by Qoder BYOC; use type 'cloud' or pin this environment to the qoder provider.`,
+            { type: "environment", name, provider: providerName }
+          );
+        }
+      }
+      for (const [name, agent] of Object.entries(config.agents ?? {})) {
+        if (agent.tunnel && (!agent.provider || agent.provider === providerName)) {
+          diagnostics.error(
+            `${providerName}.agent.tunnel.unsupported`,
+            "Tunnels are supported only by Qoder BYOC sessions.",
+            { type: "agent", name, provider: providerName }
+          );
+        }
+      }
+      for (const [name, deployment] of Object.entries(config.deployments ?? {})) {
+        if (deployment.tunnel && (!deployment.provider || deployment.provider === providerName)) {
+          diagnostics.error(
+            `${providerName}.deployment.tunnel.unsupported`,
+            "Tunnels are supported only by Qoder BYOC sessions.",
+            { type: "deployment", name, provider: providerName }
+          );
+        }
+      }
+    }
     for (const missing of findMissingBailianMcpToolConfigs(config, providerName)) {
       diagnostics.error(
         `${providerName}.agent.mcp_toolkit_missing`,
@@ -5159,6 +5851,13 @@ function collectProviderCapabilities(config, providers, diagnostics) {
   }
 }
 
+// src/internal/core/agent-materialization.ts
+function resolveAgentMaterialization(provider, agent) {
+  const mode = agent.delivery?.[provider]?.type ?? "managed";
+  if (mode === "managed") return { resourceType: "agent", mode };
+  return { resourceType: "template", mode };
+}
+
 // src/internal/graph/dependency.ts
 function buildDependencyGraph(config, targetProviders) {
   const nodes = /* @__PURE__ */ new Map();
@@ -5216,7 +5915,8 @@ function buildDependencyGraph(config, targetProviders) {
       for (const name of Object.keys(config.agents)) {
         const decl = config.agents[name];
         if (decl.provider && decl.provider !== provider) continue;
-        const agentAddr = { type: "agent", name, provider };
+        const materialization = resolveAgentMaterialization(provider, decl);
+        const agentAddr = { type: materialization.resourceType, name, provider };
         addNode(agentAddr);
         if (decl.environment && config.environments?.[decl.environment]) {
           const envAddr = {
@@ -5258,7 +5958,9 @@ function buildDependencyGraph(config, targetProviders) {
         }
         if (decl.multiagent && isSupported(caps, "multiagent")) {
           for (const subName of decl.multiagent.agents) {
-            const subAddr = { type: "agent", name: subName, provider };
+            const subDecl = config.agents[subName];
+            const subType = subDecl ? resolveAgentMaterialization(provider, subDecl).resourceType : "agent";
+            const subAddr = { type: subType, name: subName, provider };
             addEdge(agentAddr, subAddr);
           }
         }
@@ -5270,7 +5972,9 @@ function buildDependencyGraph(config, targetProviders) {
         if (decl.provider && decl.provider !== provider) continue;
         const depAddr = { type: "deployment", name, provider };
         addNode(depAddr);
-        const agentAddr = { type: "agent", name: decl.agent, provider };
+        const agentDecl = config.agents?.[decl.agent];
+        const agentType = agentDecl ? resolveAgentMaterialization(provider, agentDecl).resourceType : "agent";
+        const agentAddr = { type: agentType, name: decl.agent, provider };
         if (nodes.has(addressKey(agentAddr))) addEdge(depAddr, agentAddr);
         if (decl.environment) {
           const envAddr = { type: "environment", name: decl.environment, provider };
@@ -5338,26 +6042,57 @@ async function buildPlan(config, state, options = {}) {
   for (const res of state.resources) {
     stateIndex.set(addressKey(res.address), res);
   }
+  const remoteIdLookup = /* @__PURE__ */ new Map();
+  for (const res of state.resources) {
+    remoteIdLookup.set(addressKey(res.address), res);
+  }
+  const hashStateLookup = { getResource: (addr) => remoteIdLookup.get(addressKey(addr)) };
   for (const address of sorted) {
     const key = addressKey(address);
-    const desiredHash = await computeResourceHash(address, config, options.configPath);
+    const desiredHash = await computeResourceHash(address, config, options.configPath, hashStateLookup);
     const existing = stateIndex.get(key);
     const deps = getDependencies(address, graph);
+    if (address.type === "environment" && existing) {
+      const envDecl = config.environments?.[address.name];
+      if (existing.externally_managed && envDecl && !envDecl.environment_id) {
+        diagnostics.error(
+          "plan.environment.ownership_transition",
+          `environment.${address.name} is recorded as an external reference (${existing.remote_id ?? "unknown id"}); removing 'environment_id' would make OpenCMA modify and eventually delete a remote environment it does not own. Restore 'environment_id' to keep it as a reference, or release it first with 'agents state rm environment.${address.name}' (then 'agents state import' to adopt the remote as a managed resource).`,
+          address
+        );
+        stateIndex.delete(key);
+        continue;
+      }
+      if (!existing.externally_managed && existing.remote_id && envDecl?.environment_id && envDecl.environment_id !== existing.remote_id) {
+        diagnostics.warning(
+          "plan.environment.ownership_orphan",
+          `environment.${address.name}: switching to external reference '${envDecl.environment_id}' orphans the previously managed remote environment '${existing.remote_id}' \u2014 it will no longer be tracked or deletable by OpenCMA.`,
+          address
+        );
+      }
+    }
+    const isExternalEnv = address.type === "environment" && Boolean(config.environments?.[address.name]?.environment_id);
+    const createReason = isExternalEnv ? "Record external environment reference (no remote mutation)" : "Resource does not exist in state";
+    const updateSuffix = isExternalEnv ? " \u2014 external reference, no remote mutation" : "";
     if (!existing) {
       actions.push({
         action: "create",
         address,
         driftKind: "none",
-        reason: "Resource does not exist in state",
+        readinessImpact: "blocking",
+        reason: createReason,
         after: { content_hash: desiredHash },
         dependencies: deps
       });
     } else if ((existing.desired_hash ?? existing.content_hash) !== desiredHash && existing.drift_status === "drifted") {
+      const changedPaths = collectChangedPaths(address, config, existing, true);
       actions.push({
         action: "update",
         address,
         driftKind: "both",
-        reason: "Local config changed and remote drift detected",
+        readinessImpact: classifyReadinessImpact("update", changedPaths),
+        changedPaths,
+        reason: `Local config changed and remote drift detected${updateSuffix}`,
         before: {
           content_hash: existing.desired_hash ?? existing.content_hash,
           remote_hash: existing.remote_hash,
@@ -5367,21 +6102,27 @@ async function buildPlan(config, state, options = {}) {
         dependencies: deps
       });
     } else if ((existing.desired_hash ?? existing.content_hash) !== desiredHash) {
+      const changedPaths = collectChangedPaths(address, config, existing, false);
       actions.push({
         action: "update",
         address,
         driftKind: "local",
-        reason: "Local config changed",
+        readinessImpact: classifyReadinessImpact("update", changedPaths),
+        changedPaths,
+        reason: `Local config changed${updateSuffix}`,
         before: { content_hash: existing.desired_hash ?? existing.content_hash },
         after: { content_hash: desiredHash },
         dependencies: deps
       });
     } else if (existing.drift_status === "drifted") {
+      const changedPaths = existing.drift_paths;
       actions.push({
         action: "update",
         address,
         driftKind: "remote",
-        reason: "Remote drift detected",
+        readinessImpact: classifyReadinessImpact("update", changedPaths),
+        changedPaths,
+        reason: `Remote drift detected${updateSuffix}`,
         before: {
           content_hash: existing.desired_hash ?? existing.content_hash,
           remote_hash: existing.remote_hash,
@@ -5395,6 +6136,7 @@ async function buildPlan(config, state, options = {}) {
         action: "no-op",
         address,
         driftKind: "none",
+        readinessImpact: "none",
         reason: existing.drift_status === "unchecked" ? "No changes detected (remote content drift unchecked)" : "No changes detected",
         dependencies: deps
       });
@@ -5403,17 +6145,32 @@ async function buildPlan(config, state, options = {}) {
   }
   const toDelete = Array.from(stateIndex.values()).reverse();
   for (const res of toDelete) {
+    const replacement = deliveryReplacementAddress(res.address, graph);
     actions.push({
       action: "delete",
       address: res.address,
       driftKind: "none",
-      reason: "Resource removed from configuration",
+      readinessImpact: "blocking",
+      reason: res.externally_managed ? "Remove local reference only \u2014 externally managed remote resource is left intact" : "Resource removed from configuration",
       before: { content_hash: res.desired_hash ?? res.content_hash },
-      dependencies: []
+      dependencies: replacement ? [replacement] : []
     });
   }
   return { actions, diagnostics: diagnostics.getAll() };
 }
+function deliveryReplacementAddress(address, graph) {
+  if (address.type !== "agent" && address.type !== "template") return void 0;
+  const replacementType = address.type === "agent" ? "template" : "agent";
+  const candidate = { ...address, type: replacementType };
+  return graph.nodes.has(addressKey(candidate)) ? candidate : void 0;
+}
+function collectChangedPaths(address, config, existing, includeRemote) {
+  const current = buildReadinessBaseline(getResourceDeclaration(address, config));
+  const localPaths = existing.desired_readiness_baseline ? diffReadinessBaseline(existing.desired_readiness_baseline, current) : void 0;
+  if (!includeRemote) return localPaths;
+  if (!localPaths && !existing.drift_paths) return void 0;
+  return [.../* @__PURE__ */ new Set([...localPaths ?? [], ...existing.drift_paths ?? []])].sort();
+}
 function getDependencies(address, graph) {
   const key = addressKey(address);
   const depKeys = graph.edges.get(key) ?? /* @__PURE__ */ new Set();
@@ -5454,16 +6211,19 @@ async function refreshState(state, providers, options = {}) {
         const decl = options.config ? getResourceDeclaration(res.address, options.config) : null;
         const desiredComparable = decl ? provider.normalizeDesiredResource(res.address.type, res.address.name, decl) : null;
         const desiredComparableHash = desiredComparable === null ? void 0 : contentHash(desiredComparable);
-        const baselineHash = res.desired_comparable_hash ?? desiredComparableHash;
+        const baselineHash = res.desired_comparable_hash ?? desiredComparableHash ?? remoteHash;
         const driftStatus = baselineHash && remoteHash !== baselineHash ? "drifted" : "in_sync";
+        const comparisonBaseline = res.remote_snapshot ?? desiredComparable;
+        const driftPaths = driftStatus === "drifted" && comparisonBaseline != null ? diffChangedPaths(comparisonBaseline, remote2.comparable) : [];
         state.setResource({
           ...res,
           version: remote2.version ?? res.version,
           remote_id: remote2.id,
           desired_hash: res.desired_hash ?? res.content_hash,
-          desired_comparable_hash: res.desired_comparable_hash ?? desiredComparableHash,
+          desired_comparable_hash: baselineHash,
           remote_hash: remoteHash,
           remote_snapshot: remote2.snapshot ?? remote2.comparable,
+          drift_paths: driftPaths,
           drift_status: driftStatus
         });
         dirty = true;
@@ -5553,7 +6313,14 @@ async function syncProjectResourcesWithStateBackend(input, options = {}) {
     };
   });
 }
-var IMPORTABLE_RESOURCE_TYPES = /* @__PURE__ */ new Set(["environment", "vault", "memory_store", "skill", "agent"]);
+var IMPORTABLE_RESOURCE_TYPES = /* @__PURE__ */ new Set([
+  "environment",
+  "vault",
+  "memory_store",
+  "skill",
+  "agent",
+  "template"
+]);
 async function importResource(ctx, address, remoteId, options = {}) {
   if (!IMPORTABLE_RESOURCE_TYPES.has(address.type)) {
     throw new UserError(
@@ -5580,12 +6347,21 @@ async function importResource(ctx, address, remoteId, options = {}) {
   if (!contentHash2) {
     throw new UserError(`Planned ${address.type}.${address.name} is missing a content hash.`);
   }
+  const provider = ctx.providers.get(address.provider);
+  const remote = provider ? await readComparableIfSupported(provider, address.type, remoteId, address.name) : null;
+  const remoteHash = remote ? contentHash(remote.comparable) : void 0;
   const resource = {
     address,
     remote_id: remoteId,
-    version: options.resourceVersion,
+    externally_managed: address.type === "environment" && ctx.config.environments?.[address.name]?.environment_id ? true : void 0,
+    version: options.resourceVersion ?? remote?.version,
     content_hash: contentHash2,
-    desired_hash: contentHash2
+    desired_hash: contentHash2,
+    desired_comparable_hash: remoteHash,
+    desired_readiness_baseline: buildReadinessBaseline(getResourceDeclaration(address, ctx.config)),
+    remote_hash: remoteHash,
+    remote_snapshot: remote ? remote.snapshot ?? remote.comparable : void 0,
+    drift_status: remoteHash ? "in_sync" : void 0
   };
   ctx.state.setResource(resource);
   await ctx.state.save();
@@ -5999,6 +6775,7 @@ function buildDeploymentContext(ctx, name, provider) {
 var destroyOrder = {
   deployment: 0,
   agent: 1,
+  template: 1,
   skill: 2,
   memory_store: 3,
   vault: 4,
@@ -6034,6 +6811,10 @@ async function destroyPlannedProjectResources(planned, options = {}) {
   };
 }
 async function destroyOneResource(ctx, resource, options) {
+  if (isExternalEnvironment(ctx, resource)) {
+    ctx.state.removeResource(resource.address);
+    return successResult(resource, "reference_removed");
+  }
   let provider;
   try {
     provider = getRuntimeProvider(ctx, resource.address.provider);
@@ -6094,6 +6875,9 @@ async function destroyOneResource(ctx, resource, options) {
     return failureResult(resource, error);
   }
 }
+function isExternalEnvironment(ctx, resource) {
+  return resource.address.type === "environment" && (resource.externally_managed || Boolean(ctx.config.environments?.[resource.address.name]?.environment_id));
+}
 function successResult(resource, reason) {
   return { resource, status: "success", reason };
 }
@@ -6110,6 +6894,10 @@ async function deleteRemoteResource(provider, type, id, cascade) {
     case "agent":
       await provider.deleteAgent(id);
       return;
+    case "template":
+      if (!provider.archiveTemplate) throw new UserError(`Provider does not support templates`);
+      await provider.archiveTemplate(id);
+      return;
     case "skill":
       await provider.deleteSkill(id);
       return;
@@ -6207,6 +6995,7 @@ function buildAgentDecl(base, input) {
     model,
     instructions: input.instructions ?? base?.instructions ?? "",
     ...input.environment ? { environment: input.environment } : {},
+    ...input.vault ? { vault: input.vault } : {},
     provider: input.provider ?? base?.provider,
     tools: {
       ...base?.tools ?? { builtin: [] },
@@ -6244,6 +7033,18 @@ function buildSessionBindings(agentName, config, provider, state, options = {})
     const available = Object.keys(config.agents ?? {}).join(", ");
     throw new UserError(`Agent '${agentName}' not found in config. Available agents: ${available || "(none)"}`);
   }
+  if (resolveAgentMaterialization(provider, agent).resourceType === "template") {
+    const templateId = requireRef(state, { type: "template", name: agentName, provider });
+    const identityId = options.identityId ?? config.defaults?.session?.qoder?.identity_id;
+    return {
+      delivery: "forward",
+      template_id: templateId,
+      ...identityId ? { identity_id: identityId } : {},
+      files: (options.files ?? []).map((file) => ({ file_id: file.fileId, mount_path: file.mountPath })),
+      title: options.title,
+      metadata: options.metadata
+    };
+  }
   const agentId = requireRef(state, { type: "agent", name: agentName, provider });
   const agentState = state.getResource({ type: "agent", name: agentName, provider });
   const envName = options.environment ?? agent.environment;
@@ -6255,8 +7056,10 @@ function buildSessionBindings(agentName, config, provider, state, options = {})
       throw new UserError(`Agent '${agentName}' has no environment declared and --environment was not specified.`);
     }
     validateResourceInConfig(envName, "environment", config.environments);
-    environmentId = requireRef(state, { type: "environment", name: envName, provider });
+    const envDecl = config.environments[envName];
+    environmentId = envDecl.environment_id ?? requireRef(state, { type: "environment", name: envName, provider });
   }
+  const tunnelId = resolveTunnelId(agent, config, options, provider);
   let vaultIds;
   if (options.vaultIds) {
     vaultIds = options.vaultIds;
@@ -6278,6 +7081,7 @@ function buildSessionBindings(agentName, config, provider, state, options = {})
     agent_id: agentId,
     agent_version: agentState?.version,
     environment_id: environmentId,
+    tunnel_id: tunnelId,
     vault_ids: vaultIds,
     memory_store_ids: memoryStoreIds,
     files: (options.files ?? []).map((f) => ({ file_id: f.fileId, mount_path: f.mountPath })),
@@ -6285,6 +7089,19 @@ function buildSessionBindings(agentName, config, provider, state, options = {})
     metadata: options.metadata
   };
 }
+function resolveTunnelId(agent, config, options, provider) {
+  const tunnelName = options.tunnel ?? agent.tunnel;
+  if (!options.tunnelId && !tunnelName) return void 0;
+  if (provider !== "qoder") {
+    throw new UserError("Tunnels are supported only by Qoder BYOC sessions.");
+  }
+  if (options.tunnelId) return options.tunnelId;
+  const tunnel = config.tunnels?.[tunnelName];
+  if (!tunnel) {
+    throw new UserError(`Tunnel '${tunnelName}' is not defined in config. Declare it under the 'tunnels:' section.`);
+  }
+  return tunnel.tunnel_id;
+}
 function validateResourceInConfig(name, type, resources) {
   if (!resources?.[name]) {
     throw new UserError(`${type} '${name}' is not defined in config.`);
@@ -6571,9 +7388,7 @@ function actionKey(action) {
 }
 function isNonBlockingAgentDrift(action) {
   if (action.action === "no-op") return true;
-  if (action.action !== "update") return false;
-  const reason = action.reason.toLowerCase();
-  return reason.includes("metadata") || reason.includes("description");
+  return action.readinessImpact === "non_blocking";
 }
 function collectAgentAddresses(config, agentName, provider) {
   const agent = config.agents?.[agentName];
@@ -6581,7 +7396,10 @@ function collectAgentAddresses(config, agentName, provider) {
     throw new UserError(`Agent '${agentName}' not found in config.`);
   }
   const resolvedProvider = provider ?? resolveSessionProvider(agentName, config, void 0);
-  const addresses = [{ type: "agent", name: agentName, provider: resolvedProvider }];
+  const materialization = resolveAgentMaterialization(resolvedProvider, agent);
+  const addresses = [
+    { type: materialization.resourceType, name: agentName, provider: resolvedProvider }
+  ];
   if (agent.environment) {
     addresses.push({
       type: "environment",
@@ -6601,7 +7419,9 @@ function collectAgentAddresses(config, agentName, provider) {
     }
   }
   for (const subAgent of agent.multiagent?.agents ?? []) {
-    addresses.push({ type: "agent", name: subAgent, provider: resolvedProvider });
+    const subDecl = config.agents?.[subAgent];
+    const subType = subDecl ? resolveAgentMaterialization(resolvedProvider, subDecl).resourceType : "agent";
+    addresses.push({ type: subType, name: subAgent, provider: resolvedProvider });
   }
   return addresses;
 }
@@ -6655,8 +7475,11 @@ function resolveSessionRuntime(ctx, target = {}) {
 async function createSessionForAgent(ctx, options = {}) {
   const { agentName, provider, adapter } = resolveSessionRuntime(ctx, options);
   const bindings = buildSessionBindings(agentName, ctx.config, provider, ctx.state, {
+    identityId: options.identityId,
     environment: options.environment,
     environmentId: options.environmentId,
+    tunnel: options.tunnel,
+    tunnelId: options.tunnelId,
     vault: options.vault,
     vaultIds: options.vaultIds,
     memoryStores: options.memoryStores,
@@ -6670,8 +7493,11 @@ async function createSessionForAgent(ctx, options = {}) {
 async function startSessionRun(ctx, prompt, options = {}) {
   const { agentName, provider, adapter } = resolveSessionRuntime(ctx, options);
   const bindings = buildSessionBindings(agentName, ctx.config, provider, ctx.state, {
+    identityId: options.identityId,
     environment: options.environment,
     environmentId: options.environmentId,
+    tunnel: options.tunnel,
+    tunnelId: options.tunnelId,
     vault: options.vault,
     vaultIds: options.vaultIds,
     memoryStores: options.memoryStores,
@@ -6764,13 +7590,17 @@ async function listSessionsForProject(ctx, options = {}) {
     const resolved = resolveSessionRuntime(ctx, options);
     provider = resolved.provider;
     agentName = resolved.agentName;
+    const agentDecl = ctx.config.agents?.[resolved.agentName];
+    const resourceType = agentDecl ? resolveAgentMaterialization(provider, agentDecl).resourceType : "agent";
     const state = ctx.state.getResource({
-      type: "agent",
+      type: resourceType,
       name: resolved.agentName,
       provider
     });
     if (!state?.remote_id) {
-      throw new UserError(`Agent '${resolved.agentName}' not found in state. Run \`agents apply\` first.`);
+      throw new UserError(
+        `${resourceType === "template" ? "Template" : "Agent"} '${resolved.agentName}' not found in state. Run \`agents apply\` first.`
+      );
     }
     agentId = state.remote_id;
   } else if (options.provider) {
@@ -6886,7 +7716,7 @@ function resolveDirectAdapter(ctx, overrideProvider) {
 function buildAgentNameByRemoteId(ctx, provider) {
   const names = /* @__PURE__ */ new Map();
   for (const resource of ctx.state.listResources()) {
-    if (resource.address.type === "agent" && resource.address.provider === provider && resource.remote_id) {
+    if ((resource.address.type === "agent" || resource.address.type === "template") && resource.address.provider === provider && resource.remote_id) {
       names.set(resource.remote_id, resource.address.name);
     }
   }
@@ -7100,12 +7930,15 @@ var StateManager = class _StateManager {
       const resources = raw.map((r) => ({
         address: r.address,
         remote_id: r.remote_id,
+        externally_managed: r.externally_managed === true ? true : void 0,
         version: r.version,
         content_hash: r.content_hash ?? r.desired_hash ?? "",
         desired_hash: r.desired_hash ?? r.content_hash ?? "",
         desired_comparable_hash: r.desired_comparable_hash,
+        desired_readiness_baseline: r.desired_readiness_baseline,
         remote_hash: r.remote_hash,
         remote_snapshot: r.remote_snapshot,
+        drift_paths: r.drift_paths,
         drift_status: r.drift_status
       }));
       return new _StateManager({ resources }, path);
@@ -7282,6 +8115,7 @@ var ResourceTypeSchema = z6.enum([
   "memory_store",
   "skill",
   "agent",
+  "template",
   "deployment",
   "file"
 ]);
@@ -7299,11 +8133,14 @@ var DiagnosticSchema = z6.object({
 });
 var ActionTypeSchema = z6.enum(["create", "update", "delete", "no-op"]);
 var DriftKindSchema = z6.enum(["none", "local", "remote", "both"]);
+var PlanReadinessImpactSchema = z6.enum(["none", "non_blocking", "blocking"]);
 var PlannedActionSchema = z6.object({
   action: ActionTypeSchema,
   address: ResourceAddressSchema,
   reason: z6.string(),
   driftKind: DriftKindSchema.optional(),
+  readinessImpact: PlanReadinessImpactSchema.optional(),
+  changedPaths: z6.array(z6.string()).optional(),
   before: z6.record(z6.string(), z6.unknown()).optional(),
   after: z6.record(z6.string(), z6.unknown()).optional(),
   dependencies: z6.array(ResourceAddressSchema)
@@ -7556,6 +8393,7 @@ export {
   ListSessionsRequestSchema,
   ListSessionsResponseSchema,
   LocalFileStateBackend,
+  PlanReadinessImpactSchema,
   PlannedActionSchema,
   ResourceAddressSchema,
   ResourceTypeSchema,