@skaile/workspaces 0.29.1 → 0.30.1

package/dist/{chunk-MLJKA3S6.js → chunk-XOAF5QAE.js}

@@ -1,20 +1,20 @@
-import { WorkspacePlugin } from './chunk-LD4QIVBY.js';
+import { WorkspacePlugin } from './chunk-5MJJYIL4.js';
 import { WebSocketServerTransport } from './chunk-WQ7DE5UC.js';
 import { assembleSystemPrompt, buildCapabilitiesPromptSection } from './chunk-W3UDISS2.js';
 import { PROTOCOL_VERSION } from './chunk-TDSRLMDB.js';
-import { EventNormalizer } from './chunk-AKSR434V.js';
-import { classifyClaudeSdkError } from './chunk-PAYAFNXG.js';
-import { createDriver } from './chunk-ZEKWHJBB.js';
+import { EventNormalizer } from './chunk-5XAQDOMU.js';
+import { classifyClaudeSdkError } from './chunk-NGJ6E344.js';
+import { createDriver } from './chunk-IZIFMNTI.js';
 import { deployCatalogEntry, undeployCatalogEntry } from './chunk-LV2HPH3C.js';
-import { registerBuiltinConnectors, findMissingPackages, installNpmPackages, ConnectorManager, ConnectorStartupError, buildConnectorPromptSection, buildSdkConnectorTools } from './chunk-OTFG5Q7H.js';
-import { loadConnectorDeclarations, PreMintedSecretProvider, InMemorySecretProvider } from './chunk-CMG3GJ6B.js';
+import { registerBuiltinConnectors, buildConnectorPromptSection, findMissingPackages, installNpmPackages, ConnectorManager, ConnectorStartupError, buildSdkConnectorTools } from './chunk-FRRTUVUM.js';
+import { loadConnectorDeclarations, PreMintedSecretProvider, InMemorySecretProvider } from './chunk-DAI754GK.js';
 import { renderStimulusPrompt, buildOrchestratorPrompt } from './chunk-DEYYRFQU.js';
-import { resolveSettings, resolveApiKey, providerEnvKey } from './chunk-M4KLIEIJ.js';
-import { resolveRuntimeAssets } from './chunk-FWHOU3CX.js';
-import { resolveSkWorkspaceConfig, resolveAgentDir, stageMaterializedSkills, loadMcpServerDeclarations, COMPACTION_DEFAULTS, validateAssetRecipeAttr } from './chunk-3QQSSRYN.js';
-import { parseAssetRef } from './chunk-IEJ5IOC3.js';
+import { resolveSettings, resolveApiKey, providerEnvKey } from './chunk-YBJLYT4S.js';
+import { resolveRuntimeAssets } from './chunk-2VKVWN5E.js';
+import { resolveSkWorkspaceConfig, resolveAgentDir, stageMaterializedSkills, loadMcpServerDeclarations, COMPACTION_DEFAULTS, validateAssetRecipeAttr } from './chunk-5DQOZFWJ.js';
+import { parseAssetRef } from './chunk-LFDZYCEO.js';
 import { resolveDriverPaths } from './chunk-K5GBV4SA.js';
-import { getLogStore, resolveLogStoreConfig, createLogStoreFromConfig, OnLogBridgeSink, WsLogSink, registerLogStore, resetLogStore, createLogger } from './chunk-24UIWON4.js';
+import { getLogStore, resolveLogStoreConfig, createLogStoreFromConfig, OnLogBridgeSink, WsLogSink, registerLogStore, resetLogStore, createLogger } from './chunk-JB35MVBN.js';
 import { __require } from './chunk-NSBPE2FW.js';
 import pc from 'picocolors';
 import { Marked } from 'marked';
@@ -183,48 +183,6 @@ var MarkdownStreamer = class {
     }
   }
 };
-
-// runner/src/context.ts
-var PLATFORM_DESCRIPTIONS = {
-  skaile: "You are an AI assistant operating within the Skaile platform, an enterprise AI workspace. Users interact with you through a chat interface in their browser."
-};
-function buildContextSection(context) {
-  if (!context) return void 0;
-  const hasAny = context.platform !== void 0 || context.multi_user !== void 0 || context.session_model !== void 0;
-  if (!hasAny) return void 0;
-  const lines = ["## Platform", ""];
-  if (context.platform) {
-    const description = PLATFORM_DESCRIPTIONS[context.platform];
-    if (description) {
-      lines.push(description);
-    } else {
-      lines.push(`You are running inside the ${context.platform} platform.`);
-    }
-    lines.push("");
-  }
-  if (context.multi_user === true) {
-    lines.push(
-      "Multiple users may participate in the same session. Be aware that messages in this conversation may come from different users."
-    );
-    lines.push("");
-  } else if (context.multi_user === false) {
-    lines.push("This is a single-user session.");
-    lines.push("");
-  }
-  if (context.session_model === "persistent") {
-    lines.push(
-      "Your work persists across interactions. Files you create or modify in the workspace are saved and available in future sessions."
-    );
-    lines.push("");
-  } else if (context.session_model === "ephemeral") {
-    lines.push(
-      "This session is ephemeral. Work you do does not persist beyond the current interaction."
-    );
-    lines.push("");
-  }
-  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-  return lines.join("\n");
-}
 function defineCapability(args) {
   const inputSchema = z5.toJSONSchema(args.input, {
     target: "draft-07",
@@ -629,6 +587,48 @@ async function openLocalIndexIfAvailable(log) {
     return STUB_LIBRARY;
   }
 }
+
+// runner/src/context.ts
+var PLATFORM_DESCRIPTIONS = {
+  skaile: "You are an AI assistant operating within the Skaile platform, an enterprise AI workspace. Users interact with you through a chat interface in their browser."
+};
+function buildContextSection(context) {
+  if (!context) return void 0;
+  const hasAny = context.platform !== void 0 || context.multi_user !== void 0 || context.session_model !== void 0;
+  if (!hasAny) return void 0;
+  const lines = ["## Platform", ""];
+  if (context.platform) {
+    const description = PLATFORM_DESCRIPTIONS[context.platform];
+    if (description) {
+      lines.push(description);
+    } else {
+      lines.push(`You are running inside the ${context.platform} platform.`);
+    }
+    lines.push("");
+  }
+  if (context.multi_user === true) {
+    lines.push(
+      "Multiple users may participate in the same session. Be aware that messages in this conversation may come from different users."
+    );
+    lines.push("");
+  } else if (context.multi_user === false) {
+    lines.push("This is a single-user session.");
+    lines.push("");
+  }
+  if (context.session_model === "persistent") {
+    lines.push(
+      "Your work persists across interactions. Files you create or modify in the workspace are saved and available in future sessions."
+    );
+    lines.push("");
+  } else if (context.session_model === "ephemeral") {
+    lines.push(
+      "This session is ephemeral. Work you do does not persist beyond the current interaction."
+    );
+    lines.push("");
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.join("\n");
+}
 var execFileAsync = promisify(execFile);
 var PROBE_TIMEOUT_MS = 1500;
 var VERSION_PROBES = [
@@ -893,63 +893,72 @@ function resolveExternalMcpDeclarations(projectDir, sessionId) {
       mcpLog.warn("MCP server skipped: reserved id", { id: decl.id });
       continue;
     }
-    let resolvedDecl = decl;
-    if (decl.recipe) {
-      const recipeLogKey = decl.recipe.flake ? { flake: decl.recipe.flake } : { attr: decl.recipe.attr };
-      try {
-        const recipeKey = decl.recipe.flake ? `mcps.${decl.id}` : decl.recipe.attr ?? `mcps.${decl.id}`;
-        const outPath = resolveRecipePath(nixFlakeRef, recipeKey, recipeCache);
-        const outPaths = /* @__PURE__ */ new Map([[decl.id, outPath]]);
-        const resolvedCommand = decl.command ? substituteRecipeTemplating(decl.command, outPaths) : decl.command;
-        const resolvedArgs = decl.args?.map((a) => substituteRecipeTemplating(a, outPaths));
-        const resolvedEnv = substituteRecipeMap(decl.env, outPaths);
-        resolvedDecl = {
-          ...decl,
-          command: resolvedCommand,
-          args: resolvedArgs,
-          env: resolvedEnv
-        };
-        const recipeLog = createLogger({
-          kind: "mcp",
-          subkind: decl.id,
-          instance: "recipe-resolve"
-        });
-        const allResolved = [
-          resolvedCommand ?? "",
-          ...resolvedArgs ?? [],
-          ...Object.values(resolvedEnv ?? {})
-        ];
-        for (const v of allResolved) {
-          if (v.includes("${recipe:")) {
-            recipeLog.warn("unresolved recipe marker after substitution", {
-              value: v,
-              declId: decl.id
-            });
-          }
-        }
-        const missingPaths = validateSubstitutedPaths(resolvedCommand, resolvedArgs);
-        if (missingPaths.length > 0) {
-          recipeLog.error("MCP server skipped: substituted path does not exist", void 0, {
-            id: decl.id,
-            ...recipeLogKey,
-            missing: missingPaths
-          });
-          continue;
-        }
-        recipeLog.info("recipe substitution complete", { ...recipeLogKey, outPath });
-      } catch (err) {
-        createLogger({ kind: "mcp", subkind: decl.id, instance: "recipe-resolve" }).error(
-          "MCP server skipped: recipe resolution failed",
-          err,
-          { id: decl.id, ...recipeLogKey, flakeRef: nixFlakeRef }
-        );
-        continue;
-      }
+    if (!decl.recipe) {
+      resolved.push(decl);
+      continue;
     }
-    resolved.push(resolvedDecl);
+    const resolvedDecl = resolveRecipeDeclaration(decl, nixFlakeRef, recipeCache);
+    if (resolvedDecl) resolved.push(resolvedDecl);
   }
   return resolved;
 }
+function resolveRecipeDeclaration(decl, nixFlakeRef, recipeCache) {
+  const recipe = decl.recipe;
+  const recipeLogKey = recipe.flake ? { flake: recipe.flake } : { attr: recipe.attr };
+  try {
+    const recipeKey = recipe.flake ? `mcps.${decl.id}` : recipe.attr ?? `mcps.${decl.id}`;
+    const outPath = resolveRecipePath(nixFlakeRef, recipeKey, recipeCache);
+    const outPaths = /* @__PURE__ */ new Map([[decl.id, outPath]]);
+    const resolvedCommand = decl.command ? substituteRecipeTemplating(decl.command, outPaths) : decl.command;
+    const resolvedArgs = decl.args?.map((a) => substituteRecipeTemplating(a, outPaths));
+    const resolvedEnv = substituteRecipeMap(decl.env, outPaths);
+    const resolvedDecl = {
+      ...decl,
+      command: resolvedCommand,
+      args: resolvedArgs,
+      env: resolvedEnv
+    };
+    const recipeLog = createLogger({
+      kind: "mcp",
+      subkind: decl.id,
+      instance: "recipe-resolve"
+    });
+    warnUnresolvedRecipeMarkers(recipeLog, decl.id, resolvedCommand, resolvedArgs, resolvedEnv);
+    const missingPaths = validateSubstitutedPaths(resolvedCommand, resolvedArgs);
+    if (missingPaths.length > 0) {
+      recipeLog.error("MCP server skipped: substituted path does not exist", void 0, {
+        id: decl.id,
+        ...recipeLogKey,
+        missing: missingPaths
+      });
+      return void 0;
+    }
+    recipeLog.info("recipe substitution complete", { ...recipeLogKey, outPath });
+    return resolvedDecl;
+  } catch (err) {
+    createLogger({ kind: "mcp", subkind: decl.id, instance: "recipe-resolve" }).error(
+      "MCP server skipped: recipe resolution failed",
+      err,
+      { id: decl.id, ...recipeLogKey, flakeRef: nixFlakeRef }
+    );
+    return void 0;
+  }
+}
+function warnUnresolvedRecipeMarkers(recipeLog, declId, resolvedCommand, resolvedArgs, resolvedEnv) {
+  const allResolved = [
+    resolvedCommand ?? "",
+    ...resolvedArgs ?? [],
+    ...Object.values(resolvedEnv ?? {})
+  ];
+  for (const v of allResolved) {
+    if (v.includes("${recipe:")) {
+      recipeLog.warn("unresolved recipe marker after substitution", {
+        value: v,
+        declId
+      });
+    }
+  }
+}
 var PASSTHROUGH_INPUT_ZOD = {
   parse: (v) => v
 };
@@ -1140,122 +1149,50 @@ async function buildAgentResources(projectDir, driverType, _onLog, watch, secret
     for (const w of runtimeAssets.warnings) {
       resLog.warn("runtime asset warning", { code: w.code, message: w.message });
     }
-    if (process.env.SKAILE_AUTO_INSTALL_DEPS === "true") {
-      const required = runtimeAssets.requiredNpmDeps.required;
-      if (required.length > 0) {
-        const missing = findMissingPackages(required, projectDir);
-        if (missing.length > 0) {
-          resLog.info("installing missing npm peer deps", { packages: missing });
-          const r = await installNpmPackages(missing, projectDir);
-          if (!r.success) resLog.error("npm install failed", void 0, { output: r.output });
-        }
-      }
-    }
+    await maybeInstallNpmPeerDeps(runtimeAssets, projectDir, resLog);
     const connectorDeclarations = loadConnectorDeclarations(projectDir);
     let resourceManager = null;
     if (connectorDeclarations.length > 0) {
-      resourceManager = new ConnectorManager(projectDir, {
-        secrets: secretProvider,
-        catalogEntries: runtimeAssets.catalogEntries,
+      resourceManager = await connectAllConnectors(
+        connectorDeclarations,
+        projectDir,
+        runtimeAssets,
+        secretProvider,
         tokenMediator,
         preMintedSecrets,
-        onStatusChange: watch?.onConnectorStatus
-      });
-      try {
-        const report = await resourceManager.connectAll(connectorDeclarations, {
-          failOnReadWriteError: true,
-          deferMounts: deferFilesystemMounts
-        });
-        for (const r of report.results) {
-          if (r.connected) {
-            resLog.info("connector ok", { id: r.id, mountPath: r.mountPath });
-          } else {
-            resLog.error("connector failed", void 0, { id: r.id, error: r.error });
-          }
-        }
-      } catch (err) {
-        if (err instanceof ConnectorStartupError) {
-          for (const r of err.report.results) {
-            if (r.connected) {
-              resLog.info("connector ok", { id: r.id, mountPath: r.mountPath });
-            } else {
-              resLog.error("connector failed", void 0, { id: r.id, error: r.error });
-            }
-          }
-        }
-        throw err;
-      }
+        deferFilesystemMounts,
+        watch,
+        resLog
+      );
     }
     const resourcePromptSection = resourceManager ? buildConnectorPromptSection(resourceManager) : "";
     let mcpServers;
     let workspacePluginToShutdown = null;
     let externalMcpManager = null;
     if (driverType === "claude-sdk") {
-      if (resourceManager) {
-        const connectorsLog = createLogger({ kind: "mcp", subkind: "skaile-connectors" });
-        try {
-          const server = await buildSdkConnectorTools(resourceManager, { z: z });
-          if (server) {
-            mcpServers = { "skaile-connectors": server };
-            connectorsLog.info("server constructed", {
-              connectorCount: resourceManager.listConnectors().length
-            });
-          } else {
-            connectorsLog.debug("server skipped (no tools to expose)");
-          }
-        } catch (err) {
-          connectorsLog.error("server construction failed", err);
-          throw err;
-        }
-      }
-      const workspacePlugin = new WorkspacePlugin({
+      const inProcess = await buildInProcessMcpServers(
+        resourceManager,
         projectDir,
-        connectorManager: resourceManager ?? void 0,
-        driver: driverType,
-        provider: sessionMeta?.provider,
-        model: sessionMeta?.model
-      });
-      const wsServer = await workspacePlugin.buildWorkspaceMcpServer();
-      if (wsServer) {
-        mcpServers = { ...mcpServers ?? {}, "skaile-workspace": wsServer };
-      }
-      workspacePluginToShutdown = workspacePlugin;
+        driverType,
+        sessionMeta
+      );
+      mcpServers = inProcess.mcpServers;
+      workspacePluginToShutdown = inProcess.workspacePluginToShutdown;
     }
     if (capabilityRegistry) {
-      const resolvedDecls = resolveExternalMcpDeclarations(projectDir, sessionMeta?.sessionId);
-      if (resolvedDecls.length > 0) {
-        externalMcpManager = new ExternalMcpManager(
-          capabilityRegistry,
-          secretProvider,
-          sessionMeta?.sessionId
-        );
-        await externalMcpManager.start(resolvedDecls);
-      }
+      externalMcpManager = await startExternalMcpServers(
+        capabilityRegistry,
+        projectDir,
+        secretProvider,
+        sessionMeta
+      );
     } else if (driverType === "claude-sdk") {
-      const mcpLog = createLogger({
-        kind: "mcp",
-        subkind: "wiring",
-        instance: sessionMeta?.sessionId ?? "no-session"
-      });
-      const resolvedDecls = resolveExternalMcpDeclarations(projectDir, sessionMeta?.sessionId);
-      for (const decl of resolvedDecls) {
-        const serverConfig = toSdkMcpServerConfig(
-          decl,
-          secretProvider
-        );
-        if (serverConfig) {
-          mcpServers = { ...mcpServers ?? {}, [decl.id]: serverConfig };
-          createLogger({ kind: "mcp", subkind: decl.id }).info("MCP server registered", {
-            transport: decl.transport ?? "stdio",
-            ...decl.transport === "stdio" || !decl.transport ? { command: decl.command, args: decl.args } : { url: decl.url }
-          });
-        } else {
-          mcpLog.error("MCP server config invalid (translation returned null)", void 0, {
-            id: decl.id,
-            transport: decl.transport
-          });
-        }
-      }
+      mcpServers = wireExternalMcpServersForSdk(
+        mcpServers,
+        projectDir,
+        secretProvider,
+        sessionMeta
+      );
     }
     if (!resourceManager && driverType !== "claude-sdk" && !externalMcpManager?.hasServers())
       return noopResult;
@@ -1306,6 +1243,120 @@ async function buildAgentResources(projectDir, driverType, _onLog, watch, secret
     return noopResult;
   }
 }
+async function maybeInstallNpmPeerDeps(runtimeAssets, projectDir, resLog) {
+  if (process.env.SKAILE_AUTO_INSTALL_DEPS === "true") {
+    const required = runtimeAssets.requiredNpmDeps.required;
+    if (required.length > 0) {
+      const missing = findMissingPackages(required, projectDir);
+      if (missing.length > 0) {
+        resLog.info("installing missing npm peer deps", { packages: missing });
+        const r = await installNpmPackages(missing, projectDir);
+        if (!r.success) resLog.error("npm install failed", void 0, { output: r.output });
+      }
+    }
+  }
+}
+function logConnectorReport(results, resLog) {
+  for (const r of results) {
+    if (r.connected) {
+      resLog.info("connector ok", { id: r.id, mountPath: r.mountPath });
+    } else {
+      resLog.error("connector failed", void 0, { id: r.id, error: r.error });
+    }
+  }
+}
+async function connectAllConnectors(connectorDeclarations, projectDir, runtimeAssets, secretProvider, tokenMediator, preMintedSecrets, deferFilesystemMounts, watch, resLog) {
+  const resourceManager = new ConnectorManager(projectDir, {
+    secrets: secretProvider,
+    catalogEntries: runtimeAssets.catalogEntries,
+    tokenMediator,
+    preMintedSecrets,
+    onStatusChange: watch?.onConnectorStatus
+  });
+  try {
+    const report = await resourceManager.connectAll(connectorDeclarations, {
+      failOnReadWriteError: true,
+      deferMounts: deferFilesystemMounts
+    });
+    logConnectorReport(report.results, resLog);
+  } catch (err) {
+    if (err instanceof ConnectorStartupError) {
+      logConnectorReport(err.report.results, resLog);
+    }
+    throw err;
+  }
+  return resourceManager;
+}
+async function buildInProcessMcpServers(resourceManager, projectDir, driverType, sessionMeta) {
+  let mcpServers;
+  if (resourceManager) {
+    const connectorsLog = createLogger({ kind: "mcp", subkind: "skaile-connectors" });
+    try {
+      const server = await buildSdkConnectorTools(resourceManager, { z: z });
+      if (server) {
+        mcpServers = { "skaile-connectors": server };
+        connectorsLog.info("server constructed", {
+          connectorCount: resourceManager.listConnectors().length
+        });
+      } else {
+        connectorsLog.debug("server skipped (no tools to expose)");
+      }
+    } catch (err) {
+      connectorsLog.error("server construction failed", err);
+      throw err;
+    }
+  }
+  const workspacePlugin = new WorkspacePlugin({
+    projectDir,
+    connectorManager: resourceManager ?? void 0,
+    driver: driverType,
+    provider: sessionMeta?.provider,
+    model: sessionMeta?.model
+  });
+  const wsServer = await workspacePlugin.buildWorkspaceMcpServer();
+  if (wsServer) {
+    mcpServers = { ...mcpServers ?? {}, "skaile-workspace": wsServer };
+  }
+  return { mcpServers, workspacePluginToShutdown: workspacePlugin };
+}
+async function startExternalMcpServers(capabilityRegistry, projectDir, secretProvider, sessionMeta) {
+  const resolvedDecls = resolveExternalMcpDeclarations(projectDir, sessionMeta?.sessionId);
+  if (resolvedDecls.length === 0) return null;
+  const externalMcpManager = new ExternalMcpManager(
+    capabilityRegistry,
+    secretProvider,
+    sessionMeta?.sessionId
+  );
+  await externalMcpManager.start(resolvedDecls);
+  return externalMcpManager;
+}
+function wireExternalMcpServersForSdk(mcpServers, projectDir, secretProvider, sessionMeta) {
+  const mcpLog = createLogger({
+    kind: "mcp",
+    subkind: "wiring",
+    instance: sessionMeta?.sessionId ?? "no-session"
+  });
+  const resolvedDecls = resolveExternalMcpDeclarations(projectDir, sessionMeta?.sessionId);
+  for (const decl of resolvedDecls) {
+    const serverConfig = toSdkMcpServerConfig(
+      decl,
+      secretProvider
+    );
+    if (serverConfig) {
+      mcpServers = { ...mcpServers ?? {}, [decl.id]: serverConfig };
+      createLogger({ kind: "mcp", subkind: decl.id }).info("MCP server registered", {
+        transport: decl.transport ?? "stdio",
+        ...decl.transport === "stdio" || !decl.transport ? { command: decl.command, args: decl.args } : { url: decl.url }
+      });
+    } else {
+      mcpLog.error("MCP server config invalid (translation returned null)", void 0, {
+        id: decl.id,
+        transport: decl.transport
+      });
+    }
+  }
+  return mcpServers;
+}
 function toSdkMcpServerConfig(decl, secrets) {
   const transport = decl.transport ?? "stdio";
   if (transport === "stdio") {
@@ -1401,45 +1452,17 @@ async function createAgentSession(config) {
       "externalPromptFile is deprecated and no longer injected; use agent.prompt-extensions in skaile.yaml instead"
     );
   }
-  let composition = null;
-  if (agentDir && manifest?.composes?.length) {
-    composition = await resolveAgentComposition({
-      agentDir,
-      manifest,
-      log: sessionLog
-    });
-  } else if (manifest?.composes?.length && !agentDir) {
-    sessionLog.debug("skipping composition resolution \u2014 no agentDir available");
-  }
+  const composition = await resolveSessionComposition(agentDir, manifest, projectDir, sessionLog);
   const compositionBlocks = composition?.inlineBlocks ?? [];
   const additionalSections = config.additionalPromptSections ?? [];
-  const systemPromptSections = [];
-  if (contextSection) systemPromptSections.push({ label: "context", value: contextSection });
-  if (userPromptSection) systemPromptSections.push({ label: "prompt", value: userPromptSection });
-  if (environmentSection)
-    systemPromptSections.push({ label: "environment", value: environmentSection });
-  if (resourcePromptSection)
-    systemPromptSections.push({ label: "resources", value: resourcePromptSection });
-  for (const ext of promptExtensions) {
-    systemPromptSections.push({
-      label: "prompt-extensions",
-      value: ext.value,
-      source: ext.source
-    });
-  }
-  for (const block of compositionBlocks) {
-    systemPromptSections.push({
-      label: "composition",
-      value: block.content,
-      source: block.ref
-    });
-  }
-  additionalSections.forEach((value, idx) => {
-    systemPromptSections.push({
-      label: "additional",
-      value,
-      source: `additional[${idx}]`
-    });
+  const systemPromptSections = buildSystemPromptSections({
+    contextSection,
+    userPromptSection,
+    environmentSection,
+    resourcePromptSection,
+    promptExtensions,
+    compositionBlocks,
+    additionalSections
   });
   const systemPrompt = assembleSystemPrompt([
     contextSection,
@@ -1450,36 +1473,26 @@ async function createAgentSession(config) {
     ...compositionBlocks.map((b) => b.content),
     ...additionalSections
   ]);
-  if (process.env.SKAILE_LOG_SYSTEM_PROMPT !== "0") {
-    const length = systemPrompt?.length ?? 0;
-    sessionLog.debug("assembled system prompt", { length });
-    sessionLog.debug("system prompt content", { content: systemPrompt ?? "(empty)" });
-  }
+  logAssembledSystemPrompt(systemPrompt, sessionLog);
   const thinking = config.thinking ?? wsConfig.agent_config?.default?.thinking;
   const effort = config.effort ?? wsConfig.agent_config?.default?.effort;
   const maxTurns = maxTurnsOverride ?? manifest?.runtime?.max_turns;
-  const driver = await createDriver(driverType, {
-    cwd: agentCwd,
+  const driver = await createSessionDriver({
+    config,
+    driverType,
+    agentCwd,
     provider,
-    model: model ?? manifest?.model?.preferred,
+    model,
+    manifest,
     maxTurns,
-    apiKeys: apiKey ? { [provider ?? "anthropic"]: apiKey } : void 0,
+    apiKey,
     systemPrompt,
-    tools: manifest?.tools,
-    ...thinking ? { thinking } : {},
-    ...effort ? { effort } : {},
-    ...sessionId ? { sessionId } : {},
-    ...resumeSessionId ? { resumeSessionId } : {},
-    ...mcpServers ? { mcpServers } : {},
-    // Protocol v2 capability dispatch hooks. When provided, the driver builds
-    // a synthetic `skaile-capabilities` MCP server alongside any existing
-    // mcpServers so capability invocations route through the registry's
-    // `invoke()` (which logs + validates + handles fire-and-forget / render).
-    ...config.capabilities ? { capabilities: config.capabilities } : {},
-    ...config.aiProviderConfigId ? { aiProviderConfigId: config.aiProviderConfigId } : {},
-    ...config.onAuthError ? { onAuthError: config.onAuthError } : {},
-    // Always forward agentDir/agentName for native identity handling
-    ...agentDir ? { agentDir, agentName: manifest?.name } : {}
+    thinking,
+    effort,
+    sessionId,
+    resumeSessionId,
+    mcpServers,
+    agentDir
   });
   if (telemetry && trace) {
     driver.setTelemetry(telemetry, trace);
@@ -1520,8 +1533,110 @@ function loadPromptExtensions(paths, projectDir, log) {
   }
   return result;
 }
-
-// runner/src/agent.ts
+async function resolveSessionComposition(agentDir, manifest, projectDir, log) {
+  if (agentDir && manifest?.composes?.length) {
+    return resolveAgentComposition({
+      agentDir,
+      manifest,
+      log
+    });
+  }
+  if (manifest?.composes?.length && !agentDir) {
+    log.debug("skipping composition resolution \u2014 no agentDir available");
+  }
+  return null;
+}
+function buildSystemPromptSections(parts) {
+  const {
+    contextSection,
+    userPromptSection,
+    environmentSection,
+    resourcePromptSection,
+    promptExtensions,
+    compositionBlocks,
+    additionalSections
+  } = parts;
+  const systemPromptSections = [];
+  if (contextSection) systemPromptSections.push({ label: "context", value: contextSection });
+  if (userPromptSection) systemPromptSections.push({ label: "prompt", value: userPromptSection });
+  if (environmentSection)
+    systemPromptSections.push({ label: "environment", value: environmentSection });
+  if (resourcePromptSection)
+    systemPromptSections.push({ label: "resources", value: resourcePromptSection });
+  for (const ext of promptExtensions) {
+    systemPromptSections.push({
+      label: "prompt-extensions",
+      value: ext.value,
+      source: ext.source
+    });
+  }
+  for (const block of compositionBlocks) {
+    systemPromptSections.push({
+      label: "composition",
+      value: block.content,
+      source: block.ref
+    });
+  }
+  additionalSections.forEach((value, idx) => {
+    systemPromptSections.push({
+      label: "additional",
+      value,
+      source: `additional[${idx}]`
+    });
+  });
+  return systemPromptSections;
+}
+function logAssembledSystemPrompt(systemPrompt, log) {
+  if (process.env.SKAILE_LOG_SYSTEM_PROMPT !== "0") {
+    const length = systemPrompt?.length ?? 0;
+    log.debug("assembled system prompt", { length });
+    log.debug("system prompt content", { content: systemPrompt ?? "(empty)" });
+  }
+}
+function createSessionDriver(args) {
+  const {
+    config,
+    driverType,
+    agentCwd,
+    provider,
+    model,
+    manifest,
+    maxTurns,
+    apiKey,
+    systemPrompt,
+    thinking,
+    effort,
+    sessionId,
+    resumeSessionId,
+    mcpServers,
+    agentDir
+  } = args;
+  return createDriver(driverType, {
+    cwd: agentCwd,
+    provider,
+    model: model ?? manifest?.model?.preferred,
+    maxTurns,
+    apiKeys: apiKey ? { [provider ?? "anthropic"]: apiKey } : void 0,
+    systemPrompt,
+    tools: manifest?.tools,
+    ...thinking ? { thinking } : {},
+    ...effort ? { effort } : {},
+    ...sessionId ? { sessionId } : {},
+    ...resumeSessionId ? { resumeSessionId } : {},
+    ...mcpServers ? { mcpServers } : {},
+    // Protocol v2 capability dispatch hooks. When provided, the driver builds
+    // a synthetic `skaile-capabilities` MCP server alongside any existing
+    // mcpServers so capability invocations route through the registry's
+    // `invoke()` (which logs + validates + handles fire-and-forget / render).
+    ...config.capabilities ? { capabilities: config.capabilities } : {},
+    ...config.aiProviderConfigId ? { aiProviderConfigId: config.aiProviderConfigId } : {},
+    ...config.onAuthError ? { onAuthError: config.onAuthError } : {},
+    // Always forward agentDir/agentName for native identity handling
+    ...agentDir ? { agentDir, agentName: manifest?.name } : {}
+  });
+}
+
+// runner/src/agent.ts
 var PROMPT_AGENT = `${pc.magenta(pc.bold("agent"))} ${pc.dim("\u25B6")} `;
 async function runAgentChat(opts) {
   const sessionId = `chat-${Date.now().toString(36)}`;
@@ -1601,345 +1716,134 @@ async function buildDriver(opts) {
     onLog: opts.onLog
   });
 }
-async function handleResourceRequest(command, manager, emit) {
-  const { requestId, connectorId, operation, path: path5, options, content } = command;
-  try {
-    let data;
-    switch (operation) {
-      case "list":
-        data = await manager.list(
-          connectorId,
-          path5,
-          options
-        );
-        break;
-      case "read":
-        data = await manager.read(connectorId, path5);
-        break;
-      case "write":
-        await manager.write(connectorId, path5, content);
-        data = true;
-        break;
-      case "delete":
-        data = await manager.delete(connectorId, path5);
-        break;
-      case "search":
-        data = await manager.search(
-          connectorId,
-          path5,
-          options
-        );
-        break;
+function keywordSearch(capabilities, query, limit) {
+  const tokens = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+  if (tokens.length === 0) return capabilities.slice(0, limit);
+  const scored = capabilities.map((cap) => {
+    const haystack = [cap.name, cap.description, cap.promptFragment ?? ""].join(" ").toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+      if (haystack.includes(token)) score += 1;
     }
-    emit({ type: "resource_response", requestId, resourceId: connectorId, operation, data });
-  } catch (err) {
-    emit({
-      type: "resource_response",
-      requestId,
-      resourceId: connectorId,
-      operation,
-      error: err instanceof Error ? err.message : String(err)
-    });
+    return { cap, score };
+  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit).map((x) => x.cap);
+}
+function builtinCapabilities(registry) {
+  const listFilterSchema = z5.strictObject({
+    side: z5.enum(["client", "agent"]).optional(),
+    originKind: z5.enum(["framework", "client", "agent", "flow", "skill", "mcp", "connector", "mount"]).optional(),
+    scope: z5.enum(["session", "turn"]).optional()
+  });
+  return [
+    defineCapability({
+      name: "__capabilities.list",
+      displayName: "List capabilities",
+      description: "List available capabilities in this session. Optionally filter by side, origin kind, or scope.",
+      side: "agent",
+      origin: { kind: "framework" },
+      kind: "query",
+      userInvokable: false,
+      input: listFilterSchema,
+      handler: async (args) => registry.list({
+        side: args.side,
+        origin: args.originKind,
+        scope: args.scope
+      })
+    }),
+    defineCapability({
+      name: "__capabilities.search",
+      displayName: "Search capabilities",
+      description: "Keyword search across capability names, descriptions, and prompt fragments. Returns the top matches by score (substring match count).",
+      side: "agent",
+      origin: { kind: "framework" },
+      kind: "query",
+      userInvokable: false,
+      input: z5.strictObject({
+        query: z5.string(),
+        limit: z5.number().int().positive().optional()
+      }),
+      handler: async ({ query, limit }) => keywordSearch(registry.list(), query, limit ?? 10)
+    }),
+    defineCapability({
+      name: "__capabilities.describe",
+      displayName: "Describe capability",
+      description: "Return the full Capability descriptor for a single capability by name.",
+      side: "agent",
+      origin: { kind: "framework" },
+      kind: "query",
+      userInvokable: false,
+      input: z5.strictObject({ name: z5.string() }),
+      handler: async ({ name }) => {
+        const cap = registry.resolve(name);
+        if (!cap) return null;
+        const wire = registry.list().find((c) => c.name === name);
+        return wire ?? null;
+      }
+    })
+  ];
+}
+function bootstrapCapabilityRegistry(registry) {
+  for (const cap of builtinCapabilities(registry)) {
+    registry.register(cap, "agent");
   }
 }
-function getMimeType(filename) {
-  return mime.getType(filename) ?? "application/octet-stream";
+var DEFAULT_AUDIENCE = ["llm", "user"];
+function audienceOf(cap) {
+  return cap.audience ?? DEFAULT_AUDIENCE;
 }
-function isBinaryFile(filePath) {
-  try {
-    const fd = openSync(filePath, "r");
-    const buf = Buffer.alloc(8192);
-    const bytesRead = readSync(fd, buf, 0, 8192, 0);
-    closeSync(fd);
-    for (let i = 0; i < bytesRead; i++) {
-      if (buf[i] === 0) return true;
+function hasAudience(cap, target) {
+  return audienceOf(cap).includes(target);
+}
+var ORIGIN_PROMPT_ORDER = [
+  "framework",
+  "client",
+  "agent",
+  "flow",
+  "skill",
+  "mcp",
+  "connector",
+  "mount"
+];
+var CapabilityRegistry = class {
+  byName = /* @__PURE__ */ new Map();
+  logger;
+  remoteInvoker;
+  constructor(logger) {
+    this.logger = logger ?? createLogger({ kind: "runner", subkind: "capability-registry" });
+  }
+  /**
+   * Install the platform-bound invoker used by {@link invokeRemote}.
+   *
+   * The runner wires this up after the transport is connected and the
+   * per-session pending-call map is in place. Idempotent — repeated calls
+   * replace the prior invoker.
+   *
+   * @category Runtime
+   * @since 3.0.0
+   */
+  setRemoteInvoker(invoker) {
+    this.remoteInvoker = invoker;
+  }
+  /**
+   * Invoke a `host.*` (or other peer-side) capability on the platform.
+   *
+   * Composes a `capability_invoked` event under the hood and resolves with
+   * the matching `capability_result` payload. Infrastructure failures
+   * (timeout, schema mismatch, transport disconnect) reject with `Error`;
+   * domain failures (e.g. `{ ok: false, code }` for credential mints) ride
+   * in the resolved payload.
+   *
+   * @category Runtime
+   * @since 3.0.0
+   */
+  async invokeRemote(name, input) {
+    if (!this.remoteInvoker) {
+      throw new Error(
+        `Capability '${name}' invoked remotely but no remote invoker is wired. Call CapabilityRegistry.setRemoteInvoker(...) before dispatch.`
+      );
     }
-    return false;
-  } catch {
-    return false;
-  }
-}
-function handleMountResourceRequest(command, manager, emit) {
-  const { requestId, connectorId: mountId, operation, path: reqPath, content } = command;
-  try {
-    const entry = manager.get(mountId);
-    const mountPath = entry.handle.mountPath;
-    if (!mountPath) {
-      throw new Error(`Connector "${mountId}" has no projected mount directory`);
-    }
-    const targetPath = reqPath ? resolve(mountPath, reqPath) : mountPath;
-    const rel = relative(mountPath, targetPath);
-    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-      throw new Error("Path traversal outside mount");
-    }
-    let data;
-    switch (operation) {
-      case "list": {
-        const entries = readdirSync(targetPath, { withFileTypes: true });
-        data = entries.filter((e) => !e.name.startsWith(".")).map((e) => {
-          const entryPath = reqPath ? join(reqPath, e.name) : e.name;
-          const result = {
-            name: e.name,
-            path: entryPath,
-            type: e.isDirectory() ? "directory" : "file"
-          };
-          if (!e.isDirectory()) {
-            try {
-              result.size = statSync(join(targetPath, e.name)).size;
-            } catch {
-            }
-          }
-          return result;
-        });
-        break;
-      }
-      case "read": {
-        const contentType = getMimeType(basename(targetPath));
-        if (isBinaryFile(targetPath)) {
-          const buf = readFileSync(targetPath);
-          data = {
-            data: buf.toString("base64"),
-            contentType,
-            encoding: "binary"
-          };
-        } else {
-          data = {
-            data: readFileSync(targetPath, "utf-8"),
-            contentType,
-            encoding: "utf-8"
-          };
-        }
-        break;
-      }
-      case "write": {
-        mkdirSync(dirname(targetPath), { recursive: true });
-        const writeContent = typeof content === "string" ? content : content?.data ?? "";
-        const encoding = typeof content === "string" ? void 0 : content?.encoding;
-        if (encoding === "binary") {
-          writeFileSync(targetPath, Buffer.from(writeContent, "base64"));
-        } else {
-          writeFileSync(targetPath, writeContent, "utf-8");
-        }
-        data = true;
-        break;
-      }
-      case "delete": {
-        unlinkSync(targetPath);
-        data = true;
-        break;
-      }
-      default:
-        throw new Error(`Unsupported operation for mount: ${operation}`);
-    }
-    emit({ type: "resource_response", requestId, resourceId: mountId, operation, data });
-  } catch (err) {
-    emit({
-      type: "resource_response",
-      requestId,
-      resourceId: mountId,
-      operation,
-      error: err instanceof Error ? err.message : String(err)
-    });
-  }
-}
-
-// runner/src/ai-credential-refresh.ts
-var PROACTIVE_AI_REFRESH_MARGIN_MS = 5 * 60 * 1e3;
-function createAiCredentialRefreshScheduler(deps) {
-  const now = deps.now ?? (() => Date.now());
-  const setTimeoutImpl = deps.setTimeoutImpl ?? ((handler, ms) => {
-    const handle = setTimeout(handler, ms);
-    return handle;
-  });
-  const clearTimeoutImpl = deps.clearTimeoutImpl ?? ((handle) => {
-    clearTimeout(handle);
-  });
-  const marginMs = deps.marginMs ?? PROACTIVE_AI_REFRESH_MARGIN_MS;
-  let timer = null;
-  function cancel() {
-    if (timer !== null) {
-      clearTimeoutImpl(timer);
-      timer = null;
-    }
-  }
-  async function fire() {
-    timer = null;
-    let next;
-    try {
-      next = await deps.refresh();
-    } catch (err) {
-      deps.log(
-        `[ai-credential-refresh] refresh threw: ${err instanceof Error ? err.message : String(err)}; reactive 401 path remains as safety net`
-      );
-      return;
-    }
-    if (next === void 0) {
-      deps.log(
-        "[ai-credential-refresh] refresh returned no expiry; reactive 401 path remains as safety net"
-      );
-      return;
-    }
-    schedule(next);
-  }
-  function schedule(expiresAtIso) {
-    cancel();
-    if (!expiresAtIso) {
-      return;
-    }
-    const expiresAtMs = Date.parse(expiresAtIso);
-    if (!Number.isFinite(expiresAtMs)) return;
-    const delayMs = expiresAtMs - now() - marginMs;
-    if (delayMs <= 0) {
-      deps.log(
-        `[ai-credential-refresh] token within ${marginMs / 1e3}s of expiry; refreshing now`
-      );
-      timer = setTimeoutImpl(() => {
-        void fire();
-      }, 0);
-    } else {
-      deps.log(
-        `[ai-credential-refresh] scheduled in ${Math.round(delayMs / 1e3)}s (expiresAt=${expiresAtIso})`
-      );
-      timer = setTimeoutImpl(() => {
-        void fire();
-      }, delayMs);
-    }
-    timer.unref?.();
-  }
-  return {
-    schedule,
-    cancel,
-    isPending: () => timer !== null
-  };
-}
-function keywordSearch(capabilities, query, limit) {
-  const tokens = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
-  if (tokens.length === 0) return capabilities.slice(0, limit);
-  const scored = capabilities.map((cap) => {
-    const haystack = [cap.name, cap.description, cap.promptFragment ?? ""].join(" ").toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (haystack.includes(token)) score += 1;
-    }
-    return { cap, score };
-  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score);
-  return scored.slice(0, limit).map((x) => x.cap);
-}
-function builtinCapabilities(registry) {
-  const listFilterSchema = z5.strictObject({
-    side: z5.enum(["client", "agent"]).optional(),
-    originKind: z5.enum(["framework", "client", "agent", "flow", "skill", "mcp", "connector", "mount"]).optional(),
-    scope: z5.enum(["session", "turn"]).optional()
-  });
-  return [
-    defineCapability({
-      name: "__capabilities.list",
-      displayName: "List capabilities",
-      description: "List available capabilities in this session. Optionally filter by side, origin kind, or scope.",
-      side: "agent",
-      origin: { kind: "framework" },
-      kind: "query",
-      userInvokable: false,
-      input: listFilterSchema,
-      handler: async (args) => registry.list({
-        side: args.side,
-        origin: args.originKind,
-        scope: args.scope
-      })
-    }),
-    defineCapability({
-      name: "__capabilities.search",
-      displayName: "Search capabilities",
-      description: "Keyword search across capability names, descriptions, and prompt fragments. Returns the top matches by score (substring match count).",
-      side: "agent",
-      origin: { kind: "framework" },
-      kind: "query",
-      userInvokable: false,
-      input: z5.strictObject({
-        query: z5.string(),
-        limit: z5.number().int().positive().optional()
-      }),
-      handler: async ({ query, limit }) => keywordSearch(registry.list(), query, limit ?? 10)
-    }),
-    defineCapability({
-      name: "__capabilities.describe",
-      displayName: "Describe capability",
-      description: "Return the full Capability descriptor for a single capability by name.",
-      side: "agent",
-      origin: { kind: "framework" },
-      kind: "query",
-      userInvokable: false,
-      input: z5.strictObject({ name: z5.string() }),
-      handler: async ({ name }) => {
-        const cap = registry.resolve(name);
-        if (!cap) return null;
-        const wire = registry.list().find((c) => c.name === name);
-        return wire ?? null;
-      }
-    })
-  ];
-}
-function bootstrapCapabilityRegistry(registry) {
-  for (const cap of builtinCapabilities(registry)) {
-    registry.register(cap, "agent");
-  }
-}
-var DEFAULT_AUDIENCE = ["llm", "user"];
-function audienceOf(cap) {
-  return cap.audience ?? DEFAULT_AUDIENCE;
-}
-function hasAudience(cap, target) {
-  return audienceOf(cap).includes(target);
-}
-var ORIGIN_PROMPT_ORDER = [
-  "framework",
-  "client",
-  "agent",
-  "flow",
-  "skill",
-  "mcp",
-  "connector",
-  "mount"
-];
-var CapabilityRegistry = class {
-  byName = /* @__PURE__ */ new Map();
-  logger;
-  remoteInvoker;
-  constructor(logger) {
-    this.logger = logger ?? createLogger({ kind: "runner", subkind: "capability-registry" });
-  }
-  /**
-   * Install the platform-bound invoker used by {@link invokeRemote}.
-   *
-   * The runner wires this up after the transport is connected and the
-   * per-session pending-call map is in place. Idempotent — repeated calls
-   * replace the prior invoker.
-   *
-   * @category Runtime
-   * @since 3.0.0
-   */
-  setRemoteInvoker(invoker) {
-    this.remoteInvoker = invoker;
-  }
-  /**
-   * Invoke a `host.*` (or other peer-side) capability on the platform.
-   *
-   * Composes a `capability_invoked` event under the hood and resolves with
-   * the matching `capability_result` payload. Infrastructure failures
-   * (timeout, schema mismatch, transport disconnect) reject with `Error`;
-   * domain failures (e.g. `{ ok: false, code }` for credential mints) ride
-   * in the resolved payload.
-   *
-   * @category Runtime
-   * @since 3.0.0
-   */
-  async invokeRemote(name, input) {
-    if (!this.remoteInvoker) {
-      throw new Error(
-        `Capability '${name}' invoked remotely but no remote invoker is wired. Call CapabilityRegistry.setRemoteInvoker(...) before dispatch.`
-      );
-    }
-    return this.remoteInvoker(name, input, this.byName.get(name)?.callTimeoutMs);
+    return this.remoteInvoker(name, input, this.byName.get(name)?.callTimeoutMs);
   }
   /**
    * Register a capability. Validates that the registering `source` is
@@ -2218,34 +2122,227 @@ function resolveCapabilityResult(pending, cmd) {
   } else {
     entry.resolve(result);
   }
-  return true;
-}
-function rejectCapabilityOnApprovalDeny(pending, callId, feedback) {
-  const entry = pending.get(callId);
-  if (!entry) return false;
-  clearTimeout(entry.timer);
-  pending.delete(callId);
-  entry.reject(new Error(feedback ?? "declined by user"));
-  return true;
-}
-
-// runner/src/compaction/strategy.ts
-var TokenThresholdStrategy = class {
-  thresholdPercent;
-  minCooldownMs;
-  constructor(opts) {
-    this.thresholdPercent = opts.thresholdPercent;
-    this.minCooldownMs = opts.minCooldownMs;
+  return true;
+}
+function rejectCapabilityOnApprovalDeny(pending, callId, feedback) {
+  const entry = pending.get(callId);
+  if (!entry) return false;
+  clearTimeout(entry.timer);
+  pending.delete(callId);
+  entry.reject(new Error(feedback ?? "declined by user"));
+  return true;
+}
+async function handleResourceRequest(command, manager, emit) {
+  const { requestId, connectorId, operation, path: path5, options, content } = command;
+  try {
+    let data;
+    switch (operation) {
+      case "list":
+        data = await manager.list(
+          connectorId,
+          path5,
+          options
+        );
+        break;
+      case "read":
+        data = await manager.read(connectorId, path5);
+        break;
+      case "write":
+        await manager.write(connectorId, path5, content);
+        data = true;
+        break;
+      case "delete":
+        data = await manager.delete(connectorId, path5);
+        break;
+      case "search":
+        data = await manager.search(
+          connectorId,
+          path5,
+          options
+        );
+        break;
+    }
+    emit({ type: "resource_response", requestId, resourceId: connectorId, operation, data });
+  } catch (err) {
+    emit({
+      type: "resource_response",
+      requestId,
+      resourceId: connectorId,
+      operation,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function getMimeType(filename) {
+  return mime.getType(filename) ?? "application/octet-stream";
+}
+function isBinaryFile(filePath) {
+  try {
+    const fd = openSync(filePath, "r");
+    const buf = Buffer.alloc(8192);
+    const bytesRead = readSync(fd, buf, 0, 8192, 0);
+    closeSync(fd);
+    for (let i = 0; i < bytesRead; i++) {
+      if (buf[i] === 0) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function handleMountResourceRequest(command, manager, emit) {
+  const { requestId, connectorId: mountId, operation, path: reqPath, content } = command;
+  try {
+    const entry = manager.get(mountId);
+    const mountPath = entry.handle.mountPath;
+    if (!mountPath) {
+      throw new Error(`Connector "${mountId}" has no projected mount directory`);
+    }
+    const targetPath = reqPath ? resolve(mountPath, reqPath) : mountPath;
+    const rel = relative(mountPath, targetPath);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      throw new Error("Path traversal outside mount");
+    }
+    let data;
+    switch (operation) {
+      case "list": {
+        const entries = readdirSync(targetPath, { withFileTypes: true });
+        data = entries.filter((e) => !e.name.startsWith(".")).map((e) => {
+          const entryPath = reqPath ? join(reqPath, e.name) : e.name;
+          const result = {
+            name: e.name,
+            path: entryPath,
+            type: e.isDirectory() ? "directory" : "file"
+          };
+          if (!e.isDirectory()) {
+            try {
+              result.size = statSync(join(targetPath, e.name)).size;
+            } catch {
+            }
+          }
+          return result;
+        });
+        break;
+      }
+      case "read": {
+        const contentType = getMimeType(basename(targetPath));
+        if (isBinaryFile(targetPath)) {
+          const buf = readFileSync(targetPath);
+          data = {
+            data: buf.toString("base64"),
+            contentType,
+            encoding: "binary"
+          };
+        } else {
+          data = {
+            data: readFileSync(targetPath, "utf-8"),
+            contentType,
+            encoding: "utf-8"
+          };
+        }
+        break;
+      }
+      case "write": {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        const writeContent = typeof content === "string" ? content : content?.data ?? "";
+        const encoding = typeof content === "string" ? void 0 : content?.encoding;
+        if (encoding === "binary") {
+          writeFileSync(targetPath, Buffer.from(writeContent, "base64"));
+        } else {
+          writeFileSync(targetPath, writeContent, "utf-8");
+        }
+        data = true;
+        break;
+      }
+      case "delete": {
+        unlinkSync(targetPath);
+        data = true;
+        break;
+      }
+      default:
+        throw new Error(`Unsupported operation for mount: ${operation}`);
+    }
+    emit({ type: "resource_response", requestId, resourceId: mountId, operation, data });
+  } catch (err) {
+    emit({
+      type: "resource_response",
+      requestId,
+      resourceId: mountId,
+      operation,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+
+// runner/src/ai-credential-refresh.ts
+var PROACTIVE_AI_REFRESH_MARGIN_MS = 5 * 60 * 1e3;
+function createAiCredentialRefreshScheduler(deps) {
+  const now = deps.now ?? (() => Date.now());
+  const setTimeoutImpl = deps.setTimeoutImpl ?? ((handler, ms) => {
+    const handle = setTimeout(handler, ms);
+    return handle;
+  });
+  const clearTimeoutImpl = deps.clearTimeoutImpl ?? ((handle) => {
+    clearTimeout(handle);
+  });
+  const marginMs = deps.marginMs ?? PROACTIVE_AI_REFRESH_MARGIN_MS;
+  let timer = null;
+  function cancel() {
+    if (timer !== null) {
+      clearTimeoutImpl(timer);
+      timer = null;
+    }
+  }
+  async function fire() {
+    timer = null;
+    let next;
+    try {
+      next = await deps.refresh();
+    } catch (err) {
+      deps.log(
+        `[ai-credential-refresh] refresh threw: ${err instanceof Error ? err.message : String(err)}; reactive 401 path remains as safety net`
+      );
+      return;
+    }
+    if (next === void 0) {
+      deps.log(
+        "[ai-credential-refresh] refresh returned no expiry; reactive 401 path remains as safety net"
+      );
+      return;
+    }
+    schedule(next);
   }
-  shouldCompact(context) {
-    const fillPercent = context.estimatedTokens / context.contextWindow * 100;
-    if (fillPercent < this.thresholdPercent) return false;
-    if (context.timeSinceLastCompaction !== null && context.timeSinceLastCompaction < this.minCooldownMs) {
-      return false;
+  function schedule(expiresAtIso) {
+    cancel();
+    if (!expiresAtIso) {
+      return;
     }
-    return true;
+    const expiresAtMs = Date.parse(expiresAtIso);
+    if (!Number.isFinite(expiresAtMs)) return;
+    const delayMs = expiresAtMs - now() - marginMs;
+    if (delayMs <= 0) {
+      deps.log(
+        `[ai-credential-refresh] token within ${marginMs / 1e3}s of expiry; refreshing now`
+      );
+      timer = setTimeoutImpl(() => {
+        void fire();
+      }, 0);
+    } else {
+      deps.log(
+        `[ai-credential-refresh] scheduled in ${Math.round(delayMs / 1e3)}s (expiresAt=${expiresAtIso})`
+      );
+      timer = setTimeoutImpl(() => {
+        void fire();
+      }, delayMs);
+    }
+    timer.unref?.();
   }
-};
+  return {
+    schedule,
+    cancel,
+    isPending: () => timer !== null
+  };
+}
 
 // runner/src/compaction/prompt.ts
 var DEFAULT_COMPACTION_PROMPT = `You are being asked to compact this conversation into a structured summary.
@@ -2325,6 +2422,24 @@ ${opts.focus}`);
   return parts.join("");
 }
 
+// runner/src/compaction/strategy.ts
+var TokenThresholdStrategy = class {
+  thresholdPercent;
+  minCooldownMs;
+  constructor(opts) {
+    this.thresholdPercent = opts.thresholdPercent;
+    this.minCooldownMs = opts.minCooldownMs;
+  }
+  shouldCompact(context) {
+    const fillPercent = context.estimatedTokens / context.contextWindow * 100;
+    if (fillPercent < this.thresholdPercent) return false;
+    if (context.timeSinceLastCompaction !== null && context.timeSinceLastCompaction < this.minCooldownMs) {
+      return false;
+    }
+    return true;
+  }
+};
+
 // runner/src/compaction/orchestrator.ts
 var MIN_SUMMARY_CHARS = 200;
 var MAX_COMPRESSION_RATIO = 0.9;
@@ -2370,9 +2485,6 @@ var CompactionOrchestrator = class {
       minCooldownMs: this.config.minCooldownMs
     });
   }
-  get hasNewMessagesSinceCompaction() {
-    return this.messagesSinceCompaction > 0;
-  }
   trackMessage(seq) {
     this.currentSeq = seq;
     this.messagesSinceCompaction++;
@@ -2406,6 +2518,17 @@ var CompactionOrchestrator = class {
     const driverProvider = this.driver.driverInfo?.id ?? null;
     const coversFromSeq = this.lastCompactionSeq ?? 0;
     const capabilitySignatureAtCompaction = this.opts.getCurrentCapabilitySignature?.() ?? null;
+    const attemptBase = {
+      trigger,
+      model: driverModel,
+      provider: driverProvider,
+      inputTokens: tokensBefore,
+      coversFromSeq,
+      coversToSeq: this.currentSeq,
+      driverSessionIdAtCompaction: driverSessionId,
+      modelAtCompaction: driverModel,
+      capabilitySignatureAtCompaction
+    };
     this.opts.onCompactionStart?.(trigger);
     this.opts.onLog?.(`[compaction] Starting (trigger=${trigger}, tokens=${tokensBefore})`);
     const prompt = buildCompactionPrompt({
@@ -2414,6 +2537,33 @@ var CompactionOrchestrator = class {
       mcpDirectives: this.opts.mcpDirectives,
       focus
     });
+    const { summaryText, promptError } = await this._runCompactionPrompt(prompt);
+    if (promptError !== null) {
+      this._emitThrownFailure(attemptBase, promptError);
+      return null;
+    }
+    const actualUsage = this.driver.getTokenUsage();
+    const tokensAfter = actualUsage?.outputTokens ?? Math.ceil(summaryText.length / 4);
+    const validation = validateCompactionOutput(summaryText, tokensBefore, tokensAfter);
+    if (!validation.ok) {
+      this._emitValidationFailure(attemptBase, validation.errorCode, tokensAfter);
+      return null;
+    }
+    return await this._completeCompaction(
+      attemptBase,
+      trigger,
+      summaryText,
+      tokensBefore,
+      tokensAfter,
+      coversFromSeq
+    );
+  }
+  /**
+   * Drive the compaction `prompt()` call, capturing summary text from the
+   * driver's raw bridge-level events and any thrown error. The listener is
+   * always removed in `finally`.
+   */
+  async _runCompactionPrompt(prompt) {
     let summaryText = "";
     const captureHandler = (raw) => {
       const event = raw;
@@ -2444,59 +2594,55 @@ var CompactionOrchestrator = class {
     } finally {
       this.driver.removeListener("agent-event", captureHandler);
     }
-    if (promptError !== null) {
-      const classified = classifyClaudeSdkError(
-        promptError instanceof Error ? promptError.message : String(promptError)
-      );
-      const errorCode = classified.category === "rate_limit" ? "rate_limit" : classified.category === "auth" ? "auth" : classified.category === "network" ? "timeout" : classified.category === "validation" ? "parse_error" : classified.category;
-      this.opts.onLog?.(`[compaction] Failed: ${classified.message} (${errorCode})`);
-      this.opts.onCompactionAttempt?.({
-        type: "compaction_attempt",
-        status: "failed",
-        errorCode,
-        trigger,
-        summary: "",
-        model: driverModel,
-        provider: driverProvider,
-        inputTokens: tokensBefore,
-        outputTokens: 0,
-        coversFromSeq,
-        coversToSeq: this.currentSeq,
-        driverSessionIdAtCompaction: driverSessionId,
-        modelAtCompaction: driverModel,
-        capabilitySignatureAtCompaction,
-        validatedAt: null
-      });
-      this.opts.onCompactionEnd?.();
-      return null;
-    }
-    const actualUsage = this.driver.getTokenUsage();
-    const tokensAfter = actualUsage?.outputTokens ?? Math.ceil(summaryText.length / 4);
-    const validation = validateCompactionOutput(summaryText, tokensBefore, tokensAfter);
-    if (!validation.ok) {
-      this.opts.onLog?.(
-        `[compaction] Output failed validation (${validation.errorCode}); recording failed attempt`
-      );
-      this.opts.onCompactionAttempt?.({
-        type: "compaction_attempt",
-        status: "failed",
-        errorCode: validation.errorCode,
-        trigger,
-        summary: "",
-        model: driverModel,
-        provider: driverProvider,
-        inputTokens: tokensBefore,
-        outputTokens: tokensAfter,
-        coversFromSeq,
-        coversToSeq: this.currentSeq,
-        driverSessionIdAtCompaction: driverSessionId,
-        modelAtCompaction: driverModel,
-        capabilitySignatureAtCompaction,
-        validatedAt: null
-      });
-      this.opts.onCompactionEnd?.();
-      return null;
-    }
+    return { summaryText, promptError };
+  }
+  /**
+   * Record a `failed` attempt for a thrown `prompt()` error: classify the
+   * error, map it to an error code, log, emit the attempt event, and signal
+   * compaction end.
+   */
+  _emitThrownFailure(attemptBase, promptError) {
+    const classified = classifyClaudeSdkError(
+      promptError instanceof Error ? promptError.message : String(promptError)
+    );
+    const errorCode = classified.category === "rate_limit" ? "rate_limit" : classified.category === "auth" ? "auth" : classified.category === "network" ? "timeout" : classified.category === "validation" ? "parse_error" : classified.category;
+    this.opts.onLog?.(`[compaction] Failed: ${classified.message} (${errorCode})`);
+    this.opts.onCompactionAttempt?.({
+      type: "compaction_attempt",
+      status: "failed",
+      errorCode,
+      summary: "",
+      outputTokens: 0,
+      validatedAt: null,
+      ...attemptBase
+    });
+    this.opts.onCompactionEnd?.();
+  }
+  /**
+   * Record a `failed` attempt for output that passed `prompt()` but failed
+   * structural validation. Logs, emits the attempt event, and signals
+   * compaction end.
+   */
+  _emitValidationFailure(attemptBase, errorCode, tokensAfter) {
+    this.opts.onLog?.(
+      `[compaction] Output failed validation (${errorCode}); recording failed attempt`
+    );
+    this.opts.onCompactionAttempt?.({
+      type: "compaction_attempt",
+      status: "failed",
+      errorCode,
+      summary: "",
+      outputTokens: tokensAfter,
+      validatedAt: null,
+      ...attemptBase
+    });
+    this.opts.onCompactionEnd?.();
+  }
+  /**
+   * Success path: emit the attempt + snapshot events, update internal state,
+   * and (unless hibernating) reset the driver and inject the snapshot.
+   */
+  async _completeCompaction(attemptBase, trigger, summaryText, tokensBefore, tokensAfter, coversFromSeq) {
     const validatedAt = (/* @__PURE__ */ new Date()).toISOString();
     const snapshot = {
       type: "snapshot",
@@ -2511,18 +2657,10 @@ var CompactionOrchestrator = class {
       type: "compaction_attempt",
       status: "success",
       errorCode: null,
-      trigger,
       summary: summaryText,
-      model: driverModel,
-      provider: driverProvider,
-      inputTokens: tokensBefore,
       outputTokens: tokensAfter,
-      coversFromSeq,
-      coversToSeq: this.currentSeq,
-      driverSessionIdAtCompaction: driverSessionId,
-      modelAtCompaction: driverModel,
-      capabilitySignatureAtCompaction,
-      validatedAt
+      validatedAt,
+      ...attemptBase
     });
     this.opts.onSnapshot?.(snapshot);
     this.lastCompactionSeq = this.currentSeq + 1;
@@ -2545,11 +2683,6 @@ The conversation has been compacted. The above snapshot contains the full contex
     );
     return snapshot;
   }
-  initFromSnapshot(lastSnapshotSeq, lastSnapshotTime) {
-    this.lastCompactionSeq = lastSnapshotSeq;
-    this.lastCompactionTime = lastSnapshotTime;
-    this.messagesSinceCompaction = 0;
-  }
 };
 function rewriteFileChangedPath(event, cwd, mounts) {
   if (event.type !== "file_changed") return event;
@@ -2782,6 +2915,54 @@ function buildRunnerCapabilities(handlers) {
     })
   ];
 }
+var CLAUDE_CODE_CREDENTIALS_KEY = "CLAUDE_CODE_CREDENTIALS_JSON";
+async function writeClaudeCodeCredentialsFile(home, json) {
+  const claudeDir = join(home, ".claude");
+  await mkdir(claudeDir, { recursive: true, mode: 448 });
+  const finalPath = join(claudeDir, ".credentials.json");
+  const tmpPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+  await writeFile(tmpPath, json, { mode: 384 });
+  await rename(tmpPath, finalPath);
+  return finalPath;
+}
+async function mergeAndRewriteCredentialsFile(home, accessToken, expiresAt) {
+  const credPath = join(home, ".claude", ".credentials.json");
+  let merged = {};
+  if (existsSync(credPath)) {
+    try {
+      merged = JSON.parse(readFileSync(credPath, "utf-8"));
+    } catch {
+      merged = {};
+    }
+  }
+  const oauthBlock = merged.claudeAiOauth ?? {};
+  oauthBlock.accessToken = accessToken;
+  if (expiresAt) oauthBlock.expiresAt = expiresAt;
+  merged.claudeAiOauth = oauthBlock;
+  merged.accessToken = accessToken;
+  return writeClaudeCodeCredentialsFile(home, JSON.stringify(merged));
+}
+function extractClaudeAiOauthExpiresAt(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  const oauth = obj.claudeAiOauth;
+  const raw = oauth?.expiresAt ?? obj.expiresAt;
+  if (raw == null) return null;
+  if (typeof raw === "string") {
+    const t = Date.parse(raw);
+    return Number.isFinite(t) ? new Date(t).toISOString() : null;
+  }
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return new Date(raw).toISOString();
+  }
+  return null;
+}
 
 // runner/src/session-resource-handlers.ts
 function asDeclaration(declaration) {
@@ -2852,54 +3033,6 @@ function buildSessionResourceHandlers(deps) {
     }
   };
 }
-var CLAUDE_CODE_CREDENTIALS_KEY = "CLAUDE_CODE_CREDENTIALS_JSON";
-async function writeClaudeCodeCredentialsFile(home, json) {
-  const claudeDir = join(home, ".claude");
-  await mkdir(claudeDir, { recursive: true, mode: 448 });
-  const finalPath = join(claudeDir, ".credentials.json");
-  const tmpPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
-  await writeFile(tmpPath, json, { mode: 384 });
-  await rename(tmpPath, finalPath);
-  return finalPath;
-}
-async function mergeAndRewriteCredentialsFile(home, accessToken, expiresAt) {
-  const credPath = join(home, ".claude", ".credentials.json");
-  let merged = {};
-  if (existsSync(credPath)) {
-    try {
-      merged = JSON.parse(readFileSync(credPath, "utf-8"));
-    } catch {
-      merged = {};
-    }
-  }
-  const oauthBlock = merged.claudeAiOauth ?? {};
-  oauthBlock.accessToken = accessToken;
-  if (expiresAt) oauthBlock.expiresAt = expiresAt;
-  merged.claudeAiOauth = oauthBlock;
-  merged.accessToken = accessToken;
-  return writeClaudeCodeCredentialsFile(home, JSON.stringify(merged));
-}
-function extractClaudeAiOauthExpiresAt(json) {
-  let parsed;
-  try {
-    parsed = JSON.parse(json);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== "object") return null;
-  const obj = parsed;
-  const oauth = obj.claudeAiOauth;
-  const raw = oauth?.expiresAt ?? obj.expiresAt;
-  if (raw == null) return null;
-  if (typeof raw === "string") {
-    const t = Date.parse(raw);
-    return Number.isFinite(t) ? new Date(t).toISOString() : null;
-  }
-  if (typeof raw === "number" && Number.isFinite(raw)) {
-    return new Date(raw).toISOString();
-  }
-  return null;
-}
 
 // runner/src/session-stimulus.ts
 var DEFAULT_COALESCE_MS = 50;
@@ -3086,6 +3219,17 @@ function ensureGitConfigInclude(managedGitconfigPath) {
 `;
   writeFileSync(gitconfigPath, block, { mode: 420 });
 }
+function setupManagedGitconfig(projectDir, serverLog) {
+  const managedGitconfigPath = join(projectDir, ".skaile", "managed-gitconfig");
+  process.env.GIT_CONFIG_GLOBAL = managedGitconfigPath;
+  try {
+    ensureGitConfigInclude(managedGitconfigPath);
+  } catch (err) {
+    serverLog.warn("failed to write ~/.gitconfig include \u2014 relying on env only", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
 async function startAgentServer(opts) {
   const port = opts.port ?? 8080;
   const sessionId = opts.sessionId ?? process.env.SKAILE_SESSION_ID ?? "session-unknown";
@@ -3105,15 +3249,7 @@ async function startAgentServer(opts) {
   const log = (line) => serverLog.info(line);
   const profile = wsConfig.agent_config?.default;
   const maxTurns = wsConfig.agent?.permissions?.max_turns ?? profile?.max_turns;
-  const managedGitconfigPath = join(opts.projectDir, ".skaile", "managed-gitconfig");
-  process.env.GIT_CONFIG_GLOBAL = managedGitconfigPath;
-  try {
-    ensureGitConfigInclude(managedGitconfigPath);
-  } catch (err) {
-    serverLog.warn("failed to write ~/.gitconfig include \u2014 relying on env only", {
-      error: err instanceof Error ? err.message : String(err)
-    });
-  }
+  setupManagedGitconfig(opts.projectDir, serverLog);
   const agentDir = opts.agentDir ?? resolveAgentDir(opts.projectDir);
   if (agentDir) {
     serverLog.info("agent dir resolved", { agentDir });
@@ -3235,475 +3371,1182 @@ async function startAgentServer(opts) {
       timeoutMs
     });
   }
-  function buildCapabilityHooks() {
-    return {
-      sessionId,
-      composeTools: () => capabilityRegistry.composeLLMTools(),
-      resolve: (name) => {
-        const cap = capabilityRegistry.resolve(name);
-        if (!cap) return null;
-        return capabilityRegistry.list().find((c) => c.name === name) ?? null;
+  function buildCapabilityHooks() {
+    return {
+      sessionId,
+      composeTools: () => capabilityRegistry.composeLLMTools(),
+      resolve: (name) => {
+        const cap = capabilityRegistry.resolve(name);
+        if (!cap) return null;
+        return capabilityRegistry.list().find((c) => c.name === name) ?? null;
+      },
+      invoke: (name, input) => capabilityRegistry.invoke(name, input, { sessionId }),
+      emitRender: (event) => sendEvent(event),
+      emitText: (text) => sendEvent({
+        type: "text",
+        content: text
+      })
+    };
+  }
+  function registerSessionComposition(session) {
+    if (session.composition?.discoverableEntries.length) {
+      registerCompositionCapabilities(capabilityRegistry, session.composition.discoverableEntries);
+      log(
+        `[serve] registered ${session.composition.discoverableEntries.length} composition capabilities`
+      );
+    }
+  }
+  const secretsMode = wsConfig.secrets?.provider ?? "env";
+  wsConfig.secrets?.timeoutMs ?? 3e4;
+  function buildSessionConfig(secretProvider2, apiKey) {
+    return {
+      projectDir: opts.projectDir,
+      agentDir,
+      driver: opts.driver,
+      model: opts.model,
+      provider: opts.provider,
+      promptsDir: opts.promptsDir,
+      sessionId,
+      resumeSessionId,
+      maxTurns,
+      wsConfig,
+      externalPromptFile: process.env.SKAILE_SYSTEM_PROMPT_FILE,
+      secretProvider: secretProvider2,
+      onAuthError,
+      ...apiKey ? { apiKey } : {},
+      // Protocol v2 `<CAPABILITIES>` block — joins each registered capability's
+      // `promptFragment` (framework first, then client, then agent-side
+      // surfaces). Built lazily inside `buildSessionConfig` so newly registered
+      // capabilities (e.g. via mid-session `capability_register` commands) are
+      // reflected on the next session rebuild.
+      additionalPromptSections: (() => {
+        const sections = [];
+        const capSection = buildCapabilitiesPromptSection(capabilityRegistry);
+        if (capSection) sections.push(capSection);
+        return sections.length > 0 ? sections : void 0;
+      })(),
+      watch: {
+        onSyncStatus: (mountId, status) => {
+          sendEvent({
+            type: "sync_status",
+            mountId,
+            ...status,
+            phase: status.phase
+          });
+          if (status.phase === "stubs_ready") {
+            log(
+              `[serve] ${mountId}: file tree ready (${status.totalFiles} files, ${status.stubFiles} stubs)`
+            );
+          } else if (status.phase === "initial_sync_complete") {
+            log(
+              `[serve] ${mountId}: sync complete (${status.downloadedFiles}/${status.totalFiles} downloaded)`
+            );
+          }
+        },
+        onFileChanged: (connectorId, event) => {
+          sendEvent({
+            type: "file_changed",
+            path: event.path,
+            action: event.action,
+            mountId: connectorId
+          });
+        },
+        // Forward connector lifecycle transitions to the platform. This is the
+        // channel deferred (rclone-backed) filesystem mounts report progress on
+        // after session_init_ack — a wedged remote shows as "still syncing".
+        onConnectorStatus: (event) => {
+          sendEvent(event);
+        }
+      },
+      // Bring rclone-backed filesystem mounts up in the background so a slow
+      // remote can't blow the platform's session_init_ack deadline and trigger
+      // the container restart loop.
+      deferFilesystemMounts: true,
+      onLog: (line) => log(`[serve] ${line}`),
+      capabilities: buildCapabilityHooks(),
+      // Hand the registry to the session builder so external (declarative /
+      // recipe-backed) MCP servers are spawned by the RUNNER and their tools
+      // registered as `mcp`-origin capabilities — works on every driver, no
+      // dependence on the claude-agent-sdk `mcpServers` query option.
+      capabilityRegistry,
+      // v3: pre-minted credentials replace the tokenMediator for initial mints.
+      // Refresh routes through `host.refresh_credential` (invoked from the
+      // bridge driver's onAuthError callback). The legacy `tokenMediator`
+      // wire is gone.
+      ...preMintedSecrets ? { preMintedSecrets } : {},
+      ...aiProviderConfigId ? { aiProviderConfigId } : {}
+    };
+  }
+  let resolveSessionReady;
+  let rejectSessionReady;
+  const sessionReady = new Promise((resolve3, reject) => {
+    resolveSessionReady = resolve3;
+    rejectSessionReady = reject;
+  });
+  let sessionConfig;
+  let agentSession;
+  let secretProvider;
+  let runtimeIdentity;
+  let preMintedSecrets;
+  stageMaterializedSkillsForSession();
+  function stageMaterializedSkillsForSession() {
+    try {
+      const { skillsDir } = resolveDriverPaths({
+        driver: opts.driver ?? wsConfig.agent_config?.default?.driver ?? "claude-sdk"
+      });
+      const strict = process.env.SKAILE_STRICT_YAML === "true";
+      const declared = strict ? (wsConfig.dependencies ?? []).flatMap((dep) => {
+        try {
+          const ref = parseAssetRef(dep);
+          return ref.kind === "skill" ? [ref.name] : [];
+        } catch {
+          return [];
+        }
+      }) : [];
+      const stagedSkills = stageMaterializedSkills(opts.projectDir, skillsDir, {
+        strict,
+        declared
+      });
+      if (stagedSkills.length > 0) {
+        log(
+          `[serve] staged ${stagedSkills.length} materialized skill(s): ${stagedSkills.join(", ")}`
+        );
+      }
+    } catch {
+    }
+  }
+  if (secretsMode === "provisioned") {
+    log("[serve] secrets mode: provisioned \u2014 waiting for provision_secrets command");
+  } else {
+    sessionConfig = buildSessionConfig();
+    agentSession = await createAgentSession(sessionConfig);
+    emitSystemPromptComposed(agentSession, sendEvent);
+    registerSessionComposition(agentSession);
+    resolveSessionReady();
+  }
+  let resourceManager = secretsMode === "env" ? agentSession.resourceManager : null;
+  if (secretsMode === "env") {
+    if (!agentSession.provider) {
+      log(
+        `[serve] WARNING: no API key found for ${agentSession.provider ?? "anthropic"} \u2014 agent calls will fail`
+      );
+      log(`[serve] Pass via env var (e.g. ANTHROPIC_API_KEY) or .skaile/settings.json`);
+    }
+    if (resourceManager) {
+      const watched = resourceManager.watchedResources ?? [];
+      if (watched.length > 0) {
+        log(`[serve] watching ${watched.length} resource(s): ${watched.join(", ")}`);
+      }
+    }
+  }
+  if (secretsMode === "env" && agentSession.runtimeAssets) {
+    emitRuntimeAssetWarnings(agentSession.runtimeAssets);
+  }
+  validateSkaileYamlDependencies();
+  function emitRuntimeAssetWarnings(runtimeAssets) {
+    for (const w of runtimeAssets.warnings) {
+      const asset = w.code === "missing_driver" && w.declarationId ? `${w.declarationId} \u2192 ${w.name ?? "unknown"}` : w.name ?? w.code;
+      log(`[serve] validation_warning: ${w.code}: ${w.message}`);
+      sendEvent({
+        type: "validation_warning",
+        asset,
+        reason: w.code,
+        suggestion: w.message
+      });
+    }
+  }
+  function validateSkaileYamlDependencies() {
+    try {
+      const wsConfig2 = resolveSkWorkspaceConfig(opts.projectDir);
+      for (const dep of wsConfig2.dependencies ?? []) {
+        let ref;
+        try {
+          const parsed = parseAssetRef(dep);
+          if (parsed.kind !== "skill") continue;
+          ref = parsed.name;
+        } catch {
+          continue;
+        }
+        const skillDir = join(opts.projectDir, ".claude", "skills", ref);
+        if (!existsSync(skillDir)) {
+          log(`[serve] validation_warning: dependency "${dep}" not found \u2014 continuing without it`);
+          sendEvent({
+            type: "validation_warning",
+            asset: dep,
+            reason: "not_found",
+            suggestion: "Sync the catalog and re-add this asset"
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const normalizer = new EventNormalizer();
+  function forwardNormalizedEvent(event) {
+    if (compacting) return;
+    const isTransient = event.type === "status" || event.type === "sync_status" || event.type === "resources_available" || event.type === "resource_response" || event.type === "commands_available";
+    if (!isTransient) {
+      eventSeq++;
+      compactionOrchestrator?.trackMessage(eventSeq);
+    }
+    if (event.type === "finished") {
+      if (!compacting && compactionOrchestrator?.shouldCompact()) {
+        compactionOrchestrator.compact("threshold").catch((err) => {
+          log(
+            `[serve] auto-compaction failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        });
+      }
+    }
+    if (!resourceManager) {
+      sendEvent(event);
+      return;
+    }
+    const mounts = resourceManager.listConnectors().filter((info) => typeof info.mountPath === "string").map((info) => ({
+      id: info.id,
+      mountPath: info.mountPath
+    }));
+    sendEvent(rewriteFileChangedPath(event, opts.projectDir, mounts));
+  }
+  let driverStarted = false;
+  let driver = secretsMode === "env" ? agentSession.driver : void 0;
+  let secretsProvisioned = secretsMode === "env";
+  let eventSeq = 0;
+  let compacting = false;
+  let compactionOrchestrator = null;
+  const compactionConfig = wsConfig.compaction;
+  function rebuildCompactionOrchestrator() {
+    if (!driver) return;
+    compactionOrchestrator = new CompactionOrchestrator({
+      driver,
+      config: compactionConfig,
+      onCompactionStart: (trigger) => {
+        compacting = true;
+        sendEvent({ type: "status", phase: "compacting" });
+        log(`[serve] compaction started (trigger=${trigger})`);
+      },
+      onSnapshot: (snapshot) => {
+        sendEvent(snapshot);
+      },
+      onCompactionAttempt: (event) => {
+        sendEvent(event);
+      },
+      onCompactionEnd: () => {
+        compacting = false;
+        sendEvent({ type: "status", phase: "idle" });
+      },
+      onLog: (line) => log(`[serve] ${line}`),
+      // Phase 3: stamp every CompactionAttemptEvent with the registry's
+      // current signature so wake-time tier-1 selection has the input it
+      // needs. The registry exists for the entire serve lifetime, so this
+      // closure is safe across orchestrator rebuilds.
+      getCurrentCapabilitySignature: () => computeCapabilitySignature(capabilityRegistry.list())
+    });
+  }
+  if (secretsMode === "env" && driver) {
+    rebuildCompactionOrchestrator();
+  }
+  const activeFlows = /* @__PURE__ */ new Map();
+  let stimulusBus = null;
+  const FLOW_TURN_TIMEOUT_MS = 4 * 60 * 60 * 1e3;
+  function getOnlyActiveFlow() {
+    const iter = activeFlows.values().next();
+    return iter.done ? null : iter.value;
+  }
+  function getOrCreateStimulusBus() {
+    if (stimulusBus) return stimulusBus;
+    stimulusBus = createSessionStimulusBus({
+      driveTurn: async (promptFragment, metas) => {
+        const lastMeta = metas[metas.length - 1] ?? {};
+        const runId = typeof lastMeta.runId === "string" ? lastMeta.runId : null;
+        const entry = runId ? activeFlows.get(runId) : getOnlyActiveFlow();
+        if (!entry) {
+          serverLog.warn("driveTurn fired with no active flow", { runId });
+          return;
+        }
+        const lastKind = lastMeta.kind;
+        let stimulus;
+        if (lastKind === "flow_started") {
+          stimulus = { kind: "flow_started" };
+        } else if (lastKind === "user_message" && typeof lastMeta.text === "string") {
+          stimulus = {
+            kind: "user_message",
+            text: String(lastMeta.text),
+            senderId: String(lastMeta.senderId ?? "user")
+          };
+        } else {
+          stimulus = { kind: "state_changed" };
+        }
+        const fullPrompt = buildOrchestratorPrompt(
+          entry.flowDef,
+          entry.adapter.getExecution(entry.handle),
+          stimulus
+        );
+        if (!driverStarted) {
+          await driver.start();
+          driverStarted = true;
+          driver.on("agent-event", (event) => {
+            const normalized = normalizer.normalize(event);
+            for (const e of normalized) forwardNormalizedEvent(e);
+          });
+          driver.on("error", (err) => {
+            log(`[serve] driver error: ${err.message}`);
+            sendEvent({ type: "error", message: err.message, fatal: true });
+          });
+        }
+        await awaitFlowAgentEnd(fullPrompt, FLOW_TURN_TIMEOUT_MS);
       },
-      invoke: (name, input) => capabilityRegistry.invoke(name, input, { sessionId }),
-      emitRender: (event) => sendEvent(event),
-      emitText: (text) => sendEvent({
-        type: "text",
-        content: text
-      })
-    };
+      log: serverLog
+    });
+    return stimulusBus;
   }
-  function registerSessionComposition(session) {
-    if (session.composition?.discoverableEntries.length) {
-      registerCompositionCapabilities(capabilityRegistry, session.composition.discoverableEntries);
-      log(
-        `[serve] registered ${session.composition.discoverableEntries.length} composition capabilities`
+  function awaitFlowAgentEnd(prompt, timeoutMs) {
+    return new Promise((resolve3, reject) => {
+      let settled = false;
+      const onEvent = (event) => {
+        if (event.type === "agent_end") done();
+        else if (event.type === "error") {
+          const msg = event.error ?? event.message ?? "Agent error";
+          done(new Error(msg));
+        }
+      };
+      const done = (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        driver.off?.(
+          "agent-event",
+          onEvent
+        ) ?? driver.removeListener("agent-event", onEvent);
+        if (err) reject(err);
+        else resolve3();
+      };
+      const timer = setTimeout(
+        () => done(new Error(`Flow turn timed out after ${timeoutMs / 1e3}s`)),
+        timeoutMs
       );
-    }
+      driver.on("agent-event", onEvent);
+      driver.prompt(prompt).catch(done);
+    });
   }
-  const secretsMode = wsConfig.secrets?.provider ?? "env";
-  wsConfig.secrets?.timeoutMs ?? 3e4;
-  function buildSessionConfig(secretProvider2, apiKey) {
-    return {
-      projectDir: opts.projectDir,
-      agentDir,
-      driver: opts.driver,
-      model: opts.model,
-      provider: opts.provider,
-      promptsDir: opts.promptsDir,
-      sessionId,
-      resumeSessionId,
-      maxTurns,
-      wsConfig,
-      externalPromptFile: process.env.SKAILE_SYSTEM_PROMPT_FILE,
-      secretProvider: secretProvider2,
-      onAuthError,
-      ...apiKey ? { apiKey } : {},
-      // Protocol v2 `<CAPABILITIES>` block — joins each registered capability's
-      // `promptFragment` (framework first, then client, then agent-side
-      // surfaces). Built lazily inside `buildSessionConfig` so newly registered
-      // capabilities (e.g. via mid-session `capability_register` commands) are
-      // reflected on the next session rebuild.
-      additionalPromptSections: (() => {
-        const sections = [];
-        const capSection = buildCapabilitiesPromptSection(capabilityRegistry);
-        if (capSection) sections.push(capSection);
-        return sections.length > 0 ? sections : void 0;
-      })(),
-      watch: {
-        onSyncStatus: (mountId, status) => {
-          sendEvent({
-            type: "sync_status",
-            mountId,
-            ...status,
-            phase: status.phase
-          });
-          if (status.phase === "stubs_ready") {
-            log(
-              `[serve] ${mountId}: file tree ready (${status.totalFiles} files, ${status.stubFiles} stubs)`
-            );
-          } else if (status.phase === "initial_sync_complete") {
+  async function createActiveFlow(flowDef, seedOrExecution) {
+    if (!resourceManager) {
+      registerBuiltinConnectors();
+      resourceManager = new ConnectorManager(opts.projectDir, {
+        catalogEntries: getSessionCatalogEntries(agentSession)
+      });
+      log("[serve] created ConnectorManager for flow execution (no other connectors declared)");
+    }
+    const bus = getOrCreateStimulusBus();
+    const baseOptions = {
+      stimulusBus: bus,
+      useBusForStimulus: true
+    };
+    const options = "execution" in seedOrExecution ? { flow: flowDef, execution: seedOrExecution.execution, ...baseOptions } : { flow: flowDef, seed: seedOrExecution.seed, ...baseOptions };
+    const seedRunId = "execution" in seedOrExecution ? seedOrExecution.execution.runId : seedOrExecution.seed.runId;
+    const connectorId = `flow:${seedRunId}`;
+    const handle = await resourceManager.connect({
+      id: connectorId,
+      driver: "flow",
+      access: "read-write",
+      options
+    });
+    const adapter = resourceManager.get(connectorId).connector;
+    const runId = adapter.getExecution(handle).runId;
+    adapter.onStateChange(handle, (state) => {
+      sendEvent({
+        type: "state_changed",
+        store: `flow:${state.runId}`,
+        state
+      });
+    });
+    if (agentSession?.driverType === "claude-sdk") {
+      try {
+        const server = await buildSdkConnectorTools(resourceManager, { z: z });
+        if (server) {
+          if (driverStarted) {
+            const prevSessionId = driver.runtimeSessionId;
             log(
-              `[serve] ${mountId}: sync complete (${status.downloadedFiles}/${status.totalFiles} downloaded)`
+              `[serve] restarting driver to register flow connector tools (resume=${prevSessionId ?? "none"})`
             );
+            await agentSession.dispose();
+            agentSession = await createAgentSession({
+              ...sessionConfig,
+              resumeSessionId: prevSessionId
+            });
+            emitSystemPromptComposed(agentSession, sendEvent);
+            driver = agentSession.driver;
+            normalizer.reset();
+            driverStarted = false;
+            rebuildCompactionOrchestrator();
           }
-        },
-        onFileChanged: (connectorId, event) => {
-          sendEvent({
-            type: "file_changed",
-            path: event.path,
-            action: event.action,
-            mountId: connectorId
-          });
-        },
-        // Forward connector lifecycle transitions to the platform. This is the
-        // channel deferred (rclone-backed) filesystem mounts report progress on
-        // after session_init_ack — a wedged remote shows as "still syncing".
-        onConnectorStatus: (event) => {
-          sendEvent(event);
+          driver.config.mcpServers = { "skaile-connectors": server };
+          log(`[serve] rebuilt MCP connector tools for flow ${connectorId}`);
+        } else {
+          log(`[serve] buildSdkConnectorTools returned null for flow ${connectorId}`);
         }
-      },
-      // Bring rclone-backed filesystem mounts up in the background so a slow
-      // remote can't blow the platform's session_init_ack deadline and trigger
-      // the container restart loop.
-      deferFilesystemMounts: true,
-      onLog: (line) => log(`[serve] ${line}`),
-      capabilities: buildCapabilityHooks(),
-      // Hand the registry to the session builder so external (declarative /
-      // recipe-backed) MCP servers are spawned by the RUNNER and their tools
-      // registered as `mcp`-origin capabilities — works on every driver, no
-      // dependence on the claude-agent-sdk `mcpServers` query option.
-      capabilityRegistry,
-      // v3: pre-minted credentials replace the tokenMediator for initial mints.
-      // Refresh routes through `host.refresh_credential` (invoked from the
-      // bridge driver's onAuthError callback). The legacy `tokenMediator`
-      // wire is gone.
-      ...preMintedSecrets ? { preMintedSecrets } : {},
-      ...aiProviderConfigId ? { aiProviderConfigId } : {}
-    };
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log(`[serve] failed to rebuild MCP tools for flow: ${errMsg}`);
+      }
+    }
+    const entry = { runId, flowDef, adapter, handle, connectorId };
+    activeFlows.set(runId, entry);
+    return entry;
   }
-  let resolveSessionReady;
-  let rejectSessionReady;
-  const sessionReady = new Promise((resolve3, reject) => {
-    resolveSessionReady = resolve3;
-    rejectSessionReady = reject;
-  });
-  let sessionConfig;
-  let agentSession;
-  let secretProvider;
-  let runtimeIdentity;
-  let preMintedSecrets;
+  const refreshFlagPath = join(opts.projectDir, ".skaile", "refresh-request");
+  try {
+    mkdirSync(join(opts.projectDir, ".skaile"), { recursive: true });
+    if (!existsSync(refreshFlagPath)) {
+      writeFileSync(refreshFlagPath, "", { mode: 432, flag: "a" });
+    }
+  } catch (err) {
+    serverLog.warn("failed to pre-create refresh-flag \u2014 wake-mid-401 disabled", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+  let lastRefreshAt = 0;
+  const REFRESH_DEBOUNCE_MS = 2e3;
+  let refreshFlagWatcher = null;
   try {
-    const { skillsDir } = resolveDriverPaths({
-      driver: opts.driver ?? wsConfig.agent_config?.default?.driver ?? "claude-sdk"
+    refreshFlagWatcher = watch(refreshFlagPath, (event) => {
+      if (event !== "change") return;
+      const now = Date.now();
+      if (now - lastRefreshAt < REFRESH_DEBOUNCE_MS) return;
+      lastRefreshAt = now;
+      void dispatchRefreshToExposedGitMounts(resourceManager, serverLog);
+    });
+  } catch (err) {
+    serverLog.warn("fs.watch on refresh-flag failed \u2014 wake-mid-401 disabled", {
+      error: err instanceof Error ? err.message : String(err)
     });
-    const strict = process.env.SKAILE_STRICT_YAML === "true";
-    const declared = strict ? (wsConfig.dependencies ?? []).flatMap((dep) => {
+  }
+  async function cleanup() {
+    try {
+      await Promise.race([
+        sessionReady,
+        new Promise((resolve3) => {
+          const t = setTimeout(resolve3, 2e3);
+          t.unref?.();
+        })
+      ]);
+    } catch {
+    }
+    try {
+      driver?.kill();
+    } catch {
+    }
+    aiCredentialRefreshScheduler.cancel();
+    for (const [callId, pending] of pendingCapabilityCalls) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(`Session terminated before capability_result (callId=${callId})`));
+    }
+    pendingCapabilityCalls.clear();
+    try {
+      refreshFlagWatcher?.close();
+    } catch {
+    }
+    refreshFlagWatcher = null;
+    if (agentSession) {
       try {
-        const ref = parseAssetRef(dep);
-        return ref.kind === "skill" ? [ref.name] : [];
+        await agentSession.dispose();
       } catch {
-        return [];
       }
-    }) : [];
-    const stagedSkills = stageMaterializedSkills(opts.projectDir, skillsDir, { strict, declared });
-    if (stagedSkills.length > 0) {
-      log(
-        `[serve] staged ${stagedSkills.length} materialized skill(s): ${stagedSkills.join(", ")}`
-      );
     }
-  } catch {
-  }
-  if (secretsMode === "provisioned") {
-    log("[serve] secrets mode: provisioned \u2014 waiting for provision_secrets command");
-  } else {
-    sessionConfig = buildSessionConfig();
-    agentSession = await createAgentSession(sessionConfig);
-    emitSystemPromptComposed(agentSession, sendEvent);
-    registerSessionComposition(agentSession);
-    resolveSessionReady();
   }
-  let resourceManager = secretsMode === "env" ? agentSession.resourceManager : null;
-  if (secretsMode === "env") {
-    if (!agentSession.provider) {
-      log(
-        `[serve] WARNING: no API key found for ${agentSession.provider ?? "anthropic"} \u2014 agent calls will fail`
-      );
-      log(`[serve] Pass via env var (e.g. ANTHROPIC_API_KEY) or .skaile/settings.json`);
+  async function awaitSessionReadyOrFail() {
+    try {
+      await sessionReady;
+      return true;
+    } catch (err) {
+      sendEvent({
+        type: "error",
+        message: `Session not available: ${err.message}`,
+        fatal: true
+      });
+      return false;
     }
-    if (resourceManager) {
-      const watched = resourceManager.watchedResources ?? [];
-      if (watched.length > 0) {
-        log(`[serve] watching ${watched.length} resource(s): ${watched.join(", ")}`);
+  }
+  function registerInitClientCapabilities(incoming) {
+    for (const wire of incoming) {
+      if (wire.audience && !wire.audience.includes("llm") && !wire.audience.includes("user")) {
+        continue;
       }
+      const stub = {
+        ...wire,
+        inputZod: { parse: (v) => v },
+        outputZod: void 0,
+        handler: buildClientCapabilityHandler2(wire)
+      };
+      capabilityRegistry.register(stub, "client");
     }
   }
-  if (secretsMode === "env" && agentSession.runtimeAssets) {
-    for (const w of agentSession.runtimeAssets.warnings) {
-      const asset = w.code === "missing_driver" && w.declarationId ? `${w.declarationId} \u2192 ${w.name ?? "unknown"}` : w.name ?? w.code;
-      log(`[serve] validation_warning: ${w.code}: ${w.message}`);
+  async function provisionInitSecrets(secrets) {
+    let initialAiCredentialExpiresAt = null;
+    if (secrets) {
+      const ccdValue = secrets[CLAUDE_CODE_CREDENTIALS_KEY];
+      if (ccdValue) {
+        const home = process.env.HOME ?? homedir();
+        if (home) {
+          try {
+            await writeClaudeCodeCredentialsFile(home, ccdValue);
+            log(
+              `[serve] wrote Claude Code credentials file to ${home}/.claude/.credentials.json (mode 0600)`
+            );
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            log(`[serve] failed to write Claude Code credentials file: ${errMsg}`);
+          }
+        }
+        initialAiCredentialExpiresAt = extractClaudeAiOauthExpiresAt(ccdValue);
+      }
+      const otherSecrets = Object.fromEntries(
+        Object.entries(secrets).filter(([k]) => k !== CLAUDE_CODE_CREDENTIALS_KEY)
+      );
+      const provider = new InMemorySecretProvider();
+      provider.provision(otherSecrets);
+      secretProvider = provider;
+      secretsProvisioned = true;
+    }
+    return initialAiCredentialExpiresAt;
+  }
+  async function buildSessionFromInit(secrets) {
+    const effectiveProvider = opts.provider ?? "anthropic";
+    const envKey = providerEnvKey(effectiveProvider);
+    const apiKeyFromSecrets = secrets?.[envKey];
+    sessionConfig = buildSessionConfig(secretProvider, apiKeyFromSecrets);
+    if (!agentSession) {
+      agentSession = await createAgentSession(sessionConfig);
+      emitSystemPromptComposed(agentSession, sendEvent);
+      resourceManager = agentSession.resourceManager;
+      driver = agentSession.driver;
+      rebuildCompactionOrchestrator();
+      registerSessionComposition(agentSession);
       sendEvent({
-        type: "validation_warning",
-        asset,
-        reason: w.code,
-        suggestion: w.message
+        type: "resources_available",
+        ...splitConnectorsForWire(resourceManager)
+      });
+      agentSession.startWatching();
+      capabilityRegistry.setRemoteInvoker(remoteCapabilityInvoker);
+      const runnerCaps = buildRunnerCapabilities({
+        // Resource hot-plug handlers, wired to the live session's
+        // ConnectorManager + PreMintedSecretProvider via getters because
+        // both are lazily (re)assigned in this scope.
+        ...buildSessionResourceHandlers({
+          getResourceManager: () => resourceManager,
+          getPreMintedSecrets: () => preMintedSecrets,
+          emitResourcesAvailable: () => {
+            sendEvent({
+              type: "resources_available",
+              ...splitConnectorsForWire(resourceManager)
+            });
+          },
+          log
+        })
+        // setLogLevel left undefined — the cap's built-in fallback calls
+        // getLogStore()?.setLevel(...) directly. setState / lifecycle
+        // remain stubs (not resource hot-plug; out of Sprint 2 scope).
       });
+      for (const cap of runnerCaps) {
+        capabilityRegistry.register(cap, "agent");
+      }
+      log("[serve] session built from session_init envelope");
     }
   }
-  try {
-    const wsConfig2 = resolveSkWorkspaceConfig(opts.projectDir);
-    for (const dep of wsConfig2.dependencies ?? []) {
-      let ref;
-      try {
-        const parsed = parseAssetRef(dep);
-        if (parsed.kind !== "skill") continue;
-        ref = parsed.name;
-      } catch {
-        continue;
-      }
-      const skillDir = join(opts.projectDir, ".claude", "skills", ref);
-      if (!existsSync(skillDir)) {
-        log(`[serve] validation_warning: dependency "${dep}" not found \u2014 continuing without it`);
-        sendEvent({
-          type: "validation_warning",
-          asset: dep,
-          reason: "not_found",
-          suggestion: "Sync the catalog and re-add this asset"
-        });
-      }
+  async function recreateSessionForInit(pendingResumeSessionId) {
+    await agentSession.dispose();
+    agentSession = await createAgentSession({
+      ...sessionConfig,
+      ...aiProviderConfigId ? { aiProviderConfigId } : {},
+      ...pendingResumeSessionId ? { resumeSessionId: pendingResumeSessionId } : {}
+    });
+    emitSystemPromptComposed(agentSession, sendEvent);
+    driver = agentSession.driver;
+    normalizer.reset();
+    driverStarted = false;
+    rebuildCompactionOrchestrator();
+  }
+  async function applyInitSharedState(sharedState) {
+    if (!ensureResourceManagerForSharedState()) {
+      sendEvent({ type: "configured" });
+      return false;
     }
-  } catch {
+    let storesRegistered = 0;
+    for (const stateConfig of sharedState) {
+      if (await registerSharedStateStore(stateConfig)) storesRegistered++;
+    }
+    await rebuildMcpToolsForNewStores(storesRegistered);
+    return true;
   }
-  const normalizer = new EventNormalizer();
-  function forwardNormalizedEvent(event) {
-    if (compacting) return;
-    const isTransient = event.type === "status" || event.type === "sync_status" || event.type === "resources_available" || event.type === "resource_response" || event.type === "commands_available";
-    if (!isTransient) {
-      eventSeq++;
-      compactionOrchestrator?.trackMessage(eventSeq);
+  function ensureResourceManagerForSharedState() {
+    if (resourceManager) return true;
+    try {
+      registerBuiltinConnectors();
+      resourceManager = new ConnectorManager(opts.projectDir, {
+        catalogEntries: getSessionCatalogEntries(agentSession)
+      });
+      log("[serve] created ConnectorManager for sharedState (no connectors were declared)");
+      return true;
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log(`[serve] failed to create ConnectorManager: ${errMsg}`);
+      return false;
     }
-    if (event.type === "finished") {
-      if (!compacting && compactionOrchestrator?.shouldCompact()) {
-        compactionOrchestrator.compact("threshold").catch((err) => {
+  }
+  async function registerSharedStateStore(stateConfig) {
+    try {
+      if (resourceManager.has(stateConfig.id)) {
+        try {
+          const snapshot = await resourceManager.executeOp(stateConfig.id, "get", {});
+          const state = snapshot ? JSON.parse(snapshot) : {};
+          sendEvent({
+            type: "state_changed",
+            store: stateConfig.id,
+            state
+          });
           log(
-            `[serve] auto-compaction failed: ${err instanceof Error ? err.message : String(err)}`
+            `[serve] sharedState ${stateConfig.id} already registered \u2014 re-emitted current state`
+          );
+        } catch {
+          log(
+            `[serve] sharedState ${stateConfig.id} already registered \u2014 skipping (could not read state)`
           );
+        }
+        return false;
+      }
+      const handle = await resourceManager.connect({
+        id: stateConfig.id,
+        driver: stateConfig.adapter,
+        access: "read-write",
+        options: {
+          ...stateConfig.definition ?? {},
+          initial: stateConfig.initialState ?? {}
+        }
+      });
+      const entry = resourceManager.get(stateConfig.id);
+      if (typeof entry.connector.onStoreChange === "function") {
+        entry.connector.onStoreChange(handle, (snapshot) => {
+          sendEvent({
+            type: "state_changed",
+            store: stateConfig.id,
+            state: snapshot
+          });
         });
       }
+      log(`[serve] sharedState registered: ${stateConfig.id} (${stateConfig.adapter})`);
+      sendEvent({
+        type: "state_changed",
+        store: stateConfig.id,
+        state: stateConfig.initialState ?? {}
+      });
+      return true;
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log(`[serve] sharedState registration failed for ${stateConfig.id}: ${errMsg}`);
+      sendEvent({
+        type: "error",
+        message: `sharedState ${stateConfig.id}: ${errMsg}`,
+        fatal: false
+      });
+      return false;
     }
-    if (!resourceManager) {
-      sendEvent(event);
+  }
+  async function rebuildMcpToolsForNewStores(storesRegistered) {
+    if (!(storesRegistered > 0 && !driverStarted && agentSession?.driverType === "claude-sdk")) {
       return;
     }
-    const mounts = resourceManager.listConnectors().filter((info) => typeof info.mountPath === "string").map((info) => ({
-      id: info.id,
-      mountPath: info.mountPath
-    }));
-    sendEvent(rewriteFileChangedPath(event, opts.projectDir, mounts));
-  }
-  let driverStarted = false;
-  let driver = secretsMode === "env" ? agentSession.driver : void 0;
-  let secretsProvisioned = secretsMode === "env";
-  let eventSeq = 0;
-  let compacting = false;
-  let compactionOrchestrator = null;
-  const compactionConfig = wsConfig.compaction;
-  function rebuildCompactionOrchestrator() {
-    if (!driver) return;
-    compactionOrchestrator = new CompactionOrchestrator({
-      driver,
-      config: compactionConfig,
-      onCompactionStart: (trigger) => {
-        compacting = true;
-        sendEvent({ type: "status", phase: "compacting" });
-        log(`[serve] compaction started (trigger=${trigger})`);
-      },
-      onSnapshot: (snapshot) => {
-        sendEvent(snapshot);
-      },
-      onCompactionAttempt: (event) => {
-        sendEvent(event);
-      },
-      onCompactionEnd: () => {
-        compacting = false;
-        sendEvent({ type: "status", phase: "idle" });
-      },
-      onLog: (line) => log(`[serve] ${line}`),
-      // Phase 3: stamp every CompactionAttemptEvent with the registry's
-      // current signature so wake-time tier-1 selection has the input it
-      // needs. The registry exists for the entire serve lifetime, so this
-      // closure is safe across orchestrator rebuilds.
-      getCurrentCapabilitySignature: () => computeCapabilitySignature(capabilityRegistry.list())
-    });
-  }
-  if (secretsMode === "env" && driver) {
-    rebuildCompactionOrchestrator();
+    try {
+      const server = await buildSdkConnectorTools(resourceManager, { z: z });
+      if (server) {
+        driver.config.mcpServers = { "skaile-connectors": server };
+        log(`[serve] rebuilt MCP connector tools (${storesRegistered} new store(s))`);
+      } else {
+        log(`[serve] buildSdkConnectorTools returned null`);
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log(`[serve] failed to rebuild MCP tools: ${errMsg}`);
+    }
   }
-  const activeFlows = /* @__PURE__ */ new Map();
-  let stimulusBus = null;
-  const FLOW_TURN_TIMEOUT_MS = 4 * 60 * 60 * 1e3;
-  function getOnlyActiveFlow() {
-    const iter = activeFlows.values().next();
-    return iter.done ? null : iter.value;
+  async function applyInitAiResources(aiResources) {
+    const catalogActions = aiResources.filter((a) => a.action);
+    if (catalogActions.length === 0) return;
+    log(`[serve] aiResources catalog actions: ${catalogActions.length}`);
+    try {
+      const skillsDir = join(sessionConfig.projectDir ?? process.cwd(), ".claude", "skills");
+      const assetsRoot = process.env.SKAILE_ASSETS_ROOT ?? findAiAssetsRoot(sessionConfig.projectDir ?? process.cwd()) ?? "/app/ai-assets";
+      for (const res of catalogActions) {
+        applyCatalogAction(res, { assetsRoot, skillsDir });
+      }
+      await restartDriverForSkillChanges(catalogActions);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log(`[serve] aiResources handling failed: ${errMsg}`);
+      sendEvent({
+        type: "error",
+        message: `aiResources: ${errMsg}`,
+        fatal: false
+      });
+    }
   }
-  function getOrCreateStimulusBus() {
-    if (stimulusBus) return stimulusBus;
-    stimulusBus = createSessionStimulusBus({
-      driveTurn: async (promptFragment, metas) => {
-        const lastMeta = metas[metas.length - 1] ?? {};
-        const runId = typeof lastMeta.runId === "string" ? lastMeta.runId : null;
-        const entry = runId ? activeFlows.get(runId) : getOnlyActiveFlow();
-        if (!entry) {
-          serverLog.warn("driveTurn fired with no active flow", { runId });
-          return;
-        }
-        const lastKind = lastMeta.kind;
-        let stimulus;
-        if (lastKind === "flow_started") {
-          stimulus = { kind: "flow_started" };
-        } else if (lastKind === "user_message" && typeof lastMeta.text === "string") {
-          stimulus = {
-            kind: "user_message",
-            text: String(lastMeta.text),
-            senderId: String(lastMeta.senderId ?? "user")
-          };
-        } else {
-          stimulus = { kind: "state_changed" };
-        }
-        const fullPrompt = buildOrchestratorPrompt(
-          entry.flowDef,
-          entry.adapter.getExecution(entry.handle),
-          stimulus
+  function applyCatalogAction(res, paths) {
+    if (res.action === "add" && res.entry) {
+      const entry = res.entry;
+      const result = deployCatalogEntry(entry, {
+        assetsRoot: paths.assetsRoot,
+        skillsDir: paths.skillsDir,
+        context: res.context
+      });
+      if (result.success) {
+        log(`[serve] deployed skill: ${entry.name ?? res.name}`);
+      } else {
+        log(
+          `[serve] failed to deploy skill ${entry.name ?? res.name}: ${result.error}`
         );
-        if (!driverStarted) {
-          await driver.start();
-          driverStarted = true;
-          driver.on("agent-event", (event) => {
-            const normalized = normalizer.normalize(event);
-            for (const e of normalized) forwardNormalizedEvent(e);
+      }
+    } else if (res.action === "remove") {
+      const removed = undeployCatalogEntry(res.name, paths.skillsDir);
+      log(`[serve] ${removed ? "removed" : "not found"} skill: ${res.name}`);
+    }
+  }
+  async function restartDriverForSkillChanges(catalogActions) {
+    if (!driverStarted) {
+      log("[serve] aiResources applied before driver start \u2014 skills discovered on first prompt");
+      return;
+    }
+    const prevSessionId = driver.runtimeSessionId;
+    log(`[serve] restarting driver to pick up skill changes (resume=${prevSessionId ?? "none"})`);
+    await agentSession.dispose();
+    agentSession = await createAgentSession({
+      ...sessionConfig,
+      resumeSessionId: prevSessionId
+    });
+    emitSystemPromptComposed(agentSession, sendEvent);
+    driver = agentSession.driver;
+    normalizer.reset();
+    driverStarted = false;
+    rebuildCompactionOrchestrator();
+    sendEvent({
+      type: "skills_changed",
+      skills: catalogActions.map((a) => ({
+        name: a.entry?.name ?? a.name,
+        action: a.action ?? "add"
+      }))
+    });
+  }
+  async function handleSessionInit(cmd) {
+    if (cmd.protocolVersion.major !== PROTOCOL_VERSION.major) {
+      log(
+        `[serve] incompatible protocol: agent=${PROTOCOL_VERSION.major} platform=${cmd.protocolVersion.major}`
+      );
+      sendEvent({
+        type: "incompatible_protocol",
+        agentVersion: PROTOCOL_VERSION,
+        platformVersion: cmd.protocolVersion
+      });
+      await cleanup();
+      disposeLogStore();
+      return;
+    }
+    if (runtimeIdentity && runtimeIdentity.containerId !== cmd.identity.containerId) {
+      log(
+        `[serve] session_init_mismatch: expected=${runtimeIdentity.containerId} received=${cmd.identity.containerId}`
+      );
+      sendEvent({
+        type: "session_init_mismatch",
+        expectedContainerId: runtimeIdentity.containerId,
+        receivedContainerId: cmd.identity.containerId
+      });
+      await cleanup();
+      disposeLogStore();
+      return;
+    }
+    runtimeIdentity = cmd.identity;
+    registerInitClientCapabilities(cmd.capabilities ?? []);
+    sendEvent({ type: "protocol_info", version: PROTOCOL_VERSION });
+    preMintedSecrets = new PreMintedSecretProvider(cmd.credentials);
+    const initialAiCredentialExpiresAt = await provisionInitSecrets(cmd.secrets);
+    if (cmd.resolvedConfig.aiProviderConfigId) {
+      aiProviderConfigId = cmd.resolvedConfig.aiProviderConfigId;
+      log(`[serve] stashed aiProviderConfigId=${aiProviderConfigId}`);
+    }
+    if (aiProviderConfigId && initialAiCredentialExpiresAt) {
+      aiCredentialRefreshScheduler.schedule(initialAiCredentialExpiresAt);
+    }
+    sendEvent({
+      type: "session_init_ack",
+      capabilitySignature: computeCapabilitySignature(capabilityRegistry.list())
+    });
+    const buildSession = async () => {
+      await buildSessionFromInit(cmd.secrets);
+      const cfg = {
+        aiResources: cmd.resolvedConfig.aiResources,
+        subagents: cmd.resolvedConfig.subagents,
+        sharedState: cmd.sharedState,
+        resumeSessionId: cmd.resume?.sessionId,
+        expectedCapabilitySignature: cmd.resume?.expectedCapabilitySignature,
+        aiProviderConfigId: cmd.resolvedConfig.aiProviderConfigId
+      };
+      log(
+        `[serve] configure cfg keys=${Object.keys(cfg).join(",")} sharedState=${cfg.sharedState ? cfg.sharedState.length : "undefined"} resourceManager=${resourceManager ? "set" : "null"}`
+      );
+      let pendingResumeSessionId;
+      const cfgResumeSessionId = cfg.resumeSessionId;
+      const cfgExpectedSig = cfg.expectedCapabilitySignature;
+      if (cfgResumeSessionId) {
+        const currentSig = computeCapabilitySignature(capabilityRegistry.list());
+        if (cfgExpectedSig && cfgExpectedSig !== currentSig) {
+          log(
+            `[serve] tier-1 resume rejected: signature mismatch (expected=${cfgExpectedSig.slice(0, 12)} current=${currentSig.slice(0, 12)})`
+          );
+          sendEvent({
+            type: "resume_failed",
+            resumeSessionId: cfgResumeSessionId,
+            reason: "signature_mismatch"
           });
-          driver.on("error", (err) => {
-            log(`[serve] driver error: ${err.message}`);
-            sendEvent({ type: "error", message: err.message, fatal: true });
+        } else {
+          log(`[serve] tier-1 resume attempted: resumeSessionId=${cfgResumeSessionId}`);
+          sendEvent({
+            type: "resume_attempted",
+            resumeSessionId: cfgResumeSessionId,
+            capabilitySignature: currentSig
           });
+          pendingResumeSessionId = cfgResumeSessionId;
         }
-        await awaitFlowAgentEnd(fullPrompt, FLOW_TURN_TIMEOUT_MS);
-      },
-      log: serverLog
+      }
+      if (pendingResumeSessionId || cfg.subagents) {
+        await recreateSessionForInit(pendingResumeSessionId);
+      }
+      if (cfg.sharedState) {
+        const handled = await applyInitSharedState(cfg.sharedState);
+        if (!handled) throw new Error("session_init: shared-state setup failed");
+      }
+      if (cfg.aiResources) {
+        await applyInitAiResources(cfg.aiResources);
+      }
+      resolveSessionReady();
+    };
+    void buildSession().catch((err) => {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log(`[serve] session_init failed to build session: ${errMsg}`);
+      sendEvent({ type: "error", message: errMsg, fatal: true });
+      rejectSessionReady(err instanceof Error ? err : new Error(errMsg));
     });
-    return stimulusBus;
   }
-  function awaitFlowAgentEnd(prompt, timeoutMs) {
-    return new Promise((resolve3, reject) => {
-      let settled = false;
-      const onEvent = (event) => {
-        if (event.type === "agent_end") done();
-        else if (event.type === "error") {
-          const msg = event.error ?? event.message ?? "Agent error";
-          done(new Error(msg));
+  async function handlePrompt(cmd) {
+    if (!await awaitSessionReadyOrFail()) return;
+    if (!secretsProvisioned) {
+      log("[serve] prompt received before secrets provisioned \u2014 rejecting");
+      sendEvent({
+        type: "error",
+        message: "Secrets not yet provisioned \u2014 send provision_secrets first",
+        fatal: false
+      });
+      return;
+    }
+    log(`[serve] prompt: ${cmd.prompt.slice(0, 80)}...`);
+    const activeFlow = getOnlyActiveFlow();
+    if (activeFlow) {
+      sendEvent({ type: "status", phase: "thinking" });
+      try {
+        const bus = getOrCreateStimulusBus();
+        const userStimulus = {
+          kind: "user_message",
+          text: cmd.prompt,
+          senderId: "user"
+        };
+        await bus.signal(activeFlow.connectorId, {
+          promptFragment: renderStimulusPrompt(userStimulus),
+          meta: {
+            kind: "user_message",
+            runId: activeFlow.runId,
+            text: cmd.prompt,
+            senderId: "user"
+          }
+        });
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log(`[serve] flow user-message turn failed: ${errMsg}`);
+        sendEvent({ type: "error", message: `Flow turn failed: ${errMsg}`, fatal: false });
+      }
+      return;
+    }
+    if (!driverStarted) {
+      try {
+        await driver.start();
+        driverStarted = true;
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log(`[serve] driver start failed: ${errMsg}`);
+        sendEvent({ type: "error", message: `Driver start failed: ${errMsg}`, fatal: true });
+        return;
+      }
+      driver.on("agent-event", (event) => {
+        const normalized = normalizer.normalize(event);
+        for (const e of normalized) {
+          forwardNormalizedEvent(e);
         }
-      };
-      const done = (err) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        driver.off?.(
-          "agent-event",
-          onEvent
-        ) ?? driver.removeListener("agent-event", onEvent);
-        if (err) reject(err);
-        else resolve3();
-      };
-      const timer = setTimeout(
-        () => done(new Error(`Flow turn timed out after ${timeoutMs / 1e3}s`)),
-        timeoutMs
-      );
-      driver.on("agent-event", onEvent);
-      driver.prompt(prompt).catch(done);
-    });
+      });
+      driver.on("error", (err) => {
+        log(`[serve] driver error: ${err.message}`);
+        sendEvent({ type: "error", message: err.message, fatal: true });
+      });
+    }
+    sendEvent({ type: "status", phase: "thinking" });
+    try {
+      await driver.prompt(cmd.prompt);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log(`[serve] prompt failed: ${errMsg}`);
+      sendEvent({ type: "error", message: `Prompt failed: ${errMsg}`, fatal: true });
+    }
   }
-  async function createActiveFlow(flowDef, seedOrExecution) {
+  async function handleReply(cmd) {
+    if (!await awaitSessionReadyOrFail()) return;
+    log(`[serve] reply: ${cmd.answer.slice(0, 80)}...`);
+    try {
+      await driver.prompt(cmd.answer);
+    } catch (err) {
+      sendEvent({
+        type: "error",
+        message: `Reply failed: ${err instanceof Error ? err.message : String(err)}`,
+        fatal: false
+      });
+    }
+  }
+  async function handleCancel() {
+    if (!await awaitSessionReadyOrFail()) return;
+    log("[serve] cancel");
+    try {
+      await driver.abort();
+    } catch (err) {
+      log(`[serve] cancel failed: ${err}`);
+    }
+  }
+  async function handleResourceRequestCommand(cmd) {
+    if (!await awaitSessionReadyOrFail()) return;
+    if (resourceManager?.has(cmd.connectorId)) {
+      handleMountResourceRequest(cmd, resourceManager, sendEvent);
+      return;
+    }
     if (!resourceManager) {
-      registerBuiltinConnectors();
-      resourceManager = new ConnectorManager(opts.projectDir, {
-        catalogEntries: getSessionCatalogEntries(agentSession)
+      sendEvent({
+        type: "resource_response",
+        requestId: cmd.requestId,
+        resourceId: cmd.connectorId,
+        operation: cmd.operation,
+        error: "No resources available \u2014 no mounts or connectors configured"
       });
-      log("[serve] created ConnectorManager for flow execution (no other connectors declared)");
+      return;
     }
-    const bus = getOrCreateStimulusBus();
-    const baseOptions = {
-      stimulusBus: bus,
-      useBusForStimulus: true
-    };
-    const options = "execution" in seedOrExecution ? { flow: flowDef, execution: seedOrExecution.execution, ...baseOptions } : { flow: flowDef, seed: seedOrExecution.seed, ...baseOptions };
-    const seedRunId = "execution" in seedOrExecution ? seedOrExecution.execution.runId : seedOrExecution.seed.runId;
-    const connectorId = `flow:${seedRunId}`;
-    const handle = await resourceManager.connect({
-      id: connectorId,
-      driver: "flow",
-      access: "read-write",
-      options
-    });
-    const adapter = resourceManager.get(connectorId).connector;
-    const runId = adapter.getExecution(handle).runId;
-    adapter.onStateChange(handle, (state) => {
+    void handleResourceRequest(cmd, resourceManager, sendEvent);
+  }
+  async function handleConnectorMutate(cmd) {
+    try {
+      await sessionReady;
+    } catch (err) {
       sendEvent({
-        type: "state_changed",
-        store: `flow:${state.runId}`,
-        state
+        type: "error",
+        message: `Session not available: ${err.message}`,
+        fatal: true
       });
-    });
-    if (agentSession?.driverType === "claude-sdk") {
-      try {
-        const server = await buildSdkConnectorTools(resourceManager, { z: z });
-        if (server) {
-          if (driverStarted) {
-            const prevSessionId = driver.runtimeSessionId;
-            log(
-              `[serve] restarting driver to register flow connector tools (resume=${prevSessionId ?? "none"})`
-            );
-            await agentSession.dispose();
-            agentSession = await createAgentSession({
-              ...sessionConfig,
-              resumeSessionId: prevSessionId
+      return;
+    }
+    try {
+      if (!resourceManager) throw new Error("connector_mutate before resources ready");
+      const targetEntry = resourceManager.has?.(cmd.id) ? resourceManager.get(cmd.id) : null;
+      const isExistingFlow = targetEntry?.connector?.name === "flow";
+      const isBareFlowId = cmd.id === "flow";
+      if (cmd.op === "start") {
+        if (isExistingFlow || isBareFlowId) {
+          const payload = cmd.payload ?? {};
+          const flowDef = payload.flow;
+          const seed = payload.seed;
+          if (flowDef?.id && seed?.runId && seed?.startedBy) {
+            if (activeFlows.size > 0) {
+              serverLog.warn("connector_mutate flow.start: another flow already active", {
+                activeRunIds: Array.from(activeFlows.keys())
+              });
+              return;
+            }
+            const entry = await createActiveFlow(flowDef, { seed });
+            serverLog.info("connector_mutate flow.start", {
+              runId: entry.runId,
+              flowId: flowDef.id
             });
-            emitSystemPromptComposed(agentSession, sendEvent);
-            driver = agentSession.driver;
-            normalizer.reset();
-            driverStarted = false;
-            rebuildCompactionOrchestrator();
+            return;
           }
-          driver.config.mcpServers = { "skaile-connectors": server };
-          log(`[serve] rebuilt MCP connector tools for flow ${connectorId}`);
-        } else {
-          log(`[serve] buildSdkConnectorTools returned null for flow ${connectorId}`);
         }
-      } catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        log(`[serve] failed to rebuild MCP tools for flow: ${errMsg}`);
       }
+      let dispatchId = cmd.id;
+      if (!targetEntry && isBareFlowId) {
+        const onlyActive = getOnlyActiveFlow();
+        if (onlyActive) {
+          dispatchId = onlyActive.connectorId;
+        }
+      }
+      await resourceManager.executeOp(dispatchId, cmd.op, cmd.payload ?? {});
+    } catch (err) {
+      serverLog.warn("connector_mutate failed", {
+        id: cmd.id,
+        op: cmd.op,
+        error: err instanceof Error ? err.message : String(err)
+      });
     }
-    const entry = { runId, flowDef, adapter, handle, connectorId };
-    activeFlows.set(runId, entry);
-    return entry;
   }
-  const refreshFlagPath = join(opts.projectDir, ".skaile", "refresh-request");
-  try {
-    mkdirSync(join(opts.projectDir, ".skaile"), { recursive: true });
-    if (!existsSync(refreshFlagPath)) {
-      writeFileSync(refreshFlagPath, "", { mode: 432, flag: "a" });
+  async function handleConnectorQuery(cmd) {
+    try {
+      await sessionReady;
+    } catch (err) {
+      sendEvent({
+        type: "error",
+        message: `Session not available: ${err.message}`,
+        fatal: true
+      });
+      return;
     }
-  } catch (err) {
-    serverLog.warn("failed to pre-create refresh-flag \u2014 wake-mid-401 disabled", {
-      error: err instanceof Error ? err.message : String(err)
+    let ok = true;
+    let result;
+    let error;
+    try {
+      if (!resourceManager) throw new Error("connector_query before resources ready");
+      let dispatchId = cmd.id;
+      if (!resourceManager.has?.(cmd.id) && cmd.id === "flow") {
+        const onlyActive = getOnlyActiveFlow();
+        if (onlyActive) {
+          dispatchId = onlyActive.connectorId;
+        }
+      }
+      result = await resourceManager.executeOp(dispatchId, cmd.op, cmd.payload ?? {});
+    } catch (err) {
+      ok = false;
+      error = err instanceof Error ? err.message : String(err);
+    }
+    sendEvent({
+      type: "connector_query_response",
+      requestId: cmd.requestId,
+      ok,
+      ...result !== void 0 ? { result } : {},
+      ...error !== void 0 ? { error } : {}
     });
   }
-  let lastRefreshAt = 0;
-  const REFRESH_DEBOUNCE_MS = 2e3;
-  let refreshFlagWatcher = null;
-  try {
-    refreshFlagWatcher = watch(refreshFlagPath, (event) => {
-      if (event !== "change") return;
-      const now = Date.now();
-      if (now - lastRefreshAt < REFRESH_DEBOUNCE_MS) return;
-      lastRefreshAt = now;
-      void dispatchRefreshToExposedGitMounts(resourceManager, serverLog);
-    });
-  } catch (err) {
-    serverLog.warn("fs.watch on refresh-flag failed \u2014 wake-mid-401 disabled", {
-      error: err instanceof Error ? err.message : String(err)
-    });
+  async function computeDebugResult(cmd) {
+    switch (cmd.query) {
+      case "tools": {
+        const mcpServers = Object.keys(driver?.config?.mcpServers ?? {});
+        const allowedTools = driver?.config?.allowedTools ?? null;
+        return { mcpServers, allowedTools, driverStarted };
+      }
+      case "connectors": {
+        return resourceManager?.listConnectors?.() ?? [];
+      }
+      case "mcp": {
+        const servers = Object.entries(driver?.config?.mcpServers ?? {}).map(([name]) => ({
+          name
+        }));
+        return { servers };
+      }
+      case "config": {
+        const liveModel = driver?.getModel() ?? agentSession?.model;
+        return {
+          driver: agentSession?.driverType,
+          model: liveModel,
+          provider: agentSession?.provider,
+          maxTurns,
+          secretsMode,
+          driverStarted,
+          projectDir: opts.projectDir,
+          versions: getFrameworkVersions()
+        };
+      }
+      case "state": {
+        const storeId = cmd.args?.store;
+        if (storeId) {
+          try {
+            const snapshot = await resourceManager?.executeOp(storeId, "get", {});
+            return snapshot ? JSON.parse(snapshot) : null;
+          } catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+          }
+        }
+        const all = resourceManager?.listConnectors?.() ?? [];
+        return { stores: all.map((c) => c.id) };
+      }
+      case "commands": {
+        const commands = driver?.getSlashCommands?.() ?? [];
+        return { commands, driverType: agentSession?.driverType };
+      }
+      default:
+        return { error: `Unknown debug query: ${cmd.query}` };
+    }
   }
-  async function cleanup() {
+  async function handleDebug(cmd) {
+    if (!await awaitSessionReadyOrFail()) return;
+    log(`[serve] debug query=${cmd.query}`);
+    let result;
     try {
-      await Promise.race([
-        sessionReady,
-        new Promise((resolve3) => {
-          const t = setTimeout(resolve3, 2e3);
-          t.unref?.();
-        })
-      ]);
-    } catch {
+      result = await computeDebugResult(cmd);
+    } catch (err) {
+      result = { error: err instanceof Error ? err.message : String(err) };
     }
-    try {
-      driver?.kill();
-    } catch {
+    sendEvent({ type: "debug_result", query: cmd.query, data: result });
+  }
+  async function handleShutdown() {
+    log("[serve] shutdown requested");
+    await cleanup();
+    if (transport instanceof WebSocketServerTransport) {
+      await transport.close();
+    }
+    disposeLogStore();
+    process.exit(0);
+  }
+  function handleCapabilityResult(cmd) {
+    const matched = resolveCapabilityResult(pendingCapabilityCalls, cmd);
+    if (!matched) {
+      log(
+        `[serve] capability_result for unknown callId=${cmd.callId} (timed out or already resolved); dropping`
+      );
     }
-    aiCredentialRefreshScheduler.cancel();
-    for (const [callId, pending] of pendingCapabilityCalls) {
-      clearTimeout(pending.timer);
-      pending.reject(new Error(`Session terminated before capability_result (callId=${callId})`));
+  }
+  function handleCapabilityRegister(cmd) {
+    for (const raw of cmd.capabilities) {
+      const wire = raw;
+      capabilityRegistry.register(
+        {
+          ...wire,
+          inputZod: { parse: (v) => v },
+          outputZod: void 0,
+          handler: buildClientCapabilityHandler2(wire)
+        },
+        "client"
+      );
     }
-    pendingCapabilityCalls.clear();
-    try {
-      refreshFlagWatcher?.close();
-    } catch {
+  }
+  function handleCapabilityDeregister(cmd) {
+    for (const name of cmd.names) {
+      capabilityRegistry.deregister(name);
     }
-    refreshFlagWatcher = null;
-    if (agentSession) {
-      try {
-        await agentSession.dispose();
-      } catch {
+  }
+  function handleCapabilityApprove(cmd) {
+    if (cmd.decision === "rejected") {
+      const matched = rejectCapabilityOnApprovalDeny(
+        pendingCapabilityCalls,
+        cmd.callId,
+        cmd.feedback
+      );
+      if (!matched) {
+        log(
+          `[serve] capability_approve(rejected) for unknown callId=${cmd.callId} (already resolved or timed out); dropping`
+        );
+      } else {
+        log(
+          `[serve] capability_approve(rejected) callId=${cmd.callId} decidedBy=${cmd.decidedBy}${cmd.feedback ? ` feedback=${JSON.stringify(cmd.feedback)}` : ""}`
+        );
       }
+    } else {
+      log(
+        `[serve] capability_approve(approved) callId=${cmd.callId} decidedBy=${cmd.decidedBy} (awaiting capability_result)`
+      );
     }
   }
   async function handleCommand(cmd) {
@@ -3719,492 +4562,23 @@ async function startAgentServer(opts) {
       return;
     }
     switch (cmd.type) {
-      case "session_init": {
-        if (cmd.protocolVersion.major !== PROTOCOL_VERSION.major) {
-          log(
-            `[serve] incompatible protocol: agent=${PROTOCOL_VERSION.major} platform=${cmd.protocolVersion.major}`
-          );
-          sendEvent({
-            type: "incompatible_protocol",
-            agentVersion: PROTOCOL_VERSION,
-            platformVersion: cmd.protocolVersion
-          });
-          await cleanup();
-          disposeLogStore();
-          return;
-        }
-        if (runtimeIdentity && runtimeIdentity.containerId !== cmd.identity.containerId) {
-          log(
-            `[serve] session_init_mismatch: expected=${runtimeIdentity.containerId} received=${cmd.identity.containerId}`
-          );
-          sendEvent({
-            type: "session_init_mismatch",
-            expectedContainerId: runtimeIdentity.containerId,
-            receivedContainerId: cmd.identity.containerId
-          });
-          await cleanup();
-          disposeLogStore();
-          return;
-        }
-        runtimeIdentity = cmd.identity;
-        const incoming = cmd.capabilities ?? [];
-        for (const wire of incoming) {
-          if (wire.audience && !wire.audience.includes("llm") && !wire.audience.includes("user")) {
-            continue;
-          }
-          const stub = {
-            ...wire,
-            inputZod: { parse: (v) => v },
-            outputZod: void 0,
-            handler: buildClientCapabilityHandler2(wire)
-          };
-          capabilityRegistry.register(stub, "client");
-        }
-        sendEvent({ type: "protocol_info", version: PROTOCOL_VERSION });
-        preMintedSecrets = new PreMintedSecretProvider(cmd.credentials);
-        let initialAiCredentialExpiresAt = null;
-        if (cmd.secrets) {
-          const ccdValue = cmd.secrets[CLAUDE_CODE_CREDENTIALS_KEY];
-          if (ccdValue) {
-            const home = process.env.HOME ?? homedir();
-            if (home) {
-              try {
-                await writeClaudeCodeCredentialsFile(home, ccdValue);
-                log(
-                  `[serve] wrote Claude Code credentials file to ${home}/.claude/.credentials.json (mode 0600)`
-                );
-              } catch (err) {
-                const errMsg = err instanceof Error ? err.message : String(err);
-                log(`[serve] failed to write Claude Code credentials file: ${errMsg}`);
-              }
-            }
-            initialAiCredentialExpiresAt = extractClaudeAiOauthExpiresAt(ccdValue);
-          }
-          const otherSecrets = Object.fromEntries(
-            Object.entries(cmd.secrets).filter(([k]) => k !== CLAUDE_CODE_CREDENTIALS_KEY)
-          );
-          const provider = new InMemorySecretProvider();
-          provider.provision(otherSecrets);
-          secretProvider = provider;
-          secretsProvisioned = true;
-        }
-        try {
-          const effectiveProvider = opts.provider ?? "anthropic";
-          const envKey = providerEnvKey(effectiveProvider);
-          const apiKeyFromSecrets = cmd.secrets?.[envKey];
-          sessionConfig = buildSessionConfig(secretProvider, apiKeyFromSecrets);
-          if (!agentSession) {
-            agentSession = await createAgentSession(sessionConfig);
-            emitSystemPromptComposed(agentSession, sendEvent);
-            resourceManager = agentSession.resourceManager;
-            driver = agentSession.driver;
-            rebuildCompactionOrchestrator();
-            registerSessionComposition(agentSession);
-            sendEvent({
-              type: "resources_available",
-              ...splitConnectorsForWire(resourceManager)
-            });
-            agentSession.startWatching();
-            capabilityRegistry.setRemoteInvoker(remoteCapabilityInvoker);
-            const runnerCaps = buildRunnerCapabilities({
-              // Resource hot-plug handlers, wired to the live session's
-              // ConnectorManager + PreMintedSecretProvider via getters because
-              // both are lazily (re)assigned in this scope.
-              ...buildSessionResourceHandlers({
-                getResourceManager: () => resourceManager,
-                getPreMintedSecrets: () => preMintedSecrets,
-                emitResourcesAvailable: () => {
-                  sendEvent({
-                    type: "resources_available",
-                    ...splitConnectorsForWire(resourceManager)
-                  });
-                },
-                log
-              })
-              // setLogLevel left undefined — the cap's built-in fallback calls
-              // getLogStore()?.setLevel(...) directly. setState / lifecycle
-              // remain stubs (not resource hot-plug; out of Sprint 2 scope).
-            });
-            for (const cap of runnerCaps) {
-              capabilityRegistry.register(cap, "agent");
-            }
-            resolveSessionReady();
-            log("[serve] session built from session_init envelope");
-          }
-        } catch (err) {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          log(`[serve] session_init failed to build session: ${errMsg}`);
-          sendEvent({ type: "error", message: errMsg, fatal: true });
-          rejectSessionReady(err instanceof Error ? err : new Error(errMsg));
-        }
-        if (cmd.resolvedConfig.aiProviderConfigId) {
-          aiProviderConfigId = cmd.resolvedConfig.aiProviderConfigId;
-          log(`[serve] stashed aiProviderConfigId=${aiProviderConfigId}`);
-        }
-        if (aiProviderConfigId && initialAiCredentialExpiresAt) {
-          aiCredentialRefreshScheduler.schedule(initialAiCredentialExpiresAt);
-        }
-        const cfg = {
-          aiResources: cmd.resolvedConfig.aiResources,
-          subagents: cmd.resolvedConfig.subagents,
-          sharedState: cmd.sharedState,
-          resumeSessionId: cmd.resume?.sessionId,
-          expectedCapabilitySignature: cmd.resume?.expectedCapabilitySignature,
-          aiProviderConfigId: cmd.resolvedConfig.aiProviderConfigId
-        };
-        log(
-          `[serve] configure cfg keys=${Object.keys(cfg).join(",")} sharedState=${cfg.sharedState ? cfg.sharedState.length : "undefined"} resourceManager=${resourceManager ? "set" : "null"}`
-        );
-        let pendingResumeSessionId;
-        const cfgResumeSessionId = cfg.resumeSessionId;
-        const cfgExpectedSig = cfg.expectedCapabilitySignature;
-        if (cfgResumeSessionId) {
-          const currentSig = computeCapabilitySignature(capabilityRegistry.list());
-          if (cfgExpectedSig && cfgExpectedSig !== currentSig) {
-            log(
-              `[serve] tier-1 resume rejected: signature mismatch (expected=${cfgExpectedSig.slice(0, 12)} current=${currentSig.slice(0, 12)})`
-            );
-            sendEvent({
-              type: "resume_failed",
-              resumeSessionId: cfgResumeSessionId,
-              reason: "signature_mismatch"
-            });
-          } else {
-            log(`[serve] tier-1 resume attempted: resumeSessionId=${cfgResumeSessionId}`);
-            sendEvent({
-              type: "resume_attempted",
-              resumeSessionId: cfgResumeSessionId,
-              capabilitySignature: currentSig
-            });
-            pendingResumeSessionId = cfgResumeSessionId;
-          }
-        }
-        if (pendingResumeSessionId || cfg.subagents) {
-          await agentSession.dispose();
-          agentSession = await createAgentSession({
-            ...sessionConfig,
-            ...aiProviderConfigId ? { aiProviderConfigId } : {},
-            ...pendingResumeSessionId ? { resumeSessionId: pendingResumeSessionId } : {}
-          });
-          emitSystemPromptComposed(agentSession, sendEvent);
-          driver = agentSession.driver;
-          normalizer.reset();
-          driverStarted = false;
-          rebuildCompactionOrchestrator();
-        }
-        if (cfg.sharedState) {
-          if (!resourceManager) {
-            try {
-              registerBuiltinConnectors();
-              resourceManager = new ConnectorManager(opts.projectDir, {
-                catalogEntries: getSessionCatalogEntries(agentSession)
-              });
-              log("[serve] created ConnectorManager for sharedState (no connectors were declared)");
-            } catch (err) {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              log(`[serve] failed to create ConnectorManager: ${errMsg}`);
-              sendEvent({ type: "configured" });
-              break;
-            }
-          }
-          let storesRegistered = 0;
-          for (const stateConfig of cfg.sharedState) {
-            try {
-              if (resourceManager.has(stateConfig.id)) {
-                try {
-                  const snapshot = await resourceManager.executeOp(stateConfig.id, "get", {});
-                  const state = snapshot ? JSON.parse(snapshot) : {};
-                  sendEvent({
-                    type: "state_changed",
-                    store: stateConfig.id,
-                    state
-                  });
-                  log(
-                    `[serve] sharedState ${stateConfig.id} already registered \u2014 re-emitted current state`
-                  );
-                } catch {
-                  log(
-                    `[serve] sharedState ${stateConfig.id} already registered \u2014 skipping (could not read state)`
-                  );
-                }
-                continue;
-              }
-              const handle = await resourceManager.connect({
-                id: stateConfig.id,
-                driver: stateConfig.adapter,
-                access: "read-write",
-                options: {
-                  ...stateConfig.definition ?? {},
-                  initial: stateConfig.initialState ?? {}
-                }
-              });
-              const entry = resourceManager.get(stateConfig.id);
-              if (typeof entry.connector.onStoreChange === "function") {
-                entry.connector.onStoreChange(handle, (snapshot) => {
-                  sendEvent({
-                    type: "state_changed",
-                    store: stateConfig.id,
-                    state: snapshot
-                  });
-                });
-              }
-              log(`[serve] sharedState registered: ${stateConfig.id} (${stateConfig.adapter})`);
-              storesRegistered++;
-              sendEvent({
-                type: "state_changed",
-                store: stateConfig.id,
-                state: stateConfig.initialState ?? {}
-              });
-            } catch (err) {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              log(`[serve] sharedState registration failed for ${stateConfig.id}: ${errMsg}`);
-              sendEvent({
-                type: "error",
-                message: `sharedState ${stateConfig.id}: ${errMsg}`,
-                fatal: false
-              });
-            }
-          }
-          if (storesRegistered > 0 && !driverStarted && agentSession?.driverType === "claude-sdk") {
-            try {
-              const server = await buildSdkConnectorTools(resourceManager, { z: z });
-              if (server) {
-                driver.config.mcpServers = { "skaile-connectors": server };
-                log(`[serve] rebuilt MCP connector tools (${storesRegistered} new store(s))`);
-              } else {
-                log(`[serve] buildSdkConnectorTools returned null`);
-              }
-            } catch (err) {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              log(`[serve] failed to rebuild MCP tools: ${errMsg}`);
-            }
-          }
-        }
-        if (cfg.aiResources) {
-          const catalogActions = cfg.aiResources.filter((a) => a.action);
-          if (catalogActions.length > 0) {
-            log(`[serve] aiResources catalog actions: ${catalogActions.length}`);
-            try {
-              const skillsDir = join(
-                sessionConfig.projectDir ?? process.cwd(),
-                ".claude",
-                "skills"
-              );
-              const assetsRoot = process.env.SKAILE_ASSETS_ROOT ?? findAiAssetsRoot(sessionConfig.projectDir ?? process.cwd()) ?? "/app/ai-assets";
-              for (const res of catalogActions) {
-                if (res.action === "add" && res.entry) {
-                  const entry = res.entry;
-                  const result = deployCatalogEntry(entry, {
-                    assetsRoot,
-                    skillsDir,
-                    context: res.context
-                  });
-                  if (result.success) {
-                    log(`[serve] deployed skill: ${entry.name ?? res.name}`);
-                  } else {
-                    log(
-                      `[serve] failed to deploy skill ${entry.name ?? res.name}: ${result.error}`
-                    );
-                  }
-                } else if (res.action === "remove") {
-                  const removed = undeployCatalogEntry(res.name, skillsDir);
-                  log(`[serve] ${removed ? "removed" : "not found"} skill: ${res.name}`);
-                }
-              }
-              if (driverStarted) {
-                const prevSessionId = driver.runtimeSessionId;
-                log(
-                  `[serve] restarting driver to pick up skill changes (resume=${prevSessionId ?? "none"})`
-                );
-                await agentSession.dispose();
-                agentSession = await createAgentSession({
-                  ...sessionConfig,
-                  resumeSessionId: prevSessionId
-                });
-                emitSystemPromptComposed(agentSession, sendEvent);
-                driver = agentSession.driver;
-                normalizer.reset();
-                driverStarted = false;
-                rebuildCompactionOrchestrator();
-                sendEvent({
-                  type: "skills_changed",
-                  skills: catalogActions.map((a) => ({
-                    name: a.entry?.name ?? a.name,
-                    action: a.action ?? "add"
-                  }))
-                });
-              } else {
-                log(
-                  "[serve] aiResources applied before driver start \u2014 skills discovered on first prompt"
-                );
-              }
-            } catch (err) {
-              const errMsg = err instanceof Error ? err.message : String(err);
-              log(`[serve] aiResources handling failed: ${errMsg}`);
-              sendEvent({
-                type: "error",
-                message: `aiResources: ${errMsg}`,
-                fatal: false
-              });
-            }
-          }
-        }
-        sendEvent({
-          type: "session_init_ack",
-          capabilitySignature: computeCapabilitySignature(capabilityRegistry.list())
-        });
+      case "session_init":
+        await handleSessionInit(cmd);
         break;
-      }
-      case "prompt": {
-        try {
-          await sessionReady;
-        } catch (err) {
-          sendEvent({
-            type: "error",
-            message: `Session not available: ${err.message}`,
-            fatal: true
-          });
-          break;
-        }
-        if (!secretsProvisioned) {
-          log("[serve] prompt received before secrets provisioned \u2014 rejecting");
-          sendEvent({
-            type: "error",
-            message: "Secrets not yet provisioned \u2014 send provision_secrets first",
-            fatal: false
-          });
-          break;
-        }
-        log(`[serve] prompt: ${cmd.prompt.slice(0, 80)}...`);
-        const activeFlow = getOnlyActiveFlow();
-        if (activeFlow) {
-          sendEvent({ type: "status", phase: "thinking" });
-          try {
-            const bus = getOrCreateStimulusBus();
-            const userStimulus = {
-              kind: "user_message",
-              text: cmd.prompt,
-              senderId: "user"
-            };
-            await bus.signal(activeFlow.connectorId, {
-              promptFragment: renderStimulusPrompt(userStimulus),
-              meta: {
-                kind: "user_message",
-                runId: activeFlow.runId,
-                text: cmd.prompt,
-                senderId: "user"
-              }
-            });
-          } catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            log(`[serve] flow user-message turn failed: ${errMsg}`);
-            sendEvent({ type: "error", message: `Flow turn failed: ${errMsg}`, fatal: false });
-          }
-          break;
-        }
-        if (!driverStarted) {
-          try {
-            await driver.start();
-            driverStarted = true;
-          } catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            log(`[serve] driver start failed: ${errMsg}`);
-            sendEvent({ type: "error", message: `Driver start failed: ${errMsg}`, fatal: true });
-            break;
-          }
-          driver.on("agent-event", (event) => {
-            const normalized = normalizer.normalize(event);
-            for (const e of normalized) {
-              forwardNormalizedEvent(e);
-            }
-          });
-          driver.on("error", (err) => {
-            log(`[serve] driver error: ${err.message}`);
-            sendEvent({ type: "error", message: err.message, fatal: true });
-          });
-        }
-        sendEvent({ type: "status", phase: "thinking" });
-        try {
-          await driver.prompt(cmd.prompt);
-        } catch (err) {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          log(`[serve] prompt failed: ${errMsg}`);
-          sendEvent({ type: "error", message: `Prompt failed: ${errMsg}`, fatal: true });
-        }
+      case "prompt":
+        await handlePrompt(cmd);
         break;
-      }
-      case "reply": {
-        try {
-          await sessionReady;
-        } catch (err) {
-          sendEvent({
-            type: "error",
-            message: `Session not available: ${err.message}`,
-            fatal: true
-          });
-          break;
-        }
-        log(`[serve] reply: ${cmd.answer.slice(0, 80)}...`);
-        try {
-          await driver.prompt(cmd.answer);
-        } catch (err) {
-          sendEvent({
-            type: "error",
-            message: `Reply failed: ${err instanceof Error ? err.message : String(err)}`,
-            fatal: false
-          });
-        }
+      case "reply":
+        await handleReply(cmd);
         break;
-      }
-      case "cancel": {
-        try {
-          await sessionReady;
-        } catch (err) {
-          sendEvent({
-            type: "error",
-            message: `Session not available: ${err.message}`,
-            fatal: true
-          });
-          break;
-        }
-        log("[serve] cancel");
-        try {
-          await driver.abort();
-        } catch (err) {
-          log(`[serve] cancel failed: ${err}`);
-        }
+      case "cancel":
+        await handleCancel();
         break;
-      }
       // v3: compact + lifecycle removed — reachable via runner.lifecycle capability
       // (the v3 `runner.lifecycle` cap takes `{ phase: 'hibernate' | 'close' | 'compact' }`).
-      case "resource_request": {
-        try {
-          await sessionReady;
-        } catch (err) {
-          sendEvent({
-            type: "error",
-            message: `Session not available: ${err.message}`,
-            fatal: true
-          });
-          break;
-        }
-        if (resourceManager?.has(cmd.connectorId)) {
-          handleMountResourceRequest(cmd, resourceManager, sendEvent);
-          break;
-        }
-        if (!resourceManager) {
-          sendEvent({
-            type: "resource_response",
-            requestId: cmd.requestId,
-            resourceId: cmd.connectorId,
-            operation: cmd.operation,
-            error: "No resources available \u2014 no mounts or connectors configured"
-          });
-          break;
-        }
-        void handleResourceRequest(cmd, resourceManager, sendEvent);
+      case "resource_request":
+        await handleResourceRequestCommand(cmd);
         break;
-      }
       // v3: state_action removed — reachable via the runner.set_state capability.
       // ── Generic connector dispatch (Protocol 2.2) ──────────────────────
       // The 6 typed flow commands (`start_flow`, `approve_flow_node`,
@@ -4213,152 +4587,15 @@ async function startAgentServer(opts) {
       // extraction. Hosts now drive flow execution exclusively through
       // `connector_mutate` against the `flow` connector. See
       // `MIGRATION-flow-connector.md` for the per-op mapping table.
-      case "connector_mutate": {
-        try {
-          if (!resourceManager) throw new Error("connector_mutate before resources ready");
-          const targetEntry = resourceManager.has?.(cmd.id) ? resourceManager.get(cmd.id) : null;
-          const isExistingFlow = targetEntry?.connector?.name === "flow";
-          const isBareFlowId = cmd.id === "flow";
-          if (cmd.op === "start") {
-            if (isExistingFlow || isBareFlowId) {
-              const payload = cmd.payload ?? {};
-              const flowDef = payload.flow;
-              const seed = payload.seed;
-              if (flowDef?.id && seed?.runId && seed?.startedBy) {
-                if (activeFlows.size > 0) {
-                  serverLog.warn("connector_mutate flow.start: another flow already active", {
-                    activeRunIds: Array.from(activeFlows.keys())
-                  });
-                  break;
-                }
-                const entry = await createActiveFlow(flowDef, { seed });
-                serverLog.info("connector_mutate flow.start", {
-                  runId: entry.runId,
-                  flowId: flowDef.id
-                });
-                break;
-              }
-            }
-          }
-          let dispatchId = cmd.id;
-          if (!targetEntry && isBareFlowId) {
-            const onlyActive = getOnlyActiveFlow();
-            if (onlyActive) {
-              dispatchId = onlyActive.connectorId;
-            }
-          }
-          await resourceManager.executeOp(dispatchId, cmd.op, cmd.payload ?? {});
-        } catch (err) {
-          serverLog.warn("connector_mutate failed", {
-            id: cmd.id,
-            op: cmd.op,
-            error: err instanceof Error ? err.message : String(err)
-          });
-        }
+      case "connector_mutate":
+        await handleConnectorMutate(cmd);
         break;
-      }
-      case "connector_query": {
-        let ok = true;
-        let result;
-        let error;
-        try {
-          if (!resourceManager) throw new Error("connector_query before resources ready");
-          let dispatchId = cmd.id;
-          if (!resourceManager.has?.(cmd.id) && cmd.id === "flow") {
-            const onlyActive = getOnlyActiveFlow();
-            if (onlyActive) {
-              dispatchId = onlyActive.connectorId;
-            }
-          }
-          result = await resourceManager.executeOp(dispatchId, cmd.op, cmd.payload ?? {});
-        } catch (err) {
-          ok = false;
-          error = err instanceof Error ? err.message : String(err);
-        }
-        sendEvent({
-          type: "connector_query_response",
-          requestId: cmd.requestId,
-          ok,
-          ...result !== void 0 ? { result } : {},
-          ...error !== void 0 ? { error } : {}
-        });
+      case "connector_query":
+        await handleConnectorQuery(cmd);
         break;
-      }
-      case "debug": {
-        try {
-          await sessionReady;
-        } catch (err) {
-          sendEvent({
-            type: "error",
-            message: `Session not available: ${err.message}`,
-            fatal: true
-          });
-          break;
-        }
-        log(`[serve] debug query=${cmd.query}`);
-        let result;
-        try {
-          switch (cmd.query) {
-            case "tools": {
-              const mcpServers = Object.keys(driver?.config?.mcpServers ?? {});
-              const allowedTools = driver?.config?.allowedTools ?? null;
-              result = { mcpServers, allowedTools, driverStarted };
-              break;
-            }
-            case "connectors": {
-              result = resourceManager?.listConnectors?.() ?? [];
-              break;
-            }
-            case "mcp": {
-              const servers = Object.entries(driver?.config?.mcpServers ?? {}).map(
-                ([name]) => ({ name })
-              );
-              result = { servers };
-              break;
-            }
-            case "config": {
-              const liveModel = driver?.getModel() ?? agentSession?.model;
-              result = {
-                driver: agentSession?.driverType,
-                model: liveModel,
-                provider: agentSession?.provider,
-                maxTurns,
-                secretsMode,
-                driverStarted,
-                projectDir: opts.projectDir,
-                versions: getFrameworkVersions()
-              };
-              break;
-            }
-            case "state": {
-              const storeId = cmd.args?.store;
-              if (storeId) {
-                try {
-                  const snapshot = await resourceManager?.executeOp(storeId, "get", {});
-                  result = snapshot ? JSON.parse(snapshot) : null;
-                } catch (err) {
-                  result = { error: err instanceof Error ? err.message : String(err) };
-                }
-              } else {
-                const all = resourceManager?.listConnectors?.() ?? [];
-                result = { stores: all.map((c) => c.id) };
-              }
-              break;
-            }
-            case "commands": {
-              const commands = driver?.getSlashCommands?.() ?? [];
-              result = { commands, driverType: agentSession?.driverType };
-              break;
-            }
-            default:
-              result = { error: `Unknown debug query: ${cmd.query}` };
-          }
-        } catch (err) {
-          result = { error: err instanceof Error ? err.message : String(err) };
-        }
-        sendEvent({ type: "debug_result", query: cmd.query, data: result });
+      case "debug":
+        await handleDebug(cmd);
         break;
-      }
       // -----------------------------------------------------------------------
       // -----------------------------------------------------------------------
       // v3: add_resource, remove_resource, remount_mount, set_log_level,
@@ -4367,75 +4604,27 @@ async function startAgentServer(opts) {
       // capability invocations (audience: ['runtime']) — the platform calls
       // them through invokeRunnerCapability on the gateway. Handler bodies
       // live in the runner.* capability registrations.
-      case "shutdown": {
-        log("[serve] shutdown requested");
-        await cleanup();
-        if (transport instanceof WebSocketServerTransport) {
-          await transport.close();
-        }
-        disposeLogStore();
-        process.exit(0);
+      case "shutdown":
+        await handleShutdown();
         break;
-      }
       // Protocol v2 — capability round-trip results from the platform.
-      case "capability_result": {
-        const matched = resolveCapabilityResult(pendingCapabilityCalls, cmd);
-        if (!matched) {
-          log(
-            `[serve] capability_result for unknown callId=${cmd.callId} (timed out or already resolved); dropping`
-          );
-        }
+      case "capability_result":
+        handleCapabilityResult(cmd);
         break;
-      }
       // Protocol v2 — additional capability lifecycle commands. The platform
       // can register / deregister capabilities mid-session (e.g. when a user
       // installs an extension after `configure`). Approval routing is reserved
       // for a later phase; we accept the command shape for forward
       // compatibility and log it.
-      case "capability_register": {
-        for (const raw of cmd.capabilities) {
-          const wire = raw;
-          capabilityRegistry.register(
-            {
-              ...wire,
-              inputZod: { parse: (v) => v },
-              outputZod: void 0,
-              handler: buildClientCapabilityHandler2(wire)
-            },
-            "client"
-          );
-        }
+      case "capability_register":
+        handleCapabilityRegister(cmd);
         break;
-      }
-      case "capability_deregister": {
-        for (const name of cmd.names) {
-          capabilityRegistry.deregister(name);
-        }
+      case "capability_deregister":
+        handleCapabilityDeregister(cmd);
         break;
-      }
-      case "capability_approve": {
-        if (cmd.decision === "rejected") {
-          const matched = rejectCapabilityOnApprovalDeny(
-            pendingCapabilityCalls,
-            cmd.callId,
-            cmd.feedback
-          );
-          if (!matched) {
-            log(
-              `[serve] capability_approve(rejected) for unknown callId=${cmd.callId} (already resolved or timed out); dropping`
-            );
-          } else {
-            log(
-              `[serve] capability_approve(rejected) callId=${cmd.callId} decidedBy=${cmd.decidedBy}${cmd.feedback ? ` feedback=${JSON.stringify(cmd.feedback)}` : ""}`
-            );
-          }
-        } else {
-          log(
-            `[serve] capability_approve(approved) callId=${cmd.callId} decidedBy=${cmd.decidedBy} (awaiting capability_result)`
-          );
-        }
+      case "capability_approve":
+        handleCapabilityApprove(cmd);
         break;
-      }
     }
   }
   transport.onCommand((cmd) => {
@@ -4447,21 +4636,22 @@ async function startAgentServer(opts) {
   if (secretsMode === "env" && agentSession) {
     agentSession.startWatching();
   }
+  function emitAvailabilityOnConnect() {
+    if (resourceManager) {
+      const wire = splitConnectorsForWire(resourceManager);
+      log(
+        `[serve] emitting resources_available: ${wire.mounts.length} mount(s), ${wire.connectors.length} connector(s)`
+      );
+      sendEvent({ type: "resources_available", ...wire });
+    }
+    const commands = driver?.getSlashCommands?.() ?? [];
+    if (commands.length > 0) {
+      log(`[serve] emitting commands_available: ${commands.length} command(s)`);
+      sendEvent({ type: "commands_available", commands });
+    }
+  }
   if (transport instanceof WebSocketServerTransport) {
-    transport.onConnect(() => {
-      if (resourceManager) {
-        const wire = splitConnectorsForWire(resourceManager);
-        log(
-          `[serve] emitting resources_available: ${wire.mounts.length} mount(s), ${wire.connectors.length} connector(s)`
-        );
-        sendEvent({ type: "resources_available", ...wire });
-      }
-      const commands = driver?.getSlashCommands?.() ?? [];
-      if (commands.length > 0) {
-        log(`[serve] emitting commands_available: ${commands.length} command(s)`);
-        sendEvent({ type: "commands_available", commands });
-      }
-    });
+    transport.onConnect(emitAvailabilityOnConnect);
   }
   if (secretsMode === "env") {
     log(
@@ -4471,53 +4661,56 @@ async function startAgentServer(opts) {
     log(`[serve] secrets=provisioned \u2014 session will initialize after provision_secrets`);
   }
   log(`[serve] project=${opts.projectDir}`);
-  process.on("uncaughtException", (err) => {
-    log(
-      `[serve] uncaughtException (non-fatal): ${err instanceof Error ? err.stack ?? err.message : String(err)}`
-    );
-  });
-  process.on("unhandledRejection", (reason) => {
-    log(
-      `[serve] unhandledRejection (non-fatal): ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}`
-    );
-  });
-  const GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5e3;
-  let shuttingDown = false;
-  async function initiateShutdown(signal) {
-    if (shuttingDown) {
-      log(`[serve] ${signal} received again \u2014 forcing exit`);
-      process.exit(130);
-    }
-    shuttingDown = true;
-    log(`[serve] ${signal} received \u2014 shutting down (press Ctrl-C again to force)`);
-    const forceExitTimer = setTimeout(() => {
-      log(`[serve] graceful shutdown exceeded ${GRACEFUL_SHUTDOWN_TIMEOUT_MS}ms \u2014 forcing exit`);
-      process.exit(130);
-    }, GRACEFUL_SHUTDOWN_TIMEOUT_MS);
-    forceExitTimer.unref?.();
-    try {
-      await cleanup();
-    } catch (err) {
-      log(`[serve] cleanup error: ${err.message}`);
-    }
-    try {
-      if (transport instanceof WebSocketServerTransport) {
-        await transport.close();
+  installProcessHandlers();
+  function installProcessHandlers() {
+    process.on("uncaughtException", (err) => {
+      log(
+        `[serve] uncaughtException (non-fatal): ${err instanceof Error ? err.stack ?? err.message : String(err)}`
+      );
+    });
+    process.on("unhandledRejection", (reason) => {
+      log(
+        `[serve] unhandledRejection (non-fatal): ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}`
+      );
+    });
+    const GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5e3;
+    let shuttingDown = false;
+    async function initiateShutdown(signal) {
+      if (shuttingDown) {
+        log(`[serve] ${signal} received again \u2014 forcing exit`);
+        process.exit(130);
       }
-    } catch (err) {
-      log(`[serve] transport close error: ${err.message}`);
+      shuttingDown = true;
+      log(`[serve] ${signal} received \u2014 shutting down (press Ctrl-C again to force)`);
+      const forceExitTimer = setTimeout(() => {
+        log(`[serve] graceful shutdown exceeded ${GRACEFUL_SHUTDOWN_TIMEOUT_MS}ms \u2014 forcing exit`);
+        process.exit(130);
+      }, GRACEFUL_SHUTDOWN_TIMEOUT_MS);
+      forceExitTimer.unref?.();
+      try {
+        await cleanup();
+      } catch (err) {
+        log(`[serve] cleanup error: ${err.message}`);
+      }
+      try {
+        if (transport instanceof WebSocketServerTransport) {
+          await transport.close();
+        }
+      } catch (err) {
+        log(`[serve] transport close error: ${err.message}`);
+      }
+      clearTimeout(forceExitTimer);
+      log("[serve] shutdown complete");
+      disposeLogStore();
+      process.exit(0);
     }
-    clearTimeout(forceExitTimer);
-    log("[serve] shutdown complete");
-    disposeLogStore();
-    process.exit(0);
+    process.on("SIGTERM", () => {
+      void initiateShutdown("SIGTERM");
+    });
+    process.on("SIGINT", () => {
+      void initiateShutdown("SIGINT");
+    });
   }
-  process.on("SIGTERM", () => {
-    void initiateShutdown("SIGTERM");
-  });
-  process.on("SIGINT", () => {
-    void initiateShutdown("SIGINT");
-  });
 }
 var SESSION_DIR = ".skaile";
 var SESSIONS_SUBDIR = "sessions";
@@ -4633,5 +4826,5 @@ function touchSession(state) {
 }
 
 export { CLAUDE_CODE_CREDENTIALS_KEY, COMPILE_MANIFEST_FILENAME, CapabilityRegistry, DEFAULT_CAPABILITY_CALL_TIMEOUT_MS, DEFAULT_COALESCE_MS, MarkdownStreamer, PreInitRingSink, agentDefinitionExists, bootstrapCapabilityRegistry, bootstrapRunnerLogStore, buildAgentResources, buildClientCapabilityHandler, buildContextSection, buildEnvironmentSection, builtinCapabilities, clearPreInitRingSink, clearSession, compileComposition, computeCapabilitySignature, createAgentSession, createSessionStimulusBus, defineCapability, deleteSession, dispatchRunnerCapabilityInvocation, emitSystemPromptComposed, ensureGitConfigInclude, extractClaudeAiOauthExpiresAt, getPreInitRingSink, handleMountResourceRequest, handleResourceRequest, installPreInitRingSink, listSessions, loadAgentManifest, loadCompileManifest, loadCompileManifestFromDir, loadSession, loadSessionById, newSession, registerCompositionCapabilities, rejectCapabilityOnApprovalDeny, resetRunnerLogStore, resolveAgentComposition, resolveAgentMixins, resolveBinding, resolveCapabilityCallTimeoutMs, resolveCapabilityResult, resolveComposition, resolveMixin, runAgentChat, saveSession, setCurrentSession, startAgentServer, touchSession, writeClaudeCodeCredentialsFile };
-//# sourceMappingURL=chunk-MLJKA3S6.js.map
-//# sourceMappingURL=chunk-MLJKA3S6.js.map
+//# sourceMappingURL=chunk-XOAF5QAE.js.map
+//# sourceMappingURL=chunk-XOAF5QAE.js.map