/**
 * Spatial Agent Service
 *
 * The missing service/lifecycle layer over the proven vm-bridge primitives
 * (`SpatialCognitiveAgent`, `captureSceneSnapshot`, `applyActions`) and the
 * `@holoscript/uaal` 7-phase VM.
 *
 * Responsibilities:
 *   - `spawnAgent()`  — compile/accept a uAAL program, wire a
 *                       SpatialCognitiveAgent to the shared ECSWorld, register it.
 *   - `despawnAgent()` — clean up the agent's body entity + unregister.
 *   - `tickAll(nowMs)` — drive every live agent's perceive→decide→mutate cycle,
 *                        throttled per-agent by its cognitiveHz, callable from
 *                        the 60fps HoloVM frame loop.
 *
 * This is the destination for marketplace-acquired agent templates: Studio
 * acquires a uAAL program (intent or bytecode) and hands it to `spawnAgent`,
 * after which the agent participates in the next `tickAll` cycle.
 *
 * @packageDocumentation
 */
import type { ECSWorld } from '../vm/executor';
import type { UAALBytecode } from '@holoscript/uaal';
import { type CognitiveTickResult } from './bridge';
import { type IAgentRegistry, type RegisteredAgent } from './agent-registry';
/**
 * Template config a marketplace install (or any caller) passes to spawn a
 * spatial agent. Exactly one of `intent` / `bytecode` is required.
 */
export interface SpawnAgentConfig {
    /** Optional explicit id; auto-generated when omitted. */
    id?: string;
    /** Display / template name. */
    name?: string;
    /** Natural-language or DSL intent, compiled to bytecode via UAALCompiler. */
    intent?: string;
    /** Pre-compiled uAAL bytecode (takes precedence over `intent`). */
    bytecode?: UAALBytecode;
    /** Cognitive cycle frequency in Hz (default 2). */
    cognitiveHz?: number;
    /** Capability tags carried from the template (discovery/delegation). */
    capabilities?: string[];
    /**
     * Spawn a body entity in the ECS world for this agent and record its id.
     * Defaults to true. The body is despawned on `despawnAgent`.
     */
    spawnBody?: boolean;
    /** Pass-through VM options. */
    enableLogging?: boolean;
}
/**
 * Shape emitted by the Studio marketplace `onAgentInstalled` callback
 * (`AgentMarketplaceTab` / `MarketplaceClient.installAgent`). Bridging this to
 * a {@link SpawnAgentConfig} is what wires marketplace acquisition to a live
 * agent — see {@link spawnConfigFromMarketplaceInstall}.
 */
export interface MarketplaceInstallResult {
    templateId: string;
    templateName: string;
    /** uAAL program — either an intent string or serialized bytecode JSON. */
    program: string;
    programType: 'intent' | 'bytecode';
    config: {
        cognitiveHz: number;
        capabilities: string[];
    };
}
/**
 * Map a marketplace install result to a {@link SpawnAgentConfig}.
 *
 * `programType: 'intent'`   → `intent` string (service compiles it).
 * `programType: 'bytecode'` → `program` is parsed as serialized UAALBytecode JSON.
 */
export declare function spawnConfigFromMarketplaceInstall(result: MarketplaceInstallResult): SpawnAgentConfig;
export interface SpatialAgentServiceConfig {
    /** Inject a custom registry. Defaults to an in-memory registry. */
    registry?: IAgentRegistry;
    /** Default cognitive Hz applied when a spawn config omits it. */
    defaultCognitiveHz?: number;
}
export declare class SpatialAgentService {
    private readonly world;
    private readonly registry;
    private readonly defaultCognitiveHz;
    private readonly compiler;
    constructor(world: ECSWorld, config?: SpatialAgentServiceConfig);
    /**
     * Spawn a spatial cognitive agent: compile/accept its program, create the
     * bridge instance against the shared world, optionally give it a body
     * entity, and register it. Returns the registered agent record.
     */
    spawnAgent(config: SpawnAgentConfig): RegisteredAgent;
    /**
     * Despawn an agent: remove its body entity from the world and unregister it.
     * Returns true if an agent was removed.
     */
    despawnAgent(id: string): boolean;
    /**
     * Drive every live agent one frame. Each agent self-throttles to its own
     * cognitiveHz inside `tick`, so this is safe to call every 60fps frame.
     * Returns the per-agent tick results keyed by agent id.
     */
    tickAll(nowMs: number): Promise<Map<string, CognitiveTickResult>>;
    getRegistry(): IAgentRegistry;
    getAgent(id: string): RegisteredAgent | undefined;
    listAgents(): RegisteredAgent[];
    get agentCount(): number;
}
//# sourceMappingURL=spatial-agent-service.d.ts.map