@tonbo/cli 0.3.4 → 0.4.0

package/README.md

@@ -78,12 +78,29 @@ tonbo run "Reply with exactly READY."
 
 Choose `Use an existing agent` during `init` when the Agent already exists. `tonbo agent create <name>` and `tonbo agent use <name-hostname-or-id>` remain explicit automation and recovery commands.
 
+Every Agent has a home region, chosen when it is created and never changed afterwards. Its Deployments, Sessions and files stay in that region. The hostname and the SSH destination are the same in every region. Name the region with `--region`; `tonbo region list` shows the regions that accept new resources (`allocation_enabled`). Without `--region`, Tonbo uses the only region that accepts new Agents. When several do, interactive `init` and `agent create` ask which one to use, and a non-interactive request without `--region` is refused with HTTP 400 (`region is required`). `init --region` applies only to an Agent that interactive `init` creates:
+
+```console
+tonbo region list
+tonbo agent create my-agent --region us-east-1
+tonbo init --region us-east-1
+```
+
 `run` creates a durable Session and prints its ID in `--json` output. Pass that identity back to continue the same PI conversation:
 
 ```console
 tonbo run --session 4d8e9501-... "Continue the previous task."
 ```
 
+Each `run` submits one durable Turn. Once the platform admits it, the Turn runs to its end whether or not the CLI keeps waiting, within the limits of `contracts/agents/turn-execution-v1.json` (today at most 60 minutes of execution, after waiting at most 70 minutes to start behind earlier Turns of the same Agent). `run` waits for the result as long as it takes: once the Turn is admitted it names the Turn and its Session on stderr and reads the Turn by id until it ends. It does not rely on the Management API's `202`, which comes only after a five-minute hold that outlasts how long Node's fetch waits for an answer; a submission that gets no answer before admission is sent again under the same id. Interrupting the wait, losing the network or signing out does not stop the Turn. `--no-wait` returns as soon as the Turn is admitted and prints how to collect its result later; `tonbo turn wait` does that from any bound directory whose signed-in account can use the Agent:
+
+```console
+tonbo run --no-wait "Refactor the build and run the full test suite."
+tonbo turn wait 7a000000-... --session 4d8e9501-...
+```
+
+A failed Turn exits non-zero with its failure code, for example `Turn 7a000000-... failed (deadline_exceeded): ...`; the codes and their meaning are the `TurnFailureCode` schema of `contracts/management/openapi-v1.yaml`. `agent_busy` means the Agent already has the most Turns waiting to start and this one was not admitted; run it again later. Any other refusal also says the Turn was not admitted, and `run` stops sending a submission the platform has not admitted within 15 minutes. Waiting stops, without touching the Turn, a few minutes after the Turn's deadline if the platform has still not recorded its outcome.
+
 Every `tonbo deploy` creates one immutable Deployment: the uploaded source, the `.tonbo` settings and the git provenance of the source root (commit, branch, subject, author and whether the tree was dirty) when the directory is inside a git work tree. Git is optional; without it the Deployment records `tonbo deploy` as its source. Deployments are named by their commit subject, or by their short id (the first eight hex characters) when there is no commit, and every command that takes a Deployment accepts any unambiguous id prefix. The Agent's Production pointer names the one Deployment that serves its hostname; `deploy` moves Production to the new Deployment and prints the Deployment, its Production state and the exact standard OpenSSH command for the bound Agent and its username:
 
 ```console
@@ -117,7 +134,7 @@ tonbo deployments rollback 9b8c1d22    # or to a named one
 
 `tonbo deployments` (alias `tonbo deployments list`) marks the current Production Deployment with `●` and earlier ones with `○`; `STATUS` is the Deployment's relationship to Production: `current`, `promoting`, `failed`, `stopped`, `previous` or `none`. Promotion and rollback compare-and-swap the Production generation, so two people moving Production at once cannot silently overwrite each other; a conflict is reported and the command can be retried after checking `tonbo deployments`. `tonbo agent show` prints the Production Deployment and its state alongside the Agent addresses.
 
-Use `tonbo agent show` to rediscover the username, application address and SSH command later. `tonbo login` registers public keys found at the conventional `~/.ssh/id_ed25519.pub`, `id_ecdsa.pub` and `id_rsa.pub` paths. Register a key at another path with `tonbo ssh-key add <path.pub>` and revoke a lost or retired key with `tonbo ssh-key remove SHA256:...`. The CLI is not part of the SSH connection; ordinary OpenSSH, `scp` and `rsync` connect directly:
+Use `tonbo agent show` to rediscover the username, home region, application address and SSH command later. `tonbo login` registers public keys found at the conventional `~/.ssh/id_ed25519.pub`, `id_ecdsa.pub` and `id_rsa.pub` paths. Register a key at another path with `tonbo ssh-key add <path.pub>` and revoke a lost or retired key with `tonbo ssh-key remove SHA256:...`. The CLI is not part of the SSH connection; ordinary OpenSSH, `scp` and `rsync` connect directly:
 
 ```console
 ssh my-agent.my-account@tonbo.sh
@@ -217,7 +234,7 @@ tonbo --json machine unbind <machine-uuid>
 tonbo --json machine release <machine-uuid>
 ```
 
-Only one active Agent binding per Machine and one Machine per Agent are currently supported. Unbinding drains execution and completes physical deletion, final usage settlement and storage credential revocation before the Machine becomes available. Wait for `available: true` in `machine show` before rebinding. Cross-Agent reassignment resets rootfs; the destination mounts its own Agent Workspace and Sessions. Hidden pause/resume within the same Agent retains rootfs and process state. Release also drains an existing binding automatically; it does not delete Agent files or Sessions.
+Only one active Agent binding per Machine and one Machine per Agent are currently supported. Unbinding drains execution and completes physical deletion, final usage settlement and storage credential revocation before the Machine becomes available. Wait for `available: true` in `machine show` before rebinding. Cross-Agent reassignment resets rootfs; the destination mounts its own Agent Workspace and Sessions. Hidden pause/resume within the same Agent retains rootfs and process state. Release also drains an existing binding automatically; it does not delete Agent files or Sessions. A Machine binds only to an Agent in the same region. `machine list` names any region it could not reach in `unavailable_regions`; its Machines are missing from that answer.
 
 `tonbo agent list` lists accessible Agents without requiring a local `.tonbo` file. JSON command output uses `agent` for one Agent and `agents` for the list; there is no duplicate `agent` output alias.
 

package/dist/bin/tonbo.js

@@ -16,7 +16,7 @@ var HttpError = class extends Error {
     this.body = body;
   }
 };
-async function requestJson(fetcher, url, init = {}) {
+async function requestJsonResponse(fetcher, url, init = {}) {
   const response = await fetcher(url, init);
   const body = await response.json().catch(() => null);
   if (!response.ok) {
@@ -30,7 +30,10 @@ async function requestJson(fetcher, url, init = {}) {
       body
     );
   }
-  return body;
+  return { body, headers: response.headers, status: response.status };
+}
+async function requestJson(fetcher, url, init = {}) {
+  return (await requestJsonResponse(fetcher, url, init)).body;
 }
 
 // src/contracts.ts
@@ -518,6 +521,13 @@ function assertManagedDeploymentSpec(value) {
 }
 
 // src/api.ts
+function turnSubmission(response) {
+  if (response.status === 202) return { state: "pending" };
+  const body = response.body ?? {};
+  if (!body.data || typeof body.data.assistant_text !== "string")
+    throw new Error("Tonbo answered the Turn without its result.");
+  return { state: "completed", turn: body.data };
+}
 var TonboApi = class {
   constructor(fetcher, accountOrigin = "https://tonbo.dev", managementOrigin = "https://api.tonbo.dev") {
     this.fetcher = fetcher;
@@ -562,7 +572,14 @@ var TonboApi = class {
       }
     ).then((body) => body.organizations);
   }
-  createAgent(oauthToken, name, organizationId, requestId = randomUUID()) {
+  /** An omitted region lets the server choose the only region that accepts
+   * new Agents; once more than one does, it refuses the request. */
+  createAgent(oauthToken, {
+    name,
+    organizationId,
+    region,
+    requestId = randomUUID()
+  }) {
     return requestJson(
       this.fetcher,
       `${this.accountOrigin}/api/cli/agents`,
@@ -575,14 +592,15 @@ var TonboApi = class {
         body: JSON.stringify({
           name,
           requestId,
-          ...organizationId ? { orgId: organizationId } : {}
+          ...organizationId ? { orgId: organizationId } : {},
+          ...region ? { region } : {}
         })
       }
     ).then((body) => body.agent).catch((cause) => {
       if (cause instanceof Error && "status" in cause && typeof cause.status === "number" && cause.status >= 400 && cause.status < 500)
         throw cause;
       throw new Error(
-        `Agent creation was not confirmed. Query \`tonbo agent creation ${requestId}${organizationId ? ` --account ${organizationId}` : ""}\` or retry creation with --request-id ${requestId} and the same name and account.`,
+        `Agent creation was not confirmed. Query \`tonbo agent creation ${requestId}${organizationId ? ` --account ${organizationId}` : ""}\` or retry creation with --request-id ${requestId} and the same name, account and region.`,
         { cause }
       );
     });
@@ -741,14 +759,13 @@ var TonboApi = class {
   listRollouts(agentId, token) {
     return this.managementList(`/v1/agents/${agentId}/production/rollouts`, token);
   }
-  async run({
+  /** Checks that Production is running and opens a durable Session, or
+   * reuses the given one. */
+  async openSession({
     agentId,
-    prompt,
     sessionId,
-    token,
-    turnId = randomUUID()
+    token
   }) {
-    const agentPath = `/v1/agents/${agentId}`;
     const production = await this.getProduction(agentId, token);
     if (!production)
       throw new Error("Agent has no Production Deployment; run `tonbo deploy` first.");
@@ -756,17 +773,42 @@ var TonboApi = class {
       throw new Error(
         `Production is ${production.observed_state}${production.last_error ? ` (${production.last_error})` : ""}; wait for it to be running.`
       );
-    const session = sessionId ? { id: sessionId } : (await this.management("POST", `${agentPath}/sessions`, token, {
-      deployment_id: production.deployment_id
-    })).data;
-    const turn = (await this.management(
+    const session = sessionId ? { id: sessionId } : (await this.management(
       "POST",
-      `${agentPath}/sessions/${session.id}/turns`,
+      `/v1/agents/${agentId}/sessions`,
       token,
-      { prompt },
-      turnId
+      { deployment_id: production.deployment_id }
     )).data;
-    return { production, session, turn };
+    return { production, session };
+  }
+  /** Submits one Turn under its own id; sending it again under the same id is
+   * answered from the same operation. The Management API holds the request
+   * for up to five minutes: it answers the result, 409 `turn_failed`, a
+   * refusal, or 202 while the Turn waits or runs. */
+  async submitTurn({
+    agentId,
+    prompt,
+    sessionId,
+    signal,
+    token,
+    turnId
+  }) {
+    return turnSubmission(
+      await this.managementResponse(
+        "POST",
+        `/v1/agents/${agentId}/sessions/${sessionId}/turns`,
+        token,
+        { body: { prompt }, idempotencyKey: turnId, signal }
+      )
+    );
+  }
+  /** One durable Turn; reading it never affects its execution. */
+  getTurn(agentId, sessionId, turnId, token) {
+    return this.management(
+      "GET",
+      `/v1/agents/${agentId}/sessions/${sessionId}/turns/${turnId}`,
+      token
+    ).then((response) => response.data);
   }
   turnEvents({
     after = 0,
@@ -803,17 +845,24 @@ var TonboApi = class {
       token
     );
   }
-  management(method, path6, token, body, idempotencyKey) {
-    return requestJson(this.fetcher, `${this.managementOrigin}${path6}`, {
+  management(method, path6, token, body) {
+    return this.managementResponse(method, path6, token, { body }).then(
+      (response) => response.body
+    );
+  }
+  managementResponse(method, path6, token, {
+    body,
+    idempotencyKey = randomUUID(),
+    signal
+  } = {}) {
+    return requestJsonResponse(this.fetcher, `${this.managementOrigin}${path6}`, {
       method,
       headers: {
         authorization: `Bearer ${token}`,
-        ...body === void 0 ? {} : {
-          "content-type": "application/json",
-          "idempotency-key": idempotencyKey ?? randomUUID()
-        }
+        ...body === void 0 ? {} : { "content-type": "application/json", "idempotency-key": idempotencyKey }
       },
-      ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      ...body === void 0 ? {} : { body: JSON.stringify(body) },
+      ...signal ? { signal } : {}
     });
   }
   async managementList(path6, token) {
@@ -1107,13 +1156,15 @@ var AuthClient = class {
     this.accountOrigin = accountOrigin;
     this.browserOpener = browserOpener;
   }
-  async accessToken() {
+  /** The stored access token, refreshed first when it has less than
+   * `minimumLifetimeSeconds` left. */
+  async accessToken(minimumLifetimeSeconds = 30) {
     const injected = process.env.TONBO_ACCESS_TOKEN?.trim();
     if (injected) return injected;
     const tokens = await this.credentials.load();
     if (!tokens) throw new Error("Not logged in. Run `tonbo login`.");
     const legacyRelativeExpiry = !tokens.expires_at && tokens.expires_in;
-    if (!legacyRelativeExpiry && (!tokens.expires_at || tokens.expires_at > Math.floor(Date.now() / 1e3) + 30))
+    if (!legacyRelativeExpiry && (!tokens.expires_at || tokens.expires_at > Math.floor(Date.now() / 1e3) + minimumLifetimeSeconds))
       return tokens.access_token;
     if (!tokens.refresh_token) throw new Error("Tonbo login expired. Run `tonbo login` again.");
     const config = await this.config();
@@ -1716,14 +1767,105 @@ function agentNameSuggestion(value) {
   return name;
 }
 
+// src/turns.ts
+var TURN_OUTCOME_GRACE_MS = 3 * 60 * 1e3;
+var POLL_MIN_MS = 1e3;
+var POLL_MAX_MS = 1e4;
+var READ_FAILURE_LIMIT = 10;
+var TurnFailedError = class extends Error {
+  constructor(turnId, failureCode, detail) {
+    super(
+      `Turn ${turnId} failed${failureCode ? ` (${failureCode})` : ""}${detail ? `: ${detail}` : "."}`
+    );
+    this.turnId = turnId;
+    this.failureCode = failureCode;
+    this.detail = detail;
+  }
+};
+function problemCode(error) {
+  if (!(error instanceof HttpError)) return null;
+  const body = error.body && typeof error.body === "object" ? error.body : {};
+  const code = body.code;
+  return typeof code === "string" ? code : null;
+}
+function submissionProblem(error, turnId) {
+  if (!(error instanceof HttpError)) return error;
+  const body = error.body ?? {};
+  const code = problemCode(error);
+  if (error.status === 409 && code === "turn_failed")
+    return new TurnFailedError(
+      turnId,
+      typeof body.failure_code === "string" ? body.failure_code : null,
+      typeof body.detail === "string" ? body.detail : null
+    );
+  if (error.status === 409 && code === "agent_busy")
+    return new Error(
+      `Turn ${turnId} was not admitted: the Agent already has the most Turns waiting to start (agent_busy). Try again with a new Turn later.`,
+      { cause: error }
+    );
+  return new Error(`Turn ${turnId} was not admitted: ${error.message}`, { cause: error });
+}
+function isUnauthenticated(error) {
+  return error instanceof HttpError && error.status === 401;
+}
+function isNotFound(error) {
+  return error instanceof HttpError && error.status === 404;
+}
+function isTransient(error) {
+  if (error instanceof HttpError) return error.status === 429 || error.status >= 500;
+  return error instanceof TypeError;
+}
+function turnWaitBound(turn) {
+  const deadline = turn.deadline_at ?? turn.start_deadline_at;
+  if (!deadline) return null;
+  const at = Date.parse(deadline);
+  return Number.isFinite(at) ? at + TURN_OUTCOME_GRACE_MS : null;
+}
+async function followTurn({
+  now,
+  read: read2,
+  resume,
+  sleep,
+  turnId
+}) {
+  let delay = POLL_MIN_MS;
+  let failures = 0;
+  for (; ; ) {
+    let state;
+    try {
+      state = await read2();
+      failures = 0;
+    } catch (error) {
+      const transient = isTransient(error);
+      if (transient && (failures += 1) < READ_FAILURE_LIMIT) {
+        await sleep(POLL_MAX_MS);
+        continue;
+      }
+      if (!transient && !(error instanceof HttpError)) throw error;
+      throw new Error(
+        `${error instanceof Error ? error.message : String(error)} Waiting stopped, which does not stop the Turn; ${resume}`,
+        { cause: error }
+      );
+    }
+    if ("result" in state) return state.result;
+    const bound = state.pending ? turnWaitBound(state.pending) : null;
+    if (bound !== null && now() > bound)
+      throw new Error(
+        `Turn ${turnId} is still pending after its deadline, and the platform has not recorded its outcome. Waiting stopped, which does not stop the Turn; ${resume}`
+      );
+    await sleep(delay);
+    delay = Math.min(delay * 2, POLL_MAX_MS);
+  }
+}
+
 // src/commands.ts
-async function resolveAgent(deps) {
+async function resolveAgent(deps, minimumTokenLifetimeSeconds) {
   const root = await findDeclarationRoot(deps.cwd());
   const declaration = await loadDeclaration(root);
   if (!declaration.agent) {
     throw new Error("No Agent is configured in .tonbo. Run `tonbo agent use <agent>` first.");
   }
-  const oauthToken = await deps.auth.accessToken();
+  const oauthToken = await deps.auth.accessToken(minimumTokenLifetimeSeconds);
   return {
     declaration,
     oauthToken,
@@ -1753,6 +1895,10 @@ async function initCommand(deps, options) {
   const overwrite = options.force === true || exists && interactive;
   if (exists && !overwrite)
     throw new Error(`${DECLARATION_FILENAME} already exists. Pass --force to replace it.`);
+  if (options.region !== void 0 && !interactive)
+    throw new Error(
+      "--region applies only to an agent that interactive init creates. Run `tonbo agent create <name> --region <region>` instead."
+    );
   const inspection = await deps.inspectSource(root);
   let harness = options.harness ?? (existingDeclaration ? "pi" : void 0);
   if (harness !== void 0 && harness !== "pi") {
@@ -1799,7 +1945,7 @@ async function initCommand(deps, options) {
     publicHostname: existingDeclaration.agent
   } : { kind: "later" };
   if (interactive && !existingDeclaration?.agent) {
-    agentPlan = await selectInitAgent(deps, root);
+    agentPlan = await selectInitAgent(deps, root, options.region);
   }
   if (interactive) {
     while (true) {
@@ -1842,7 +1988,7 @@ async function initCommand(deps, options) {
         ...driver === "command" ? [{ description: entry, name: "PI SDK entry file", value: "entry" }] : [],
         { name: "Back to review", value: "back" }
       ]);
-      if (setting === "agent") agentPlan = await selectInitAgent(deps, root);
+      if (setting === "agent") agentPlan = await selectInitAgent(deps, root, options.region);
       if (setting === "harness") harness = await selectHarness(deps);
       if (setting === "driver") {
         driver = await deps.select(
@@ -1871,7 +2017,11 @@ async function initCommand(deps, options) {
   let createdAgent;
   if (agentPlan.kind === "create") {
     const oauthToken = await deps.auth.accessToken();
-    createdAgent = await deps.api.createAgent(oauthToken, agentPlan.name, agentPlan.organizationId);
+    createdAgent = await deps.api.createAgent(oauthToken, {
+      name: agentPlan.name,
+      organizationId: agentPlan.organizationId,
+      region: agentPlan.region
+    });
     agentHostname = createdAgent.publicHostname;
   }
   const configuredDeclaration = createDeclaration(
@@ -1904,9 +2054,11 @@ Build: ${buildCommand?.join(" ")}
 Entrypoint: node ${entry}` : inspection.pi.packageCount > 0 ? `PI CLI with ${inspection.pi.packageCount} package${inspection.pi.packageCount === 1 ? "" : "s"}` : "PI CLI";
   const agentSummary = createdAgent ? `Agent: ${createdAgent.name} (${createdAgent.publicHostname})
 Organization: ${createdAgent.organizationName}
+Region: ${createdAgent.region}
 Application: https://${createdAgent.publicHostname}
 SSH after deploy: ssh ${createdAgent.sshDestination}` : agentPlan.kind === "existing" ? `Agent: ${agentPlan.name ? `${agentPlan.name} (${agentPlan.publicHostname})` : agentPlan.publicHostname}${agentPlan.organizationName ? `
-Organization: ${agentPlan.organizationName}` : ""}${agentPlan.sshDestination ? `
+Organization: ${agentPlan.organizationName}` : ""}${agentPlan.region ? `
+Region: ${agentPlan.region}` : ""}${agentPlan.sshDestination ? `
 SSH after deploy: ssh ${agentPlan.sshDestination}` : ""}` : "Next: tonbo agent create <name>";
   deps.output({
     message: `${createdAgent ? `Created agent ${createdAgent.name} and` : exists ? "Updated" : "Created"} ${DECLARATION_FILENAME}.
@@ -1923,7 +2075,7 @@ function initSaveLabel(exists, agent) {
   }
   return exists ? `Replace ${DECLARATION_FILENAME}` : `Create ${DECLARATION_FILENAME}`;
 }
-async function selectInitAgent(deps, root) {
+async function selectInitAgent(deps, root, requestedRegion) {
   for (; ; ) {
     const action = await deps.select("How should this directory connect to Tonbo?", [
       {
@@ -1945,6 +2097,7 @@ async function selectInitAgent(deps, root) {
     if (action === "later") return { kind: "later" };
     if (action === "create") {
       const organization = await selectInitOrganization(deps);
+      const region = requestedRegion ?? await selectAgentRegion(deps);
       const defaultName = agentNameSuggestion(path4.basename(root)) || "tonbo-agent";
       for (; ; ) {
         const answer = (await deps.prompt(`Agent name [${defaultName}]: `)).trim().toLowerCase();
@@ -1955,7 +2108,8 @@ async function selectInitAgent(deps, root) {
             kind: "create",
             name,
             organizationId: organization?.id,
-            organizationName: organization?.name
+            organizationName: organization?.name,
+            ...region ? { region } : {}
           };
         } catch (error) {
           deps.output({
@@ -1976,7 +2130,7 @@ async function selectInitAgent(deps, root) {
       "Which agent should this directory use?",
       agents.map((agent2) => ({
         name: agent2.name,
-        description: `Organization: ${agent2.organizationName} \xB7 ${agent2.publicHostname} \xB7 ${agent2.id}`,
+        description: `Organization: ${agent2.organizationName} \xB7 ${agent2.region} \xB7 ${agent2.publicHostname} \xB7 ${agent2.id}`,
         value: agent2.id
       }))
     );
@@ -1986,13 +2140,23 @@ async function selectInitAgent(deps, root) {
       name: agent.name,
       organizationName: agent.organizationName,
       publicHostname: agent.publicHostname,
+      region: agent.region,
       sshDestination: agent.sshDestination
     };
   }
 }
+async function selectAgentRegion(deps) {
+  const { regions } = await deps.api.listRegions(await deps.auth.accessToken());
+  const open3 = regions.filter((region) => region.allocation_enabled);
+  if (open3.length < 2) return void 0;
+  return deps.select(
+    "Which region should hold the new agent? It stays there permanently.",
+    open3.map((region) => ({ description: region.id, name: region.display_name, value: region.id }))
+  );
+}
 function initAgentSummary(agent) {
   if (agent.kind === "create")
-    return `Create ${agent.name}${agent.organizationName ? ` in ${agent.organizationName}` : ""} (permanent address assigned after creation)`;
+    return `Create ${agent.name}${agent.organizationName ? ` in ${agent.organizationName}` : ""}${agent.region ? `, region ${agent.region}` : ""} (permanent address assigned after creation)`;
   if (agent.kind === "existing") {
     return agent.name ? `${agent.name}${agent.organizationName ? ` in ${agent.organizationName}` : ""} (${agent.publicHostname})` : `Keep ${agent.publicHostname}`;
   }
@@ -2166,7 +2330,13 @@ async function agentCreateCommand(deps, name, options = {}) {
   const oauthToken = await deps.auth.accessToken();
   validateAgentName(name);
   const requestId = options.requestId ?? randomUUID3();
-  const agent = await deps.api.createAgent(oauthToken, name, options.account, requestId);
+  const region = options.region ?? (deps.interactive() ? await selectAgentRegion(deps) : void 0);
+  const agent = await deps.api.createAgent(oauthToken, {
+    name,
+    organizationId: options.account,
+    region,
+    requestId
+  });
   try {
     await bindDeclarationAgent(root, agent.publicHostname);
   } catch (error) {
@@ -2176,7 +2346,13 @@ async function agentCreateCommand(deps, name, options = {}) {
     );
   }
   deps.output({
-    message: `Created agent ${agent.name} and bound it in .tonbo.`,
+    message: [
+      `Created agent ${agent.name} and bound it in .tonbo.`,
+      `Organization: ${agent.organizationName}`,
+      `Region: ${agent.region}`,
+      `Application: https://${agent.publicHostname}`,
+      `SSH after deploy: ssh ${agent.sshDestination}`
+    ].join("\n"),
     agent,
     requestId
   });
@@ -2224,25 +2400,223 @@ async function deployCommand(deps, options = { promote: true }) {
   }
   deps.output({ message: lines.join("\n"), agent, ...result });
 }
-async function runCommand(deps, prompt, options) {
-  const { oauthToken, agent } = await resolveAgent(deps);
-  const managementToken = await deps.api.exchangeManagementToken(oauthToken, agent.id);
-  const result = await deps.api.run({
-    agentId: agent.id,
-    prompt,
-    sessionId: options.session,
-    token: managementToken
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var ADMISSION_WAIT_MS = 15 * 60 * 1e3;
+var RESUBMIT_MS = 5e3;
+var SUBMISSION_TOKEN_LIFETIME_SECONDS = 240;
+function managementTokens(deps, agentId, oauthToken) {
+  let current = deps.api.exchangeManagementToken(oauthToken, agentId);
+  return async function withToken(call) {
+    const token = await current;
+    try {
+      return await call(token);
+    } catch (error) {
+      if (!isUnauthenticated(error)) throw error;
+      current = deps.auth.accessToken().then((oauth) => deps.api.exchangeManagementToken(oauth, agentId));
+      return call(await current);
+    }
+  };
+}
+function waitCommand(turnId, sessionId) {
+  return `tonbo turn wait ${turnId} --session ${sessionId}`;
+}
+function turnNotFound(turnId, sessionId, agentName) {
+  return new Error(`Turn ${turnId} was not found in Session ${sessionId} of agent ${agentName}.`);
+}
+function sessionTurn(turn) {
+  return {
+    assistant_text: turn.assistant_text ?? "",
+    session_id: turn.session_id,
+    turn_id: turn.id
+  };
+}
+function holdSubmission(deps, withToken, submission) {
+  const controller = new AbortController();
+  const held = { controller, settled: Promise.resolve() };
+  held.settled = withToken(
+    (token) => deps.api.submitTurn({ ...submission, signal: controller.signal, token })
+  ).then(
+    (value) => {
+      held.answer = { value };
+    },
+    (error) => {
+      held.answer = { error };
+    }
+  );
+  return held;
+}
+async function submitAndFollow(deps, withToken, submission, { agentName, outcome }) {
+  const { agentId, sessionId, turnId } = submission;
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? pause;
+  const submittedAt = now();
+  const state = {
+    admitted: false,
+    announced: false,
+    held: holdSubmission(deps, withToken, submission),
+    resubmitAt: 0,
+    unanswered: null
+  };
+  const read2 = async () => {
+    const answer = state.held?.answer;
+    if (answer) {
+      state.held = null;
+      if ("error" in answer) {
+        const problem = submissionProblem(answer.error, turnId);
+        if (problem instanceof TurnFailedError) throw problem;
+        if (!state.admitted) {
+          if (!isTransient(answer.error)) throw problem;
+          state.unanswered = answer.error;
+          state.resubmitAt = now() + RESUBMIT_MS;
+        }
+      } else if (answer.value.state === "completed") {
+        return { result: { completed: answer.value.turn } };
+      }
+    }
+    let turn = null;
+    try {
+      turn = await withToken((token) => deps.api.getTurn(agentId, sessionId, turnId, token));
+    } catch (error) {
+      if (!isNotFound(error)) throw error;
+      if (state.admitted) throw turnNotFound(turnId, sessionId, agentName);
+    }
+    if (turn) {
+      state.admitted = true;
+      if (turn.status === "completed") return { result: { completed: sessionTurn(turn) } };
+      if (turn.status === "failed")
+        throw new TurnFailedError(turn.id, turn.failure_code, turn.failure);
+      if (!outcome) return { result: { admitted: turn } };
+      if (!state.announced) {
+        state.announced = true;
+        deps.progress.start(
+          `Turn ${turnId} is running on the platform in Session ${sessionId}; waiting for its result. Interrupting the wait does not stop the Turn.`
+        );
+      }
+      return { pending: turn };
+    }
+    if (now() - submittedAt > ADMISSION_WAIT_MS) {
+      const cause = state.unanswered;
+      throw new Error(
+        `Turn ${turnId} was not admitted within ${ADMISSION_WAIT_MS / 6e4} minutes${cause instanceof Error ? ` (the last submission got no answer: ${cause.message})` : ""}. Waiting stopped; if the platform admits it later, \`${waitCommand(turnId, sessionId)}\` follows it.`,
+        { cause }
+      );
+    }
+    if (!state.held && now() >= state.resubmitAt)
+      state.held = holdSubmission(deps, withToken, submission);
+    return { pending: null };
+  };
+  try {
+    const followed = await followTurn({
+      now,
+      read: read2,
+      resume: `wait for it with \`${waitCommand(turnId, sessionId)}\`.`,
+      // An answer to the held submission ends a pause at once.
+      sleep: async (ms) => {
+        const held = state.held;
+        if (!held) return sleep(ms);
+        const wake = new AbortController();
+        await Promise.race([sleep(ms, wake.signal), held.settled]);
+        wake.abort();
+      },
+      turnId
+    });
+    if (state.announced) deps.progress.succeed(`Turn ${turnId} completed.`);
+    return followed;
+  } catch (error) {
+    if (state.announced) deps.progress.fail();
+    throw error;
+  } finally {
+    state.held?.controller.abort();
+  }
+}
+function pause(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
   });
+}
+async function runCommand(deps, prompt, options) {
+  const { oauthToken, agent } = await resolveAgent(deps, SUBMISSION_TOKEN_LIFETIME_SECONDS);
+  const withToken = managementTokens(deps, agent.id, oauthToken);
+  const { production, session } = await withToken(
+    (token) => deps.api.openSession({ agentId: agent.id, sessionId: options.session, token })
+  );
+  const turnId = randomUUID3();
+  const followed = await submitAndFollow(
+    deps,
+    withToken,
+    { agentId: agent.id, prompt, sessionId: session.id, turnId },
+    { agentName: agent.name, outcome: options.wait !== false }
+  );
+  if ("admitted" in followed) {
+    deps.output({
+      message: [
+        `Turn ${turnId} was admitted in Session ${session.id}; the platform runs it to its end.`,
+        "Wait for its result:",
+        `  ${waitCommand(turnId, session.id)}`
+      ].join("\n"),
+      agent,
+      production,
+      session,
+      turn_id: turnId,
+      turn: followed.admitted
+    });
+    return;
+  }
   deps.output({
-    message: result.turn.assistant_text,
+    message: followed.completed.assistant_text,
     agent,
-    ...result
+    production,
+    session,
+    turn: followed.completed
   });
 }
+async function turnWaitCommand(deps, turnId, options) {
+  if (!UUID.test(turnId) || !UUID.test(options.session))
+    throw new Error("The Turn and its Session are identified by UUIDs.");
+  const { oauthToken, agent } = await resolveAgent(deps);
+  const withToken = managementTokens(deps, agent.id, oauthToken);
+  deps.progress.start(`Waiting for Turn ${turnId}. Interrupting the wait does not stop the Turn.`);
+  try {
+    const turn = await followTurn({
+      now: deps.now ?? Date.now,
+      read: async () => {
+        let current;
+        try {
+          current = await withToken(
+            (token) => deps.api.getTurn(agent.id, options.session, turnId, token)
+          );
+        } catch (error) {
+          if (!isNotFound(error)) throw error;
+          throw turnNotFound(turnId, options.session, agent.name);
+        }
+        if (current.status === "completed") return { result: current };
+        if (current.status === "failed")
+          throw new TurnFailedError(current.id, current.failure_code, current.failure);
+        return { pending: current };
+      },
+      resume: `run \`${waitCommand(turnId, options.session)}\` again.`,
+      sleep: deps.sleep ?? pause,
+      turnId
+    });
+    deps.progress.succeed(`Turn ${turnId} completed.`);
+    deps.output({ message: turn.assistant_text ?? "", agent, turn });
+  } catch (error) {
+    deps.progress.fail();
+    throw error;
+  }
+}
 async function agentListCommand(deps) {
   const agents = await deps.api.listAgents(await deps.auth.accessToken());
   deps.output({
-    message: agents.length ? agents.map((agent) => `${agent.name} \xB7 ${agent.publicHostname}`).join("\n") : "No agents are available.",
+    message: agents.length ? agents.map((agent) => `${agent.name} \xB7 ${agent.publicHostname} \xB7 ${agent.region}`).join("\n") : "No agents are available.",
     agents
   });
 }
@@ -2253,6 +2627,7 @@ async function agentShowCommand(deps) {
   const lines = [
     `agent: ${agent.name}`,
     `Organization: ${agent.organizationName}`,
+    `region: ${agent.region}`,
     `application: https://${agent.publicHostname}`,
     `ssh: ssh ${agent.sshDestination}`
   ];
@@ -2746,7 +3121,7 @@ function jsonOutput(program) {
 }
 function createProgram(dependencies = createDependencies) {
   const program = new Command().name("tonbo").description("Deploy a persistent Agent to Tonbo.").version(packageVersion.version).option("--json", "print machine-readable JSON");
-  program.command("init").description("interactively create a Tonbo Agent declaration in this directory").option("--harness <harness>", "Agent Harness (currently pi)").option("--model <model>", "inference model").option("--driver <driver>", "PI driver: native or command").option("--agent-entry <file>", "Node entry file for the command driver").option("--build-command <argv...>", "build command argv for the command driver").option("--force", `replace an existing ${DECLARATION_FILENAME}`).action(
+  program.command("init").description("interactively create a Tonbo Agent declaration in this directory").option("--harness <harness>", "Agent Harness (currently pi)").option("--model <model>", "inference model").option("--driver <driver>", "PI driver: native or command").option("--agent-entry <file>", "Node entry file for the command driver").option("--build-command <argv...>", "build command argv for the command driver").option("--region <region>", "home region of an agent init creates (see tonbo region list)").option("--force", `replace an existing ${DECLARATION_FILENAME}`).action(
     async (options) => initCommand(dependencies(jsonOutput(program)), options)
   );
   program.command("login").description("sign in through the browser and store the session in the user config").action(async () => loginCommand(dependencies(jsonOutput(program))));
@@ -2830,7 +3205,10 @@ function createProgram(dependencies = createDependencies) {
     );
   });
   const agent = program.command("agent").description("manage the Agent bound to this source directory");
-  agent.command("create <name>").description("create an agent and bind this directory to it").option("--account <account>", "owning account UUID; defaults to your personal account").option("--request-id <uuid>", "reuse the same creation UUID after an uncertain response").action(
+  agent.command("create <name>").description("create an agent and bind this directory to it").option("--account <account>", "owning account UUID; defaults to your personal account").option(
+    "--region <region>",
+    "permanent home region (see tonbo region list); required once several regions accept new agents"
+  ).option("--request-id <uuid>", "reuse the same creation UUID after an uncertain response").action(
     async (name, options) => agentCreateCommand(dependencies(jsonOutput(program)), name, options)
   );
   agent.command("creation <requestId>").description("query the original Agent for a creation request").option("--account <account>", "owning account UUID; defaults to your personal account").action(async (requestId, options) => {
@@ -2870,9 +3248,17 @@ function createProgram(dependencies = createDependencies) {
   deployments.command("rollback [deployment]").description("move Production back to the previous Production Deployment, or to a named one").action(
     async (prefix) => deploymentsRollbackCommand(dependencies(jsonOutput(program)), prefix)
   );
-  program.command("run <prompt>").description("run one prompt in a durable agent session").option("--session <session>", "resume an existing Agent Session UUID").action(
+  program.command("run <prompt>").description("run one prompt as a durable Turn in an agent session and wait for its result").option("--session <session>", "resume an existing Agent Session UUID").option(
+    "--no-wait",
+    "return once the Turn is admitted; the platform runs it to its end (see tonbo turn wait)"
+  ).action(
     async (prompt, options) => runCommand(dependencies(jsonOutput(program)), prompt, options)
   );
+  program.command("turn").description("follow durable Turns of the bound agent").command("wait <turn>").description(
+    "wait for a Turn's result; the Turn runs on the platform whether or not anyone waits"
+  ).requiredOption("--session <session>", "the Turn's Agent Session UUID").action(
+    async (turnId, options) => turnWaitCommand(dependencies(jsonOutput(program)), turnId, options)
+  );
   const secret = program.command("secret").description("manage encrypted environment secrets for the agent service");
   secret.command("list").action(async () => secretListCommand(dependencies(jsonOutput(program))));
   secret.command("set <name>").description("set a secret from an environment variable (the same name by default)").option("--from-env <name>", "read the value from another environment variable").action(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Deploy persistent Agents and manage their Machines from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {