warpmetal 0.8.13 → 0.9.1

package/skills/warpmetal/references/cli-reference.md

@@ -3,12 +3,14 @@
 ## Contents
 
 - Discovery
+- Account authentication
 - Purchase and provisioning
 - SSH identities
 - Renewal and notifications
 - Server management
 - Agent Runtime and sandboxes
 - Per-agent access
+- Retained Work and Insights (source candidate)
 - Skill installation and state
 - Exit codes
 
@@ -17,11 +19,106 @@
 ```sh
 warpmetal health --json
 warpmetal catalog [--plan <planId>] --json
+warpmetal models [--provider <id>] [--auth-mode <api_key|chatgpt_subscription>] [--json]
 ```
 
+## Public model catalog
+
+`warpmetal models` performs a read-only `GET /agent-team-model-catalog` request.
+It preserves the published snapshot metadata, source provenance, freshness state
+and authentication modes. `--provider` and `--auth-mode` filter entries and
+remove recommendations whose published entry is no longer present. The command
+does not infer eligibility or contact a model provider. `catalog` remains the
+VPS plan catalog.
+
 `health` exits with code 3 when the service responds but purchasing is paused.
 The catalog remains useful for read-only discovery.
 
+## Account authentication
+
+```sh
+warpmetal login [--no-browser] [--read-only] --json
+warpmetal auth status --json
+warpmetal logout --json
+```
+
+`login` uses the public `warpmetal-customer-cli` device client. It requests
+`cli:read cli:write` by default or only `cli:read` with `--read-only`, prints the
+bounded verification page and user code to stderr, and opens that page unless
+`--no-browser` is present. Polling follows the server interval and treats
+pending, slow-down, denial, expiry and cancellation as distinct outcomes. JSON
+stdout contains only safe account identity and scope fields; access, refresh
+and device credentials are never output.
+
+The rotating CLI refresh family is independent of browser sessions, legacy
+owner tokens and SSH credentials. It is stored in an owner-only, atomic session
+file under the private WarpMetal state directory. Concurrent commands serialize
+refresh. If refresh completion is ambiguous, the saved session is cleared and a
+new login is required rather than replaying the old credential.
+
+Sessions are bound to the exact Identity and account origins. Defaults are
+`https://identity.warpmetal.com` and `https://warpmetal.com`; explicit
+`--identity-url` and `--account-url` values must be HTTPS origins (localhost may
+use HTTP). Redirects are refused, and credentials for one origin pair are never
+sent to another. `logout` attempts remote family revocation and always clears
+the matching local session, reporting whether revocation was confirmed.
+
+Account login does not grant server SSH access. `warpmetal server login` remains
+the separate, server-specific SSH challenge command.
+
+## Account orders and devices
+
+```sh
+warpmetal account orders [--task <taskId>] --json
+warpmetal account devices [--server <serverId>] --json
+warpmetal order prepare --account --without-agent-boxes \
+  --plan <planId> --hostname <name> --os '<exact catalog OS>' \
+  --generate-ssh-key [--idempotency-key <key>] --json
+```
+
+Reads require `cli:read`; unpaid preparation requires `cli:write`. Only these
+allowlisted operations are granted. Account scope never authorizes a payment,
+renewal, server deletion, credential change or runtime execution. Collections
+return the server's bounded page and `nextCursor`; order history is distinct from
+active devices and can include released or cancelled orders.
+
+Account mode signs in before checking order fields. It derives contact and
+ownership from the signed-in principal, rejects `--email`, uses the private
+account gateway, and records `ownershipMode: account` plus principal/origin in
+private local state without an owner token. Use the same idempotency key and
+unchanged payload to retry an ambiguous preparation. Do not retry a charge.
+Existing owner-token checkout commands do not become account payment commands.
+
+Boxes/team are selected by default for new account preparation: provide
+`--runtime-file` with your chosen team, `--without-team` for one persistent small
+`main` box, or `--without-agent-boxes` for no runtime. Explicit runtime files keep
+their box/team choices, and older scripts without `--account` retain their
+defaults. Server model/runtime readiness gates remain binding.
+
+The optional `teams` sibling of `sandboxes` uses the deployed team-v1 schema:
+
+```json
+{
+  "sandboxes": [{"name":"manager","size":"small"},{"name":"builder","size":"small"}],
+  "teams": {"version":1,"teams":[{
+    "name":"Build team",
+    "members":[
+      {"sandboxName":"manager","role":"manager","providerId":"openai"},
+      {"sandboxName":"builder","role":"worker","providerId":"anthropic"}
+    ],
+    "links":[{"from":"manager","to":"builder","capability":"task.delegate"}],
+    "startPolicy":"manual"
+  }]}
+}
+```
+
+Provider names in this example are preferences, not qualification proof. Optional
+`modelId` and `authMode` must reflect the selected published entry; omitted values
+mean choose later, never automatic credentials. A team has one manager and 2–8
+distinct declared boxes. Credentials, unknown fields, automatic start and
+cross-team links are rejected. Team/setup files are for order preparation;
+`sandbox create --file` accepts a sandbox batch only.
+
 ## Purchase and provisioning
 
 ```sh
@@ -246,8 +343,8 @@ warpmetal sandbox list --server <serverId> --json
 warpmetal sandbox get --server <serverId> --sandbox <sandboxId> [--wait] --json
 warpmetal sandbox action \
   --server <serverId> --sandbox <sandboxId> \
-  --action <start|stop|restart|make_persistent|refresh_image> --confirm <same-action> \
-  [--wait] --json
+  --action <start|stop|restart|make_persistent|refresh_image|patch_image> --confirm <same-action> \
+  [--image-digest <image@sha256:digest>] [--wait] --json
 warpmetal sandbox delete \
   --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json
 
@@ -315,6 +412,57 @@ Every selection must reference a sandbox name in the same file. Unknown fields,
 including URL, shell, command, argv, environment, or artifact overrides, are
 rejected before an API request.
 
+## Retained Work and Insights (source candidate)
+
+Discover command availability with `warpmetal --help`; these routes require
+the corresponding candidate control plane, Runtime and Sandbox.
+
+```sh
+warpmetal work list|sources|policy SERVER BOX --json
+warpmetal work show|content|targets SERVER BOX WORK --json
+warpmetal work create SERVER BOX --file request.json --json
+warpmetal work update|enable|checkpoint|continue|restore|handoff SERVER BOX WORK --file request.json --json
+warpmetal work status SERVER BOX WORK --kind checkpoint|continue|restore|handoff \
+  (--request REQUEST | --operation OPERATION) --json
+warpmetal work open SERVER BOX WORK --json
+warpmetal insights summary SERVER --json
+warpmetal insights status|list SERVER BOX --json
+warpmetal insights enable|disable SERVER BOX --file request.json --json
+warpmetal insights show SERVER BOX FINDING --json
+warpmetal insights acknowledge|snooze|dismiss SERVER BOX FINDING --file request.json --json
+warpmetal insights open SERVER BOX FINDING [--takeover OPERATION] --json
+warpmetal insights manager settings SERVER BOX [--file request.json] --json
+warpmetal insights manager activity SERVER BOX [--finding FINDING] --json
+warpmetal insights manager run SERVER BOX RUN --json
+warpmetal insights manager target SERVER BOX FINDING --json
+warpmetal insights manager recheck SERVER BOX FINDING --file request.json --json
+warpmetal insights manager status SERVER BOX FINDING --request REQUEST --json
+warpmetal insights takeover list SERVER BOX FINDING --json
+warpmetal insights takeover SERVER BOX FINDING --file request.json --json
+warpmetal insights takeover status SERVER BOX FINDING --operation OPERATION --json
+warpmetal insights takeover resume SERVER BOX FINDING --operation OPERATION --file request.json --json
+warpmetal insights review SERVER BOX RUN --json
+```
+
+Use the server's existing scoped owner/SSH credential. The account session is
+not a fallback. `--file` mutations validate a closed request with an explicit
+request ID and revision fences before HTTP. Saved same-intent retries are
+GET-only. Preserve the original request after a lost reply; never generate a
+new request to bypass an uncertain outcome. Pending operations exit 8, terminal
+failures/conflicts exit 5. Accepted Continue/handoff means task admission, not
+completion. Check task state separately.
+
+Only `work content` deliberately prints private content. Metadata and receipts
+are closed projections. Do not log private request files or content output.
+
+`open`/`review --json` returns a fresh descriptor without SSH. For deliberate
+human interactive access, omit `--json` and supply absolute
+`--connection-file` and `--identity` paths for the exact sandbox grant. Local
+OpenCode 2.0.14 connects through the fixed pinned bridge to the exact existing
+session. The command creates no session and sends no initial prompt. Manager
+review cannot mutate the worker. Takeover checks the current protected hold;
+Resume requires its saved operation, predecessor and revision tuple.
+
 ## Per-agent access
 
 ```sh

package/skills/warpmetal/references/runtime.md

@@ -183,6 +183,25 @@ workspace, sandbox lifetime, and original start time. `--wait` requires both
 the observed digest and generation to match the accepted target. A change to
 the global production image does not refresh existing sandboxes implicitly.
 
+To replace one sandbox's image while keeping its incarnation generation, use
+an explicitly approved digest-pinned image reference:
+
+```sh
+warpmetal sandbox action \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --action patch_image \
+  --confirm patch_image \
+  --image-digest <registry/image@sha256:64-lowercase-hex-digest> \
+  --wait \
+  --json
+```
+
+This also briefly disconnects active sessions. The reference must contain an
+immutable SHA-256 digest; tags alone are refused. `--image-digest` is supported
+only for `patch_image`. Its wait requires the exact requested observed digest
+and the accepted generation, so a still-running old container is not completion.
+
 Manual deletion is irreversible:
 
 ```sh

package/src/account-gateway.js

@@ -0,0 +1,217 @@
+import { CliError } from "./errors.js";
+import { AccountSessionStore } from "./account-session.js";
+import {
+  CustomerAuthClient,
+  DEFAULT_ACCOUNT_ORIGIN,
+  DEFAULT_IDENTITY_ORIGIN,
+  validateOrigin,
+} from "./customer-auth.js";
+import { USER_AGENT } from "./version.js";
+
+function safeGatewayCode(data) {
+  const value = data?.code ?? data?.error?.code;
+  return typeof value === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(value)
+    ? value
+    : "unavailable";
+}
+
+function allowedAccountRoute(method, path) {
+  if (typeof path !== "string" || !path.startsWith("/")) return false;
+  if (method === "POST") return path === "/account/cli/orders";
+  if (method !== "GET") return false;
+  return (
+    [
+      "/account/cli/whoami",
+      "/account/cli/devices",
+      "/account/cli/orders",
+    ].includes(path) ||
+    /^\/account\/cli\/(?:devices|orders)\/[^/?#]+$/.test(path)
+  );
+}
+
+export class AccountGatewayClient {
+  constructor({
+    accountOrigin,
+    accessToken,
+    scopes = [],
+    fetchImpl = globalThis.fetch,
+    timeoutMs = 30_000,
+  } = {}) {
+    this.accountOrigin = validateOrigin(
+      accountOrigin || DEFAULT_ACCOUNT_ORIGIN,
+      "WarpMetal account URL",
+    );
+    if (typeof accessToken !== "string" || accessToken.length === 0) {
+      throw new CliError("A WarpMetal account access token is required.", {
+        exitCode: 4,
+        code: "invalid_token",
+      });
+    }
+    this.accessToken = accessToken;
+    this.scopes = scopes;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(method, path, { body, idempotencyKey } = {}) {
+    if (!allowedAccountRoute(method, path)) {
+      throw new CliError("The requested account gateway route is not allowed.", {
+        exitCode: 2,
+        code: "account_route_not_allowed",
+      });
+    }
+    const url = new URL(path, `${this.accountOrigin}/`);
+    if (url.origin !== this.accountOrigin || `${url.pathname}${url.search}${url.hash}` !== path) {
+      throw new CliError("The requested account gateway route is not allowed.", {
+        exitCode: 2,
+        code: "account_route_not_allowed",
+      });
+    }
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${this.accessToken}`,
+      "User-Agent": USER_AGENT,
+    };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        redirect: "manual",
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch {
+      throw new CliError(`Could not reach ${url.origin}.`, {
+        exitCode: 3,
+        code: "unavailable",
+      });
+    }
+    if (response.status >= 300 && response.status < 400) {
+      throw new CliError("The account gateway refused an HTTP redirect.", {
+        exitCode: 3,
+        code: "redirect_refused",
+      });
+    }
+    let data;
+    try {
+      const text = await response.text();
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      throw new CliError("The account gateway returned an invalid response.", {
+        exitCode: 3,
+        code: "invalid_response",
+      });
+    }
+    if (!response.ok) {
+      const code = safeGatewayCode(data);
+      throw new CliError(`Account request failed: ${code} (HTTP ${response.status}).`, {
+        exitCode: response.status === 401 || response.status === 403 ? 4 : 3,
+        code,
+      });
+    }
+    return data;
+  }
+
+  whoami() {
+    return this.request("GET", "/account/cli/whoami");
+  }
+
+  orders() {
+    return this.request("GET", "/account/cli/orders");
+  }
+
+  order(id) {
+    return this.request("GET", `/account/cli/orders/${encodeURIComponent(id)}`);
+  }
+
+  devices() {
+    return this.request("GET", "/account/cli/devices");
+  }
+
+  device(id) {
+    return this.request("GET", `/account/cli/devices/${encodeURIComponent(id)}`);
+  }
+
+  prepareOrder(body, idempotencyKey) {
+    if (!this.scopes.includes("cli:write")) {
+      throw new CliError("This account session does not include cli:write.", {
+        exitCode: 4,
+        code: "insufficient_scope",
+      });
+    }
+    return this.request("POST", "/account/cli/orders", { body, idempotencyKey });
+  }
+}
+
+export function accountSessionContext({
+  stateDirectory,
+  identityOrigin = DEFAULT_IDENTITY_ORIGIN,
+  accountOrigin = DEFAULT_ACCOUNT_ORIGIN,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const checkedIdentity = validateOrigin(identityOrigin, "WarpMetal Identity URL");
+  const checkedAccount = validateOrigin(accountOrigin, "WarpMetal account URL");
+  return {
+    identityOrigin: checkedIdentity,
+    accountOrigin: checkedAccount,
+    auth: new CustomerAuthClient({
+      identityOrigin: checkedIdentity,
+      accountOrigin: checkedAccount,
+      fetchImpl,
+    }),
+    store: new AccountSessionStore(stateDirectory, {
+      identityOrigin: checkedIdentity,
+      accountOrigin: checkedAccount,
+    }),
+    fetchImpl,
+  };
+}
+
+export async function authenticatedAccountClient(options) {
+  const context = accountSessionContext(options);
+  return context.store.withLock(async () => {
+    let session = await context.store.read();
+    if (!session) return null;
+    if (Date.parse(session.accessExpiresAt) <= Date.now() + 30_000) {
+      let refreshed;
+      try {
+        refreshed = await context.auth.refresh(
+          session.refreshToken,
+          session.scopes,
+        );
+      } catch (error) {
+        await context.store.clear();
+        if (error?.code === "unavailable") {
+          throw new CliError(
+            "Refresh completion is unknown, so the saved session was cleared. Run warpmetal login again.",
+            { exitCode: 3, code: "refresh_ambiguous" },
+          );
+        }
+        throw error;
+      }
+      try {
+        session = { ...session, ...refreshed, refreshedAt: new Date().toISOString() };
+        await context.store.write(session);
+      } catch (error) {
+        await context.store.clear();
+        throw new CliError(
+          "The rotated account session could not be saved, so local credentials were cleared. Run warpmetal login again.",
+          { exitCode: 3, code: "refresh_ambiguous" },
+        );
+      }
+    }
+    return {
+      client: new AccountGatewayClient({
+        accountOrigin: context.accountOrigin,
+        accessToken: session.accessToken,
+        scopes: session.scopes,
+        fetchImpl: context.fetchImpl,
+      }),
+      session,
+      context,
+    };
+  });
+}

package/src/account-session.js

@@ -0,0 +1,209 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmod,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  stat,
+  unlink,
+} from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { CliError } from "./errors.js";
+
+const SESSION_VERSION = 1;
+const LOCK_WAIT_MS = 45_000;
+const LOCK_STALE_MS = 30_000;
+
+function sessionKey(identityOrigin, accountOrigin) {
+  return createHash("sha256")
+    .update(`${identityOrigin}\n${accountOrigin}\n`, "utf8")
+    .digest("hex");
+}
+
+async function privateDirectory(path) {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  if (process.platform !== "win32") await chmod(path, 0o700);
+}
+
+async function atomicWrite(path, value) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporary, path);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+  if (process.platform !== "win32") await chmod(path, 0o600);
+}
+
+function validateSession(value, identityOrigin, accountOrigin) {
+  if (
+    !value ||
+    value.version !== SESSION_VERSION ||
+    value.identityOrigin !== identityOrigin ||
+    value.accountOrigin !== accountOrigin ||
+    typeof value.accessToken !== "string" ||
+    typeof value.refreshToken !== "string" ||
+    !value.refreshToken.startsWith("wmclr_") ||
+    typeof value.accessExpiresAt !== "string" ||
+    !Number.isFinite(Date.parse(value.accessExpiresAt)) ||
+    !Array.isArray(value.scopes) ||
+    value.scopes.length === 0 ||
+    new Set(value.scopes).size !== value.scopes.length ||
+    value.scopes.some((scope) => !["cli:read", "cli:write"].includes(scope)) ||
+    !value.scopes.includes("cli:read")
+  ) {
+    throw new CliError(
+      "The saved WarpMetal account session is invalid. Run warpmetal logout, then login again.",
+      { code: "invalid_session" },
+    );
+  }
+  return value;
+}
+
+function processExists(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function pause(milliseconds) {
+  return new Promise((resolvePause) => setTimeout(resolvePause, milliseconds));
+}
+
+export class AccountSessionStore {
+  constructor(directory, { identityOrigin, accountOrigin } = {}) {
+    if (typeof directory !== "string" || directory.length === 0) {
+      throw new CliError("A WarpMetal state directory is required.", {
+        exitCode: 2,
+      });
+    }
+    this.stateDirectory = isAbsolute(directory) ? directory : resolve(directory);
+    this.identityOrigin = identityOrigin;
+    this.accountOrigin = accountOrigin;
+    this.directory = join(this.stateDirectory, "account-sessions");
+    const key = sessionKey(identityOrigin, accountOrigin);
+    this.path = join(this.directory, `${key}.json`);
+    this.lockPath = join(this.directory, `${key}.lock`);
+  }
+
+  async read() {
+    try {
+      const value = JSON.parse(await readFile(this.path, "utf8"));
+      return validateSession(value, this.identityOrigin, this.accountOrigin);
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      if (error instanceof CliError) throw error;
+      throw new CliError(
+        "The saved WarpMetal account session could not be read. Run warpmetal logout, then login again.",
+        { code: "invalid_session" },
+      );
+    }
+  }
+
+  async write(session) {
+    await privateDirectory(this.directory);
+    await atomicWrite(
+      this.path,
+      validateSession(
+        {
+          ...session,
+          version: SESSION_VERSION,
+          identityOrigin: this.identityOrigin,
+          accountOrigin: this.accountOrigin,
+        },
+        this.identityOrigin,
+        this.accountOrigin,
+      ),
+    );
+  }
+
+  async clear() {
+    try {
+      await unlink(this.path);
+      return true;
+    } catch (error) {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+
+  async #recoverStaleLock() {
+    let info;
+    try {
+      info = await stat(this.lockPath);
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+    if (Date.now() - info.mtimeMs < LOCK_STALE_MS) return;
+    let owner;
+    try {
+      owner = JSON.parse(await readFile(this.lockPath, "utf8"));
+    } catch {
+      owner = null;
+    }
+    if (owner && processExists(owner.pid)) return;
+    try {
+      await unlink(this.lockPath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+
+  async withLock(callback) {
+    await privateDirectory(this.directory);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    let handle;
+    while (!handle) {
+      try {
+        const candidate = await open(this.lockPath, "wx", 0o600);
+        try {
+          await candidate.writeFile(
+            `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+            "utf8",
+          );
+          await candidate.sync();
+          handle = candidate;
+        } catch (error) {
+          await candidate.close().catch(() => {});
+          await unlink(this.lockPath).catch(() => {});
+          throw error;
+        }
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        await this.#recoverStaleLock();
+        if (Date.now() >= deadline) {
+          throw new CliError(
+            "Another WarpMetal process is updating this account session. Try again.",
+            { exitCode: 3, code: "session_locked" },
+          );
+        }
+        await pause(50 + Math.floor(Math.random() * 75));
+      }
+    }
+    try {
+      return await callback();
+    } finally {
+      await handle.close();
+      try {
+        await unlink(this.lockPath);
+      } catch (error) {
+        if (error?.code !== "ENOENT") throw error;
+      }
+    }
+  }
+}