@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/skill-registry/client.js

@@ -0,0 +1,345 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadGlobalConfig, normalizeEnvironmentBaseUrl, readEnvironmentProfile, } from '../config.js';
+import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
+import { businessEndpoint } from '../utils/environment-endpoints.js';
+import { message, RegistryError } from './messages.js';
+import { MAX_BUNDLE_BYTES, parseSkillReference, sha256 } from './package.js';
+const ROOT = '/api/agent/skill-registry/managed';
+const MAX_JSON_BYTES = 2 * 1024 * 1024;
+export function resolveRegistryCredentials(options) {
+    const config = options.config ?? loadGlobalConfig();
+    const savedUrl = typeof config.backendUrl === 'string'
+        ? config.backendUrl
+        : typeof config.url === 'string'
+            ? config.url
+            : undefined;
+    const raw = options.url ||
+        process.env.PLAYCRAFT_API_URL ||
+        process.env.PLAYCRAFT_URL ||
+        savedUrl ||
+        DEFAULT_PLAYCRAFT_CLOUD_BASE;
+    // Reject query/fragment credentials instead of silently normalizing them away.
+    try {
+        businessEndpoint(raw, ROOT);
+    }
+    catch {
+        throw new RegistryError('invalid_environment', message('invalidUrl'));
+    }
+    const url = normalizeEnvironmentBaseUrl(raw);
+    if (!url)
+        throw new RegistryError('invalid_environment', message('invalidUrl'));
+    const profile = readEnvironmentProfile(config, url);
+    const legacy = savedUrl && normalizeEnvironmentBaseUrl(savedUrl) === url && typeof config.token === 'string'
+        ? config.token
+        : undefined;
+    const token = options.token || process.env.PLAYCRAFT_TOKEN || profile?.token || legacy;
+    if (!token)
+        throw new RegistryError('authentication_required', message('login'));
+    return { url, token };
+}
+async function readBounded(response, maximum) {
+    const contentLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > maximum) {
+        await response.body?.cancel();
+        throw new RegistryError('response_too_large', message('tooLarge'));
+    }
+    if (!response.body)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            length += chunk.value.byteLength;
+            if (length > maximum) {
+                await reader.cancel();
+                throw new RegistryError('response_too_large', message('tooLarge'));
+            }
+            chunks.push(Buffer.from(chunk.value));
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, length);
+}
+export class RegistryClient {
+    environment;
+    token;
+    transport;
+    timeoutMs;
+    receiptDirectory;
+    constructor(options = {}) {
+        const credentials = resolveRegistryCredentials(options);
+        this.environment = credentials.url;
+        this.token = credentials.token;
+        this.transport = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.receiptDirectory =
+            options.receiptDirectory ?? path.join(homedir(), '.playcraft', 'registry-requests');
+    }
+    async receipt(key, status, route) {
+        await fs.mkdir(this.receiptDirectory, { recursive: true, mode: 0o700 });
+        const temporary = path.join(this.receiptDirectory, `.${randomUUID()}.tmp`);
+        try {
+            await fs.writeFile(temporary, JSON.stringify({
+                requestKey: key,
+                status,
+                environment: this.environment,
+                route,
+                updatedAt: new Date().toISOString(),
+            }), { flag: 'wx', mode: 0o600 });
+            await fs.rename(temporary, path.join(this.receiptDirectory, `${key}.json`));
+        }
+        finally {
+            await fs.rm(temporary, { force: true });
+        }
+    }
+    async request(route, options = {}) {
+        const native = options.surface === 'workbench';
+        const requestRoute = native ? `/api/agent/skill-registry${route}` : route;
+        const url = businessEndpoint(this.environment, native ? requestRoute : `${ROOT}${route}`);
+        for (const [key, value] of Object.entries(options.query ?? {}))
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        const method = options.method ?? (options.body ? 'POST' : 'GET');
+        const requestKey = method !== 'GET'
+            ? (options.requestKey ??
+                sha256(JSON.stringify([
+                    this.environment,
+                    sha256(this.token),
+                    native ? `${method}:${requestRoute}` : route,
+                    options.body,
+                    options.bundle?.uploadHash,
+                ])))
+            : undefined;
+        const requestId = randomUUID();
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: options.binary ? 'application/gzip' : 'application/json',
+            'X-Request-Id': requestId,
+        };
+        let body;
+        if (options.body) {
+            const payload = (options.requestKeyInBody ?? !native) ? { ...options.body, requestKey } : options.body;
+            if (options.bundle) {
+                const form = new FormData();
+                form.append('file', new Blob([new Uint8Array(options.bundle.archive)], { type: 'application/gzip' }), 'skill.tar.gz');
+                for (const [key, value] of Object.entries(payload))
+                    if (value !== undefined)
+                        form.append(key, String(value));
+                body = form;
+            }
+            else {
+                headers['Content-Type'] = 'application/json';
+                body = JSON.stringify(payload);
+            }
+            await this.receipt(requestKey, 'pending', requestRoute);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.transport(url.toString(), {
+                method,
+                headers,
+                body,
+                signal: controller.signal,
+                redirect: 'error',
+            });
+            const buffer = await readBounded(response, options.binary && response.ok ? MAX_BUNDLE_BYTES : MAX_JSON_BYTES);
+            if (options.binary && response.ok)
+                return { archive: buffer, artifactHash: response.headers.get('x-artifact-hash') };
+            let result;
+            try {
+                result = JSON.parse(buffer.toString('utf8'));
+            }
+            catch {
+                throw new RegistryError('invalid_response', message('invalidResponse'), { requestId, requestKey }, response.status);
+            }
+            if (!response.ok) {
+                const error = result;
+                if (requestKey && response.status < 500)
+                    await this.receipt(requestKey, 'rejected', requestRoute);
+                throw new RegistryError(error.code ?? 'request_failed', typeof error.message === 'string' ? error.message : message('requestFailed'), { requestId, requestKey, response: result }, response.status);
+            }
+            options.validate?.(result);
+            if (requestKey)
+                await this.receipt(requestKey, 'completed', requestRoute);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof RegistryError)
+                throw error;
+            throw new RegistryError('request_incomplete', message('network'), { requestId, requestKey });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    list(scope, query = {}) {
+        return this.request('/catalog', { query: { ...scope, ...query } });
+    }
+    async info(skillRef, version, scope) {
+        const result = await this.request(`/skills/${encodeURIComponent(skillRef)}`, {
+            query: { ...scope, version },
+        });
+        assertRegistryItem(result, skillRef, version);
+        return result;
+    }
+    versions(skillRef, scope) {
+        return this.request(`/skills/${encodeURIComponent(skillRef)}/versions`, { query: scope });
+    }
+    async upload(bundle, scope, options = {}) {
+        const item = await this.request('/bundles', {
+            body: { skillRef: bundle.skillRef, version: bundle.version, ...scope, ...options },
+            bundle,
+        });
+        assertRegistryItem(item, bundle.skillRef, bundle.version);
+        if (item.published !== false)
+            throw new RegistryError('invalid_response', message('invalidResponse'));
+        return item;
+    }
+    async download(item) {
+        const result = await this.request(this.versionRoute(item, 'archive'), { binary: true });
+        if (result.artifactHash !== item.artifactHash || sha256(result.archive) !== item.artifactHash)
+            throw new RegistryError('artifact_hash_mismatch', message('invalidResponse'));
+        return result.archive;
+    }
+    check(item, scope) {
+        return this.request(this.versionRoute(item, 'publish-check'), { query: scope });
+    }
+    async prepareRelease(item, scope, action, reason) {
+        const target = {
+            environment: this.environment,
+            action,
+            route: this.versionRoute(item, action),
+            skillRef: item.skillRef,
+            skillVersionId: item.skillVersionId,
+            version: item.version,
+            artifactHash: item.artifactHash,
+            scope: scope.scope,
+            teamId: scope.teamId ?? null,
+            reason: reason ?? null,
+        };
+        const signature = sha256(JSON.stringify([sha256(this.token), target]));
+        const prefix = `release-${signature}-`;
+        await fs.mkdir(this.receiptDirectory, { recursive: true, mode: 0o700 });
+        const pending = async () => {
+            const files = (await fs.readdir(this.receiptDirectory))
+                .filter((name) => name.startsWith(prefix) && name.endsWith('.json'))
+                .sort();
+            for (const file of files) {
+                const stored = JSON.parse(await fs.readFile(path.join(this.receiptDirectory, file), 'utf8'));
+                if (stored.signature !== signature ||
+                    JSON.stringify(stored.target) !== JSON.stringify(target) ||
+                    typeof stored.requestKey !== 'string' ||
+                    !/^[a-f0-9]{64}$/.test(stored.requestKey) ||
+                    !(stored.expectedStableVersionId === null ||
+                        typeof stored.expectedStableVersionId === 'string')) {
+                    throw new RegistryError('invalid_release_receipt', message('invalidReceipt'));
+                }
+                const receipt = await fs
+                    .readFile(path.join(this.receiptDirectory, `${stored.requestKey}.json`), 'utf8')
+                    .catch((error) => {
+                    if (error.code === 'ENOENT')
+                        return null;
+                    throw error;
+                });
+                const status = receipt ? JSON.parse(receipt).status : 'pending';
+                if (status === 'completed' || status === 'rejected')
+                    continue;
+                if (status !== 'pending')
+                    throw new RegistryError('invalid_release_receipt', message('invalidReceipt'));
+                return {
+                    expectedStableVersionId: stored.expectedStableVersionId,
+                    requestKey: stored.requestKey,
+                };
+            }
+            return null;
+        };
+        const existing = await pending();
+        if (existing)
+            return existing;
+        const check = await this.check(item, scope);
+        if (!(check.currentStableVersionId === null || typeof check.currentStableVersionId === 'string'))
+            throw new RegistryError('invalid_response', message('invalidResponse'));
+        // Another invocation may have persisted its original comparison while this check was in flight.
+        const concurrentlyPrepared = await pending();
+        if (concurrentlyPrepared)
+            return concurrentlyPrepared;
+        const attempt = {
+            expectedStableVersionId: check.currentStableVersionId,
+            requestKey: sha256(randomUUID()),
+        };
+        const temporary = path.join(this.receiptDirectory, `.${randomUUID()}.tmp`);
+        try {
+            await fs.writeFile(temporary, JSON.stringify({ signature, target, ...attempt, status: 'pending' }), { flag: 'wx', mode: 0o600 });
+            await fs.rename(temporary, path.join(this.receiptDirectory, `${prefix}${attempt.requestKey}.json`));
+        }
+        finally {
+            await fs.rm(temporary, { force: true });
+        }
+        return attempt;
+    }
+    publish(item, scope, expectedStableVersionId, requestKey) {
+        return this.release(item, 'publish', { ...scope, expectedStableVersionId }, requestKey);
+    }
+    rollback(item, scope, expectedStableVersionId, reason, requestKey) {
+        return this.release(item, 'rollback', { ...scope, expectedStableVersionId, reason }, requestKey);
+    }
+    async release(item, action, body, requestKey) {
+        return this.request(this.versionRoute(item, action), {
+            body,
+            requestKey,
+            validate: (result) => {
+                if (!result ||
+                    result.skillRef !== item.skillRef ||
+                    result.skillVersionId !== item.skillVersionId ||
+                    result.version !== item.version ||
+                    result.artifactHash !== item.artifactHash ||
+                    !['published', 'review_pending'].includes(result.status) ||
+                    result.published !== (result.status === 'published'))
+                    throw new RegistryError('invalid_response', message('invalidResponse'));
+            },
+        });
+    }
+    submit(item, scope) {
+        return this.request(this.versionRoute(item, 'review'), { body: scope });
+    }
+    reviews(scope) {
+        return this.request('/reviews', { query: scope });
+    }
+    decide(reviewId, decision, reason) {
+        return this.request(`/reviews/${encodeURIComponent(reviewId)}/decision`, {
+            body: { decision, reason },
+        });
+    }
+    history(skillRef, scope) {
+        return this.request(`/skills/${encodeURIComponent(skillRef)}/history`, { query: scope });
+    }
+    versionRoute(item, action) {
+        return `/skills/${encodeURIComponent(item.skillRef)}/versions/${encodeURIComponent(item.skillVersionId)}/${action}`;
+    }
+}
+export function assertRegistryItem(item, skillRef, version) {
+    if (!item ||
+        item.skillRef !== skillRef ||
+        (version !== undefined && item.version !== version) ||
+        typeof item.version !== 'string' ||
+        typeof item.skillVersionId !== 'string' ||
+        !item.skillVersionId ||
+        !/^[a-f0-9]{64}$/.test(item.artifactHash))
+        throw new RegistryError('invalid_response', message('invalidResponse'));
+    try {
+        parseSkillReference(`${item.skillRef}@${item.version}`, true);
+    }
+    catch {
+        throw new RegistryError('invalid_response', message('invalidResponse'));
+    }
+}

package/dist/skill-registry/commands.js

@@ -0,0 +1,180 @@
+import { promises as fs } from 'node:fs';
+import { RegistryClient } from './client.js';
+import { packSkillDirectory, parseSkillReference, unpackSkillArchive } from './package.js';
+import { message, RegistryError } from './messages.js';
+import { registerEvaluationCommands } from './evaluation-commands.js';
+export function registryScope(options) {
+    const scope = options.scope ?? 'private';
+    if (!['private', 'team', 'platform'].includes(scope) ||
+        (scope === 'team' ? !options.team?.trim() : Boolean(options.team))) {
+        throw new RegistryError('invalid_scope', message('invalidScope'));
+    }
+    return {
+        scope: scope,
+        ...(options.team ? { teamId: options.team } : {}),
+    };
+}
+export function registerRegistryCommands(skills, dependencies = {}) {
+    const registry = skills
+        .command('registry')
+        .enablePositionalOptions(false)
+        .description(message('group'))
+        .option('--url <url>', message('url'))
+        .option('--token <token>', message('token'))
+        .option('--json', message('json'))
+        .option('--scope <scope>', message('scope'), 'private')
+        .option('--team <teamId>', message('team'));
+    const stdout = dependencies.stdout ?? ((text) => console.log(text));
+    const stderr = dependencies.stderr ?? ((text) => console.error(text));
+    registerEvaluationCommands(registry, dependencies);
+    function action(command, callback) {
+        command.action(async (...values) => {
+            const invoked = values.at(-1);
+            const options = invoked.optsWithGlobals();
+            try {
+                registryScope(options);
+                const client = dependencies.client?.(options) ?? new RegistryClient(options);
+                const result = await callback(client, options, values.slice(0, -2));
+                stdout(JSON.stringify(result, null, options.json ? undefined : 2));
+            }
+            catch (error) {
+                const failure = error instanceof RegistryError
+                    ? error
+                    : new RegistryError('operation_failed', error instanceof Error ? error.message : String(error));
+                const result = JSON.stringify({
+                    error: {
+                        code: failure.code,
+                        message: failure.message,
+                        status: failure.status,
+                        details: failure.details,
+                    },
+                });
+                (options.json ? stdout : stderr)(result);
+                if (dependencies.failure)
+                    dependencies.failure();
+                else
+                    process.exitCode = 1;
+            }
+        });
+    }
+    function uploadOptions(command) {
+        return command
+            .option('--ref <ref>', message('ref'))
+            .option('--version <version>', message('version'))
+            .option('--base-version <version>', message('base'))
+            .option('--changelog <text>', message('changelog'));
+    }
+    async function exact(client, input, options) {
+        const reference = parseSkillReference(input, true);
+        return client.info(reference.skillRef, reference.version, registryScope(options));
+    }
+    async function upload(client, directory, options) {
+        const bundle = await packSkillDirectory(directory, {
+            ref: options.ref,
+            version: options.version,
+        });
+        if (options.baseVersion)
+            parseSkillReference(`${bundle.skillRef}@${options.baseVersion}`, true);
+        return client.upload(bundle, registryScope(options), {
+            baseVersion: options.baseVersion,
+            changelog: options.changelog,
+        });
+    }
+    action(registry
+        .command('list')
+        .description(message('list'))
+        .option('--query <text>', message('query'))
+        .option('--limit <count>', message('limit'), '20')
+        .option('--cursor <cursor>', message('cursor')), async (client, options) => {
+        const limit = Number(options.limit);
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+            throw new RegistryError('invalid_limit', message('limit'));
+        return client.list(registryScope(options), {
+            search: options.query,
+            limit,
+            cursor: options.cursor,
+        });
+    });
+    action(registry
+        .command('info <reference>')
+        .description(message('info'))
+        .option('--versions', message('versions'))
+        .option('--files', message('files')), async (client, options, [input]) => {
+        const ref = parseSkillReference(input);
+        if (options.versions)
+            return client.versions(ref.skillRef, registryScope(options));
+        const item = await client.info(ref.skillRef, ref.version, registryScope(options));
+        const { contentMd: _content, files, ...summary } = item;
+        return options.files ? { ...summary, files } : summary;
+    });
+    action(registry
+        .command('pull <reference>')
+        .description(message('pull'))
+        .requiredOption('--out <directory>', message('out')), async (client, options, [input]) => {
+        const ref = parseSkillReference(input);
+        const item = await client.info(ref.skillRef, ref.version, registryScope(options));
+        const archive = await client.download(item);
+        const output = await unpackSkillArchive(archive, options.out, {
+            environment: client.environment,
+            skillRef: item.skillRef,
+            version: item.version,
+            artifactHash: item.artifactHash,
+        });
+        return {
+            skillRef: item.skillRef,
+            skillVersionId: item.skillVersionId,
+            version: item.version,
+            artifactHash: item.artifactHash,
+            ...output,
+        };
+    });
+    action(uploadOptions(registry.command('push <directory>').description(message('push'))), (client, options, [directory]) => upload(client, directory, options));
+    action(uploadOptions(registry.command('update <reference>').description(message('update'))).requiredOption('--from <directory>', message('from')), async (client, options, [input]) => {
+        const ref = parseSkillReference(input);
+        if (ref.version ||
+            !options.baseVersion ||
+            !options.version ||
+            options.baseVersion === options.version ||
+            (options.ref && options.ref !== ref.skillRef)) {
+            throw new RegistryError('invalid_update', message('missingBase'));
+        }
+        return upload(client, options.from, { ...options, ref: ref.skillRef });
+    });
+    action(uploadOptions(registry.command('publish <source>').description(message('publish'))), async (client, options, [source]) => {
+        const stat = await fs.lstat(source).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!stat &&
+            [options.ref, options.version, options.baseVersion, options.changelog].some((value) => value !== undefined)) {
+            throw new RegistryError('upload_options_on_reference', message('uploadOptionsOnly'));
+        }
+        const item = stat
+            ? await upload(client, source, options)
+            : await exact(client, source, options);
+        const attempt = await client.prepareRelease(item, registryScope(options), 'publish');
+        return client.publish(item, registryScope(options), attempt.expectedStableVersionId, attempt.requestKey);
+    });
+    action(registry.command('publish-check <reference>').description(message('check')), async (client, options, [input]) => client.check(await exact(client, input, options), registryScope(options)));
+    action(registry.command('history <reference>').description(message('history')), async (client, options, [input]) => client.history(parseSkillReference(input).skillRef, registryScope(options)));
+    action(registry
+        .command('rollback <reference>')
+        .description(message('rollback'))
+        .requiredOption('--reason <text>', message('reason')), async (client, options, [input]) => {
+        const item = await exact(client, input, options);
+        const attempt = await client.prepareRelease(item, registryScope(options), 'rollback', options.reason);
+        return client.rollback(item, registryScope(options), attempt.expectedStableVersionId, options.reason, attempt.requestKey);
+    });
+    const review = registry.command('review').description(message('review'));
+    action(review.command('list').description(message('list')), (client, options) => client.reviews(registryScope(options)));
+    action(review.command('submit <reference>').description(message('submit')), async (client, options, [input]) => client.submit(await exact(client, input, options), registryScope(options)));
+    for (const decision of ['approve', 'reject']) {
+        const command = review.command(`${decision} <reviewId>`).description(message(decision));
+        if (decision === 'reject')
+            command.requiredOption('--reason <text>', message('reason'));
+        else
+            command.option('--reason <text>', message('reason'));
+        action(command, (client, options, [id]) => client.decide(id, decision === 'approve' ? 'approved' : 'rejected', options.reason));
+    }
+}

package/dist/skill-registry/evaluation-client.js

@@ -0,0 +1,156 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { RegistryClient, assertRegistryItem } from './client.js';
+import { message, RegistryError } from './messages.js';
+const terminal = new Set(['completed', 'error', 'cancelled']);
+const phases = new Set(['queued', 'preparing', 'running', 'grading', 'archiving', ...terminal]);
+export function requireUuid(value) {
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value))
+        throw new RegistryError('invalid_identifier', message('invalidIdentifier'));
+    return value;
+}
+function invalidResponse() {
+    throw new RegistryError('invalid_response', message('invalidResponse'));
+}
+function assertRun(run, expected) {
+    if (!run ||
+        typeof run.id !== 'string' ||
+        !phases.has(run.phase) ||
+        !Array.isArray(run.results) ||
+        Object.entries(expected).some(([key, value]) => run[key] !== value))
+        invalidResponse();
+    try {
+        requireUuid(run.id);
+    }
+    catch {
+        invalidResponse();
+    }
+}
+export function validatePollOptions(options) {
+    if (!Number.isFinite(options.timeoutSeconds) ||
+        options.timeoutSeconds <= 0 ||
+        options.timeoutSeconds > 86400 ||
+        !Number.isFinite(options.intervalSeconds) ||
+        options.intervalSeconds <= 0 ||
+        options.intervalSeconds > 60)
+        throw new RegistryError('invalid_poll_options', message('invalidPollOptions'));
+}
+export class EvaluationClient extends RegistryClient {
+    versionPath(item, action) {
+        requireUuid(item.skillVersionId);
+        return `/skills/${encodeURIComponent(item.skillRef)}/versions/${item.skillVersionId}/${action}`;
+    }
+    importPlatform(bundle, changelog, evaluationTemplateId) {
+        if (!changelog.trim() || changelog.length > 4000)
+            throw new RegistryError('invalid_changelog', message('changelog'));
+        if (evaluationTemplateId)
+            requireUuid(evaluationTemplateId);
+        return this.request(`/platform/skills/${encodeURIComponent(bundle.skillRef)}/bundle`, {
+            surface: 'workbench',
+            bundle,
+            body: { changelog, evaluationTemplateId },
+            validate: (result) => {
+                assertRegistryItem(result, bundle.skillRef, bundle.version);
+                if (typeof result.created !== 'boolean' || typeof result.lifecycle !== 'string')
+                    invalidResponse();
+            },
+        });
+    }
+    templates() {
+        return this.request('/evaluation-templates', { surface: 'workbench' });
+    }
+    createTemplate(input) {
+        return this.request('/evaluation-templates', { surface: 'workbench', body: input });
+    }
+    templateState(id, state) {
+        return this.request(`/evaluation-templates/${requireUuid(id)}/state`, {
+            surface: 'workbench',
+            body: { state },
+        });
+    }
+    models(workspaceId) {
+        return this.request('/evaluation-models', { surface: 'workbench', query: { workspaceId } });
+    }
+    config(item) {
+        return this.request(this.versionPath(item, 'evaluation-config'), {
+            surface: 'workbench',
+            validate: (result) => {
+                if (!result ||
+                    result.skillVersionId !== item.skillVersionId ||
+                    !Number.isInteger(result.revision))
+                    invalidResponse();
+            },
+        });
+    }
+    saveConfig(item, input) {
+        requireUuid(input.templateId);
+        if (!Number.isInteger(input.expectedRevision) || input.expectedRevision < 0)
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        return this.request(this.versionPath(item, 'evaluation-config'), {
+            surface: 'workbench',
+            method: 'PUT',
+            body: input,
+            validate: (result) => {
+                if (!result ||
+                    result.skillVersionId !== item.skillVersionId ||
+                    result.templateId !== input.templateId ||
+                    ![input.expectedRevision, input.expectedRevision + 1].includes(result.revision))
+                    invalidResponse();
+            },
+        });
+    }
+    createRun(item, input) {
+        requireUuid(item.skillVersionId);
+        requireUuid(input.configId);
+        if (!input.workspaceId.trim() || !/^[a-zA-Z0-9_-]{8,128}$/.test(input.requestKey))
+            throw new RegistryError('invalid_evaluation_input', message('invalidEvaluationInput'));
+        return this.request('/evaluation-runs', {
+            surface: 'workbench',
+            requestKey: input.requestKey,
+            requestKeyInBody: true,
+            body: { skillRef: item.skillRef, skillVersionId: item.skillVersionId, ...input },
+            validate: (result) => assertRun(result, {
+                skillVersionId: item.skillVersionId,
+                configId: input.configId,
+                workspaceId: input.workspaceId,
+            }),
+        });
+    }
+    run(id) {
+        return this.request(`/evaluation-runs/${requireUuid(id)}`, {
+            surface: 'workbench',
+            validate: (result) => assertRun(result, { id }),
+        });
+    }
+    runs(item, workspaceId) {
+        return this.request(this.versionPath(item, 'evaluation-runs'), {
+            surface: 'workbench',
+            query: { workspaceId },
+        });
+    }
+    evidence(runId, caseResultId) {
+        return this.request(`/evaluation-runs/${requireUuid(runId)}/artifacts/${requireUuid(caseResultId)}`, { surface: 'workbench' });
+    }
+    cancel(id) {
+        return this.request(`/evaluation-runs/${requireUuid(id)}/cancel`, {
+            surface: 'workbench',
+            body: {},
+        });
+    }
+    async wait(id, options) {
+        requireUuid(id);
+        validatePollOptions(options);
+        const deadline = Date.now() + options.timeoutSeconds * 1000;
+        while (true) {
+            const run = await this.run(id);
+            if (terminal.has(run.phase))
+                return run;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new RegistryError('evaluation_wait_timeout', message('waitTimeout'), {
+                    runId: id,
+                    phase: run.phase,
+                });
+            await sleep(Math.min(options.intervalSeconds * 1000, remaining));
+        }
+    }
+}