openworkgraph 0.2.12 → 0.3.0

package/dist/builtin-skills.js

@@ -0,0 +1,514 @@
+import { isSkillName } from "./vendor/protocol/index.js";
+import { promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir, hostname } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { parseDocument } from 'yaml';
+import { ServiceError } from './errors.js';
+import { parseSkillConfig } from './skill-schema.js';
+import { DEFAULT_SKILL_SOURCE, GitHubSkillSource, SKILL_LIMITS, gitBlobSha, packageDigest, validatePackageFiles, safeSkillPath } from './skill-source.js';
+const key = (id) => createHash('sha256').update(id).digest('hex');
+const isMissing = (error) => error.code === 'ENOENT';
+class SkillDeadline {
+    expires;
+    constructor(duration) { this.expires = Date.now() + duration; }
+    check() { if (Date.now() >= this.expires)
+        throw new ServiceError('CONFLICT', '技能操作超过总时限，请稍后重试。', { retryable: true }); }
+    async wait(work) {
+        this.check();
+        let timer;
+        try {
+            const timeout = new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new ServiceError('CONFLICT', '技能操作超过总时限，请稍后重试。', { retryable: true })), Math.max(1, this.expires - Date.now())); });
+            const result = await Promise.race([work(), timeout]);
+            this.check();
+            return result;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}
+export function parseSkillFrontmatter(text) {
+    if (Buffer.byteLength(text) > SKILL_LIMITS.metadataBytes)
+        throw new ServiceError('INVALID_REQUEST', 'SKILL.md 超过大小限制。');
+    const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        throw new ServiceError('INVALID_REQUEST', 'SKILL.md 缺少 YAML frontmatter。');
+    try {
+        const document = parseDocument(match[1], { uniqueKeys: true });
+        if (document.errors.length)
+            throw Error('yaml');
+        const value = document.toJS({ maxAliasCount: 32 });
+        if (!value || !isSkillName(value.name) || typeof value.description !== 'string' || !value.description.trim() || value.description.length > 16_384)
+            throw Error('metadata');
+        return { name: value.name, description: value.description.trim() };
+    }
+    catch {
+        throw new ServiceError('INVALID_REQUEST', 'SKILL.md 的名称或 YAML 简介无效。');
+    }
+}
+/** Shared packages, workspace-independent installation pointers, immutable versions. */
+export class BuiltinSkills {
+    root;
+    source;
+    provider;
+    ready;
+    refreshing;
+    constructor(_directories, _serviceId, options = {}) {
+        this.root = resolve(options.root ?? join(homedir(), '.openworkgraph', 'skills'));
+        this.source = { ...(options.source ?? DEFAULT_SKILL_SOURCE) };
+        this.provider = options.provider ?? new GitHubSkillSource();
+    }
+    initialize() {
+        return this.ready ??= (async () => {
+            await fs.mkdir(this.root, { recursive: true, mode: 0o700 });
+            const stat = await fs.lstat(this.root);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new ServiceError('INVALID_REQUEST', '技能管理目录不能是链接。');
+            await fs.chmod(this.root, 0o700);
+            await this.directory('versions');
+            await this.directory('staging');
+        })();
+    }
+    async checked(relative) {
+        const parts = relative.split('/');
+        let path = this.root;
+        const rootStat = await fs.lstat(path);
+        if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+            throw new ServiceError('INVALID_REQUEST', '技能管理目录无效。');
+        for (const part of parts) {
+            if (!part || part === '.' || part === '..' || part.includes('\\') || part.includes('\0'))
+                throw new ServiceError('INVALID_REQUEST', '技能管理路径无效。');
+            path = join(path, part);
+            try {
+                if ((await fs.lstat(path)).isSymbolicLink())
+                    throw new ServiceError('INVALID_REQUEST', '技能管理路径不能是链接。');
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        return path;
+    }
+    async directory(relative) {
+        const path = await this.checked(relative);
+        await fs.mkdir(path, { recursive: true, mode: 0o700 });
+        if (!(await fs.lstat(path)).isDirectory())
+            throw new ServiceError('INVALID_REQUEST', '技能管理目录无效。');
+        await fs.chmod(path, 0o700);
+        return path;
+    }
+    async readJson(relative) {
+        try {
+            const path = await this.checked(relative);
+            if ((await fs.stat(path)).size > 16 * 1024 * 1024)
+                throw new ServiceError('INVALID_REQUEST', '技能管理记录过大。');
+            return JSON.parse(await fs.readFile(path, 'utf8'));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return undefined;
+            throw error;
+        }
+    }
+    async atomicJson(relative, value) {
+        const target = await this.checked(relative);
+        const temp = target + '.' + randomUUID() + '.tmp';
+        try {
+            const file = await fs.open(temp, 'wx', 0o600);
+            try {
+                await file.writeFile(JSON.stringify(value));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await fs.rename(temp, target);
+            if (process.platform !== 'win32') {
+                const parent = await fs.open(dirname(target), 'r');
+                try {
+                    await parent.sync();
+                }
+                finally {
+                    await parent.close();
+                }
+            }
+        }
+        finally {
+            await fs.rm(temp, { force: true });
+        }
+    }
+    async state() {
+        const value = await this.readJson('installed.json');
+        if (!value)
+            return { version: 1, items: {} };
+        if (value.version !== 1 || !value.items || typeof value.items !== 'object' || Array.isArray(value.items))
+            throw new ServiceError('INVALID_REQUEST', '技能安装记录损坏。');
+        for (const [id, item] of Object.entries(value.items))
+            if (item.skillId !== id || !Number.isSafeInteger(item.revision) || item.revision < 0 || (item.packageVersion && !/^[a-f0-9]{64}$/.test(item.packageVersion)))
+                throw new ServiceError('INVALID_REQUEST', '技能安装记录损坏。');
+        return value;
+    }
+    async claimLock(relative) {
+        const target = await this.checked(relative);
+        const parent = relative.includes('/') ? relative.slice(0, relative.lastIndexOf('/')) + '/' : '';
+        const prepared = parent + '.owner-' + randomUUID();
+        await this.directory(prepared);
+        try {
+            const owner = { pid: process.pid, hostname: hostname(), token: randomUUID() };
+            await this.atomicJson(prepared + '/owner.json', owner);
+            try {
+                await fs.lstat(target);
+                return false;
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+            try {
+                await fs.rename(await this.checked(prepared), target);
+                return true;
+            }
+            catch (error) {
+                if (['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error.code ?? '')) {
+                    try {
+                        if ((await fs.lstat(target)).isDirectory())
+                            return false;
+                    }
+                    catch (error) {
+                        if (isMissing(error))
+                            return false;
+                        throw error;
+                    }
+                }
+                throw error;
+            }
+        }
+        finally {
+            await fs.rm(await this.checked(prepared), { recursive: true, force: true });
+        }
+    }
+    async lockOwner(relative) {
+        const owner = await this.readJson(relative + '/owner.json');
+        if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.token !== 'string' || typeof owner.hostname !== 'string')
+            return undefined;
+        return owner;
+    }
+    deadOwner(owner) {
+        if (owner.hostname !== hostname())
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === 'ESRCH';
+        }
+    }
+    async recoverLock(relative, depth = 0) {
+        const owner = await this.lockOwner(relative);
+        if (!owner || !this.deadOwner(owner) || depth > 4)
+            return false;
+        const recovery = relative + '/.recovery';
+        try {
+            if (!await this.claimLock(recovery)) {
+                await this.recoverLock(recovery, depth + 1);
+                return false;
+            }
+        }
+        catch (error) {
+            if (isMissing(error))
+                return false;
+            throw error;
+        }
+        let moved = false;
+        try {
+            const current = await this.lockOwner(relative);
+            if (!current || current.token !== owner.token || !this.deadOwner(current))
+                return false;
+            const retired = relative + '.retired-' + randomUUID();
+            await fs.rename(await this.checked(relative), await this.checked(retired));
+            moved = true;
+            await fs.rm(await this.checked(retired), { recursive: true, force: true });
+            return true;
+        }
+        finally {
+            if (!moved)
+                await fs.rm(await this.checked(recovery), { recursive: true, force: true });
+        }
+    }
+    async lock(work) {
+        await this.initialize();
+        const started = Date.now();
+        for (;;) {
+            if (await this.claimLock('installation.lock'))
+                break;
+            if (await this.recoverLock('installation.lock'))
+                continue;
+            if (Date.now() - started > 30_000)
+                throw new ServiceError('CONFLICT', '技能操作正在其他工作空间进行，或无法确认锁进程已退出，请稍后重试。', { retryable: true });
+            await delay(50);
+        }
+        try {
+            // Only the lock holder may clean interrupted downloads. Published versions are retained.
+            for (const entry of await fs.readdir(await this.checked('staging')))
+                if (/^install-[a-f0-9-]+$/.test(entry))
+                    await fs.rm(await this.checked('staging/' + entry), { recursive: true, force: true });
+            return await work();
+        }
+        finally {
+            const retired = 'installation.lock.retired-' + randomUUID();
+            await fs.rename(await this.checked('installation.lock'), await this.checked(retired));
+            await fs.rm(await this.checked(retired), { recursive: true, force: true });
+        }
+    }
+    async download(pkg, commitSha, file, deadline) {
+        const read = () => this.provider.read(this.source, commitSha, this.source.directory + '/' + pkg.directory + '/' + file.path);
+        const bytes = Buffer.from(await (deadline ? deadline.wait(read) : read()));
+        if (bytes.length !== file.size || bytes.length > SKILL_LIMITS.fileBytes || gitBlobSha(bytes) !== file.sha)
+            throw new ServiceError('INVALID_REQUEST', '技能文件大小或内容摘要校验失败。');
+        return bytes;
+    }
+    async metadata(pkg, commitSha, deadline) {
+        validatePackageFiles(pkg);
+        const read = async (name) => {
+            const file = pkg.files.find(file => file.path === name);
+            if (file.size > SKILL_LIMITS.metadataBytes)
+                throw new ServiceError('INVALID_REQUEST', '技能说明或配置超过大小限制。');
+            return (await this.download(pkg, commitSha, file, deadline)).toString('utf8');
+        };
+        const [skill, config, readme] = await Promise.all([read('SKILL.md'), read('config.json'), read('README.md')]);
+        if (!readme.trim())
+            throw new ServiceError('INVALID_REQUEST', '技能包 README.md 不能为空。');
+        return { ...parseSkillFrontmatter(skill), config: parseSkillConfig(config) };
+    }
+    refresh() {
+        return this.refreshing ??= (async () => {
+            const deadline = new SkillDeadline(SKILL_LIMITS.catalogMs);
+            const snapshot = await deadline.wait(() => this.provider.snapshot(this.source));
+            if (!/^[a-f0-9]{40}$/.test(snapshot.commitSha) || snapshot.packages.length > 500)
+                throw new ServiceError('INVALID_REQUEST', '技能来源目录无效。');
+            const packages = [];
+            const seen = new Set();
+            for (const pkg of snapshot.packages) {
+                deadline.check();
+                if (seen.has(pkg.directory))
+                    throw new ServiceError('INVALID_REQUEST', '技能来源含重复目录。');
+                seen.add(pkg.directory);
+                const item = { skillId: this.source.id + ':' + pkg.directory, source: this.source, directory: pkg.directory, name: pkg.directory, description: '', installed: false, revision: 0, packageVersion: packageDigest(pkg.files), commitSha: snapshot.commitSha, updateAvailable: false, configuration: 'none' };
+                try {
+                    const metadata = await this.metadata(pkg, snapshot.commitSha, deadline);
+                    item.name = metadata.name;
+                    item.description = metadata.description;
+                    item.configuration = metadata.config.environment.length ? 'required' : 'none';
+                    packages.push({ ...pkg, item, config: metadata.config });
+                }
+                catch (error) {
+                    item.error = error instanceof ServiceError ? error.message : '无法读取技能包，请刷新重试。';
+                    packages.push({ ...pkg, item });
+                }
+            }
+            deadline.check();
+            const cache = { source: this.source, fetchedAt: Date.now(), packages };
+            await this.atomicJson('catalog-' + key(JSON.stringify(this.source)) + '.json', cache);
+            return cache;
+        })().finally(() => { this.refreshing = undefined; });
+    }
+    async cached(refresh = false) {
+        await this.initialize();
+        const cache = await this.readJson('catalog-' + key(JSON.stringify(this.source)) + '.json');
+        if (!refresh && cache && Date.now() - cache.fetchedAt < 5 * 60_000)
+            return { cache };
+        try {
+            return { cache: await this.refresh() };
+        }
+        catch (error) {
+            return { cache, error: error instanceof ServiceError ? error.message : '技能来源暂时不可用，请检查网络后重试。' };
+        }
+    }
+    async catalog(refresh = false) {
+        const { cache, error } = await this.cached(refresh);
+        const state = await this.state();
+        const result = new Map();
+        for (const pkg of cache?.packages ?? []) {
+            const local = state.items[pkg.item.skillId];
+            result.set(pkg.item.skillId, local?.installed ? { ...local, updateAvailable: local.packageVersion !== pkg.item.packageVersion, ...(pkg.item.error ? { error: pkg.item.error } : {}) } : { ...pkg.item, revision: local?.revision ?? 0 });
+        }
+        for (const item of Object.values(state.items))
+            if (item.installed && !result.has(item.skillId))
+                result.set(item.skillId, item);
+        return { items: [...result.values()].sort((a, b) => a.name.localeCompare(b.name)), stale: !!error, ...(error ? { error } : {}) };
+    }
+    async installed() { await this.initialize(); return Object.values((await this.state()).items).filter(item => item.installed); }
+    versionDirectory(id, version) {
+        if (!id || id.length > 1024 || !/^[a-f0-9]{64}$/.test(version))
+            throw new ServiceError('INVALID_REQUEST', '技能身份或包版本无效。');
+        return 'versions/' + key(id) + '/' + version;
+    }
+    async packageEntry(skillId, packageVersion) {
+        await this.initialize();
+        const current = (await this.state()).items[skillId];
+        const version = packageVersion ?? (current?.installed ? current.packageVersion : undefined);
+        if (!version)
+            throw new ServiceError('NOT_FOUND', '技能尚未安装或已卸载。');
+        const relative = this.versionDirectory(skillId, version);
+        const manifest = await this.readJson(relative + '/manifest.json');
+        if (!manifest || manifest.version !== 1 || manifest.item.skillId !== skillId || manifest.item.packageVersion !== version)
+            throw new ServiceError('NOT_FOUND', '技能固定包版本不可用。');
+        validatePackageFiles({ directory: manifest.item.directory, files: manifest.files });
+        if (packageDigest(manifest.files) !== version)
+            throw new ServiceError('INVALID_REQUEST', '技能包元数据摘要无效。');
+        for (const file of manifest.files) {
+            const path = await this.checked(relative + '/package/' + file.path);
+            const stat = await fs.stat(path);
+            if (!stat.isFile() || stat.size !== file.size || gitBlobSha(await fs.readFile(path)) !== file.sha)
+                throw new ServiceError('INVALID_REQUEST', '已安装技能包完整性校验失败。');
+        }
+        const config = parseSkillConfig(await fs.readFile(await this.checked(relative + '/package/config.json'), 'utf8'));
+        return { path: await this.checked(relative + '/package/SKILL.md'), config, item: current?.installed && current.packageVersion === version ? current : manifest.item };
+    }
+    /** Holds the same cross-process lock as updates while a configuration write uses its schema. */
+    async withPackageEntry(skillId, expectedVersion, work) {
+        return this.lock(async () => {
+            const entry = await this.packageEntry(skillId);
+            if (entry.item.packageVersion !== expectedVersion)
+                throw new ServiceError('REVISION_CONFLICT', '技能包已更新，请重新打开设置后保存。');
+            return work(entry);
+        });
+    }
+    /** Only files declared in a validated immutable manifest or pinned source snapshot are readable. */
+    async readPackageFile(skillId, packageVersion, path) {
+        safeSkillPath(path);
+        await this.initialize();
+        const relative = this.versionDirectory(skillId, packageVersion);
+        const manifest = await this.readJson(relative + '/manifest.json');
+        if (manifest) {
+            if (manifest.version !== 1 || manifest.item.skillId !== skillId || manifest.item.packageVersion !== packageVersion)
+                throw new ServiceError('INVALID_REQUEST', '技能包元数据无效。');
+            validatePackageFiles({ directory: manifest.item.directory, files: manifest.files });
+            if (packageDigest(manifest.files) !== packageVersion)
+                throw new ServiceError('INVALID_REQUEST', '技能包元数据摘要无效。');
+            const file = manifest.files.find(file => file.path === path);
+            if (!file)
+                throw new ServiceError('NOT_FOUND', '技能包资源不存在。');
+            const target = await this.checked(relative + '/package/' + path);
+            const stat = await fs.stat(target);
+            if (!stat.isFile() || stat.size !== file.size)
+                throw new ServiceError('INVALID_REQUEST', '技能资源完整性校验失败。');
+            const bytes = await fs.readFile(target);
+            if (gitBlobSha(bytes) !== file.sha)
+                throw new ServiceError('INVALID_REQUEST', '技能资源完整性校验失败。');
+            return bytes;
+        }
+        const { cache, error } = await this.cached();
+        const pkg = cache?.packages.find(pkg => pkg.item.skillId === skillId && pkg.item.packageVersion === packageVersion);
+        if (!pkg || pkg.item.error)
+            throw new ServiceError('NOT_FOUND', error ?? '技能固定包版本或资源不可用，请刷新详情。');
+        validatePackageFiles(pkg);
+        const file = pkg.files.find(file => file.path === path);
+        if (!file)
+            throw new ServiceError('NOT_FOUND', '技能包资源不存在。');
+        return this.download(pkg, pkg.item.commitSha, file);
+    }
+    async detail(skillId, locale = 'en') {
+        if (!/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(locale))
+            throw new ServiceError('INVALID_REQUEST', '技能说明语言无效。');
+        const names = [...new Set(['README.' + locale + '.md', 'README.' + locale.split('-')[0] + '.md', 'README.md'])];
+        const current = (await this.installed()).find(item => item.skillId === skillId);
+        if (current) {
+            const entry = await this.packageEntry(skillId);
+            const relative = this.versionDirectory(skillId, current.packageVersion);
+            const manifest = (await this.readJson(relative + '/manifest.json'));
+            const name = names.find(name => manifest.files.some(file => file.path === name));
+            const cached = await this.readJson('catalog-' + key(JSON.stringify(this.source)) + '.json');
+            const remote = cached?.packages.find(pkg => pkg.item.skillId === skillId);
+            return { item: { ...entry.item, updateAvailable: !!remote && remote.item.packageVersion !== entry.item.packageVersion }, config: entry.config, readme: await fs.readFile(join(dirname(entry.path), name), 'utf8') };
+        }
+        const { cache, error } = await this.cached();
+        const pkg = cache?.packages.find(pkg => pkg.item.skillId === skillId);
+        if (!pkg)
+            throw new ServiceError('NOT_FOUND', error ?? '技能不存在。');
+        if (pkg.item.error || !pkg.config)
+            throw new ServiceError('INVALID_REQUEST', pkg.item.error ?? '技能包配置无效。');
+        const file = pkg.files.find(file => file.path === names.find(name => pkg.files.some(file => file.path === name)));
+        if (file.size > SKILL_LIMITS.metadataBytes)
+            throw new ServiceError('PAYLOAD_TOO_LARGE', '技能说明超过大小限制。');
+        return { item: { ...pkg.item, revision: (await this.state()).items[skillId]?.revision ?? 0 }, config: pkg.config, readme: (await this.download(pkg, pkg.item.commitSha, file)).toString('utf8') };
+    }
+    async install(skillId, expectedRevision) {
+        const deadline = new SkillDeadline(SKILL_LIMITS.installMs);
+        return this.lock(async () => {
+            deadline.check();
+            const state = await this.state();
+            const current = state.items[skillId];
+            this.checkRevision(current, expectedRevision);
+            const { cache, error } = await deadline.wait(() => this.cached(true));
+            // A stale catalog may be shown, but must never be used to publish an installation.
+            if (error)
+                throw new ServiceError('NOT_FOUND', error, { retryable: true });
+            const pkg = cache?.packages.find(pkg => pkg.item.skillId === skillId);
+            if (!pkg)
+                throw new ServiceError('NOT_FOUND', '技能不存在。');
+            if (pkg.item.error)
+                throw new ServiceError('INVALID_REQUEST', pkg.item.error);
+            if (current?.installed && current.packageVersion === pkg.item.packageVersion)
+                return current;
+            const item = { ...pkg.item, installed: true, revision: (current?.revision ?? 0) + 1, updateAvailable: false };
+            const target = this.versionDirectory(skillId, item.packageVersion);
+            const staging = 'staging/install-' + randomUUID();
+            await this.directory(staging + '/package');
+            try {
+                for (const file of pkg.files) {
+                    const bytes = await this.download(pkg, item.commitSha, file, deadline);
+                    deadline.check();
+                    const path = await this.checked(staging + '/package/' + file.path);
+                    await fs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+                    await fs.writeFile(path, bytes, { flag: 'wx', mode: file.mode === '100755' ? 0o700 : 0o600 });
+                }
+                parseSkillFrontmatter(await fs.readFile(await this.checked(staging + '/package/SKILL.md'), 'utf8'));
+                parseSkillConfig(await fs.readFile(await this.checked(staging + '/package/config.json'), 'utf8'));
+                deadline.check();
+                await this.atomicJson(staging + '/manifest.json', { version: 1, item, files: pkg.files, installedAt: new Date().toISOString() });
+                await this.directory('versions/' + key(skillId));
+                const existing = await this.readJson(target + '/manifest.json');
+                deadline.check();
+                if (!existing)
+                    await fs.rename(await this.checked(staging), await this.checked(target));
+                else
+                    await this.packageEntry(skillId, item.packageVersion);
+                deadline.check();
+                state.items[skillId] = item;
+                await this.atomicJson('installed.json', state);
+                return item;
+            }
+            finally {
+                await fs.rm(await this.checked(staging), { recursive: true, force: true });
+            }
+        });
+    }
+    async uninstall(skillId, expectedRevision) {
+        return this.lock(async () => {
+            const state = await this.state();
+            const current = state.items[skillId];
+            this.checkRevision(current, expectedRevision);
+            if (!current)
+                throw new ServiceError('NOT_FOUND', '技能不存在。');
+            if (!current.installed)
+                return current;
+            const item = { ...current, installed: false, revision: current.revision + 1, updateAvailable: false };
+            state.items[skillId] = item;
+            await this.atomicJson('installed.json', state);
+            return item;
+        });
+    }
+    checkRevision(item, expected) {
+        if (!Number.isSafeInteger(expected) || expected < 0)
+            throw new ServiceError('INVALID_REQUEST', '技能操作需要有效的 expectedRevision。');
+        if ((item?.revision ?? 0) !== expected)
+            throw new ServiceError('REVISION_CONFLICT', '技能安装状态已改变，请刷新后重试。');
+    }
+}
+//# sourceMappingURL=builtin-skills.js.map

package/dist/graph-transfer.js

@@ -4,7 +4,7 @@ import { previewEdgeError } from "./vendor/protocol/index.js";
 import { Graphs, assertProjectWritable, resourceLinks, nodeDimension } from './graphs.js';
 import { Resources } from './resources.js';
 import { mimeMatchesBytes, sniffMime } from './blob-store.js';
-import { checkedJson, PluginRegistry } from './plugins.js';
+import { checkedJson, PluginRegistry, portableSkillContent } from './plugins.js';
 import { atomic } from './persistence/database.js';
 import { canonicalJsonHash } from './persistence/repositories.js';
 import { ServiceError } from './errors.js';
@@ -13,7 +13,10 @@ const DEFAULT_LIMITS = { maxBundleBytes: WORKGRAPH_BUNDLE_MAX_BYTES, maxResource
 const core = new Set(['text', 'image', 'document', 'video', 'file', 'preview', 'execution', 'group']);
 const key = (id, version) => JSON.stringify([id, version]);
 function portableNode(node) {
-    return structuredClone(node);
+    const result = structuredClone(node);
+    if (core.has(node.type))
+        result.content = portableSkillContent(result.content);
+    return result;
 }
 function invalid(message) { throw new ServiceError('INVALID_REQUEST', message); }
 function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
@@ -181,6 +184,8 @@ export class GraphTransfer {
             if (nodes.has(n.id) || typeof n.readOnly !== 'boolean' || !Number.isFinite(n.x) || !Number.isFinite(n.y) || Math.abs(n.x) > 1e9 || Math.abs(n.y) > 1e9)
                 invalid('Invalid or duplicate node');
             checkedJson(n.content, 2 * 1024 * 1024, 32);
+            if (core.has(n.type))
+                n.content = portableSkillContent(n.content);
             if (n.width !== undefined)
                 nodeDimension(n.width);
             if (n.height !== undefined)

package/dist/inputs.d.ts

@@ -52,6 +52,7 @@ export interface InputPreview {
 }
 export type BuildInputOptions = {
     expectedExecutionRevision?: number;
+    skills?: import("./vendor/protocol/index.js").FrozenSkill[];
 } & ({
     model: ModelSelection;
     imageRoute?: Extract<ImageRoute, {

package/dist/inputs.js

@@ -58,7 +58,7 @@ export class InputPreparation {
         else {
             if (!options.model || typeof options.model.model !== 'string' || !options.model.model.trim() || (options.model.reasoningEffort !== null && typeof options.model.reasoningEffort !== 'string'))
                 throw new ServiceError('MODEL_UNAVAILABLE', 'A valid model selection is required');
-            payload = { ...base, model: { model: options.model.model, reasoningEffort: options.model.reasoningEffort }, ...(options.imageRoute ? { imageRoute: options.imageRoute, inputMode } : {}) };
+            payload = { ...base, model: { model: options.model.model, reasoningEffort: options.model.reasoningEffort }, ...(options.skills?.length ? { skills: structuredClone(options.skills) } : {}), ...(options.imageRoute ? { imageRoute: options.imageRoute, inputMode } : {}) };
         }
         // Include exact source revisions and edge provenance in the digest without sending ancestors to the model.
         const inputDigest = createHash('sha256').update(JSON.stringify({ graphId, nodeId, ...payload, sources: preview.sources })).digest('hex');

package/dist/plugins.d.ts

@@ -34,6 +34,10 @@ export interface PluginContract {
 /** Bounded pure JSON only: no getters, functions, cycles or exotic prototypes. */
 export declare function checkedJson(value: unknown, maxBytes?: number, maxDepth?: number): Json;
 export declare function readField(content: Json, field: string): Json | undefined;
+/** Validate explicit references against the exact prompt occurrence, including boundaries. */
+export declare function validSkillContent(content: Json): boolean;
+/** Keep explicit Codex provenance while removing host paths; re-selection is required. */
+export declare function portableSkillContent(content: Json): Json;
 export interface PluginInformation {
     state: 'available' | 'missing' | 'incompatible' | 'invalid';
     typeId: string;

package/dist/plugins.js

@@ -1,3 +1,4 @@
+import { isSkillName } from "./vendor/protocol/index.js";
 import { ServiceError } from './errors.js';
 const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
 const builtins = new Set(['text', 'image', 'document', 'video', 'file', 'preview', 'execution', 'group']);
@@ -154,6 +155,37 @@ function validateContract(input) {
     }
     return c;
 }
+/** Validate explicit references against the exact prompt occurrence, including boundaries. */
+export function validSkillContent(content) {
+    if (!object(content) || content.skillReferences === undefined)
+        return true;
+    const refs = content.skillReferences;
+    if (!Array.isArray(refs) || refs.length > 1024 || typeof content.prompt !== 'string')
+        return false;
+    const prompt = content.prompt;
+    let end = 0;
+    for (const value of refs) {
+        if (!object(value) || Object.keys(value).some(key => !['skillId', 'source', 'name', 'start', 'end'].includes(key)))
+            return false;
+        const ref = value;
+        if (typeof ref.skillId !== 'string' || !ref.skillId.trim() || ref.skillId.length > 4096 || /[\x00-\x1f]/.test(ref.skillId) ||
+            !['openworkgraph', 'codex'].includes(ref.source) || !isSkillName(ref.name) ||
+            !Number.isSafeInteger(ref.start) || !Number.isSafeInteger(ref.end) || ref.start < end || ref.end > prompt.length ||
+            prompt.slice(ref.start, ref.end) !== '$' + ref.name ||
+            (ref.start > 0 && !/\s/.test(prompt[ref.start - 1])) || (ref.end < prompt.length && !/[\s.,!?;，。！？；]/.test(prompt[ref.end])))
+            return false;
+        end = ref.end;
+    }
+    return true;
+}
+/** Keep explicit Codex provenance while removing host paths; re-selection is required. */
+export function portableSkillContent(content) {
+    if (!object(content) || content.skillReferences === undefined)
+        return content;
+    if (!validSkillContent(content))
+        invalid('Invalid skill references');
+    return { ...content, skillReferences: content.skillReferences.map(ref => object(ref) && ref.source === 'codex' ? { ...ref, skillId: 'codex-unresolved:' + ref.name } : ref) };
+}
 export class PluginRegistry {
     db;
     constructor(db) {
@@ -209,7 +241,7 @@ export class PluginRegistry {
         }
         if (!contract)
             return { state: 'missing', typeId: type, schemaVersion, content, reason: 'Resource contract is unavailable', contract: null };
-        const valid = matches(contract.contentSchema, content);
+        const valid = matches(contract.contentSchema, content) && (!builtins.has(type) || validSkillContent(content));
         return { state: valid ? 'available' : 'invalid', typeId: type, schemaVersion, content, reason: valid ? null : 'Content does not match schema', contract };
     }
     /** Pure copy-on-success migration. Caller persists new node version atomically; old version is never changed. */

package/dist/runtime-backend.d.ts

@@ -5,6 +5,7 @@ import { Runs } from './runs.js';
 import { ProjectProbe } from './project-probe.js';
 import { type DataDirectories } from './directories.js';
 import { RunContexts } from './run-context.js';
+import type { SkillSessions } from './skill-sessions.js';
 export declare function backendReply(interaction: Interaction, answer: Json): BackendReply;
 /** Trusted host bridge. Never accepts browser paths or creates isolation evidence. */
 export declare class RuntimeBackend implements SchedulerBackend {
@@ -12,9 +13,10 @@ export declare class RuntimeBackend implements SchedulerBackend {
     readonly dirs: DataDirectories;
     readonly adapter: BackendAdapter;
     readonly probe: ProjectProbe;
+    readonly skillSessions?: SkillSessions | undefined;
     private readonly contexts;
     readonly runContexts: RunContexts;
-    constructor(runs: Runs, dirs: DataDirectories, adapter: BackendAdapter, probe?: ProjectProbe);
+    constructor(runs: Runs, dirs: DataDirectories, adapter: BackendAdapter, probe?: ProjectProbe, skillSessions?: SkillSessions | undefined);
     private snapshot;
     start(run: Run, snapshot: InputSnapshot, context: BackendContext): Promise<void>;
     queryHistory(runId: string, query: string): string;