@actant/core 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,1968 @@
+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 { z } from 'zod/v4';
+import { EventEmitter } from 'node:events';
+import { Writable, Readable } from 'node:stream';
+
+interface VerifyResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+interface BackendBuilder {
+    readonly backendType: AgentBackendType;
+    /** Create the directory scaffold for the workspace */
+    scaffold(workspaceDir: string): Promise<void>;
+    /** Write skill content files */
+    materializeSkills(workspaceDir: string, skills: SkillDefinition[]): Promise<void>;
+    /** Write prompt content files */
+    materializePrompts(workspaceDir: string, prompts: PromptDefinition[]): Promise<void>;
+    /** Write MCP server configuration */
+    materializeMcpConfig(workspaceDir: string, servers: McpServerDefinition[]): Promise<void>;
+    /** Write plugin configuration */
+    materializePlugins(workspaceDir: string, plugins: PluginDefinition[]): Promise<void>;
+    /** Write workflow content */
+    materializeWorkflow(workspaceDir: string, workflow: WorkflowDefinition): Promise<void>;
+    /** Inject tool permissions for autonomous operation */
+    injectPermissions(workspaceDir: string, servers: McpServerDefinition[], permissions?: PermissionsInput): Promise<void>;
+    /** Verify the workspace integrity after build */
+    verify(workspaceDir: string): Promise<VerifyResult>;
+}
+
+interface NamedComponent {
+    name: string;
+}
+/**
+ * Generic base class for Domain Context component managers.
+ * Provides CRUD, persist, import/export, search/filter, and load-from-directory.
+ */
+declare abstract class BaseComponentManager<T extends NamedComponent> {
+    protected readonly components: Map<string, T>;
+    protected readonly logger: Logger;
+    protected abstract readonly componentType: string;
+    protected persistDir?: string;
+    constructor(loggerName: string);
+    setPersistDir(dir: string): void;
+    register(component: T): void;
+    unregister(name: string): boolean;
+    get(name: string): T | undefined;
+    has(name: string): boolean;
+    /**
+     * Resolve a list of component names to their definitions.
+     * @throws {ComponentReferenceError} if any name is not found
+     */
+    resolve(names: string[]): T[];
+    list(): T[];
+    get size(): number;
+    clear(): void;
+    add(component: T, persist?: boolean): Promise<void>;
+    update(name: string, patch: Partial<T>, persist?: boolean): Promise<T>;
+    remove(name: string, persist?: boolean): Promise<boolean>;
+    importFromFile(filePath: string): Promise<T>;
+    exportToFile(name: string, filePath: string): Promise<void>;
+    search(query: string): T[];
+    filter(predicate: (c: T) => boolean): T[];
+    /**
+     * Resolve a content file reference (e.g. "content.md") to its file contents.
+     * Returns null if the ref is inline text (contains newline) or file not found.
+     */
+    protected resolveContentFile(dirPath: string, contentRef: string): Promise<string | null>;
+    /**
+     * Load component definitions from JSON files and directory-based components (manifest.json).
+     * Invalid files/directories are skipped with a warning.
+     * @-prefixed directories are scanned recursively as source namespaces.
+     */
+    loadFromDirectory(dirPath: string): Promise<number>;
+    /**
+     * Validate raw data against the component schema.
+     * Returns a structured ConfigValidationResult with errors and warnings.
+     */
+    abstract validate(data: unknown, source: string): ConfigValidationResult<T>;
+    /**
+     * Validate and unwrap — throws ConfigValidationError on failure.
+     * Used internally by CRUD and loading operations.
+     */
+    protected validateOrThrow(data: unknown, source: string): T;
+    protected writeComponent(component: T): Promise<void>;
+    protected deleteComponent(name: string): Promise<void>;
+}
+
+/**
+ * Encapsulates the handling of a single DomainContext component type.
+ * Each handler knows how to resolve names and materialize definitions.
+ */
+interface ComponentTypeHandler<TDef = unknown> {
+    /** The key in DomainContextConfig (e.g. "skills", "prompts") */
+    readonly contextKey: string;
+    /** Resolve name references to full definitions */
+    resolve(refs: unknown, manager?: BaseComponentManager<NamedComponent>): TDef[];
+    /** Materialize resolved definitions into the workspace */
+    materialize(workspaceDir: string, definitions: TDef[], backendType: AgentBackendType, backendBuilder: unknown): Promise<void>;
+}
+
+declare class CursorBuilder implements BackendBuilder {
+    readonly backendType: AgentBackendType;
+    scaffold(workspaceDir: string): Promise<void>;
+    materializeSkills(workspaceDir: string, skills: SkillDefinition[]): Promise<void>;
+    materializePrompts(workspaceDir: string, prompts: PromptDefinition[]): Promise<void>;
+    materializeMcpConfig(workspaceDir: string, servers: McpServerDefinition[]): Promise<void>;
+    materializePlugins(workspaceDir: string, plugins: PluginDefinition[]): Promise<void>;
+    materializeWorkflow(workspaceDir: string, workflow: WorkflowDefinition): Promise<void>;
+    injectPermissions(workspaceDir: string, servers: McpServerDefinition[], permissions?: PermissionsInput): Promise<void>;
+    verify(workspaceDir: string): Promise<VerifyResult>;
+}
+
+declare class ClaudeCodeBuilder implements BackendBuilder {
+    readonly backendType: "claude-code";
+    scaffold(workspaceDir: string): Promise<void>;
+    materializeSkills(workspaceDir: string, skills: SkillDefinition[]): Promise<void>;
+    materializePrompts(workspaceDir: string, prompts: PromptDefinition[]): Promise<void>;
+    materializeMcpConfig(workspaceDir: string, servers: McpServerDefinition[]): Promise<void>;
+    materializePlugins(workspaceDir: string, plugins: PluginDefinition[]): Promise<void>;
+    materializeWorkflow(workspaceDir: string, workflow: WorkflowDefinition): Promise<void>;
+    injectPermissions(workspaceDir: string, servers: McpServerDefinition[], permissions?: PermissionsInput): Promise<void>;
+    verify(workspaceDir: string): Promise<VerifyResult>;
+}
+
+interface CustomBuilderConfig {
+    configDir?: string;
+    skillsDir?: string;
+}
+declare class CustomBuilder extends CursorBuilder {
+    readonly backendType: AgentBackendType;
+}
+
+declare class SkillManager extends BaseComponentManager<SkillDefinition> {
+    protected readonly componentType = "Skill";
+    constructor();
+    /** Render all resolved skills into a single AGENTS.md content block. */
+    renderSkills(skills: SkillDefinition[]): string;
+    validate(data: unknown, _source: string): ConfigValidationResult<SkillDefinition>;
+}
+
+declare class PromptManager extends BaseComponentManager<PromptDefinition> {
+    protected readonly componentType = "Prompt";
+    constructor();
+    /**
+     * Render a prompt with variable interpolation.
+     * Replaces {{variableName}} placeholders with provided values.
+     */
+    renderPrompt(prompt: PromptDefinition, variables?: Record<string, string>): string;
+    /** Render multiple prompts into a single system.md content block. */
+    renderPrompts(prompts: PromptDefinition[], variables?: Record<string, string>): string;
+    validate(data: unknown, _source: string): ConfigValidationResult<PromptDefinition>;
+}
+
+declare class McpConfigManager extends BaseComponentManager<McpServerDefinition> {
+    protected readonly componentType = "McpServer";
+    constructor();
+    /**
+     * Render resolved MCP servers into the .cursor/mcp.json format.
+     * Returns the JSON object ready to be serialized.
+     */
+    renderMcpConfig(servers: McpServerDefinition[]): Record<string, unknown>;
+    validate(data: unknown, _source: string): ConfigValidationResult<McpServerDefinition>;
+}
+
+declare class WorkflowManager extends BaseComponentManager<WorkflowDefinition> {
+    protected readonly componentType = "Workflow";
+    constructor();
+    /** Get the workflow content ready to write to .trellis/workflow.md */
+    renderWorkflow(workflow: WorkflowDefinition): string;
+    validate(data: unknown, _source: string): ConfigValidationResult<WorkflowDefinition>;
+}
+
+declare class PluginManager extends BaseComponentManager<PluginDefinition> {
+    protected readonly componentType = "Plugin";
+    constructor();
+    /**
+     * Render plugins into a Claude Code plugins.json format.
+     * Only includes enabled plugins with npm type.
+     */
+    renderPluginsJson(plugins: PluginDefinition[]): string;
+    /**
+     * Render plugins as a Cursor extensions.json format.
+     */
+    renderExtensionsJson(plugins: PluginDefinition[]): string;
+    validate(data: unknown, _source: string): ConfigValidationResult<PluginDefinition>;
+}
+
+interface DomainManagers$1 {
+    skills?: SkillManager;
+    prompts?: PromptManager;
+    mcp?: McpConfigManager;
+    workflows?: WorkflowManager;
+    plugins?: PluginManager;
+}
+interface WorkspaceBuildResult {
+    verify: VerifyResult;
+    backendType: AgentBackendType;
+}
+declare class WorkspaceBuilder {
+    private readonly managers?;
+    private readonly builders;
+    private readonly handlers;
+    constructor(managers?: DomainManagers$1 | undefined);
+    /** Register a custom BackendBuilder (e.g. for "custom" backend type) */
+    registerBuilder(builder: BackendBuilder): void;
+    /** Register a component type handler for custom component types or extensions */
+    registerHandler(handler: ComponentTypeHandler): void;
+    private getManager;
+    /**
+     * Build workspace using the 6-step pipeline:
+     * 1. Resolve — select builder + resolve domain context names to definitions
+     * 2. Validate — check that required components exist
+     * 3. Scaffold — create directory structure
+     * 4. Materialize — write component files
+     * 5. Inject — set up permissions
+     * 6. Verify — check workspace integrity
+     */
+    build(workspaceDir: string, domainContext: DomainContextConfig, backendType?: AgentBackendType, permissions?: PermissionsInput): Promise<WorkspaceBuildResult>;
+}
+
+type TaskPriority = "low" | "normal" | "high" | "critical";
+type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+interface AgentTask {
+    id: string;
+    agentName: string;
+    prompt: string;
+    priority: TaskPriority;
+    source: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface ExecutionRecord {
+    taskId: string;
+    agentName: string;
+    prompt: string;
+    source: string;
+    status: TaskStatus;
+    startedAt: string;
+    completedAt?: string;
+    durationMs?: number;
+    result?: string;
+    error?: string;
+}
+
+declare class TaskQueue {
+    private queues;
+    private processing;
+    /** Enqueue a task. Sorts by priority. */
+    enqueue(task: AgentTask): void;
+    /** Dequeue the highest-priority task for an agent. Returns undefined if empty or agent is processing. */
+    dequeue(agentName: string): AgentTask | undefined;
+    /** Mark an agent as currently processing (serial execution). */
+    markProcessing(agentName: string): void;
+    /** Mark an agent as done processing. */
+    markDone(agentName: string): void;
+    /** Check if an agent has queued tasks. */
+    hasTasks(agentName: string): boolean;
+    /** Check if an agent is currently processing a task. */
+    isProcessing(agentName: string): boolean;
+    /** Get the number of queued tasks for an agent. */
+    queueSize(agentName: string): number;
+    /** Get all queued tasks for an agent. */
+    peek(agentName: string): AgentTask[];
+    /** Clear all tasks for an agent. */
+    clear(agentName: string): void;
+    /** Clear all queues. */
+    clearAll(): void;
+}
+
+declare class ExecutionLog {
+    private records;
+    private persistDir?;
+    private maxInMemory;
+    setPersistDir(dir: string): void;
+    setMaxInMemory(max: number): void;
+    record(entry: ExecutionRecord): Promise<void>;
+    /** Get recent execution records, optionally filtered by agent. */
+    getRecords(agentName?: string, limit?: number): ExecutionRecord[];
+    /** Get the last execution record for an agent. */
+    getLastRecord(agentName: string): ExecutionRecord | undefined;
+    /** Count records by status for an agent. */
+    getStats(agentName?: string): Record<string, number>;
+    clear(): void;
+    private persistRecord;
+}
+
+interface PromptAgentFn {
+    (agentName: string, prompt: string): Promise<string>;
+}
+declare class TaskDispatcher {
+    private readonly queue;
+    private readonly log;
+    private readonly promptAgent;
+    private readonly pollIntervalMs;
+    private running;
+    private dispatchInterval;
+    private agentNames;
+    constructor(queue: TaskQueue, log: ExecutionLog, promptAgent: PromptAgentFn, pollIntervalMs?: number);
+    /** Register an agent name to be dispatched. */
+    registerAgent(agentName: string): void;
+    /** Unregister an agent. */
+    unregisterAgent(agentName: string): void;
+    /** Start the dispatch loop. */
+    start(): void;
+    /** Stop the dispatch loop. */
+    stop(): void;
+    /** Manual dispatch — process one tick immediately. */
+    tick(): Promise<void>;
+    private executeTask;
+    get isRunning(): boolean;
+}
+
+declare const HeartbeatConfigSchema: z.ZodObject<{
+    intervalMs: z.ZodNumber;
+    prompt: z.ZodString;
+    priority: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        normal: "normal";
+        high: "high";
+        critical: "critical";
+    }>>;
+}, z.core.$strip>;
+declare const CronConfigSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    prompt: z.ZodString;
+    timezone: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        normal: "normal";
+        high: "high";
+        critical: "critical";
+    }>>;
+}, z.core.$strip>;
+declare const HookConfigSchema: z.ZodObject<{
+    eventName: z.ZodString;
+    prompt: z.ZodString;
+    priority: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        normal: "normal";
+        high: "high";
+        critical: "critical";
+    }>>;
+}, z.core.$strip>;
+declare const ScheduleConfigSchema: z.ZodObject<{
+    heartbeat: z.ZodOptional<z.ZodObject<{
+        intervalMs: z.ZodNumber;
+        prompt: z.ZodString;
+        priority: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            high: "high";
+            critical: "critical";
+        }>>;
+    }, z.core.$strip>>;
+    cron: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        pattern: z.ZodString;
+        prompt: z.ZodString;
+        timezone: z.ZodOptional<z.ZodString>;
+        priority: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            high: "high";
+            critical: "critical";
+        }>>;
+    }, z.core.$strip>>>>;
+    hooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        eventName: z.ZodString;
+        prompt: z.ZodString;
+        priority: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            high: "high";
+            critical: "critical";
+        }>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+type ScheduleConfig = z.infer<typeof ScheduleConfigSchema>;
+type ScheduleConfigInput = z.input<typeof ScheduleConfigSchema>;
+
+declare class EmployeeScheduler {
+    private readonly agentName;
+    private readonly queue;
+    private readonly dispatcher;
+    private readonly log;
+    private readonly router;
+    private readonly eventBus;
+    private _running;
+    constructor(agentName: string, promptAgent: PromptAgentFn, config?: {
+        persistDir?: string;
+    });
+    /** Configure schedule from template config. */
+    configure(scheduleConfig: ScheduleConfigInput): void;
+    /** Start the scheduler — begins accepting and dispatching tasks. */
+    start(): void;
+    /** Stop the scheduler. */
+    stop(): void;
+    /** Manually dispatch a one-off task. */
+    dispatch(prompt: string, priority?: "low" | "normal" | "high" | "critical"): void;
+    /** Emit an event to trigger HookInput sources. */
+    emitEvent(eventName: string, payload?: unknown): void;
+    /** Get queued tasks. */
+    getTasks(): {
+        queued: number;
+        processing: boolean;
+        tasks: unknown[];
+    };
+    /** Get execution logs. */
+    getLogs(limit?: number): unknown[];
+    /** Get execution stats. */
+    getStats(): Record<string, number>;
+    /** Get input sources info. */
+    getSources(): {
+        id: string;
+        type: string;
+        active: boolean;
+    }[];
+    get running(): boolean;
+    get executionLog(): ExecutionLog;
+}
+
+type TaskCallback = (task: AgentTask) => void;
+interface InputSource {
+    readonly id: string;
+    readonly type: string;
+    /** Start the input source. Calls onTask when a task should be dispatched. */
+    start(agentName: string, onTask: TaskCallback): void;
+    /** Stop the input source. */
+    stop(): void;
+    /** Whether this source is currently active. */
+    readonly active: boolean;
+}
+
+interface HeartbeatConfig {
+    intervalMs: number;
+    prompt: string;
+    priority?: "low" | "normal" | "high" | "critical";
+}
+declare class HeartbeatInput implements InputSource {
+    private readonly config;
+    readonly id: string;
+    readonly type = "heartbeat";
+    private interval;
+    private _active;
+    constructor(config: HeartbeatConfig, id?: string);
+    start(agentName: string, onTask: TaskCallback): void;
+    stop(): void;
+    get active(): boolean;
+}
+
+interface CronConfig {
+    pattern: string;
+    prompt: string;
+    timezone?: string;
+    priority?: "low" | "normal" | "high" | "critical";
+}
+declare class CronInput implements InputSource {
+    private readonly config;
+    readonly id: string;
+    readonly type = "cron";
+    private job;
+    private _active;
+    constructor(config: CronConfig, id?: string);
+    start(agentName: string, onTask: TaskCallback): void;
+    stop(): void;
+    get active(): boolean;
+}
+
+interface HookConfig {
+    eventName: string;
+    prompt: string;
+    priority?: "low" | "normal" | "high" | "critical";
+}
+declare class HookInput implements InputSource {
+    private readonly config;
+    private readonly emitter;
+    readonly id: string;
+    readonly type = "hook";
+    private _active;
+    private handler;
+    constructor(config: HookConfig, emitter: EventEmitter, id?: string);
+    start(agentName: string, onTask: TaskCallback): void;
+    stop(): void;
+    get active(): boolean;
+}
+
+declare class InputRouter {
+    private readonly queue;
+    private sources;
+    private agentName?;
+    constructor(queue: TaskQueue);
+    /** Register an input source. */
+    register(source: InputSource): void;
+    /** Unregister an input source. */
+    unregister(sourceId: string): boolean;
+    /** Start all registered input sources. */
+    startAll(agentName: string): void;
+    /** Stop all registered input sources. */
+    stopAll(): void;
+    /** Get all registered source IDs. */
+    listSources(): {
+        id: string;
+        type: string;
+        active: boolean;
+    }[];
+    /** Get a specific source by ID. */
+    getSource(id: string): InputSource | undefined;
+    get sourceCount(): number;
+}
+
+declare const McpServerRefSchema: z.ZodObject<{
+    name: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    env: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+}, z.core.$strip>;
+declare const DomainContextSchema: z.ZodObject<{
+    skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    prompts: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    mcpServers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        env: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strip>>>>;
+    workflow: z.ZodOptional<z.ZodString>;
+    subAgents: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnknown>>>;
+}, z.core.$strip>;
+declare const AgentBackendSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        cursor: "cursor";
+        "claude-code": "claude-code";
+        custom: "custom";
+    }>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const ModelProviderSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        custom: "custom";
+        anthropic: "anthropic";
+        openai: "openai";
+    }>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const InitializerStepSchema: z.ZodObject<{
+    type: z.ZodString;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const InitializerSchema: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const PermissionsObjectSchema: z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    defaultMode: z.ZodOptional<z.ZodEnum<{
+        bypassPermissions: "bypassPermissions";
+        default: "default";
+        acceptEdits: "acceptEdits";
+        plan: "plan";
+        dontAsk: "dontAsk";
+    }>>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        autoAllowBashIfSandboxed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        network: z.ZodOptional<z.ZodObject<{
+            allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    additionalDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const PermissionPresetSchema: z.ZodEnum<{
+    permissive: "permissive";
+    standard: "standard";
+    restricted: "restricted";
+    readonly: "readonly";
+}>;
+/** Accepts either a preset string or a full permissions object. */
+declare const PermissionsInputSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    permissive: "permissive";
+    standard: "standard";
+    restricted: "restricted";
+    readonly: "readonly";
+}>, z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    defaultMode: z.ZodOptional<z.ZodEnum<{
+        bypassPermissions: "bypassPermissions";
+        default: "default";
+        acceptEdits: "acceptEdits";
+        plan: "plan";
+        dontAsk: "dontAsk";
+    }>>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        autoAllowBashIfSandboxed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        network: z.ZodOptional<z.ZodObject<{
+            allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    additionalDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>]>;
+declare const ComponentOriginSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        source: "source";
+        builtin: "builtin";
+        local: "local";
+    }>;
+    sourceName: z.ZodOptional<z.ZodString>;
+    syncHash: z.ZodOptional<z.ZodString>;
+    syncedAt: z.ZodOptional<z.ZodString>;
+    modified: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const AgentTemplateSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    $type: z.ZodOptional<z.ZodString>;
+    $version: z.ZodOptional<z.ZodNumber>;
+    origin: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            source: "source";
+            builtin: "builtin";
+            local: "local";
+        }>;
+        sourceName: z.ZodOptional<z.ZodString>;
+        syncHash: z.ZodOptional<z.ZodString>;
+        syncedAt: z.ZodOptional<z.ZodString>;
+        modified: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    backend: z.ZodObject<{
+        type: z.ZodEnum<{
+            cursor: "cursor";
+            "claude-code": "claude-code";
+            custom: "custom";
+        }>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    provider: z.ZodObject<{
+        type: z.ZodEnum<{
+            custom: "custom";
+            anthropic: "anthropic";
+            openai: "openai";
+        }>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    domainContext: z.ZodObject<{
+        skills: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        prompts: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        mcpServers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+            env: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        }, z.core.$strip>>>>;
+        workflow: z.ZodOptional<z.ZodString>;
+        subAgents: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnknown>>>;
+    }, z.core.$strip>;
+    permissions: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        permissive: "permissive";
+        standard: "standard";
+        restricted: "restricted";
+        readonly: "readonly";
+    }>, z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        defaultMode: z.ZodOptional<z.ZodEnum<{
+            bypassPermissions: "bypassPermissions";
+            default: "default";
+            acceptEdits: "acceptEdits";
+            plan: "plan";
+            dontAsk: "dontAsk";
+        }>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            autoAllowBashIfSandboxed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            network: z.ZodOptional<z.ZodObject<{
+                allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        additionalDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>]>>;
+    initializer: z.ZodOptional<z.ZodObject<{
+        steps: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        heartbeat: z.ZodOptional<z.ZodObject<{
+            intervalMs: z.ZodNumber;
+            prompt: z.ZodString;
+            priority: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                normal: "normal";
+                high: "high";
+                critical: "critical";
+            }>>;
+        }, z.core.$strip>>;
+        cron: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodString;
+            prompt: z.ZodString;
+            timezone: z.ZodOptional<z.ZodString>;
+            priority: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                normal: "normal";
+                high: "high";
+                critical: "critical";
+            }>>;
+        }, z.core.$strip>>>>;
+        hooks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            eventName: z.ZodString;
+            prompt: z.ZodString;
+            priority: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                normal: "normal";
+                high: "high";
+                critical: "critical";
+            }>>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+type AgentTemplateInput = z.input<typeof AgentTemplateSchema>;
+type AgentTemplateOutput = z.output<typeof AgentTemplateSchema>;
+
+/**
+ * Standalone config validators (#119).
+ * Each function validates a sub-config and returns a ConfigValidationResult
+ * with both schema errors and semantic warnings.
+ */
+
+declare function validateBackendConfig(data: unknown): ConfigValidationResult<AgentBackendConfig>;
+declare function validateProviderConfig(data: unknown): ConfigValidationResult<ModelProviderConfig>;
+declare function validatePermissionsConfig(data: unknown): ConfigValidationResult<PermissionsInput>;
+declare function validateScheduleConfig(data: unknown): ConfigValidationResult<ScheduleConfig>;
+declare function validateDomainContextConfig(data: unknown): ConfigValidationResult<DomainContextConfig>;
+/**
+ * Deep-validate an AgentTemplate: schema + cross-field semantic checks.
+ * Returns all errors and warnings.
+ */
+declare function validateTemplate(data: unknown): ConfigValidationResult<AgentTemplate>;
+
+declare class TemplateLoader {
+    /**
+     * Load and validate an Agent Template from a JSON file.
+     * @throws {ConfigNotFoundError} if file does not exist
+     * @throws {ConfigValidationError} if JSON is malformed or fails schema validation
+     */
+    loadFromFile(filePath: string): Promise<AgentTemplate>;
+    /**
+     * Parse and validate an Agent Template from a JSON string.
+     * @throws {ConfigValidationError} if JSON is malformed or fails schema validation
+     */
+    loadFromString(content: string, source?: string): Promise<AgentTemplate>;
+    /**
+     * Load all valid Agent Templates from a directory (non-recursive).
+     * Only `.json` files are considered; non-template files are skipped.
+     * @throws {ConfigNotFoundError} if directory does not exist
+     */
+    loadFromDirectory(dirPath: string): Promise<AgentTemplate[]>;
+    private parseAndValidate;
+}
+/**
+ * Map Zod's output (with defaults applied) to the shared AgentTemplate type.
+ * This ensures the return type satisfies the interface contract exactly.
+ */
+declare function toAgentTemplate(output: AgentTemplateOutput): AgentTemplate;
+
+interface RegistryOptions {
+    /** If true, re-registering the same name overwrites the existing entry. Default: false */
+    allowOverwrite?: boolean;
+}
+/**
+ * Template registry that extends BaseComponentManager (#119).
+ * Inherits CRUD, search/filter, import/export from the base class.
+ * Adds template-specific overrides: duplicate checking, TemplateLoader-based directory loading.
+ */
+declare class TemplateRegistry extends BaseComponentManager<AgentTemplate> {
+    protected readonly componentType = "template";
+    private readonly loader;
+    private readonly allowOverwrite;
+    constructor(options?: RegistryOptions);
+    /**
+     * Register a template. Throws if a template with the same name already exists
+     * (unless allowOverwrite is enabled).
+     */
+    register(template: AgentTemplate): void;
+    /**
+     * Get a template by name.
+     * @throws {TemplateNotFoundError} if not found
+     */
+    getOrThrow(name: string): AgentTemplate;
+    /**
+     * Load templates from a directory using TemplateLoader (JSON + Zod validation).
+     * Invalid files are skipped with a warning log.
+     */
+    loadFromDirectory(dirPath: string): Promise<number>;
+    /** @deprecated Use loadFromDirectory instead. */
+    loadBuiltins(configDir: string): Promise<number>;
+    /**
+     * Validate raw data as an AgentTemplate using the Zod schema.
+     * Returns structured ConfigValidationResult (#119).
+     */
+    validate(data: unknown, _source: string): ConfigValidationResult<AgentTemplate>;
+    persist(template: AgentTemplate): Promise<void>;
+}
+
+interface TemplateFileWatcherOptions {
+    debounceMs?: number;
+}
+/**
+ * Watches the templates directory for file changes and auto-reloads
+ * the TemplateRegistry. Handles create, modify, and delete events.
+ *
+ * Tracks file→templateName mapping so deletions can correctly unregister
+ * templates whose name differs from the filename.
+ */
+declare class TemplateFileWatcher {
+    private readonly templatesDir;
+    private readonly registry;
+    private watcher;
+    private readonly debounceMs;
+    private readonly loader;
+    private debounceTimers;
+    /** Maps relative filename → template name loaded from that file. */
+    private fileToName;
+    constructor(templatesDir: string, registry: TemplateRegistry, options?: TemplateFileWatcherOptions);
+    start(): void;
+    stop(): void;
+    get isWatching(): boolean;
+    private buildFileMap;
+    private handleChange;
+    private processChange;
+}
+
+interface StepContext {
+    workspaceDir: string;
+    instanceMeta: Partial<AgentInstanceMeta>;
+    template: AgentTemplate;
+    logger: {
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+        debug: (...args: unknown[]) => void;
+    };
+    /** Shared mutable state between steps. */
+    state: Map<string, unknown>;
+}
+interface StepResult {
+    success: boolean;
+    output?: Record<string, unknown>;
+    message?: string;
+}
+interface StepValidationIssue {
+    field: string;
+    message: string;
+}
+interface StepValidationResult {
+    valid: boolean;
+    issues: StepValidationIssue[];
+}
+interface PipelineOptions {
+    /** Per-step timeout in ms. Default: 60_000 (1 min). */
+    defaultStepTimeoutMs?: number;
+    /** Total pipeline timeout in ms. Default: 300_000 (5 min). */
+    totalTimeoutMs?: number;
+    /** Progress callback invoked before each step executes. */
+    onProgress?: (stepIndex: number, totalSteps: number, stepType: string) => void;
+}
+interface PipelineResult {
+    success: boolean;
+    stepsExecuted: number;
+    stepsTotal: number;
+    errors: PipelineStepError[];
+    outputs: Map<string, Record<string, unknown>>;
+}
+interface PipelineStepError {
+    stepIndex: number;
+    stepType: string;
+    error: Error;
+}
+
+/**
+ * Abstract base class for initializer step executors.
+ * Each step type (e.g. "git-clone", "exec") implements this interface.
+ */
+declare abstract class InitializerStepExecutor {
+    /** Unique identifier matching the `type` field in InitializerStep config. */
+    abstract readonly type: string;
+    /** Validate step-specific config before execution. */
+    abstract validate(config: unknown): StepValidationResult;
+    /** Execute the step within the given context. */
+    abstract execute(context: StepContext, config: unknown): Promise<StepResult>;
+    /** Optional rollback — called in reverse order when a later step fails. */
+    rollback?(context: StepContext, config: unknown, error: Error): Promise<void>;
+}
+
+/**
+ * Registry for initializer step executors.
+ * Supports registration of custom step types at runtime.
+ */
+declare class StepRegistry {
+    private readonly executors;
+    register(executor: InitializerStepExecutor): void;
+    get(type: string): InitializerStepExecutor | undefined;
+    getOrThrow(type: string): InitializerStepExecutor;
+    has(type: string): boolean;
+    listTypes(): string[];
+}
+
+interface InitializerOptions {
+    defaultLaunchMode?: LaunchMode;
+    domainManagers?: DomainManagers$1;
+    /** Step registry for InitializerConfig pipeline execution. When provided, template.initializer.steps will be executed during createInstance(). */
+    stepRegistry?: StepRegistry;
+}
+interface InstanceOverrides {
+    launchMode: LaunchMode;
+    workspacePolicy: WorkspacePolicy;
+    /** Absolute path for the agent workspace. When omitted, defaults to {instancesBaseDir}/{name}. */
+    workDir: string;
+    /** Behavior when workDir already exists. Default: "error". */
+    workDirConflict: WorkDirConflict;
+    /** Override template permissions at instance level. Completely replaces template.permissions. */
+    permissions: PermissionsInput;
+    metadata: Record<string, string>;
+}
+declare class AgentInitializer {
+    private readonly templateRegistry;
+    private readonly instancesBaseDir;
+    private readonly options?;
+    private readonly builder;
+    private readonly pipeline?;
+    constructor(templateRegistry: TemplateRegistry, instancesBaseDir: string, options?: InitializerOptions | undefined);
+    /**
+     * Create a new Agent Instance.
+     * 1. Resolve template from registry
+     * 2. Create workspace directory {instancesBaseDir}/{name}/
+     * 3. Materialize Domain Context files
+     * 4. Write .actant.json metadata
+     *
+     * @throws {TemplateNotFoundError} if template is not in registry
+     * @throws {ConfigValidationError} if name conflicts with existing directory
+     * @throws {WorkspaceInitError} if directory creation or file writing fails
+     */
+    createInstance(name: string, templateName: string, overrides?: Partial<InstanceOverrides>): Promise<AgentInstanceMeta>;
+    /**
+     * Find an existing instance or create a new one (idempotent).
+     * - Directory exists + valid .actant.json → return existing
+     * - Directory does not exist → create new instance
+     * - Directory exists but corrupted → throw InstanceCorruptedError
+     */
+    findOrCreateInstance(name: string, templateName: string, overrides?: Partial<InstanceOverrides>): Promise<{
+        meta: AgentInstanceMeta;
+        created: boolean;
+    }>;
+    /**
+     * Destroy an instance by removing its workspace directory.
+     * For symlinked instances (custom workDir): removes the symlink and `.actant.json`
+     * from the target, but preserves the rest of the user's directory.
+     * For normal instances: removes the entire workspace directory.
+     */
+    destroyInstance(name: string): Promise<void>;
+}
+
+/**
+ * Optional Domain managers for full component resolution.
+ * When provided, names are resolved to real definitions and rendered.
+ * When absent, placeholder content is generated.
+ */
+interface DomainManagers {
+    skills?: SkillManager;
+    prompts?: PromptManager;
+    mcp?: McpConfigManager;
+    workflows?: WorkflowManager;
+}
+/**
+ * Materializes Domain Context references into actual files in the instance workspace.
+ * Paths for IDE-specific config (MCP, etc.) depend on backendType (e.g. .cursor vs .claude).
+ *
+ * Materialization rules:
+ *   skills      → AGENTS.md
+ *   mcpServers  → {backendConfigDir}/mcp.json (e.g. .cursor/mcp.json or .claude/mcp.json)
+ *   workflow    → .trellis/workflow.md
+ *   prompts     → prompts/system.md
+ *   subAgents   → recorded in .actant.json (not materialized as files)
+ *
+ * @deprecated Use WorkspaceBuilder + BackendBuilder instead (Phase 3b).
+ * Kept for backward compatibility; will be removed in a future version.
+ */
+declare class ContextMaterializer {
+    private readonly managers?;
+    constructor(managers?: DomainManagers | undefined);
+    materialize(workspaceDir: string, domainContext: DomainContextConfig, backendType?: AgentBackendType): Promise<void>;
+    private materializeSkills;
+    /**
+     * MCP Servers → {configDir}/mcp.json (e.g. .cursor/mcp.json or .claude/mcp.json)
+     * Template provides inline McpServerRef configs; no name-based resolution needed.
+     */
+    private materializeMcpServers;
+    /**
+     * Claude Code settings.local.json — pre-approve tools so agents can operate autonomously.
+     * Includes both MCP tools (`mcp__<server>` prefix) and essential built-in tools.
+     */
+    private materializeClaudePermissions;
+    private materializeWorkflow;
+    private materializePrompts;
+}
+
+/**
+ * Executes an ordered list of initializer steps with:
+ * - Sequential execution (steps may depend on prior shared state)
+ * - Per-step and total pipeline timeout
+ * - Transactional rollback on failure (reverse order)
+ * - Progress reporting
+ */
+declare class InitializationPipeline {
+    private readonly registry;
+    private readonly stepTimeoutMs;
+    private readonly totalTimeoutMs;
+    private readonly onProgress?;
+    constructor(registry: StepRegistry, options?: PipelineOptions);
+    /**
+     * Validate all steps without executing them.
+     * Returns per-step validation results.
+     */
+    dryRun(steps: InitializerStep[]): StepValidationResult[];
+    /**
+     * Execute all steps sequentially. On failure, rollback executed steps in reverse order.
+     */
+    run(steps: InitializerStep[], context: StepContext): Promise<PipelineResult>;
+    private executeWithTimeout;
+    private rollback;
+}
+
+/**
+ * Creates directories within the workspace.
+ * Paths are relative to workspaceDir (absolute paths are rejected for safety).
+ */
+declare class MkdirStep extends InitializerStepExecutor {
+    readonly type = "mkdir";
+    validate(config: unknown): StepValidationResult;
+    execute(context: StepContext, config: unknown): Promise<StepResult>;
+    rollback(context: StepContext, config: unknown, _error: Error): Promise<void>;
+}
+
+/**
+ * Execute an arbitrary shell command within the workspace.
+ */
+declare class ExecStep extends InitializerStepExecutor {
+    readonly type = "exec";
+    validate(config: unknown): StepValidationResult;
+    execute(context: StepContext, config: unknown): Promise<StepResult>;
+}
+
+/**
+ * Copy files or directories into the workspace.
+ * `from` can be absolute (external source) or relative to workspaceDir.
+ * `to` must be relative to workspaceDir.
+ */
+declare class FileCopyStep extends InitializerStepExecutor {
+    readonly type = "file-copy";
+    validate(config: unknown): StepValidationResult;
+    execute(context: StepContext, config: unknown): Promise<StepResult>;
+    rollback(context: StepContext, config: unknown, _error: Error): Promise<void>;
+}
+
+/**
+ * Clone a git repository into the workspace.
+ */
+declare class GitCloneStep extends InitializerStepExecutor {
+    readonly type = "git-clone";
+    validate(config: unknown): StepValidationResult;
+    execute(context: StepContext, config: unknown): Promise<StepResult>;
+    rollback(context: StepContext, config: unknown, _error: Error): Promise<void>;
+}
+
+/**
+ * Run package installation (npm/pnpm/yarn install) within the workspace.
+ */
+declare class NpmInstallStep extends InitializerStepExecutor {
+    readonly type = "npm-install";
+    validate(config: unknown): StepValidationResult;
+    execute(context: StepContext, config: unknown): Promise<StepResult>;
+}
+
+/**
+ * Create a StepRegistry pre-loaded with all built-in step executors.
+ */
+declare function createDefaultStepRegistry(): StepRegistry;
+
+declare const AgentStatusSchema: z.ZodEnum<{
+    error: "error";
+    running: "running";
+    created: "created";
+    starting: "starting";
+    stopping: "stopping";
+    stopped: "stopped";
+    crashed: "crashed";
+}>;
+declare const LaunchModeSchema: z.ZodEnum<{
+    direct: "direct";
+    "acp-background": "acp-background";
+    "acp-service": "acp-service";
+    "one-shot": "one-shot";
+}>;
+declare const AgentInstanceMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    templateName: z.ZodString;
+    templateVersion: z.ZodString;
+    backendType: z.ZodDefault<z.ZodEnum<{
+        cursor: "cursor";
+        "claude-code": "claude-code";
+        custom: "custom";
+    }>>;
+    backendConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    status: z.ZodEnum<{
+        error: "error";
+        running: "running";
+        created: "created";
+        starting: "starting";
+        stopping: "stopping";
+        stopped: "stopped";
+        crashed: "crashed";
+    }>;
+    launchMode: z.ZodEnum<{
+        direct: "direct";
+        "acp-background": "acp-background";
+        "acp-service": "acp-service";
+        "one-shot": "one-shot";
+    }>;
+    workspacePolicy: z.ZodDefault<z.ZodEnum<{
+        persistent: "persistent";
+        ephemeral: "ephemeral";
+    }>>;
+    processOwnership: z.ZodDefault<z.ZodEnum<{
+        managed: "managed";
+        external: "external";
+    }>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    pid: z.ZodOptional<z.ZodNumber>;
+    effectivePermissions: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        defaultMode: z.ZodOptional<z.ZodEnum<{
+            bypassPermissions: "bypassPermissions";
+            default: "default";
+            acceptEdits: "acceptEdits";
+            plan: "plan";
+            dontAsk: "dontAsk";
+        }>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
+            network: z.ZodOptional<z.ZodObject<{
+                allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        additionalDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+
+/** Minimal interface for scanInstances to use registry without circular dependency. */
+interface InstanceRegistryAdapter {
+    list(): Iterable<{
+        name: string;
+        workspacePath: string;
+        status: string;
+    }>;
+}
+
+declare function metaFilePath(workspaceDir: string): string;
+/** Read and validate `.actant.json` from a workspace directory. */
+declare function readInstanceMeta(workspaceDir: string): Promise<AgentInstanceMeta>;
+/** Atomic write: write to a temp file then rename (prevents partial writes). */
+declare function writeInstanceMeta(workspaceDir: string, meta: AgentInstanceMeta): Promise<void>;
+/** Partially update `.actant.json` — read, merge, write. */
+declare function updateInstanceMeta(workspaceDir: string, patch: Partial<AgentInstanceMeta>): Promise<AgentInstanceMeta>;
+/**
+ * Scan `instancesBaseDir` for all valid instance directories.
+ * Directories whose `.actant.json` is missing or invalid are logged and skipped.
+ *
+ * When `registry` is provided, also includes instances from the registry (external workspaces)
+ * and deduplicates by name (registry entries take precedence).
+ */
+declare function scanInstances(instancesBaseDir: string, registry?: InstanceRegistryAdapter): Promise<{
+    valid: AgentInstanceMeta[];
+    corrupted: string[];
+}>;
+
+interface InstanceRegistryEntry {
+    name: string;
+    template: string;
+    workspacePath: string;
+    location: "builtin" | "external";
+    createdAt: string;
+    status: "stopped" | "running" | "orphaned";
+}
+interface InstanceRegistryData {
+    version: 1;
+    instances: Record<string, InstanceRegistryEntry>;
+}
+declare class InstanceRegistry implements InstanceRegistryAdapter {
+    private readonly registryPath;
+    private readonly builtinInstancesDir;
+    private data;
+    constructor(registryPath: string, builtinInstancesDir: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    register(entry: InstanceRegistryEntry): void;
+    unregister(name: string): boolean;
+    get(name: string): InstanceRegistryEntry | undefined;
+    list(): InstanceRegistryEntry[];
+    has(name: string): boolean;
+    updateStatus(name: string, status: InstanceRegistryEntry["status"]): void;
+    adopt(workspacePath: string, renameTo?: string): Promise<InstanceRegistryEntry>;
+    reconcile(): Promise<{
+        orphaned: string[];
+        adopted: string[];
+    }>;
+}
+
+interface AgentProcess {
+    pid: number;
+    workspaceDir: string;
+    instanceName: string;
+    /** Present when the process uses ACP stdio protocol. */
+    stdio?: {
+        stdin: Writable;
+        stdout: Readable;
+        stderr: Readable;
+    };
+}
+/**
+ * Strategy interface for launching/terminating Agent backend processes.
+ */
+interface AgentLauncher {
+    launch(workspaceDir: string, meta: AgentInstanceMeta): Promise<AgentProcess>;
+    terminate(process: AgentProcess): Promise<void>;
+}
+
+interface RestartPolicy {
+    /** Maximum number of restarts before giving up. Default: 5 */
+    maxRestarts: number;
+    /** Base delay for exponential backoff (ms). Default: 1000 */
+    backoffBaseMs: number;
+    /** Maximum backoff delay cap (ms). Default: 60000 */
+    backoffMaxMs: number;
+    /** Reset restart counter after this many ms of stable running. Default: 300000 (5 min) */
+    resetAfterMs: number;
+}
+declare const DEFAULT_RESTART_POLICY: RestartPolicy;
+interface RestartDecision {
+    allowed: boolean;
+    delayMs: number;
+    attempt: number;
+}
+/**
+ * Tracks restart attempts per instance and enforces exponential backoff.
+ *
+ * Usage:
+ *   const tracker = new RestartTracker();
+ *   // Before restarting:
+ *   const decision = tracker.shouldRestart("my-agent");
+ *   if (decision.allowed) {
+ *     await delay(decision.delayMs);
+ *     tracker.recordRestart("my-agent");
+ *     // ... do restart ...
+ *   }
+ *   // After agent successfully starts:
+ *   tracker.recordStart("my-agent");
+ */
+declare class RestartTracker {
+    private states;
+    private readonly policy;
+    constructor(policy?: Partial<RestartPolicy>);
+    shouldRestart(instanceName: string): RestartDecision;
+    recordRestart(instanceName: string): void;
+    recordStart(instanceName: string): void;
+    reset(instanceName: string): void;
+    getRestartCount(instanceName: string): number;
+    dispose(): void;
+    private getOrCreate;
+}
+
+interface PromptResult {
+    text: string;
+    sessionId?: string;
+}
+interface StreamChunk {
+    type: "text" | "tool_use" | "result" | "error";
+    content: string;
+}
+interface AgentCommunicator {
+    /**
+     * Send a prompt and collect the full response.
+     * @param workspaceDir - The agent's workspace directory (cwd for the process)
+     * @param prompt - The user prompt
+     * @param options - Optional configuration
+     */
+    runPrompt(workspaceDir: string, prompt: string, options?: RunPromptOptions): Promise<PromptResult>;
+    /**
+     * Send a prompt and stream the response chunks.
+     * @param workspaceDir - The agent's workspace directory
+     * @param prompt - The user prompt
+     * @param options - Optional configuration
+     */
+    streamPrompt(workspaceDir: string, prompt: string, options?: RunPromptOptions): AsyncIterable<StreamChunk>;
+}
+interface RunPromptOptions {
+    systemPromptFile?: string;
+    appendSystemPrompt?: string;
+    sessionId?: string;
+    timeoutMs?: number;
+    maxTurns?: number;
+    model?: string;
+}
+type CommunicatorFactory = (backendType: AgentBackendType) => AgentCommunicator;
+
+/**
+ * Minimal ACP connection manager interface.
+ * The real implementation lives in @actant/acp; this avoids a circular dependency.
+ */
+interface AcpConnectionManagerLike {
+    connect(name: string, options: {
+        command: string;
+        args: string[];
+        cwd: string;
+        connectionOptions?: {
+            autoApprove?: boolean;
+            env?: Record<string, string>;
+        };
+    }): Promise<{
+        sessionId: string;
+    }>;
+    has(name: string): boolean;
+    getPrimarySessionId(name: string): string | undefined;
+    getConnection(name: string): AcpConnectionLike | undefined;
+    disconnect(name: string): Promise<void>;
+    disposeAll(): Promise<void>;
+}
+interface AcpConnectionLike {
+    prompt(sessionId: string, text: string): Promise<{
+        stopReason: string;
+        text: string;
+    }>;
+    streamPrompt(sessionId: string, text: string): AsyncIterable<unknown>;
+    newSession(cwd: string): Promise<{
+        sessionId: string;
+    }>;
+    isConnected: boolean;
+}
+interface ManagerOptions {
+    corruptedDir?: string;
+    /** Milliseconds between process alive checks. Default: 5000 */
+    watcherPollIntervalMs?: number;
+    /** Restart policy for acp-service agents. */
+    restartPolicy?: Partial<RestartPolicy>;
+    /** ACP connection manager for ACP-based backends. */
+    acpManager?: AcpConnectionManagerLike;
+    /** Instance registry for discovering external workspaces. */
+    instanceRegistry?: InstanceRegistryAdapter;
+}
+declare class AgentManager {
+    private readonly initializer;
+    private readonly launcher;
+    private readonly instancesBaseDir;
+    private cache;
+    private processes;
+    private readonly corruptedDir;
+    private readonly watcher;
+    private readonly restartTracker;
+    private readonly acpManager?;
+    private readonly instanceRegistry?;
+    constructor(initializer: AgentInitializer, launcher: AgentLauncher, instancesBaseDir: string, options?: ManagerOptions);
+    /**
+     * Scan all workspace directories, load metadata into cache,
+     * fix stale running/starting states, and start the process watcher.
+     */
+    initialize(): Promise<void>;
+    /** Create a new agent (delegates to Initializer). */
+    createAgent(name: string, templateName: string, overrides?: Partial<InstanceOverrides>): Promise<AgentInstanceMeta>;
+    /** Find existing or create new agent (idempotent). */
+    getOrCreateAgent(name: string, templateName: string, overrides?: Partial<InstanceOverrides>): Promise<{
+        meta: AgentInstanceMeta;
+        created: boolean;
+    }>;
+    /**
+     * Start an agent — launch the backend process.
+     * For ACP backends, also establishes ACP connection (initialize + session/new).
+     * @throws {AgentNotFoundError} if agent is not in cache
+     * @throws {AgentAlreadyRunningError} if agent is already running
+     */
+    startAgent(name: string): Promise<void>;
+    /**
+     * Stop an agent — disconnect ACP and terminate the backend process.
+     * @throws {AgentNotFoundError} if agent is not in cache
+     */
+    stopAgent(name: string): Promise<void>;
+    /** Destroy an agent — stop it if running, then remove workspace. */
+    destroyAgent(name: string): Promise<void>;
+    /** Get agent metadata by name. */
+    getAgent(name: string): AgentInstanceMeta | undefined;
+    /** Get agent status by name. */
+    getStatus(name: string): AgentStatus | undefined;
+    /** List all known agents. */
+    listAgents(): AgentInstanceMeta[];
+    /** Get count of managed agents. */
+    get size(): number;
+    /**
+     * Resolve spawn info for an agent without starting it.
+     * If the agent doesn't exist but templateName is provided, auto-creates it.
+     */
+    resolveAgent(name: string, templateName?: string, overrides?: Partial<InstanceOverrides>): Promise<ResolveResult>;
+    /**
+     * Register an externally-spawned process with the manager.
+     * Sets processOwnership to "external" and registers ProcessWatcher monitoring.
+     * @throws {AgentNotFoundError} if agent is not in cache
+     * @throws {AgentAlreadyAttachedError} if agent already has an attached process
+     */
+    attachAgent(name: string, pid: number, attachMetadata?: Record<string, string>): Promise<AgentInstanceMeta>;
+    /**
+     * Detach an externally-managed process.
+     * Clears pid and processOwnership. If cleanup is requested and workspace is ephemeral, destroys the instance.
+     * @throws {AgentNotFoundError} if agent is not in cache
+     * @throws {AgentNotAttachedError} if agent has no attached process
+     */
+    detachAgent(name: string, options?: {
+        cleanup?: boolean;
+    }): Promise<DetachResult>;
+    /**
+     * Send a prompt to an agent and collect the full response.
+     * Uses ACP connection if the agent is started with ACP, otherwise falls back to CLI pipe mode.
+     */
+    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.
+     */
+    streamPrompt(name: string, prompt: string, options?: RunPromptOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Send a message to a running agent via its ACP session.
+     * Unlike runPrompt, this requires the agent to be started with ACP.
+     * @throws {Error} if agent has no ACP connection
+     */
+    promptAgent(name: string, message: string, sessionId?: string): Promise<PromptResult>;
+    /** Check if an agent has an active ACP connection. */
+    hasAcpConnection(name: string): boolean;
+    /** Shut down the process watcher, ACP connections, and release resources. */
+    dispose(): Promise<void>;
+    private handleProcessExit;
+    private requireAgent;
+    private moveToCorrupted;
+}
+
+/**
+ * What the manager should do when a watched process exits.
+ * - "mark-stopped": set status to stopped, clear pid (default for most modes)
+ * - "restart": attempt to relaunch the process (acp-service with restart policy)
+ * - "destroy": mark stopped then destroy the instance (one-shot with autoDestroy)
+ */
+type ProcessExitAction = {
+    type: "mark-stopped";
+} | {
+    type: "restart";
+} | {
+    type: "destroy";
+};
+/**
+ * What the manager should do for a stale running/starting instance on daemon restart.
+ * - "mark-stopped": reset status to stopped (default)
+ * - "restart": attempt to relaunch (acp-service recovery)
+ */
+type RecoveryAction = {
+    type: "mark-stopped";
+} | {
+    type: "restart";
+};
+interface LaunchModeHandler {
+    readonly mode: LaunchMode;
+    getProcessExitAction(instanceName: string, meta?: AgentInstanceMeta): ProcessExitAction;
+    getRecoveryAction(instanceName: string): RecoveryAction;
+}
+declare function getLaunchModeHandler(mode: LaunchMode): LaunchModeHandler;
+
+/**
+ * Mock launcher for testing — simulates launching a process
+ * by returning a fake PID without actually spawning anything.
+ */
+declare class MockLauncher implements AgentLauncher {
+    readonly launched: AgentProcess[];
+    readonly terminated: AgentProcess[];
+    launch(workspaceDir: string, meta: AgentInstanceMeta): Promise<AgentProcess>;
+    terminate(process: AgentProcess): Promise<void>;
+}
+
+interface ProcessLogWriterOptions {
+    /** Max file size in bytes before rotation. Default: 10 MB. */
+    maxSizeBytes?: number;
+    /** Number of rotated files to keep. Default: 3. */
+    maxFiles?: number;
+}
+/**
+ * Captures stdout/stderr from a child process into log files within
+ * {instanceDir}/logs/. Supports size-based log rotation.
+ */
+declare class ProcessLogWriter {
+    private readonly logsDir;
+    private readonly maxSize;
+    private readonly maxFiles;
+    private stdoutStream;
+    private stderrStream;
+    private stdoutBytes;
+    private stderrBytes;
+    private closed;
+    constructor(instanceDir: string, options?: ProcessLogWriterOptions);
+    /**
+     * Initialize the log directory and open write streams.
+     * Call this before piping process streams.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Attach to readable streams from a spawned process.
+     */
+    attach(stdout: Readable | null, stderr: Readable | null): void;
+    /**
+     * Close all write streams gracefully.
+     */
+    close(): Promise<void>;
+    /**
+     * Read the last N lines from a log file (stdout or stderr).
+     */
+    readTail(stream: "stdout" | "stderr", lines: number): Promise<string[]>;
+    get logDirectory(): string;
+    private rotateFile;
+    private closeStream;
+}
+
+interface ProcessLauncherOptions {
+    /** Milliseconds to wait for graceful shutdown before SIGKILL. Default: 5000 */
+    terminateTimeoutMs?: number;
+    /** Milliseconds to wait after spawn to verify the process is still alive. Default: 500 */
+    spawnVerifyDelayMs?: number;
+    /** Enable process log capture for non-ACP backends. Default: true. */
+    enableProcessLogs?: boolean;
+    /** Options for process log file writer. */
+    logWriterOptions?: ProcessLogWriterOptions;
+}
+/**
+ * Real launcher that spawns IDE/CLI backend processes.
+ *
+ * Lifecycle:
+ *   launch()     → spawn detached child → verify alive → return AgentProcess
+ *   terminate()  → SIGTERM → wait → SIGKILL if still alive
+ */
+declare class ProcessLauncher implements AgentLauncher {
+    private readonly terminateTimeoutMs;
+    private readonly spawnVerifyDelayMs;
+    private readonly enableProcessLogs;
+    private readonly logWriterOptions?;
+    private readonly logWriters;
+    constructor(options?: ProcessLauncherOptions);
+    launch(workspaceDir: string, meta: AgentInstanceMeta): Promise<AgentProcess>;
+    getLogWriter(instanceName: string): ProcessLogWriter | undefined;
+    terminate(agentProcess: AgentProcess): Promise<void>;
+}
+
+type LauncherMode = "mock" | "real";
+interface LauncherConfig {
+    mode: LauncherMode;
+    processOptions?: ProcessLauncherOptions;
+}
+/**
+ * Factory function to create the appropriate AgentLauncher.
+ *
+ * - "mock": returns MockLauncher (for testing / development without real IDE)
+ * - "real": returns ProcessLauncher (spawns actual processes)
+ *
+ * Default: "real" in production, can be overridden by config or env.
+ */
+declare function createLauncher(config?: Partial<LauncherConfig>): AgentLauncher;
+
+interface ResolvedBackend {
+    command: string;
+    args: string[];
+}
+/** Whether a backend type uses the ACP stdio protocol for communication. */
+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`.
+ */
+declare function resolveBackend(backendType: AgentBackendType, workspaceDir: string, backendConfig?: Record<string, unknown>): ResolvedBackend;
+
+/**
+ * Check whether a process with the given PID is still alive.
+ * Uses `kill(pid, 0)` which sends no signal but checks existence.
+ */
+declare function isProcessAlive(pid: number): boolean;
+
+interface ProcessExitInfo {
+    instanceName: string;
+    pid: number;
+}
+type ProcessExitHandler = (info: ProcessExitInfo) => void | Promise<void>;
+interface ProcessWatcherOptions {
+    /** Milliseconds between alive-checks. Default: 5000 */
+    pollIntervalMs?: number;
+}
+/**
+ * Periodically polls tracked PIDs and fires a callback
+ * when a watched process is no longer alive.
+ *
+ * Usage:
+ *   const watcher = new ProcessWatcher(onExit, { pollIntervalMs: 3000 });
+ *   watcher.start();
+ *   watcher.watch("my-agent", 12345);
+ *   // ... later ...
+ *   watcher.unwatch("my-agent");  // e.g. before intentional stop
+ *   watcher.dispose();
+ */
+declare class ProcessWatcher {
+    private readonly onProcessExit;
+    private readonly watches;
+    private timer;
+    private polling;
+    private readonly pollIntervalMs;
+    constructor(onProcessExit: ProcessExitHandler, options?: ProcessWatcherOptions);
+    watch(instanceName: string, pid: number): void;
+    unwatch(instanceName: string): boolean;
+    isWatching(instanceName: string): boolean;
+    get watchCount(): number;
+    start(): void;
+    stop(): void;
+    dispose(): void;
+    get isRunning(): boolean;
+    private poll;
+}
+
+/**
+ * Communicates with an agent via the `claude` CLI in print mode.
+ * Uses `claude -p --output-format stream-json "prompt"` for streaming
+ * and `claude -p --output-format json "prompt"` for one-shot.
+ */
+declare class ClaudeCodeCommunicator implements AgentCommunicator {
+    private readonly executable;
+    constructor(executable?: string);
+    runPrompt(workspaceDir: string, prompt: string, options?: RunPromptOptions): Promise<PromptResult>;
+    streamPrompt(workspaceDir: string, prompt: string, options?: RunPromptOptions): AsyncIterable<StreamChunk>;
+    private buildArgs;
+}
+
+/**
+ * Communicator stub for Cursor backend.
+ * Cursor CLI does not yet support a pipe mode for programmatic communication.
+ * This implementation provides a clear error until Cursor adds this capability.
+ */
+declare class CursorCommunicator implements AgentCommunicator {
+    runPrompt(_workspaceDir: string, _prompt: string, _options?: RunPromptOptions): Promise<PromptResult>;
+    streamPrompt(_workspaceDir: string, _prompt: string, _options?: RunPromptOptions): AsyncIterable<StreamChunk>;
+}
+
+declare function createCommunicator(backendType: AgentBackendType): AgentCommunicator;
+
+declare function resolvePermissions(input: PermissionsInput | undefined): PermissionsConfig;
+declare function resolvePermissionsWithMcp(input: PermissionsInput | undefined, mcpServerNames: string[]): PermissionsConfig;
+
+/**
+ * Minimal tool information extracted from ACP RequestPermissionRequest.toolCall
+ * for pattern matching against PermissionsConfig rules.
+ */
+interface ToolCallInfo {
+    /** ACP ToolKind: read | edit | delete | move | search | execute | think | fetch | switch_mode | other */
+    kind?: string;
+    /** Human-readable title, e.g. "Bash: npm run build", "Write to /src/foo.ts" */
+    title?: string;
+    /** Tool call ID for audit trail */
+    toolCallId: string;
+}
+type PolicyAction = "allow" | "deny" | "ask";
+interface PolicyDecision {
+    action: PolicyAction;
+    matchedRule?: string;
+}
+/**
+ * Permission policy enforcer that evaluates ACP tool calls against
+ * a PermissionsConfig (allow/deny/ask lists with Claude Code glob syntax).
+ *
+ * Evaluation order: deny -> ask -> allow (deny wins).
+ */
+declare class PermissionPolicyEnforcer {
+    private config;
+    constructor(config: PermissionsConfig);
+    updateConfig(config: PermissionsConfig): void;
+    getConfig(): Readonly<PermissionsConfig>;
+    /**
+     * Evaluate a tool call against the configured permission rules.
+     * Order: deny > ask > allow > defaultMode fallback.
+     */
+    evaluate(toolCall: ToolCallInfo): PolicyDecision;
+    /**
+     * Build an ACP RequestPermissionOutcome from a PolicyDecision.
+     * Returns the appropriate option selection based on the decision.
+     */
+    buildOutcome(decision: PolicyDecision, options: ReadonlyArray<{
+        kind: string;
+        optionId: string;
+    }>): {
+        outcome: "selected";
+        optionId: string;
+    } | {
+        outcome: "cancelled";
+    };
+    private extractToolName;
+    private extractToolArg;
+    /**
+     * Check if toolName+toolArg match any pattern in the list.
+     * Returns the matched pattern string, or undefined.
+     */
+    private matchList;
+    /**
+     * Match a single Claude Code permission pattern against tool name + arg.
+     *
+     * Supported formats:
+     *   "*"              — matches everything
+     *   "ToolName"       — matches tool by name (case-insensitive)
+     *   "Tool(specifier)" — matches tool with glob specifier
+     *   "mcp__server"    — matches MCP server prefix
+     *   "mcp__server__tool" — matches specific MCP tool
+     */
+    private matchPattern;
+    private toolNameMatches;
+}
+/**
+ * Simple glob matcher supporting * (match any sequence) and ** (match across path separators).
+ * Sufficient for Claude Code permission patterns like "npm run *", "./src/**", "domain:*.com".
+ */
+declare function globMatch(pattern: string, input: string): boolean;
+
+type PermissionAuditEvent = "permission.resolved" | "permission.injected" | "permission.evaluated" | "permission.updated";
+interface AuditEntry {
+    event: PermissionAuditEvent;
+    instanceName?: string;
+    templateName?: string;
+    toolCall?: ToolCallInfo;
+    decision?: PolicyDecision;
+    detail?: Record<string, unknown>;
+    timestamp: string;
+}
+declare class PermissionAuditLogger {
+    private readonly instanceName;
+    constructor(instanceName?: string);
+    log(event: PermissionAuditEvent, detail?: Omit<AuditEntry, "event" | "timestamp" | "instanceName">): void;
+    logEvaluation(toolCall: ToolCallInfo, decision: PolicyDecision): void;
+    logResolved(templateName: string, preset?: string): void;
+    logInjected(backendType: string): void;
+    logUpdated(source: string): void;
+}
+
+type SessionState = "active" | "idle" | "expired";
+interface SessionLease {
+    sessionId: string;
+    agentName: string;
+    /** Currently-bound client identifier. null when idle (client disconnected). */
+    clientId: string | null;
+    state: SessionState;
+    createdAt: string;
+    lastActivityAt: string;
+    /** Milliseconds of idle time before the session expires. */
+    idleTtlMs: number;
+}
+interface CreateSessionOptions {
+    agentName: string;
+    clientId: string;
+    idleTtlMs?: number;
+}
+interface SessionRegistryOptions {
+    defaultIdleTtlMs?: number;
+    ttlCheckIntervalMs?: number;
+}
+/**
+ * In-memory registry of Session Lease objects.
+ * Tracks which client owns which session, handles idle/expire transitions,
+ * and runs a periodic sweep to expire stale sessions.
+ */
+declare class SessionRegistry {
+    private sessions;
+    private sweepTimer;
+    private readonly defaultIdleTtlMs;
+    private onExpireCallback?;
+    constructor(options?: SessionRegistryOptions);
+    /** Register a callback invoked when a session expires. */
+    onExpire(callback: (session: SessionLease) => void): void;
+    /** Create a new session for an agent, bound to a client. */
+    create(opts: CreateSessionOptions): SessionLease;
+    /** Get a session by ID, or undefined if not found. */
+    get(sessionId: string): SessionLease | undefined;
+    /** List all sessions, optionally filtered by agent name. */
+    list(agentName?: string): SessionLease[];
+    /**
+     * Record activity on a session, updating lastActivityAt
+     * and ensuring state is "active".
+     */
+    touch(sessionId: string): void;
+    /**
+     * Mark a session as idle (client disconnected but session is kept alive).
+     * The session will expire after its idleTtlMs elapses.
+     */
+    release(sessionId: string): void;
+    /**
+     * Resume an idle session, binding it to a (potentially new) client.
+     * Returns false if the session is not found, expired, or already active.
+     */
+    resume(sessionId: string, clientId: string): boolean;
+    /** Explicitly close and remove a session. */
+    close(sessionId: string): boolean;
+    /** Close all sessions for a given agent. */
+    closeByAgent(agentName: string): number;
+    /** Number of active sessions. */
+    get size(): number;
+    /** Stop the TTL sweep timer and clear all sessions. */
+    dispose(): void;
+    private sweepExpired;
+}
+
+interface FetchResult {
+    manifest: PackageManifest;
+    skills: SkillDefinition[];
+    prompts: PromptDefinition[];
+    mcpServers: McpServerDefinition[];
+    workflows: WorkflowDefinition[];
+    presets: PresetDefinition[];
+    templates: AgentTemplate[];
+}
+/**
+ * Extensible interface for component sources.
+ * Implement this to add new source types (GitHub, local, HTTP, npm, etc.).
+ */
+interface ComponentSource {
+    readonly type: string;
+    readonly packageName: string;
+    readonly config: SourceConfig;
+    fetch(): Promise<FetchResult>;
+    sync(): Promise<FetchResult>;
+    dispose(): Promise<void>;
+}
+
+/**
+ * Fetches component packages from GitHub repositories via shallow clone.
+ * After cloning, delegates to LocalSource for actual file parsing.
+ */
+declare class GitHubSource implements ComponentSource {
+    readonly type = "github";
+    readonly packageName: string;
+    readonly config: GitHubSourceConfig;
+    private readonly cacheDir;
+    constructor(packageName: string, config: GitHubSourceConfig, cacheDir: string);
+    fetch(): Promise<FetchResult>;
+    sync(): Promise<FetchResult>;
+    dispose(): Promise<void>;
+    private clone;
+    private pull;
+    private readCached;
+}
+
+declare class LocalSource implements ComponentSource {
+    readonly type = "local";
+    readonly packageName: string;
+    readonly config: LocalSourceConfig;
+    constructor(packageName: string, config: LocalSourceConfig);
+    fetch(): Promise<FetchResult>;
+    sync(): Promise<FetchResult>;
+    dispose(): Promise<void>;
+    private loadPackage;
+    private loadManifest;
+    private loadJsonDir;
+    private loadPresets;
+}
+
+type ComponentTypeName = "skill" | "prompt" | "workflow" | "mcpServer" | "plugin" | "template" | "preset";
+interface ComponentVersionDelta {
+    type: ComponentTypeName;
+    name: string;
+    oldVersion?: string;
+    newVersion?: string;
+}
+interface SyncReport {
+    added: ComponentVersionDelta[];
+    updated: ComponentVersionDelta[];
+    removed: ComponentVersionDelta[];
+    unchanged: string[];
+    hasBreakingChanges: boolean;
+}
+
+declare const DEFAULT_SOURCE_NAME = "actant-hub";
+declare const DEFAULT_SOURCE_CONFIG: SourceConfig;
+
+interface SourceManagerDeps {
+    skillManager: BaseComponentManager<SkillDefinition>;
+    promptManager: BaseComponentManager<PromptDefinition>;
+    mcpConfigManager: BaseComponentManager<McpServerDefinition>;
+    workflowManager: BaseComponentManager<WorkflowDefinition>;
+    templateRegistry?: TemplateRegistry;
+}
+/**
+ * Manages component sources (GitHub repos, local dirs, etc.).
+ * Syncs remote components into the domain managers with `package@name` namespacing.
+ */
+declare class SourceManager {
+    private readonly sources;
+    private readonly presets;
+    private readonly managers;
+    private readonly homeDir;
+    private readonly sourcesFilePath;
+    private readonly cacheDir;
+    constructor(homeDir: string, managers: SourceManagerDeps);
+    addSource(name: string, config: SourceConfig): Promise<FetchResult>;
+    syncSource(name: string): Promise<FetchResult>;
+    syncSourceWithReport(name: string): Promise<{
+        fetchResult: FetchResult;
+        report: SyncReport;
+    }>;
+    syncAll(): Promise<void>;
+    syncAllWithReport(): Promise<{
+        report: SyncReport;
+    }>;
+    removeSource(name: string): Promise<boolean>;
+    listSources(): SourceEntry[];
+    hasSource(name: string): boolean;
+    listPresets(packageName?: string): PresetDefinition[];
+    getPreset(qualifiedName: string): PresetDefinition | undefined;
+    /**
+     * Apply a preset to a template — expands preset component refs
+     * into the template's domainContext with `package@name` namespacing.
+     * Returns a new template (does not mutate input).
+     */
+    applyPreset(qualifiedName: string, template: AgentTemplate): AgentTemplate;
+    initialize(): Promise<void>;
+    private createSource;
+    private injectComponents;
+    private removeNamespacedComponents;
+    private removeNamespacedPresets;
+    private persistSources;
+    private getSourceOrThrow;
+    private snapshotComponents;
+    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 };