@actant/core 0.1.2 → 0.2.0

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, PermissionsConfig, SourceConfig, PackageManifest, PresetDefinition, GitHubSourceConfig, LocalSourceConfig, SourceEntry } from '@actant/shared';
+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 } from '@actant/shared';
 import { z } from 'zod/v4';
 import { EventEmitter } from 'node:events';
 import { Writable, Readable } from 'node:stream';
@@ -531,8 +531,10 @@ declare const DomainContextSchema: z.ZodObject<{
 declare const AgentBackendSchema: z.ZodObject<{
     type: z.ZodEnum<{
         cursor: "cursor";
+        "cursor-agent": "cursor-agent";
         "claude-code": "claude-code";
         custom: "custom";
+        pi: "pi";
     }>;
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
@@ -541,7 +543,14 @@ declare const ModelProviderSchema: z.ZodObject<{
         custom: "custom";
         anthropic: "anthropic";
         openai: "openai";
+        "openai-compatible": "openai-compatible";
     }>;
+    protocol: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        http: "http";
+        websocket: "websocket";
+        grpc: "grpc";
+    }>>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 declare const InitializerStepSchema: z.ZodObject<{
@@ -640,8 +649,10 @@ declare const AgentTemplateSchema: z.ZodObject<{
     backend: z.ZodObject<{
         type: z.ZodEnum<{
             cursor: "cursor";
+            "cursor-agent": "cursor-agent";
             "claude-code": "claude-code";
             custom: "custom";
+            pi: "pi";
         }>;
         config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>;
@@ -650,7 +661,14 @@ declare const AgentTemplateSchema: z.ZodObject<{
             custom: "custom";
             anthropic: "anthropic";
             openai: "openai";
+            "openai-compatible": "openai-compatible";
         }>;
+        protocol: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            http: "http";
+            websocket: "websocket";
+            grpc: "grpc";
+        }>>>;
+        baseUrl: z.ZodOptional<z.ZodString>;
         config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>;
     domainContext: z.ZodObject<{
@@ -946,6 +964,7 @@ declare class AgentInitializer {
     private readonly builder;
     private readonly pipeline?;
     constructor(templateRegistry: TemplateRegistry, instancesBaseDir: string, options?: InitializerOptions | undefined);
+    get workspaceBuilder(): WorkspaceBuilder;
     /**
      * Create a new Agent Instance.
      * 1. Resolve template from registry
@@ -1125,8 +1144,10 @@ declare const AgentInstanceMetaSchema: z.ZodObject<{
     templateVersion: z.ZodString;
     backendType: z.ZodDefault<z.ZodEnum<{
         cursor: "cursor";
+        "cursor-agent": "cursor-agent";
         "claude-code": "claude-code";
         custom: "custom";
+        pi: "pi";
     }>>;
     backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     status: z.ZodEnum<{
@@ -1405,10 +1426,12 @@ declare class AgentManager {
         created: boolean;
     }>;
     /**
-     * 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
      */
     startAgent(name: string): Promise<void>;
     /**
@@ -1431,6 +1454,15 @@ declare class AgentManager {
      * If the agent doesn't exist but templateName is provided, auto-creates it.
      */
     resolveAgent(name: string, templateName?: string, overrides?: Partial<InstanceOverrides>): Promise<ResolveResult>;
+    /**
+     * 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
+     */
+    openAgent(name: string): Promise<{
+        command: string;
+        args: string[];
+    }>;
     /**
      * Register an externally-spawned process with the manager.
      * Sets processOwnership to "external" and registers ProcessWatcher monitoring.
@@ -1454,9 +1486,10 @@ declare class AgentManager {
     runPrompt(name: string, prompt: string, options?: RunPromptOptions): Promise<PromptResult>;
     /**
      * 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: string, prompt: string, options?: RunPromptOptions): AsyncIterable<StreamChunk>;
+    private streamFromAcp;
     /**
      * Send a message to a running agent via its ACP session.
      * Unlike runPrompt, this requires the agent to be started with ACP.
@@ -1603,13 +1636,51 @@ interface ResolvedBackend {
     command: string;
     args: string[];
 }
-/** Whether a backend type uses the ACP stdio protocol for communication. */
+/**
+ * Whether a backend type supports the ACP protocol for Actant-managed control.
+ * Replaces the old hardcoded `isAcpBackend()`.
+ */
 declare function isAcpBackend(backendType: AgentBackendType): boolean;
 /**
- * Resolve the executable command and arguments for a given backend type.
- * Supports explicit override via `backendConfig.executablePath` and `backendConfig.args`.
+ * 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.
+ */
+declare function resolveAcpBackend(backendType: AgentBackendType, workspaceDir: string, backendConfig?: Record<string, unknown>): ResolvedBackend;
+
+/**
+ * Register a backend descriptor.
+ * Call at startup for built-in backends and from external packages (e.g. @actant/pi).
+ */
+declare function registerBackend(descriptor: BackendDescriptor): void;
+/**
+ * Retrieve the descriptor for a backend type.
+ * @throws if the type has not been registered.
+ */
+declare function getBackendDescriptor(type: AgentBackendType): BackendDescriptor;
+/** Check whether a backend supports a specific open mode. */
+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;
 
 /**
  * Check whether a process with the given PID is still alive.
@@ -1679,7 +1750,14 @@ declare class CursorCommunicator implements AgentCommunicator {
     streamPrompt(_workspaceDir: string, _prompt: string, _options?: RunPromptOptions): AsyncIterable<StreamChunk>;
 }
 
-declare function createCommunicator(backendType: AgentBackendType): AgentCommunicator;
+/**
+ * Register a communicator factory for a backend type.
+ * External packages (e.g. @actant/pi) call this at startup.
+ * The factory receives the template's `backend.config` so it can extract
+ * provider-specific settings (provider, model, apiKey, etc.).
+ */
+declare function registerCommunicator(backendType: AgentBackendType, factory: (backendConfig?: Record<string, unknown>) => AgentCommunicator): void;
+declare function createCommunicator(backendType: AgentBackendType, backendConfig?: Record<string, unknown>): AgentCommunicator;
 
 declare function resolvePermissions(input: PermissionsInput | undefined): PermissionsConfig;
 declare function resolvePermissionsWithMcp(input: PermissionsInput | undefined, mcpServerNames: string[]): PermissionsConfig;
@@ -1925,6 +2003,10 @@ interface SourceManagerDeps {
  * Manages component sources (GitHub repos, local dirs, etc.).
  * Syncs remote components into the domain managers with `package@name` namespacing.
  */
+interface SourceManagerOptions {
+    /** Skip auto-registration of the default actant-hub source (useful for tests). */
+    skipDefaultSource?: boolean;
+}
 declare class SourceManager {
     private readonly sources;
     private readonly presets;
@@ -1932,7 +2014,8 @@ declare class SourceManager {
     private readonly homeDir;
     private readonly sourcesFilePath;
     private readonly cacheDir;
-    constructor(homeDir: string, managers: SourceManagerDeps);
+    private readonly skipDefaultSource;
+    constructor(homeDir: string, managers: SourceManagerDeps, options?: SourceManagerOptions);
     addSource(name: string, config: SourceConfig): Promise<FetchResult>;
     syncSource(name: string): Promise<FetchResult>;
     syncSourceWithReport(name: string): Promise<{
@@ -1955,6 +2038,11 @@ declare class SourceManager {
      */
     applyPreset(qualifiedName: string, template: AgentTemplate): AgentTemplate;
     initialize(): Promise<void>;
+    /**
+     * Registers the official actant-hub as the default source if not already present.
+     * Fails silently when offline or the repo is unreachable.
+     */
+    private ensureDefaultSource;
     private createSource;
     private injectComponents;
     private removeNamespacedComponents;
@@ -1965,4 +2053,4 @@ declare class SourceManager {
     private buildSyncReport;
 }
 
-export { AgentBackendSchema, type AgentCommunicator, AgentInitializer, AgentInstanceMetaSchema, type AgentLauncher, AgentManager, type AgentProcess, AgentStatusSchema, type AgentTask, type AgentTemplateInput, type AgentTemplateOutput, AgentTemplateSchema, type AuditEntry, type BackendBuilder, BaseComponentManager, ClaudeCodeBuilder, ClaudeCodeCommunicator, type CommunicatorFactory, 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, 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 StepContext, StepRegistry, type StepResult, type StepValidationResult, type StreamChunk, type TaskCallback, TaskDispatcher, type TaskPriority, TaskQueue, type TaskStatus, TemplateFileWatcher, type TemplateFileWatcherOptions, TemplateLoader, TemplateRegistry, type ToolCallInfo, type VerifyResult, WorkflowManager, type WorkspaceBuildResult, WorkspaceBuilder, createCommunicator, createDefaultStepRegistry, createLauncher, getLaunchModeHandler, globMatch, isAcpBackend, isProcessAlive, metaFilePath, readInstanceMeta, resolveBackend, resolvePermissions, resolvePermissionsWithMcp, scanInstances, toAgentTemplate, updateInstanceMeta, validateBackendConfig, validateDomainContextConfig, validatePermissionsConfig, validateProviderConfig, validateScheduleConfig, validateTemplate, writeInstanceMeta };
+export { AgentBackendSchema, type AgentCommunicator, AgentInitializer, AgentInstanceMetaSchema, type AgentLauncher, AgentManager, type AgentProcess, AgentStatusSchema, type AgentTask, type AgentTemplateInput, type AgentTemplateOutput, AgentTemplateSchema, type AuditEntry, type BackendBuilder, BaseComponentManager, ClaudeCodeBuilder, ClaudeCodeCommunicator, type CommunicatorFactory, 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, 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 StepContext, StepRegistry, type StepResult, type StepValidationResult, type StreamChunk, type TaskCallback, TaskDispatcher, type TaskPriority, TaskQueue, type TaskStatus, TemplateFileWatcher, type TemplateFileWatcherOptions, TemplateLoader, TemplateRegistry, type ToolCallInfo, type VerifyResult, WorkflowManager, type WorkspaceBuildResult, WorkspaceBuilder, createCommunicator, createDefaultStepRegistry, createLauncher, getBackendDescriptor, getLaunchModeHandler, globMatch, isAcpBackend, isAcpOnlyBackend, isProcessAlive, metaFilePath, openBackend, readInstanceMeta, registerBackend, registerCommunicator, requireMode, resolveAcpBackend, resolveBackend, resolvePermissions, resolvePermissionsWithMcp, scanInstances, supportsMode, toAgentTemplate, updateInstanceMeta, validateBackendConfig, validateDomainContextConfig, validatePermissionsConfig, validateProviderConfig, validateScheduleConfig, validateTemplate, writeInstanceMeta };