@bnbagent/deploy-provider-bnb 0.3.0

package/src/index.ts

@@ -0,0 +1,591 @@
+/**
+ * @bnbagent/deploy-provider-bnb — the BNB Chain trial-platform provider.
+ *
+ * Runtime: **bnb/trial** (the managed free-trial service, bnbagent-api). Unlike
+ * aws/azure this provider talks to a PLATFORM over plain HTTPS — you bring no
+ * cloud credentials; GitHub device-flow login is the only auth. The platform
+ * deploys to its own AWS account (48h testnet trial) and exposes the agent
+ * through its gateway.
+ *
+ * Deliberately mechanics-only: business gates that belong to the caller
+ * (trial terms, campaign windows, wallet warnings in bnbagent-studio) stay
+ * OUT of this provider — it maps the CloudProvider lifecycle onto the
+ * platform's HTTP API (bnbagent-api docs/client-integration.md) and nothing else.
+ *
+ * ★ All platform knowledge stays inside this package; core is unaware of it.
+ */
+import type {
+  AgentListing,
+  CloudProvider,
+  Context,
+  DeploymentSpec,
+  DeployResult,
+  Status,
+} from "@bnbagent/deploy-core";
+import { artifactReadinessIssues } from "@bnbagent/deploy-core";
+import { apiUrl, authedRequest, publicRequest, sameOrigin, envApiToken, BnbApiError } from "./client.ts";
+import { loadSession, saveSession, clearSession } from "./session.ts";
+import { shipZipArtifact } from "./artifact.ts";
+import { shipImageArtifact } from "./image.ts";
+import { initCmd } from "./init.ts";
+import type {
+  AccountInfo,
+  AgentInfo,
+  CampaignStatus,
+  DeploymentAccepted,
+  DeploymentStatus,
+  DevicePending,
+  DeviceStart,
+  TokenPair,
+  TrialStatus,
+} from "./api-types.ts";
+import { agentIdOf } from "./api-types.ts";
+
+const DEFAULT_RUNTIME = "trial";
+const SUPPORTED_RUNTIMES = [DEFAULT_RUNTIME];
+
+/** Platform slug rule (per-tenant agent name). */
+const SLUG_RE = /^[a-z][a-z0-9-]{1,40}$/;
+
+function resolveProviderRuntime(ctx: Context): string {
+  const runtime = ctx.runtime ?? DEFAULT_RUNTIME;
+  if (SUPPORTED_RUNTIMES.includes(runtime)) return runtime;
+  throw new Error(
+    `Unknown runtime 'bnb/${runtime}'. Available: ${SUPPORTED_RUNTIMES.map((r) => `bnb/${r}`).join(", ")}.`,
+  );
+}
+
+/** Map both agent states (provisioning/updating/…) and deployment states (queued/deploying/…). */
+function mapState(state: string | undefined): Status["state"] {
+  switch (state) {
+    case "ready":
+      return "running";
+    case "queued":
+    case "deploying":
+    case "provisioning":
+    case "updating":
+      return "deploying";
+    case "failed":
+      return "failed";
+    case "reclaiming":
+    case "deleted":
+      return "stopped";
+    default:
+      return "unknown";
+  }
+}
+
+/** The platform stores deploy issues as {level,code,message} objects OR plain strings. */
+function formatIssues(issues: unknown): string {
+  if (!Array.isArray(issues) || issues.length === 0) return "";
+  const lines = issues.map((i) =>
+    typeof i === "string"
+      ? i
+      : i && typeof i === "object"
+        ? [(i as any).code, (i as any).message].filter(Boolean).join(": ") || JSON.stringify(i)
+        : String(i),
+  );
+  return `\n  ${lines.join("\n  ")}`;
+}
+
+/** Slug is validated only in validate(); encode it defensively on every path build. */
+function slugPath(id: string): string {
+  return encodeURIComponent(id);
+}
+
+/**
+ * The HARD spec contract for bnb/trial. validate() reports these early;
+ * deploy() re-asserts UNCONDITIONALLY — --force / skipValidation only skip the
+ * operational gates (sign-in/campaign), never the platform contract. All
+ * checks run BEFORE the artifact upload, so a doomed deploy costs nothing.
+ */
+function specContractIssues(spec: DeploymentSpec, ctx: Context): string[] {
+  const issues: string[] = [];
+  try {
+    resolveProviderRuntime(ctx);
+  } catch (e) {
+    issues.push((e as Error).message);
+  }
+  try {
+    apiUrl(ctx); // the platform endpoint is a hard prerequisite (no localhost default)
+  } catch (e) {
+    issues.push((e as Error).message);
+  }
+  if (!SLUG_RE.test(spec.name)) {
+    issues.push(
+      `The trial platform requires a slug-style name (^[a-z][a-z0-9-]{1,40}$) — got "${spec.name}".`,
+    );
+  }
+  if (spec.type === "zip") {
+    if (!spec.dist) issues.push('deploy.dist is required for bnb/trial (type = "zip").');
+    const entryProblem = entrypointIssue(spec);
+    if (entryProblem) issues.push(entryProblem);
+  } else if (spec.type === "image") {
+    if (!spec.image) issues.push('deploy.image is required for type = "image".');
+  }
+  // container: the Dockerfile is resolved at deploy time (same rules as aws —
+  // this tool never generates one). NOTE: the platform pins artifact type per
+  // slug — zip↔image on an existing slug is a 409 (deploy.artifact_type_immutable).
+  if (spec.secrets?.refs && Object.keys(spec.secrets.refs).length > 0) {
+    issues.push(
+      "[secrets] refs (secret://…) reference YOUR cloud's secret store — the trial platform " +
+        "can't read it. Use secrets.envFile instead (values travel TLS-encrypted to the platform).",
+    );
+  }
+  return issues;
+}
+
+function assertSpecContract(spec: DeploymentSpec, ctx: Context): void {
+  const issues = specContractIssues(spec, ctx);
+  if (issues.length > 0) throw new Error(issues.join("\n"));
+}
+
+/**
+ * A deleted slug is permanently retired by the platform — a deploy against it
+ * is doomed AFTER the artifact upload. Cheap GET first so validate reports it
+ * and deploy fails before shipping bytes. Returns undefined when the slug is
+ * fresh/live or when the check itself can't run (those errors surface elsewhere).
+ */
+async function slugRetiredIssue(name: string, ctx: Context): Promise<string | undefined> {
+  const retired = `The slug '${name}' was deleted and is permanently retired by the platform — deploys to it will always fail.`;
+  try {
+    const agent: AgentInfo = await authedRequest(ctx, "GET", `/v1/agents/${slugPath(name)}`);
+    if (agent.state === "deleted" || agent.state === "reclaiming") return retired;
+  } catch (e) {
+    if (e instanceof BnbApiError && (e.status === 410 || e.code === "agent.deleted")) return retired;
+    // 404 = fresh slug; anything else (auth/network) is another gate's job.
+  }
+  return undefined;
+}
+
+function entrypointIssue(spec: DeploymentSpec): string | undefined {
+  const e = spec.entrypoint;
+  if (!e) return undefined; // config.ts enforces presence for zip
+  if (e.includes("/") || e.includes("\\")) {
+    return (
+      `deploy.entrypoint "${e}" must be a ROOT-LEVEL file in the bundle — the trial ` +
+      `platform resolves it at the zip root (move the file up, or adjust your packaging).`
+    );
+  }
+  // The PLATFORM's exact rule (api ENTRYPOINT_RE): [A-Za-z0-9._-] name + a runtime
+  // extension. A looser local check would let e.g. "my agent.py" fail only AFTER
+  // the artifact upload — a doomed deploy must cost nothing.
+  if (!/^[A-Za-z0-9._-]+\.(js|mjs|cjs|py)$/.test(e)) {
+    return (
+      `deploy.entrypoint "${e}" is not a valid trial-platform entrypoint — letters/digits/._- only, ` +
+      `ending in .py (Python) or .js/.mjs/.cjs (Node).`
+    );
+  }
+  return undefined;
+}
+
+/** Structured trial status (GET /v1/account/trial) — the gate orchestrators read before offering a deploy. */
+export async function getTrialStatus(ctx: Context): Promise<TrialStatus> {
+  return authedRequest(ctx, "GET", "/v1/account/trial");
+}
+
+const bnbProvider: CloudProvider = {
+  name: "bnb",
+
+  capabilities() {
+    return {
+      artifactModes: ["zip", "container", "image"],
+      supportsSecrets: true, // values ride the deploy request (TLS); platform injects
+      supportsSecretRefs: false, // refs point at YOUR cloud's store — rejected by contract
+      supportsLogs: true,
+      supportsOAuth: true, // buyer invoke-client plane for A2A/MCP (`clients`)
+      supportsDestroy: true,
+      supportsToken: true, // bnbk_ platform API tokens (`token` + BNBAGENT_API_TOKEN)
+      supportsTrial: true,
+      supportsList: true,
+      supportsInit: true,
+    };
+  },
+
+  /** Account-level inventory (GET /v1/agents). */
+  async list(ctx: Context): Promise<AgentListing[]> {
+    const res = (await authedRequest(ctx, "GET", "/v1/agents")) as { agents?: AgentInfo[] } | AgentInfo[];
+    const agents = Array.isArray(res) ? res : (res.agents ?? []);
+    return agents.map((a) => ({
+      id: a.slug,
+      state: mapState(a.state),
+      nativeState: a.state,
+      ...(a.invoke_url ? { endpoint: { kind: "url" as const, value: a.invoke_url } } : {}),
+      ...(a.protocol ? { protocol: a.protocol } : {}),
+      managed: true, // everything under this account went through the platform API
+    }));
+  },
+
+  /** Environment diagnosis: is there a working platform auth path? */
+  async doctor(ctx: Context): Promise<{ level: "info" | "warn" | "error"; code: string; message: string }[]> {
+    if (envApiToken()) return [{ level: "info", code: "auth.ok", message: "BNBAGENT_API_TOKEN is set (CI bearer)." }];
+    const session = await loadSession();
+    if (!session) {
+      return [{ level: "error", code: "auth.signed_out", message: "No session and no BNBAGENT_API_TOKEN — run `bnbagent-deploy login`." }];
+    }
+    return [{ level: "info", code: "auth.ok", message: `Session present (minted against ${session.apiUrl}).` }];
+  },
+
+  /** Scaffold an agent-deploy.toml pointed at the trial platform (no agent code). */
+  init(ctx: Context): Promise<void> {
+    return initCmd(ctx);
+  },
+
+  /** GitHub device-flow sign-in (no cloud credentials, no client secret). */
+  async login(ctx: Context): Promise<void> {
+    const base = apiUrl(ctx);
+    ctx.logger.step(`Signing in to the trial platform (${base})…`);
+    const start: DeviceStart = await publicRequest(base, "POST", "/v1/auth/device/start");
+    ctx.logger.info(
+      `Open ${start.verification_uri} in a browser and enter the code: ${start.user_code}`,
+    );
+    let interval = Math.max(Number(start.interval) || 5, 1);
+    const deadline = Date.now() + (Number(start.expires_in) || 900) * 1000;
+    while (Date.now() < deadline) {
+      await Bun.sleep(interval * 1000);
+      const res: TokenPair | DevicePending = await publicRequest(base, "POST", "/v1/auth/device/poll", {
+        json: { device_code: start.device_code },
+      });
+      if ("access_token" in res && res.access_token) {
+        await saveSession({ apiUrl: base, access_token: res.access_token, refresh_token: res.refresh_token });
+        ctx.logger.success("Signed in — session saved to ~/.bnbagent-deploy/bnb/ (mode 0600).");
+        return;
+      }
+      if ("status" in res && res.status === "slow_down") interval += 5;
+      // authorization_pending → keep polling
+    }
+    throw new Error("Device-flow sign-in timed out — run `bnbagent-deploy login` again.");
+  },
+
+  /** Show the signed-in identity (GitHub login) + trial clock. */
+  async whoami(ctx: Context): Promise<void> {
+    const session = await loadSession();
+    const viaToken = envApiToken();
+    if (!session && !viaToken) {
+      ctx.logger.info("Not signed in to the trial platform (run `bnbagent-deploy login`).");
+      return;
+    }
+    try {
+      const account: AccountInfo = await authedRequest(ctx, "GET", "/v1/account");
+      const trial: TrialStatus = await authedRequest(ctx, "GET", "/v1/account/trial");
+      const target = viaToken ? `${apiUrl(ctx)} (via BNBAGENT_API_TOKEN)` : session!.apiUrl;
+      const who = account.login ? ` as ${account.login} (GitHub)` : "";
+      const extra =
+        trial.case === "active"
+          ? ` — trial active, ${Math.max(0, Math.round((trial.remaining_seconds ?? 0) / 3600))}h left`
+          : ` — trial ${trial.case}`;
+      ctx.logger.info(`Signed in to ${target}${who}${extra}.`);
+      if (typeof account.agents === "number") {
+        ctx.logger.info(`Agents on this account: ${account.agents}.`);
+      }
+    } catch (e) {
+      if (e instanceof BnbApiError && e.status === 401) {
+        ctx.logger.info("Session expired — run `bnbagent-deploy login` again.");
+        return;
+      }
+      throw e;
+    }
+  },
+
+  /** Revoke the platform session (best-effort), then forget the local one. */
+  async logout(ctx: Context): Promise<void> {
+    const session = await loadSession();
+    if (session) {
+      // Best-effort server-side revocation — the local delete is the part that
+      // must succeed; an unreachable platform must not block signing out.
+      try {
+        await authedRequest(ctx, "DELETE", "/v1/auth/session");
+      } catch {
+        ctx.logger.debug("[bnb] server-side session revoke failed (continuing with local sign-out)");
+      }
+    }
+    const removed = await clearSession();
+    ctx.logger.success(removed ? "Signed out (local session removed)." : "Already signed out.");
+  },
+
+  /** Spec + sign-in + campaign gates (business gates like trial terms stay with the caller). */
+  async validate(spec, ctx) {
+    const issues: { level: "info" | "warn" | "error"; code: string; message: string; hint?: string }[] = [];
+    // apiUrl is a hard part of the contract (nothing works without it), so it
+    // rides in specContractIssues — same as aws/azure report ALL contract issues
+    // at once, and deploy's assertSpecContract surfaces the SAME code (not a
+    // generic provider.error). Resolve it once here for the campaign check.
+    for (const message of specContractIssues(spec, ctx)) {
+      issues.push({ level: "error", code: "spec.invalid", message });
+    }
+    let base: string | undefined;
+    try {
+      base = apiUrl(ctx);
+    } catch {
+      /* already reported via specContractIssues */
+    }
+    const session = await loadSession();
+    const apiToken = envApiToken(); // CI bearer replaces the session entirely
+    if (!session && !apiToken) {
+      issues.push({
+        level: "error",
+        code: "auth.signed_out",
+        message: "Not signed in to the trial platform.",
+        hint: "Run: bnbagent-deploy login (CI: set BNBAGENT_API_TOKEN)",
+      });
+    } else if (!apiToken && session && base && session.apiUrl && !sameOrigin(session.apiUrl, base)) {
+      // Parity with authedRequest's host binding: a token minted against
+      // platform A is never sent to platform B — surface that here instead of
+      // letting a green validate die on deploy's first authenticated call.
+      issues.push({
+        level: "error",
+        code: "auth.host_mismatch",
+        message: `Signed in against ${session.apiUrl}, but this spec targets ${base} — authenticated calls would be refused.`,
+        hint: "Run: bnbagent-deploy login (against the current apiUrl), or fix [bnb] apiUrl / BNBAGENT_API_URL.",
+      });
+    }
+    try {
+      if (!base) throw new Error("no endpoint");
+      const campaign: CampaignStatus = await publicRequest(base, "GET", "/v1/campaign");
+      if (campaign.campaign_active === false) {
+        issues.push({
+          level: "error",
+          code: "campaign.ended",
+          message: "The free-trial campaign is closed to NEW deploys (existing agents keep running).",
+        });
+      }
+    } catch {
+      issues.push({
+        level: "info",
+        code: "campaign.unknown",
+        message: `Could not check the campaign status at ${base} (continuing).`,
+      });
+    }
+    // Doomed-deploy precheck (needs working auth): a deleted slug is
+    // retired forever — deploy would fail AFTER uploading the artifact.
+    if ((apiToken || session) && base && !issues.some((i) => i.code === "auth.host_mismatch")) {
+      const retired = await slugRetiredIssue(spec.name, ctx);
+      if (retired) {
+        issues.push({
+          level: "error",
+          code: "agent.retired",
+          message: retired,
+          hint: "Pick a new agent name (slug) in agent-deploy.toml.",
+        });
+      }
+    }
+    // Parity with deploy's pre-cloud gates: dist/entrypoint existence (warn —
+    // `validate → pack → deploy` is a legitimate order) + escaping symlinks (error).
+    issues.push(...(await artifactReadinessIssues(spec, ctx.baseDir)));
+    return { ok: !issues.some((i) => i.level === "error"), issues };
+  },
+
+  /** zip/image → upload/push → create deployment → poll to ready. Secrets ride the deploy request (TLS). */
+  async deploy(spec: DeploymentSpec, ctx: Context): Promise<DeployResult> {
+    assertSpecContract(spec, ctx); // the platform contract holds even under --force
+    const base = apiUrl(ctx);
+    if (ctx.dryRun) {
+      const what =
+        spec.type === "zip"
+          ? `zip ${spec.dist} and upload it to ${base}`
+          : spec.type === "container"
+            ? `docker-build ${spec.path ?? "."} and push it to the platform's brokered registry`
+            : `push image ${spec.image} to the platform's brokered registry`;
+      ctx.logger.info(
+        `[dry-run] would ${what}, then deploy trial agent '${spec.name}'` +
+          `${spec.protocol && spec.protocol !== "HTTP" ? ` (protocol ${spec.protocol})` : ""}. No changes made.`,
+      );
+      return { id: spec.name, outputs: {} };
+    }
+
+    // One pre-ship GET answers two things: a retired slug is doomed (fail BEFORE
+    // shipping bytes), and a live agent means this deploy is an update.
+    let preexisting = false;
+    try {
+      const agent: AgentInfo = await authedRequest(ctx, "GET", `/v1/agents/${slugPath(spec.name)}`);
+      if (agent.state === "deleted" || agent.state === "reclaiming") {
+        throw new Error(
+          `The slug '${spec.name}' was deleted and is permanently retired by the platform — deploys to it will always fail.\n` +
+            `  Pick a new agent name (slug) in agent-deploy.toml.`,
+        );
+      }
+      preexisting = true;
+    } catch (e) {
+      if (e instanceof BnbApiError && (e.status === 410 || e.code === "agent.deleted")) {
+        throw new Error(
+          `The slug '${spec.name}' was deleted and is permanently retired by the platform.\n  Pick a new agent name (slug).`,
+        );
+      }
+      if (!(e instanceof BnbApiError)) throw e; // the retired-slug Error above
+      // 404 = fresh slug; other API/network errors are the next call's problem.
+    }
+
+    const shipped = spec.type === "zip" ? await shipZipArtifact(spec, ctx) : await shipImageArtifact(spec, ctx);
+    // Deterministic idempotency key (slug + content hash): re-running a deploy
+    // of IDENTICAL content dedupes to the same deployment platform-side instead
+    // of minting a new one (matches the studio semantic).
+    const contentKey = "checksum" in shipped ? shipped.checksum : shipped.digest;
+
+    ctx.logger.step(`Deploying trial agent '${spec.name}'…`);
+    const body: Record<string, unknown> = { artifact_id: shipped.artifactId };
+    // entrypoint is a ZIP concept (picks the managed runtime); ignored for images.
+    if (spec.type === "zip" && spec.entrypoint) body.entrypoint = spec.entrypoint;
+    if (spec.protocol && spec.protocol !== "HTTP") body.protocol = spec.protocol;
+    if (ctx.secrets && Object.keys(ctx.secrets).length > 0) {
+      body.secrets = ctx.secrets; // values TLS-only; never logged
+      ctx.logger.info(`Sending ${Object.keys(ctx.secrets).length} secret(s) with the deploy (values hidden).`);
+    }
+    const accepted: DeploymentAccepted = await authedRequest(
+      ctx,
+      "POST",
+      `/v1/agents/${slugPath(spec.name)}/deployments`,
+      { json: body, headers: { "idempotency-key": `${spec.name}:${contentKey}` } },
+    );
+
+    // Poll to a terminal state (the platform's worker deploys asynchronously).
+    // Tolerate a few transient GET failures so one network blip doesn't abort a
+    // deploy that is actually progressing on the platform.
+    const statusPath = accepted.status_url ?? `/v1/deployments/${accepted.deployment_id}`;
+    const deadline = Date.now() + 10 * 60_000;
+    let last: DeploymentStatus | undefined;
+    let transientErrors = 0;
+    while (Date.now() < deadline) {
+      await Bun.sleep(3000);
+      try {
+        last = await authedRequest(ctx, "GET", statusPath);
+      } catch (e) {
+        if (e instanceof BnbApiError && e.status === 0 && ++transientErrors <= 5) {
+          ctx.logger.debug(`[bnb] status poll transient error (${transientErrors}/5): ${e.message}`);
+          continue;
+        }
+        throw e;
+      }
+      transientErrors = 0;
+      const polled = last!; // just assigned in the try above
+      ctx.logger.debug(`[bnb] deployment state: ${polled.state}`);
+      if (polled.state === "ready") break;
+      if (polled.state === "failed") {
+        throw new Error(`Trial deployment failed.${formatIssues(polled.issues)}`);
+      }
+    }
+    if (last?.state !== "ready") {
+      throw new Error("Timed out waiting for the trial deployment (check `bnbagent-deploy status`).");
+    }
+
+    const invokeUrl = last.invoke_url ?? accepted.invoke_url;
+    const endpoint = invokeUrl ? { kind: "url" as const, value: invokeUrl } : undefined;
+    const protocol = last.protocol ?? spec.protocol ?? "HTTP";
+    const agentId = last.agent_id ?? accepted.agent_id;
+    return {
+      id: spec.name,
+      // The platform pins slugs: a pre-existing live agent means this was an update.
+      status: preexisting ? "updated" : "created",
+      ...(endpoint ? { endpoint } : {}),
+      record: {
+        provider: "bnb",
+        runtime: "trial",
+        protocol,
+        packaging: spec.type,
+        ...(endpoint ? { endpoint } : {}),
+        deploymentId: accepted.deployment_id,
+        ...(agentId ? { agentId } : {}),
+        ...("imageUri" in shipped && shipped.imageUri ? { imageUri: shipped.imageUri } : {}),
+        logsUrl: `${base}/v1/agents/${slugPath(spec.name)}/logs`,
+        // A2A/MCP run behind the platform's buyer token plane — the non-secret
+        // auth surface is derivable (client-integration.md §5b), so hand it to
+        // callers instead of making each one re-derive from base + agentId.
+        ...(agentId && (protocol === "A2A" || protocol === "MCP")
+          ? { auth: { tokenUrl: `${base}/v1/oauth/token`, scope: `invoke:${agentId}` } }
+          : {}),
+        lastDeployAt: new Date().toISOString(),
+      },
+      outputs: {
+        Platform: base,
+        ...(last.agent_id ? { AgentId: last.agent_id } : {}),
+        ...(last.protocol ? { Protocol: last.protocol } : {}),
+      },
+      hints: [
+        "The runtime boots on the FIRST invoke; logs stay empty until then.",
+        spec.protocol === "A2A" || spec.protocol === "MCP"
+          ? "Buyers need an invoke client — mint one: bnbagent-deploy clients --new"
+          : 'Test it:        bnbagent-deploy invoke "hello"',
+        "Trial note:     the 48h clock starts at the first successful deploy.",
+      ],
+    };
+  },
+
+  /** The platform's recorded state for this slug. */
+  async status(id: string, ctx: Context): Promise<Status> {
+    try {
+      const agent: AgentInfo = await authedRequest(ctx, "GET", `/v1/agents/${slugPath(id)}`);
+      const state = agent.state ?? "unknown";
+      return {
+        id,
+        state: mapState(state),
+        nativeState: state,
+        ...(agent.invoke_url ? { endpoint: { kind: "url", value: agent.invoke_url } } : {}),
+        ...(agentIdOf(agent) ? { agentId: agentIdOf(agent) } : {}),
+      };
+    } catch (e) {
+      if (e instanceof BnbApiError && (e.status === 404 || e.status === 410)) {
+        return { id, state: "unknown", detail: "no trial agent found under this slug (not deployed?)" };
+      }
+      throw e;
+    }
+  },
+
+  /** HTTP-protocol agents only (A2A/MCP go through the buyer token plane). */
+  async invoke(id: string, payload: string, ctx: Context): Promise<string> {
+    ctx.logger.step(`Invoking ${id} (via the platform gateway)…`);
+    // Forward the payload VERBATIM (like the AWS provider + the platform contract)
+    // — don't re-parse: a raw --payload string must not crash with a SyntaxError.
+    return authedRequest(ctx, "POST", `/v1/agents/${slugPath(id)}/invoke`, {
+      bytes: new TextEncoder().encode(payload),
+      headers: { "content-type": "application/json" },
+      text: true,
+    });
+  },
+
+  /** Recent runtime logs via the platform (empty until the first invoke). */
+  async *logs(id: string, ctx: Context): AsyncIterable<string> {
+    const raw: string = await authedRequest(ctx, "GET", `/v1/agents/${slugPath(id)}/logs`, { text: true });
+    // Tolerate a JSON envelope ({logs|text|output}: "…") — the platform serves
+    // plain text today, but an envelope must not be dumped as one "log line".
+    let text = raw;
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("{")) {
+      try {
+        const env = JSON.parse(trimmed) as Record<string, unknown>;
+        const inner = env.logs ?? env.text ?? env.output;
+        if (typeof inner === "string") text = inner;
+      } catch {
+        /* not JSON after all — keep the raw text */
+      }
+    }
+    if (!text.trim()) {
+      ctx.logger.info("No logs yet — the runtime boots on the FIRST invoke after a deploy.");
+      return;
+    }
+    for (const line of text.split("\n")) if (line) yield line;
+  },
+
+  /** Delete the trial agent. ⚠ The slug is permanently retired by the platform. */
+  async destroy(id: string, ctx: Context): Promise<void> {
+    ctx.logger.warn(
+      `Trial slugs are retired forever: after this delete, '${id}' cannot be redeployed — pick a new name.`,
+    );
+    try {
+      await authedRequest(ctx, "DELETE", `/v1/agents/${slugPath(id)}`);
+    } catch (e) {
+      // Idempotent destroy: an already-deleted/never-deployed slug is success,
+      // not an error (re-running destroy must not fail the second time).
+      if (e instanceof BnbApiError && (e.status === 404 || e.status === 410)) {
+        ctx.logger.info(`No trial agent under '${id}' — nothing to delete.`);
+        return;
+      }
+      throw e;
+    }
+    ctx.logger.success(`Delete accepted — the platform reclaims '${id}' asynchronously.`);
+  },
+};
+
+export default bnbProvider;
+export { bnbProvider };
+// bnb-specific CLI extras (deliberately NOT on the CloudProvider contract —
+// they would leak platform concepts into core), mirroring aws's cognitoCmd.
+export { clientsCmd, tokenCmd, trialCmd } from "./extras.ts";

package/src/init.ts

@@ -0,0 +1,55 @@
+/**
+ * `bnbagent-deploy init` for bnb/trial — write an agent-deploy.toml pointed at
+ * the trial platform. Pure local file generation; scaffolds NO agent code
+ * (same rule as every provider's init).
+ */
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import type { Context } from "@bnbagent/deploy-core";
+
+const ask = (q: string): string => (prompt(q) ?? "").trim();
+
+/** Fit a directory name into the platform slug rule (^[a-z][a-z0-9-]{1,40}$). */
+function slugify(raw: string): string {
+  let s = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (!/^[a-z]/.test(s)) s = `a-${s}`;
+  return s.slice(0, 41) || "my-agent";
+}
+
+export async function initCmd(ctx: Context): Promise<void> {
+  const file = join(ctx.baseDir, "agent-deploy.toml");
+  if (existsSync(file)) {
+    throw new Error(`agent-deploy.toml already exists in ${ctx.baseDir} — edit it, or remove it to re-init.`);
+  }
+
+  const defaultName = slugify(basename(ctx.baseDir));
+  const name = process.stdin.isTTY ? slugify(ask(`Agent name (slug) [${defaultName}]: `) || defaultName) : defaultName;
+  const apiUrl = process.stdin.isTTY ? ask("Trial platform URL (https://…): ") : "";
+
+  const toml = `name = "${name}"
+
+[deploy]
+target = "bnb/trial"
+type = "zip"                     # zip (managed runtime) · container/image (BYO Docker)
+dist = "deployment_package"
+entrypoint = "main.py"           # .py → Python · .js/.mjs/.cjs → Node (zip root)
+# protocol = "A2A"               # or "MCP" — buyers then authenticate via the platform token plane
+
+[bnb]
+apiUrl = "${apiUrl || "https://<the-trial-platform-host>"}"
+
+# [env]                          # non-sensitive runtime config (plaintext)
+# MY_FLAG = "1"
+
+# [secrets]                      # values travel TLS-encrypted with the deploy; never bundled
+# envFile = ".env"
+`;
+  await writeFile(file, toml, "utf8");
+  ctx.logger.success(`Wrote ${file}`);
+  if (!apiUrl) ctx.logger.warn("Set [bnb] apiUrl (or BNBAGENT_API_URL) before deploying — there is no default.");
+  ctx.logger.info("Next steps:");
+  ctx.logger.info("  1. bnbagent-deploy login          (GitHub device flow)");
+  ctx.logger.info("  2. bnbagent-deploy pack           (Python zip projects — vendors arm64 deps)");
+  ctx.logger.info("  3. bnbagent-deploy deploy");
+}