@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/dist/runtime-contracts.js

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+import { ARTIFACT_NEXT_RUNTIME, artifactNextSecretNameSchema } from './manifest-next.js';
+import { MAX_STUDIO_PATH_LENGTH } from './paths.js';
+export { resolveArtifactNextImages } from './next-image-config.js';
+/** Shared by local collection, repository collection and the bounded source-upload API. */
+export const ARTIFACT_NEXT_SOURCE_LIMITS = Object.freeze({
+    maxFiles: 2_000,
+    maxFileBytes: 10 * 1024 * 1024,
+    maxTotalBytes: 32 * 1024 * 1024,
+});
+const identifierSchema = z.string().min(1).max(256).regex(/^[^\s\u0000-\u001f\u007f]+$/);
+const timestampSchema = z.iso.datetime();
+const exactVersionSchema = z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/, 'An exact, stable toolchain version is required');
+export const artifactSha256DigestSchema = z.string().regex(/^[a-f0-9]{64}$/, 'Expected a lowercase SHA-256 digest');
+/** Immutable Next deploymentId from compiled output; distinct from the Atlas activation ID. */
+export const artifactNextFrameworkBuildIdSchema = z.string().min(1).max(128).refine((value) => !/[^A-Za-z0-9_-]/.test(value), 'Expected a canonical Next.js deploymentId containing only letters, digits, underscores and hyphens');
+const imageDigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/, 'Expected a SHA-256 image digest');
+const imageReferenceSchema = z.string().max(1024).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*(?::[1-9][0-9]{0,4})?(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)+@sha256:[a-f0-9]{64}$/, 'Expected a registry image reference pinned by digest');
+const excludedSourceSegments = new Set([
+    '.git', 'node_modules', '.next', '.npmrc', '.netrc', '.aws', '.ssh', '.config',
+    'dist', '.artifact-studio', '.git-credentials', '.pypirc', '.azure', '.gcloud', '.doppler',
+    '.turbo', 'coverage', '.docker',
+]);
+/** Shared upload exclusion policy. Content scanning and filesystem containment remain separate checks. */
+export function isExcludedArtifactSourcePath({ path }) {
+    return path.split('/').some((segment) => {
+        const normalized = segment.toLowerCase();
+        return excludedSourceSegments.has(normalized)
+            || normalized.startsWith('.env') || normalized.startsWith('.yarnrc')
+            || /(?:^|[-_.])(?:credentials?|service[-_]?account)(?:[-_.].*)?\.json$/.test(normalized)
+            || /\.(pem|key|p12|pfx|jks)$/.test(normalized);
+    });
+}
+/** POSIX source paths only; filesystem readers must additionally reject symlink escapes. */
+export const artifactSourcePathSchema = z.string().min(1).max(MAX_STUDIO_PATH_LENGTH).refine((path) => {
+    if (path !== path.trim() || /[\\%:\u0000-\u001f\u007f]/.test(path))
+        return false;
+    return !isExcludedArtifactSourcePath({ path })
+        && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}, 'Source paths must be relative and exclude credentials, dependencies and build output');
+/** An exact browser origin, not a URL prefix or an allowlist wildcard. */
+export const artifactRuntimeOriginSchema = z.string().max(2048).refine((value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.origin === value && !url.hostname.includes('*');
+    }
+    catch {
+        return false;
+    }
+}, 'Expected an exact, canonical HTTPS origin');
+const sourceFileSchema = z.strictObject({
+    path: artifactSourcePathSchema,
+    sha256: artifactSha256DigestSchema,
+    sizeBytes: z.number().int().nonnegative().max(ARTIFACT_NEXT_SOURCE_LIMITS.maxFileBytes),
+});
+/** Metadata points to an immutable snapshot; file bytes travel through the source-upload API. */
+export const artifactNextBuildInputSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    framework: z.literal('nextjs'),
+    projectId: identifierSchema,
+    source: z.strictObject({
+        snapshotId: identifierSchema,
+        sha256: artifactSha256DigestSchema,
+        git: z.strictObject({
+            repositoryId: identifierSchema,
+            commitSha: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/, 'Expected a full Git commit SHA'),
+        }),
+        files: z.array(sourceFileSchema).min(1).max(ARTIFACT_NEXT_SOURCE_LIMITS.maxFiles),
+    }),
+    lockfile: z.strictObject({ path: z.literal('pnpm-lock.yaml'), sha256: artifactSha256DigestSchema }),
+    toolchain: z.strictObject({
+        node: exactVersionSchema.refine((version) => version.startsWith(`${ARTIFACT_NEXT_RUNTIME.node}.`), 'Unsupported Node runtime'),
+        next: exactVersionSchema.refine((version) => version.startsWith(`${ARTIFACT_NEXT_RUNTIME.next}.`), 'Unsupported Next.js release line'),
+        react: exactVersionSchema.refine((version) => version.startsWith(`${ARTIFACT_NEXT_RUNTIME.react}.`), 'Unsupported React release line'),
+        packageManager: z.strictObject({ name: z.literal('pnpm'), version: exactVersionSchema }),
+        builderImageDigest: imageDigestSchema,
+    }),
+}).superRefine((value, ctx) => {
+    if (value.source.files.reduce((total, file) => total + file.sizeBytes, 0) > ARTIFACT_NEXT_SOURCE_LIMITS.maxTotalBytes) {
+        ctx.addIssue({ code: 'custom', path: ['source', 'files'], message: 'Source snapshot exceeds the upload size limit' });
+    }
+    const seen = new Set();
+    for (const [index, file] of value.source.files.entries()) {
+        if (seen.has(file.path)) {
+            ctx.addIssue({ code: 'custom', path: ['source', 'files', index, 'path'], message: 'Duplicate source path' });
+        }
+        seen.add(file.path);
+    }
+    for (const [index, file] of value.source.files.entries()) {
+        const segments = file.path.split('/');
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            if (seen.has(segments.slice(0, depth).join('/'))) {
+                ctx.addIssue({ code: 'custom', path: ['source', 'files', index, 'path'], message: 'A source file cannot also be a directory' });
+                break;
+            }
+        }
+    }
+    const lockfile = value.source.files.find((file) => file.path === value.lockfile.path);
+    if (!lockfile || lockfile.sha256 !== value.lockfile.sha256) {
+        ctx.addIssue({ code: 'custom', path: ['lockfile'], message: 'The pinned lockfile must match a file in the source snapshot' });
+    }
+});
+const immutableObjectSchema = z.strictObject({ objectId: identifierSchema, sha256: artifactSha256DigestSchema });
+export const artifactDeploymentOutputSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('static'), bundle: immutableObjectSchema }),
+    z.strictObject({
+        kind: z.literal('next-server'),
+        frameworkBuildId: artifactNextFrameworkBuildIdSchema,
+        imageRef: imageReferenceSchema,
+        assets: immutableObjectSchema,
+        buildInputSha256: artifactSha256DigestSchema,
+    }),
+]);
+const operationFields = {
+    id: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    kind: z.enum(['build', 'deploy', 'preview', 'rollback', 'suspend', 'delete']),
+    deploymentId: identifierSchema.optional(),
+    createdAt: timestampSchema,
+    updatedAt: timestampSchema,
+};
+const operationProgressSchema = z.strictObject({
+    stage: z.string().min(1).max(128),
+    percent: z.number().min(0).max(100).optional(),
+});
+export const artifactOperationSchema = z.discriminatedUnion('status', [
+    z.strictObject({ ...operationFields, status: z.literal('queued') }),
+    z.strictObject({ ...operationFields, status: z.literal('running'), progress: operationProgressSchema.optional() }),
+    z.strictObject({ ...operationFields, status: z.literal('succeeded'), completedAt: timestampSchema }),
+    z.strictObject({
+        ...operationFields,
+        status: z.literal('failed'),
+        completedAt: timestampSchema,
+        error: z.strictObject({ code: identifierSchema, message: z.string().min(1).max(4096) }),
+    }),
+    z.strictObject({ ...operationFields, status: z.literal('cancelled'), completedAt: timestampSchema }),
+]).superRefine((value, ctx) => {
+    if (Date.parse(value.updatedAt) < Date.parse(value.createdAt)) {
+        ctx.addIssue({ code: 'custom', path: ['updatedAt'], message: 'An operation cannot be updated before it was created' });
+    }
+    if ('completedAt' in value && (Date.parse(value.completedAt) < Date.parse(value.createdAt)
+        || Date.parse(value.completedAt) > Date.parse(value.updatedAt))) {
+        ctx.addIssue({ code: 'custom', path: ['completedAt'], message: 'Completion must be between creation and the last update' });
+    }
+});
+/** Runtime bootstrap is ephemeral. Do not persist bootstrap URLs in deployment history. */
+export const artifactRuntimeSessionSchema = z.strictObject({
+    id: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    mode: z.enum(['local', 'preview', 'published']),
+    origin: artifactRuntimeOriginSchema,
+    parentOrigin: artifactRuntimeOriginSchema,
+    bootstrapUrl: z.url().max(4096),
+    bridge: z.strictObject({ protocolVersion: z.literal(1), channelId: identifierSchema }),
+    expiresAt: timestampSchema,
+}).superRefine((value, ctx) => {
+    let validBootstrap = false;
+    try {
+        const url = new URL(value.bootstrapUrl);
+        validBootstrap = url.origin === value.origin && !url.username && !url.password && !url.hash;
+    }
+    catch {
+        // URL syntax failures are also reported by the field schema; never throw from safeParse.
+    }
+    if (!validBootstrap) {
+        ctx.addIssue({ code: 'custom', path: ['bootstrapUrl'], message: 'Bootstrap must use the exact runtime origin without credentials or a fragment' });
+    }
+});
+/** Public session metadata contains no tunnel bearer, local credentials or managed secrets. */
+export const artifactLocalDevSessionSchema = z.strictObject({
+    id: identifierSchema,
+    ownerId: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    origin: artifactRuntimeOriginSchema,
+    sourceRevision: artifactSha256DigestSchema.optional(),
+    revision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    state: z.enum(['starting', 'compiling', 'ready', 'reconnecting', 'failed', 'offline', 'revoked', 'expired']),
+    lease: z.strictObject({
+        id: identifierSchema,
+        fence: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+        expiresAt: timestampSchema,
+    }),
+    createdAt: timestampSchema,
+    updatedAt: timestampSchema,
+    expiresAt: timestampSchema,
+}).superRefine((value, ctx) => {
+    const created = Date.parse(value.createdAt);
+    const updated = Date.parse(value.updatedAt);
+    const expires = Date.parse(value.expiresAt);
+    const leaseExpires = Date.parse(value.lease.expiresAt);
+    if (updated < created || expires <= created || leaseExpires <= created || leaseExpires > expires) {
+        ctx.addIssue({ code: 'custom', path: ['lease', 'expiresAt'], message: 'Session timestamps must be ordered and the lease cannot outlive its session' });
+    }
+    if (['starting', 'compiling', 'ready', 'reconnecting'].includes(value.state) && updated >= leaseExpires) {
+        ctx.addIssue({ code: 'custom', path: ['updatedAt'], message: 'An active session must have an unexpired lease at its last update' });
+    }
+});
+export const artifactActivationSchema = z.strictObject({
+    id: identifierSchema,
+    projectId: identifierSchema,
+    environment: identifierSchema,
+    deploymentId: identifierSchema,
+    configurationSha256: artifactSha256DigestSchema,
+    policySha256: artifactSha256DigestSchema,
+    secretVersions: z.array(z.strictObject({
+        binding: artifactNextSecretNameSchema,
+        secretId: identifierSchema,
+        version: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    })).max(100),
+    cacheGeneration: identifierSchema,
+    activatedAt: timestampSchema,
+    activatedBy: identifierSchema,
+}).superRefine((value, ctx) => {
+    const bindings = new Set();
+    for (const [index, secret] of value.secretVersions.entries()) {
+        if (bindings.has(secret.binding)) {
+            ctx.addIssue({ code: 'custom', path: ['secretVersions', index, 'binding'], message: 'Secret binding names must be unique' });
+        }
+        bindings.add(secret.binding);
+    }
+});

package/dist/sdk.d.ts

@@ -1,4 +1,22 @@
+import { type StartStorageUpload, type StorageUploadSession } from '@sequenceholdings/storage';
+export interface SequenceStorageOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    onProgress?: (progress: {
+        uploadId: string;
+        fileId: string;
+        uploadedBytes: number;
+    }) => void;
+}
+export interface SequenceStorage {
+    upload(workspaceId: string, input: StartStorageUpload, file: Blob, options?: SequenceStorageOptions): Promise<StorageUploadSession>;
+    resume(workspaceId: string, uploadId: string, file: Blob, options?: SequenceStorageOptions): Promise<StorageUploadSession>;
+}
 export interface SequenceApiFetchOptions {
+    traceAction?: {
+        id: string;
+        key: string;
+    };
     method?: string;
     body?: unknown;
     headers?: Record<string, string>;
@@ -7,6 +25,8 @@ export interface SequenceApiFetchResponse<TBody = unknown> {
     ok: boolean;
     status: number;
     body: TBody;
+    /** Allowlisted download headers for binary responses; keys are lowercase. */
+    headers?: Record<string, string>;
 }
 export interface SequenceApiUploadOptions {
     timeoutMs?: number;
@@ -28,7 +48,10 @@ export interface SequenceApi {
     delete<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;
 }
 export interface SequenceFunctions {
-    invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;
+    invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>, traceAction?: {
+        id: string;
+        key: string;
+    }): Promise<TOutput>;
 }
 export interface SequenceUser {
     current(): Promise<{
@@ -109,6 +132,7 @@ export interface SequenceHost {
     }): void;
 }
 export interface SequenceArtifactSdk {
+    storage: SequenceStorage;
     api: SequenceApi;
     ai: {
         fetch(path: string, options?: SequenceApiFetchOptions): Promise<Response>;
@@ -128,3 +152,398 @@ declare global {
 }
 export declare const seq: SequenceArtifactSdk;
 export default seq;
+/** Typed metadata API plus direct browser-host transfers for sandboxed Artifacts. */
+export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk): {
+    workspace(id: string): {
+        uploads: {
+            put: (input: StartStorageUpload, file: Blob, options?: SequenceStorageOptions) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "aborted" | "complete" | "pending";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            resume: (uploadId: string, file: Blob, options?: SequenceStorageOptions) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "aborted" | "complete" | "pending";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            start: (input: StartStorageUpload) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            get: (id: string) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            complete: (id: string, input?: import("@sequenceholdings/storage").CompleteStorageUpload) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            abort: (id: string) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+        };
+        get: () => Promise<{
+            id: string;
+            name: string;
+            description: string;
+            environment: string;
+            state: "active" | "trashed" | "purging";
+            revision: number;
+            createdAt: string;
+            role: "viewer" | "editor" | "admin" | "owner";
+            quotaBytes: number;
+            usedBytes: number;
+            reservedBytes: number;
+        }>;
+        delete: (expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        list: (options?: import("@sequenceholdings/storage").StorageListOptions & {
+            parentId?: string | null;
+            trash?: boolean;
+        }) => Promise<{
+            items: {
+                id: string;
+                workspaceId: string;
+                parentId: string | null;
+                name: string;
+                kind: "file" | "folder";
+                state: "active" | "trashed" | "purging";
+                restricted: boolean;
+                revision: number;
+                currentVersionId: string | null;
+                metadata: Record<string, string>;
+                createdAt: string;
+                updatedAt: string;
+                role: "viewer" | "editor" | "admin";
+                size: number | null;
+                contentType: string | null;
+            }[];
+            nextCursor: string | null;
+        }>;
+        getNode: (id: string) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        createFolder: (name: string, parentId?: string | null, { idempotencyKey, }?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        update: (id: string, input: import("zod").input<typeof import("@sequenceholdings/storage").updateNodeSchema>) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        trash: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        restore: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        purge: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        download: (id: string, options?: {
+            versionId?: string;
+            preview?: boolean;
+        }) => Promise<{
+            url: string;
+            expiresAt: string;
+            preview: boolean;
+        }>;
+        versions: (id: string, options?: {
+            before?: number;
+            limit?: number;
+        }) => Promise<{
+            items: {
+                id: string;
+                fileId: string;
+                revision: number;
+                size: number;
+                checksum: string;
+                contentType: string;
+                createdAt: string;
+                createdBy: string;
+                state: "active" | "purging";
+            }[];
+            nextRevision: number | null;
+        }>;
+        restoreVersion: (id: string, versionId: string, expectedRevision: number) => Promise<{
+            id: string;
+            fileId: string;
+            revision: number;
+            size: number;
+            checksum: string;
+            contentType: string;
+            createdAt: string;
+            createdBy: string;
+            state: "active" | "purging";
+        }>;
+        deleteVersion: (id: string, versionId: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        access: (id?: string) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        setAccess: (input: import("zod").input<typeof import("@sequenceholdings/storage").updateStorageAccessSchema>, id?: string) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        transferOwner: (principal: {
+            type: "user" | "service_account";
+            id: string;
+        }, expectedRevision: number) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        operations: (options?: {
+            before?: string;
+            limit?: number;
+            scope?: import("@sequenceholdings/storage").StorageOperationScope;
+        }) => Promise<{
+            items: {
+                id: string;
+                workspaceId: string;
+                targetId: string | null;
+                kind: "purge" | "delete_version";
+                status: "queued" | "running" | "succeeded" | "failed";
+                completed: number;
+                total: number;
+                error: string | null;
+                createdAt: string;
+                updatedAt: string;
+                canRetry: boolean;
+            }[];
+            nextCursor: string | null;
+        }>;
+        retryOperation: (id: string) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+    };
+    capabilities: () => Promise<{
+        canProvision: boolean;
+        uploadMethods: string[];
+    }>;
+    list: (options?: import("@sequenceholdings/storage").StorageListOptions) => Promise<{
+        items: {
+            id: string;
+            name: string;
+            description: string;
+            environment: string;
+            state: "active" | "trashed" | "purging";
+            revision: number;
+            createdAt: string;
+            role: "viewer" | "editor" | "admin" | "owner";
+            quotaBytes: number;
+            usedBytes: number;
+            reservedBytes: number;
+        }[];
+        nextCursor: string | null;
+    }>;
+    shared: (options?: import("@sequenceholdings/storage").StorageListOptions & {
+        trash?: boolean;
+    }) => Promise<{
+        items: {
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }[];
+        nextCursor: string | null;
+    }>;
+    apply: (manifest: import("@sequenceholdings/storage").WorkspaceManifest) => Promise<{
+        id: string;
+        name: string;
+        description: string;
+        environment: string;
+        state: "active" | "trashed" | "purging";
+        revision: number;
+        createdAt: string;
+        role: "viewer" | "editor" | "admin" | "owner";
+        quotaBytes: number;
+        usedBytes: number;
+        reservedBytes: number;
+    }>;
+};
+/** Explicit scope keeps concurrent browser actions isolated. The key is a safe
+ * author label, never a payload or an authentication claim. */
+export declare function withTraceAction<T>({ key, sdk }: {
+    key: string;
+    sdk?: SequenceArtifactSdk;
+}, run: (client: Pick<SequenceArtifactSdk, 'api' | 'functions'>) => Promise<T>): Promise<T>;