@luxorai/agentbox-provider 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+import { CloudBackend, CredStatusSummary, Provider, BoxRecord, AttachKind, BuildAttachOptions, AttachSpec, ProviderModule } from '@madarco/agentbox-provider-sdk';
+export { SDK_API_VERSION } from '@madarco/agentbox-provider-sdk';
+
+/**
+ * Tenki `CloudBackend` — maps the provider-neutral cloud primitives onto the
+ * `@tenkicloud/sandbox` SDK (Firecracker microVMs + pause/resume snapshots).
+ * Composed into a full `Provider` by the provider SDK's `createCloudProvider`.
+ *
+ * Platform shape this backend is built around:
+ *   - Boxes boot from a snapshot id: the base snapshot baked by `agentbox
+ *     prepare --provider tenki`, or a checkpoint snapshot (`req.snapshot`),
+ *     which wins. `backend.provision` gates on `ensureTenkiBaseImage()` (mirrors
+ *     the e2b/hetzner/vercel pattern: `prepare` sidesteps the gate so a cold
+ *     install can bootstrap).
+ *   - The SDK's high-level `Session` carries both the control-plane handle and
+ *     a per-session data plane (`run`, `readFile`/`writeFile`/`fs.*`). We
+ *     resolve a fresh `Session` per op via `client.get(sessionId)` — the CLI is
+ *     a short-lived process per command, matching e2b's `Sandbox.connect`.
+ *   - `CloudHandle.sandboxId` IS the Tenki session id.
+ *   - Comms are ConnectRPC + a websocket data plane (no SSH for exec/files);
+ *     interactive attach uses `session.ssh()`, wired by `buildTenkiAttach`.
+ *   - Preview URLs come from `session.exposePort(port)` — public HTTPS, no
+ *     header token (same shape as e2b/vercel).
+ *   - `session.pause()` / `session.resume()` give free pause/resume;
+ *     `createSnapshotAndWait` is the reusable, id-addressed checkpoint
+ *     primitive (the provider overrides `checkpoint` in index.ts to store the
+ *     snapshot id, matching vercel/e2b).
+ */
+
+declare const tenkiBackend: CloudBackend;
+
+/**
+ * Tenki env auto-loader. The `@tenkicloud/sandbox` SDK reads `TENKI_AUTH_TOKEN`
+ * from `process.env` (and we honor optional `TENKI_BASE_URL` /
+ * `TENKI_GATEWAY_ADDRESS` overrides for non-default / self-hosted control
+ * planes). We seed those from `~/.agentbox/secrets.env` — the store AgentBox's
+ * built-in cloud providers use — so the SDK Just Works after a one-time setup.
+ *
+ * Lookup order (first wins; process.env is never overwritten):
+ *   1. `process.env` (already set in the shell).
+ *   2. `~/.agentbox/secrets.env` — written by the credential prompt.
+ *
+ * `TENKI_API_TOKEN` is accepted as an alias for `TENKI_AUTH_TOKEN`.
+ *
+ * Project-level `.env` / `.env.local` are intentionally NOT consulted: those
+ * files belong to the app code being developed. Put host credentials in
+ * `~/.agentbox/secrets.env` (or the shell env).
+ *
+ * Only TENKI-prefixed keys are imported; the rest of the file is left alone.
+ * Idempotent and side-effect-free after the first call.
+ */
+declare function ensureTenkiEnvLoaded(): void;
+/**
+ * Force a re-read of `~/.agentbox/secrets.env`. Used by the interactive
+ * credential flow after it persists the token, so the same process can pick it
+ * up without a restart.
+ */
+declare function reloadTenkiEnv(): void;
+
+/**
+ * Atomic writer for the managed keys this provider owns in
+ * `~/.agentbox/secrets.env` — the same store AgentBox's built-in cloud providers
+ * use, so a Tenki token sits alongside the rest and `agentbox doctor` finds it.
+ *
+ * The provider SDK does not re-export AgentBox's internal secrets writer, so
+ * this is a local implementation of the same contract: strip any prior values
+ * for the keys we manage, append the new ones, and write through a temp file +
+ * rename at mode 0600 so a concurrent reader never sees a half-written file and
+ * the token is never briefly world-readable.
+ */
+
+/**
+ * Outcome of a non-interactive credential write. `status` reflects the store
+ * *after* the attempt, so a caller can report `configured` without a second read.
+ * Mirrors the shape AgentBox's `providerModule.setCredentials` returns.
+ */
+interface CredSetResult {
+    ok: boolean;
+    /** One-line failure reason when `ok` is false (e.g. a rejected token). */
+    error?: string;
+    status: CredStatusSummary;
+}
+
+/**
+ * Interactive Tenki credential setup. Single mode — paste a workspace auth
+ * token (`tk_…`) from the Tenki dashboard. Persists to
+ * `~/.agentbox/secrets.env` (the canonical store, matching daytona / hetzner /
+ * vercel / e2b).
+ *
+ * Non-interactive callers (no TTY): silent no-op, so scripted/CI runs surface
+ * the SDK's own "not configured" error instead of hanging on a prompt.
+ */
+
+interface EnsureTenkiCredentialsOptions {
+    /** Re-prompt even when valid credentials are already present. */
+    force?: boolean;
+}
+declare function ensureTenkiCredentials(opts?: EnsureTenkiCredentialsOptions): Promise<void>;
+/**
+ * Non-interactive credential write — the headless path an API driver uses,
+ * bypassing the TTY-gated `ensureTenkiCredentials` prompts. Extracts the `token`
+ * field, persists it, and returns a normalized result without echoing the secret.
+ */
+declare function setTenkiCredentials(fields: Record<string, string>): CredSetResult;
+declare function secretsPath(): string;
+interface TenkiCredStatus {
+    auth: 'token' | 'none';
+    token?: string;
+    source: 'env' | 'secrets.env' | 'none';
+}
+declare function readTenkiCredStatus(): TenkiCredStatus;
+declare function maskKey(value: string): string;
+
+/**
+ * `agentbox prepare --provider tenki` — bake the AgentBox base image, then pin it
+ * as a snapshot so per-box `create` boots ready in seconds.
+ *
+ * ## Shape: builder sandbox, not the template API
+ *
+ * Boot a throwaway session from Tenki's plain `sandbox` base, push the runtime in
+ * over the data plane, run the install with `session.run`, snapshot it, and
+ * record the snapshot id. This is the same shape the built-in Vercel and E2B
+ * providers use, and it sidesteps every constraint the template API imposes:
+ *
+ *   - **Real file upload.** A template build context is Git-only, so a template
+ *     cannot receive host files at all — it would have to reinstall the runtime
+ *     from npm and hope the published version matches the CLI. Over the data
+ *     plane we ship the *running CLI's own* `ctl.cjs` and shims via the provider
+ *     SDK's `resolveSharedRuntimeAsset`, which is the intended version-locking
+ *     mechanism.
+ *   - **Bash.** Template steps run under `sh -lc` (dash), where `pipefail` is a
+ *     fatal bashism. `session.run(['bash', '-c', …])` — what the backend already
+ *     uses for every exec — gives us bash 5.2.
+ *   - **Per-step error attribution.** Each install step is its own exec with a
+ *     name, so a failure says which step broke instead of failing somewhere
+ *     inside one opaque script.
+ *   - **No template-API restrictions**: no required `setup_script`, no
+ *     single-default-run-step projection, no Git-context rule.
+ *
+ * Boxes then boot with `create({ snapshotId })` — the same path the
+ * checkpoint-restore flow already exercises.
+ */
+
+/**
+ * A provider-neutral runtime asset, taken from the *running CLI* and pushed in
+ * over the data plane.
+ */
+interface PrepareAsset {
+    /** Basename in the CLI's `runtime/_shared/`. */
+    shared: string;
+    /** Absolute destination inside the box. */
+    dest: string;
+    /** Octal mode applied on install. */
+    mode: string;
+}
+/**
+ * `shared` names must exist in the SDK's `SHARED_RUNTIME_ASSETS`; never vendor
+ * copies of these — resolving them from the CLI is what keeps the baked
+ * `agentbox-ctl` version-locked to the host driving the box.
+ *
+ * The `gh` / `git` / `ntn` / `linear` entries are deliberately *shims*: they land
+ * in `/usr/local/bin`, which precedes `/usr/bin` on PATH, so an agent running
+ * `git push` reaches the host relay (which holds the credentials) rather than the
+ * real binary. That indirection is why a box needs no credentials of its own.
+ */
+declare const PREPARE_ASSETS: readonly PrepareAsset[];
+/** Staging path an asset is uploaded to before being installed into place. */
+declare function stagedAssetPath(shared: string): string;
+/** One install step, run as its own exec so a failure names the step. */
+interface PrepareStep {
+    name: string;
+    command: string;
+    /** Run as root (`privileged`). Unset means the box user. */
+    root?: boolean;
+    /** Per-step attempt timeout; the backend default (5 min) is too short for npm. */
+    timeoutMs?: number;
+}
+/**
+ * The install plan, as discrete steps. Pure, so the whole recipe is assertable
+ * offline — a mistake here otherwise only surfaces minutes into a live bake.
+ *
+ * `bash -c` is guaranteed (the backend's exec always uses it), so `pipefail` and
+ * heredocs are safe here, unlike in a template build step.
+ */
+declare function buildInstallPlan(): PrepareStep[];
+interface PrepareTenkiOptions {
+    name?: string;
+    hostWorkspace?: string;
+    /** Rebake even when a base snapshot is already recorded. */
+    force?: boolean;
+    /** Tenki base-image id the builder boots from (default: the workspace default). */
+    baseImage?: string;
+    /** Tenki workspace to build in (defaults to the token's own scope). */
+    workspaceId?: string;
+    cpuCount?: number;
+    memoryMB?: number;
+    diskSizeGB?: number;
+    onLog?: (line: string) => void;
+}
+interface PrepareTenkiResult {
+    /** The Tenki snapshot id recorded as the base. */
+    snapshotName?: string;
+}
+/**
+ * Build a throwaway HOME containing a *shadow* of `~/.codex`: real directories,
+ * but every regular file replaced by a symlink to the original.
+ *
+ * Why: `stageCodexStaticForUpload` runs `rsync -aL` over `~/.codex`, and `-a`
+ * implies `-D` (recreate devices and specials). Codex leaves a live Unix socket
+ * at `~/.codex/ipc/ipc.sock` whenever it has run, which rsync cannot recreate —
+ * it exits 23 ("partial transfer due to error") and the whole staging throws. The
+ * upstream exclude list doesn't filter specials, so the built-in vercel and e2b
+ * providers fail their entire `prepare` on such a host.
+ *
+ * The shadow skips anything that isn't a directory or regular file, so the socket
+ * simply isn't there to trip over. Symlinks (rather than copies) mean no user data
+ * is duplicated on disk — `rsync -L` reads through them to the originals. We also
+ * omit `auth.json`: the helper excludes it from the tarball anyway, and this way
+ * the token never lands in a temp directory at all.
+ *
+ * Returns null when there is no `~/.codex` to shadow — the caller then stages
+ * normally and the helper reports "nothing to stage".
+ */
+declare function shadowCodexHome(hostHome: string): {
+    home: string;
+    cleanup: () => void;
+} | null;
+declare function prepareTenki(opts?: PrepareTenkiOptions): Promise<PrepareTenkiResult>;
+/** Provider-level binding used by the CLI's `prepare` command. */
+declare const prepareTenkiProvider: NonNullable<Provider['prepare']>;
+
+/**
+ * Persisted record of what `agentbox prepare --provider tenki` has resolved.
+ * Lives at `~/.agentbox/tenki-prepared.json` so the auto-prepare gate
+ * (`ensureTenkiBaseImage()`) and `backend.provision` can resolve the base
+ * image every box boots from.
+ *
+ * Tenki boots a session from a snapshot id.
+ * The "base" recorded here is the ID of the snapshot carrying
+ * the AgentBox runtime (agentbox-ctl, the agents, tmux), captured by
+ * `prepare` from a throwaway builder sandbox. Per-box `create` then boots from
+ * it in seconds.
+ *
+ * Schema versioned so future shape changes can migrate. Only `schema: 2` is
+ * accepted; an older file is refused by `readPreparedState` and simply re-baked.
+ */
+declare const SCHEMA: 2;
+interface PreparedTenkiBase {
+    /** Tenki snapshot id the AgentBox runtime is baked into. `create({ snapshotId })` boots from this. */
+    snapshotId: string;
+    /** Human-readable snapshot label (informational; ids are what we boot from). */
+    snapshotName?: string;
+    /** CLI version that produced this base (informational). */
+    cliVersion?: string;
+    /** Git short SHA of the CLI build (informational). */
+    cliCommit?: string;
+    /** ISO timestamp of prepare completion. */
+    createdAt: string;
+}
+interface PreparedTenkiState {
+    schema: typeof SCHEMA;
+    /** The shared base image ref. Absent until first `agentbox prepare`. */
+    base?: PreparedTenkiBase;
+}
+declare function preparedStatePath(): string;
+declare function readPreparedState(): PreparedTenkiState;
+declare function writePreparedState(state: PreparedTenkiState): void;
+/** Update one field of the state without forcing callers to read/merge/write. */
+declare function updatePreparedState(mutate: (s: PreparedTenkiState) => void): void;
+/**
+ * CURRENT build-context fingerprint for the tenki base. The base is an opaque
+ * Tenki snapshot id, so there is no reproducible host-side fingerprint to diff
+ * against. Returning `undefined` makes the cross-provider freshness nudge
+ * degrade to "can't tell, don't nag" — the same contract the other providers use
+ * when assets can't be resolved.
+ */
+declare function currentTenkiBaseFingerprintLive(): Promise<string | undefined>;
+/**
+ * First-use gate. If no base image is recorded, throw an actionable error
+ * pointing at `agentbox prepare --provider tenki`. Called by
+ * `backend.provision` (so `create` / `claude` trip it but `prepare` itself
+ * does not — same shape as the hetzner / vercel / e2b gates).
+ */
+declare function ensureTenkiBaseImage(): void;
+
+/**
+ * `buildTenkiAttach` — the Tenki provider's override of `Provider.buildAttach`.
+ *
+ * ## Why this shells out to real OpenSSH
+ *
+ * `session.ssh()` is NOT a shell channel: `SSHConnection` is a thin wrapper over
+ * a WebSocket carrying the **raw SSH wire protocol**, exposing only
+ * `read()/write()/close()`. Writing shell commands into it just gets you the
+ * gateway's version banner (`SSH-2.0-Tenki-edge-gateway`) — reaching a shell
+ * means performing the SSH handshake: key exchange, publickey auth, channel
+ * open, PTY request. The data plane is no help either: `session.run` has no
+ * tty/pty option, so there is no interactive path through it.
+ *
+ * So we let the host's `ssh` do the protocol and use our helper purely as the
+ * transport:
+ *
+ *   ssh -o ProxyCommand='node attach-helper.cjs --proxy --session-id <id>' \
+ *       -i <key> -o CertificateFile=<key>-cert.pub -t <user>@<id> <inner cmd>
+ *
+ * Auth is an ephemeral ed25519 key plus a short-lived OpenSSH certificate from
+ * `issueSandboxSSHCert` — which the SDK documents for exactly this
+ * (`<key>-cert.pub` / `-o CertificateFile=`).
+ *
+ * Beyond correctness this gets window-size propagation for free: OpenSSH
+ * forwards SIGWINCH, so tmux tracks terminal resizes. The previous
+ * bridge-the-bytes-ourselves design could not, since `SSHConnection` has no
+ * resize op.
+ *
+ * Detached pre-start keeps its own path (see `--detached` in the helper): it only
+ * needs to CREATE the tmux session, which is a plain non-interactive exec.
+ */
+
+declare function buildTenkiAttach(box: BoxRecord, kind: AttachKind, opts?: BuildAttachOptions): Promise<AttachSpec>;
+
+/**
+ * The Tenki sandbox provider. A thin `CloudBackend` over the
+ * `@tenkicloud/sandbox` SDK, composed via the provider SDK's
+ * `createCloudProvider` for everything provider-agnostic (workspace seeding,
+ * ctl launch, state, relay polling).
+ *
+ * Three capabilities are overridden on top of the cloud scaffold:
+ *   - `prepare`     — bake the AgentBox base snapshot in the Tenki workspace
+ *                     (`agentbox prepare --provider tenki`).
+ *   - `buildAttach` — the host's own `ssh` client, pointed at the session
+ *                     through a `ProxyCommand` that bridges stdio to
+ *                     `session.ssh()`. Requires OpenSSH on the host.
+ *   - `checkpoint`  — store the Tenki snapshot id in the manifest so restore
+ *     boots from it (`createSnapshotAndWait` returns an id-addressed snapshot).
+ *
+ * `launchDockerd: true` — in-box Docker works on Tenki: verified on a live
+ * microVM with cgroup2 and native overlay2 (not the vfs fallback), brought up by
+ * the shared `agentbox-dockerd-start` launcher. Containers need no nested
+ * virtualization, so the absence of /dev/kvm doesn't matter. The daemon is
+ * started by the same idempotent bootstrap kick used on create and resume.
+ */
+
+/** The AgentBox provider name. `agentbox create --provider tenki` matches on this exactly. */
+declare const PROVIDER_NAME = "tenki";
+declare const tenkiProvider: Provider;
+/** Uniform surface the CLI provider loader resolves this package through. */
+declare const providerModule: ProviderModule;
+
+export { type EnsureTenkiCredentialsOptions, PREPARE_ASSETS, PROVIDER_NAME, type PrepareAsset, type PrepareStep, type PrepareTenkiOptions, type PrepareTenkiResult, type PreparedTenkiBase, type PreparedTenkiState, type TenkiCredStatus, buildInstallPlan, buildTenkiAttach, currentTenkiBaseFingerprintLive, ensureTenkiBaseImage, ensureTenkiCredentials, ensureTenkiEnvLoaded, maskKey, prepareTenki, prepareTenkiProvider, preparedStatePath, providerModule, readPreparedState, readTenkiCredStatus, reloadTenkiEnv, secretsPath, setTenkiCredentials, shadowCodexHome, stagedAssetPath, tenkiBackend, tenkiProvider, updatePreparedState, writePreparedState };