shennian 0.2.68 → 0.2.69

package/dist/src/agents/adapter.d.ts

@@ -35,6 +35,7 @@ export declare abstract class AgentAdapter extends EventEmitter<AgentAdapterEven
         externalChannel?: ExternalChannelSessionStatus | null;
         env?: NodeJS.ProcessEnv;
     }): void;
+    setTitle?(agentSessionId: string, title: string, workDir?: string): Promise<void>;
     abstract start(sessionId: string, workDir: string, agentSessionId?: string | null): Promise<void>;
     abstract send(text: string, modelId?: string, reasoningEffort?: string, attachments?: ChatAttachmentMeta[]): Promise<void>;
     abstract resume(agentSessionId: string): Promise<void>;

package/dist/src/agents/codex.d.ts

@@ -38,6 +38,7 @@ export declare class CodexAdapter extends AgentAdapter {
     start(_sessionId: string, workDir: string, agentSessionId?: string | null): Promise<void>;
     send(text: string, modelId?: string, reasoningEffort?: string, attachments?: ChatAttachmentMeta[]): Promise<void>;
     resume(agentSessionId: string): Promise<void>;
+    setTitle(agentSessionId: string, title: string, workDir?: string): Promise<void>;
     stop(): Promise<void>;
     private spawnCodex;
     private spawnAppServer;

package/dist/src/agents/codex.js

@@ -101,6 +101,18 @@ export class CodexAdapter extends AgentAdapter {
         this.namedThread = true;
         this.resetTextState();
     }
+    async setTitle(agentSessionId, title, workDir) {
+        const threadId = agentSessionId.trim();
+        const name = title.replace(/\s+/g, ' ').trim();
+        if (!threadId || !name)
+            return;
+        this.agentSessionId = threadId;
+        if (workDir?.trim())
+            this.workDir = workDir;
+        await this.ensureAppServer();
+        await this.sendRpc('thread/name/set', { threadId, name });
+        this.namedThread = true;
+    }
     async stop() {
         await this.interruptActiveTurn().catch(() => { });
         await this.killProcess();

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

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { convertMarkdownToPdf, defaultPdfOutputPath } from '../../tools/markdown-to-pdf.js';
+import { convertMarkdownToPdf, defaultPdfOutputPath, MarkdownPdfBrowserMissingError, } from '../../tools/markdown-to-pdf.js';
 const FILE_SYSTEM_ROOTS_PATH = '__roots__';
 const MAX_FOLDER_UPLOAD_FILES = 2000;
 const MAX_FOLDER_UPLOAD_TOTAL_SIZE = 1024 * 1024 * 1024;
@@ -37,7 +37,9 @@ function listFileSystemRoots() {
     return [{ name: '/', path: '/', isDir: true }];
 }
 function fsErrorMessage(err, fallbackPath) {
-    const code = typeof err === 'object' && err && 'code' in err ? String(err.code) : '';
+    const code = typeof err === 'object' && err && 'code' in err
+        ? String(err.code)
+        : '';
     if (code === 'ENOENT')
         return `Directory not found: ${fallbackPath}`;
     if (code === 'EACCES' || code === 'EPERM')
@@ -129,7 +131,12 @@ export async function handleFsLs(runtime, req) {
         });
     }
     catch (err) {
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: fsErrorMessage(err, dirPath) });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: fsErrorMessage(err, dirPath),
+        });
     }
 }
 export async function handleFsRead(runtime, req) {
@@ -221,7 +228,12 @@ export async function handleFsWrite(runtime, req) {
     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' });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'path and content are required',
+        });
         return;
     }
     const resolved = runtime.resolveAuthorizedPath(requestedPath, rootPath);
@@ -253,7 +265,12 @@ export async function handleFsRename(runtime, req) {
     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' });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'path and newName are required',
+        });
         return;
     }
     if (!isSafeRenameName(newName)) {
@@ -307,7 +324,12 @@ export async function handleFsExportMarkdownPdf(runtime, req) {
         return;
     }
     if (!/\.mdx?$/i.test(resolved.path)) {
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Only Markdown files can be exported to PDF' });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'Only Markdown files can be exported to PDF',
+        });
         return;
     }
     const outputPath = defaultPdfOutputPath(resolved.path);
@@ -333,6 +355,16 @@ export async function handleFsExportMarkdownPdf(runtime, req) {
         });
     }
     catch (err) {
+        if (err instanceof MarkdownPdfBrowserMissingError) {
+            runtime.client.sendRes({
+                type: 'res',
+                id: req.id,
+                ok: false,
+                error: 'This machine needs the PDF export component before Markdown files can be exported to PDF.',
+                payload: err.setup,
+            });
+            return;
+        }
         runtime.client.sendRes({
             type: 'res',
             id: req.id,
@@ -344,7 +376,12 @@ export async function handleFsExportMarkdownPdf(runtime, req) {
 export async function handleFsTransfer(runtime, req) {
     const { name, targetPath, data, direct } = req.params;
     if (!name || !data) {
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'name and data are required' });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'name and data are required',
+        });
         return;
     }
     try {
@@ -371,9 +408,14 @@ export async function handleFsTransferStart(runtime, req) {
     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;
+    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' });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'name and totalSize are required',
+        });
         return;
     }
     try {
@@ -390,11 +432,21 @@ export async function handleFsTransferStart(runtime, req) {
         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' });
+                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}` });
+                runtime.client.sendRes({
+                    type: 'res',
+                    id: req.id,
+                    ok: false,
+                    error: `Too many files: ${manifest.length}`,
+                });
                 return;
             }
             const folderName = path.basename(transferName);
@@ -405,7 +457,12 @@ export async function handleFsTransferStart(runtime, req) {
             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 });
+                runtime.client.sendRes({
+                    type: 'res',
+                    id: req.id,
+                    ok: false,
+                    error: checkedTargetDir.error,
+                });
                 return;
             }
             const seen = new Set();
@@ -413,32 +470,62 @@ export async function handleFsTransferStart(runtime, req) {
             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}` });
+                    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}` });
+                    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}` });
+                    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` });
+                    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 });
+                    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 });
+                files.set(item.relativePath, {
+                    relativePath: item.relativePath,
+                    tempPath,
+                    targetPath: checkedFinalPath.path,
+                    size: item.size,
+                });
             }
             runtime.pendingTransfers.set(transferId, {
                 tempPath: '',
@@ -449,13 +536,23 @@ export async function handleFsTransferStart(runtime, req) {
                 targetDir: checkedTargetDir.path,
                 files,
             });
-            runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { transferId, path: checkedTargetDir.path } });
+            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(transferName));
         fs.writeFileSync(tempPath, Buffer.alloc(0));
-        runtime.pendingTransfers.set(transferId, { tempPath, targetPath: finalPath, totalSize, kind: 'file' });
+        runtime.pendingTransfers.set(transferId, {
+            tempPath,
+            targetPath: finalPath,
+            totalSize,
+            kind: 'file',
+        });
         runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { transferId } });
     }
     catch (err) {
@@ -479,7 +576,12 @@ export async function handleFsTransferChunk(runtime, req) {
         }
         const buffer = Buffer.from(data, 'base64');
         if (offset < 0 || offset + buffer.length > target.size) {
-            runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Chunk exceeds declared size' });
+            runtime.client.sendRes({
+                type: 'res',
+                id: req.id,
+                ok: false,
+                error: 'Chunk exceeds declared size',
+            });
             return;
         }
         const fd = fs.openSync(target.tempPath, 'r+');
@@ -489,7 +591,12 @@ export async function handleFsTransferChunk(runtime, req) {
         finally {
             fs.closeSync(fd);
         }
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { written: buffer.length } });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: { written: buffer.length },
+        });
     }
     catch (err) {
         runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });
@@ -521,14 +628,24 @@ export async function handleFsTransferFinish(runtime, req) {
         }
         fs.renameSync(transfer.tempPath, transfer.targetPath);
         runtime.pendingTransfers.delete(transferId);
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { path: transfer.targetPath } });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: { path: transfer.targetPath },
+        });
     }
     catch {
         try {
             fs.copyFileSync(transfer.tempPath, transfer.targetPath);
             fs.unlinkSync(transfer.tempPath);
             runtime.pendingTransfers.delete(transferId);
-            runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { path: transfer.targetPath } });
+            runtime.client.sendRes({
+                type: 'res',
+                id: req.id,
+                ok: true,
+                payload: { path: transfer.targetPath },
+            });
         }
         catch (err) {
             runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });

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

@@ -2,4 +2,6 @@ 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 handleSkillDoctor(runtime: SessionManagerRuntime, req: ReqFrame): Promise<void>;
+export declare function handleSkillSetup(runtime: SessionManagerRuntime, req: ReqFrame): Promise<void>;
 export declare function handleSkillUse(runtime: SessionManagerRuntime, req: ReqFrame): Promise<void>;

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

@@ -1,6 +1,7 @@
 // @arch docs/features/skill-marketplace.md
 // @test src/__tests__/skill-registry.test.ts
-import { buildSkillUsePrompt, installSkillFromUrl, listInstalledSkills } from '../../skills/registry.js';
+import { buildSkillUsePrompt, getInstalledSkill, installSkillFromUrl, listInstalledSkills, updateInstalledSkillSetup, } from '../../skills/registry.js';
+import { runSkillDoctor, runSkillSetup, summarizeSetupStatus } from '../../skills/setup.js';
 export async function handleSkillList(runtime, req) {
     runtime.client.sendRes({
         type: 'res',
@@ -23,6 +24,76 @@ export async function handleSkillInstall(runtime, req) {
         payload: { skill: installed },
     });
 }
+export async function handleSkillDoctor(runtime, req) {
+    const skillId = typeof req.params.skillId === 'string' ? req.params.skillId : '';
+    const doctorId = typeof req.params.doctorId === 'string' ? req.params.doctorId : undefined;
+    if (!skillId) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'skillId is required' });
+        return;
+    }
+    if (!getInstalledSkill(skillId)) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: `Skill not installed: ${skillId}`,
+        });
+        return;
+    }
+    const doctorResults = await runSkillDoctor(skillId, doctorId);
+    const setupStatus = summarizeSetupStatus(doctorResults);
+    updateInstalledSkillSetup(skillId, { setupStatus, doctorResults });
+    runtime.client.sendRes({
+        type: 'res',
+        id: req.id,
+        ok: true,
+        payload: { skill: getInstalledSkill(skillId), setupStatus, doctorResults },
+    });
+}
+export async function handleSkillSetup(runtime, req) {
+    const skillId = typeof req.params.skillId === 'string' ? req.params.skillId : '';
+    const repairActionId = typeof req.params.repairActionId === 'string' ? req.params.repairActionId : '';
+    if (!skillId || !repairActionId) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'skillId and repairActionId are required',
+        });
+        return;
+    }
+    if (!getInstalledSkill(skillId)) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: `Skill not installed: ${skillId}`,
+        });
+        return;
+    }
+    try {
+        const result = await runSkillSetup(skillId, repairActionId);
+        updateInstalledSkillSetup(skillId, {
+            setupStatus: result.status,
+            doctorResults: result.doctorResults,
+        });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: result.status === 'ready',
+            payload: { skill: getInstalledSkill(skillId), ...result },
+            error: result.status === 'ready' ? undefined : result.message,
+        });
+    }
+    catch (err) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 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();

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

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

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

@@ -0,0 +1,60 @@
+// @arch docs/architecture/cli/daemon.md#会话管理
+// @test src/__tests__/session-manager.test.ts
+import { createAgent } from '../../agents/adapter.js';
+import { buildManagedAgentEnv } from '../../agents/config-status.js';
+function cleanString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+export async function handleSessionTitleSet(runtime, req) {
+    const params = req.params;
+    const sessionId = cleanString(params.sessionId);
+    const title = cleanString(params.title);
+    const agentSessionId = cleanString(params.agentSessionId);
+    const agentType = cleanString(params.agentType);
+    const workDir = cleanString(params.workDir) || process.cwd();
+    if (!sessionId || !title) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'sessionId and title are required',
+        });
+        return;
+    }
+    if (agentType !== 'codex' || !agentSessionId) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: { skipped: true },
+        });
+        return;
+    }
+    const active = runtime.sessions.get(sessionId);
+    if (active?.agentType === 'codex' && active.adapter.setTitle) {
+        await active.adapter.setTitle(agentSessionId, title, active.workDir || workDir);
+        active.agentSessionId = agentSessionId;
+        active.lastActiveAt = Date.now();
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { synced: true } });
+        return;
+    }
+    const adapter = createAgent('codex');
+    if (!adapter?.setTitle) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: 'Codex adapter does not support title sync',
+        });
+        return;
+    }
+    adapter.configure?.({ sessionId, env: buildManagedAgentEnv('codex') });
+    try {
+        await adapter.start(sessionId, workDir, agentSessionId);
+        await adapter.setTitle(agentSessionId, title, workDir);
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: true, payload: { synced: true } });
+    }
+    finally {
+        await adapter.stop().catch(() => { });
+    }
+}

package/dist/src/session/manager.js

@@ -8,12 +8,13 @@ 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 { handleSessionTitleSet } from './handlers/title.js';
 import { cleanupPendingTransfers, handleFsLs, handleFsRead, handleFsRename, handleFsWrite, handleFsTransfer, handleFsTransferAbort, handleFsTransferChunk, handleFsTransferFinish, handleFsTransferStart, handleFsExportMarkdownPdf, } from './handlers/fs.js';
-import { handleSkillInstall, handleSkillList, handleSkillUse } from './handlers/skills.js';
-import { handleRegionProbe, handleRegionSwitch, handleUpgradeSetPolicy } from './handlers/control.js';
+import { handleSkillDoctor, handleSkillInstall, handleSkillList, handleSkillSetup, 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';
-import { createAuthorizedFsRoot, resolveAuthorizedPath, resolveSessionWorkDir } from '../fs/boundary.js';
+import { createAuthorizedFsRoot, resolveAuthorizedPath, resolveSessionWorkDir, } from '../fs/boundary.js';
 // Side-effect imports to register built-in agent adapters.
 import '../agents/claude.js';
 import '../agents/codex.js';
@@ -108,6 +109,9 @@ export class SessionManager {
                 case 'session.refresh':
                     await handleSessionRefresh(runtime, req);
                     break;
+                case 'session.title.set':
+                    await handleSessionTitleSet(runtime, req);
+                    break;
                 case 'fs.ls':
                     await handleFsLs(runtime, req);
                     break;
@@ -129,6 +133,12 @@ export class SessionManager {
                 case 'skill.install':
                     await handleSkillInstall(runtime, req);
                     break;
+                case 'skill.doctor':
+                    await handleSkillDoctor(runtime, req);
+                    break;
+                case 'skill.setup':
+                    await handleSkillSetup(runtime, req);
+                    break;
                 case 'skill.use':
                     await handleSkillUse(runtime, req);
                     break;
@@ -187,12 +197,19 @@ export class SessionManager {
                     await runtime.managerRuntime?.handleAppReq(req);
                     break;
                 default:
-                    this.client.sendRes({ type: 'res', id: req.id, ok: false, error: `Unknown method: ${req.method}` });
+                    this.client.sendRes({
+                        type: 'res',
+                        id: req.id,
+                        ok: false,
+                        error: `Unknown method: ${req.method}`,
+                    });
             }
         }
         catch (err) {
             this.client.sendRes({
-                type: 'res', id: req.id, ok: false,
+                type: 'res',
+                id: req.id,
+                ok: false,
                 error: err instanceof Error ? err.message : String(err),
             });
         }

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

@@ -1,8 +1,12 @@
-import type { InstalledShennianSkill } from '@shennian/wire';
+import type { InstalledShennianSkill, SkillDoctorResult, SkillSetupStatus } 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 updateInstalledSkillSetup(skillId: string, update: {
+    setupStatus?: SkillSetupStatus;
+    doctorResults?: SkillDoctorResult[];
+}): void;
 export declare function installSkillFromUrl(installUrl: string): Promise<InstalledShennianSkill>;
 export declare function buildSkillUsePrompt(skillId: string, workDir: string, attachments?: Array<{
     path: string;

package/dist/src/skills/registry.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveShennianPath } from '../config/index.js';
+import { runSkillDoctor, summarizeSetupStatus } from './setup.js';
 function safeSkillId(skillId) {
     const normalized = skillId.trim();
     if (!/^[a-z0-9][a-z0-9._-]{1,80}$/i.test(normalized)) {
@@ -39,7 +40,8 @@ export function getSkillDir(skillId) {
 }
 export function listInstalledSkills() {
     const dir = getSkillsDir();
-    return fs.readdirSync(dir, { withFileTypes: true })
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
         .map((entry) => {
         const skillPath = path.join(dir, entry.name);
@@ -47,11 +49,16 @@ export function listInstalledSkills() {
         const install = readJsonFile(path.join(skillPath, '.shennian-install.json'));
         if (!manifest?.id || !manifest.name)
             return null;
-        return {
+        const item = {
             ...manifest,
             installedAt: install?.installedAt ?? new Date(0).toISOString(),
             path: skillPath,
         };
+        if (install?.setupStatus)
+            item.setupStatus = install.setupStatus;
+        if (install?.doctorResults)
+            item.doctorResults = install.doctorResults;
+        return item;
     })
         .filter((item) => item != null)
         .sort((left, right) => left.name.localeCompare(right.name));
@@ -59,16 +66,23 @@ export function listInstalledSkills() {
 export function getInstalledSkill(skillId) {
     return listInstalledSkills().find((skill) => skill.id === skillId) ?? null;
 }
+export function updateInstalledSkillSetup(skillId, update) {
+    const skillDir = getSkillDir(skillId);
+    const installPath = path.join(skillDir, '.shennian-install.json');
+    const current = readJsonFile(installPath) ?? {};
+    fs.writeFileSync(installPath, JSON.stringify({ ...current, ...update, updatedAt: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+}
 async function fetchSkillBundle(installUrl) {
     if (!installUrl.startsWith('http://') && !installUrl.startsWith('https://')) {
-        return readJsonFile(path.resolve(installUrl)) ?? (() => {
-            throw new Error('Invalid skill bundle');
-        })();
+        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();
+    return (await res.json());
 }
 function writeBundleFile(skillDir, file) {
     const relativePath = assertSafeBundlePath(file.path);
@@ -91,7 +105,11 @@ export async function installSkillFromUrl(installUrl) {
     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 doctorResults = bundle.manifest.setup?.doctors?.length
+        ? (await Promise.all(bundle.manifest.setup.doctors.map((doctorId) => runSkillDoctor(bundle.manifest.id, doctorId)))).flat()
+        : [];
+    const setupStatus = summarizeSetupStatus(doctorResults);
+    fs.writeFileSync(path.join(skillDir, '.shennian-install.json'), JSON.stringify({ installedAt: new Date().toISOString(), installUrl, setupStatus, doctorResults }, null, 2) + '\n', 'utf8');
     const installed = getInstalledSkill(bundle.manifest.id);
     if (!installed)
         throw new Error('Skill installation did not complete');
@@ -113,7 +131,9 @@ export function buildSkillUsePrompt(skillId, workDir, attachments) {
         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');
+    ]
+        .filter(Boolean)
+        .join('\n');
 }
 export function buildInstalledSkillInstructions() {
     const skills = listInstalledSkills();

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

@@ -0,0 +1,11 @@
+import type { SkillDoctorResult, SkillRepairAction, SkillSetupStatus } from '@shennian/wire';
+export declare const MARKDOWN_PDF_REPAIR_ACTION: SkillRepairAction;
+export declare function markdownPdfRepairActions(): SkillRepairAction[];
+export declare function runMarkdownPdfBrowserDoctor(): Promise<SkillDoctorResult>;
+export declare function runSkillDoctor(skillId: string, doctorId?: string): Promise<SkillDoctorResult[]>;
+export declare function runSkillSetup(skillId: string, repairActionId: string): Promise<{
+    status: SkillSetupStatus;
+    doctorResults: SkillDoctorResult[];
+    message: string;
+}>;
+export declare function summarizeSetupStatus(doctorResults: SkillDoctorResult[]): SkillSetupStatus | undefined;

package/dist/src/skills/setup.js

@@ -0,0 +1,101 @@
+// @arch docs/features/skill-marketplace.md
+// @test src/__tests__/skill-registry.test.ts
+import { findChromiumExecutable, installManagedChromium, MARKDOWN_PDF_BROWSER_DOCTOR_ID, MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID, MARKDOWN_PDF_SKILL_ID, managedChromiumBrowsersPath, } from '../tools/markdown-to-pdf.js';
+export const MARKDOWN_PDF_REPAIR_ACTION = {
+    id: MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID,
+    label: 'Install PDF export component',
+    description: 'Download a Shennian-managed Chromium browser into ~/.shennian/browsers without using sudo.',
+    requiresNetwork: true,
+    requiresSudo: false,
+    downloadSizeMb: 180,
+};
+export function markdownPdfRepairActions() {
+    return [MARKDOWN_PDF_REPAIR_ACTION];
+}
+function result(input) {
+    return {
+        skillId: MARKDOWN_PDF_SKILL_ID,
+        doctorId: MARKDOWN_PDF_BROWSER_DOCTOR_ID,
+        status: input.status,
+        issues: input.issues,
+        checkedAt: input.checkedAt ?? new Date().toISOString(),
+        recommendedRepairActionId: MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID,
+        repairActions: markdownPdfRepairActions(),
+    };
+}
+export async function runMarkdownPdfBrowserDoctor() {
+    try {
+        const browserPath = await findChromiumExecutable();
+        return result({
+            status: 'ready',
+            issues: [
+                {
+                    code: 'MARKDOWN_PDF_BROWSER_READY',
+                    severity: 'info',
+                    message: `PDF export browser is ready: ${browserPath}`,
+                },
+            ],
+        });
+    }
+    catch {
+        return result({
+            status: 'needs_setup',
+            issues: [
+                {
+                    code: 'MARKDOWN_PDF_BROWSER_MISSING',
+                    severity: 'error',
+                    message: 'This machine needs a headless browser before Markdown files can be exported to PDF.',
+                    repairActionId: MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID,
+                },
+            ],
+        });
+    }
+}
+export async function runSkillDoctor(skillId, doctorId) {
+    if (skillId === MARKDOWN_PDF_SKILL_ID &&
+        (!doctorId || doctorId === MARKDOWN_PDF_BROWSER_DOCTOR_ID)) {
+        return [await runMarkdownPdfBrowserDoctor()];
+    }
+    return [
+        {
+            skillId,
+            doctorId: doctorId || 'unknown',
+            status: 'ready',
+            issues: [
+                {
+                    code: 'SKILL_DOCTOR_NOT_REQUIRED',
+                    severity: 'info',
+                    message: 'This skill does not declare a local environment doctor.',
+                },
+            ],
+            checkedAt: new Date().toISOString(),
+        },
+    ];
+}
+export async function runSkillSetup(skillId, repairActionId) {
+    if (skillId !== MARKDOWN_PDF_SKILL_ID ||
+        repairActionId !== MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID) {
+        throw new Error('Unsupported skill repair action');
+    }
+    await installManagedChromium();
+    const doctorResults = await runSkillDoctor(skillId, MARKDOWN_PDF_BROWSER_DOCTOR_ID);
+    const status = doctorResults.every((item) => item.status === 'ready') ? 'ready' : 'setup_failed';
+    return {
+        status,
+        doctorResults,
+        message: status === 'ready'
+            ? `PDF export component installed in ${managedChromiumBrowsersPath()}`
+            : 'PDF export component was installed, but the browser is still not ready. The system may need additional Linux libraries.',
+    };
+}
+export function summarizeSetupStatus(doctorResults) {
+    if (doctorResults.length === 0)
+        return undefined;
+    if (doctorResults.every((item) => item.status === 'ready'))
+        return 'ready';
+    if (doctorResults.some((item) => item.status === 'blocked'))
+        return 'blocked';
+    if (doctorResults.some((item) => item.status === 'setup_failed'))
+        return 'setup_failed';
+    return 'needs_setup';
+}

package/dist/src/tools/markdown-to-pdf.d.ts

@@ -1,3 +1,20 @@
+export declare const MARKDOWN_PDF_SKILL_ID = "markdown-to-pdf";
+export declare const MARKDOWN_PDF_BROWSER_DOCTOR_ID = "markdownPdf.browser";
+export declare const MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID = "markdownPdf.installManagedChromium";
+export declare const MARKDOWN_PDF_SETUP_REQUIRED_CODE = "SKILL_SETUP_REQUIRED";
+export declare const PLAYWRIGHT_VERSION_FOR_MANAGED_CHROMIUM = "1.59.1";
+export type MarkdownPdfSetupRequiredPayload = {
+    code: typeof MARKDOWN_PDF_SETUP_REQUIRED_CODE;
+    skillId: typeof MARKDOWN_PDF_SKILL_ID;
+    doctorId: typeof MARKDOWN_PDF_BROWSER_DOCTOR_ID;
+    recommendedRepairActionId: typeof MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID;
+};
+export declare function markdownPdfSetupRequiredPayload(): MarkdownPdfSetupRequiredPayload;
+export declare class MarkdownPdfBrowserMissingError extends Error {
+    readonly code = "SKILL_SETUP_REQUIRED";
+    readonly setup: MarkdownPdfSetupRequiredPayload;
+    constructor(message?: string);
+}
 export type MarkdownToPdfOptions = {
     outputPath?: string;
     title?: string;
@@ -16,5 +33,10 @@ export declare function renderMarkdownHtml(markdown: string, options?: {
     title?: string;
     sourceDir?: string;
 }): string;
+export declare function managedChromiumBrowsersPath(): string;
 export declare function findChromiumExecutable(explicitPath?: string): Promise<string>;
+export declare function installManagedChromium(): Promise<{
+    browsersPath: string;
+    output: string;
+}>;
 export declare function convertMarkdownToPdf(inputPath: string, options?: MarkdownToPdfOptions): Promise<MarkdownToPdfResult>;

package/dist/src/tools/markdown-to-pdf.js

@@ -6,7 +6,29 @@ import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { promisify } from 'node:util';
+import { resolveShennianPath } from '../config/index.js';
 const execFileAsync = promisify(execFile);
+export const MARKDOWN_PDF_SKILL_ID = 'markdown-to-pdf';
+export const MARKDOWN_PDF_BROWSER_DOCTOR_ID = 'markdownPdf.browser';
+export const MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID = 'markdownPdf.installManagedChromium';
+export const MARKDOWN_PDF_SETUP_REQUIRED_CODE = 'SKILL_SETUP_REQUIRED';
+export const PLAYWRIGHT_VERSION_FOR_MANAGED_CHROMIUM = '1.59.1';
+export function markdownPdfSetupRequiredPayload() {
+    return {
+        code: MARKDOWN_PDF_SETUP_REQUIRED_CODE,
+        skillId: MARKDOWN_PDF_SKILL_ID,
+        doctorId: MARKDOWN_PDF_BROWSER_DOCTOR_ID,
+        recommendedRepairActionId: MARKDOWN_PDF_MANAGED_CHROMIUM_ACTION_ID,
+    };
+}
+export class MarkdownPdfBrowserMissingError extends Error {
+    code = MARKDOWN_PDF_SETUP_REQUIRED_CODE;
+    setup = markdownPdfSetupRequiredPayload();
+    constructor(message = 'PDF export needs a local headless browser. Install the PDF export component, then retry.') {
+        super(message);
+        this.name = 'MarkdownPdfBrowserMissingError';
+    }
+}
 const FENCED_CODE_RE = /^```(\S*)\s*$/;
 function isWindowsAbsolutePath(value) {
     return /^[A-Za-z]:([\\/]|$)/.test(value) || /^\\\\[^\\]+\\[^\\]+/.test(value);
@@ -68,7 +90,11 @@ function renderTable(lines, sourceDir) {
     const separator = lines[1].trim();
     if (!/^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?$/.test(separator))
         return null;
-    const parseRow = (line) => line.trim().replace(/^\||\|$/g, '').split('|').map((cell) => cell.trim());
+    const parseRow = (line) => line
+        .trim()
+        .replace(/^\||\|$/g, '')
+        .split('|')
+        .map((cell) => cell.trim());
     const header = parseRow(lines[0]);
     const rows = lines.slice(2).map(parseRow);
     return [
@@ -226,6 +252,7 @@ ${body}
 function executableCandidates() {
     const envPath = process.env.SHENNIAN_CHROME_PATH;
     const candidates = envPath ? [envPath] : [];
+    candidates.push(...managedChromiumExecutableCandidates());
     if (process.platform === 'darwin') {
         candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser');
     }
@@ -244,6 +271,30 @@ function executableCandidates() {
     }
     return candidates;
 }
+export function managedChromiumBrowsersPath() {
+    return resolveShennianPath('browsers', 'ms-playwright');
+}
+function managedChromiumExecutableCandidates() {
+    const root = managedChromiumBrowsersPath();
+    if (!fs.existsSync(root))
+        return [];
+    const candidates = [];
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith('chromium-'))
+            continue;
+        const dir = path.join(root, entry.name);
+        if (process.platform === 'darwin') {
+            candidates.push(path.join(dir, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'));
+        }
+        else if (process.platform === 'win32') {
+            candidates.push(path.join(dir, 'chrome-win', 'chrome.exe'));
+        }
+        else {
+            candidates.push(path.join(dir, 'chrome-linux', 'chrome'));
+        }
+    }
+    return candidates;
+}
 export async function findChromiumExecutable(explicitPath) {
     const candidates = explicitPath ? [explicitPath] : executableCandidates();
     for (const candidate of candidates) {
@@ -260,7 +311,24 @@ export async function findChromiumExecutable(explicitPath) {
             // continue
         }
     }
-    throw new Error('No Chrome/Edge/Chromium executable found. Install Chrome/Edge/Chromium or set SHENNIAN_CHROME_PATH.');
+    throw new MarkdownPdfBrowserMissingError();
+}
+export async function installManagedChromium() {
+    const browsersPath = managedChromiumBrowsersPath();
+    fs.mkdirSync(browsersPath, { recursive: true });
+    const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    const { stdout, stderr } = await execFileAsync(npx, ['-y', `playwright@${PLAYWRIGHT_VERSION_FOR_MANAGED_CHROMIUM}`, 'install', 'chromium'], {
+        timeout: 10 * 60_000,
+        maxBuffer: 4 * 1024 * 1024,
+        env: {
+            ...process.env,
+            PLAYWRIGHT_BROWSERS_PATH: browsersPath,
+        },
+    });
+    return {
+        browsersPath,
+        output: [stdout, stderr].filter(Boolean).join('\n').slice(0, 20_000),
+    };
 }
 export async function convertMarkdownToPdf(inputPath, options = {}) {
     const resolvedInput = path.resolve(inputPath);
@@ -277,7 +345,9 @@ export async function convertMarkdownToPdf(inputPath, options = {}) {
         sourceDir: path.dirname(resolvedInput),
     });
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'shennian-mdpdf-'));
-    const htmlPath = options.keepHtml ? outputPath.replace(/\.pdf$/i, '.html') : path.join(tempDir, 'document.html');
+    const htmlPath = options.keepHtml
+        ? outputPath.replace(/\.pdf$/i, '.html')
+        : path.join(tempDir, 'document.html');
     fs.writeFileSync(htmlPath, html, 'utf8');
     const browserPath = await findChromiumExecutable(options.chromePath);
     const args = [
@@ -299,5 +369,10 @@ export async function convertMarkdownToPdf(inputPath, options = {}) {
     if (!fs.existsSync(outputPath) || fs.statSync(outputPath).size === 0) {
         throw new Error('PDF export failed: output file was not created');
     }
-    return { inputPath: resolvedInput, outputPath, htmlPath: options.keepHtml ? htmlPath : null, browserPath };
+    return {
+        inputPath: resolvedInput,
+        outputPath,
+        htmlPath: options.keepHtml ? htmlPath : null,
+        browserPath,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shennian",
-  "version": "0.2.68",
+  "version": "0.2.69",
   "description": "Shennian — AI Agent Control Plane CLI",
   "type": "module",
   "bin": {