@shardflux/sdk 0.6.1 → 0.7.0

package/dist/templates.js

@@ -1,5 +1,6 @@
 import { ShardfluxApiError } from "./errors.js";
 import { pollWithWait, randomId } from "./http.js";
+import { TemplateFileError, UPLOAD_BYTES_MAX, assertInside, fileBody, nodeModules, normalizeTemplateDocument, readTemplateFile, resolveLocalSource, tempDir } from "./template-file.js";
 import { Workspace } from "./workspace.js";
 const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
 /** Finished from the caller's point of view: failed/canceled/legacy succeeded, or published and its registration settled. */
@@ -31,6 +32,8 @@ export function saveAsTemplateBody(params) {
         body.description = params.description;
     if (params.defaults !== undefined)
         body.defaults = params.defaults;
+    if (params.settings !== undefined)
+        body.settings = params.settings;
     if (params.checkpointId !== undefined)
         body.checkpoint_id = params.checkpointId;
     if (params.autoPublish !== undefined)
@@ -39,6 +42,16 @@ export function saveAsTemplateBody(params) {
         body.acknowledged_scan_findings = params.acknowledgedScanFindings;
     return body;
 }
+/** A 200/202 open-shaped answer (drafts, test instances) as a Workspace handle, waiting for the operation unless `wait: false`. */
+async function openedWorkspace(ctx, res, p) {
+    const wrap = { agentLabel: p.agentLabel, tools: p.tools };
+    if (res.status === 200 || p.wait === false || res.body.operation === null) {
+        return { workspace: new Workspace(ctx, res.body.workspace, { ...wrap, token: res.body.tool_token }), operation: res.body.operation };
+    }
+    const operation = await ctx.workspaces.waitForOperation(res.body.operation.id, p.wait ?? {});
+    const view = await ctx.http.json('GET', `/v1/workspaces/${enc(res.body.workspace.id)}`, {}, ctx.authorization);
+    return { workspace: new Workspace(ctx, view, wrap), operation };
+}
 /**
  * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
  * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
@@ -57,15 +70,8 @@ export class TemplateDraftApi {
     #path(suffix = '') {
         return `${templatePath(this.slug, this.#org)}/draft${suffix}`;
     }
-    async #opened(res, p) {
-        const ctx = this.#ctx();
-        const wrap = { agentLabel: p.agentLabel, tools: p.tools };
-        if (res.status === 200 || p.wait === false || res.body.operation === null) {
-            return { workspace: new Workspace(ctx, res.body.workspace, { ...wrap, token: res.body.tool_token }), operation: res.body.operation };
-        }
-        const operation = await ctx.workspaces.waitForOperation(res.body.operation.id, p.wait ?? {});
-        const view = await ctx.http.json('GET', `/v1/workspaces/${enc(res.body.workspace.id)}`, {}, ctx.authorization);
-        return { workspace: new Workspace(ctx, view, wrap), operation };
+    #opened(res, p) {
+        return openedWorkspace(this.#ctx(), res, p);
     }
     /**
      * Opens the template's draft on `base` (202; waits until ready unless `wait: false`). 409 template_not_layered (the
@@ -75,6 +81,10 @@ export class TemplateDraftApi {
         const body = {};
         if (params.base !== undefined)
             body.base = params.base;
+        if (params.displayName !== undefined)
+            body.display_name = params.displayName;
+        if (params.inputs !== undefined)
+            body.inputs = params.inputs;
         if (params.caps !== undefined)
             body.caps = params.caps;
         if (params.projectId !== undefined)
@@ -146,6 +156,8 @@ export class TemplateDraftApi {
             body.agent_label = params.agentLabel;
         if (params.tools !== undefined)
             body.tools = params.tools;
+        if (params.inputs !== undefined)
+            body.inputs = params.inputs;
         const ctx = this.#ctx();
         const res = await ctx.http.jsonWithStatus('POST', this.#path('/test-instances'), { json: body, idempotencyKey: params.idempotencyKey ?? randomId('test-') }, ctx.authorization);
         return (await this.#opened(res, params)).workspace;
@@ -168,6 +180,8 @@ export class TemplateDraftApi {
             body.description = params.description;
         if (params.defaults !== undefined)
             body.defaults = params.defaults;
+        if (params.settings !== undefined)
+            body.settings = params.settings;
         if (params.autoPublish !== undefined)
             body.auto_publish = params.autoPublish;
         if (params.acknowledgedScanFindings !== undefined)
@@ -181,13 +195,22 @@ export class TemplateBuildsApi {
     constructor(ctx) {
         this.#ctx = ctx;
     }
-    /** Queues a build (202). Poll with get()/waitForBuild(); `builder_availability` says whether a builder runs. */
+    /**
+     * Queues a build (202) of a recipe v1 (Dockerfile) or recipe v2 (0.7.0). Poll with get()/waitForBuild();
+     * `builder_availability` says whether a builder runs. A recipe v2 is validated at once: 422 validation_failed with
+     * details.reason (invalid_recipe, base_not_layered, language_unavailable, upload_missing, invalid_settings, ...) and
+     * details.field (the JSON path). A file entry still carrying `from` is 422 upload_required.
+     */
     create(organizationId, params) {
         const body = { template_slug: params.templateSlug, recipe: params.recipe };
         if (params.displayName !== undefined)
             body.display_name = params.displayName;
         if (params.autoPublish !== undefined)
             body.auto_publish = params.autoPublish;
+        if (params.description !== undefined)
+            body.description = params.description;
+        if (params.acknowledgedScanFindings !== undefined)
+            body.acknowledged_scan_findings = params.acknowledgedScanFindings;
         return this.#ctx().http.json('POST', `/v1/organizations/${enc(organizationId)}/template-builds`, { json: body, idempotencyKey: params.idempotencyKey ?? randomId('template-build-') }, this.#ctx().authorization);
     }
     get(organizationId, buildId) {
@@ -230,15 +253,23 @@ export class TemplateBuildsApi {
             const waitS = opts.serverWait === false ? 0 : (timeoutMs - (Date.now() - started)) / 1000;
             const t0 = Date.now();
             const { body: build, applied } = await pollWithWait(http, `/v1/organizations/${enc(organizationId)}/template-builds/${enc(buildId)}`, authorization, waitS, opts.signal);
+            const key = `${build.state}/${build.registration.state}`;
+            const changed = key !== lastKey;
+            lastKey = key;
+            if (changed && opts.onChange) {
+                try {
+                    opts.onChange(build);
+                }
+                catch {
+                    // A listener never breaks the wait.
+                }
+            }
             if (buildSettled(build))
                 return build;
             const waited = Date.now() - started;
             if (waited >= timeoutMs)
                 throw new TemplateBuildTimeoutError(build, waited);
             // Held by the server (or a change): poll again at once; a quick unchanged answer falls through to the backoff.
-            const key = `${build.state}/${build.registration.state}`;
-            const changed = key !== lastKey;
-            lastKey = key;
             if (applied && (changed || Date.now() - t0 >= 1_000))
                 continue;
             await sleep(Math.max(10, Math.min(interval, timeoutMs - waited)));
@@ -248,12 +279,400 @@ export class TemplateBuildsApi {
         }
     }
 }
+/** A presigned PUT the storage refused (the URL is a bearer credential and never part of the message). */
+export class TemplateUploadError extends Error {
+    /** HTTP status of the storage's answer (0: no answer, a network failure). */
+    status;
+    /** The storage's error code: BadDigest (other bytes), SignatureDoesNotMatch (another length or header), ... */
+    code;
+    sha256;
+    constructor(sha256, status, code, detail) {
+        super(`Upload of sha256:${sha256} was refused by the storage: ${status === 0 ? (detail ?? 'network error') : `HTTP ${status}${code ? ` ${code}` : ''}`}${code === 'BadDigest' ? ' (the bytes do not match their SHA-256)' : code === 'SignatureDoesNotMatch' ? ' (another length, or a header was changed)' : ''}`);
+        this.name = 'TemplateUploadError';
+        this.status = status;
+        this.code = code;
+        this.sha256 = sha256;
+    }
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+function hex(buf) {
+    return Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+async function sha256Of(bytes) {
+    // DOM typings (browser bundles) take only ArrayBuffer-backed views; a SharedArrayBuffer view is copied.
+    const view = bytes.buffer instanceof ArrayBuffer ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength) : new Uint8Array(bytes);
+    return hex(await crypto.subtle.digest('SHA-256', view));
+}
+async function readStream(stream) {
+    const chunks = [];
+    let n = 0;
+    for await (const c of stream) {
+        chunks.push(c);
+        n += c.length;
+        if (n > UPLOAD_BYTES_MAX)
+            throw new TemplateFileError(`an upload is at most ${UPLOAD_BYTES_MAX} bytes (5 GiB)`);
+    }
+    const out = new Uint8Array(n);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}
+function uploadsPath(organizationId) {
+    return organizationId === undefined ? '/v1/template-uploads' : `/v1/organizations/${enc(organizationId)}/template-uploads`;
+}
+async function requestUpload(ctx, meta, organizationId, signal) {
+    return ctx.http.jsonWithStatus('POST', uploadsPath(organizationId), { json: meta, ...(signal ? { signal } : {}) }, ctx.authorization);
+}
+/**
+ * POST …/template-uploads; on 201 PUT the bytes with exactly the presigned headers, then ask again so the answer says
+ * `available`. On 200 nothing is sent (the organization already has the bytes).
+ */
+async function sendUpload(ctx, meta, body, organizationId, signal) {
+    const ref = `sha256:${meta.sha256}`;
+    const first = await requestUpload(ctx, meta, organizationId, signal);
+    const put = first.body.put;
+    if (first.status === 200 || put === null)
+        return { upload: first.body.upload, ref, uploaded: false };
+    const attempts = body.replayable ? 3 : 1;
+    for (let attempt = 1;; attempt += 1) {
+        let res;
+        try {
+            const init = { method: put.method, headers: { ...put.headers }, body: await body.open(), ...(signal ? { signal } : {}) };
+            if (init.body instanceof ReadableStream)
+                init.duplex = 'half';
+            res = await ctx.fetch(put.url, init);
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            if (attempt >= attempts)
+                throw new TemplateUploadError(meta.sha256, 0, null, err instanceof Error ? (err.cause instanceof Error ? err.cause.message : err.message) : String(err));
+            await ctx.sleep(500 * 2 ** (attempt - 1));
+            continue;
+        }
+        if (res.ok) {
+            await res.body?.cancel().catch(() => undefined);
+            break;
+        }
+        const text = await res.text().catch(() => '');
+        const code = /<Code>([^<]+)<\/Code>/.exec(text)?.[1] ?? null;
+        if (res.status >= 500 && attempt < attempts) {
+            await ctx.sleep(500 * 2 ** (attempt - 1));
+            continue;
+        }
+        throw new TemplateUploadError(meta.sha256, res.status, code);
+    }
+    const again = await requestUpload(ctx, meta, organizationId, signal);
+    return { upload: again.body.upload, ref, uploaded: true };
+}
+/**
+ * Build uploads (contracts §24.2): files and folders a recipe v2 copies into the template, stored once per
+ * organization and content (SHA-256). Needs build access (API keys with a tool permission). Uploads count toward the
+ * organization's template storage while they exist; one nothing references is deleted 7 days later.
+ */
+export class TemplateUploadsApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /**
+     * POST …/template-uploads alone: `status` 200 (the organization has the bytes; `put` null) or 201 (`put`: the
+     * presigned PUT, valid 900 s). 422 upload_too_large (over 5 GiB), upload_digest_mismatch (the same SHA-256 with
+     * another size); 503 dependency_unavailable (uploads_not_configured).
+     */
+    async request(meta, opts = {}) {
+        const res = await requestUpload(this.#ctx(), meta, opts.organizationId, opts.signal);
+        return { status: res.status, ...res.body };
+    }
+    /**
+     * Uploads bytes unless the organization already has them, and returns the `sha256:<hex>` reference for a recipe v2
+     * file entry. The PUT carries exactly the presigned headers (the storage checks the SHA-256 and the length). A stream
+     * is sent as it is when `sha256` and `size` are given (it cannot be retried); otherwise it is read into memory first.
+     * Throws TemplateUploadError when the storage refuses the bytes.
+     */
+    async put(data, opts) {
+        let sha256 = opts.sha256;
+        let size = opts.size;
+        let body;
+        if (data instanceof ReadableStream) {
+            if (sha256 === undefined || size === undefined) {
+                const bytes = await readStream(data);
+                sha256 ??= await sha256Of(bytes);
+                size ??= bytes.length;
+                body = { open: () => Promise.resolve(bytes), replayable: true };
+            }
+            else {
+                let used = false;
+                body = {
+                    open: () => {
+                        if (used)
+                            throw new TemplateFileError('the upload stream was already sent');
+                        used = true;
+                        return Promise.resolve(data);
+                    },
+                    replayable: false,
+                };
+            }
+        }
+        else if (data instanceof Blob) {
+            size ??= data.size;
+            sha256 ??= await sha256Of(new Uint8Array(await data.arrayBuffer()));
+            body = { open: () => Promise.resolve(data), replayable: true };
+        }
+        else {
+            const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+            size ??= bytes.length;
+            sha256 ??= await sha256Of(bytes);
+            body = { open: () => Promise.resolve(bytes), replayable: true };
+        }
+        if (!SHA256_HEX.test(sha256))
+            throw new TemplateFileError(`sha256 must be 64 lower-case hex digits (got "${sha256}")`);
+        if (size > UPLOAD_BYTES_MAX)
+            throw new TemplateFileError(`an upload is at most ${UPLOAD_BYTES_MAX} bytes (5 GiB); got ${size}`);
+        const result = await sendUpload(this.#ctx(), { sha256, size, kind: opts.kind }, body, opts.organizationId, opts.signal);
+        if (data instanceof ReadableStream && !result.uploaded)
+            await data.cancel().catch(() => undefined);
+        return result;
+    }
+    /**
+     * Node only: uploads a local file, or a folder packed as the reproducible tar (the same bytes as the Python SDK's
+     * for the same folder). `kind` omitted: a folder is `tar`, a file `file`; a file with kind `tar` is a prepared,
+     * uncompressed archive.
+     */
+    async putPath(path, opts = {}) {
+        const tmp = tempDir();
+        try {
+            const src = await resolveLocalSource(path, opts.kind, { baseDir: '.', tmpDir: tmp.get });
+            const result = await uploadLocal(this.#ctx(), src, opts.organizationId, opts.signal);
+            return { ...result, path: src.path, kind: src.kind, size: src.size, entries: src.entries };
+        }
+        finally {
+            await tmp.cleanup();
+        }
+    }
+}
+function uploadLocal(ctx, src, organizationId, signal) {
+    return sendUpload(ctx, { sha256: src.sha256, size: src.size, kind: src.kind }, { open: () => fileBody(src.uploadPath), replayable: true }, organizationId, signal);
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// ---- recipe export, version test instances, package search (contracts §24.6) --------------------------------------------
+export class TemplateVersionsApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /**
+     * The recipe and settings a version was built from, in request form (`recipe` null for versions saved from a
+     * workspace and platform versions). Building the recipe again (same base, uploads still present) gives the same
+     * recipe_sha256. Same visibility as the version.
+     */
+    recipe(slug, version, params = {}) {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', `${templatePath(slug, params.organizationId)}/versions/${enc(String(version))}/recipe`, { query: { owner: params.owner } }, ctx.authorization);
+    }
+}
+/**
+ * Test instances of a version (contracts §24.6): a session workspace on a registered version of the organization's
+ * template, published or not, so a build can be tried before it is published. Owners, admins and API keys with a
+ * tool permission (403 template_dev_mode_role otherwise).
+ */
+export class TemplateVersionTestInstancesApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /** Opens one (202; waits until ready unless `wait: false`). It ends with close() or when idle. */
+    async create(slug, version, params = {}) {
+        const body = {};
+        if (params.key !== undefined)
+            body.key = params.key;
+        if (params.caps !== undefined)
+            body.caps = params.caps;
+        if (params.agentLabel !== undefined)
+            body.agent_label = params.agentLabel;
+        if (params.tools !== undefined)
+            body.tools = params.tools;
+        if (params.inputs !== undefined)
+            body.inputs = params.inputs;
+        if (params.projectId !== undefined)
+            body.project_id = params.projectId;
+        const ctx = this.#ctx();
+        const res = await ctx.http.jsonWithStatus('POST', `${templatePath(slug, params.organizationId)}/versions/${enc(String(version))}/test-instances`, { json: body, idempotencyKey: params.idempotencyKey ?? randomId('test-') }, ctx.authorization);
+        return (await openedWorkspace(ctx, res, params)).workspace;
+    }
+}
+/** Package names for the editor's pickers (contracts §24.6): apt (a base's index), pip (names only) and npm. */
+export class TemplatePackagesApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    #path(organizationId, suffix = '') {
+        return organizationId === undefined ? `/v1/template-packages${suffix}` : `/v1/organizations/${enc(organizationId)}/template-packages${suffix}`;
+    }
+    /**
+     * Searches an ecosystem (`query` 1..100 characters; `limit` 1..50, default 20). apt needs `base` (`<slug>@<version>`);
+     * a base without an index is 409 package_index_unavailable. pip returns names only (fetch one package for versions).
+     * 503 dependency_unavailable (package_search_unavailable, package_index_loading) and 429 are retryable.
+     */
+    search(ecosystem, query, params = {}) {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', this.#path(params.organizationId), { query: { ecosystem, q: query, base: params.base, limit: params.limit } }, ctx.authorization);
+    }
+    /** One package: its latest version, summary and known versions (404 package_not_found). */
+    get(ecosystem, name, params = {}) {
+        const ctx = this.#ctx();
+        return ctx.http.json('GET', this.#path(params.organizationId, `/${enc(ecosystem)}/${enc(name)}`), { query: { base: params.base } }, ctx.authorization);
+    }
+}
 export class TemplatesApi {
     #ctx;
     builds;
+    /** Build uploads (0.7.0): files and folders for recipe v2. */
+    uploads;
+    /** Recipe export of a version (0.7.0). */
+    versions;
+    /** Test instances of a registered version, published or not (0.7.0). */
+    versionTestInstances;
+    /** Package search for recipes (0.7.0). */
+    packages;
+    #organization;
     constructor(ctx) {
         this.#ctx = ctx;
         this.builds = new TemplateBuildsApi(ctx);
+        this.uploads = new TemplateUploadsApi(ctx);
+        this.versions = new TemplateVersionsApi(ctx);
+        this.versionTestInstances = new TemplateVersionTestInstancesApi(ctx);
+        this.packages = new TemplatePackagesApi(ctx);
+    }
+    /**
+     * The languages `base` (`<slug>@<version>`) offers a recipe v2's `build.languages` (0.7.0): the platform's table for
+     * the chain's platform base, in table order. `included`: the base already has that version (nothing is installed and
+     * no host is needed); a version the base has another version of is left out (a build would refuse it with
+     * language_conflict). `hosts` and `apt` are what the language adds to an `auto` build network. An unknown or
+     * archived base is 422 validation_failed with details.field `base`. Build access (API keys with a tool permission).
+     */
+    languages(base, params = {}) {
+        const ctx = this.#ctx();
+        const path = params.organizationId === undefined ? '/v1/template-languages' : `/v1/organizations/${enc(params.organizationId)}/template-languages`;
+        return ctx.http.json('GET', path, { query: { base } }, ctx.authorization);
+    }
+    /** The API key's organization (GET /v1/me, once per client). */
+    #organizationId() {
+        this.#organization ??= (async () => {
+            const ctx = this.#ctx();
+            const me = await ctx.http.json('GET', '/v1/me', {}, ctx.authorization);
+            const org = me.api_key?.organization_id;
+            if (!org)
+                throw new TemplateFileError('this principal has no API key organization; pass organizationId');
+            return org;
+        })();
+        this.#organization.catch(() => (this.#organization = undefined));
+        return this.#organization;
+    }
+    /**
+     * Node only: builds a template from template.yaml (or a .json file with the same document; contracts §24.1). The
+     * file is recipe v2; each `build.files[]` entry may name a local `from` path (relative to the file): folders are
+     * packed as the reproducible tar, files are sent as they are, both uploaded unless the organization already has
+     * them, and the build is created (and awaited with `wait`). YAML needs the optional `yaml` package or `parseYaml`.
+     */
+    async buildFromFile(file, opts) {
+        const { path } = await nodeModules();
+        const resolved = path.resolve(file);
+        if (opts.root !== undefined)
+            await assertInside(opts.root, resolved, file);
+        const doc = await readTemplateFile(resolved, opts.parseYaml ? { parseYaml: opts.parseYaml } : {});
+        return this.buildFromRecipe(doc, { ...opts, baseDir: path.dirname(resolved) });
+    }
+    /**
+     * Builds a recipe v2 document whose file entries may name local `from` paths (Node only when one does): the same
+     * as buildFromFile() for a document already in memory, `from` relative to `baseDir`.
+     */
+    async buildFromRecipe(recipe, opts) {
+        const doc = normalizeTemplateDocument(structuredClone(recipe), 'the recipe');
+        const build = isRecord(doc.build) ? { ...doc.build } : null;
+        const files = build && Array.isArray(build.files) ? [...build.files] : null;
+        const uploads = [];
+        const tmp = tempDir();
+        const emit = (e) => {
+            try {
+                opts.onProgress?.(e);
+            }
+            catch {
+                // A listener never breaks the build.
+            }
+        };
+        try {
+            if (files && build) {
+                const done = new Map();
+                const orgForUploads = opts.organizationId;
+                for (let i = 0; i < files.length; i += 1) {
+                    const f = files[i];
+                    if (!isRecord(f) || f.from === undefined)
+                        continue;
+                    const where = `build.files[${i}]`;
+                    if (typeof f.from !== 'string' || f.from.length === 0)
+                        throw new TemplateFileError(`${where}.from must be a local path`);
+                    if (f.upload !== undefined)
+                        throw new TemplateFileError(`${where} has both from and upload; keep one`);
+                    if (f.kind !== undefined && f.kind !== 'file' && f.kind !== 'tar')
+                        throw new TemplateFileError(`${where}.kind must be file or tar`);
+                    const { path } = await nodeModules();
+                    const baseDir = opts.baseDir ?? process.cwd();
+                    const key = `${path.resolve(baseDir, f.from)}\0${f.kind ?? ''}`;
+                    let hit = done.get(key);
+                    if (!hit) {
+                        const t0 = Date.now();
+                        const src = await resolveLocalSource(f.from, f.kind, { baseDir, root: opts.root, tmpDir: tmp.get });
+                        emit({ type: 'pack', from: f.from, path: src.path, kind: src.kind, sha256: src.sha256, size: src.size, entries: src.entries, ms: Date.now() - t0 });
+                        const t1 = Date.now();
+                        const result = await uploadLocal(this.#ctx(), src, orgForUploads, opts.signal);
+                        emit({ type: 'upload', from: f.from, sha256: src.sha256, size: src.size, uploaded: result.uploaded, ms: Date.now() - t1 });
+                        hit = { src, uploaded: result.uploaded };
+                        done.set(key, hit);
+                        // One row per distinct local source (as the Python SDK reports them); `to` is its first entry's.
+                        uploads.push({ from: f.from, path: src.path, to: typeof f.to === 'string' ? f.to : '', kind: src.kind, sha256: src.sha256, size: src.size, entries: src.entries, uploaded: result.uploaded });
+                    }
+                    const rest = { ...f };
+                    delete rest.from;
+                    delete rest.kind;
+                    files[i] = { upload: `sha256:${hit.src.sha256}`, kind: hit.src.kind, ...rest };
+                }
+                build.files = files;
+                doc.build = build;
+            }
+        }
+        finally {
+            await tmp.cleanup();
+        }
+        const sent = doc;
+        const org = opts.organizationId ?? (await this.#organizationId());
+        let created = await this.builds.create(org, {
+            templateSlug: opts.templateSlug,
+            recipe: sent,
+            ...(opts.displayName !== undefined ? { displayName: opts.displayName } : {}),
+            ...(opts.description !== undefined ? { description: opts.description } : {}),
+            ...(opts.autoPublish !== undefined ? { autoPublish: opts.autoPublish } : {}),
+            ...(opts.acknowledgedScanFindings !== undefined ? { acknowledgedScanFindings: opts.acknowledgedScanFindings } : {}),
+            ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+        });
+        emit({ type: 'build', build: created });
+        if (opts.wait) {
+            const waitOpts = opts.wait === true ? {} : { ...opts.wait };
+            if (opts.signal && !waitOpts.signal)
+                waitOpts.signal = opts.signal;
+            const outer = waitOpts.onChange;
+            waitOpts.onChange = (b) => {
+                if (b.state !== created.state || b.registration.state !== created.registration.state)
+                    emit({ type: 'build', build: b });
+                outer?.(b);
+            };
+            created = await this.builds.waitForBuild(org, created.id, waitOpts);
+        }
+        return { build: created, recipe: sent, uploads };
     }
     /** Templates the API key's organization can use (platform + its own), with the version `open` picks. */
     async list(params = {}) {

package/dist/tools.d.ts

@@ -1,15 +1,3 @@
-/**
- * Framework-neutral agent tools for a workspace (TEMPLATES.md):
- *
- *   await agent.run({ input, tools: workspaceTools(workspace) });
- *
- * Each tool is { name, description, parameters (JSON Schema 2020-12), execute }.
- * `execute` validates its arguments against `parameters` (the same schema the
- * model saw), then calls the cell gateway through the workspace's managed tool
- * token. The customer's model and agent loop stay in the customer's
- * application; toOpenAITools/toAnthropicTools export the definitions in those
- * providers' formats and executeToolCall dispatches a model's tool call.
- */
 import type { CellClientOptions } from './cell.js';
 import type { ToolName } from './tokens.js';
 import type { Workspace } from './workspace.js';
@@ -37,8 +25,10 @@ export interface WorkspaceTool<A extends Record<string, unknown> = Record<string
     };
     /** Which workspace tool permission the call needs (exec, files, pty, process, git, browser). */
     permission: ToolName;
+    /** `toolCallId` (0.7.0+): the model's call id, recorded by tool-call capture (executeToolCall passes it). */
     execute(args: A, options?: {
         signal?: AbortSignal;
+        toolCallId?: string;
     }): Promise<R>;
 }
 export declare class ToolArgumentError extends Error {
@@ -97,12 +87,15 @@ export declare function toAnthropicTools(tools: readonly WorkspaceTool[]): {
 }[];
 /**
  * Runs a model's tool call: `arguments` may be the JSON string (OpenAI) or an object (Anthropic
- * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError).
+ * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError). The call's `id` / `call_id` is passed
+ * to `execute` as `toolCallId` (0.7.0+), so `executeToolCall(capture.tools(tools), call)` records it.
  */
 export declare function executeToolCall(tools: readonly WorkspaceTool[], call: {
     name: string;
     arguments?: string | Record<string, unknown>;
     input?: Record<string, unknown>;
+    id?: string;
+    call_id?: string;
 }, options?: {
     signal?: AbortSignal;
 }): Promise<unknown>;

package/dist/tools.js

@@ -1,3 +1,16 @@
+/**
+ * Framework-neutral agent tools for a workspace (TEMPLATES.md):
+ *
+ *   await agent.run({ input, tools: workspaceTools(workspace) });
+ *
+ * Each tool is { name, description, parameters (JSON Schema 2020-12), execute }.
+ * `execute` validates its arguments against `parameters` (the same schema the
+ * model saw), then calls the cell gateway through the workspace's managed tool
+ * token. The customer's model and agent loop stay in the customer's
+ * application; toOpenAITools/toAnthropicTools export the definitions in those
+ * providers' formats and executeToolCall dispatches a model's tool call.
+ */
+import { CAPTURE_BARRIER } from "./cell.js";
 export class ToolArgumentError extends Error {
     tool;
     issues;
@@ -283,7 +296,12 @@ export function workspaceTools(workspace, opts = {}) {
             const issues = validateArgs(d.parameters, args);
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
-            return d.run(args, options);
+            // Read-your-writes: tool calls captured before this one are in the workspace before it runs (bounded).
+            const barrier = workspace[CAPTURE_BARRIER];
+            const pending = typeof barrier === 'function' ? barrier.call(workspace) : undefined;
+            if (pending)
+                await pending;
+            return d.run(args, options.signal ? { signal: options.signal } : {});
         },
     }));
 }
@@ -299,7 +317,8 @@ export function toAnthropicTools(tools) {
 }
 /**
  * Runs a model's tool call: `arguments` may be the JSON string (OpenAI) or an object (Anthropic
- * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError).
+ * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError). The call's `id` / `call_id` is passed
+ * to `execute` as `toolCallId` (0.7.0+), so `executeToolCall(capture.tools(tools), call)` records it.
  */
 export async function executeToolCall(tools, call, options = {}) {
     const tool = tools.find((t) => t.name === call.name);
@@ -313,5 +332,6 @@ export async function executeToolCall(tools, call, options = {}) {
     catch {
         throw new ToolArgumentError(call.name, ['arguments are not valid JSON']);
     }
-    return tool.execute(args, options);
+    const toolCallId = call.call_id ?? call.id;
+    return tool.execute(args, toolCallId === undefined ? options : { ...options, toolCallId });
 }