@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/index.js

@@ -0,0 +1,276 @@
+/**
+ * LuaSkills in dsh. The runtime is not part of this package: the user installs it from the
+ * LuaSkills settings page, and from then on every enabled skill entry is a dsh tool, every
+ * loaded skill is in dsh's skill catalog, and the page manages installed skills and the Hub.
+ * The pages talk to the exact `/api/vulcan-luaskills/*` routes inside dsh's authenticated
+ * connection.
+ */
+import path from 'node:path';
+import { getDshRuntimeVersion } from '@deepseek-ai/dsh-app-boot';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { READ_ONLY_ENTRIES } from './constants.js';
+import { HubError, hubSkill, searchHub } from './hub.js';
+import { LuaSkillsRuntime, RuntimeError } from './runtime.js';
+import { SettingsError } from './settings.js';
+import { listInstalled } from './skills.js';
+import { helpTool, skillTool, toolName } from './tools.js';
+export const name = 'vulcan-luaskills';
+export const inject = ['skills', 'tools', 'workingDirectory'];
+/** Prefix of every page route, below dsh's `/api`. Also restated in `client/shared.ts`. */
+export const ROUTE_PREFIX = '/api/vulcan-luaskills/';
+/** Skill catalog name of the help tool, as VulcanCode names it. */
+const HELP_TOOL = 'luaskill_help';
+/** Between user skills (400) and bundled ones (600): a user's own skill of the same name wins. */
+const SKILL_RANK = 500;
+const PROVIDER = 'vulcan-luaskills';
+/** dsh skill names are kebab-case. */
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Hub skill ids are flat. */
+const HUB_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function apply(ctx) {
+    const dshVersion = getDshRuntimeVersion();
+    const runtime = new LuaSkillsRuntime(path.join(resolveDshHome(), 'vulcan-luaskills'), () => { onChange(); });
+    let disposers = [];
+    /** dsh tool name → LuaSkills canonical name, for entries that may change files. */
+    const writeTools = new Map();
+    /** Canonical name → dsh tool name, for the skill guides. */
+    let toolNames = new Map();
+    let catalog = [];
+    let skillControl;
+    let generation = 0;
+    let lastKind = runtime.current.kind;
+    const onChange = () => {
+        const kind = runtime.current.kind;
+        if ((kind === 'ready') !== (lastKind === 'ready'))
+            void refresh();
+        lastKind = kind;
+    };
+    /** Register the tools and catalog of the running engine, replacing the previous set whole. */
+    const refresh = async () => {
+        const mine = ++generation;
+        let entries = [];
+        let help = [];
+        if (runtime.current.kind === 'ready') {
+            try {
+                const engine = runtime.engine();
+                [entries, help] = await Promise.all([engine.entries(), engine.help()]);
+            }
+            catch (error) {
+                ctx.logger.warn(`cannot list LuaSkills entries: ${messageOf(error)}`);
+            }
+        }
+        if (mine !== generation)
+            return;
+        for (const dispose of disposers)
+            dispose();
+        disposers = [];
+        writeTools.clear();
+        toolNames = new Map();
+        catalog = help;
+        if (entries.length > 0 || help.length > 0) {
+            const ours = new Set();
+            const taken = (candidate) => ours.has(candidate) || ctx.tools.get(candidate) !== undefined;
+            const register = (definition) => {
+                try {
+                    disposers.push(ctx.tools.register(definition));
+                    ours.add(definition.name);
+                    return true;
+                }
+                catch (error) {
+                    ctx.logger.warn(`cannot register the LuaSkills tool ${definition.name}: ${messageOf(error)}`);
+                    return false;
+                }
+            };
+            register(helpTool(toolName(HELP_TOOL, taken), (skillId, flow) => renderHelp(skillId, flow)));
+            for (const entry of entries) {
+                const tool = toolName(entry.canonical_name, taken);
+                if (taken(tool)) {
+                    ctx.logger.warn(`the LuaSkills entry ${entry.canonical_name} has no free tool name`);
+                    continue;
+                }
+                if (!register(skillTool(tool, entry, toolHost)))
+                    continue;
+                toolNames.set(entry.canonical_name, tool);
+                if (!READ_ONLY_ENTRIES.has(entry.canonical_name))
+                    writeTools.set(tool, entry.canonical_name);
+            }
+        }
+        skillControl?.invalidate();
+    };
+    const toolHost = {
+        dshVersion,
+        workingDirectory: async (exec) => {
+            if (exec.agent === undefined)
+                throw new Error('this LuaSkills tool needs a session');
+            return await ctx.workingDirectory.ensure(exec.agent, exec.signal);
+        },
+        call: (canonical, args, context) => runtime.engine().call(canonical, args, context),
+    };
+    const renderHelp = async (skillId, flow) => {
+        const detail = await runtime.engine().helpDetail(skillId, flow);
+        if (detail === null)
+            throw new Error(flow === undefined ? `no LuaSkills skill ${skillId}` : `the skill ${skillId} has no topic ${flow}`);
+        return detail.content;
+    };
+    /** A skill's guide for dsh's catalog: its main help, its topics, and its tools' dsh names. */
+    const renderGuide = async (skillId) => {
+        const help = catalog.find(item => item.skill_id === skillId);
+        const parts = [await renderHelp(skillId, undefined)];
+        const helpName = ctx.tools.get(HELP_TOOL) !== undefined ? HELP_TOOL : `ls_${HELP_TOOL}`;
+        const topics = help?.flows.filter(flow => !flow.is_main) ?? [];
+        if (topics.length > 0) {
+            parts.push(`## Topics\n\nRead one with \`${helpName}\` (\`skill_id: "${skillId}"\`, \`flow\`):\n\n${topics.map(flow => `- \`${flow.flow_name}\`: ${flow.description}`).join('\n')}`);
+        }
+        const tools = [...toolNames].filter(([canonical]) => canonical.startsWith(`${skillId}-`));
+        if (tools.length > 0) {
+            parts.push(`## Tools\n\n${tools.map(([canonical, tool]) => `- \`${tool}\` (LuaSkills entry \`${canonical}\`)`).join('\n')}`);
+        }
+        return parts.join('\n\n');
+    };
+    ctx.skills.registerProvider((control) => {
+        skillControl = control;
+        const provider = {
+            name: PROVIDER,
+            list: () => Promise.resolve(catalog.filter(help => SKILL_NAME.test(help.skill_id)).map((help) => ({
+                name: help.skill_id,
+                description: help.main.description,
+                invocation: { modelInvocable: true, userInvocable: true },
+                provider: PROVIDER,
+                source: 'luaskills',
+                rank: SKILL_RANK,
+                locator: help.skill_id,
+            }))),
+            async get(candidate) {
+                const { rank: _rank, locator, ...summary } = candidate;
+                return { ...summary, content: await renderGuide(locator) };
+            },
+        };
+        return provider;
+    });
+    // Entries that may change files follow the session's sandbox: refused when read-only, run
+    // under full access, asked about otherwise.
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        const canonical = writeTools.get(exec.name);
+        if (canonical === undefined)
+            return next();
+        const session = exec.agent?.session;
+        const mode = ctx.get('sandboxPolicy')?.resolve(session === undefined ? {} : { session }).mode;
+        if (mode === 'read-only') {
+            return { kind: 'deny', reason: `The LuaSkills tool ${exec.name} may change files, and this session's sandbox is read-only.` };
+        }
+        if (mode === 'danger-full-access')
+            return next();
+        const downstream = await next();
+        if (downstream.kind !== 'allow')
+            return downstream;
+        return {
+            kind: 'ask',
+            reason: `The LuaSkills entry ${canonical} may change files.`,
+            displayReason: { en: `LuaSkills: ${canonical} may change files.`, zh: `LuaSkills：${canonical} 可能修改文件。` },
+        };
+    });
+    const skillRows = async () => {
+        const installed = listInstalled(runtime.runtimeRoot);
+        const loaded = new Set(catalog.map(help => help.skill_id));
+        const tools = [...toolNames];
+        return installed.map(skill => ({
+            ...skill,
+            loaded: loaded.has(skill.skillId),
+            tools: tools.filter(([canonical]) => canonical.startsWith(`${skill.skillId}-`)).map(([, tool]) => tool),
+        }));
+    };
+    const findSkill = (url) => {
+        const id = url.searchParams.get('id') ?? '';
+        const skill = listInstalled(runtime.runtimeRoot).find(item => item.skillId === id);
+        if (skill === undefined)
+            throw new RuntimeError(`no installed skill ${id}`, 'invalid_request');
+        return skill;
+    };
+    /** Run one skill change, then re-read the tools and catalog. */
+    const mutate = async (work) => {
+        try {
+            return await work();
+        }
+        finally {
+            await refresh();
+        }
+    };
+    const hubBase = () => runtime.settings.network.officialSkillHubBaseUrl;
+    const routes = [
+        ['GET', 'state', async () => runtime.view()],
+        ['POST', 'install', async () => { runtime.install(); }],
+        ['POST', 'install/cancel', async () => { runtime.cancel(); }],
+        ['POST', 'remove', () => runtime.remove()],
+        ['POST', 'restart', () => runtime.restart()],
+        ['POST', 'settings', async (request) => runtime.saveSettings(await readJson(request))],
+        ['GET', 'skills', () => skillRows()],
+        ['POST', 'skills/enabled', async (_request, url) => {
+                const skill = findSkill(url);
+                const enabled = url.searchParams.get('enabled');
+                if (enabled !== 'true' && enabled !== 'false')
+                    throw new RuntimeError('enabled must be true or false', 'invalid_request');
+                return await mutate(() => runtime.engine().setEnabled(skill.skillId, enabled === 'true'));
+            }],
+        ['POST', 'skills/update', async (_request, url) => {
+                const skill = findSkill(url);
+                if (skill.source === undefined)
+                    throw new RuntimeError(`${skill.skillId} was not installed from a source it can be updated from`, 'invalid_request');
+                const source = skill.source;
+                return await mutate(() => runtime.engine().update(skill.root, { skill_id: skill.skillId, source: source.locator, source_type: source.type }));
+            }],
+        ['POST', 'skills/uninstall', async (_request, url) => {
+                const skill = findSkill(url);
+                if (skill.root !== 'USER')
+                    throw new RuntimeError(`${skill.skillId} is a default skill; it can be disabled, not removed`, 'invalid_request');
+                return await mutate(() => runtime.engine().uninstall('USER', skill.skillId));
+            }],
+        ['POST', 'skills/install', async (_request, url) => {
+                const id = url.searchParams.get('id') ?? '';
+                if (!HUB_ID.test(id))
+                    throw new RuntimeError('id must be a LuaSkills Hub skill id', 'invalid_request');
+                return await mutate(() => runtime.engine().install('USER', { skill_id: null, source: id, source_type: 'official_hub' }));
+            }],
+        ['GET', 'hub/search', async (_request, url) => searchHub(hubBase(), url.searchParams.get('q') ?? '', url.searchParams.get('cursor'), url.searchParams.get('lang'))],
+        ['GET', 'hub/skill', async (_request, url) => hubSkill(hubBase(), url.searchParams.get('id') ?? '', url.searchParams.get('lang'))],
+    ];
+    ctx.inject(['connection'], (child) => {
+        for (const [method, route, handler] of routes) {
+            child.effect(() => child.connection.fetch.register({
+                path: `${ROUTE_PREFIX}${route}`,
+                methods: [method],
+                requestBody: 'buffered',
+                fetch: request => handle(handler, request),
+            }));
+        }
+    });
+    ctx.effect(() => {
+        runtime.boot().catch((error) => { ctx.logger.warn(`cannot start LuaSkills: ${messageOf(error)}`); });
+        return () => {
+            generation++;
+            void runtime.close();
+        };
+    }, 'vulcan-luaskills: runtime');
+}
+async function readJson(request) {
+    try {
+        return await request.json();
+    }
+    catch {
+        throw new RuntimeError('the request body must be JSON', 'invalid_request');
+    }
+}
+/** Answer one page request; failures carry their code, never a stack. */
+export async function handle(handler, request) {
+    try {
+        const value = await handler(request, new URL(request.url));
+        return Response.json({ ok: true, value: value ?? null }, { headers: { 'cache-control': 'no-store' } });
+    }
+    catch (error) {
+        const code = error instanceof RuntimeError || error instanceof SettingsError || error instanceof HubError ? error.code : 'failed';
+        const status = code === 'invalid_request' || code === 'invalid_settings' ? 400 : code === 'busy' ? 409 : code === 'not_ready' ? 503 : 500;
+        return Response.json({ ok: false, error: { code, message: messageOf(error) } }, { status, headers: { 'cache-control': 'no-store' } });
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/protocol.d.ts

@@ -0,0 +1,65 @@
+/** Messages between the Host plugin and its LuaSkills worker process. */
+export interface WorkerRequest {
+    readonly id: number;
+    readonly method: string;
+    readonly params: unknown;
+}
+export type WorkerReply = {
+    readonly id: number;
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly id: number;
+    readonly ok: false;
+    readonly error: string;
+};
+export type WorkerEvent = {
+    readonly event: 'ready';
+}
+/** Bytes of one runtime archive so far; `total` is null when the server sent no length. */
+ | {
+    readonly event: 'download';
+    readonly role: string;
+    readonly received: number;
+    readonly total: number | null;
+};
+/** One skill entry as the SDK lists it; only the fields read here. */
+export interface EntryDescriptor {
+    readonly canonical_name: string;
+    readonly skill_id: string;
+    readonly local_name: string;
+    readonly root_name: string;
+    readonly description: string;
+    readonly input_schema: unknown;
+}
+/** One help node of a skill. */
+export interface HelpNode {
+    readonly flow_name: string;
+    readonly description: string;
+    readonly related_entries: readonly string[];
+    readonly is_main: boolean;
+}
+/** One loaded skill's help, as the SDK lists it. */
+export interface SkillHelp {
+    readonly skill_id: string;
+    readonly skill_name: string;
+    readonly skill_version: string;
+    readonly root_name: string;
+    readonly main: HelpNode;
+    readonly flows: readonly HelpNode[];
+}
+export interface HelpDetail extends HelpNode {
+    readonly skill_id: string;
+    readonly content: string;
+}
+export interface InvocationResult {
+    readonly content: string;
+    readonly overflow_mode?: string | null;
+}
+/** Outcome of an install, update or uninstall. */
+export interface ApplyResult {
+    readonly skill_id: string;
+    readonly status: string;
+    readonly message: string;
+    readonly version?: string | null;
+}

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/protocol.js

@@ -0,0 +1,2 @@
+/** Messages between the Host plugin and its LuaSkills worker process. */
+export {};

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/runtime.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The LuaSkills runtime's lifecycle: absent until the user installs it, then installed in five
+ * steps with progress, started on every dsh start while its versions match, restarted when
+ * settings change, and removable. A failed or cancelled install leaves nothing half-installed.
+ *
+ * Layout below the plugin's folder in the dsh home:
+ * - `sdk/node_modules/` — the SDK and Koffi;
+ * - `runtime/` — the SDK's runtime root (core library, Lua packages, skill layers, state);
+ * - `installed.json` — written last; without it the runtime counts as not installed;
+ * - `settings.json` — the user's settings, kept when the runtime is removed.
+ */
+import { HUB_SITES } from './constants.js';
+import { LuaSkillsWorker } from './engine.js';
+import { type LuaSkillsSettings } from './settings.js';
+export interface Versions {
+    readonly sdk: string;
+    readonly luaskills: string;
+    readonly luaRuntime: string;
+}
+/** The versions this plugin installs. */
+export declare const PINNED: Versions;
+/** Install steps, in the order the SDK fetches the runtime archives. */
+export declare const PHASES: readonly ["sdk", "lua", "core", "engine", "skill"];
+export type Phase = (typeof PHASES)[number];
+export type RuntimeState = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'installing';
+    readonly phase: Phase;
+    readonly received: number;
+    readonly total: number | null;
+} | {
+    readonly kind: 'starting';
+} | {
+    readonly kind: 'ready';
+}
+/** Installed by another plugin version; it is not started until reinstalled. */
+ | {
+    readonly kind: 'outdated';
+    readonly installed: Versions;
+}
+/** `installed` says whether the runtime is on disk (the engine failed) or not (the install failed). */
+ | {
+    readonly kind: 'failed';
+    readonly error: string;
+    readonly installed: boolean;
+};
+/** Everything the pages show about the runtime, in one answer. */
+export interface RuntimeView {
+    readonly state: RuntimeState;
+    readonly location: string;
+    readonly sizeMb: number;
+    readonly versions: Versions;
+    readonly settings: LuaSkillsSettings;
+    /** `defaults` until the user saves once. */
+    readonly settingsSource: 'defaults' | 'saved' | 'invalid';
+    readonly settingsError?: string;
+    readonly hubSites: typeof HUB_SITES;
+}
+export declare class RuntimeError extends Error {
+    readonly code: 'not_ready' | 'busy' | 'invalid_request';
+    constructor(message: string, code?: 'not_ready' | 'busy' | 'invalid_request');
+}
+export declare class LuaSkillsRuntime {
+    readonly home: string;
+    private readonly changed;
+    readonly runtimeRoot: string;
+    private readonly nodeModules;
+    private readonly marker;
+    private readonly settingsFile;
+    private readonly scratch;
+    private state;
+    private worker;
+    private loaded;
+    private installing;
+    private closed;
+    /**
+     * @param home - this plugin's folder in the dsh home.
+     * @param changed - called after every state change.
+     */
+    constructor(home: string, changed: () => void);
+    get current(): RuntimeState;
+    view(): RuntimeView;
+    get settings(): LuaSkillsSettings;
+    /** The running engine. @throws RuntimeError when it is not ready. */
+    engine(): LuaSkillsWorker;
+    /** Start the installed runtime, if there is one this version can use. */
+    boot(): Promise<void>;
+    /** Begin installing in the background; progress shows in the state. */
+    install(): void;
+    /** Stop the running install; what it wrote is removed. */
+    cancel(): void;
+    /** Stop the engine and delete the runtime; settings are kept. */
+    remove(): Promise<void>;
+    /** Restart the engine with the current settings. */
+    restart(): Promise<void>;
+    /**
+     * Check and save the settings, then restart a running engine so they apply.
+     * @throws SettingsError when the value is not valid; nothing is written then.
+     */
+    saveSettings(value: unknown): Promise<void>;
+    close(): Promise<void>;
+    private set;
+    private sdkEntry;
+    private readMarker;
+    private spawn;
+    private stopWorker;
+    private start;
+    private wipe;
+    private runInstall;
+}