shennian 0.2.63 → 0.2.65

package/dist/src/session/handlers/fs.js

@@ -4,9 +4,70 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 const FILE_SYSTEM_ROOTS_PATH = '__roots__';
+const MAX_FOLDER_UPLOAD_FILES = 2000;
+const MAX_FOLDER_UPLOAD_TOTAL_SIZE = 1024 * 1024 * 1024;
 function isWindowsAbsolutePath(pathValue) {
     return /^[A-Za-z]:([\\/]|$)/.test(pathValue) || /^\\\\[^\\]+\\[^\\]+/.test(pathValue);
 }
+function pathApiForPath(pathValue) {
+    return isWindowsAbsolutePath(pathValue) ? path.win32 : path.posix;
+}
+function makeFsEntry(entryPath) {
+    const stat = fs.statSync(entryPath);
+    const api = pathApiForPath(entryPath);
+    return {
+        name: api.basename(entryPath),
+        path: entryPath,
+        isDir: stat.isDirectory(),
+        size: stat.isFile() ? stat.size : undefined,
+        modifiedAt: stat.mtimeMs,
+    };
+}
+function isSafeRelativeUploadPath(relativePath) {
+    if (!relativePath || relativePath === '.' || relativePath.trim() !== relativePath)
+        return false;
+    if (path.posix.isAbsolute(relativePath) || path.win32.isAbsolute(relativePath))
+        return false;
+    const normalized = relativePath.replace(/\\/g, '/');
+    if (normalized !== relativePath)
+        return false;
+    return normalized
+        .split('/')
+        .every((segment) => segment && segment !== '.' && segment !== '..' && !hasControlChar(segment));
+}
+function isSafeRenameName(name) {
+    const trimmed = name.trim();
+    if (!trimmed || trimmed !== name)
+        return false;
+    if (name === '.' || name === '..')
+        return false;
+    if (hasControlChar(name) || /[\\/:]/.test(name))
+        return false;
+    if (/[<>|"?*]/.test(name))
+        return false;
+    if (/[. ]$/.test(name))
+        return false;
+    const upper = name.split('.')[0]?.toUpperCase();
+    if (upper && /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/.test(upper))
+        return false;
+    return true;
+}
+function hasControlChar(value) {
+    return Array.from(value).some((char) => {
+        const code = char.charCodeAt(0);
+        return code >= 0x00 && code <= 0x1f;
+    });
+}
+function decodeManifest(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => ({
+        relativePath: String(item.relativePath || ''),
+        size: Number(item.size || 0),
+        mimeType: item.mimeType,
+        modifiedAt: item.modifiedAt,
+    }));
+}
 export async function handleFsLs(runtime, req) {
     const requestedPath = req.params.path || os.homedir();
     const rootPath = req.params.rootPath || requestedPath;
@@ -129,6 +190,83 @@ export async function handleFsRead(runtime, req) {
         runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });
     }
 }
+export async function handleFsWrite(runtime, req) {
+    const requestedPath = req.params.path;
+    const content = req.params.content;
+    const rootPath = req.params.rootPath || requestedPath;
+    if (!requestedPath || typeof content !== 'string') {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'path and content are required' });
+        return;
+    }
+    const resolved = runtime.resolveAuthorizedPath(requestedPath, rootPath);
+    if (!resolved.ok) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: resolved.error });
+        return;
+    }
+    try {
+        const existing = fs.existsSync(resolved.path) ? fs.statSync(resolved.path) : null;
+        if (existing && !existing.isFile()) {
+            runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Not a file' });
+            return;
+        }
+        fs.writeFileSync(resolved.path, content, 'utf-8');
+        const stat = fs.statSync(resolved.path);
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: { path: resolved.path, size: stat.size, modifiedAt: stat.mtimeMs },
+        });
+    }
+    catch (err) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });
+    }
+}
+export async function handleFsRename(runtime, req) {
+    const requestedPath = req.params.path;
+    const newName = req.params.newName;
+    const rootPath = req.params.rootPath || requestedPath;
+    if (!requestedPath || !newName) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'path and newName are required' });
+        return;
+    }
+    if (!isSafeRenameName(newName)) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Invalid newName' });
+        return;
+    }
+    const resolved = runtime.resolveAuthorizedPath(requestedPath, rootPath);
+    if (!resolved.ok) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: resolved.error });
+        return;
+    }
+    try {
+        const api = pathApiForPath(resolved.path);
+        const newPath = api.join(api.dirname(resolved.path), newName);
+        const checkedNewPath = runtime.resolveAuthorizedPath(newPath, rootPath);
+        if (!checkedNewPath.ok) {
+            runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: checkedNewPath.error });
+            return;
+        }
+        if (fs.existsSync(checkedNewPath.path)) {
+            runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Target already exists' });
+            return;
+        }
+        fs.renameSync(resolved.path, checkedNewPath.path);
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: {
+                oldPath: resolved.path,
+                newPath: checkedNewPath.path,
+                entry: makeFsEntry(checkedNewPath.path),
+            },
+        });
+    }
+    catch (err) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });
+    }
+}
 export async function handleFsTransfer(runtime, req) {
     const { name, targetPath, data, direct } = req.params;
     if (!name || !data) {
@@ -156,8 +294,11 @@ export async function handleFsTransfer(runtime, req) {
     }
 }
 export async function handleFsTransferStart(runtime, req) {
-    const { name, targetPath, totalSize, direct } = req.params;
-    if (!name || !totalSize) {
+    const { name, targetPath, totalSize, direct, kind, baseName } = req.params;
+    const manifest = decodeManifest(req.params.manifest);
+    const isFolder = kind === 'folder';
+    const transferName = isFolder ? (baseName || name) : name;
+    if (!transferName || (!isFolder && !totalSize)) {
         runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'name and totalSize are required' });
         return;
     }
@@ -173,10 +314,74 @@ export async function handleFsTransferStart(runtime, req) {
         if (!direct)
             fs.mkdirSync(destinationDir, { recursive: true });
         const transferId = `tf-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        if (isFolder) {
+            if (!manifest.length) {
+                runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'manifest is required for folder uploads' });
+                return;
+            }
+            if (manifest.length > MAX_FOLDER_UPLOAD_FILES) {
+                runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: `Too many files: ${manifest.length}` });
+                return;
+            }
+            const folderName = path.basename(transferName);
+            if (!isSafeRenameName(folderName)) {
+                runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Invalid folder name' });
+                return;
+            }
+            const targetDir = path.join(destinationDir, folderName);
+            const checkedTargetDir = runtime.resolveAuthorizedPath(targetDir, rootPath);
+            if (!checkedTargetDir.ok) {
+                runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: checkedTargetDir.error });
+                return;
+            }
+            const seen = new Set();
+            let aggregateSize = 0;
+            const files = new Map();
+            for (const item of manifest) {
+                if (!isSafeRelativeUploadPath(item.relativePath)) {
+                    runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: `Invalid relativePath: ${item.relativePath}` });
+                    return;
+                }
+                if (!Number.isFinite(item.size) || item.size < 0) {
+                    runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: `Invalid size: ${item.relativePath}` });
+                    return;
+                }
+                if (seen.has(item.relativePath)) {
+                    runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: `Duplicate relativePath: ${item.relativePath}` });
+                    return;
+                }
+                seen.add(item.relativePath);
+                aggregateSize += item.size;
+                if (aggregateSize > MAX_FOLDER_UPLOAD_TOTAL_SIZE) {
+                    runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: `Folder too large: ${aggregateSize} bytes` });
+                    return;
+                }
+                const finalPath = path.join(checkedTargetDir.path, ...item.relativePath.split('/'));
+                const checkedFinalPath = runtime.resolveAuthorizedPath(finalPath, rootPath);
+                if (!checkedFinalPath.ok) {
+                    runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: checkedFinalPath.error });
+                    return;
+                }
+                const tempPath = path.join(os.tmpdir(), `.shennian-upload-${transferId}-${files.size}`);
+                fs.writeFileSync(tempPath, Buffer.alloc(0));
+                files.set(item.relativePath, { relativePath: item.relativePath, tempPath, targetPath: checkedFinalPath.path, size: item.size });
+            }
+            runtime.pendingTransfers.set(transferId, {
+                tempPath: '',
+                targetPath: checkedTargetDir.path,
+                totalSize: aggregateSize,
+                kind: 'folder',
+                rootPath,
+                targetDir: checkedTargetDir.path,
+                files,
+            });
+            runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { transferId, path: checkedTargetDir.path } });
+            return;
+        }
         const tempPath = path.join(os.tmpdir(), `.shennian-upload-${transferId}`);
-        const finalPath = path.join(destinationDir, path.basename(name));
+        const finalPath = path.join(destinationDir, path.basename(transferName));
         fs.writeFileSync(tempPath, Buffer.alloc(0));
-        runtime.pendingTransfers.set(transferId, { tempPath, targetPath: finalPath, totalSize });
+        runtime.pendingTransfers.set(transferId, { tempPath, targetPath: finalPath, totalSize, kind: 'file' });
         runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { transferId } });
     }
     catch (err) {
@@ -184,15 +389,26 @@ export async function handleFsTransferStart(runtime, req) {
     }
 }
 export async function handleFsTransferChunk(runtime, req) {
-    const { transferId, offset, data } = req.params;
+    const { transferId, offset, data, relativePath } = req.params;
     const transfer = runtime.pendingTransfers.get(transferId);
     if (!transfer) {
         runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Invalid transferId' });
         return;
     }
     try {
+        const target = transfer.kind === 'folder'
+            ? transfer.files?.get(String(relativePath || ''))
+            : { tempPath: transfer.tempPath, size: transfer.totalSize };
+        if (!target) {
+            runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Invalid relativePath' });
+            return;
+        }
         const buffer = Buffer.from(data, 'base64');
-        const fd = fs.openSync(transfer.tempPath, 'r+');
+        if (offset < 0 || offset + buffer.length > target.size) {
+            runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Chunk exceeds declared size' });
+            return;
+        }
+        const fd = fs.openSync(target.tempPath, 'r+');
         try {
             fs.writeSync(fd, buffer, 0, buffer.length, offset);
         }
@@ -213,6 +429,22 @@ export async function handleFsTransferFinish(runtime, req) {
         return;
     }
     try {
+        if (transfer.kind === 'folder') {
+            let count = 0;
+            for (const file of transfer.files?.values() ?? []) {
+                fs.mkdirSync(path.dirname(file.targetPath), { recursive: true });
+                fs.renameSync(file.tempPath, file.targetPath);
+                count += 1;
+            }
+            runtime.pendingTransfers.delete(transferId);
+            runtime.client.sendRes({
+                type: 'res',
+                id: req.id,
+                ok: true,
+                payload: { path: transfer.targetDir ?? transfer.targetPath, count },
+            });
+            return;
+        }
         fs.renameSync(transfer.tempPath, transfer.targetPath);
         runtime.pendingTransfers.delete(transferId);
         runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { path: transfer.targetPath } });
@@ -233,11 +465,17 @@ export async function handleFsTransferAbort(runtime, req) {
     const { transferId } = req.params;
     const transfer = runtime.pendingTransfers.get(transferId);
     if (transfer) {
-        try {
-            fs.unlinkSync(transfer.tempPath);
-        }
-        catch {
-            // ignore cleanup failures
+        const tempPaths = transfer.kind === 'folder'
+            ? Array.from(transfer.files?.values() ?? []).map((file) => file.tempPath)
+            : [transfer.tempPath];
+        for (const tempPath of tempPaths) {
+            try {
+                if (tempPath)
+                    fs.unlinkSync(tempPath);
+            }
+            catch {
+                // ignore cleanup failures
+            }
         }
         runtime.pendingTransfers.delete(transferId);
     }
@@ -245,11 +483,17 @@ export async function handleFsTransferAbort(runtime, req) {
 }
 export function cleanupPendingTransfers(runtime) {
     for (const [, transfer] of runtime.pendingTransfers) {
-        try {
-            fs.unlinkSync(transfer.tempPath);
-        }
-        catch {
-            // ignore cleanup failures
+        const tempPaths = transfer.kind === 'folder'
+            ? Array.from(transfer.files?.values() ?? []).map((file) => file.tempPath)
+            : [transfer.tempPath];
+        for (const tempPath of tempPaths) {
+            try {
+                if (tempPath)
+                    fs.unlinkSync(tempPath);
+            }
+            catch {
+                // ignore cleanup failures
+            }
         }
     }
     runtime.pendingTransfers.clear();

package/dist/src/session/handlers/skills.d.ts

@@ -0,0 +1,5 @@
+import type { ReqFrame } from '@shennian/wire';
+import type { SessionManagerRuntime } from '../types.js';
+export declare function handleSkillList(runtime: SessionManagerRuntime, req: ReqFrame): Promise<void>;
+export declare function handleSkillInstall(runtime: SessionManagerRuntime, req: ReqFrame): Promise<void>;
+export declare function handleSkillUse(runtime: SessionManagerRuntime, req: ReqFrame): Promise<void>;

package/dist/src/session/handlers/skills.js

@@ -0,0 +1,50 @@
+// @arch docs/features/skill-marketplace.md
+// @test src/__tests__/skill-registry.test.ts
+import { buildSkillUsePrompt, installSkillFromUrl, listInstalledSkills } from '../../skills/registry.js';
+export async function handleSkillList(runtime, req) {
+    runtime.client.sendRes({
+        type: 'res',
+        id: req.id,
+        ok: true,
+        payload: { skills: listInstalledSkills() },
+    });
+}
+export async function handleSkillInstall(runtime, req) {
+    const installUrl = typeof req.params.installUrl === 'string' ? req.params.installUrl : '';
+    if (!installUrl) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'installUrl is required' });
+        return;
+    }
+    const installed = await installSkillFromUrl(installUrl);
+    runtime.client.sendRes({
+        type: 'res',
+        id: req.id,
+        ok: true,
+        payload: { skill: installed },
+    });
+}
+export async function handleSkillUse(runtime, req) {
+    const skillId = typeof req.params.skillId === 'string' ? req.params.skillId : '';
+    const workDir = typeof req.params.workDir === 'string' ? req.params.workDir : process.cwd();
+    const attachments = Array.isArray(req.params.attachments)
+        ? req.params.attachments
+            .map((item) => {
+            const record = item;
+            const path = typeof record.path === 'string' ? record.path : '';
+            const name = typeof record.name === 'string' ? record.name : '';
+            const mimeType = typeof record.mimeType === 'string' ? record.mimeType : '';
+            return path && name ? { path, name, mimeType } : null;
+        })
+            .filter((item) => item != null)
+        : undefined;
+    if (!skillId) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'skillId is required' });
+        return;
+    }
+    runtime.client.sendRes({
+        type: 'res',
+        id: req.id,
+        ok: true,
+        payload: { prompt: buildSkillUsePrompt(skillId, workDir, attachments) },
+    });
+}

package/dist/src/session/manager.js

@@ -8,7 +8,8 @@ import { handleAgentsRefresh, handleModelsRefresh } from './handlers/agents.js';
 import { handleAgentConfigClear, handleAgentConfigGet, handleAgentConfigTest, handleAgentConfigUpsert, } from './handlers/agent-config.js';
 import { handleChatAbort, handleChatSend } from './handlers/chat.js';
 import { handleSessionRefresh } from './handlers/session-refresh.js';
-import { cleanupPendingTransfers, handleFsLs, handleFsRead, handleFsTransfer, handleFsTransferAbort, handleFsTransferChunk, handleFsTransferFinish, handleFsTransferStart, } from './handlers/fs.js';
+import { cleanupPendingTransfers, handleFsLs, handleFsRead, handleFsRename, handleFsWrite, handleFsTransfer, handleFsTransferAbort, handleFsTransferChunk, handleFsTransferFinish, handleFsTransferStart, } from './handlers/fs.js';
+import { handleSkillInstall, handleSkillList, handleSkillUse } from './handlers/skills.js';
 import { handleRegionProbe, handleRegionSwitch, handleUpgradeSetPolicy } from './handlers/control.js';
 import { ManagerRuntimeService, setManagerRuntimeService } from '../manager/runtime.js';
 import { ChatQueueManager } from './queue.js';
@@ -113,6 +114,21 @@ export class SessionManager {
                 case 'fs.read':
                     await handleFsRead(runtime, req);
                     break;
+                case 'fs.write':
+                    await handleFsWrite(runtime, req);
+                    break;
+                case 'fs.rename':
+                    await handleFsRename(runtime, req);
+                    break;
+                case 'skill.list':
+                    await handleSkillList(runtime, req);
+                    break;
+                case 'skill.install':
+                    await handleSkillInstall(runtime, req);
+                    break;
+                case 'skill.use':
+                    await handleSkillUse(runtime, req);
+                    break;
                 case 'fs.transfer':
                     await handleFsTransfer(runtime, req);
                     break;

package/dist/src/session/types.d.ts

@@ -25,6 +25,16 @@ export type PendingTransfer = {
     tempPath: string;
     targetPath: string;
     totalSize: number;
+    kind?: 'file' | 'folder';
+    rootPath?: string;
+    targetDir?: string;
+    files?: Map<string, PendingTransferFile>;
+};
+export type PendingTransferFile = {
+    relativePath: string;
+    tempPath: string;
+    targetPath: string;
+    size: number;
 };
 export type ChatQueueService = {
     handleEnqueue(req: import('@shennian/wire').ReqFrame): Promise<void>;

package/dist/src/skills/registry.d.ts

@@ -0,0 +1,12 @@
+import type { InstalledShennianSkill } from '@shennian/wire';
+export declare function getSkillsDir(): string;
+export declare function getSkillDir(skillId: string): string;
+export declare function listInstalledSkills(): InstalledShennianSkill[];
+export declare function getInstalledSkill(skillId: string): InstalledShennianSkill | null;
+export declare function installSkillFromUrl(installUrl: string): Promise<InstalledShennianSkill>;
+export declare function buildSkillUsePrompt(skillId: string, workDir: string, attachments?: Array<{
+    path: string;
+    name: string;
+    mimeType: string;
+}>): string;
+export declare function buildInstalledSkillInstructions(): string;

package/dist/src/skills/registry.js

@@ -0,0 +1,128 @@
+// @arch docs/features/skill-marketplace.md
+// @test src/__tests__/skill-registry.test.ts
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveShennianPath } from '../config/index.js';
+function safeSkillId(skillId) {
+    const normalized = skillId.trim();
+    if (!/^[a-z0-9][a-z0-9._-]{1,80}$/i.test(normalized)) {
+        throw new Error('Invalid skill id');
+    }
+    return normalized;
+}
+function assertSafeBundlePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+    if (!normalized || normalized.startsWith('/') || normalized.includes('\0')) {
+        throw new Error(`Unsafe bundle path: ${relativePath}`);
+    }
+    const parts = normalized.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..')) {
+        throw new Error(`Unsafe bundle path: ${relativePath}`);
+    }
+    return normalized;
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function getSkillsDir() {
+    const skillsDir = resolveShennianPath('skills');
+    fs.mkdirSync(skillsDir, { recursive: true });
+    return skillsDir;
+}
+export function getSkillDir(skillId) {
+    return path.join(getSkillsDir(), safeSkillId(skillId));
+}
+export function listInstalledSkills() {
+    const dir = getSkillsDir();
+    return fs.readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => {
+        const skillPath = path.join(dir, entry.name);
+        const manifest = readJsonFile(path.join(skillPath, 'skill.json'));
+        const install = readJsonFile(path.join(skillPath, '.shennian-install.json'));
+        if (!manifest?.id || !manifest.name)
+            return null;
+        return {
+            ...manifest,
+            installedAt: install?.installedAt ?? new Date(0).toISOString(),
+            path: skillPath,
+        };
+    })
+        .filter((item) => item != null)
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+export function getInstalledSkill(skillId) {
+    return listInstalledSkills().find((skill) => skill.id === skillId) ?? null;
+}
+async function fetchSkillBundle(installUrl) {
+    if (!installUrl.startsWith('http://') && !installUrl.startsWith('https://')) {
+        return readJsonFile(path.resolve(installUrl)) ?? (() => {
+            throw new Error('Invalid skill bundle');
+        })();
+    }
+    const res = await fetch(installUrl);
+    if (!res.ok)
+        throw new Error(`Skill download failed: ${res.status} ${res.statusText}`);
+    return await res.json();
+}
+function writeBundleFile(skillDir, file) {
+    const relativePath = assertSafeBundlePath(file.path);
+    const target = path.join(skillDir, relativePath);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.content, 'utf8');
+    if (file.executable && process.platform !== 'win32') {
+        fs.chmodSync(target, 0o755);
+    }
+}
+export async function installSkillFromUrl(installUrl) {
+    const bundle = await fetchSkillBundle(installUrl);
+    if (!bundle?.manifest?.id || !Array.isArray(bundle.files)) {
+        throw new Error('Invalid skill bundle');
+    }
+    const skillDir = getSkillDir(bundle.manifest.id);
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, 'skill.json'), JSON.stringify(bundle.manifest, null, 2) + '\n', 'utf8');
+    for (const file of bundle.files) {
+        writeBundleFile(skillDir, file);
+    }
+    fs.writeFileSync(path.join(skillDir, '.shennian-install.json'), JSON.stringify({ installedAt: new Date().toISOString(), installUrl }, null, 2) + '\n', 'utf8');
+    const installed = getInstalledSkill(bundle.manifest.id);
+    if (!installed)
+        throw new Error('Skill installation did not complete');
+    return installed;
+}
+export function buildSkillUsePrompt(skillId, workDir, attachments) {
+    const installed = getInstalledSkill(skillId);
+    if (!installed)
+        throw new Error(`Skill not installed: ${skillId}`);
+    const attachmentLines = (attachments ?? [])
+        .map((attachment) => `- ${attachment.name} (${attachment.mimeType}): ${attachment.path}`)
+        .join('\n');
+    return [
+        `Use the Shennian skill "${installed.name}".`,
+        '',
+        `Skill folder: ${installed.path}`,
+        `Before using it, read: ${path.join(installed.path, 'SKILL.md')}`,
+        `Working directory: ${workDir}`,
+        attachmentLines ? `\nCurrent attachments:\n${attachmentLines}` : '',
+        '',
+        'Follow the skill output contract. Prefer local deterministic extraction first, then use agent document or vision capability only when needed.',
+    ].filter(Boolean).join('\n');
+}
+export function buildInstalledSkillInstructions() {
+    const skills = listInstalledSkills();
+    if (skills.length === 0)
+        return '';
+    const lines = skills.map((skill) => [
+        `- ${skill.id}: ${skill.description}`,
+        `  Skill folder: ${skill.path}`,
+        `  Read ${path.join(skill.path, 'SKILL.md')} before using this skill.`,
+    ].join('\n'));
+    return `## Shennian Skills\n\nInstalled skills are file-based capabilities managed by Shennian under ${getSkillsDir()}.\nWhen a user asks to use one, read its SKILL.md and follow its output contract.\n\n${lines.join('\n')}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shennian",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "description": "Shennian — AI Agent Control Plane CLI",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "commander": "^13.1.0",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.1",
-    "@shennian/wire": "0.1.4"
+    "@shennian/wire": "0.1.5"
   },
   "devDependencies": {
     "@types/node": "^20",