import type { Identity } from '@icp-sdk/core/agent';
import type { OperatorPermissions } from './engram-idl.js';
export interface CreateOptions {
    /** The owner identity — its principal becomes the engram's owner (root). Never EngramX's key. */
    identity: Identity;
    /** The EngramX registry canister id to create against (defaults to the canonical registry). */
    registryCanisterId: string;
    /** Replica host, e.g. https://icp-api.io (mainnet) or http://127.0.0.1:4943 (local). */
    host: string;
    /** Local replica → fetch the root key before calling. Never do this against mainnet. */
    local: boolean;
    /**
     * Spawn the live canister in this same call. Default false → RESERVE only (a free registry
     * record, ~$0). See the module docs for why reserve is the default.
     */
    activate?: boolean;
    /**
     * Invite code for deployments that arm the reserve gate (invite-or-wallet-proof admission).
     * Raw-keypair identities (the kind this CLI mints) need one there; wallet-rooted identities
     * do not. Ignored by deployments with the gate off (the default).
     */
    invite?: string;
}
export type EngramState = 'none' | 'reserved' | 'provisioned';
export interface CreateResult {
    /** What exists now: 'none' (nothing yet), a free 'reserved' record, or a live 'provisioned' canister. */
    state: EngramState;
    /** The engram canister id — present only once provisioned (null while merely reserved). */
    canisterId: string | null;
    /** The owner principal (the identity that signed — you). */
    owner: string;
    /** True if the record already existed (one-per-principal) and was returned as-is. */
    alreadyExisted: boolean;
}
/**
 * Create an engram owned by `opts.identity`.
 *
 * RESERVE IS THE DEFAULT, and provisioning (the real ~1.15T-cycle canister spawn) is a separate,
 * opt-in step. This is the cycle anti-drain: a skill/agent that calls "create" speculatively and
 * walks away leaves only a FREE registry record (`reserved`), never a funded canister. The spawn
 * happens only when the owner actually commits — `activate: true` here, or a later `provision()`
 * call — i.e. when there is a real signal the engram will be used.
 *
 * The registry makes the CALLER the owner — no owner parameter, no reassignment — so the signing
 * identity IS the owner, by construction. Idempotent on both steps: an existing reservation or
 * engram (one-per-principal) is returned as-is rather than provoking an Err.
 */
export declare function createEngram(opts: CreateOptions): Promise<CreateResult>;
/**
 * Provision (spawn) the canister for an already-reserved principal — the funded step, split out so
 * a two-phase flow (reserve now, activate later) can call it directly. Idempotent.
 */
export declare function provision(opts: Omit<CreateOptions, 'activate'>): Promise<CreateResult>;
/**
 * Read-only: what does this principal have — nothing, a free reservation, or a live engram? No
 * writes, no spend. Used by the owner-side status surfaces (CLI check, owner MCP).
 */
export declare function status(opts: Omit<CreateOptions, 'activate'>): Promise<CreateResult>;
export interface ConnectAgentResult extends CreateResult {
    /** The invite code the AGENT redeems with `@engramx/client pair` to become an append-only operator. */
    inviteCode: string;
    /** The label recorded for this operator. */
    operatorName: string;
}
/**
 * Connect an agent: provision the engram if needed (the owner's real-use spawn trigger — you only
 * spin it up when you're actually wiring an agent), then mint an append-only OPERATOR invite for it.
 * The agent redeems the returned code with `@engramx/client pair`. Owner ≠ operator, by construction:
 * this mints a scoped, append-only grant, never owner powers.
 */
export declare function connectAgent(opts: Omit<CreateOptions, 'activate'>, params?: {
    name?: string;
    permissions?: OperatorPermissions;
}): Promise<ConnectAgentResult>;