@actant/core 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentBackendType, SkillDefinition, PromptDefinition, McpServerDefinition, PluginDefinition, WorkflowDefinition, PermissionsInput, Logger, ConfigValidationResult, DomainContextConfig, AgentBackendConfig, ModelProviderConfig, AgentTemplate, AgentInstanceMeta, LaunchMode, WorkspacePolicy, WorkDirConflict, InitializerStep, AgentStatus, ResolveResult, DetachResult, BackendDescriptor, AgentOpenMode, PermissionsConfig, SourceConfig, PackageManifest, PresetDefinition, GitHubSourceConfig, LocalSourceConfig, SourceEntry, ModelProviderDescriptor } from '@actant/shared';
+import { AgentBackendType, SkillDefinition, PromptDefinition, McpServerDefinition, PluginDefinition, WorkflowDefinition, PermissionsInput, Logger, ConfigValidationResult, DomainContextConfig, AgentBackendConfig, ModelProviderConfig, AgentTemplate, AgentInstanceMeta, LaunchMode, WorkspacePolicy, WorkDirConflict, InitializerStep, OpenSpawnOptions, AgentStatus, ResolveResult, DetachResult, BackendDefinition, AgentOpenMode, PlatformCommand, BackendInstallMethod, BackendDescriptor, PermissionsConfig, SourceConfig, PackageManifest, PresetDefinition, GitHubSourceConfig, LocalSourceConfig, SourceEntry, ModelProviderDescriptor } from '@actant/shared';
 import { z } from 'zod/v4';
 import { EventEmitter } from 'node:events';
 import { Writable, Readable } from 'node:stream';
@@ -1158,13 +1158,7 @@ declare const AgentInstanceMetaSchema: z.ZodObject<{
     name: z.ZodString;
     templateName: z.ZodString;
     templateVersion: z.ZodString;
-    backendType: z.ZodDefault<z.ZodEnum<{
-        cursor: "cursor";
-        "cursor-agent": "cursor-agent";
-        "claude-code": "claude-code";
-        custom: "custom";
-        pi: "pi";
-    }>>;
+    backendType: z.ZodDefault<z.ZodString>;
     backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     providerConfig: z.ZodOptional<z.ZodObject<{
         type: z.ZodString;
@@ -1305,6 +1299,46 @@ interface AgentLauncher {
     terminate(process: AgentProcess): Promise<void>;
 }
 
+interface ResolvedBackend {
+    command: string;
+    args: string[];
+    /** npm package providing the binary (for auto-resolution when not on PATH). */
+    resolvePackage?: string;
+    /** Working directory for the spawned process. */
+    cwd?: string;
+    /** Declarative spawn options for `open` mode (from BackendDescriptor). */
+    openSpawnOptions?: OpenSpawnOptions;
+}
+/**
+ * Whether a backend type supports the ACP protocol for Actant-managed control.
+ * Replaces the old hardcoded `isAcpBackend()`.
+ */
+declare function isAcpBackend(backendType: AgentBackendType): boolean;
+/**
+ * Whether a backend's ACP connection owns the process lifecycle.
+ * When true, ProcessLauncher.launch() is skipped — only AcpConnectionManager spawns the process.
+ */
+declare function isAcpOnlyBackend(backendType: AgentBackendType): boolean;
+/**
+ * Resolve the executable command and arguments for spawning a backend (resolve mode).
+ * @throws if the backend does not support "resolve" mode.
+ */
+declare function resolveBackend(backendType: AgentBackendType, workspaceDir: string, backendConfig?: Record<string, unknown>): ResolvedBackend;
+/**
+ * Resolve the open command for directly launching a backend's native TUI/UI.
+ * `openWorkspaceDir` is consumed here to build `args`/`cwd`; the returned
+ * `openSpawnOptions` maps 1:1 to `child_process.SpawnOptions` so the CLI
+ * can spread it as-is with zero branching.
+ */
+declare function openBackend(backendType: AgentBackendType, workspaceDir: string): ResolvedBackend;
+/**
+ * Resolve the ACP spawn command for a backend.
+ * For ACP backends, this returns the command used by AcpConnectionManager to spawn the agent process.
+ * Checks acpCommand first, then falls back to resolveCommand.
+ * @throws if the backend does not support "acp" mode.
+ */
+declare function resolveAcpBackend(backendType: AgentBackendType, workspaceDir: string, backendConfig?: Record<string, unknown>): ResolvedBackend;
+
 interface RestartPolicy {
     /** Maximum number of restarts before giving up. Default: 5 */
     maxRestarts: number;
@@ -1392,6 +1426,7 @@ interface AcpConnectionManagerLike {
         command: string;
         args: string[];
         cwd: string;
+        resolvePackage?: string;
         connectionOptions?: {
             autoApprove?: boolean;
             env?: Record<string, string>;
@@ -1485,10 +1520,7 @@ declare class AgentManager {
      * Requires the backend to support "open" mode.
      * @throws if backend does not support "open" mode
      */
-    openAgent(name: string): Promise<{
-        command: string;
-        args: string[];
-    }>;
+    openAgent(name: string): Promise<ResolvedBackend>;
     /**
      * Register an externally-spawned process with the manager.
      * Sets processOwnership to "external" and registers ProcessWatcher monitoring.
@@ -1658,55 +1690,62 @@ interface LauncherConfig {
  */
 declare function createLauncher(config?: Partial<LauncherConfig>): AgentLauncher;
 
-interface ResolvedBackend {
+type AcpResolverFn = (workspaceDir: string, backendConfig?: Record<string, unknown>) => {
     command: string;
     args: string[];
-}
-/**
- * Whether a backend type supports the ACP protocol for Actant-managed control.
- * Replaces the old hardcoded `isAcpBackend()`.
- */
-declare function isAcpBackend(backendType: AgentBackendType): boolean;
-/**
- * Whether a backend's ACP connection owns the process lifecycle.
- * When true, ProcessLauncher.launch() is skipped — only AcpConnectionManager spawns the process.
- */
-declare function isAcpOnlyBackend(backendType: AgentBackendType): boolean;
-/**
- * Resolve the executable command and arguments for spawning a backend (resolve mode).
- * @throws if the backend does not support "resolve" mode.
- */
-declare function resolveBackend(backendType: AgentBackendType, workspaceDir: string, backendConfig?: Record<string, unknown>): ResolvedBackend;
-/**
- * Resolve the open command for directly launching a backend's native TUI/UI.
- * @throws if the backend does not support "open" mode.
- */
-declare function openBackend(backendType: AgentBackendType, workspaceDir: string): ResolvedBackend;
+};
 /**
- * Resolve the ACP spawn command for a backend.
- * For ACP backends, this returns the command used by AcpConnectionManager to spawn the agent process.
- * Checks acpCommand first, then falls back to resolveCommand.
- * @throws if the backend does not support "acp" mode.
+ * Manages backend definitions as VersionedComponents.
+ *
+ * Pure-data definitions are stored in the component registry (JSON-serializable,
+ * loadable from `~/.actant/configs/backends/`). Non-serializable behavioral
+ * extensions (acpResolver) are stored in a separate Map keyed by backend name.
  */
-declare function resolveAcpBackend(backendType: AgentBackendType, workspaceDir: string, backendConfig?: Record<string, unknown>): ResolvedBackend;
+declare class BackendManager extends BaseComponentManager<BackendDefinition> {
+    protected readonly componentType = "Backend";
+    private readonly acpResolvers;
+    constructor();
+    registerAcpResolver(backendName: string, resolver: AcpResolverFn): void;
+    getAcpResolver(backendName: string): AcpResolverFn | undefined;
+    supportsMode(backendName: string, mode: AgentOpenMode): boolean;
+    requireMode(backendName: string, mode: AgentOpenMode): void;
+    getPlatformCommand(cmd: PlatformCommand): string;
+    /**
+     * 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).
+     */
+    checkAvailability(backendName: string): Promise<BackendAvailability>;
+    /**
+     * Get platform-appropriate install methods for a backend.
+     * Filters by `platforms` field; returns all methods if no platform restriction.
+     */
+    getInstallMethods(backendName: string): BackendInstallMethod[];
+    validate(data: unknown, _source: string): ConfigValidationResult<BackendDefinition>;
+}
+interface BackendAvailability {
+    available: boolean;
+    version?: string;
+    error?: string;
+}
 
+/** Access the singleton BackendManager for advanced operations (CRUD, persistence, directory loading). */
+declare function getBackendManager(): BackendManager;
 /**
- * Register a backend descriptor.
- * Call at startup for built-in backends and from external packages (e.g. @actant/pi).
+ * Register a backend descriptor (legacy API).
+ * Converts `BackendDescriptor.type` → `BackendDefinition.name` and
+ * extracts `acpResolver` into the behavioral registry.
  */
 declare function registerBackend(descriptor: BackendDescriptor): void;
 /**
- * Retrieve the descriptor for a backend type.
- * @throws if the type has not been registered.
+ * Register a BackendDefinition directly (new API).
+ * For behavioral extensions, use `getBackendManager().registerAcpResolver()`.
  */
-declare function getBackendDescriptor(type: AgentBackendType): BackendDescriptor;
-/** Check whether a backend supports a specific open mode. */
+declare function registerBackendDefinition(definition: BackendDefinition): void;
+declare function getBackendDescriptor(type: AgentBackendType): BackendDefinition;
 declare function supportsMode(type: AgentBackendType, mode: AgentOpenMode): boolean;
-/**
- * Assert that a backend supports a mode, throwing a descriptive error if not.
- * Used as a guard in manager methods before executing mode-specific logic.
- */
 declare function requireMode(type: AgentBackendType, mode: AgentOpenMode): void;
+declare function getInstallHint(type: AgentBackendType): string | undefined;
 
 /**
  * Check whether a process with the given PID is still alive.
@@ -1952,6 +1991,7 @@ interface FetchResult {
     prompts: PromptDefinition[];
     mcpServers: McpServerDefinition[];
     workflows: WorkflowDefinition[];
+    backends: BackendDefinition[];
     presets: PresetDefinition[];
     templates: AgentTemplate[];
 }
@@ -2027,6 +2067,7 @@ interface SourceManagerDeps {
     promptManager: BaseComponentManager<PromptDefinition>;
     mcpConfigManager: BaseComponentManager<McpServerDefinition>;
     workflowManager: BaseComponentManager<WorkflowDefinition>;
+    backendManager?: BaseComponentManager<BackendDefinition>;
     templateRegistry?: TemplateRegistry;
 }
 /**
@@ -2164,4 +2205,4 @@ declare const BUILTIN_PROVIDERS: readonly ModelProviderDescriptor[];
 /** Register all built-in providers into the singleton registry. */
 declare function registerBuiltinProviders(): void;
 
-export { AgentBackendSchema, type AgentCommunicator, AgentInitializer, AgentInstanceMetaSchema, type AgentLauncher, AgentManager, type AgentProcess, AgentStatusSchema, type AgentTask, type AgentTemplateInput, type AgentTemplateOutput, AgentTemplateSchema, type AuditEntry, BUILTIN_PROVIDERS, type BackendBuilder, BaseComponentManager, ClaudeCodeBuilder, ClaudeCodeCommunicator, type CommunicatorFactory, type CompatMode, ComponentOriginSchema, type ComponentSource, type ComponentTypeHandler, ContextMaterializer, type CreateSessionOptions, type CronConfig, CronConfigSchema, CronInput, CursorBuilder, CursorCommunicator, CustomBuilder, type CustomBuilderConfig, DEFAULT_RESTART_POLICY, DEFAULT_SOURCE_CONFIG, DEFAULT_SOURCE_NAME, DomainContextSchema, type DomainManagers$1 as DomainManagers, EmployeeScheduler, ExecStep, ExecutionLog, type ExecutionRecord, type FetchResult, FileCopyStep, GitCloneStep, GitHubSource, type HeartbeatConfig, HeartbeatConfigSchema, HeartbeatInput, type HookConfig, HookConfigSchema, HookInput, InitializationPipeline, type InitializerOptions, InitializerSchema, InitializerStepExecutor, InitializerStepSchema, InputRouter, type InputSource, type InstanceOverrides, InstanceRegistry, type InstanceRegistryAdapter, type InstanceRegistryData, type InstanceRegistryEntry, type LaunchModeHandler, LaunchModeSchema, type LauncherConfig, type LauncherMode, LocalSource, type ManagerOptions, McpConfigManager, McpServerRefSchema, MkdirStep, MockLauncher, ModelProviderRegistry, ModelProviderSchema, type NamedComponent, NpmInstallStep, type PermissionAuditEvent, PermissionAuditLogger, PermissionPolicyEnforcer, PermissionPresetSchema, PermissionsInputSchema, PermissionsObjectSchema, type PipelineOptions, type PipelineResult, PluginManager, type PolicyAction, type PolicyDecision, type ProcessExitAction, type ProcessExitHandler, type ProcessExitInfo, ProcessLauncher, type ProcessLauncherOptions, ProcessLogWriter, type ProcessLogWriterOptions, ProcessWatcher, type ProcessWatcherOptions, type PromptAgentFn, PromptManager, type PromptResult, type RecoveryAction, type RegistryOptions, type ResolvedBackend, type RestartDecision, type RestartPolicy, RestartTracker, type RunPromptOptions, type ScheduleConfig, type ScheduleConfigInput, ScheduleConfigSchema, type SessionLease, SessionRegistry, type SessionRegistryOptions, type SessionState, SkillManager, SourceManager, type SourceManagerDeps, type SourceManagerOptions, type SourceValidationIssue, type SourceValidationReport, SourceValidator, type StepContext, StepRegistry, type StepResult, type StepValidationResult, type StreamChunk, type TaskCallback, TaskDispatcher, type TaskPriority, TaskQueue, type TaskStatus, TemplateFileWatcher, type TemplateFileWatcherOptions, TemplateLoader, TemplateRegistry, type ToolCallInfo, type ValidateOptions, type VerifyResult, WorkflowManager, type WorkspaceBuildResult, WorkspaceBuilder, createCommunicator, createDefaultStepRegistry, createLauncher, getBackendDescriptor, getLaunchModeHandler, globMatch, isAcpBackend, isAcpOnlyBackend, isProcessAlive, metaFilePath, modelProviderRegistry, openBackend, readInstanceMeta, registerBackend, registerBuiltinProviders, registerCommunicator, requireMode, resolveAcpBackend, resolveBackend, resolvePermissions, resolvePermissionsWithMcp, scanInstances, supportsMode, toAgentTemplate, updateInstanceMeta, validateBackendConfig, validateDomainContextConfig, validatePermissionsConfig, validateProviderConfig, validateScheduleConfig, validateTemplate, writeInstanceMeta };
+export { type AcpResolverFn, AgentBackendSchema, type AgentCommunicator, AgentInitializer, AgentInstanceMetaSchema, type AgentLauncher, AgentManager, type AgentProcess, AgentStatusSchema, type AgentTask, type AgentTemplateInput, type AgentTemplateOutput, AgentTemplateSchema, type AuditEntry, BUILTIN_PROVIDERS, type BackendAvailability, type BackendBuilder, BackendManager, BaseComponentManager, ClaudeCodeBuilder, ClaudeCodeCommunicator, type CommunicatorFactory, type CompatMode, ComponentOriginSchema, type ComponentSource, type ComponentTypeHandler, ContextMaterializer, type CreateSessionOptions, type CronConfig, CronConfigSchema, CronInput, CursorBuilder, CursorCommunicator, CustomBuilder, type CustomBuilderConfig, DEFAULT_RESTART_POLICY, DEFAULT_SOURCE_CONFIG, DEFAULT_SOURCE_NAME, DomainContextSchema, type DomainManagers$1 as DomainManagers, EmployeeScheduler, ExecStep, ExecutionLog, type ExecutionRecord, type FetchResult, FileCopyStep, GitCloneStep, GitHubSource, type HeartbeatConfig, HeartbeatConfigSchema, HeartbeatInput, type HookConfig, HookConfigSchema, HookInput, InitializationPipeline, type InitializerOptions, InitializerSchema, InitializerStepExecutor, InitializerStepSchema, InputRouter, type InputSource, type InstanceOverrides, InstanceRegistry, type InstanceRegistryAdapter, type InstanceRegistryData, type InstanceRegistryEntry, type LaunchModeHandler, LaunchModeSchema, type LauncherConfig, type LauncherMode, LocalSource, type ManagerOptions, McpConfigManager, McpServerRefSchema, MkdirStep, MockLauncher, ModelProviderRegistry, ModelProviderSchema, type NamedComponent, NpmInstallStep, type PermissionAuditEvent, PermissionAuditLogger, PermissionPolicyEnforcer, PermissionPresetSchema, PermissionsInputSchema, PermissionsObjectSchema, type PipelineOptions, type PipelineResult, PluginManager, type PolicyAction, type PolicyDecision, type ProcessExitAction, type ProcessExitHandler, type ProcessExitInfo, ProcessLauncher, type ProcessLauncherOptions, ProcessLogWriter, type ProcessLogWriterOptions, ProcessWatcher, type ProcessWatcherOptions, type PromptAgentFn, PromptManager, type PromptResult, type RecoveryAction, type RegistryOptions, type ResolvedBackend, type RestartDecision, type RestartPolicy, RestartTracker, type RunPromptOptions, type ScheduleConfig, type ScheduleConfigInput, ScheduleConfigSchema, type SessionLease, SessionRegistry, type SessionRegistryOptions, type SessionState, SkillManager, SourceManager, type SourceManagerDeps, type SourceManagerOptions, type SourceValidationIssue, type SourceValidationReport, SourceValidator, type StepContext, StepRegistry, type StepResult, type StepValidationResult, type StreamChunk, type TaskCallback, TaskDispatcher, type TaskPriority, TaskQueue, type TaskStatus, TemplateFileWatcher, type TemplateFileWatcherOptions, TemplateLoader, TemplateRegistry, type ToolCallInfo, type ValidateOptions, type VerifyResult, WorkflowManager, type WorkspaceBuildResult, WorkspaceBuilder, createCommunicator, createDefaultStepRegistry, createLauncher, getBackendDescriptor, getBackendManager, getInstallHint, getLaunchModeHandler, globMatch, isAcpBackend, isAcpOnlyBackend, isProcessAlive, metaFilePath, modelProviderRegistry, openBackend, readInstanceMeta, registerBackend, registerBackendDefinition, registerBuiltinProviders, registerCommunicator, requireMode, resolveAcpBackend, resolveBackend, resolvePermissions, resolvePermissionsWithMcp, scanInstances, supportsMode, toAgentTemplate, updateInstanceMeta, validateBackendConfig, validateDomainContextConfig, validatePermissionsConfig, validateProviderConfig, validateScheduleConfig, validateTemplate, writeInstanceMeta };