unfazed 0.6.1 → 0.8.1

package/dist/unfazed.js

@@ -1,5 +1,5 @@
 import { UnfazedClient } from "./client.js";
-import { DEPLOYMENT_NOT_FOUND, UnfazedConflictError, UnfazedDeployError, UnfazedGraphQLError, UnfazedNotFoundError, UnfazedRunError, WORKSPACE_NOT_FOUND, isDuplicateWorkspaceName, isNotFoundSentinel as isNotFound, looksLikeCASConflict, } from "./errors.js";
+import { DEPLOYMENT_NOT_FOUND, UnfazedConflictError, UnfazedDeployError, UnfazedError, UnfazedGraphQLError, UnfazedNotFoundError, UnfazedRunError, UnfazedTimeoutError, UnfazedUnconfirmedAppsError, UnfazedWriteError, WORKSPACE_NOT_FOUND, isAppNotFound, isDuplicateWorkspaceName, isNotFoundSentinel as isNotFound, isUnconfirmedAppsRefusal, isTooManyWaits, isUnsupportedField, looksLikeCASConflict, } from "./errors.js";
 import * as ops from "./operations.js";
 import { pollWithBackoff, resolveWaitOptions } from "./wait.js";
 /**
@@ -44,41 +44,103 @@ export class Unfazed {
         return data.workspaces;
     }
     /**
-     * Deletes a workspace and everything anchored to it — deployments, env, and
-     * a BOX's persistent data disk. Not recoverable.
+     * Deletes a workspace — its files, env and secrets, and a BOX's persistent
+     * data disk — and, with `withDeployments`, every app it serves.
      *
-     * **The cascade is opt-out, not opt-in.** The server refuses to delete a
-     * workspace that has ANY deployment history — including FAILED records, and
-     * including deployments whose alias was long since taken over by something
-     * else — unless the mutation carries `withDeployments`. Since almost every
-     * workspace an agent creates gets deployed at least once, defaulting to
-     * `false` would make this method fail on nearly every real workspace, so it
-     * defaults to **`true`**: the behaviour this docstring has always promised.
-     *
-     * Pass `withDeployments: false` for the strict variant, which refuses rather
-     * than cascading and is the safer choice when you are deleting a workspace
-     * you did not create:
+     * A workspace can serve several apps (each `unfazed.json` `apps[]` entry, or
+     * several aliases deployed into it), so deleting one with its deployments is
+     * never implicit: **name exactly the apps it takes offline** in
+     * `confirmAliases`. The server compares them with the workspace's live apps
+     * and refuses, deleting nothing, on a missing or extra alias; the refusal
+     * ({@link UnfazedUnconfirmedAppsError}) lists every live app with its
+     * domains. The SDK never fills the list in: look it up deliberately with
+     * {@link liveApps} and decide. To delete one app and keep the rest, use
+     * {@link deleteApp}.
      *
      * ```ts
-     * await unfazed.deleteWorkspace(ws.id);                            // cascade
-     * await unfazed.deleteWorkspace(ws.id, { withDeployments: false }); // refuse if deployed
-     * await unfazed.deleteWorkspace(id, { ignoreNotFound: true });      // false, not a throw
+     * await unfazed.deleteWorkspace(ws.id);   // only when no deployment is left
+     * await unfazed.deleteWorkspace(ws.id, { withDeployments: true, confirmAliases: ["web", "api"] });
+     * await unfazed.deleteWorkspace(ws.id, { withDeployments: true, confirmAliases: [] }); // serves no app
+     * await unfazed.deleteWorkspace(id, { ignoreNotFound: true });   // false, not a throw
      * ```
      *
+     * Without `withDeployments` the server refuses while ANY deployment record
+     * is left — FAILED ones included — with `still has deployments; delete them
+     * first`. A workspace whose deploys all failed serves no app: delete it with
+     * `withDeployments: true, confirmAliases: []`.
+     *
+     * What is deleted disappears at once — gone from your views, its names and
+     * aliases free, its VMs stopped — but the platform keeps it for 30 days:
+     * within that time support (the platform operator) can restore it exactly
+     * as it was. You cannot restore it yourself; ask support. After 30 days it
+     * is erased for good.
+     *
      * With `ignoreNotFound` a workspace that is absent (or belongs to someone
      * else — the server returns one indistinguishable sentinel for both, on
      * purpose) resolves to `false` instead of throwing, which makes teardown in
      * a `finally` block idempotent.
      */
     async deleteWorkspace(workspaceId, options = {}) {
-        const withDeployments = options.withDeployments ?? true;
+        const withDeployments = options.withDeployments === true;
+        const confirmAliases = options.confirmAliases;
+        // The types already require both together; these guard plain JavaScript
+        // callers, before anything is sent.
+        if (withDeployments && !Array.isArray(confirmAliases)) {
+            throw new UnfazedError(`unfazed: nothing was deleted: deleteWorkspace("${workspaceId}", { withDeployments: true }) ` +
+                "takes every app the workspace serves offline, so it needs confirmAliases naming exactly " +
+                `those apps ([] when it serves none). Look them up with unfazed.liveApps("${workspaceId}"); ` +
+                "to delete one app, use unfazed.deleteApp.");
+        }
+        if (!withDeployments && confirmAliases !== undefined) {
+            throw new UnfazedError("unfazed: nothing was deleted: confirmAliases applies only with withDeployments: true.");
+        }
         try {
-            const data = await this.client.mutate(ops.DeleteWorkspaceDocument, { workspaceID: workspaceId, withDeployments }, options);
+            const data = await this.client.mutate(ops.DeleteWorkspaceDocument, withDeployments
+                ? { workspaceID: workspaceId, withDeployments, confirmAliases: [...confirmAliases] }
+                : { workspaceID: workspaceId, withDeployments }, options);
             return data.deleteWorkspace.ok;
         }
         catch (e) {
             if (options.ignoreNotFound && isNotFound(e, WORKSPACE_NOT_FOUND))
                 return false;
+            if (isUnconfirmedAppsRefusal(e)) {
+                throw new UnfazedUnconfirmedAppsError(workspaceId, [...(confirmAliases ?? [])], e.errors, e.data);
+            }
+            throw e;
+        }
+    }
+    /**
+     * The apps a workspace serves right now, by alias, with the deployment
+     * serving each and its custom domains: everything
+     * `deleteWorkspace(id, { withDeployments: true, … })` takes offline, and the
+     * exact list its `confirmAliases` must name.
+     *
+     * It is a lookup for you to read, not something to pipe into a delete
+     * unseen: check that the apps are the ones you mean to take down.
+     *
+     * ```ts
+     * const live = await unfazed.liveApps(ws.id);   // [{ alias: "web", deploymentID, domains: [] }, …]
+     * ```
+     *
+     * Throws {@link UnfazedNotFoundError} when the workspace is absent or not
+     * visible to this token.
+     */
+    async liveApps(workspaceId, options) {
+        const data = await this.client.query(ops.WorkspaceLiveAppsDocument, { id: workspaceId }, options);
+        if (!data.workspace) {
+            throw new UnfazedNotFoundError(`unfazed: workspace ${workspaceId} not found`);
+        }
+        return data.workspace.liveApps;
+    }
+    async deleteApp(app, options = {}) {
+        try {
+            const data = await this.client.mutate(ops.DeleteAppDocument, { workspaceID: app.workspaceId, alias: app.alias }, options);
+            return data.deleteApp;
+        }
+        catch (e) {
+            if (options.ignoreNotFound && (isNotFound(e, WORKSPACE_NOT_FOUND) || isAppNotFound(e, app.alias))) {
+                return null;
+            }
             throw e;
         }
     }
@@ -120,48 +182,143 @@ export class Unfazed {
     }
     /* ------------------------------------------------------------------- files */
     /**
-     * Writes many files in as few requests as possible.
-     *
-     * The API is one-file-per-mutation, so writing a 12-file app naively costs 12
-     * round trips. This batches them into a single GraphQL document with one
-     * ALIASED root field per file (`f0: writeWorkspaceTextFile(...)`,
-     * `f1: ...`), which the server resolves in one request.
+     * Writes many files in ONE request — and, on an app with platform git, ONE
+     * commit — exactly as MCP `write_workspace_files` does.
      *
      * ```ts
-     * await unfazed.writeFiles(ws.id, {
+     * const out = await unfazed.writeFiles(ws.id, {
      *   "server.ts": serverCode,
-     *   "unfazed.json": JSON.stringify({ entry: "server.ts" }),
+     *   "package.json": JSON.stringify(pkg),
      *   "public/logo.png": { bytes: pngBytes },
-     * });
+     * }, { commitMessage: "Add the server" });
+     * out.commit;   // { sha, committed, waiting, conflicts, writeSHA, … } or null
      * ```
      *
-     * Batches are NOT atomic: GraphQL resolves each aliased field independently,
-     * so a partial failure leaves earlier writes committed. The thrown
-     * {@link UnfazedGraphQLError} carries `data` with whichever aliases
-     * succeeded, and `error.path` identifies the ones that did not.
+     * A call is not transactional: files are written in order, each atomically,
+     * and a file's failure does not undo the others. When any file fails this
+     * throws {@link UnfazedWriteError} (its `result` lists what was written and
+     * `failed` what was not; retry only those), unless `allowPartial`. A
+     * repeated path keeps its last content.
+     *
+     * On an app with platform git the commit is made before any file is
+     * written: if it fails, the request fails and nothing is written. `commit`
+     * may come back `waiting` — the files are saved and the commit lands in
+     * order; pass `waitForCommit: true` (or call {@link waitForCommit}) to
+     * resolve only once it has. See {@link FileCommit} for saved, committed and
+     * deployed.
+     *
+     * One request carries up to 100 files and 32 MiB; a bigger map is split
+     * into several requests, each its own commit (`commits`). On a platform
+     * older than the batch write the SDK falls back to one mutation per file
+     * (one commit each) and reports `commit: null`.
      */
     async writeFiles(workspaceId, files, options = {}) {
         const entries = Object.entries(files).map(([path, content]) => normalizeFile(path, content));
+        const result = {
+            workspaceId,
+            files: [],
+            written: 0,
+            failed: 0,
+            totalBytes: 0,
+            commit: null,
+            commits: [],
+        };
         if (entries.length === 0)
-            return [];
-        const batchSize = options.batchSize ?? 20;
-        const maxBatchBytes = options.maxBatchBytes ?? 4 * 1024 * 1024;
-        const written = [];
+            return result;
+        const batchSize = Math.min(options.batchSize ?? MAX_BATCH_FILES, MAX_BATCH_FILES);
+        const maxBatchBytes = options.maxBatchBytes ?? MAX_BATCH_BYTES;
+        const requestOptions = options.signal ? { signal: options.signal } : {};
         for (const batch of chunkFiles(entries, batchSize, maxBatchBytes)) {
-            written.push(...(await this.#writeBatch(workspaceId, batch, options.signal)));
+            const written = this.#legacyWrites
+                ? await this.#writeBatchLegacy(workspaceId, batch, requestOptions)
+                : await this.#writeBatch(workspaceId, batch, options.commitMessage, requestOptions);
+            result.files.push(...written.files);
+            result.written += written.written;
+            result.failed += written.failed;
+            result.totalBytes += written.totalBytes;
+            if (written.commit) {
+                result.commits.push(written.commit);
+                result.commit = written.commit;
+            }
+        }
+        // Only a waiting commit lands by itself; a paused one waits for the
+        // operator's recovery, which no client wait should block on.
+        if (options.waitForCommit && result.commits.some((c) => c.waiting)) {
+            const waitOptions = options.waitForCommit === true ? {} : options.waitForCommit;
+            result.landed = await this.waitForCommit(workspaceId, {
+                ...waitOptions,
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+        }
+        if (result.failed > 0 && !options.allowPartial) {
+            throw new UnfazedWriteError(result, result.files.filter((f) => !f.ok).map((f) => ({ path: f.path, error: f.error ?? "not written" })));
         }
-        return written;
+        return result;
     }
-    /** Writes one text file. Prefer {@link writeFiles} for more than one. */
-    async writeFile(workspaceId, path, text, options) {
-        const data = await this.client.mutate(ops.WriteTextFileDocument, { workspaceID: workspaceId, path, text }, options);
-        return data.writeWorkspaceTextFile.file;
+    /**
+     * Writes one text file: {@link writeFiles} with one entry, so it is one
+     * commit with `commitMessage` on an app with platform git, and the answer
+     * carries that commit. Throws {@link UnfazedWriteError} when it is refused.
+     */
+    async writeFile(workspaceId, path, text, options = {}) {
+        return this.#writeOne(workspaceId, path, text, options);
+    }
+    /** Writes one binary file (raw bytes or base64), like {@link writeFile}. */
+    async writeBinaryFile(workspaceId, path, content, options = {}) {
+        const file = content instanceof Uint8Array || content instanceof ArrayBuffer ? { bytes: content } : content;
+        return this.#writeOne(workspaceId, path, file, options);
     }
-    /** Writes one binary file. Accepts raw bytes or a base64 string. */
-    async writeBinaryFile(workspaceId, path, content, options) {
-        const contentBase64 = "base64" in content ? content.base64 : toBase64(content);
-        const data = await this.client.mutate(ops.WriteBase64FileDocument, { workspaceID: workspaceId, path, contentBase64 }, options);
-        return data.writeWorkspaceBase64File.file;
+    async #writeOne(workspaceId, path, content, options) {
+        const out = await this.writeFiles(workspaceId, { [path]: content }, options);
+        const file = out.files[0]?.file;
+        if (!file)
+            throw new UnfazedError(`unfazed: ${path} was not written`);
+        return { ...file, commit: out.commit };
+    }
+    /**
+     * Waits until no file write of the app waits for its commit: platform git
+     * commits a write at once, but when the git server is slow the write is
+     * saved and its commit `waiting`, landing in order. Resolves with the
+     * branch head then — every write made before the call is in its history.
+     * An app without platform git resolves at once (`head: null`).
+     *
+     * Default timeout 2 minutes; throws {@link UnfazedTimeoutError} past it
+     * (the writes stay saved, and still land).
+     */
+    async waitForCommit(workspaceId, waitOptions = {}) {
+        const resolved = resolveWaitOptions({
+            timeoutMs: 120_000,
+            initialIntervalMs: 250,
+            maxIntervalMs: 2_000,
+            ...waitOptions,
+        });
+        const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
+        const started = resolved.now();
+        let waiting = 0;
+        return pollWithBackoff(async () => {
+            let page;
+            try {
+                page = (await this.client.query(ops.AppCommitsWaitingDocument, { workspaceID: workspaceId }, requestOptions))
+                    .appCommits;
+            }
+            catch (e) {
+                if (!(e instanceof UnfazedGraphQLError))
+                    throw e;
+                // The history can be unreadable while writes still wait: keep waiting.
+                if (e.errors.some((x) => /waiting to be committed/i.test(x.message)))
+                    return { done: false };
+                // An app without platform git has no commits to wait for.
+                if (e.errors.some((x) => NO_PLATFORM_GIT.test(x.message))) {
+                    return { done: true, value: { branch: "", head: null, waitedMs: resolved.now() - started } };
+                }
+                throw e;
+            }
+            waiting = page.waitingCommits;
+            if (page.waitingCommits > 0)
+                return { done: false };
+            return { done: true, value: { branch: page.branch, head: page.head ?? null, waitedMs: resolved.now() - started } };
+        }, resolved, () => new UnfazedTimeoutError(`unfazed: ${waiting} write(s) of workspace ${workspaceId} still wait for their commit after ${resolved.timeoutMs}ms; ` +
+            "they are saved and land in order"));
     }
     /** Lists workspace files (paginated). */
     async listFiles(workspaceId, input = {}, options) {
@@ -266,29 +423,193 @@ export class Unfazed {
     }
     async #deploy(input, options) {
         const requestOptions = options.signal ? { signal: options.signal } : {};
+        const now = options.waitOptions?.now ?? (() => Date.now());
+        const sent = now();
         const data = await this.client.mutate(ops.CreateDeploymentDocument, { input }, requestOptions);
         const deployment = data.createDeployment.deployment;
         if (!options.wait)
             return deployment;
-        return this.waitForDeployment(deployment.id, {
+        const created = now();
+        const waited = await this.#waitTerminal(deployment.id, {
             ...options.waitOptions,
             ...(options.signal ? { signal: options.signal } : {}),
         });
+        const seen = now();
+        const timings = {
+            client: {
+                createMs: created - sent,
+                waitMs: seen - created,
+                totalMs: seen - sent,
+                waitRequests: waited.requests,
+                waitMode: waited.mode,
+            },
+            platform: null,
+        };
+        if (options.timings !== false) {
+            timings.platform = await this.#readyTimings(deployment.id, options.waitOptions, requestOptions);
+        }
+        return { ...waited.deployment, timings };
     }
     /**
-     * Polls a deployment until it is READY, throwing on FAILED or timeout.
+     * Waits until a deployment is READY, throwing {@link UnfazedDeployError} on
+     * FAILED or timeout (default 10 minutes).
+     *
+     * It waits SERVER-SIDE (MCP `wait_for_deployment`): each request blocks on
+     * the control plane until the deployment leaves BUILDING — woken by the
+     * deploy pipeline itself — or 45 s pass, and comes back with the full
+     * deployment; so READY reaches you one round trip after it happens, not at
+     * the next poll. A NEW app that starts directly on its server is READY
+     * before it serves there; the wait covers that landing too. On a platform
+     * without the server-side wait, or when the platform refuses one because
+     * the account already holds its cap of waits in progress (16), it polls
+     * instead (`waitOptions.mode: "poll"` forces that), every 0.5 s backing
+     * off to 3 s by default.
      *
-     * BUILDING is the only non-terminal status; READY and FAILED are terminal.
-     * The poll query selects six fields rather than the full deployment, because
-     * this runs every few seconds for potentially minutes — then the READY
-     * deployment is re-read in full so callers get the same shape `deployService`
-     * returns without `wait`.
+     * Pass a {@link CommitDeploymentTarget} instead of an id to wait for the
+     * deploy a git import makes of a commit — a restore, a push or a sync
+     * deploys before any id exists. The wait covers the import too, and
+     * {@link UnfazedDeployError} carries the import's error when it failed on
+     * the commit.
+     *
+     * ```ts
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha });
+     * await unfazed.waitForDeployment({
+     *   workspaceId: back.workspaceID, gitCommit: back.sha, alias: back.deployAlias, after: back.waitAfter,
+     * });
+     * ```
      */
-    async waitForDeployment(deploymentId, waitOptions = {}) {
+    async waitForDeployment(target, waitOptions = {}) {
+        if (typeof target !== "string")
+            return (await this.#commitWait(target, waitOptions)).deployment;
+        return (await this.#waitTerminal(target, waitOptions)).deployment;
+    }
+    async #waitTerminal(deploymentId, waitOptions) {
+        const now = waitOptions.now ?? (() => Date.now());
+        const started = now();
+        if ((waitOptions.mode ?? "server") === "server" && !this.#noServerWait) {
+            try {
+                return await this.#serverWait(deploymentId, waitOptions);
+            }
+            catch (e) {
+                if (isUnsupportedField(e, "waitForDeployment")) {
+                    // An older platform: poll, and do not ask again on this instance.
+                    this.#noServerWait = true;
+                }
+                else if (!isTooManyWaits(e)) {
+                    throw e;
+                }
+                // Past the platform's cap on waits in progress (many parallel waits
+                // of one account): this wait polls instead, for what is left of its
+                // budget.
+            }
+        }
+        const timeoutMs = Math.max(0, (waitOptions.timeoutMs ?? 600_000) - (now() - started));
+        return this.#pollWait(deploymentId, { ...waitOptions, timeoutMs });
+    }
+    async #serverWait(deploymentId, waitOptions) {
         const resolved = resolveWaitOptions(waitOptions);
+        const deadline = resolved.now() + resolved.timeoutMs;
+        let last = null;
+        let landing = false;
+        for (let requests = 1;; requests++) {
+            if (resolved.signal?.aborted)
+                throw new UnfazedTimeoutError("unfazed: wait aborted");
+            const remaining = deadline - resolved.now();
+            if (requests > 1 && remaining <= 0) {
+                throw new UnfazedDeployError("TIMEOUT", deploymentId, last, `unfazed: deployment ${deploymentId} still ${last?.status ?? "BUILDING"}` +
+                    `${landing ? " (READY, still landing on its server)" : ""} after ${resolved.timeoutMs}ms`);
+            }
+            const seconds = Math.max(1, Math.min(SERVER_WAIT_SECONDS, Math.ceil(remaining / 1000)));
+            let answer;
+            try {
+                answer = (await this.client.query(ops.WaitForDeploymentDocument, { id: deploymentId, timeoutSeconds: seconds }, 
+                // The request is a long poll: give it the wait plus a round trip,
+                // whatever the client's default per-request timeout is.
+                { ...(resolved.signal ? { signal: resolved.signal } : {}), timeoutMs: (seconds + 30) * 1000 })).waitForDeployment;
+            }
+            catch (e) {
+                if (isNotFound(e, DEPLOYMENT_NOT_FOUND)) {
+                    throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
+                }
+                throw e;
+            }
+            // By id the platform always answers the deployment; null is only for a
+            // wait by commit before the import made it.
+            const d = answer.deployment;
+            if (!d)
+                throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
+            last = d;
+            if (answer.timedOut) {
+                landing = d.status === "READY";
+                continue;
+            }
+            if (d.status === "READY")
+                return { deployment: d, requests, mode: "server" };
+            throw new UnfazedDeployError("FAILED", deploymentId, d, `unfazed: deployment ${deploymentId} ${d.status}${d.error ? `: ${d.error}` : ""}`);
+        }
+    }
+    /**
+     * The server-side wait by commit: for the import to make the commit's
+     * deployment, then for it, one budget for both. There is nothing cheaper to
+     * poll, so a refusal past the platform's cap on waits in progress backs off
+     * (0.5 s up to 3 s) and asks again.
+     */
+    async #commitWait(target, waitOptions) {
+        const resolved = resolveWaitOptions(waitOptions);
+        const deadline = resolved.now() + resolved.timeoutMs;
+        const commit = target.gitCommit.slice(0, 7);
+        const what = `the deploy of ${commit}${target.alias ? ` to ${target.alias}` : ""}`;
+        let last = null;
+        let status = "IMPORTING";
+        let backoff = 500;
+        for (let requests = 1;; requests++) {
+            if (resolved.signal?.aborted)
+                throw new UnfazedTimeoutError("unfazed: wait aborted");
+            const remaining = deadline - resolved.now();
+            if (requests > 1 && remaining <= 0) {
+                throw new UnfazedDeployError("TIMEOUT", last?.id ?? "", last, `unfazed: ${what} still ${status} after ${resolved.timeoutMs}ms`);
+            }
+            const seconds = Math.max(1, Math.min(SERVER_WAIT_SECONDS, Math.ceil(remaining / 1000)));
+            let answer;
+            try {
+                answer = (await this.client.query(ops.WaitForCommitDeploymentDocument, {
+                    workspaceID: target.workspaceId,
+                    gitCommit: target.gitCommit,
+                    alias: target.alias ?? null,
+                    after: target.after ?? null,
+                    timeoutSeconds: seconds,
+                }, { ...(resolved.signal ? { signal: resolved.signal } : {}), timeoutMs: (seconds + 30) * 1000 })).waitForDeployment;
+            }
+            catch (e) {
+                if (!isTooManyWaits(e))
+                    throw e;
+                await resolved.sleep(Math.max(0, Math.min(backoff, deadline - resolved.now())), resolved.signal);
+                backoff = Math.min(backoff * 1.5, 3_000);
+                continue;
+            }
+            const d = answer.deployment;
+            status = answer.status;
+            if (d)
+                last = d;
+            if (answer.timedOut)
+                continue;
+            if (!d) {
+                // Not timed out and no deployment: the import failed on the commit
+                // and nothing imports any more, so no deployment of it is coming.
+                throw new UnfazedDeployError("FAILED", "", null, `unfazed: the import of ${commit} failed${answer.importError ? `: ${answer.importError}` : ""}`);
+            }
+            if (d.status === "READY")
+                return { deployment: d, requests };
+            throw new UnfazedDeployError("FAILED", d.id, d, `unfazed: deployment ${d.id} (${what}) ${d.status}${d.error ? `: ${d.error}` : ""}`);
+        }
+    }
+    async #pollWait(deploymentId, waitOptions) {
+        const resolved = resolveWaitOptions({ initialIntervalMs: 500, maxIntervalMs: 3_000, ...waitOptions });
         const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
         let last = null;
+        let requests = 0;
         await pollWithBackoff(async () => {
+            requests++;
             const data = await this.client.query(ops.PollDeploymentDocument, { id: deploymentId }, requestOptions);
             const d = data.deployment;
             if (!d) {
@@ -302,10 +623,43 @@ export class Unfazed {
             }
             return { done: false };
         }, resolved, () => new UnfazedDeployError("TIMEOUT", deploymentId, last, `unfazed: deployment ${deploymentId} still ${last?.status ?? "BUILDING"} after ${resolved.timeoutMs}ms`));
+        // The poll query is narrow; re-read the READY deployment in full so the
+        // answer has the shape deployService returns without `wait`.
         const full = await this.getDeployment(deploymentId, requestOptions);
         if (!full)
             throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
-        return full;
+        return { deployment: full, requests: requests + 1, mode: "poll" };
+    }
+    /**
+     * The platform's measured phases of a deploy ({@link PlatformTimings}), as
+     * it parses them from all of the deployment's timing events
+     * (`Deployment.timings`). Null when it recorded none (a deploy that is
+     * still building, or one from before timings existed), or for a deployment
+     * you cannot see.
+     */
+    async getDeploymentTimings(deploymentId, options) {
+        const data = await this.client.query(ops.DeploymentTimingsDocument, { id: deploymentId }, options);
+        const timings = data.deployment?.timings;
+        return timings ? toPlatformTimings(timings) : null;
+    }
+    /**
+     * The timings of a deploy that just went READY. `deployment.phases` is
+     * written right after the READY transition, so a read that races it is
+     * retried once.
+     */
+    async #readyTimings(deploymentId, waitOptions, requestOptions) {
+        try {
+            const first = await this.getDeploymentTimings(deploymentId, requestOptions);
+            if (first?.totalMs != null)
+                return first;
+            const sleep = waitOptions?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+            await sleep(250, requestOptions.signal);
+            return (await this.getDeploymentTimings(deploymentId, requestOptions)) ?? first;
+        }
+        catch {
+            // Timings are a diagnostic: never fail a deploy that went READY.
+            return null;
+        }
     }
     /** Reads one deployment by id. Null when absent. */
     async getDeployment(deploymentId, options) {
@@ -340,10 +694,25 @@ export class Unfazed {
         const data = await this.client.query(ops.ServiceLogsDocument, { deploymentID: deploymentId, tailBytes: input.tailBytes ?? null }, options);
         return data.serviceLogs;
     }
-    /** Deployment lifecycle events — build, boot, probe, cron, restarts. */
+    /**
+     * Deployment lifecycle events — build, boot, probe, cron, restarts — the
+     * most recent `limit` (default 20), oldest first.
+     *
+     * `type` is the event's own name, as MCP reports it:
+     * `"deployment.build_finished"`, `"deployment.phases"`,
+     * `"service.vm_started"`, `"service.crashed"`. (`typeEnum` keeps the GraphQL
+     * enum, which reads `UNKNOWN` for names it does not list.) Timing events
+     * carry their phases in `metadata`; {@link getDeploymentTimings} turns them
+     * into numbers.
+     *
+     * ```ts
+     * const events = await unfazed.getEvents(app.id, 50);
+     * events.filter((e) => e.type === "deployment.build_finished");
+     * ```
+     */
     async getEvents(deploymentId, limit, options) {
         const data = await this.client.query(ops.DeploymentEventsDocument, { deploymentID: deploymentId, limit: limit ?? null }, options);
-        return data.deploymentEvents;
+        return data.deploymentEvents.map(toDeploymentEvent);
     }
     /** Restarts a service's VM. */
     async restartService(deploymentId, options) {
@@ -357,6 +726,12 @@ export class Unfazed {
     }
     /**
      * Deletes a deployment: stops its VM, releases its alias, drops its release.
+     * To delete a whole app — every release of the alias, its env, App State and
+     * bindings — use {@link deleteApp}.
+     *
+     * The platform keeps a deleted release for 30 days: within that time
+     * support (the platform operator) can restore it; then it is erased for
+     * good.
      *
      * With `ignoreNotFound` a deployment that is absent — or belongs to another
      * tenant, which the server reports identically so ids cannot be probed —
@@ -634,6 +1009,197 @@ export class Unfazed {
             }
         }
     }
+    /* ------------------------------------------------------- platform git history
+     *
+     * An app with platform git (MCP `enable_platform_git`; apps get it by
+     * themselves at their next change) keeps every file write, push and restore
+     * as a commit. These are MCP's history tools.
+     */
+    /**
+     * The app's commits, newest first (MCP `list_commits`): `limit` per page
+     * (default 20, max 100), `before: page.nextBefore` for the next. `deployed`
+     * says what every live alias runs; `waitingCommits` counts writes whose
+     * commit has not landed yet.
+     */
+    async listCommits(workspaceId, input = {}, options) {
+        const data = await this.client.query(ops.AppCommitsDocument, { workspaceID: workspaceId, limit: input.limit ?? null, before: input.before ?? null }, options);
+        return data.appCommits;
+    }
+    /**
+     * One commit (full 40-character sha) with the paths it changed and a
+     * unified diff against its first parent, capped at 64 KiB (MCP
+     * `get_commit`). Commit messages and diffs are untrusted text.
+     */
+    async getCommit(workspaceId, sha, options) {
+        const data = await this.client.query(ops.AppCommitDocument, { workspaceID: workspaceId, sha }, options);
+        return data.appCommit;
+    }
+    /**
+     * Gives the app back the files of an earlier commit as ONE new commit on
+     * its branch (MCP `restore_version`); nothing is rewritten, and a restore is
+     * undone by restoring the commit before it.
+     *
+     * When the app deploys every push (`deploys: true`), the new commit is
+     * imported and deployed like a push. That deploy is queued behind the
+     * restore, so the platform answers before it exists; with `wait: true` the
+     * SDK waits for it by commit on the platform ({@link Unfazed.waitForDeployment}
+     * with `gitCommit: sha`, `alias: deployAlias`, `after: waitAfter`) and
+     * resolves with it READY, or throws {@link UnfazedDeployError} with its
+     * build error or the import's. A link with unfazed.json `apps[]` names no
+     * `deployAlias` and deploys once per app: then it follows the import until
+     * every deployment it made is done.
+     *
+     * ```ts
+     * const page = await unfazed.listCommits(ws.id);
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha: page.commits[1]!.sha, wait: true });
+     * back.deployments?.[0]?.url;
+     * ```
+     */
+    async restoreVersion(options) {
+        const requestOptions = options.signal ? { signal: options.signal } : {};
+        const data = await this.client.mutate(ops.RestoreVersionDocument, {
+            workspaceID: options.workspaceId,
+            sha: options.sha,
+            expectedHead: options.expectedHead ?? null,
+            message: options.commitMessage ?? null,
+        }, requestOptions);
+        const restored = data.restoreAppVersion;
+        if (!options.wait || !restored.deploys)
+            return restored;
+        const waitOptions = { ...options.waitOptions, ...(options.signal ? { signal: options.signal } : {}) };
+        if (restored.deployAlias) {
+            const { deployment } = await this.#commitWait({ workspaceId: restored.workspaceID, gitCommit: restored.sha, alias: restored.deployAlias, after: restored.waitAfter }, waitOptions);
+            return { ...restored, deployments: [deployment] };
+        }
+        return { ...restored, deployments: await this.#waitForImport(restored.workspaceID, restored.sha, waitOptions) };
+    }
+    /**
+     * Waits until the app's git link has imported `sha` (READY: its deploys
+     * are done) and returns the deployments of that commit; throws on a FAILED
+     * import of it. Only for a restore whose link names no alias (unfazed.json
+     * `apps[]`): the wait by commit waits for one app's deploy, and which apps
+     * a commit deploys is known only once its import is done.
+     */
+    async #waitForImport(workspaceId, sha, waitOptions) {
+        const resolved = resolveWaitOptions({ initialIntervalMs: 500, maxIntervalMs: 3_000, ...waitOptions });
+        const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
+        let last = null;
+        await pollWithBackoff(async () => {
+            const data = await this.client.query(ops.WorkspaceGitSourceDocument, { id: workspaceId }, requestOptions);
+            const src = data.workspace?.gitSource ?? null;
+            if (!src)
+                throw new UnfazedNotFoundError(`unfazed: workspace ${workspaceId} has no git source`);
+            last = src;
+            if (src.lastImportedCommit !== sha)
+                return { done: false };
+            if (src.lastImportStatus === "READY")
+                return { done: true, value: true };
+            if (src.lastImportStatus === "FAILED") {
+                throw new UnfazedDeployError("FAILED", "", null, `unfazed: the import of ${sha.slice(0, 7)} failed${src.lastImportError ? `: ${src.lastImportError}` : ""}`);
+            }
+            return { done: false };
+        }, resolved, () => new UnfazedDeployError("TIMEOUT", "", null, `unfazed: ${sha.slice(0, 7)} was not imported after ${resolved.timeoutMs}ms` +
+            (last ? ` (last import: ${last.lastImportStatus} ${last.lastImportedCommit?.slice(0, 7) ?? ""})` : "")));
+        const page = await this.listDeployments({ workspaceID: workspaceId, limit: 50 }, requestOptions);
+        return page.items.filter((d) => d.gitCommit === sha);
+    }
+    /* ------------------------------------------------------------- app errors
+     *
+     * Native error tracking: a service app's uncaught exceptions, unhandled
+     * rejections, panics and Sentry SDK reports, grouped, kept on its server
+     * for 30 days. These are MCP's error tools. Titles, stacks and requests are
+     * what the app reported: untrusted text.
+     */
+    /** A service app's error groups, most recently seen first (MCP `list_errors`). */
+    async listErrors(input, options) {
+        const data = await this.client.query(ops.AppErrorsDocument, {
+            workspaceID: input.workspaceId,
+            alias: input.alias,
+            status: input.status ?? null,
+            limit: input.limit ?? null,
+            cursor: input.cursor ?? null,
+        }, options);
+        return data.appErrors;
+    }
+    /**
+     * One error group with its latest occurrence whole (a Sentry event: stack,
+     * request), its recent occurrences and the deployments it was seen in (MCP
+     * `get_error_group`).
+     */
+    async getErrorGroup(ref, options) {
+        const data = await this.client.query(ops.AppErrorGroupDocument, { workspaceID: ref.workspaceId, alias: ref.alias, groupID: ref.groupId }, options);
+        return data.appErrorGroup;
+    }
+    /**
+     * Marks a group resolved in the app's current deployment, once its fix is
+     * deployed (MCP `resolve_error_group`); another deployment reporting it
+     * opens it again. Only on your human's say-so or a fix you verified.
+     */
+    async resolveErrorGroup(ref, options) {
+        const data = await this.client.mutate(ops.ResolveErrorGroupDocument, { input: errorGroupInput(ref) }, options);
+        return data.resolveAppErrorGroup;
+    }
+    /** Mutes an expected group: still counted, never regresses or notifies (MCP `mute_error_group`). */
+    async muteErrorGroup(ref, options) {
+        const data = await this.client.mutate(ops.MuteErrorGroupDocument, { input: errorGroupInput(ref) }, options);
+        return data.muteAppErrorGroup;
+    }
+    /** Opens a resolved or muted group again (MCP `reopen_error_group`). */
+    async reopenErrorGroup(ref, options) {
+        const data = await this.client.mutate(ops.ReopenErrorGroupDocument, { input: errorGroupInput(ref) }, options);
+        return data.reopenAppErrorGroup;
+    }
+    /* ------------------------------------------------------------------ events
+     *
+     * What happened to the apps, runs and domains you can see —
+     * deployment.finished, service.crashed, error.new, error.regressed,
+     * git.conflict, run.finished, … — instead of re-polling status. The same
+     * feed and cursors as MCP `poll_events` / `wait_for_events`.
+     */
+    /** The event types, with each one's filters and payload schema (MCP `list_event_types`). */
+    async listEventTypes(options) {
+        const data = await this.client.query(ops.EventTypesDocument, {}, options);
+        return data.platformEventTypes;
+    }
+    /**
+     * Events since `cursor` (MCP `poll_events`). Omit `cursor` to start from now
+     * — nothing is replayed — and pass the returned `cursor` back: at once while
+     * `hasMore`, otherwise after `nextPollMs`, or to {@link waitForEvents}.
+     * `truncated` means events may be missing: re-read state.
+     */
+    async pollEvents(input = {}, options) {
+        const data = await this.client.query(ops.PollEventsDocument, { input: eventsInput(input) }, options);
+        return data.pollEvents;
+    }
+    /**
+     * {@link pollEvents} that waits server-side until an event arrives (MCP
+     * `wait_for_events`), for up to `timeoutMs` (default 45 s; longer waits are
+     * several server waits of up to 45 s, continuing from each cursor). A
+     * timeout is not an error: the page has `timedOut: true`, no events and a
+     * cursor to wait again with. The platform caps an account's waits in
+     * progress (16, deploy waits included); past it this throws an error that
+     * `isTooManyWaits` recognizes: poll then.
+     *
+     * ```ts
+     * let page = await unfazed.pollEvents({ names: ["deployment.finished"] });   // from now
+     * page = await unfazed.waitForEvents({ names: ["deployment.finished"], cursor: page.cursor, timeoutMs: 120_000 });
+     * ```
+     */
+    async waitForEvents(input = {}, options = {}) {
+        const now = options.now ?? (() => Date.now());
+        const deadline = now() + (input.timeoutMs ?? SERVER_WAIT_SECONDS * 1000);
+        let cursor = input.cursor;
+        for (;;) {
+            const remaining = deadline - now();
+            const seconds = Math.max(1, Math.min(SERVER_WAIT_SECONDS, Math.ceil(remaining / 1000)));
+            const { now: _now, ...requestOptions } = options;
+            const data = await this.client.query(ops.WaitForEventsDocument, { input: eventsInput({ ...input, ...(cursor === undefined ? {} : { cursor }) }), timeoutSeconds: seconds }, { ...requestOptions, timeoutMs: (seconds + 30) * 1000 });
+            const page = data.waitForEvents;
+            if (!page.timedOut || deadline - now() <= 0)
+                return page;
+            cursor = page.cursor;
+        }
+    }
     /* --------------------------------------------------------------- agent runs
      *
      * A run is the past-tense counterpart to a deployment: boot a fresh VM off
@@ -854,7 +1420,47 @@ export class Unfazed {
         return (workspaces.find((w) => w.name === name) ??
             workspaces.find((w) => w.name.toLowerCase() === folded));
     }
-    async #writeBatch(workspaceId, batch, signal) {
+    /** Set once the platform turned out to predate writeWorkspaceFiles. */
+    #legacyWrites = false;
+    /** Set once the platform turned out to predate the server-side deployment wait. */
+    #noServerWait = false;
+    /** One request of {@link writeFiles}: one call of the batch mutation, one commit. */
+    async #writeBatch(workspaceId, batch, commitMessage, requestOptions) {
+        try {
+            const data = await this.client.mutate(ops.WriteFilesDocument, {
+                workspaceID: workspaceId,
+                files: batch.map((f) => ({
+                    path: f.path,
+                    content: f.content,
+                    ...(f.kind === "base64" ? { encoding: "base64" } : {}),
+                })),
+                commitMessage: commitMessage ?? null,
+            }, requestOptions);
+            const out = data.writeWorkspaceFiles;
+            return {
+                files: out.files.map((f) => ({ path: f.path, ok: f.ok, error: f.error ?? null, file: f.file ?? null })),
+                written: out.written,
+                failed: out.failed,
+                totalBytes: out.totalBytes,
+                commit: out.commit ?? null,
+            };
+        }
+        catch (e) {
+            if (!isUnsupportedField(e, "writeWorkspaceFiles") && !isUnsupportedField(e, "WorkspaceFileWriteInput"))
+                throw e;
+            // A platform older than the batch mutation: one mutation per file, as
+            // before 0.8.0. It reports no commit.
+            this.#legacyWrites = true;
+            return this.#writeBatchLegacy(workspaceId, batch, requestOptions);
+        }
+    }
+    /**
+     * The pre-0.8.0 batch: one document with one ALIASED single-file mutation
+     * per file. One request, but one commit per file on an app with platform
+     * git, and no commit in the answer. Used only against platforms without
+     * writeWorkspaceFiles.
+     */
+    async #writeBatchLegacy(workspaceId, batch, requestOptions) {
         const varDefs = ["$workspaceID: ID!"];
         const fields = [];
         const variables = { workspaceID: workspaceId };
@@ -867,13 +1473,185 @@ export class Unfazed {
                 : `  f${i}: writeWorkspaceBase64File(input: { workspaceID: $workspaceID, path: $p${i}, contentBase64: $c${i} }) { file { ${FILE_SELECTION} } }`);
         });
         // Built at runtime rather than codegen'd: the field COUNT varies per call,
-        // so no static document can express it. The field shapes are still fixed
-        // and typed below, and each individual mutation is codegen-validated by its
-        // single-file twin in operations.ts.
+        // so no static document can express it. The field shapes are still fixed,
+        // and each individual mutation is codegen-validated by its single-file
+        // twin in operations.ts.
         const document = `mutation SdkWriteFilesBatch(${varDefs.join(", ")}) {\n${fields.join("\n")}\n}`;
-        const data = await this.client.mutate(document, variables, signal ? { signal } : {});
-        return batch.map((_, i) => data[`f${i}`].file);
+        let data;
+        let errors = [];
+        try {
+            data = await this.client.mutate(document, variables, requestOptions);
+        }
+        catch (e) {
+            // Fields answered independently: keep what landed, name what did not.
+            if (!(e instanceof UnfazedGraphQLError) || !e.data)
+                throw e;
+            data = e.data;
+            errors = e.errors;
+        }
+        const files = batch.map((f, i) => {
+            const file = data[`f${i}`]?.file ?? null;
+            if (file)
+                return { path: f.path, ok: true, error: null, file };
+            const error = errors.find((x) => x.path?.[0] === `f${i}`)?.message ?? "not written";
+            return { path: f.path, ok: false, error, file: null };
+        });
+        const written = files.filter((f) => f.ok);
+        return {
+            files,
+            written: written.length,
+            failed: files.length - written.length,
+            totalBytes: written.reduce((sum, f) => sum + (f.file?.sizeBytes ?? 0), 0),
+            commit: null,
+        };
+    }
+}
+/** The platform's per-call limits of writeWorkspaceFiles (MCP's too). */
+const MAX_BATCH_FILES = 100;
+const MAX_BATCH_BYTES = 32 * 1024 * 1024;
+/** One server-side wait's budget, under the ~60 s a proxy or client allows a request. */
+const SERVER_WAIT_SECONDS = 45;
+/** How the platform says an app keeps no history in platform git. */
+const NO_PLATFORM_GIT = /platform git is not enabled|its history is there|has no git repository/i;
+/** The enum lists only the events it was written for; anything newer is UNKNOWN there. */
+function toDeploymentEvent(event) {
+    return {
+        id: event.id,
+        deploymentID: event.deploymentID,
+        type: event.rawType,
+        typeEnum: event.type,
+        rawType: event.rawType,
+        severity: event.severity,
+        message: event.message,
+        vmID: event.vmID ?? null,
+        metadata: event.metadata ?? null,
+        timings: event.timings ? toPlatformTimings(event.timings) : null,
+        createdAt: event.createdAt,
+    };
+}
+const BUILD_FINISHED_EVENT = "deployment.build_finished";
+const DEPLOY_PHASES_EVENT = "deployment.phases";
+/**
+ * A duration as the platform accepts one: a whole, non-negative number of
+ * milliseconds (a number, or a string of digits as metadata carries it). A
+ * fraction or anything else is not a duration; a negative one is a clock gone
+ * backwards. Both are dropped, as the platform drops them.
+ */
+function durationMs(value) {
+    let n;
+    if (typeof value === "number")
+        n = value;
+    else if (typeof value === "string" && /^[+-]?\d+$/.test(value.trim()))
+        n = Number(value.trim());
+    else
+        return null;
+    return Number.isSafeInteger(n) && n >= 0 ? n + 0 : null; // + 0: -0 is 0
+}
+/** The platform's structured timings, with every duration checked like the metadata's. */
+function toPlatformTimings(t) {
+    const phases = {};
+    if (t.phases && typeof t.phases === "object") {
+        for (const [name, value] of Object.entries(t.phases)) {
+            const ms = durationMs(value);
+            if (ms !== null)
+                phases[name] = ms;
+        }
+    }
+    const memory = durationMs(t.buildMemoryMiB);
+    return {
+        totalMs: durationMs(t.totalMs),
+        buildMs: durationMs(t.buildMs),
+        promoteMs: durationMs(t.promoteMs),
+        phases,
+        buildMode: t.buildMode || null,
+        artifactTransport: t.artifactTransport || null,
+        buildMemoryMiB: memory ? memory : null,
+    };
+}
+/**
+ * Timing-event metadata read exactly as the platform reads it
+ * (internal/usecases/deploy_timings.go): every `<name>_ms` that is a whole,
+ * non-negative number; `total` only from the READY summary.
+ */
+function timingsFromMetadata(metadata, ready) {
+    const out = {
+        totalMs: null,
+        buildMs: null,
+        promoteMs: null,
+        phases: {},
+        buildMode: metadata["build_mode"] || null,
+        artifactTransport: metadata["artifact_transport"] || null,
+        buildMemoryMiB: null,
+    };
+    for (const [key, raw] of Object.entries(metadata)) {
+        if (!key.endsWith("_ms") || key === "_ms")
+            continue;
+        const ms = durationMs(raw);
+        if (ms === null)
+            continue;
+        const name = key.slice(0, -3);
+        if (name === "total") {
+            if (ready)
+                out.totalMs = ms;
+        }
+        else if (name === "build")
+            out.buildMs = ms;
+        else if (name === "promote")
+            out.promoteMs = ms;
+        else
+            out.phases[name] = ms;
     }
+    const memory = durationMs(metadata["build_memory_mib"]);
+    if (memory)
+        out.buildMemoryMiB = memory;
+    return out;
+}
+/**
+ * A deploy's phases from its events, as the platform reads them: the latest
+ * `deployment.phases` (written when it went READY: build, promotion and its
+ * split, total) over the latest `deployment.build_finished` (the build VM's
+ * own phases). It prefers the `timings` the platform parsed into each event
+ * ({@link Unfazed.getEvents} reads them); events without them (an older
+ * platform, events built by hand) are parsed from their `*_ms` metadata the
+ * same way. Durations are whole, non-negative milliseconds: anything else is
+ * dropped, as the platform drops it. Null when neither event is there.
+ */
+export function parseDeploymentTimings(events) {
+    const latest = (type) => {
+        const event = [...events].reverse().find((e) => e.type === type);
+        return event && (event.timings || event.metadata) ? event : null;
+    };
+    const build = latest(BUILD_FINISHED_EVENT);
+    const ready = latest(DEPLOY_PHASES_EVENT);
+    if (!build && !ready)
+        return null;
+    if ((!build || build.timings) && (!ready || ready.timings)) {
+        const b = build?.timings ? toPlatformTimings(build.timings) : null;
+        const r = ready?.timings ? toPlatformTimings(ready.timings) : null;
+        return {
+            totalMs: r?.totalMs ?? null,
+            buildMs: r?.buildMs ?? b?.buildMs ?? null,
+            promoteMs: r?.promoteMs ?? b?.promoteMs ?? null,
+            phases: { ...b?.phases, ...r?.phases },
+            buildMode: r?.buildMode ?? b?.buildMode ?? null,
+            artifactTransport: r?.artifactTransport ?? b?.artifactTransport ?? null,
+            buildMemoryMiB: r?.buildMemoryMiB ?? b?.buildMemoryMiB ?? null,
+        };
+    }
+    // The platform merges the two events' metadata, the READY summary's values
+    // over the build's, and parses the result.
+    return timingsFromMetadata({ ...build?.metadata, ...ready?.metadata }, ready !== null);
+}
+function errorGroupInput(ref) {
+    return { workspaceID: ref.workspaceId, alias: ref.alias, groupID: ref.groupId };
+}
+function eventsInput(input) {
+    return {
+        ...(input.names === undefined ? {} : { names: input.names }),
+        ...(input.arguments === undefined ? {} : { arguments: input.arguments }),
+        ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+        ...(input.max === undefined ? {} : { max: input.max }),
+    };
 }
 const FILE_SELECTION = "path sizeBytes size sha256 updatedAt";
 const ENV_SELECTION = "name value secret alias inherited masked updatedAt";