@shardflux/sdk 0.6.1 → 0.7.0

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.6.1";
+export declare const SDK_VERSION = "0.7.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

package/dist/http.js

@@ -6,7 +6,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.6.1';
+export const SDK_VERSION = '0.7.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends

package/dist/index.d.ts

@@ -12,14 +12,18 @@
 export type { components, operations, paths } from './generated/app-api.js';
 export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from './client.js';
-export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
 export type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
 export { formatTiming } from './progress.js';
 export type { LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
 export { UsageApi } from './usage.js';
 export type { Grants, Spend, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
-export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatesApi, buildSettled, saveAsTemplateBody } from './templates.js';
-export type { BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, DraftOpened, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRegistrationState, TemplateBuildState, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateOwner, TemplateRecipe, TemplateSource, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateVersion, TemplateVersionState, WaitForBuildOptions, } from './templates.js';
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from './templates.js';
+export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from './template-file.js';
+export type { PackedFile, YamlParser } from './template-file.js';
+export { tarEnd, tarHeader, tarPadding } from './tar.js';
+export type { TarEntry, TarEntryType } from './tar.js';
+export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
 export { SecretsApi, WorkspaceSecrets } from './secrets.js';
 export type { BoundSecretStatus, CreateOrganizationSecretParams, CreateSecretParams, Secret, SecretAccessEvent, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams, WorkspaceSecretBindings, } from './secrets.js';
 export { EgressPolicyApi } from './egress.js';
@@ -36,6 +40,9 @@ export { ToolTokenManager } from './tokens.js';
 export type { ToolName, ToolToken, ToolTokenOptions } from './tokens.js';
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from './tools.js';
 export type { JsonSchema, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export { CaptureError, ToolCallCapture, captureTool } from './capture.js';
+export type { CallLike, CallRef, CaptureCall, CaptureErrorKind, CaptureEvent, CaptureFlushResult, CapturePart, CaptureSelector, CaptureSource, CaptureStats, CaptureStatus, DropReason, ToolCallCaptureOptions, WrapOptions, } from './capture.js';
+export type { AiSdkAdapter, AiSdkToolEndEvent, AnthropicAdapter, ClaudeAdapter, ClaudeCaptureHooks, ClaudeHookCallback, ClaudeHookMatcher, LangChainAdapter, LangChainToolHandler, MastraAdapter, MastraAfterToolCallContext, McpAdapter, OpenAIAgentsAdapter, } from './capture-adapters.js';
 export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from './errors.js';
 export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason } from './errors.js';
 export { SDK_VERSION } from './http.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
 export { formatTiming } from "./progress.js";
 export { UsageApi } from "./usage.js";
-export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatesApi, buildSettled, saveAsTemplateBody } from "./templates.js";
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from "./templates.js";
+export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from "./template-file.js";
+export { tarEnd, tarHeader, tarPadding } from "./tar.js";
 export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";
@@ -10,5 +12,6 @@ export { Workspace } from "./workspace.js";
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from "./cell.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
+export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
 export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 export { SDK_VERSION } from "./http.js";

package/dist/lifecycle.d.ts

@@ -20,7 +20,8 @@ export interface LifecycleOptions {
     /**
      * Default (false): resolve once the change is requested; the returned operation is usually still `queued`.
      * `true` or WaitOptions: resolve once it has finished (the operation `succeeded`); throws OperationFailedError when it
-     * fails and OperationTimeoutError after `timeoutMs` (default 5 minutes; the operation continues server side).
+     * fails and OperationTimeoutError after `timeoutMs` (default 5 minutes; the operation continues server side, a start
+     * waiting for capacity until its deadline, then it fails with `capacity_unavailable`, retryable).
      */
     wait?: boolean | WaitOptions;
     /** Progress events of this call (phases, retries, and `done` with its timing). */
@@ -45,4 +46,6 @@ export declare function waitOptionsOf(opts: LifecycleOptions): WaitOptions | nul
  * Starts a lifecycle operation with `start` and, when `opts.wait` asks for it, waits for it to finish. The trace covers
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
-export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>) => Promise<Operation>, opts: InternalLifecycleOptions): Promise<Operation>;
+export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>) => Promise<Operation>, opts: InternalLifecycleOptions, capture?: {
+    settle?: boolean;
+}): Promise<Operation>;

package/dist/lifecycle.js

@@ -13,10 +13,14 @@ export function waitOptionsOf(opts) {
  * Starts a lifecycle operation with `start` and, when `opts.wait` asks for it, waits for it to finish. The trace covers
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
-export async function runLifecycle(ctx, kind, workspaceId, start, opts) {
+export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture = {}) {
     const waitOpts = waitOptionsOf(opts);
     const trace = new Trace(kind, combineListeners(ctx.onProgress, opts.onProgress, waitOpts?.onProgress), { workspaceId });
     return traced(trace, async () => {
+        // Tool-call capture writes recorded before this call land first (snapshot, fork, suspend and close include them).
+        const pending = capture.settle ? ctx.captures.settle(workspaceId) : undefined;
+        if (pending)
+            await trace.span('capture_flush', () => pending);
         trace.phase('request');
         const operation = await start({ onRetry: trace.onRetry });
         trace.observe(operation);

package/dist/progress.d.ts

@@ -26,8 +26,10 @@ export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork
  *   operation's `state_reason` (e.g. `no_ready_host`, `template_downloading`).
  * - `view`: reading the workspace after the operation. `token`: issuing a tool token (concurrent with `view` in open()).
  * - `busy`: a tool call waiting out `workspace_busy` (only in `tool` events).
+ * - `capture_flush` (0.7.0+): a lifecycle call waiting for tool-call capture writes recorded before it (only when some
+ *   were pending).
  */
-export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy';
+export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy' | 'capture_flush';
 export interface TimingPhase {
     phase: LifecyclePhase;
     /** The server's state_reason, or why the SDK entered the phase (`held`, `initial`, `expiring`, `invalidated`). */
@@ -104,6 +106,8 @@ interface EventBase {
 }
 /**
  * - `phase`: a phase began (live progress: "capacity_pending: no_ready_host"). `tool` phases come from tool calls.
+ *   A `capacity_pending` phase carries `deadlineAt` (0.6.2+, when the API reports it): when the start gives up waiting
+ *   for a host and fails with `capacity_unavailable` (retryable; nothing was started).
  * - `retry`: a request is retried after a transient failure (also emitted for tool calls, action `tool`).
  * - `done`: the call ended, successfully or not, with its full timing.
  */
@@ -111,6 +115,7 @@ export type ProgressEvent = (EventBase & {
     type: 'phase';
     phase: LifecyclePhase;
     reason: string | null;
+    deadlineAt?: string;
 }) | (EventBase & {
     type: 'retry';
     retry: RetryRecord;
@@ -123,6 +128,12 @@ export type ProgressListener = (event: ProgressEvent) => void;
 export declare function emitTo(listeners: ReadonlyArray<ProgressListener | undefined>, event: ProgressEvent): void;
 /** Combines listeners (client-level and per call) into one; undefined when there are none. */
 export declare function combineListeners(...listeners: Array<ProgressListener | undefined>): ProgressListener | undefined;
+/**
+ * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
+ * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
+ * from an API that does not report it.
+ */
+export declare function capacityDeadlineOf(op: Operation): string | null;
 /** Server timing from an operation as GET /v1/operations/{id} returns it. */
 export declare function serverTiming(op: Operation): ServerTiming;
 /** Why a request failed, in one short phrase (for retry records). */
@@ -139,8 +150,11 @@ export declare class Trace {
     /** Milliseconds since the call began. */
     now(): number;
     get finished(): LifecycleTiming | null;
-    /** Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase. */
-    phase(phase: LifecyclePhase, reason?: string | null): void;
+    /**
+     * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
+     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     */
+    phase(phase: LifecyclePhase, reason?: string | null, deadlineAt?: string | null): void;
     /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
     span<T>(phase: LifecyclePhase, fn: () => Promise<T>, reason?: string | null): Promise<T>;
     /** Records an operation snapshot: its ids, the observed state as a phase, and the server timing. */

package/dist/progress.js

@@ -30,6 +30,17 @@ function diffMs(from, to) {
 }
 const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/**
+ * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
+ * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
+ * from an API that does not report it.
+ */
+export function capacityDeadlineOf(op) {
+    if (op.state !== 'capacity_pending')
+        return null;
+    const details = op.error?.details;
+    return typeof details === 'object' && details !== null ? str(details.deadline_at) : null;
+}
 /** Server timing from an operation as GET /v1/operations/{id} returns it. */
 export function serverTiming(op) {
     const r = (op.result ?? {});
@@ -113,8 +124,11 @@ export class Trace {
             this.#current.durationMs = round(at - this.#current.startMs);
         this.#current = null;
     }
-    /** Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase. */
-    phase(phase, reason = null) {
+    /**
+     * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
+     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     */
+    phase(phase, reason = null, deadlineAt = null) {
         if (this.#timing)
             return;
         if (this.#current && this.#current.phase === phase && this.#current.reason === reason)
@@ -123,7 +137,7 @@ export class Trace {
         this.#close(at);
         this.#current = { phase, reason, operationId: this.operationId, startMs: at, durationMs: 0 };
         this.#phases.push(this.#current);
-        this.#emit({ ...this.#base(), type: 'phase', phase, reason });
+        this.#emit({ ...this.#base(), type: 'phase', phase, reason, ...(deadlineAt ? { deadlineAt } : {}) });
     }
     /** Runs `fn` as a phase that may overlap others (open() reads the view and issues the token together). */
     async span(phase, fn, reason = null) {
@@ -145,7 +159,7 @@ export class Trace {
         this.workspaceId ??= op.workspace_id;
         this.#server = serverTiming(op);
         if (!TERMINAL.has(op.state))
-            this.phase(op.state, op.state_reason ?? null);
+            this.phase(op.state, op.state_reason ?? null, capacityDeadlineOf(op));
     }
     retry(r) {
         if (this.#timing)

package/dist/tar.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * static tool). Pure: no Node imports, so the browser bundle can carry it.
+ *
+ * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the
+ * Python SDK's writer), so both SDKs upload the same bytes for the same folder and a template built from either has the
+ * same recipe_sha256:
+ * - a pax `x` header (`././@PaxHeader`) precedes a member whose name or link target is non-ASCII or longer than 100
+ *   characters (`path`, `linkpath` records), or whose size does not fit the 11 octal digits (`size`);
+ * - the ustar header then holds the name encoded as ASCII with `?` for each non-ASCII code point, truncated to 100 bytes;
+ * - the archive ends with two zero blocks and is padded to a multiple of 10240 bytes (tarfile's RECORDSIZE).
+ */
+export declare const TAR_BLOCK = 512;
+export declare const TAR_RECORD_SIZE: number;
+export type TarEntryType = 'file' | 'dir' | 'symlink';
+export interface TarEntry {
+    /** Relative path with `/` separators; directories get their trailing `/` from the writer. */
+    path: string;
+    type: TarEntryType;
+    /** Permission bits (masked to 0o7777 as tarfile does). */
+    mode: number;
+    /** Bytes of a regular file (0 for directories and symlinks). */
+    size: number;
+    /** Symlink target. */
+    linkname?: string;
+    mtime?: number;
+    uid?: number;
+    gid?: number;
+    uname?: string;
+    gname?: string;
+}
+/** Zero padding after `size` bytes of member data. */
+export declare function tarPadding(size: number): Uint8Array;
+/**
+ * The header block(s) of one member: an optional pax extended header with its records, then the ustar header.
+ * Member data (a file's bytes) follows, then tarPadding(size).
+ */
+export declare function tarHeader(entry: TarEntry): Uint8Array;
+/** The end of an archive written so far (`offset` bytes): two zero blocks, then zeros up to a multiple of 10240. */
+export declare function tarEnd(offset: number): Uint8Array;

package/dist/tar.js

@@ -0,0 +1,150 @@
+/**
+ * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * static tool). Pure: no Node imports, so the browser bundle can carry it.
+ *
+ * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the
+ * Python SDK's writer), so both SDKs upload the same bytes for the same folder and a template built from either has the
+ * same recipe_sha256:
+ * - a pax `x` header (`././@PaxHeader`) precedes a member whose name or link target is non-ASCII or longer than 100
+ *   characters (`path`, `linkpath` records), or whose size does not fit the 11 octal digits (`size`);
+ * - the ustar header then holds the name encoded as ASCII with `?` for each non-ASCII code point, truncated to 100 bytes;
+ * - the archive ends with two zero blocks and is padded to a multiple of 10240 bytes (tarfile's RECORDSIZE).
+ */
+export const TAR_BLOCK = 512;
+export const TAR_RECORD_SIZE = 20 * TAR_BLOCK;
+const TYPEFLAG = { file: 0x30, dir: 0x35, symlink: 0x32 };
+const utf8 = new TextEncoder();
+function isAscii(s) {
+    for (let i = 0; i < s.length; i += 1)
+        if (s.charCodeAt(i) > 0x7f)
+            return false;
+    return true;
+}
+/** Python's `s.encode("ascii", "replace")`: one `?` per non-ASCII code point (not per UTF-16 unit). */
+function asciiReplace(s) {
+    const out = [];
+    for (const ch of s)
+        out.push(ch.codePointAt(0) > 0x7f ? 0x3f : ch.charCodeAt(0));
+    return Uint8Array.from(out);
+}
+/** tarfile's stn(): the bytes truncated to `length` and NUL-padded. */
+function putString(buf, offset, length, bytes) {
+    buf.set(bytes.subarray(0, length), offset);
+}
+/** tarfile's itn() for the POSIX range: `%0*o` with digits-1 digits and a NUL. */
+function putOctal(buf, offset, digits, value) {
+    const text = `${value.toString(8).padStart(digits - 1, '0')}\0`;
+    buf.set(utf8.encode(text), offset);
+}
+/** Python's len(str): code points. */
+function codePoints(s) {
+    return Array.from(s).length;
+}
+/** tarfile's _create_header(info, USTAR_FORMAT, "ascii", "replace"). */
+function ustarHeader(info) {
+    const h = new Uint8Array(TAR_BLOCK);
+    putString(h, 0, 100, asciiReplace(info.name));
+    putOctal(h, 100, 8, info.mode & 0o7777);
+    putOctal(h, 108, 8, info.uid);
+    putOctal(h, 116, 8, info.gid);
+    putOctal(h, 124, 12, info.size);
+    putOctal(h, 136, 12, info.mtime);
+    h.fill(0x20, 148, 156);
+    h[156] = info.type;
+    putString(h, 157, 100, asciiReplace(info.linkname));
+    h.set(utf8.encode('ustar\x0000'), 257);
+    putString(h, 265, 32, asciiReplace(info.uname));
+    putString(h, 297, 32, asciiReplace(info.gname));
+    // devmajor, devminor and prefix stay NUL (tarfile writes empty strings for non-device members).
+    let sum = 0;
+    for (const b of h)
+        sum += b;
+    h.set(utf8.encode(`${sum.toString(8).padStart(6, '0')}\0`), 148);
+    return h;
+}
+/** Zero padding after `size` bytes of member data. */
+export function tarPadding(size) {
+    const rest = size % TAR_BLOCK;
+    return new Uint8Array(rest === 0 ? 0 : TAR_BLOCK - rest);
+}
+/** tarfile's pax record: "%d %s=%s\n" where the length counts itself. */
+function paxRecord(keyword, value) {
+    const kv = utf8.encode(`${keyword}=${value}\n`);
+    const l = kv.length + 1; // + ' '
+    let p = 0;
+    for (;;) {
+        const n = l + String(p).length;
+        if (n === p)
+            break;
+        p = n;
+    }
+    const head = utf8.encode(`${p} `);
+    const out = new Uint8Array(head.length + kv.length);
+    out.set(head, 0);
+    out.set(kv, head.length);
+    return out;
+}
+/**
+ * The header block(s) of one member: an optional pax extended header with its records, then the ustar header.
+ * Member data (a file's bytes) follows, then tarPadding(size).
+ */
+export function tarHeader(entry) {
+    const name = entry.type === 'dir' && !entry.path.endsWith('/') ? `${entry.path}/` : entry.path;
+    const info = {
+        name,
+        mode: entry.mode,
+        uid: entry.uid ?? 0,
+        gid: entry.gid ?? 0,
+        size: entry.type === 'file' ? entry.size : 0,
+        mtime: entry.mtime ?? 0,
+        type: TYPEFLAG[entry.type],
+        linkname: entry.linkname ?? '',
+        uname: entry.uname ?? '',
+        gname: entry.gname ?? '',
+    };
+    const records = [];
+    for (const [field, keyword, length] of [
+        ['name', 'path', 100],
+        ['linkname', 'linkpath', 100],
+        ['uname', 'uname', 32],
+        ['gname', 'gname', 32],
+    ]) {
+        const value = info[field];
+        if (!isAscii(value) || codePoints(value) > length)
+            records.push(paxRecord(keyword, value));
+    }
+    for (const [field, digits] of [
+        ['uid', 8],
+        ['gid', 8],
+        ['size', 12],
+        ['mtime', 12],
+    ]) {
+        const value = info[field];
+        if (!(value >= 0 && value < 8 ** (digits - 1))) {
+            records.push(paxRecord(field, String(value)));
+            info[field] = 0;
+        }
+    }
+    const header = ustarHeader(info);
+    if (records.length === 0)
+        return header;
+    const total = records.reduce((n, r) => n + r.length, 0);
+    const payload = new Uint8Array(total + tarPadding(total).length);
+    let at = 0;
+    for (const r of records) {
+        payload.set(r, at);
+        at += r.length;
+    }
+    const pax = ustarHeader({ name: '././@PaxHeader', mode: 0, uid: 0, gid: 0, size: total, mtime: 0, type: 0x78, linkname: '', uname: '', gname: '' });
+    const out = new Uint8Array(pax.length + payload.length + header.length);
+    out.set(pax, 0);
+    out.set(payload, pax.length);
+    out.set(header, pax.length + payload.length);
+    return out;
+}
+/** The end of an archive written so far (`offset` bytes): two zero blocks, then zeros up to a multiple of 10240. */
+export function tarEnd(offset) {
+    const end = offset + 2 * TAR_BLOCK;
+    const rest = end % TAR_RECORD_SIZE;
+    return new Uint8Array(2 * TAR_BLOCK + (rest === 0 ? 0 : TAR_RECORD_SIZE - rest));
+}

package/dist/template-file.d.ts

@@ -0,0 +1,92 @@
+type Fs = typeof import('node:fs');
+type FsPromises = typeof import('node:fs/promises');
+type Path = typeof import('node:path');
+type Os = typeof import('node:os');
+type Crypto = typeof import('node:crypto');
+type Stream = {
+    Readable: typeof import('node:stream').Readable;
+};
+interface NodeModules {
+    fs: Fs;
+    fsp: FsPromises;
+    path: Path;
+    os: Os;
+    crypto: Crypto;
+    stream: Stream;
+}
+/** The Node modules this file needs, loaded once (throws outside Node). */
+export declare function nodeModules(): Promise<NodeModules>;
+/** A template file that cannot be read, parsed or packed (before any request is made). */
+export declare class TemplateFileError extends Error {
+    /** The template file or local path concerned, when there is one. */
+    readonly path: string | undefined;
+    constructor(message: string, path?: string);
+}
+/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+export declare const UPLOAD_BYTES_MAX = 5368709120;
+/** Most entries a folder tar may have (the host's extraction limit, §24.2). */
+export declare const TAR_ENTRIES_MAX = 200000;
+export declare const RECIPE_V2_SCHEMA = "shardflux.template-recipe.v2";
+/** Parses YAML text: the optional `yaml` package's parse() unless the caller passes its own. */
+export type YamlParser = (text: string) => unknown;
+/**
+ * The document of a template file: `.json` is JSON, anything else YAML (JSON is valid YAML too). YAML needs the
+ * optional `yaml` package (`npm install yaml`) or `parseYaml`; without either, a YAML file that is not valid JSON fails.
+ */
+export declare function parseTemplateText(text: string, fileName: string, parseYaml?: YamlParser): Promise<Record<string, unknown>>;
+/** The recipe v2 document: a mapping whose `schema` is recipe v2 (filled in when absent). */
+export declare function normalizeTemplateDocument(doc: unknown, where?: string): Record<string, unknown>;
+/** Reads and parses a template file (template.yaml or .json). */
+export declare function readTemplateFile(file: string, opts?: {
+    parseYaml?: YamlParser;
+}): Promise<Record<string, unknown>>;
+export interface PackedFile {
+    sha256: string;
+    size: number;
+    /** Tar members (folders), null for a file uploaded as it is. */
+    entries: number | null;
+}
+/** SHA-256 (lower-case hex) and size of a local file, streamed. */
+export declare function hashFile(file: string): Promise<{
+    sha256: string;
+    size: number;
+}>;
+/**
+ * Packs the folder `root` into `dest` as the reproducible tar (tar.ts; byte-identical to the Python SDK's): members in
+ * UTF-8 path order, mtime 0, uid/gid 0 without names, permission bits kept (symlinks 0777). Returns its sha256, size and
+ * member count.
+ */
+export declare function packDirectory(root: string, dest: string): Promise<PackedFile>;
+/** Refuses `target` when it resolves, after symlinks, outside `root` (an agent-facing server confines local reads). */
+export declare function assertInside(root: string, target: string, what: string): Promise<void>;
+/** One `from` entry resolved on the disk: what gets uploaded and how. */
+export interface LocalSource {
+    /** `from` as written. */
+    from: string;
+    /** The resolved local path. */
+    path: string;
+    kind: 'file' | 'tar';
+    /** The bytes to upload: the file itself, or the packed tar in a temporary directory. */
+    uploadPath: string;
+    sha256: string;
+    size: number;
+    entries: number | null;
+}
+/**
+ * Resolves `from` (relative to `baseDir`), checks it against `root` when given (after symlinks), and packs or hashes
+ * it. `kind` omitted: a folder is `tar`, a file is `file`. A folder with kind `file` is refused; a file with kind `tar`
+ * is a prepared (uncompressed) archive.
+ */
+export declare function resolveLocalSource(from: string, kind: 'file' | 'tar' | undefined, opts: {
+    baseDir: string;
+    root?: string | undefined;
+    tmpDir: () => Promise<string>;
+}): Promise<LocalSource>;
+/** A fetch body that streams a local file (replayable: each call opens it again). */
+export declare function fileBody(file: string): Promise<ReadableStream<Uint8Array>>;
+/** A private temporary directory, created on first use; `cleanup()` removes it. */
+export declare function tempDir(): {
+    get: () => Promise<string>;
+    cleanup: () => Promise<void>;
+};
+export {};