@actant/core 0.2.1 → 0.2.2

package/dist/index.js

@@ -336,9 +336,9 @@ import { createLogger as createLogger3 } from "@actant/shared";
 // src/builder/handlers/skills-handler.ts
 var skillsHandler = {
   contextKey: "skills",
-  resolve(refs, manager) {
+  resolve(refs, manager2) {
     if (!refs || !Array.isArray(refs) || refs.length === 0) return [];
-    return manager?.resolve(refs) ?? refs.map((name) => ({ name, content: `- ${name}` }));
+    return manager2?.resolve(refs) ?? refs.map((name) => ({ name, content: `- ${name}` }));
   },
   async materialize(workspaceDir, definitions, _backendType, builder) {
     await builder.materializeSkills(workspaceDir, definitions);
@@ -348,9 +348,9 @@ var skillsHandler = {
 // src/builder/handlers/prompts-handler.ts
 var promptsHandler = {
   contextKey: "prompts",
-  resolve(refs, manager) {
+  resolve(refs, manager2) {
     if (!refs || !Array.isArray(refs) || refs.length === 0) return [];
-    return manager?.resolve(refs) ?? refs.map((name) => ({ name, content: `- ${name}` }));
+    return manager2?.resolve(refs) ?? refs.map((name) => ({ name, content: `- ${name}` }));
   },
   async materialize(workspaceDir, definitions, _backendType, builder) {
     await builder.materializePrompts(workspaceDir, definitions);
@@ -363,7 +363,7 @@ function isMcpServerRef(obj) {
 }
 var mcpServersHandler = {
   contextKey: "mcpServers",
-  resolve(refs, manager) {
+  resolve(refs, manager2) {
     if (!refs || !Array.isArray(refs) || refs.length === 0) return [];
     const arr = refs;
     if (arr.every(isMcpServerRef)) {
@@ -374,7 +374,7 @@ var mcpServersHandler = {
         env: ref.env
       }));
     }
-    return manager?.resolve(arr) ?? [];
+    return manager2?.resolve(arr) ?? [];
   },
   async materialize(workspaceDir, definitions, _backendType, builder) {
     await builder.materializeMcpConfig(workspaceDir, definitions);
@@ -384,11 +384,11 @@ var mcpServersHandler = {
 // src/builder/handlers/workflow-handler.ts
 var workflowHandler = {
   contextKey: "workflow",
-  resolve(refs, manager) {
+  resolve(refs, manager2) {
     if (refs === void 0 || refs === null) return [];
     const name = typeof refs === "string" ? refs : Array.isArray(refs) && typeof refs[0] === "string" ? refs[0] : void 0;
     if (!name) return [];
-    const resolved = manager?.resolve([name]);
+    const resolved = manager2?.resolve([name]);
     if (resolved && resolved.length > 0) return resolved;
     return [
       {
@@ -411,9 +411,9 @@ var workflowHandler = {
 // src/builder/handlers/plugins-handler.ts
 var pluginsHandler = {
   contextKey: "plugins",
-  resolve(refs, manager) {
+  resolve(refs, manager2) {
     if (!refs || !Array.isArray(refs) || refs.length === 0) return [];
-    return manager?.resolve(refs) ?? [];
+    return manager2?.resolve(refs) ?? [];
   },
   async materialize(workspaceDir, definitions, _backendType, builder) {
     await builder.materializePlugins(workspaceDir, definitions);
@@ -477,8 +477,8 @@ var WorkspaceBuilder = class {
       const refs = domainContext[handler.contextKey];
       if (refs === void 0 || refs === null) continue;
       if (Array.isArray(refs) && refs.length === 0) continue;
-      const manager = this.getManager(handler.contextKey);
-      const definitions = handler.resolve(refs, manager);
+      const manager2 = this.getManager(handler.contextKey);
+      const definitions = handler.resolve(refs, manager2);
       if (definitions.length > 0) {
         await handler.materialize(workspaceDir, definitions, backendType, activeBuilder);
         if (handler.contextKey === "mcpServers") {
@@ -1810,9 +1810,9 @@ import { createLogger as createLogger13 } from "@actant/shared";
 var logger12 = createLogger13("template-file-watcher");
 var DEFAULT_DEBOUNCE_MS = 300;
 var TemplateFileWatcher = class {
-  constructor(templatesDir, registry3, options) {
+  constructor(templatesDir, registry2, options) {
     this.templatesDir = templatesDir;
-    this.registry = registry3;
+    this.registry = registry2;
     this.debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   }
   watcher = null;
@@ -1935,7 +1935,7 @@ var LaunchModeSchema = z3.enum([
 ]);
 var ProcessOwnershipSchema = z3.enum(["managed", "external"]);
 var WorkspacePolicySchema = z3.enum(["persistent", "ephemeral"]);
-var AgentBackendTypeSchema = z3.enum(["cursor", "cursor-agent", "claude-code", "custom", "pi"]);
+var AgentBackendTypeSchema = z3.string().min(1);
 var PermissionModeSchema2 = z3.enum([
   "default",
   "acceptEdits",
@@ -2044,12 +2044,12 @@ async function updateInstanceMeta(workspaceDir, patch) {
   await writeInstanceMeta(workspaceDir, updated);
   return updated;
 }
-async function scanInstances(instancesBaseDir, registry3) {
+async function scanInstances(instancesBaseDir, registry2) {
   const valid = [];
   const corrupted = [];
   const validNames = /* @__PURE__ */ new Set();
-  if (registry3) {
-    for (const entry of registry3.list()) {
+  if (registry2) {
+    for (const entry of registry2.list()) {
       if (entry.status === "orphaned") continue;
       try {
         const st = await stat5(entry.workspacePath);
@@ -2240,8 +2240,8 @@ var logger14 = createLogger15("initialization-pipeline");
 var DEFAULT_STEP_TIMEOUT_MS = 6e4;
 var DEFAULT_TOTAL_TIMEOUT_MS = 3e5;
 var InitializationPipeline = class {
-  constructor(registry3, options) {
-    this.registry = registry3;
+  constructor(registry2, options) {
+    this.registry = registry2;
     this.stepTimeoutMs = options?.defaultStepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
     this.totalTimeoutMs = options?.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS;
     this.onProgress = options?.onProgress;
@@ -2591,7 +2591,7 @@ var ContextMaterializer = class {
     this.managers = managers;
   }
   async materialize(workspaceDir, domainContext, backendType = "cursor") {
-    const configDir = BACKEND_CONFIG_DIR[backendType];
+    const configDir = BACKEND_CONFIG_DIR[backendType] ?? ".cursor";
     const tasks = [];
     if (domainContext.skills && domainContext.skills.length > 0) {
       tasks.push(this.materializeSkills(workspaceDir, domainContext.skills));
@@ -2992,10 +2992,10 @@ var NpmInstallStep = class extends InitializerStepExecutor {
     return { valid: issues.length === 0, issues };
   }
   async execute(context, config) {
-    const { packageManager = "npm", cwd = ".", args = [], registry: registry3 } = config;
+    const { packageManager = "npm", cwd = ".", args = [], registry: registry2 } = config;
     const workDir = join16(context.workspaceDir, cwd);
     const cmdArgs = ["install", ...args];
-    if (registry3) cmdArgs.push("--registry", registry3);
+    if (registry2) cmdArgs.push("--registry", registry2);
     context.logger.debug({ packageManager, cwd: workDir, args: cmdArgs }, "Installing dependencies");
     const result = await runInstall(packageManager, cmdArgs, workDir);
     if (result.exitCode !== 0) {
@@ -3037,13 +3037,13 @@ function runInstall(pm, args, cwd) {
 
 // src/initializer/steps/index.ts
 function createDefaultStepRegistry() {
-  const registry3 = new StepRegistry();
-  registry3.register(new MkdirStep());
-  registry3.register(new ExecStep());
-  registry3.register(new FileCopyStep());
-  registry3.register(new GitCloneStep());
-  registry3.register(new NpmInstallStep());
-  return registry3;
+  const registry2 = new StepRegistry();
+  registry2.register(new MkdirStep());
+  registry2.register(new ExecStep());
+  registry2.register(new FileCopyStep());
+  registry2.register(new GitCloneStep());
+  registry2.register(new NpmInstallStep());
+  return registry2;
 }
 
 // src/manager/agent-manager.ts
@@ -3059,69 +3059,272 @@ import {
   createLogger as createLogger24
 } from "@actant/shared";
 
+// src/domain/backend/backend-manager.ts
+import { execFile } from "child_process";
+
+// src/domain/backend/backend-schema.ts
+import { z as z4 } from "zod/v4";
+var PlatformCommandSchema = z4.object({
+  win32: z4.string().min(1),
+  default: z4.string().min(1)
+});
+var OpenSpawnOptionsSchema = z4.object({
+  stdio: z4.enum(["inherit", "ignore"]).optional(),
+  detached: z4.boolean().optional(),
+  windowsHide: z4.boolean().optional(),
+  shell: z4.boolean().optional()
+});
+var ExistenceCheckSchema = z4.object({
+  command: z4.string().min(1),
+  args: z4.array(z4.string()).optional(),
+  expectedExitCode: z4.number().int().optional(),
+  versionPattern: z4.string().optional()
+});
+var InstallMethodSchema = z4.object({
+  type: z4.enum(["npm", "brew", "winget", "choco", "url", "manual"]),
+  package: z4.string().optional(),
+  platforms: z4.array(z4.string()).optional(),
+  label: z4.string().optional(),
+  instructions: z4.string().optional()
+});
+var BackendDefinitionSchema = z4.object({
+  name: z4.string().min(1),
+  version: z4.string().optional(),
+  description: z4.string().optional(),
+  tags: z4.array(z4.string()).optional(),
+  supportedModes: z4.array(z4.enum(["resolve", "open", "acp"])).min(1),
+  resolveCommand: PlatformCommandSchema.optional(),
+  openCommand: PlatformCommandSchema.optional(),
+  acpCommand: PlatformCommandSchema.optional(),
+  acpOwnsProcess: z4.boolean().optional(),
+  resolvePackage: z4.string().optional(),
+  openWorkspaceDir: z4.enum(["arg", "cwd"]).optional(),
+  openSpawnOptions: OpenSpawnOptionsSchema.optional(),
+  existenceCheck: ExistenceCheckSchema.optional(),
+  install: z4.array(InstallMethodSchema).optional()
+}).passthrough();
+
+// src/domain/backend/backend-manager.ts
+var BackendManager = class extends BaseComponentManager {
+  componentType = "Backend";
+  acpResolvers = /* @__PURE__ */ new Map();
+  constructor() {
+    super("backend-manager");
+  }
+  // ---------------------------------------------------------------------------
+  // ACP resolver (behavioral extension, not serializable)
+  // ---------------------------------------------------------------------------
+  registerAcpResolver(backendName, resolver) {
+    this.acpResolvers.set(backendName, resolver);
+  }
+  getAcpResolver(backendName) {
+    return this.acpResolvers.get(backendName);
+  }
+  // ---------------------------------------------------------------------------
+  // Mode queries
+  // ---------------------------------------------------------------------------
+  supportsMode(backendName, mode) {
+    const def = this.get(backendName);
+    return def != null && def.supportedModes.includes(mode);
+  }
+  requireMode(backendName, mode) {
+    const def = this.get(backendName);
+    if (!def) {
+      throw new Error(
+        `Backend "${backendName}" is not registered. Ensure the backend package is installed and its definition was loaded at startup.`
+      );
+    }
+    if (!def.supportedModes.includes(mode)) {
+      const supported = def.supportedModes.join(", ");
+      throw new Error(
+        `Backend "${backendName}" does not support "${mode}" mode. Supported modes: [${supported}]. ` + (mode === "resolve" ? `Use \`agent start\` or \`agent run\` instead.` : mode === "open" ? `This backend has no native TUI/UI to open.` : `Use \`agent resolve\` or \`agent open\` instead.`)
+      );
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Platform command helper
+  // ---------------------------------------------------------------------------
+  getPlatformCommand(cmd) {
+    return process.platform === "win32" ? cmd.win32 : cmd.default;
+  }
+  // ---------------------------------------------------------------------------
+  // Availability check
+  // ---------------------------------------------------------------------------
+  /**
+   * Probe whether a backend binary is available on the system.
+   * Uses the `existenceCheck` field. Returns `{ available, version? }`.
+   * If no `existenceCheck` is configured, returns `{ available: true }` (assume ok).
+   */
+  async checkAvailability(backendName) {
+    const def = this.get(backendName);
+    if (!def) return { available: false, error: `Backend "${backendName}" not registered` };
+    if (!def.existenceCheck) return { available: true };
+    const { command, args = ["--version"], expectedExitCode = 0, versionPattern } = def.existenceCheck;
+    try {
+      const { stdout, exitCode } = await execCommand(command, args);
+      if (exitCode !== expectedExitCode) {
+        return { available: false, error: `Exit code ${exitCode} (expected ${expectedExitCode})` };
+      }
+      if (versionPattern) {
+        const match = new RegExp(versionPattern).exec(stdout);
+        if (!match) {
+          return { available: false, error: `Version output didn't match pattern: ${versionPattern}` };
+        }
+        return { available: true, version: match[0] };
+      }
+      const version = stdout.trim().split("\n")[0];
+      return { available: true, version: version || void 0 };
+    } catch (err) {
+      return { available: false, error: err.message };
+    }
+  }
+  /**
+   * Get platform-appropriate install methods for a backend.
+   * Filters by `platforms` field; returns all methods if no platform restriction.
+   */
+  getInstallMethods(backendName) {
+    const def = this.get(backendName);
+    if (!def?.install) return [];
+    const plat = process.platform;
+    return def.install.filter((m) => !m.platforms || m.platforms.includes(plat));
+  }
+  // ---------------------------------------------------------------------------
+  // Validation
+  // ---------------------------------------------------------------------------
+  validate(data, _source) {
+    const result = BackendDefinitionSchema.safeParse(data);
+    if (!result.success) {
+      return {
+        valid: false,
+        errors: result.error.issues.map((i) => ({
+          path: i.path.map(String).join("."),
+          message: i.message,
+          severity: "error"
+        })),
+        warnings: []
+      };
+    }
+    return { valid: true, data: result.data, errors: [], warnings: [] };
+  }
+};
+function execCommand(command, args) {
+  return new Promise((resolve3) => {
+    execFile(command, args, { timeout: 1e4, windowsHide: true }, (err, stdout) => {
+      if (err && typeof err.code === "string" && err.code === "ENOENT") {
+        resolve3({ stdout: "", exitCode: -1 });
+        return;
+      }
+      const exitCode = err && "code" in err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+      resolve3({ stdout: stdout ?? "", exitCode });
+    });
+  });
+}
+
 // src/manager/launcher/backend-registry.ts
-var registry = /* @__PURE__ */ new Map();
+var manager = new BackendManager();
+function getBackendManager() {
+  return manager;
+}
 function registerBackend(descriptor) {
-  registry.set(descriptor.type, descriptor);
+  const { type, acpResolver, ...rest } = descriptor;
+  const definition = { ...rest, name: type };
+  manager.register(definition);
+  if (acpResolver) {
+    manager.registerAcpResolver(type, acpResolver);
+  }
+}
+function registerBackendDefinition(definition) {
+  manager.register(definition);
 }
 function getBackendDescriptor(type) {
-  const desc = registry.get(type);
-  if (!desc) {
+  const def = manager.get(type);
+  if (!def) {
     throw new Error(
       `Backend "${type}" is not registered. Ensure the backend package is installed and registerBackend() was called at startup.`
     );
   }
-  return desc;
+  return def;
 }
 function supportsMode(type, mode) {
-  const desc = registry.get(type);
-  return desc != null && desc.supportedModes.includes(mode);
+  return manager.supportsMode(type, mode);
 }
 function requireMode(type, mode) {
-  const desc = getBackendDescriptor(type);
-  if (!desc.supportedModes.includes(mode)) {
-    const supported = desc.supportedModes.join(", ");
-    throw new Error(
-      `Backend "${type}" does not support "${mode}" mode. Supported modes: [${supported}]. ` + (mode === "resolve" ? `Use \`agent start\` or \`agent run\` instead.` : mode === "open" ? `This backend has no native TUI/UI to open.` : `Use \`agent resolve\` or \`agent open\` instead.`)
-    );
-  }
+  manager.requireMode(type, mode);
 }
 function getPlatformCommand(cmd) {
-  return process.platform === "win32" ? cmd.win32 : cmd.default;
+  return manager.getPlatformCommand(cmd);
 }
-var installHints = /* @__PURE__ */ new Map([
-  ["claude-code", "npm install -g @zed-industries/claude-agent-acp"],
-  ["cursor", "Install Cursor from https://cursor.com"],
-  ["cursor-agent", "Install Cursor from https://cursor.com"]
-]);
 function getInstallHint(type) {
-  return installHints.get(type);
+  const methods = manager.getInstallMethods(type);
+  const first = methods[0];
+  return first?.label ?? first?.instructions;
+}
+function getAcpResolver(type) {
+  return manager.getAcpResolver(type);
 }
 
 // src/manager/launcher/builtin-backends.ts
-function registerBuiltinBackends() {
-  registerBackend({
-    type: "cursor",
+var BUILTIN_BACKENDS = [
+  {
+    name: "cursor",
+    version: "1.0.0",
+    description: "Cursor IDE",
+    origin: { type: "builtin" },
     supportedModes: ["resolve", "open"],
     resolveCommand: { win32: "cursor.cmd", default: "cursor" },
-    openCommand: { win32: "cursor.cmd", default: "cursor" }
-  });
-  registerBackend({
-    type: "cursor-agent",
+    openCommand: { win32: "cursor.cmd", default: "cursor" },
+    openSpawnOptions: { shell: process.platform === "win32" },
+    existenceCheck: { command: "cursor", args: ["--version"] },
+    install: [
+      { type: "url", package: "https://cursor.com", label: "Download Cursor", platforms: ["win32", "darwin", "linux"] },
+      { type: "brew", package: "cursor", label: "brew install --cask cursor", platforms: ["darwin"] },
+      { type: "winget", package: "Anysphere.Cursor", label: "winget install Anysphere.Cursor", platforms: ["win32"] }
+    ]
+  },
+  {
+    name: "cursor-agent",
+    version: "1.0.0",
+    description: "Cursor Agent (TUI)",
+    origin: { type: "builtin" },
     supportedModes: ["resolve", "open", "acp"],
-    resolveCommand: { win32: "cursor.cmd", default: "cursor" },
-    openCommand: { win32: "cursor.cmd", default: "cursor" }
-  });
-  registerBackend({
-    type: "claude-code",
+    resolveCommand: { win32: "agent", default: "agent" },
+    openCommand: { win32: "agent", default: "agent" },
+    openWorkspaceDir: "cwd",
+    openSpawnOptions: { stdio: "inherit", detached: false, windowsHide: false },
+    existenceCheck: { command: "agent", args: ["--version"] },
+    install: [
+      { type: "manual", label: "Included with Cursor", instructions: "Install Cursor from https://cursor.com \u2014 the `agent` CLI is bundled." }
+    ]
+  },
+  {
+    name: "claude-code",
+    version: "1.0.0",
+    description: "Claude Code CLI",
+    origin: { type: "builtin" },
     supportedModes: ["resolve", "open", "acp"],
     resolveCommand: { win32: "claude-agent-acp.cmd", default: "claude-agent-acp" },
-    openCommand: { win32: "claude.cmd", default: "claude" }
-  });
-  registerBackend({
-    type: "custom",
+    openCommand: { win32: "claude.exe", default: "claude" },
+    openWorkspaceDir: "cwd",
+    openSpawnOptions: { stdio: "inherit", detached: false, windowsHide: false },
+    resolvePackage: "@zed-industries/claude-agent-acp",
+    existenceCheck: { command: "claude", args: ["--version"] },
+    install: [
+      { type: "npm", package: "@anthropic-ai/claude-code", label: "npm install -g @anthropic-ai/claude-code" }
+    ]
+  },
+  {
+    name: "custom",
+    version: "1.0.0",
+    description: "Custom backend (user-provided executable)",
+    origin: { type: "builtin" },
     supportedModes: ["resolve"]
-  });
+  }
+];
+function registerBuiltinBackends() {
+  const mgr = getBackendManager();
+  for (const def of BUILTIN_BACKENDS) {
+    mgr.register(def);
+  }
 }
 registerBuiltinBackends();
 
@@ -3157,25 +3360,36 @@ function resolveBackend(backendType, workspaceDir, backendConfig) {
   })();
   return {
     command,
-    args: buildArgs(backendType, workspaceDir, backendConfig)
+    args: buildArgs(backendType, workspaceDir, backendConfig),
+    resolvePackage: desc.resolvePackage
   };
 }
+var DEFAULT_OPEN_SPAWN = {
+  stdio: "ignore",
+  detached: true,
+  windowsHide: true,
+  shell: false
+};
 function openBackend(backendType, workspaceDir) {
   requireMode(backendType, "open");
   const desc = getBackendDescriptor(backendType);
   if (!desc.openCommand) {
     throw new Error(`Backend "${backendType}" has no openCommand configured.`);
   }
+  const useCwd = desc.openWorkspaceDir === "cwd";
   return {
     command: getPlatformCommand(desc.openCommand),
-    args: [workspaceDir]
+    args: useCwd ? [] : [workspaceDir],
+    cwd: useCwd ? workspaceDir : void 0,
+    openSpawnOptions: { ...DEFAULT_OPEN_SPAWN, ...desc.openSpawnOptions }
   };
 }
 function resolveAcpBackend(backendType, workspaceDir, backendConfig) {
   requireMode(backendType, "acp");
   const desc = getBackendDescriptor(backendType);
-  if (desc.acpResolver) {
-    return desc.acpResolver(workspaceDir, backendConfig);
+  const resolver = getAcpResolver(backendType);
+  if (resolver) {
+    return resolver(workspaceDir, backendConfig);
   }
   const explicitPath = backendConfig?.executablePath;
   const commandSource = desc.acpCommand ?? desc.resolveCommand;
@@ -3184,7 +3398,8 @@ function resolveAcpBackend(backendType, workspaceDir, backendConfig) {
   })();
   return {
     command,
-    args: buildArgs(backendType, workspaceDir, backendConfig)
+    args: buildArgs(backendType, workspaceDir, backendConfig),
+    resolvePackage: desc.resolvePackage
   };
 }
 
@@ -3433,7 +3648,8 @@ var ClaudeCodeCommunicator = class {
       const child = spawn4(this.executable, args, {
         cwd: workspaceDir,
         stdio: ["pipe", "pipe", "pipe"],
-        env: { ...process.env }
+        env: { ...process.env },
+        windowsHide: true
       });
       let stdout = "";
       let stderr = "";
@@ -3469,11 +3685,18 @@ var ClaudeCodeCommunicator = class {
           } else if (subtype === "error_max_turns") {
             text = "[max turns reached \u2014 no final result text]";
           } else {
-            text = stdout.trim();
+            const costUsd = parsed["cost_usd"];
+            const duration = parsed["duration_ms"];
+            const parts = ["[no result text]"];
+            if (subtype) parts.push(`subtype=${subtype}`);
+            if (costUsd != null) parts.push(`cost=$${costUsd.toFixed(4)}`);
+            if (duration != null) parts.push(`duration=${duration}ms`);
+            text = parts.join(" ");
           }
           resolve3({ text, sessionId });
         } catch {
-          resolve3({ text: stdout.trim() });
+          const firstLine = stdout.slice(0, 200).split("\n")[0] ?? "";
+          resolve3({ text: firstLine || "[unparseable response]" });
         }
       });
       child.on("error", (err) => {
@@ -3489,7 +3712,8 @@ var ClaudeCodeCommunicator = class {
     const child = spawn4(this.executable, args, {
       cwd: workspaceDir,
       stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env }
+      env: { ...process.env },
+      windowsHide: true
     });
     const timeout = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const timer = setTimeout(() => {
@@ -3600,12 +3824,12 @@ var CursorCommunicator = class {
 };
 
 // src/communicator/create-communicator.ts
-var registry2 = /* @__PURE__ */ new Map();
+var registry = /* @__PURE__ */ new Map();
 function registerCommunicator(backendType, factory) {
-  registry2.set(backendType, factory);
+  registry.set(backendType, factory);
 }
 function createCommunicator(backendType, backendConfig) {
-  const registered = registry2.get(backendType);
+  const registered = registry.get(backendType);
   if (registered) return registered(backendConfig);
   switch (backendType) {
     case "claude-code":
@@ -3613,13 +3837,9 @@ function createCommunicator(backendType, backendConfig) {
     case "cursor":
     case "cursor-agent":
       return new CursorCommunicator();
-    case "custom":
-      throw new Error(
-        "Custom backend communicator not yet supported. Implement AgentCommunicator for your backend."
-      );
-    case "pi":
+    default:
       throw new Error(
-        "Pi backend communicator not registered. Ensure @actant/pi is installed and initialized."
+        `No communicator registered for backend "${backendType}". Register one via registerCommunicator() at startup.`
       );
   }
 }
@@ -3738,12 +3958,13 @@ var AgentManager = class {
         pid = proc.pid;
       }
       if (this.acpManager) {
-        const { command, args } = resolveAcpBackend(meta.backendType, dir, meta.backendConfig);
+        const acpResolved = resolveAcpBackend(meta.backendType, dir, meta.backendConfig);
         const providerEnv = buildProviderEnv(meta.providerConfig);
         const connResult = await this.acpManager.connect(name, {
-          command,
-          args,
+          command: acpResolved.command,
+          args: acpResolved.args,
           cwd: dir,
+          resolvePackage: acpResolved.resolvePackage,
           connectionOptions: {
             autoApprove: true,
             ...Object.keys(providerEnv).length > 0 ? { env: providerEnv } : {}
@@ -3853,14 +4074,15 @@ var AgentManager = class {
       throw new AgentNotFoundError(name);
     }
     const dir = join17(this.instancesBaseDir, name);
-    const { command, args } = resolveBackend(meta.backendType, dir, meta.backendConfig);
+    const resolved = resolveBackend(meta.backendType, dir, meta.backendConfig);
     return {
       workspaceDir: dir,
-      command,
-      args,
+      command: resolved.command,
+      args: resolved.args,
       instanceName: name,
       backendType: meta.backendType,
-      created
+      created,
+      resolvePackage: resolved.resolvePackage
     };
   }
   /**
@@ -3871,8 +4093,7 @@ var AgentManager = class {
   async openAgent(name) {
     const meta = this.requireAgent(name);
     const dir = join17(this.instancesBaseDir, name);
-    const resolved = openBackend(meta.backendType, dir);
-    return resolved;
+    return openBackend(meta.backendType, dir);
   }
   /**
    * Register an externally-spawned process with the manager.
@@ -4444,15 +4665,15 @@ function createLauncher(config) {
 }
 
 // src/domain/skill/skill-manager.ts
-import { z as z4 } from "zod/v4";
-var SkillDefinitionSchema = z4.object({
-  name: z4.string().min(1),
-  description: z4.string().optional(),
-  content: z4.string().min(1),
-  tags: z4.array(z4.string()).optional(),
-  license: z4.string().optional(),
-  compatibility: z4.string().optional(),
-  allowedTools: z4.array(z4.string()).optional()
+import { z as z5 } from "zod/v4";
+var SkillDefinitionSchema = z5.object({
+  name: z5.string().min(1),
+  description: z5.string().optional(),
+  content: z5.string().min(1),
+  tags: z5.array(z5.string()).optional(),
+  license: z5.string().optional(),
+  compatibility: z5.string().optional(),
+  allowedTools: z5.array(z5.string()).optional()
 }).passthrough();
 var SkillManager = class extends BaseComponentManager {
   componentType = "Skill";
@@ -4492,12 +4713,12 @@ ${sections.join("\n\n---\n\n")}
 };
 
 // src/domain/prompt/prompt-manager.ts
-import { z as z5 } from "zod/v4";
-var PromptDefinitionSchema = z5.object({
-  name: z5.string().min(1),
-  description: z5.string().optional(),
-  content: z5.string().min(1),
-  variables: z5.array(z5.string()).optional()
+import { z as z6 } from "zod/v4";
+var PromptDefinitionSchema = z6.object({
+  name: z6.string().min(1),
+  description: z6.string().optional(),
+  content: z6.string().min(1),
+  variables: z6.array(z6.string()).optional()
 }).passthrough();
 var PromptManager = class extends BaseComponentManager {
   componentType = "Prompt";
@@ -4549,13 +4770,13 @@ ${sections.join("\n\n---\n\n")}
 };
 
 // src/domain/mcp/mcp-config-manager.ts
-import { z as z6 } from "zod/v4";
-var McpServerDefinitionSchema = z6.object({
-  name: z6.string().min(1),
-  description: z6.string().optional(),
-  command: z6.string().min(1),
-  args: z6.array(z6.string()).optional(),
-  env: z6.record(z6.string(), z6.string()).optional()
+import { z as z7 } from "zod/v4";
+var McpServerDefinitionSchema = z7.object({
+  name: z7.string().min(1),
+  description: z7.string().optional(),
+  command: z7.string().min(1),
+  args: z7.array(z7.string()).optional(),
+  env: z7.record(z7.string(), z7.string()).optional()
 }).passthrough();
 var McpConfigManager = class extends BaseComponentManager {
   componentType = "McpServer";
@@ -4595,11 +4816,11 @@ var McpConfigManager = class extends BaseComponentManager {
 };
 
 // src/domain/workflow/workflow-manager.ts
-import { z as z7 } from "zod/v4";
-var WorkflowDefinitionSchema = z7.object({
-  name: z7.string().min(1),
-  description: z7.string().optional(),
-  content: z7.string().min(1)
+import { z as z8 } from "zod/v4";
+var WorkflowDefinitionSchema = z8.object({
+  name: z8.string().min(1),
+  description: z8.string().optional(),
+  content: z8.string().min(1)
 }).passthrough();
 var WorkflowManager = class extends BaseComponentManager {
   componentType = "Workflow";
@@ -4628,14 +4849,14 @@ var WorkflowManager = class extends BaseComponentManager {
 };
 
 // src/domain/plugin/plugin-manager.ts
-import { z as z8 } from "zod/v4";
-var PluginDefinitionSchema = z8.object({
-  name: z8.string().min(1),
-  description: z8.string().optional(),
-  type: z8.enum(["npm", "file", "config"]),
-  source: z8.string().optional(),
-  config: z8.record(z8.string(), z8.unknown()).optional(),
-  enabled: z8.boolean().optional().default(true)
+import { z as z9 } from "zod/v4";
+var PluginDefinitionSchema = z9.object({
+  name: z9.string().min(1),
+  description: z9.string().optional(),
+  type: z9.enum(["npm", "file", "config"]),
+  source: z9.string().optional(),
+  config: z9.record(z9.string(), z9.unknown()).optional(),
+  enabled: z9.boolean().optional().default(true)
 }).passthrough();
 var PluginManager = class extends BaseComponentManager {
   componentType = "Plugin";
@@ -5023,7 +5244,7 @@ var SessionRegistry = class {
 // src/source/github-source.ts
 import { join as join20 } from "path";
 import { mkdir as mkdir13, rm as rm5 } from "fs/promises";
-import { execFile } from "child_process";
+import { execFile as execFile2 } from "child_process";
 import { promisify } from "util";
 import { createLogger as createLogger31 } from "@actant/shared";
 
@@ -5054,16 +5275,17 @@ var LocalSource = class {
   async loadPackage() {
     const rootDir = this.config.path;
     const manifest = await this.loadManifest(rootDir);
-    const [skills, prompts, mcpServers, workflows, presets, templates] = await Promise.all([
+    const [skills, prompts, mcpServers, workflows, backends, presets, templates] = await Promise.all([
       this.loadJsonDir(rootDir, manifest.components?.skills, "skills"),
       this.loadJsonDir(rootDir, manifest.components?.prompts, "prompts"),
       this.loadJsonDir(rootDir, manifest.components?.mcp, "mcp"),
       this.loadJsonDir(rootDir, manifest.components?.workflows, "workflows"),
+      this.loadJsonDir(rootDir, manifest.components?.backends, "backends"),
       this.loadPresets(rootDir, manifest.presets),
       this.loadJsonDir(rootDir, manifest.components?.templates, "templates")
     ]);
     logger29.info({ packageName: this.packageName, rootDir }, "Local package loaded");
-    return { manifest, skills, prompts, mcpServers, workflows, presets, templates };
+    return { manifest, skills, prompts, mcpServers, workflows, backends, presets, templates };
   }
   async loadManifest(rootDir) {
     const manifestPath = join19(rootDir, "actant.json");
@@ -5155,7 +5377,7 @@ var LocalSource = class {
 };
 
 // src/source/github-source.ts
-var execFileAsync = promisify(execFile);
+var execFileAsync = promisify(execFile2);
 var logger30 = createLogger31("github-source");
 var GitHubSource = class {
   type = "github";
@@ -5449,6 +5671,11 @@ var SourceManager = class {
     for (const wf of result.workflows) {
       this.managers.workflowManager.register(ns(wf));
     }
+    if (this.managers.backendManager) {
+      for (const backend of result.backends) {
+        this.managers.backendManager.register(ns(backend));
+      }
+    }
     for (const preset of result.presets) {
       this.presets.set(`${packageName}@${preset.name}`, preset);
     }
@@ -5477,6 +5704,7 @@ var SourceManager = class {
         prompts: result.prompts.length,
         mcp: result.mcpServers.length,
         workflows: result.workflows.length,
+        backends: result.backends.length,
         presets: result.presets.length,
         templates: result.templates.length
       },
@@ -5496,6 +5724,9 @@ var SourceManager = class {
     removeFrom(this.managers.promptManager);
     removeFrom(this.managers.mcpConfigManager);
     removeFrom(this.managers.workflowManager);
+    if (this.managers.backendManager) {
+      removeFrom(this.managers.backendManager);
+    }
     if (this.managers.templateRegistry) {
       for (const t of this.managers.templateRegistry.list()) {
         if (t.name.startsWith(prefix)) {
@@ -5609,66 +5840,100 @@ import { readFile as readFile8, readdir as readdir6, stat as stat9, access as ac
 import { join as join22, relative as relative2, extname as extname4 } from "path";
 
 // src/source/source-schemas.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var VersionedComponentFields = {
-  name: z9.string().min(1, "name is required"),
-  version: z9.string().optional(),
-  description: z9.string().optional(),
-  $type: z9.string().optional(),
-  $version: z9.number().optional(),
-  origin: z9.object({
-    type: z9.enum(["builtin", "source", "local"]),
-    sourceName: z9.string().optional(),
-    syncHash: z9.string().optional(),
-    syncedAt: z9.string().optional(),
-    modified: z9.boolean().optional()
+  name: z10.string().min(1, "name is required"),
+  version: z10.string().optional(),
+  description: z10.string().optional(),
+  $type: z10.string().optional(),
+  $version: z10.number().optional(),
+  origin: z10.object({
+    type: z10.enum(["builtin", "source", "local"]),
+    sourceName: z10.string().optional(),
+    syncHash: z10.string().optional(),
+    syncedAt: z10.string().optional(),
+    modified: z10.boolean().optional()
   }).optional(),
-  tags: z9.array(z9.string()).optional()
+  tags: z10.array(z10.string()).optional()
 };
-var PackageManifestSchema = z9.object({
-  name: z9.string().min(1, "name is required"),
-  version: z9.string().optional(),
-  description: z9.string().optional(),
-  components: z9.object({
-    skills: z9.array(z9.string()).optional(),
-    prompts: z9.array(z9.string()).optional(),
-    mcp: z9.array(z9.string()).optional(),
-    workflows: z9.array(z9.string()).optional(),
-    templates: z9.array(z9.string()).optional()
+var PackageManifestSchema = z10.object({
+  name: z10.string().min(1, "name is required"),
+  version: z10.string().optional(),
+  description: z10.string().optional(),
+  components: z10.object({
+    skills: z10.array(z10.string()).optional(),
+    prompts: z10.array(z10.string()).optional(),
+    mcp: z10.array(z10.string()).optional(),
+    workflows: z10.array(z10.string()).optional(),
+    templates: z10.array(z10.string()).optional(),
+    backends: z10.array(z10.string()).optional()
   }).optional(),
-  presets: z9.array(z9.string()).optional()
+  presets: z10.array(z10.string()).optional()
 });
-var SkillDefinitionSchema2 = z9.object({
+var SkillDefinitionSchema2 = z10.object({
   ...VersionedComponentFields,
-  content: z9.string().min(1, "content is required"),
-  license: z9.string().optional(),
-  compatibility: z9.string().optional(),
-  allowedTools: z9.array(z9.string()).optional()
+  content: z10.string().min(1, "content is required"),
+  license: z10.string().optional(),
+  compatibility: z10.string().optional(),
+  allowedTools: z10.array(z10.string()).optional()
 });
-var PromptDefinitionSchema2 = z9.object({
+var PromptDefinitionSchema2 = z10.object({
   ...VersionedComponentFields,
-  content: z9.string().min(1, "content is required"),
-  variables: z9.array(z9.string()).optional()
+  content: z10.string().min(1, "content is required"),
+  variables: z10.array(z10.string()).optional()
 });
-var McpServerDefinitionSchema2 = z9.object({
+var McpServerDefinitionSchema2 = z10.object({
   ...VersionedComponentFields,
-  command: z9.string().min(1, "command is required"),
-  args: z9.array(z9.string()).optional(),
-  env: z9.record(z9.string(), z9.string()).optional()
+  command: z10.string().min(1, "command is required"),
+  args: z10.array(z10.string()).optional(),
+  env: z10.record(z10.string(), z10.string()).optional()
 });
-var WorkflowDefinitionSchema2 = z9.object({
+var WorkflowDefinitionSchema2 = z10.object({
   ...VersionedComponentFields,
-  content: z9.string().min(1, "content is required")
+  content: z10.string().min(1, "content is required")
 });
-var PresetDefinitionSchema = z9.object({
-  name: z9.string().min(1, "name is required"),
-  version: z9.string().optional(),
-  description: z9.string().optional(),
-  skills: z9.array(z9.string()).optional(),
-  prompts: z9.array(z9.string()).optional(),
-  mcpServers: z9.array(z9.string()).optional(),
-  workflows: z9.array(z9.string()).optional(),
-  templates: z9.array(z9.string()).optional()
+var PlatformCommandSchema2 = z10.object({
+  win32: z10.string().min(1),
+  default: z10.string().min(1)
+});
+var SourceBackendDefinitionSchema = z10.object({
+  ...VersionedComponentFields,
+  supportedModes: z10.array(z10.enum(["resolve", "open", "acp"])).min(1),
+  resolveCommand: PlatformCommandSchema2.optional(),
+  openCommand: PlatformCommandSchema2.optional(),
+  acpCommand: PlatformCommandSchema2.optional(),
+  acpOwnsProcess: z10.boolean().optional(),
+  resolvePackage: z10.string().optional(),
+  openWorkspaceDir: z10.enum(["arg", "cwd"]).optional(),
+  openSpawnOptions: z10.object({
+    stdio: z10.enum(["inherit", "ignore"]).optional(),
+    detached: z10.boolean().optional(),
+    windowsHide: z10.boolean().optional(),
+    shell: z10.boolean().optional()
+  }).optional(),
+  existenceCheck: z10.object({
+    command: z10.string().min(1),
+    args: z10.array(z10.string()).optional(),
+    expectedExitCode: z10.number().int().optional(),
+    versionPattern: z10.string().optional()
+  }).optional(),
+  install: z10.array(z10.object({
+    type: z10.enum(["npm", "brew", "winget", "choco", "url", "manual"]),
+    package: z10.string().optional(),
+    platforms: z10.array(z10.string()).optional(),
+    label: z10.string().optional(),
+    instructions: z10.string().optional()
+  })).optional()
+});
+var PresetDefinitionSchema = z10.object({
+  name: z10.string().min(1, "name is required"),
+  version: z10.string().optional(),
+  description: z10.string().optional(),
+  skills: z10.array(z10.string()).optional(),
+  prompts: z10.array(z10.string()).optional(),
+  mcpServers: z10.array(z10.string()).optional(),
+  workflows: z10.array(z10.string()).optional(),
+  templates: z10.array(z10.string()).optional()
 });
 
 // src/source/source-validator.ts
@@ -6276,6 +6541,7 @@ export {
   AgentStatusSchema,
   AgentTemplateSchema,
   BUILTIN_PROVIDERS,
+  BackendManager,
   BaseComponentManager,
   ClaudeCodeBuilder,
   ClaudeCodeCommunicator,
@@ -6343,6 +6609,8 @@ export {
   createDefaultStepRegistry,
   createLauncher,
   getBackendDescriptor,
+  getBackendManager,
+  getInstallHint,
   getLaunchModeHandler,
   globMatch,
   isAcpBackend,
@@ -6353,6 +6621,7 @@ export {
   openBackend,
   readInstanceMeta,
   registerBackend,
+  registerBackendDefinition,
   registerBuiltinProviders,
   registerCommunicator,
   requireMode,