@aiwg/cli 2026.8.19 → 2026.8.20

package/dist/src/uhp/client.js

@@ -0,0 +1,374 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { link, lstat, mkdir, open, readFile, stat, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_UHP_LIMITS, isUhpLoopback, isUhpPrivateAddress, resolveUhpLimits, validateUhpEndpoint } from './config.js';
+import { parseUhpError, redactUhpText, UhpError } from './errors.js';
+import { parseUhpEventStream } from './sse.js';
+import { UHP_VERSION, } from './types.js';
+const ID_PATTERNS = {
+    harness: /^chrn_[A-Za-z0-9_-]+$/,
+    response: /^resp_[A-Za-z0-9_-]+$/,
+    session: /^hsess[A-Za-z0-9_-]+$/,
+    container: /^cntr_[A-Za-z0-9_-]+$/,
+    file: /^file_[A-Za-z0-9_-]+$/,
+};
+const TERMINAL = new Set(['completed', 'failed', 'incomplete', 'cancelled']);
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => [key, stableValue(child)]));
+}
+export function canonicalUhpRequestDigest(request) {
+    return createHash('sha256').update(JSON.stringify(stableValue(request))).digest('hex');
+}
+export function uhpIdempotencyKey(request) {
+    return `aiwg-${canonicalUhpRequestDigest(request)}`;
+}
+export function resolveEnvironmentCredential(profile, env = process.env) {
+    const value = env[profile.credential.name];
+    if (!value || /[\r\n]/.test(value))
+        throw new UhpError('missing_credential', `Credential reference '${profile.credential.name}' is unavailable or invalid`, { remoteState: 'not-started' });
+    return Promise.resolve(value);
+}
+function assertId(kind, value) {
+    if (!ID_PATTERNS[kind].test(value))
+        throw new UhpError('invalid_identifier', `Malformed UHP ${kind} identifier`, { remoteState: 'not-started' });
+    return value;
+}
+async function readBounded(response, maxBytes = 2 * 1024 * 1024) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new UhpError('response_too_large', 'UHP response exceeded the configured size limit', { remoteState: 'unknown' });
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > maxBytes)
+                throw new UhpError('response_too_large', 'UHP response exceeded the configured size limit', { remoteState: 'unknown' });
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}
+function parseJson(bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new UhpError('invalid_json', 'UHP server returned malformed JSON', { remoteState: 'unknown' });
+    }
+}
+function ensureDiscovery(value) {
+    if (!value || typeof value !== 'object')
+        throw new UhpError('invalid_discovery', 'UHP discovery document must be an object');
+    const discovery = value;
+    if (discovery.object !== 'uhp.discovery' || discovery.protocol !== 'uhp')
+        throw new UhpError('invalid_discovery', 'Endpoint did not return a UHP discovery document');
+    if (!Array.isArray(discovery.versions) || !discovery.versions.length || !discovery.versions.every(version => typeof version === 'string'))
+        throw new UhpError('invalid_discovery', 'UHP discovery versions must be a non-empty string array');
+    if (!discovery.versions.includes(discovery.default_version))
+        throw new UhpError('invalid_discovery', 'UHP default version is not listed as supported');
+    if (!discovery.versions.includes(UHP_VERSION))
+        throw new UhpError('unsupported_protocol_version', `UHP endpoint does not advertise required version ${UHP_VERSION}`);
+    if (!['core', 'extended', 'full'].includes(discovery.conformance_class))
+        throw new UhpError('invalid_discovery', 'UHP discovery has an unknown conformance class');
+    const required = discovery.conformance_class === 'core' ? ['streaming', 'sessions', 'cancellation', 'idempotency']
+        : discovery.conformance_class === 'extended' ? ['streaming', 'sessions', 'cancellation', 'idempotency', 'files_input', 'files_output', 'session_listing']
+            : ['streaming', 'sessions', 'cancellation', 'idempotency', 'files_input', 'files_output', 'session_listing', 'harness_management', 'session_sharing'];
+    if (required.some(capability => discovery.capabilities?.[capability] !== true))
+        throw new UhpError('invalid_discovery', 'UHP conformance class contradicts advertised capabilities');
+    return discovery;
+}
+function ensureResponse(value) {
+    if (!value || typeof value !== 'object')
+        throw new UhpError('invalid_response', 'UHP response must be an object', { remoteState: 'unknown' });
+    const response = value;
+    if (response.object !== 'response' || !ID_PATTERNS.response.test(response.id)
+        || !Number.isSafeInteger(response.created_at) || typeof response.status !== 'string'
+        || typeof response.model !== 'string' || !Array.isArray(response.output)
+        || (response.metadata !== undefined && (!response.metadata || typeof response.metadata !== 'object'))) {
+        throw new UhpError('invalid_response', 'UHP response is missing required identity or lifecycle fields', { remoteState: 'unknown' });
+    }
+    return { ...response, metadata: response.metadata ?? {} };
+}
+function safeFilename(value) {
+    let decoded = value;
+    for (let i = 0; i < 3; i += 1) {
+        try {
+            const next = decodeURIComponent(decoded);
+            if (next === decoded)
+                break;
+            decoded = next;
+        }
+        catch {
+            break;
+        }
+    }
+    const base = path.basename(decoded.replace(/\\/g, '/')).replace(/[\u0000-\u001f\u007f]/g, '_').trim();
+    if (!base || base === '.' || base === '..')
+        return `artifact-${randomUUID()}`;
+    return base.slice(0, 240);
+}
+export class UhpClient {
+    profileName;
+    profile;
+    fetchImpl;
+    credentialResolver;
+    base;
+    limits;
+    idempotency = new Map();
+    enforceDnsPolicy;
+    constructor(profileName, profile, fetchImpl = globalThis.fetch, credentialResolver = resolveEnvironmentCredential) {
+        this.profileName = profileName;
+        this.profile = profile;
+        this.fetchImpl = fetchImpl;
+        this.credentialResolver = credentialResolver;
+        this.base = validateUhpEndpoint(profile.endpoint, profile);
+        this.limits = { ...DEFAULT_UHP_LIMITS, ...resolveUhpLimits(profile) };
+        this.enforceDnsPolicy = fetchImpl === globalThis.fetch;
+    }
+    async assertResolvedTarget(target) {
+        if (!this.enforceDnsPolicy || /^[\d.]+$/.test(target.hostname) || target.hostname.startsWith('['))
+            return;
+        let addresses;
+        try {
+            addresses = await lookup(target.hostname, { all: true, verbatim: true });
+        }
+        catch {
+            throw new UhpError('endpoint_resolution_failed', 'UHP endpoint hostname could not be resolved', { remoteState: 'not-started' });
+        }
+        for (const { address } of addresses) {
+            if (!isUhpPrivateAddress(address))
+                continue;
+            const permitted = isUhpLoopback(address)
+                ? this.profile.trust?.allowInsecureLoopback === true
+                : this.profile.trust?.allowPrivateNetwork === true;
+            if (!permitted)
+                throw new UhpError('endpoint_resolution_blocked', 'UHP endpoint resolved outside the profile network trust policy', { remoteState: 'not-started' });
+        }
+    }
+    url(relative, base = this.base) {
+        const root = new URL(base.toString());
+        if (!root.pathname.endsWith('/'))
+            root.pathname += '/';
+        return new URL(relative.replace(/^\/+/, ''), root);
+    }
+    async fetch(relative, init) {
+        const authenticated = init.authenticated !== false;
+        const secret = authenticated ? await this.credentialResolver(this.profile) : undefined;
+        let target = this.url(relative);
+        let headers = new Headers(init.headers);
+        headers.set('UHP-Version', UHP_VERSION);
+        if (authenticated && secret)
+            headers.set('Authorization', `Bearer ${secret}`);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error('request timeout')), init.timeoutMs ?? this.limits.requestTimeoutMs);
+        const externalSignal = init.signal;
+        const abort = () => controller.abort(externalSignal?.reason);
+        externalSignal?.addEventListener('abort', abort, { once: true });
+        try {
+            for (let redirects = 0;; redirects += 1) {
+                await this.assertResolvedTarget(target);
+                let response;
+                try {
+                    response = await this.fetchImpl(target, { ...init, headers, redirect: 'manual', signal: controller.signal });
+                }
+                catch (error) {
+                    const state = init.method === 'POST' ? 'unknown' : 'not-started';
+                    throw new UhpError(controller.signal.aborted ? 'request_timeout' : 'network_error', redactUhpText(controller.signal.aborted ? 'UHP request timed out; remote task state is unknown' : `UHP network request failed: ${error.message}`, secret ? [secret] : []), { retryable: true, remoteState: state });
+                }
+                if (![301, 302, 303, 307, 308].includes(response.status))
+                    return { response, secret };
+                const location = response.headers.get('location');
+                if (!this.profile.trust?.allowRedirects || !location || redirects >= 3)
+                    throw new UhpError('redirect_blocked', 'UHP redirect was blocked by endpoint policy', { remoteState: init.method === 'POST' ? 'unknown' : 'not-started' });
+                const next = new URL(location, target);
+                validateUhpEndpoint(next.toString(), this.profile);
+                if (next.origin !== target.origin && authenticated)
+                    throw new UhpError('credential_redirect_blocked', 'Cross-origin UHP redirect was blocked before forwarding authentication', { remoteState: init.method === 'POST' ? 'unknown' : 'not-started' });
+                target = next;
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            externalSignal?.removeEventListener('abort', abort);
+        }
+    }
+    async json(relative, init = {}) {
+        const { response, secret } = await this.fetch(relative, init);
+        const version = response.headers.get('UHP-Version');
+        const bytes = await readBounded(response);
+        const payload = bytes.byteLength ? parseJson(bytes) : null;
+        if (version !== UHP_VERSION)
+            throw new UhpError('protocol_version_mismatch', `Expected UHP-Version ${UHP_VERSION}, received ${version ?? 'none'}`, { remoteState: init.method === 'POST' ? 'unknown' : 'not-started' });
+        if (!response.ok)
+            throw parseUhpError(response.status, payload, secret ? [secret] : []);
+        return payload;
+    }
+    async discover() {
+        return ensureDiscovery(await this.json('v1/uhp', { authenticated: false }));
+    }
+    async listHarnesses() {
+        const payload = await this.json('v1/harnesses');
+        if (!Array.isArray(payload.harnesses))
+            throw new UhpError('invalid_response', 'UHP harness list is malformed');
+        return payload.harnesses;
+    }
+    async listModels(harnessId) {
+        return this.json(harnessId ? `v1/harnesses/${encodeURIComponent(assertId('harness', harnessId))}/models` : 'v1/models');
+    }
+    async createResponse(request, options = {}) {
+        const normalized = { ...request, stream: false, metadata: { ...request.metadata, ...(request.metadata?.harness_id || !this.profile.defaultHarness ? {} : { harness_id: this.profile.defaultHarness }) }, ...(request.model || !this.profile.defaultModel ? {} : { model: this.profile.defaultModel }) };
+        if ((normalized.timeout_seconds ?? this.limits.maxTaskSeconds) > this.limits.maxTaskSeconds)
+            throw new UhpError('task_budget_exceeded', 'Requested UHP task duration exceeds the profile limit', { remoteState: 'not-started' });
+        const digest = canonicalUhpRequestDigest(normalized);
+        const key = options.idempotencyKey ?? `aiwg-${digest}`;
+        const prior = this.idempotency.get(key);
+        if (prior && prior !== digest)
+            throw new UhpError('idempotency_key_reused', 'Idempotency key cannot be reused for changed UHP task content', { remoteState: 'not-started' });
+        this.idempotency.set(key, digest);
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                const payload = await this.json('v1/responses', {
+                    method: 'POST', signal: options.signal,
+                    headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'Idempotency-Key': key },
+                    body: JSON.stringify(normalized),
+                    timeoutMs: Math.max(this.limits.requestTimeoutMs, ((normalized.timeout_seconds ?? 0) * 1_000) + 30_000),
+                });
+                return ensureResponse(payload);
+            }
+            catch (error) {
+                const uhpError = error instanceof UhpError ? error : undefined;
+                if (!uhpError?.options.retryable || uhpError.code === 'session_busy' || attempt >= this.limits.maxRetries)
+                    throw error;
+                await new Promise(resolve => setTimeout(resolve, Math.min(10 * 2 ** attempt, 250)));
+                options.signal?.throwIfAborted();
+            }
+        }
+    }
+    async *streamResponse(request, options = {}) {
+        const normalized = { ...request, stream: true, metadata: { ...request.metadata, ...(request.metadata?.harness_id || !this.profile.defaultHarness ? {} : { harness_id: this.profile.defaultHarness }) } };
+        const digest = canonicalUhpRequestDigest(normalized);
+        const key = options.idempotencyKey ?? `aiwg-${digest}`;
+        const prior = this.idempotency.get(key);
+        if (prior && prior !== digest)
+            throw new UhpError('idempotency_key_reused', 'Idempotency key cannot be reused for changed UHP task content', { remoteState: 'not-started' });
+        this.idempotency.set(key, digest);
+        const { response, secret } = await this.fetch('v1/responses', {
+            method: 'POST', signal: options.signal,
+            headers: { 'Content-Type': 'application/json', Accept: 'text/event-stream', 'Idempotency-Key': key }, body: JSON.stringify(normalized),
+            timeoutMs: Math.max(this.limits.requestTimeoutMs, ((normalized.timeout_seconds ?? 0) * 1_000) + 30_000),
+        });
+        if (response.headers.get('UHP-Version') !== UHP_VERSION)
+            throw new UhpError('protocol_version_mismatch', 'UHP stream response did not preserve the pinned version', { remoteState: 'unknown' });
+        if (!response.ok)
+            throw parseUhpError(response.status, parseJson(await readBounded(response)), secret ? [secret] : []);
+        if (!response.headers.get('content-type')?.toLowerCase().startsWith('text/event-stream') || !response.body)
+            throw new UhpError('invalid_stream', 'UHP streaming response must be text/event-stream', { remoteState: 'unknown' });
+        yield* parseUhpEventStream(response.body, { inactivityTimeoutMs: this.limits.inactivityTimeoutMs, secrets: secret ? [secret] : [], signal: options.signal });
+    }
+    async readResponse(responseId) {
+        return ensureResponse(await this.json(`v1/responses/${encodeURIComponent(assertId('response', responseId))}`));
+    }
+    /** Stored-response reads are authoritative after stream loss or local timeout. */
+    async reconcileUnknownResponse(responseId) {
+        return this.readResponse(responseId);
+    }
+    async continueResponse(previousResponseId, request, options = {}) {
+        const previous = await this.readResponse(previousResponseId);
+        const harness = previous.metadata.harness_id;
+        if (request.metadata?.harness_id && harness && request.metadata.harness_id !== harness)
+            throw new UhpError('harness_mismatch', 'Continuation harness does not match the existing UHP session', { remoteState: 'not-started' });
+        return this.createResponse({ ...request, previous_response_id: previousResponseId, metadata: { ...request.metadata, ...(harness ? { harness_id: harness } : {}) } }, options);
+    }
+    async cancelResponse(responseId, options = {}) {
+        const id = encodeURIComponent(assertId('response', responseId));
+        let response = ensureResponse(await this.json(`v1/responses/${id}/cancel`, { method: 'POST', signal: options.signal, headers: { 'Content-Type': 'application/json' }, body: '{}' }));
+        if (!options.wait)
+            return response;
+        for (let attempt = 0; attempt < 20 && !TERMINAL.has(response.status); attempt += 1) {
+            await new Promise(resolve => setTimeout(resolve, Math.min(250 * 2 ** attempt, 2_000)));
+            options.signal?.throwIfAborted();
+            response = await this.readResponse(responseId);
+        }
+        return response;
+    }
+    async listArtifacts(sessionId) {
+        const payload = await this.json(`v1/sessions/${encodeURIComponent(assertId('session', sessionId))}/files`);
+        if (!Array.isArray(payload.files))
+            throw new UhpError('invalid_response', 'UHP artifact list is malformed');
+        if (payload.files.length > this.limits.maxArtifactCount)
+            throw new UhpError('artifact_count_exceeded', 'UHP artifact count exceeds the profile limit');
+        return payload.files;
+    }
+    async downloadArtifact(containerId, fileId, destinationDirectory, filename) {
+        assertId('container', containerId);
+        assertId('file', fileId);
+        await mkdir(destinationDirectory, { recursive: true, mode: 0o700 });
+        const directoryInfo = await lstat(destinationDirectory);
+        if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink())
+            throw new UhpError('unsafe_artifact_destination', 'Artifact destination must be a non-symlink directory');
+        const { response, secret } = await this.fetch(`v1/containers/${encodeURIComponent(containerId)}/files/${encodeURIComponent(fileId)}/content`, { method: 'GET' });
+        if (response.headers.get('UHP-Version') !== UHP_VERSION)
+            throw new UhpError('protocol_version_mismatch', 'Artifact response did not preserve the pinned UHP version');
+        if (!response.ok)
+            throw parseUhpError(response.status, parseJson(await readBounded(response)), secret ? [secret] : []);
+        if (response.headers.get('x-content-type-options')?.toLowerCase() !== 'nosniff')
+            throw new UhpError('artifact_missing_nosniff', 'Refusing UHP artifact without X-Content-Type-Options: nosniff');
+        const bytes = await readBounded(response, this.limits.maxArtifactBytes);
+        const target = path.resolve(destinationDirectory, safeFilename(filename ?? fileId));
+        const root = path.resolve(destinationDirectory) + path.sep;
+        if (!target.startsWith(root))
+            throw new UhpError('artifact_path_traversal', 'Artifact filename escaped the approved destination');
+        const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            // A hard-link publishes atomically and, unlike rename, never overwrites an
+            // existing approved artifact path.
+            await link(temporary, target);
+            await unlink(temporary);
+        }
+        catch (error) {
+            await unlink(temporary).catch(() => undefined);
+            throw error;
+        }
+        return { path: target, bytes: bytes.byteLength, contentType: response.headers.get('content-type') ?? 'application/octet-stream' };
+    }
+    async uploadFile(filename) {
+        const info = await stat(filename);
+        if (!info.isFile() || info.size > this.limits.maxUploadBytes)
+            throw new UhpError('file_too_large', 'UHP upload is not a regular file within the configured size limit', { remoteState: 'not-started' });
+        const data = await readFile(filename);
+        const form = new FormData();
+        form.append('file', new Blob([data]), safeFilename(path.basename(filename)));
+        return this.json('v1/files', { method: 'POST', body: form });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/uhp/config.js

@@ -0,0 +1,130 @@
+import { isIP } from 'node:net';
+import { UHP_VERSION } from './types.js';
+export const DEFAULT_UHP_LIMITS = {
+    requestTimeoutMs: 10 * 60_000,
+    inactivityTimeoutMs: 45_000,
+    maxTaskSeconds: 3_600,
+    maxUploadBytes: 50 * 1024 * 1024,
+    maxArtifactBytes: 100 * 1024 * 1024,
+    maxArtifactCount: 100,
+    maxRetries: 3,
+};
+const PROFILE_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const OBJECT_ID = /^(?:chrn_|resp_|hsess|cntr_|file_)[A-Za-z0-9_-]+$/;
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/;
+export function isUhpLoopback(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return host === 'localhost' || host === '::1' || host.startsWith('127.');
+}
+export function isUhpPrivateAddress(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (isUhpLoopback(host))
+        return true;
+    if (isIP(host) === 4) {
+        const [a, b] = host.split('.').map(Number);
+        return a === 10 || a === 0 || a === 127 || (a === 169 && b === 254)
+            || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+    }
+    return isIP(host) === 6 && (host === '::' || host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80:'));
+}
+export function validateUhpEndpoint(endpoint, profile) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error('UHP endpoint must be an absolute URL');
+    }
+    if (url.username || url.password)
+        throw new Error('UHP endpoint must not contain inline credentials');
+    if (url.hash)
+        throw new Error('UHP endpoint must not contain a fragment');
+    if (!['https:', 'http:'].includes(url.protocol))
+        throw new Error('UHP endpoint must use HTTPS');
+    if (url.protocol === 'http:' && !(isUhpLoopback(url.hostname) && profile.trust?.allowInsecureLoopback === true)) {
+        throw new Error('UHP endpoint requires TLS except explicitly allowed loopback development');
+    }
+    if (isUhpPrivateAddress(url.hostname)) {
+        const permitted = isUhpLoopback(url.hostname)
+            ? profile.trust?.allowInsecureLoopback === true
+            : profile.trust?.allowPrivateNetwork === true;
+        if (!permitted)
+            throw new Error('UHP endpoint targets a private network outside the profile trust policy');
+    }
+    if (profile.trust?.allowedHosts?.length
+        && !profile.trust.allowedHosts.some(host => host.toLowerCase() === url.hostname.toLowerCase())) {
+        throw new Error(`UHP endpoint host '${url.hostname}' is not allowed by profile trust policy`);
+    }
+    return url;
+}
+export function validateUhpConfig(config) {
+    if (config === undefined || config === null)
+        return [];
+    if (typeof config !== 'object' || Array.isArray(config))
+        return ['uhp: must be an object'];
+    const value = config;
+    const errors = [];
+    if (value.enabled !== undefined && typeof value.enabled !== 'boolean')
+        errors.push('uhp.enabled: must be boolean');
+    if (value.profiles === undefined)
+        return errors;
+    if (!value.profiles || typeof value.profiles !== 'object' || Array.isArray(value.profiles))
+        return [...errors, 'uhp.profiles: must be an object'];
+    for (const [name, raw] of Object.entries(value.profiles)) {
+        const where = `uhp.profiles.${name}`;
+        if (!PROFILE_NAME.test(name))
+            errors.push(`${where}: invalid profile name`);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(`${where}: must be an object`);
+            continue;
+        }
+        const profile = raw;
+        for (const forbidden of ['token', 'bearer', 'apiKey', 'authorization']) {
+            if (forbidden in profile)
+                errors.push(`${where}.${forbidden}: inline credentials are forbidden`);
+        }
+        if (typeof profile.endpoint !== 'string')
+            errors.push(`${where}.endpoint: required string`);
+        else {
+            try {
+                validateUhpEndpoint(profile.endpoint, profile);
+            }
+            catch (error) {
+                errors.push(`${where}.endpoint: ${error.message}`);
+            }
+        }
+        if (profile.version !== UHP_VERSION)
+            errors.push(`${where}.version: must be '${UHP_VERSION}'`);
+        if (profile.experimental !== true)
+            errors.push(`${where}.experimental: must be true`);
+        if (!profile.credential || profile.credential.source !== 'env' || !/^[A-Z_][A-Z0-9_]*$/.test(profile.credential.name ?? '')) {
+            errors.push(`${where}.credential: must be an env secret reference with an uppercase variable name`);
+        }
+        if (profile.defaultHarness !== undefined && !OBJECT_ID.test(profile.defaultHarness))
+            errors.push(`${where}.defaultHarness: malformed UHP harness id`);
+        if (profile.defaultModel !== undefined && !MODEL_ID.test(profile.defaultModel))
+            errors.push(`${where}.defaultModel: malformed model id`);
+        if (profile.limits) {
+            for (const [key, limit] of Object.entries(profile.limits)) {
+                if (!(key in DEFAULT_UHP_LIMITS) || !Number.isSafeInteger(limit) || Number(limit) <= 0)
+                    errors.push(`${where}.limits.${key}: must be a positive supported integer`);
+            }
+        }
+    }
+    return errors;
+}
+export function resolveUhpProfile(config, name) {
+    if (!config?.enabled)
+        throw new Error('Experimental UHP transport is not enabled');
+    const profile = config.profiles?.[name];
+    if (!profile)
+        throw new Error(`Unknown UHP endpoint profile '${name}'`);
+    const errors = validateUhpConfig({ enabled: true, profiles: { [name]: profile } });
+    if (errors.length)
+        throw new Error(errors.join('\n'));
+    return profile;
+}
+export function resolveUhpLimits(profile) {
+    return { ...DEFAULT_UHP_LIMITS, ...profile.limits };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/uhp/errors.js

@@ -0,0 +1,63 @@
+const SECRET_PATTERNS = [
+    /\bBearer\s+[A-Za-z0-9._~+/=-]+/gi,
+    /\b(?:token|authorization|api[-_ ]?key)\b\s*[:=]\s*[^\s,;]+/gi,
+];
+export function redactUhpText(value, secrets = []) {
+    let redacted = value;
+    for (const secret of secrets) {
+        if (secret)
+            redacted = redacted.split(secret).join('[REDACTED]');
+    }
+    for (const pattern of SECRET_PATTERNS)
+        redacted = redacted.replace(pattern, '[REDACTED]');
+    return redacted.slice(0, 2_000);
+}
+function redactUhpValue(value, secrets, key) {
+    if (key && /^(?:authorization|token|api[-_]?key|secret)$/i.test(key))
+        return '[REDACTED]';
+    if (typeof value === 'string')
+        return redactUhpText(value, secrets);
+    if (Array.isArray(value))
+        return value.map(item => redactUhpValue(item, secrets));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .map(([childKey, child]) => [childKey, redactUhpValue(child, secrets, childKey)]));
+    }
+    return value;
+}
+export class UhpError extends Error {
+    code;
+    options;
+    name = 'UhpError';
+    constructor(code, message, options = {}) {
+        super(redactUhpText(message));
+        this.code = code;
+        this.options = options;
+    }
+}
+export function isRetryableUhpError(code, status) {
+    if (code === 'rate_limited' || code === 'session_busy' || code === 'harness_unavailable')
+        return true;
+    if (code === 'quota_exhausted')
+        return false;
+    return status !== undefined && [500, 502, 503, 504].includes(status);
+}
+export function parseUhpError(status, payload, secrets = []) {
+    const candidate = payload && typeof payload === 'object'
+        ? payload.error
+        : undefined;
+    const code = typeof candidate?.code === 'string' ? candidate.code : `http_${status}`;
+    const message = typeof candidate?.message === 'string' ? candidate.message : `UHP request failed with HTTP ${status}`;
+    const detail = candidate?.detail && typeof candidate.detail === 'object'
+        ? redactUhpValue(candidate.detail, secrets)
+        : null;
+    return new UhpError(code, redactUhpText(message, secrets), {
+        status,
+        type: typeof candidate?.type === 'string' ? candidate.type : undefined,
+        param: typeof candidate?.param === 'string' ? candidate.param : null,
+        detail,
+        retryable: isRetryableUhpError(code, status),
+        remoteState: status >= 500 ? 'unknown' : 'not-started',
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/uhp/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './config.js';
+export * from './sse.js';
+export * from './mission.js';
+export * from './client.js';
+//# sourceMappingURL=index.js.map