import type { ConnectionOpts } from 'e2b';
import type { DeferredNamedTemplateSpec } from './template.js';
/**
 * Repository clone target plus an optional credential for it.
 *
 * Structurally identical to the factory capability of the same name, and
 * declared here so this package carries no factory dependency: a host can
 * pass its context accessor straight through.
 */
export interface RepositoryAccess {
    /** https clone URL, e.g. `https://github.com/acme/widgets.git`. */
    cloneUrl: string;
    /**
     * Credential for private repositories. `scheme` describes the credential
     * itself; git over https accepts only basic auth, so a bearer token is
     * presented as `x-access-token:<token>` (see {@link gitAuthFlag}).
     */
    authorization?: {
        scheme: 'bearer';
        token: string;
    };
}
export interface RepoTemplateOptions {
    /**
     * Resolves the clone URL and, for private repositories, a SHORT-LIVED
     * credential (e.g. a GitHub App installation token). Called once per
     * template resolution: the credential authenticates the head lookup and,
     * when a build is needed, the build's clone (via `setEnvs` plus an
     * in-shell `http.extraheader` — it never touches the image filesystem,
     * and probing confirms `setEnvs` values do not persist into runtime
     * sandbox environments). Never supply a long-lived PAT: the value enters
     * the template definition, where only its expiry bounds the exposure. A
     * rejection degrades to tokenless behavior.
     *
     * Sole source of the clone URL, so what gets cloned and what the template
     * is identified by can never disagree. A public repository needs no
     * credential: `async () => ({ cloneUrl })`.
     *
     * The key is required so that passing a host context whose field was
     * renamed fails to compile instead of silently producing no template.
     * `undefined` means the session has no repository, and
     * {@link createRepoTemplate} then returns undefined.
     */
    getRepositoryAccess: (() => Promise<RepositoryAccess | undefined>) | undefined;
    /**
     * Setup command(s) run inside the checkout and hashed into the template name.
     * Array entries run as separate cached build steps.
     */
    setupCommand?: string | string[];
    /**
     * Extra environment for the build, available to every build step
     * including {@link RepoTemplateOptions.setupCommand}. Use it for the
     * credentials a setup command needs (registry tokens, private index
     * URLs) so the build reaches the same state a runtime setup would.
     *
     * Hashed into the template name (keys and values), because env that
     * changes what setup installs changes the image just as the setup command
     * does. Rotating a value therefore forces a rebuild — put credentials
     * that rotate often in {@link RepoTemplateOptions.getRepositoryAccess}
     * instead, which is excluded from identity.
     *
     * Values reach the template definition, so they must be short-lived or
     * non-secret.
     */
    buildEnv?: Record<string, string> | (() => Promise<Record<string, string>>);
    /**
     * vCPUs allocated to sandboxes created from this template. Resources are
     * a property of the built template, not of an individual sandbox, so this
     * is hashed into the template name — a resize builds a new template
     * instead of silently reusing one built at the old size. Defaults to the
     * SDK default (2). Account tier caps the maximum.
     */
    cpuCount?: number;
    /**
     * Memory in MB allocated to sandboxes created from this template. Hashed
     * into the template name for the same reason as {@link cpuCount}.
     * Defaults to the SDK default (1024).
     */
    memoryMB?: number;
    /**
     * Absolute parent for the checkout. Created by the build user, so its parent
     * must already be writable by that user. Becomes the build cwd, the runtime
     * cwd, and part of template identity; the repo lands at `<workingDirectory>/<repo>`.
     * Omit to use the base image's working directory for all of the above.
     */
    workingDirectory?: string;
}
/**
 * Identity inputs for a repo template, already resolved. Separate from
 * {@link RepoTemplateOptions} because identity must be computable without
 * awaiting anything, while the clone URL and credential arrive from an
 * async accessor.
 */
export interface RepoTemplateIdentity {
    /** https clone URL. Host is part of the identity. */
    cloneUrl: string;
    /** Resolved head sha. Becomes the template's tag. */
    sha?: string;
    setupCommand?: string | string[];
    buildEnv?: Record<string, string>;
    cpuCount?: number;
    memoryMB?: number;
    workingDirectory?: string;
}
/**
 * Compute the deterministic template ref for a set of repo template inputs
 * without constructing the builder: `mastra-repo-<hash>` named over
 * (clone URL, setup command, build env), tag-qualified with `:sha-<sha>`
 * when the sha is known. Exposed so callers (and proofs) can predict which
 * ref a sandbox will resolve.
 */
export declare function repoTemplateRef(identity: RepoTemplateIdentity): string;
/**
 * Create a sha-tagged repo template spec for `E2BSandbox`.
 *
 * Returns undefined when {@link RepoTemplateOptions.getRepositoryAccess} is
 * absent, which is how a session with no repository asks for no template —
 * so a host can write `template: createRepoTemplate(ctx)` without a
 * conditional.
 *
 * Resolution is deferred: right before the exists-then-build check it
 * resolves the clone URL and credential, resolves the repository's current
 * default-branch head (`git ls-remote`, ~100ms, no clone), and keys the
 * template ref as `mastra-repo-<hash>:sha-<head>` — so a moved default
 * branch produces a fresh tagged build of the SAME template on the next new
 * session (rebuild-in-place), and an unmoved head reuses the existing
 * tagged build. When the head cannot be resolved the ref degrades to the
 * untagged name and the build clones whatever the default branch is at
 * build time.
 *
 * When the build itself fails — inaccessible repo, registry flake — the
 * sandbox falls back to its fallback template and the session's runtime
 * setup performs the full clone, so a broken build never wedges a session.
 */
export declare function createRepoTemplate(options: RepoTemplateOptions): DeferredNamedTemplateSpec | undefined;
/** Result of a {@link refreshRepoTemplate} call. */
export interface RefreshRepoTemplateResult {
    /** Template ref (`name:tag`) that is now current. */
    ref: string;
    /** Whether an up-to-date build already existed or a fresh build ran. */
    action: 'reused' | 'built';
    /** Resolved head sha, when it could be determined. */
    sha?: string;
}
/**
 * Ensure the repo template is built at the repository's current
 * default-branch head, building it (and moving the `current` tag) when it
 * is not. This is the same resolution the lazy sandbox-start path performs
 * — exposed standalone so template warming can be driven externally: call
 * it from a scheduled workflow (cron) or a merge-to-main event handler and
 * the next session boots warm instead of paying the build.
 *
 * The build is awaited; a build failure rejects so callers can observe it.
 * An unresolvable head degrades to the sha-less `name:current` form, same
 * as the lazy path.
 */
export declare function refreshRepoTemplate(options: RepoTemplateOptions, connection?: ConnectionOpts): Promise<RefreshRepoTemplateResult>;
//# sourceMappingURL=repo-template.d.ts.map