@actant/core 0.1.2 → 0.2.0

package/dist/index.js

@@ -1061,11 +1061,13 @@ var DomainContextSchema = z2.object({
   extensions: z2.record(z2.string(), z2.array(z2.unknown())).optional()
 });
 var AgentBackendSchema = z2.object({
-  type: z2.enum(["cursor", "claude-code", "custom"]),
+  type: z2.enum(["cursor", "cursor-agent", "claude-code", "custom", "pi"]),
   config: z2.record(z2.string(), z2.unknown()).optional()
 });
 var ModelProviderSchema = z2.object({
-  type: z2.enum(["anthropic", "openai", "custom"]),
+  type: z2.enum(["anthropic", "openai", "openai-compatible", "custom"]),
+  protocol: z2.enum(["http", "websocket", "grpc"]).optional().default("http"),
+  baseUrl: z2.string().optional(),
   config: z2.record(z2.string(), z2.unknown()).optional()
 });
 var InitializerStepSchema = z2.object({
@@ -1721,9 +1723,9 @@ import { createLogger as createLogger12 } from "@actant/shared";
 var logger11 = createLogger12("template-file-watcher");
 var DEFAULT_DEBOUNCE_MS = 300;
 var TemplateFileWatcher = class {
-  constructor(templatesDir, registry, options) {
+  constructor(templatesDir, registry3, options) {
     this.templatesDir = templatesDir;
-    this.registry = registry;
+    this.registry = registry3;
     this.debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   }
   watcher = null;
@@ -1846,7 +1848,7 @@ var LaunchModeSchema = z3.enum([
 ]);
 var ProcessOwnershipSchema = z3.enum(["managed", "external"]);
 var WorkspacePolicySchema = z3.enum(["persistent", "ephemeral"]);
-var AgentBackendTypeSchema = z3.enum(["cursor", "claude-code", "custom"]);
+var AgentBackendTypeSchema = z3.enum(["cursor", "cursor-agent", "claude-code", "custom", "pi"]);
 var PermissionModeSchema2 = z3.enum([
   "default",
   "acceptEdits",
@@ -1947,12 +1949,12 @@ async function updateInstanceMeta(workspaceDir, patch) {
   await writeInstanceMeta(workspaceDir, updated);
   return updated;
 }
-async function scanInstances(instancesBaseDir, registry) {
+async function scanInstances(instancesBaseDir, registry3) {
   const valid = [];
   const corrupted = [];
   const validNames = /* @__PURE__ */ new Set();
-  if (registry) {
-    for (const entry of registry.list()) {
+  if (registry3) {
+    for (const entry of registry3.list()) {
       if (entry.status === "orphaned") continue;
       try {
         const st = await stat5(entry.workspacePath);
@@ -2143,8 +2145,8 @@ var logger13 = createLogger14("initialization-pipeline");
 var DEFAULT_STEP_TIMEOUT_MS = 6e4;
 var DEFAULT_TOTAL_TIMEOUT_MS = 3e5;
 var InitializationPipeline = class {
-  constructor(registry, options) {
-    this.registry = registry;
+  constructor(registry3, options) {
+    this.registry = registry3;
     this.stepTimeoutMs = options?.defaultStepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
     this.totalTimeoutMs = options?.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS;
     this.onProgress = options?.onProgress;
@@ -2273,6 +2275,9 @@ var AgentInitializer = class {
   }
   builder;
   pipeline;
+  get workspaceBuilder() {
+    return this.builder;
+  }
   /**
    * Create a new Agent Instance.
    * 1. Resolve template from registry
@@ -2462,7 +2467,9 @@ import { createLogger as createLogger16 } from "@actant/shared";
 var logger15 = createLogger16("context-materializer");
 var BACKEND_CONFIG_DIR = {
   cursor: ".cursor",
+  "cursor-agent": ".cursor",
   "claude-code": ".claude",
+  pi: ".pi",
   custom: ".cursor"
 };
 var ContextMaterializer = class {
@@ -2871,10 +2878,10 @@ var NpmInstallStep = class extends InitializerStepExecutor {
     return { valid: issues.length === 0, issues };
   }
   async execute(context, config) {
-    const { packageManager = "npm", cwd = ".", args = [], registry } = config;
+    const { packageManager = "npm", cwd = ".", args = [], registry: registry3 } = config;
     const workDir = join16(context.workspaceDir, cwd);
     const cmdArgs = ["install", ...args];
-    if (registry) cmdArgs.push("--registry", registry);
+    if (registry3) cmdArgs.push("--registry", registry3);
     context.logger.debug({ packageManager, cwd: workDir, args: cmdArgs }, "Installing dependencies");
     const result = await runInstall(packageManager, cmdArgs, workDir);
     if (result.exitCode !== 0) {
@@ -2916,13 +2923,13 @@ function runInstall(pm, args, cwd) {
 
 // src/initializer/steps/index.ts
 function createDefaultStepRegistry() {
-  const registry = new StepRegistry();
-  registry.register(new MkdirStep());
-  registry.register(new ExecStep());
-  registry.register(new FileCopyStep());
-  registry.register(new GitCloneStep());
-  registry.register(new NpmInstallStep());
-  return registry;
+  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;
 }
 
 // src/manager/agent-manager.ts
@@ -2936,36 +2943,120 @@ import {
   createLogger as createLogger23
 } from "@actant/shared";
 
-// src/manager/launcher/backend-resolver.ts
-var IS_WINDOWS = process.platform === "win32";
-var DEFAULT_COMMANDS = {
-  cursor: () => IS_WINDOWS ? "cursor.cmd" : "cursor",
-  "claude-code": () => IS_WINDOWS ? "claude-agent-acp.cmd" : "claude-agent-acp",
-  custom: () => {
-    throw new Error("Custom backend requires explicit executablePath in backend config");
+// src/manager/launcher/backend-registry.ts
+var registry = /* @__PURE__ */ new Map();
+function registerBackend(descriptor) {
+  registry.set(descriptor.type, descriptor);
+}
+function getBackendDescriptor(type) {
+  const desc = registry.get(type);
+  if (!desc) {
+    throw new Error(
+      `Backend "${type}" is not registered. Ensure the backend package is installed and registerBackend() was called at startup.`
+    );
   }
-};
+  return desc;
+}
+function supportsMode(type, mode) {
+  const desc = registry.get(type);
+  return desc != null && desc.supportedModes.includes(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.`)
+    );
+  }
+}
+function getPlatformCommand(cmd) {
+  return process.platform === "win32" ? cmd.win32 : cmd.default;
+}
+
+// src/manager/launcher/builtin-backends.ts
+function registerBuiltinBackends() {
+  registerBackend({
+    type: "cursor",
+    supportedModes: ["resolve", "open"],
+    resolveCommand: { win32: "cursor.cmd", default: "cursor" },
+    openCommand: { win32: "cursor.cmd", default: "cursor" }
+  });
+  registerBackend({
+    type: "cursor-agent",
+    supportedModes: ["resolve", "open", "acp"],
+    resolveCommand: { win32: "cursor.cmd", default: "cursor" },
+    openCommand: { win32: "cursor.cmd", default: "cursor" }
+  });
+  registerBackend({
+    type: "claude-code",
+    supportedModes: ["resolve", "acp"],
+    resolveCommand: { win32: "claude-agent-acp.cmd", default: "claude-agent-acp" }
+  });
+  registerBackend({
+    type: "custom",
+    supportedModes: ["resolve"]
+  });
+}
+registerBuiltinBackends();
+
+// src/manager/launcher/backend-resolver.ts
 function isAcpBackend(backendType) {
-  return backendType === "claude-code";
+  return supportsMode(backendType, "acp");
+}
+function isAcpOnlyBackend(backendType) {
+  const desc = getBackendDescriptor(backendType);
+  return supportsMode(backendType, "acp") && desc.acpOwnsProcess === true;
 }
 function buildArgs(backendType, workspaceDir, backendConfig) {
-  switch (backendType) {
-    case "cursor":
-      return [workspaceDir];
-    case "claude-code":
-      return [];
-    case "custom": {
-      const configArgs = backendConfig?.args;
-      if (Array.isArray(configArgs)) {
-        return configArgs.map(String);
-      }
-      return [workspaceDir];
-    }
+  const desc = getBackendDescriptor(backendType);
+  if (backendType === "custom") {
+    const configArgs = backendConfig?.args;
+    if (Array.isArray(configArgs)) return configArgs.map(String);
+    return [workspaceDir];
+  }
+  if (desc.supportedModes.includes("open") && !desc.supportedModes.includes("acp")) {
+    return [workspaceDir];
+  }
+  if (desc.supportedModes.includes("acp")) {
+    return [];
   }
+  return [workspaceDir];
 }
 function resolveBackend(backendType, workspaceDir, backendConfig) {
+  requireMode(backendType, "resolve");
+  const desc = getBackendDescriptor(backendType);
+  const explicitPath = backendConfig?.executablePath;
+  const command = typeof explicitPath === "string" && explicitPath.length > 0 ? explicitPath : desc.resolveCommand ? getPlatformCommand(desc.resolveCommand) : (() => {
+    throw new Error(`Backend "${backendType}" has no resolveCommand configured.`);
+  })();
+  return {
+    command,
+    args: buildArgs(backendType, workspaceDir, backendConfig)
+  };
+}
+function openBackend(backendType, workspaceDir) {
+  requireMode(backendType, "open");
+  const desc = getBackendDescriptor(backendType);
+  if (!desc.openCommand) {
+    throw new Error(`Backend "${backendType}" has no openCommand configured.`);
+  }
+  return {
+    command: getPlatformCommand(desc.openCommand),
+    args: [workspaceDir]
+  };
+}
+function resolveAcpBackend(backendType, workspaceDir, backendConfig) {
+  requireMode(backendType, "acp");
+  const desc = getBackendDescriptor(backendType);
+  if (desc.acpResolver) {
+    return desc.acpResolver(workspaceDir, backendConfig);
+  }
   const explicitPath = backendConfig?.executablePath;
-  const command = typeof explicitPath === "string" && explicitPath.length > 0 ? explicitPath : DEFAULT_COMMANDS[backendType]();
+  const commandSource = desc.acpCommand ?? desc.resolveCommand;
+  const command = typeof explicitPath === "string" && explicitPath.length > 0 ? explicitPath : commandSource ? getPlatformCommand(commandSource) : (() => {
+    throw new Error(`Backend "${backendType}" has no command configured for ACP spawn.`);
+  })();
   return {
     command,
     args: buildArgs(backendType, workspaceDir, backendConfig)
@@ -3384,16 +3475,27 @@ var CursorCommunicator = class {
 };
 
 // src/communicator/create-communicator.ts
-function createCommunicator(backendType) {
+var registry2 = /* @__PURE__ */ new Map();
+function registerCommunicator(backendType, factory) {
+  registry2.set(backendType, factory);
+}
+function createCommunicator(backendType, backendConfig) {
+  const registered = registry2.get(backendType);
+  if (registered) return registered(backendConfig);
   switch (backendType) {
     case "claude-code":
       return new ClaudeCodeCommunicator();
     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":
+      throw new Error(
+        "Pi backend communicator not registered. Ensure @actant/pi is installed and initialized."
+      );
   }
 }
 
@@ -3486,13 +3588,16 @@ var AgentManager = class {
     return { meta, created };
   }
   /**
-   * Start an agent — launch the backend process.
-   * For ACP backends, also establishes ACP connection (initialize + session/new).
+   * Start an agent — launch the backend process via ACP.
+   * Requires the backend to support "acp" mode.
+   * For acpOwnsProcess backends, ProcessLauncher is skipped.
    * @throws {AgentNotFoundError} if agent is not in cache
    * @throws {AgentAlreadyRunningError} if agent is already running
+   * @throws {Error} if backend does not support "acp" mode
    */
   async startAgent(name) {
     const meta = this.requireAgent(name);
+    requireMode(meta.backendType, "acp");
     if (meta.status === "running" || meta.status === "starting") {
       throw new AgentAlreadyRunningError(name);
     }
@@ -3500,23 +3605,34 @@ var AgentManager = class {
     const starting = await updateInstanceMeta(dir, { status: "starting" });
     this.cache.set(name, starting);
     try {
-      const proc = await this.launcher.launch(dir, starting);
-      this.processes.set(name, proc);
-      if (isAcpBackend(meta.backendType) && this.acpManager) {
-        const { command, args } = resolveBackend(meta.backendType, dir, meta.backendConfig);
-        await this.acpManager.connect(name, {
+      const acpOnly = isAcpOnlyBackend(meta.backendType);
+      let pid;
+      if (!acpOnly) {
+        const proc = await this.launcher.launch(dir, starting);
+        this.processes.set(name, proc);
+        pid = proc.pid;
+      }
+      if (this.acpManager) {
+        const { command, args } = resolveAcpBackend(meta.backendType, dir, meta.backendConfig);
+        const connResult = await this.acpManager.connect(name, {
           command,
           args,
           cwd: dir,
           connectionOptions: { autoApprove: true }
         });
-        logger22.info({ name }, "ACP connection established");
+        logger22.info({ name, acpOnly }, "ACP connection established");
+        if (acpOnly && "pid" in connResult && typeof connResult.pid === "number") {
+          pid = connResult.pid;
+          this.processes.set(name, { pid, workspaceDir: dir, instanceName: name });
+        }
       }
-      const running = await updateInstanceMeta(dir, { status: "running", pid: proc.pid });
+      const running = await updateInstanceMeta(dir, { status: "running", pid });
       this.cache.set(name, running);
-      this.watcher.watch(name, proc.pid);
+      if (pid) {
+        this.watcher.watch(name, pid);
+      }
       this.restartTracker.recordStart(name);
-      logger22.info({ name, pid: proc.pid, launchMode: starting.launchMode, acp: isAcpBackend(meta.backendType) }, "Agent started");
+      logger22.info({ name, pid, launchMode: starting.launchMode, acp: true }, "Agent started");
     } catch (err) {
       if (this.acpManager?.has(name)) {
         await this.acpManager.disconnect(name).catch(() => {
@@ -3611,6 +3727,17 @@ var AgentManager = class {
       created
     };
   }
+  /**
+   * Open an agent's native TUI/UI (e.g. `cursor <dir>`).
+   * Requires the backend to support "open" mode.
+   * @throws if backend does not support "open" mode
+   */
+  async openAgent(name) {
+    const meta = this.requireAgent(name);
+    const dir = join17(this.instancesBaseDir, name);
+    const resolved = openBackend(meta.backendType, dir);
+    return resolved;
+  }
   /**
    * Register an externally-spawned process with the manager.
    * Sets processOwnership to "external" and registers ProcessWatcher monitoring.
@@ -3685,14 +3812,46 @@ var AgentManager = class {
   }
   /**
    * Send a prompt to an agent and stream the response.
-   * Uses ACP connection if available, otherwise falls back to CLI pipe mode.
+   * Uses ACP connection if available, otherwise falls back to communicator.
    */
   streamPrompt(name, prompt, options) {
     const meta = this.requireAgent(name);
+    if (this.acpManager?.has(name)) {
+      const conn = this.acpManager.getConnection(name);
+      const sessionId = this.acpManager.getPrimarySessionId(name);
+      if (conn && sessionId) {
+        logger22.debug({ name, sessionId }, "Streaming prompt via ACP");
+        return this.streamFromAcp(conn, sessionId, prompt);
+      }
+    }
     const dir = join17(this.instancesBaseDir, name);
     const communicator = createCommunicator(meta.backendType);
     return communicator.streamPrompt(dir, prompt, options);
   }
+  async *streamFromAcp(conn, sessionId, prompt) {
+    try {
+      for await (const event of conn.streamPrompt(sessionId, prompt)) {
+        const record = event;
+        const type = record["type"];
+        if (type === "text" || type === "assistant") {
+          const content = record["content"] ?? record["message"] ?? "";
+          yield { type: "text", content };
+        } else if (type === "tool_use") {
+          const toolName = record["name"];
+          yield { type: "tool_use", content: toolName ? `[Tool: ${toolName}]` : "" };
+        } else if (type === "result") {
+          yield { type: "result", content: record["result"] ?? "" };
+        } else if (type === "error") {
+          const errMsg = record["error"]?.["message"];
+          yield { type: "error", content: errMsg ?? "Unknown error" };
+        } else if (typeof record["content"] === "string") {
+          yield { type: "text", content: record["content"] };
+        }
+      }
+    } catch (err) {
+      yield { type: "error", content: err instanceof Error ? err.message : String(err) };
+    }
+  }
   /**
    * Send a message to a running agent via its ACP session.
    * Unlike runPrompt, this requires the agent to be started with ACP.
@@ -4901,11 +5060,13 @@ var SourceManager = class {
   homeDir;
   sourcesFilePath;
   cacheDir;
-  constructor(homeDir, managers) {
+  skipDefaultSource;
+  constructor(homeDir, managers, options) {
     this.homeDir = homeDir;
     this.managers = managers;
     this.sourcesFilePath = join21(homeDir, "sources.json");
     this.cacheDir = join21(homeDir, "sources-cache");
+    this.skipDefaultSource = options?.skipDefaultSource ?? false;
   }
   // ---------------------------------------------------------------------------
   // Source CRUD
@@ -5039,14 +5200,13 @@ var SourceManager = class {
   // Initialization (load persisted sources on startup)
   // ---------------------------------------------------------------------------
   async initialize() {
-    let entries;
+    let entries = [];
     try {
       const raw = await readFile7(this.sourcesFilePath, "utf-8");
       const data = JSON.parse(raw);
       entries = Object.entries(data.sources ?? {}).map(([name, config]) => ({ name, config }));
     } catch {
       logger30.debug("No sources.json found, starting with empty sources");
-      return;
     }
     for (const entry of entries) {
       try {
@@ -5059,6 +5219,21 @@ var SourceManager = class {
         logger30.warn({ name: entry.name, error: err }, "Failed to restore source, skipping");
       }
     }
+    await this.ensureDefaultSource();
+  }
+  /**
+   * Registers the official actant-hub as the default source if not already present.
+   * Fails silently when offline or the repo is unreachable.
+   */
+  async ensureDefaultSource() {
+    if (this.skipDefaultSource) return;
+    if (this.sources.has(DEFAULT_SOURCE_NAME)) return;
+    try {
+      await this.addSource(DEFAULT_SOURCE_NAME, DEFAULT_SOURCE_CONFIG);
+      logger30.info("Default source registered: %s", DEFAULT_SOURCE_NAME);
+    } catch (err) {
+      logger30.debug({ error: err }, "Failed to register default source (offline?), skipping");
+    }
   }
   // ---------------------------------------------------------------------------
   // Internals
@@ -5300,16 +5475,24 @@ export {
   createCommunicator,
   createDefaultStepRegistry,
   createLauncher,
+  getBackendDescriptor,
   getLaunchModeHandler,
   globMatch,
   isAcpBackend,
+  isAcpOnlyBackend,
   isProcessAlive,
   metaFilePath,
+  openBackend,
   readInstanceMeta,
+  registerBackend,
+  registerCommunicator,
+  requireMode,
+  resolveAcpBackend,
   resolveBackend,
   resolvePermissions,
   resolvePermissionsWithMcp,
   scanInstances,
+  supportsMode,
   toAgentTemplate,
   updateInstanceMeta,
   validateBackendConfig,