agental 0.3.0 → 0.4.0

package/dist/cli.js

@@ -46,7 +46,7 @@ import { parseArgs } from "node:util";
 
 // ../src/cli-build.ts
 var PUBLISHED = true;
-var CLI_VERSION = true ? "0.3.0" : "dev";
+var CLI_VERSION = true ? "0.4.0" : "dev";
 var DEFAULT_API_URL = true ? "https://agental.io" : "http://127.0.0.1:8741";
 var PACKAGE_NAME = "agental";
 var USER_AGENT = `agental-cli/${CLI_VERSION}`;
@@ -2407,7 +2407,7 @@ function topUpByDollars(dollars) {
 var TOP_UPS = [20, 50, 100, 250, 500, 1e3, 5e3, 1e4].map((dollars) => topUpByDollars(dollars));
 
 // ../src/sandbox-where.ts
-var TERMS = /* @__PURE__ */ new Set(["status", "size", "region", "template", "tag", "archived", "memory", "outbound", "stops", "made-by"]);
+var TERMS = /* @__PURE__ */ new Set(["status", "size", "region", "template", "tag", "archived", "memory", "outbound", "stops", "made-by", "activity"]);
 function words(text) {
   const found = [];
   for (const match of text.matchAll(/(?:[^\s"]+|"[^"]*")+/g)) {
@@ -2443,8 +2443,8 @@ function whereQuery(text, query = new URLSearchParams()) {
       query.append(`${not ? "notMetadata" : "metadata"}[${key2}]`, value);
       continue;
     }
-    if (not && key2 !== "tag") {
-      throw new Error(`${word}: only tags and metadata keys can be left out with -.`);
+    if (not && key2 !== "tag" && key2 !== "activity") {
+      throw new Error(`${word}: only tags, activity and metadata keys can be left out with -.`);
     }
     switch (key2) {
       case "status":
@@ -2479,6 +2479,11 @@ function whereQuery(text, query = new URLSearchParams()) {
       case "made-by":
         query.append("createdBy", value);
         break;
+      case "activity":
+        for (const each of value.split(",")) {
+          query.append(not ? "notActivity" : "activity", each);
+        }
+        break;
       case "archived":
         query.set("archived", value);
         break;
@@ -2623,6 +2628,8 @@ async function main() {
       never: { type: "boolean", default: false },
       outbound: { type: "string" },
       allow: { type: "string", multiple: true },
+      // Where a sandbox's web traffic leaves, as agental create takes it: box, or residential:<country>[:sticky|rotating].
+      egress: { type: "string" },
       "ssh-key": { type: "string", multiple: true },
       none: { type: "boolean", default: false },
       host: { type: "string", multiple: true },
@@ -2770,6 +2777,9 @@ async function main() {
     case "network":
       await network(positionals.slice(1), values);
       return;
+    case "egress":
+      await egress(positionals.slice(1), values);
+      return;
     case "templates":
       await listTemplates(values.json);
       return;
@@ -2875,6 +2885,7 @@ async function create(values) {
     );
   }
   const allow = values.allow === void 0 ? void 0 : listedIn(values.allow);
+  const egressAsked = values.egress === void 0 ? void 0 : egressFrom(values.egress.split(":"), "--egress takes box, or residential:<country>, as residential:de or residential:us:rotating.");
   const sshKeys2 = values["ssh-key"] === void 0 ? void 0 : publicKeysFrom(values["ssh-key"]);
   const box = boxNamed(values.box);
   const templateId = values.template === void 0 ? void 0 : (await templateNamed(values.template)).id;
@@ -2888,6 +2899,7 @@ async function create(values) {
       ...templateId ? { templateId } : {},
       ...regionsOption(values.region),
       ...allow ? { network: { allow } } : {},
+      ...egressAsked ? { egress: egressAsked } : {},
       ...ttlSeconds === void 0 ? {} : { ttlSeconds },
       ...sshKeys2 === void 0 ? {} : { sshKeys: sshKeys2 },
       ...given
@@ -3751,6 +3763,72 @@ async function network(positionals, values) {
     ].join("\n")
   );
 }
+function egressFrom(words2, how) {
+  const [via, country, session, ...more] = words2.map((word) => word.trim());
+  if (via === "box" && country === void 0) {
+    return { via: "box" };
+  }
+  if (via !== "residential" || country === void 0 || !/^[a-zA-Z]{2}$/.test(country) || more.length > 0 || session !== void 0 && session !== "sticky" && session !== "rotating") {
+    throw new Error(how);
+  }
+  return { via: "residential", country: country.toLowerCase(), ...session === void 0 ? {} : { session } };
+}
+function egressInWords(body) {
+  if (body?.via !== "residential") {
+    return "from its server (box)";
+  }
+  return `residential, from ${String(body.country ?? "").toUpperCase()}, ${body.session === "rotating" ? "a new address each connection" : "one address kept (sticky)"}`;
+}
+async function egress(positionals, values) {
+  const [first, ...rest] = positionals;
+  const print4 = (body2, words2) => {
+    process.stdout.write(values.json ? `${JSON.stringify(body2, null, 2)}
+` : words2);
+  };
+  if (first === void 0 || first === "use-case" || first === "budget") {
+    let body2;
+    if (first === "use-case") {
+      const useCase = rest.join(" ").trim();
+      if (useCase === "") {
+        throw new Error('egress use-case takes what your sandboxes will use residential addresses for, in a few sentences, as agental egress use-case "Our agents test sign-up flows from the countries we sell in."');
+      }
+      body2 = await call2("/v1/egress/use-case", { method: "PUT", body: JSON.stringify({ useCase }) });
+    } else if (first === "budget") {
+      const given = rest[0];
+      const dollars = given === void 0 || given.trim() === "" ? Number.NaN : Number(given.replace(/^\$/, ""));
+      if (rest.length !== 1 || given !== "default" && (!Number.isFinite(dollars) || dollars < 0)) {
+        throw new Error("egress budget takes the most residential traffic may cost in a month, in US dollars, as agental egress budget 20, or default.");
+      }
+      body2 = await call2("/v1/egress/budget", { method: "PUT", body: JSON.stringify({ budgetMicros: given === "default" ? null : Math.round(dollars * 1e6) }) });
+    } else {
+      body2 = await call2("/v1/egress", { method: "GET" });
+    }
+    const account3 = body2 && typeof body2 === "object" ? body2 : {};
+    const number = (name) => typeof account3[name] === "number" ? account3[name] : 0;
+    const missing = Array.isArray(account3["missing"]) ? account3["missing"].map(String) : [];
+    const needs = {
+      plan: "a plan of Fleet ($100 a month) or larger: agental billing",
+      card: "a card saved: agental billing card",
+      use_case: 'what your sandboxes will use it for: agental egress use-case "<what for>"'
+    };
+    const refused = account3["refused"];
+    const lines = !account3["offered"] ? ["Residential egress is not offered here."] : [
+      `residential: ${account3["enabled"] ? "on for this account" : refused ? `refused: ${String(refused.reason ?? "")}` : "not yet"}`,
+      ...missing.map((need) => `  needs ${needs[need] ?? need}`),
+      `price:       ${money(number("microsPerGb"))} a GB, both directions counted`,
+      `this month:  ${money(number("spentMicros"))} of a ${money(number("budgetMicros"))} budget${account3["budgetSet"] ? "" : " (the default)"}`,
+      ...account3["blocked"] && account3["blocked"] !== "refused" ? [`blocked now: ${String(account3["blocked"]).replaceAll("_", " ")}`] : []
+    ];
+    print4(body2, `${lines.join("\n")}
+`);
+    return;
+  }
+  const path4 = `/v1/sandboxes/${encodeURIComponent(first)}/egress`;
+  const how = `egress takes <sandbox-id>, and then nothing, box, or residential <country> [sticky|rotating], as agental egress ${first} residential de.`;
+  const body = await call2(path4, rest.length === 0 ? { method: "GET" } : { method: "PUT", body: JSON.stringify(egressFrom(rest, how)) });
+  print4(body, `${first}: ${egressInWords(body)}
+`);
+}
 function templateSshInWords(ssh2) {
   const keys = ssh2.keys.length === 1 ? "1 key" : `${ssh2.keys.length} keys`;
   return `${ssh2.enabled ? "on" : "off"} as a sandbox is made, ${keys} let in`;
@@ -3832,7 +3910,7 @@ function showTemplate(each) {
 }
 async function template(positionals, values) {
   const [action, first, ...rest] = positionals;
-  const usage = "template takes create, show, rename, delete, start, network, ssh, ssh-keys, tags, meta, sandboxes, apply, of or put. agental help says how.";
+  const usage = "template takes create, show, rename, delete, start, network, egress, ssh, ssh-keys, tags, meta, sandboxes, apply, of or put. agental help says how.";
   const print4 = (body, words2) => {
     process.stdout.write(values.json ? `${JSON.stringify(body, null, 2)}
 ` : words2);
@@ -3922,6 +4000,15 @@ ${mode === void 0 ? "" : "A sandbox on it takes this when it next starts, or now
       );
       return;
     }
+    case "egress": {
+      const found = await templateNamed(need(first, "<template>"));
+      const path4 = `/v1/templates/${encodeURIComponent(found.id)}/egress`;
+      const how = `template egress takes <template>, and then nothing, box, or residential <country> [sticky|rotating], as agental template egress ${first ?? ""} residential de.`;
+      const set = await call2(path4, rest.length === 0 ? { method: "GET" } : { method: "PUT", body: JSON.stringify(egressFrom(rest, how)) });
+      print4(set, `${found.name}: ${egressInWords(set)}${rest.length === 0 ? "" : ", for sandboxes made from it from now on"}
+`);
+      return;
+    }
     case "ssh": {
       const found = await templateNamed(need(first, "<template>"));
       const path4 = `/v1/templates/${encodeURIComponent(found.id)}/ssh`;
@@ -4847,7 +4934,7 @@ Setting up
 
 Usage
   agental create --name <name> [--template <template>] [--size tiny|small|medium|large] [--region <region>[,<region>...]] [--ttl <time> | --ttl default] [--idempotency-key <key>]
-                 ${operator ? "[--box <name-or-id>] " : ""}[--allow <address>[,<address>...]] [--max-burst-fee <dollars>]
+                 ${operator ? "[--box <name-or-id>] " : ""}[--allow <address>[,<address>...]] [--egress box | residential:<country>[:sticky|rotating]] [--max-burst-fee <dollars>]
                  [--ssh-key <public-key-or-file>]... [--tag <tag>[,<tag>...]]... [--meta <key>=<value>]...
   agental summary [--where '<words>'] [--tag <tag>[,<tag>...]]... [--meta <key>=<value>]... [--facets <field>[,<field>...]] [--json]
   agental list [--where '<words>'] [--tag <tag>[,<tag>...]]... [--meta <key>=<value>]... [--sort=<sort>] [--limit <n>] [--json]
@@ -4865,6 +4952,7 @@ Usage
   agental recover <sandbox-id> [--max-burst-fee <dollars>]
   agental auto-stop <sandbox-id> [--in <time> | --at <date-time> | --never] [--json]
   agental network <sandbox-id> [--allow <address>[,<address>...] | --none] [--json]
+  agental egress <sandbox-id> [box | residential <country> [sticky | rotating]] [--json]
   agental templates [--json]
   agental template create <name> [--tag <tag>[,<tag>...]]... [--meta <key>=<value>]...
   agental template show <template> [--json]
@@ -4872,6 +4960,7 @@ Usage
   agental template delete <template>
   agental template start <template> [--size tiny|small|medium|large] [--snapshot <snapshot-id> | --new-machine] [--ttl <time> | --ttl default]
   agental template network <template> [open | blocked | allowlist <address>...] [--json]
+  agental template egress <template> [box | residential <country> [sticky | rotating]] [--json]
   agental template ssh <template> [on | off] [--json]
   agental template ssh-keys <template> [<public-key-or-file>... | --remove <key-id>] [--json]
   agental template tags <template> [add|rm <tag>...] [--json]
@@ -4920,6 +5009,8 @@ Usage
   agental key delete <key>
   agental billing [prices | card | top-up <dollars> | auto-reload <dollars | off>] [--json]
   agental burst [budget <dollars> | budget default] [--json]
+  agental egress [budget <dollars> | budget default] [--json]
+  agental egress use-case "<what your sandboxes will use it for>" [--json]
   agental account export [--out <file>]
   agental ssh <sandbox-id> [--tmux] [ssh options] [command...]
   agental scp [scp options] <source>... <target>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agental",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The agental command: Linux sandboxes for your agents, from the terminal. npx agental@latest signs you in and installs the agent skills.",
   "license": "MIT",
   "author": "VERTIXER LTD",