@playcraft/cli 0.1.69 → 0.1.71

package/dist/project-skills/remote-activation.js

@@ -0,0 +1,500 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { canonicalProjectSkillsJson, createCanonicalBundleArchive, declarationDigest, dependencyDigest, effectiveProjectSkills, extractBundleArchive, parseRemoteSkillSelectionResult, projectSkillsDigest, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { ensureProjectSkillDirectory, readLockedProjectSkillCatalog, readLockedProjectSkillFiles, } from './discovery.js';
+import { writeSharedFile } from '../workspace-runtime/workspaces/shared-write.js';
+const LIMIT = 16 * 1024 * 1024;
+const PROCESS_STARTED_AT = Math.round(Date.now() - process.uptime() * 1000);
+const inside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
+const paths = (root) => ({ declaration: join(root, '.playcraft/skills.json'), lock: join(root, '.playcraft/skills.lock.json') });
+const serialized = (snapshot) => ({ declaration: `${canonicalProjectSkillsJson(snapshot.declaration)}\n`, lock: `${canonicalProjectSkillsJson(snapshot.lock)}\n` });
+const code = (value) => { throw new Error(value); };
+async function safeBytes(path, maximum = LIMIT) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > maximum)
+            code('skill_activation_invalid_file');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function currentBytes(root) {
+    await ensureProjectSkillDirectory(root, '.playcraft', true);
+    const target = paths(root);
+    return { declaration: (await safeBytes(target.declaration, 1024 * 1024)).toString('utf8'),
+        lock: (await safeBytes(target.lock, 1024 * 1024)).toString('utf8') };
+}
+async function privateDirectory(path, root) {
+    const canonicalParent = async (value) => {
+        try {
+            return await realpath(value);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT' || dirname(value) === value)
+                throw error;
+            return join(await canonicalParent(dirname(value)), basename(value));
+        }
+    };
+    const supplied = resolve(path), target = join(await canonicalParent(dirname(supplied)), basename(supplied));
+    if (inside(root, target))
+        code('skill_activation_state_not_private');
+    let current = dirname(target);
+    while (true) {
+        const stat = await lstat(current).catch((error) => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+            code('skill_activation_invalid_state');
+        if (dirname(current) === current)
+            break;
+        current = dirname(current);
+    }
+    await mkdir(target, { recursive: true, mode: 0o700 });
+    const stat = await lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0)
+        code('skill_activation_state_not_private');
+    return realpath(target);
+}
+async function writeTransaction(path, transaction) {
+    const bytes = canonicalProjectSkillsJson(transaction);
+    if (Buffer.byteLength(bytes) > LIMIT)
+        code('skill_activation_state_limit');
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function selectionIdentity(selection) {
+    return projectSkillsDigest({ declaration: selection.declaration, lock: selection.lock,
+        skills: selection.skills.map(({ skillRef, skillVersionId, version, artifactHash }) => ({ skillRef, skillVersionId, version, artifactHash })).sort((a, b) => a.skillRef.localeCompare(b.skillRef)) });
+}
+function storedTransaction(value, root, transactionId) {
+    const record = value;
+    if (!record || record.version !== 1 || record.transactionId !== transactionId || record.root !== root
+        || [record.selectionId, record.selectionHash, record.expectedLockHash, record.expectedDeclarationHash]
+            .some(hash => typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))
+        || !['prepared', 'applied'].includes(record.status) || typeof record.before?.declaration !== 'string'
+        || typeof record.before?.lock !== 'string' || !Array.isArray(record.selectedKeys))
+        code('skill_activation_transaction_conflict');
+    const before = validateProjectSkillsSnapshot(record.before.declaration, record.before.lock);
+    if (projectSkillsDigest(before.lock) !== record.expectedLockHash || before.lock.declarationHash !== record.expectedDeclarationHash)
+        code('skill_activation_transaction_conflict');
+    record.after = validateProjectSkillsSnapshot(record.after?.declaration, record.after?.lock);
+    if (!record.selectedKeys.length || new Set(record.selectedKeys).size !== record.selectedKeys.length
+        || record.selectedKeys.some(key => !record.after.lock.entries.some(entry => entry.entryKey === key)))
+        code('skill_activation_transaction_conflict');
+    return record;
+}
+function validateTransaction(value, root, selection, options) {
+    const record = storedTransaction(value, root, options.transactionId);
+    if (record.selectionId !== selection.selectionId || record.selectionHash !== selectionIdentity(selection)
+        || record.expectedLockHash !== options.expectedLockHash || record.expectedDeclarationHash !== options.expectedDeclarationHash
+        || record.selectedKeys.length !== selection.lock.entries.length)
+        code('skill_activation_transaction_conflict');
+    return record;
+}
+async function readSelection(root, selection) {
+    const relativePath = `.playcraft/skill-selections/${selection.selectionId}`;
+    const directory = join(root, relativePath);
+    let current = root;
+    for (const segment of relativePath.split('/')) {
+        current = join(current, segment);
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            code('skill_activation_invalid_selection');
+    }
+    const saved = parseRemoteSkillSelectionResult(JSON.parse((await safeBytes(join(directory, 'selection.json'))).toString('utf8')));
+    if (selectionIdentity(saved) !== selectionIdentity(selection))
+        code('skill_activation_selection_conflict');
+    const catalog = await readLockedProjectSkillCatalog(directory, join(directory, '.playcraft/skill-artifacts'));
+    if (catalog.lockHash !== selection.lockHash || catalog.skills.length !== selection.lock.entries.length)
+        code('skill_activation_selection_conflict');
+    const archives = new Map();
+    for (const entry of selection.lock.entries) {
+        const names = [`${entry.revision.artifactHash}.tar.gz`, ...(entry.revision.contentHash ? [`content-${entry.revision.contentHash}.tar.gz`] : [])];
+        let archive;
+        for (const name of names) {
+            try {
+                archive = await safeBytes(join(directory, '.playcraft/skill-artifacts', name), 80 * 1024 * 1024);
+                break;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (!archive || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+            code('skill_activation_artifact_mismatch');
+        archives.set(entry.entryKey, archive);
+    }
+    return archives;
+}
+function contentHash(archive) {
+    const extracted = extractBundleArchive(archive);
+    if (extracted.issues.length)
+        code('skill_activation_artifact_mismatch');
+    return sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data })));
+}
+function merge(before, selection, archives) {
+    const after = structuredClone(before);
+    const byRef = new Map(after.lock.entries.map(entry => [entry.revision.skillRef, entry]));
+    if (byRef.size !== after.lock.entries.length)
+        code('skill_activation_revision_conflict');
+    const keys = new Set(after.lock.entries.map(entry => entry.entryKey));
+    const mapping = new Map();
+    for (const selected of selection.lock.entries) {
+        const existing = byRef.get(selected.revision.skillRef);
+        if (existing) {
+            if (existing.revision.kind !== 'release' || selected.revision.kind !== 'release'
+                || existing.revision.version !== selected.revision.version || existing.revision.artifactHash !== selected.revision.artifactHash
+                || before.lock.lockVersion === 4 && existing.revision.contentHash !== contentHash(archives.get(selected.entryKey)))
+                code('skill_activation_revision_conflict');
+            const declaration = after.declaration.entries.find(entry => entry.entryKey === existing.entryKey);
+            if (declaration.surface !== 'sandbox-agent')
+                code('skill_activation_surface_conflict');
+            declaration.enabled = true;
+            mapping.set(selected.entryKey, existing.entryKey);
+        }
+        else {
+            let key = selected.entryKey;
+            if (keys.has(key))
+                key = `remote-${createHash('sha256').update(selected.revision.skillRef).digest('hex').slice(0, 32)}`;
+            if (keys.has(key))
+                code('skill_activation_entry_conflict');
+            keys.add(key);
+            mapping.set(selected.entryKey, key);
+            const revision = structuredClone(selected.revision);
+            if (after.lock.lockVersion === 4)
+                after.lock.entries.push({ ...structuredClone(selected), entryKey: key,
+                    revision: { ...revision, contentHash: contentHash(archives.get(selected.entryKey)) } });
+            else {
+                delete revision.contentHash;
+                after.lock.entries.push({ ...structuredClone(selected), entryKey: key, revision });
+            }
+            if (revision.kind !== 'release')
+                code('skill_activation_revision_conflict');
+            after.declaration.entries.push({ entryKey: key, source: { kind: 'registry', skillRef: revision.skillRef,
+                    version: 'version' in revision ? revision.version : code('skill_activation_revision_conflict') }, enabled: true, surface: 'sandbox-agent' });
+        }
+    }
+    for (const selected of selection.lock.entries) {
+        const locked = after.lock.entries.find(entry => entry.entryKey === mapping.get(selected.entryKey));
+        const mapped = selected.dependencies.map(key => mapping.get(key));
+        // Existing exact entries retain prior hard requirements as well as the newly verified closure.
+        const previous = before.lock.entries.find(entry => entry.entryKey === locked.entryKey);
+        locked.dependencies = [...new Set([...(previous?.dependencies ?? []), ...mapped])].sort();
+    }
+    for (const entry of after.lock.entries)
+        entry.dependencyLockHash = dependencyDigest(after.lock.entries, entry.dependencies);
+    after.lock.declarationHash = declarationDigest(after.declaration);
+    return { after: validateProjectSkillsSnapshot(after.declaration, after.lock), selectedKeys: [...mapping.values()], mapping };
+}
+async function stageGeneration(root, transactionPath, transaction, selection, selectedArchives) {
+    const before = validateProjectSkillsSnapshot(transaction.before.declaration, transaction.before.lock);
+    const stage = `${transactionPath}.generation`;
+    await mkdir(stage, { recursive: true, mode: 0o700 });
+    if ((await lstat(stage)).isSymbolicLink())
+        code('skill_activation_invalid_state');
+    const cache = await ensureProjectSkillDirectory(stage, '.playcraft/skill-artifacts');
+    for (const [name, value] of [['skills.json', transaction.after.declaration], ['skills.lock.json', transaction.after.lock]])
+        await writeSharedFile(stage, join(stage, '.playcraft', name), `${canonicalProjectSkillsJson(value)}\n`);
+    const selectedByRef = new Map(selection.lock.entries.map(entry => [entry.revision.skillRef, entry]));
+    const mainCache = await ensureProjectSkillDirectory(root, '.playcraft/skill-artifacts');
+    for (const entry of effectiveProjectSkills(transaction.after.declaration, transaction.after.lock, 'sandbox-agent')) {
+        const selected = selectedByRef.get(entry.revision.skillRef);
+        let archive;
+        if (selected)
+            archive = selectedArchives.get(selected.entryKey);
+        else {
+            const original = before.lock.entries.find(item => item.entryKey === entry.entryKey);
+            const files = await readLockedProjectSkillFiles(root, mainCache, original, before, undefined, true);
+            try {
+                archive = await safeBytes(join(mainCache, `${entry.revision.artifactHash}.tar.gz`), 80 * 1024 * 1024);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                archive = createCanonicalBundleArchive(files);
+            }
+        }
+        const exact = createHash('sha256').update(archive).digest('hex') === entry.revision.artifactHash;
+        if (!exact && (!entry.revision.contentHash || contentHash(archive) !== entry.revision.contentHash))
+            code('skill_activation_artifact_mismatch');
+        const name = exact ? `${entry.revision.artifactHash}.tar.gz` : `content-${entry.revision.contentHash}.tar.gz`;
+        await writeSharedFile(stage, join(cache, name), archive);
+        if (selected)
+            await writeSharedFile(root, join(mainCache, name), archive);
+    }
+    const catalog = await readLockedProjectSkillCatalog(stage, cache);
+    const lockHash = projectSkillsDigest(transaction.after.lock);
+    if (catalog.lockHash !== lockHash)
+        code('skill_activation_generation_conflict');
+    const destination = await ensureProjectSkillDirectory(root, '.playcraft/skills');
+    const generation = join(destination, lockHash), frozen = join(stage, '.playcraft/skills', lockHash);
+    const check = async (source, target, relativePath = '') => {
+        await ensureProjectSkillDirectory(root, `.playcraft/skills/${lockHash}${relativePath ? `/${relativePath}` : ''}`);
+        const expected = await readdir(source, { withFileTypes: true });
+        for (const file of expected) {
+            const next = relativePath ? `${relativePath}/${file.name}` : file.name;
+            if (file.isDirectory())
+                await check(join(source, file.name), join(target, file.name), next);
+            else {
+                if (!file.isFile())
+                    code('skill_activation_generation_conflict');
+                const bytes = await safeBytes(join(source, file.name)), path = join(target, file.name);
+                await writeFile(path, bytes, { flag: 'wx', mode: 0o444 }).catch((error) => { if (error.code !== 'EEXIST')
+                    throw error; });
+                const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const stat = await handle.stat();
+                    if (!stat.isFile() || stat.nlink !== 1 || !bytes.equals(await handle.readFile()))
+                        code('skill_activation_generation_conflict');
+                    if ((stat.mode & 0o777) !== 0o444)
+                        await handle.chmod(0o444);
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+        }
+        const actual = await readdir(target, { withFileTypes: true });
+        if (expected.length !== actual.length || expected.some(file => !actual.some(item => item.name === file.name)))
+            code('skill_activation_generation_conflict');
+    };
+    await check(frozen, generation);
+}
+function ownsBytes(current, transaction) {
+    const after = serialized(transaction.after);
+    return (current.declaration === transaction.before.declaration || current.declaration === after.declaration)
+        && (current.lock === transaction.before.lock || current.lock === after.lock);
+}
+async function takeWriter(path, transactionId, assertCurrent) {
+    const create = async () => {
+        const handle = await open(path, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify({ version: 1, transactionId, pid: process.pid, startedAt: PROCESS_STARTED_AT }));
+        }
+        catch (error) {
+            await handle.close();
+            await rm(path, { force: true });
+            throw error;
+        }
+        return handle;
+    };
+    try {
+        return await create();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        let bytes, lease;
+        try {
+            bytes = await safeBytes(path, 1024);
+            lease = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            return code('skill_activation_busy');
+        }
+        if (lease.version !== 1 || lease.transactionId !== transactionId || !Number.isInteger(lease.pid) || !lease.startedAt)
+            code('skill_activation_busy');
+        let live = true;
+        if (lease.pid === process.pid)
+            live = lease.startedAt === PROCESS_STARTED_AT;
+        else
+            try {
+                process.kill(lease.pid, 0);
+            }
+            catch (failure) {
+                live = failure.code !== 'ESRCH';
+            }
+        if (live)
+            code('skill_activation_busy');
+        await assertCurrent?.();
+        if (!(await safeBytes(path, 1024)).equals(bytes))
+            code('skill_activation_busy');
+        await rm(path);
+        return create();
+    }
+}
+/** Startup repairs only owned partial writes; it never activates a selection or starts a native request. */
+export async function recoverPreparedSkillActivationTransactions(directory, options) {
+    if (!await lstat(options.transactionDirectory).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }) && !options.orphanTransactionIds?.length)
+        return [];
+    const root = await realpath(directory), privateRoot = await privateDirectory(options.transactionDirectory, root);
+    const files = (await readdir(privateRoot)).filter(name => /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,159}\.json$/.test(name)).sort();
+    if (files.length > 1024)
+        code('skill_activation_state_limit');
+    const results = [];
+    for (const file of files) {
+        const transactionPath = join(privateRoot, file), value = JSON.parse((await safeBytes(transactionPath)).toString('utf8'));
+        if (value.root !== root)
+            continue;
+        const transaction = storedTransaction(value, root, file.slice(0, -5)), after = serialized(transaction.after);
+        let current = await currentBytes(root);
+        let status;
+        const beforePair = () => current.declaration === transaction.before.declaration && current.lock === transaction.before.lock;
+        const afterPair = () => current.declaration === after.declaration && current.lock === after.lock;
+        if (!ownsBytes(current, transaction)) {
+            // A newer transaction may own this partial pair. Defer validation until every owner was considered.
+            status = 'preserved';
+        }
+        else {
+            status = afterPair() ? 'retained' : beforePair() ? 'unchanged' : 'rolled_back';
+            const writerPath = join(root, '.playcraft/skills-write.lock');
+            const lease = await safeBytes(writerPath, 1024).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            });
+            const ownsLease = lease && JSON.parse(lease.toString('utf8')).transactionId === transaction.transactionId;
+            // Retired transactions may share a root with a newer writer; only its own lease may be reclaimed.
+            if (status === 'rolled_back' || ownsLease) {
+                const writer = await takeWriter(writerPath, transaction.transactionId);
+                try {
+                    current = await currentBytes(root);
+                    if (!ownsBytes(current, transaction))
+                        status = 'conflict';
+                    else if (current.declaration === after.declaration && current.lock === after.lock)
+                        status = 'retained';
+                    else if (current.declaration === transaction.before.declaration && current.lock === transaction.before.lock)
+                        status = 'unchanged';
+                    else
+                        for (const key of ['declaration', 'lock']) {
+                            current = await currentBytes(root);
+                            if (!ownsBytes(current, transaction)) {
+                                status = 'conflict';
+                                break;
+                            }
+                            if (current[key] !== transaction.before[key])
+                                await writeSharedFile(root, paths(root)[key], transaction.before[key]);
+                        }
+                }
+                finally {
+                    await writer.close();
+                    await rm(writerPath, { force: true });
+                }
+            }
+        }
+        transaction.recovery = { status, occurredAt: new Date().toISOString() };
+        await writeTransaction(transactionPath, transaction);
+        results.push({ transactionId: transaction.transactionId, status });
+    }
+    // An unowned partial pair requires explicit repair; never pass it to native preparation.
+    if (results.length || options.orphanTransactionIds?.length) {
+        const final = await currentBytes(root);
+        try {
+            validateProjectSkillsSnapshot(final.declaration, final.lock);
+        }
+        catch {
+            code('skill_activation_recovery_required');
+        }
+    }
+    const writerPath = join(root, '.playcraft/skills-write.lock');
+    const remainingLease = await safeBytes(writerPath, 1024).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (remainingLease && options.orphanTransactionIds) {
+        const lease = JSON.parse(remainingLease.toString('utf8'));
+        // Only the managed caller can prove an orphan belongs to an unsent request for this exact root and binding.
+        if (!lease.transactionId || !options.orphanTransactionIds.includes(lease.transactionId)
+            || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,159}$/.test(lease.transactionId))
+            code('skill_activation_busy');
+        const writer = await takeWriter(writerPath, lease.transactionId);
+        try {
+            results.push({ transactionId: lease.transactionId, status: 'unchanged' });
+        }
+        finally {
+            await writer.close();
+            await rm(writerPath, { force: true });
+        }
+    }
+    return results;
+}
+/** Called only by an idle managed activation queue while it owns the directory and execution fence. */
+export async function activatePreparedSkillSelection(directory, input, options) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,159}$/.test(options.transactionId)
+        || !/^[a-f0-9]{64}$/.test(options.expectedLockHash) || !/^[a-f0-9]{64}$/.test(options.expectedDeclarationHash))
+        code('skill_activation_invalid_request');
+    const supplied = resolve(directory), stat = await lstat(supplied);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        code('skill_activation_invalid_root');
+    const root = await realpath(supplied), selection = parseRemoteSkillSelectionResult(input);
+    const privateRoot = await privateDirectory(options.transactionDirectory, root);
+    const transactionPath = join(privateRoot, `${options.transactionId}.json`);
+    const selectedArchives = await readSelection(root, selection);
+    const writerPath = join(root, '.playcraft/skills-write.lock');
+    const writer = await takeWriter(writerPath, options.transactionId, options.assertCurrent);
+    try {
+        let transaction;
+        try {
+            transaction = validateTransaction(JSON.parse((await safeBytes(transactionPath)).toString('utf8')), root, selection, options);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const before = await currentBytes(root), snapshot = validateProjectSkillsSnapshot(before.declaration, before.lock);
+            if (projectSkillsDigest(snapshot.lock) !== options.expectedLockHash || snapshot.lock.declarationHash !== options.expectedDeclarationHash)
+                code('skill_activation_revision_conflict');
+            const merged = merge(snapshot, selection, selectedArchives);
+            transaction = { version: 1, transactionId: options.transactionId, root, selectionId: selection.selectionId,
+                selectionHash: selectionIdentity(selection), expectedLockHash: options.expectedLockHash, expectedDeclarationHash: options.expectedDeclarationHash,
+                before, after: merged.after, selectedKeys: merged.selectedKeys, status: 'prepared' };
+            await writeTransaction(transactionPath, transaction);
+        }
+        if (!ownsBytes(await currentBytes(root), transaction))
+            code('skill_activation_revision_conflict');
+        await options.assertCurrent?.();
+        await stageGeneration(root, transactionPath, transaction, selection, selectedArchives);
+        const after = serialized(transaction.after), target = paths(root);
+        try {
+            for (const key of ['declaration', 'lock']) {
+                await options.assertCurrent?.();
+                const current = await currentBytes(root);
+                if (!ownsBytes(current, transaction))
+                    code('skill_activation_revision_conflict');
+                if (current[key] !== after[key])
+                    await writeSharedFile(root, target[key], after[key]);
+            }
+            const catalog = await readLockedProjectSkillCatalog(root, join(root, '.playcraft/skill-artifacts'));
+            if (catalog.lockHash !== projectSkillsDigest(transaction.after.lock))
+                code('skill_activation_generation_conflict');
+        }
+        catch (error) {
+            // Ordinary failures restore the original pair only while every observed byte still belongs to this transaction.
+            const current = await currentBytes(root).catch(() => undefined);
+            if (current && ownsBytes(current, transaction)) {
+                for (const key of ['declaration', 'lock']) {
+                    const observed = await currentBytes(root);
+                    if (!ownsBytes(observed, transaction))
+                        break;
+                    if (observed[key] !== transaction.before[key])
+                        await writeSharedFile(root, target[key], transaction.before[key]);
+                }
+            }
+            throw error;
+        }
+        transaction.status = 'applied';
+        await writeTransaction(transactionPath, transaction);
+        const lockHash = projectSkillsDigest(transaction.after.lock);
+        return { lockHash, declarationHash: transaction.after.lock.declarationHash,
+            entries: transaction.selectedKeys.map(entryKey => ({ entryKey, lockHash })) };
+    }
+    finally {
+        await writer.close();
+        await rm(writerPath, { force: true });
+    }
+}

package/dist/project-skills/remote-client.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import { remoteSkillMatchRequestSchema, remoteSkillMatchResultSchema, remoteSkillSelectionRequestSchema, parseRemoteSkillSelectionResult, projectSkillsDigest, remoteSkillActivationRequestSchema, } from '@playcraft/common/project-skills';
+import { skillActivationRegistrationSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveRegistryCredentials } from '../skill-registry/client.js';
+import { businessEndpoint } from '../utils/environment-endpoints.js';
+import { projectSkillsMessage as t } from './messages.js';
+const MAX_ARTIFACT_BYTES = 80 * 1024 * 1024;
+export class RemoteSkillError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+async function readJson(response, maximum) {
+    if (!response.body)
+        throw new RemoteSkillError('remote_skills_unavailable', t('remoteUnavailable'));
+    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)
+                throw new RemoteSkillError('remote_skills_response_too_large', t('remoteTooLarge'));
+            chunks.push(chunk.value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+/** Prefer the current native turn's delegated loopback capability; never expose controller credentials. */
+export class RemoteSkillClient {
+    options;
+    transport;
+    env;
+    constructor(options = {}) {
+        this.options = options;
+        this.transport = options.fetch ?? fetch;
+        this.env = options.env ?? process.env;
+    }
+    bridge() {
+        const endpoint = this.env.PLAYCRAFT_SKILLS_ENDPOINT, token = this.env.PLAYCRAFT_SKILLS_CAPABILITY;
+        if (!endpoint && !token)
+            return undefined;
+        if (!endpoint || endpoint.length > 2048 || !token || !/^[A-Za-z0-9_-]{16,128}$/.test(token))
+            throw new RemoteSkillError('remote_skills_bridge_invalid', t('remoteBridgeInvalid'));
+        let url;
+        try {
+            url = new URL(endpoint);
+        }
+        catch {
+            throw new RemoteSkillError('remote_skills_bridge_invalid', t('remoteBridgeInvalid'));
+        }
+        if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.search || url.hash
+            || !/^\/[A-Za-z0-9_-]+\/[a-f0-9]{32}\/skill-discovery$/.test(url.pathname))
+            throw new RemoteSkillError('remote_skills_bridge_invalid', t('remoteBridgeInvalid'));
+        return { endpoint: url, token };
+    }
+    hasExecutionBridge() { return this.bridge() !== undefined; }
+    async request(action, input) {
+        const bridge = this.bridge();
+        // A failed bridge is never replaced with a broader local login or a different environment.
+        const credentials = bridge ? undefined : resolveRegistryCredentials(this.options);
+        const endpoint = bridge ? new URL(`${bridge.endpoint.href}/${action}`)
+            : businessEndpoint(credentials.url, `/api/project-skills/discovery/${action}`);
+        const response = await this.transport(endpoint, { method: 'POST', redirect: 'error',
+            signal: AbortSignal.timeout(action === 'artifact' ? 60_000 : 30_000),
+            headers: { authorization: `Bearer ${bridge?.token ?? credentials.token}`, 'content-type': 'application/json' },
+            body: JSON.stringify(bridge ? { cwd: this.options.cwd ?? process.cwd(), input } : input) });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new RemoteSkillError(response.status === 401 || response.status === 403 ? 'remote_skills_access_denied' : 'remote_skills_unavailable', response.status === 401 || response.status === 403 ? t('remoteAccessDenied') : t('remoteUnavailable'));
+        }
+        return readJson(response, action === 'artifact' ? Math.ceil(MAX_ARTIFACT_BYTES / 3) * 4 + 4096 : 4 * 1024 * 1024);
+    }
+    async match(input) {
+        return remoteSkillMatchResultSchema.parse(await this.request('match', remoteSkillMatchRequestSchema.parse(input)));
+    }
+    async select(input) {
+        const request = remoteSkillSelectionRequestSchema.parse(input);
+        const result = parseRemoteSkillSelectionResult(await this.request('selection', request));
+        for (const selected of request.skills) {
+            if (!result.skills.some(skill => skill.skillRef === selected.skillRef && skill.skillVersionId === selected.skillVersionId
+                && skill.version === selected.version && skill.artifactHash === selected.artifactHash))
+                throw new RemoteSkillError('remote_skills_selection_changed', t('remoteSelectionChanged'));
+        }
+        return result;
+    }
+    /** Local preparation has no native session to continue; a present but invalid bridge remains fatal. */
+    async activate(selectionId) {
+        if (!this.bridge())
+            return undefined;
+        return skillActivationRegistrationSchema.parse(await this.request('activate', remoteSkillActivationRequestSchema.parse({ selectionId })));
+    }
+    async artifact(selection, entry) {
+        const expected = selection.lock.entries.find(item => item.entryKey === entry.entryKey);
+        if (!expected || projectSkillsDigest(expected.revision) !== projectSkillsDigest(entry.revision))
+            throw new RemoteSkillError('remote_skills_selection_changed', t('remoteSelectionChanged'));
+        const input = this.bridge() ? { selectionId: selection.selectionId, entryKey: entry.entryKey }
+            : { entryKey: entry.entryKey, revision: entry.revision };
+        const value = await this.request('artifact', input);
+        if (!value || typeof value.content !== 'string' || value.content.length > Math.ceil(MAX_ARTIFACT_BYTES / 3) * 4
+            || value.content.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(value.content) || value.artifactHash !== entry.revision.artifactHash)
+            throw new RemoteSkillError('remote_skills_digest_mismatch', t('remoteDigestMismatch'));
+        const archive = Buffer.from(value.content, 'base64');
+        if (archive.length > MAX_ARTIFACT_BYTES || archive.toString('base64') !== value.content
+            || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+            throw new RemoteSkillError('remote_skills_digest_mismatch', t('remoteDigestMismatch'));
+        return archive;
+    }
+}