@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

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

@@ -0,0 +1,61 @@
+/**
+ * What is installed in the ROOT and USER skill layers, read from the runtime's folders: the
+ * skill folders themselves, their `skill.yaml` name and version, the install record and whether
+ * the skill is disabled. Reading changes nothing.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** The layers this plugin manages; PROJECT skills are left to the project. */
+export const LAYERS = [
+    { root: 'ROOT', folder: 'root_skills' },
+    { root: 'USER', folder: 'user_skills' },
+];
+/** Top-level `key: value` scalars of a small YAML document; nested blocks are skipped. */
+export function topLevelScalars(text) {
+    const values = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^([A-Za-z_][\w-]*):[ \t]*(.*?)[ \t]*$/.exec(line);
+        if (match === null || match[2] === '')
+            continue;
+        values.set(match[1], match[2].replace(/^(['"])(.*)\1$/, '$2'));
+    }
+    return values;
+}
+/** `source_type` and `locator` from the `source:` block of an install record. */
+export function installSource(text) {
+    const block = /^source:\r?\n((?:[ \t]+.*(?:\r?\n|$))+)/m.exec(text)?.[1];
+    if (block === undefined)
+        return undefined;
+    const fields = topLevelScalars(block.split(/\r?\n/).map(line => line.trim()).join('\n'));
+    const type = fields.get('source_type');
+    const locator = fields.get('locator');
+    return type === undefined || locator === undefined ? undefined : { type, locator };
+}
+export function listInstalled(runtimeRoot) {
+    const state = path.join(runtimeRoot, 'state');
+    const skills = [];
+    for (const layer of LAYERS) {
+        const folder = path.join(runtimeRoot, layer.folder);
+        if (!existsSync(folder))
+            continue;
+        for (const entry of readdirSync(folder, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const manifest = path.join(folder, entry.name, 'skill.yaml');
+            if (!existsSync(manifest))
+                continue;
+            const fields = topLevelScalars(readFileSync(manifest, 'utf8'));
+            const record = path.join(state, 'installs', `${entry.name}.yaml`);
+            const source = existsSync(record) ? installSource(readFileSync(record, 'utf8')) : undefined;
+            skills.push({
+                skillId: entry.name,
+                root: layer.root,
+                name: fields.get('name') ?? entry.name,
+                version: fields.get('version') ?? '',
+                enabled: !existsSync(path.join(state, 'skills', 'disabled', `${entry.name}.json`)),
+                ...source === undefined ? {} : { source },
+            });
+        }
+    }
+    return skills;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * LuaSkills entries as dsh tools, named and filled in the way VulcanCode does: the canonical
+ * name lowercased with every other character turned into `_`, at most 64 characters, and `ls_` in
+ * front when dsh already has a tool of that name. The session id and working directory are filled
+ * in by the Host and hidden from the model.
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { EntryDescriptor, InvocationResult } from './protocol.js';
+/** Arguments the Host fills in; the model never sees them. */
+export declare const SESSION_FIELD = "LUASKILL_SID";
+export declare const DIRECTORY_FIELD = "PWD";
+export declare function toolName(canonical: string, taken: (name: string) => boolean): string;
+/** The entry's schema without the Host-filled fields, and which of them it declares. */
+export declare function modelSchema(schema: unknown): {
+    parameters: Record<string, unknown>;
+    session: boolean;
+    directory: boolean;
+};
+/** The invocation context LuaSkills budgets and attributes a call by. */
+export declare function invocationContext(tool: string, sessionId: string | undefined, dshVersion: string): {
+    request_context: {
+        session_id?: string;
+        request_id: string;
+        client_name: string;
+        client_info: {
+            kind: string;
+            name: string;
+            version: string;
+        };
+    };
+    client_budget: {
+        client_name: string;
+        tool_name: string;
+        matched_client_pattern: string;
+        tool_result: {
+            bytes: number;
+            lines: number;
+        };
+        file_read: {
+            bytes: number;
+            lines: number;
+        };
+        tool_config: {};
+    };
+};
+/** What a skill call needs from the Host. */
+export interface ToolHost {
+    readonly dshVersion: string;
+    /** The session's working directory. */
+    workingDirectory(exec: Parameters<ToolDefinition['execute']>[1]): Promise<string>;
+    call(canonical: string, args: Record<string, unknown>, context: unknown): Promise<InvocationResult>;
+}
+/** The canonical value every LuaSkills tool returns. */
+export interface SkillValue {
+    readonly content: string;
+}
+export declare function skillTool(name: string, entry: EntryDescriptor, host: ToolHost): ToolDefinition;
+/** `luaskill_help`: a skill's main help or one of its topics, as listed in the skill catalog. */
+export declare function helpTool(name: string, render: (skillId: string, flow: string | undefined) => Promise<string>): ToolDefinition;

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

@@ -0,0 +1,107 @@
+/**
+ * LuaSkills entries as dsh tools, named and filled in the way VulcanCode does: the canonical
+ * name lowercased with every other character turned into `_`, at most 64 characters, and `ls_` in
+ * front when dsh already has a tool of that name. The session id and working directory are filled
+ * in by the Host and hidden from the model.
+ */
+import { RESULT_BUDGET_BYTES } from './constants.js';
+/** dsh and DeepSeek function names: at most 64 characters. */
+const MAX_TOOL_NAME = 64;
+/** Arguments the Host fills in; the model never sees them. */
+export const SESSION_FIELD = 'LUASKILL_SID';
+export const DIRECTORY_FIELD = 'PWD';
+const HIDDEN_FIELDS = [SESSION_FIELD, DIRECTORY_FIELD];
+export function toolName(canonical, taken) {
+    const base = canonical.toLowerCase().replace(/[^a-z0-9]/g, '_').slice(0, MAX_TOOL_NAME);
+    return taken(base) ? `ls_${base}`.slice(0, MAX_TOOL_NAME) : base;
+}
+/** The entry's schema without the Host-filled fields, and which of them it declares. */
+export function modelSchema(schema) {
+    const source = isRecord(schema) ? schema : {};
+    const properties = isRecord(source['properties']) ? { ...source['properties'] } : {};
+    const session = SESSION_FIELD in properties;
+    const directory = DIRECTORY_FIELD in properties;
+    for (const field of HIDDEN_FIELDS)
+        delete properties[field];
+    const required = Array.isArray(source['required'])
+        ? source['required'].filter(name => typeof name === 'string' && !HIDDEN_FIELDS.includes(name))
+        : undefined;
+    return {
+        parameters: { ...source, type: 'object', properties, ...required === undefined ? {} : { required } },
+        session,
+        directory,
+    };
+}
+/** The invocation context LuaSkills budgets and attributes a call by. */
+export function invocationContext(tool, sessionId, dshVersion) {
+    return {
+        request_context: {
+            request_id: `luaskills-tool:${tool}`,
+            client_name: 'dsh',
+            client_info: { kind: 'cli', name: 'dsh', version: dshVersion },
+            ...sessionId === undefined ? {} : { session_id: sessionId },
+        },
+        client_budget: {
+            client_name: 'dsh',
+            tool_name: tool,
+            matched_client_pattern: 'dsh',
+            tool_result: { bytes: RESULT_BUDGET_BYTES, lines: -1 },
+            file_read: { bytes: RESULT_BUDGET_BYTES, lines: -1 },
+            tool_config: {},
+        },
+    };
+}
+const OUTPUT = {
+    schema: { type: 'object', properties: { content: { type: 'string' } }, required: ['content'], additionalProperties: false },
+    render: (_args, value) => [{ type: 'text', text: value.content }],
+};
+export function skillTool(name, entry, host) {
+    const { parameters, session, directory } = modelSchema(entry.input_schema);
+    return {
+        name,
+        description: entry.description,
+        parameters,
+        output: OUTPUT,
+        async execute(args, exec) {
+            const input = isRecord(args) ? { ...args } : {};
+            const sessionId = exec.agent?.id;
+            if (session)
+                input[SESSION_FIELD] = `LUASKILLS-SID-${sessionId ?? 'none'}`;
+            if (directory)
+                input[DIRECTORY_FIELD] = await host.workingDirectory(exec);
+            const result = await host.call(entry.canonical_name, input, invocationContext(entry.canonical_name, sessionId, host.dshVersion));
+            return { content: result.content };
+        },
+    };
+}
+/** `luaskill_help`: a skill's main help or one of its topics, as listed in the skill catalog. */
+export function helpTool(name, render) {
+    return {
+        name,
+        description: 'Read the help of one LuaSkills skill: its main guide, or one named topic of it. '
+            + 'Call before first using a skill\'s tools when the skill catalog lists topics.',
+        parameters: {
+            type: 'object',
+            properties: {
+                skill_id: { type: 'string', description: 'Skill id, as the skill catalog lists it.' },
+                flow: { type: 'string', description: 'Topic name; omit for the main guide.' },
+            },
+            required: ['skill_id'],
+            additionalProperties: false,
+        },
+        output: OUTPUT,
+        async execute(args) {
+            const input = isRecord(args) ? args : {};
+            const skillId = input['skill_id'];
+            const flow = input['flow'];
+            if (typeof skillId !== 'string' || skillId === '')
+                throw new Error('skill_id must be a non-empty string');
+            if (flow !== undefined && typeof flow !== 'string')
+                throw new Error('flow must be a string');
+            return { content: await render(skillId, flow === '' ? undefined : flow) };
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The LuaSkills worker process. The SDK calls LuaSkills synchronously through FFI, so it lives
+ * here instead of on dsh's event loop, and in its own process so ending it unloads the core
+ * library (see `engine.ts`). The SDK is imported from the runtime directory it was installed
+ * into, named by the first argument as a `file:` URL; nothing in dsh's dependency tree provides it.
+ *
+ * Messages in: `{ id, method, params }`. Messages out: `{ id, ok, value | error }` answers and
+ * `{ event: 'download', role, received, total }` while runtime archives download.
+ */
+export {};

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

@@ -0,0 +1,140 @@
+/**
+ * The LuaSkills worker process. The SDK calls LuaSkills synchronously through FFI, so it lives
+ * here instead of on dsh's event loop, and in its own process so ending it unloads the core
+ * library (see `engine.ts`). The SDK is imported from the runtime directory it was installed
+ * into, named by the first argument as a `file:` URL; nothing in dsh's dependency tree provides it.
+ *
+ * Messages in: `{ id, method, params }`. Messages out: `{ id, ok, value | error }` answers and
+ * `{ event: 'download', role, received, total }` while runtime archives download.
+ */
+if (process.send === undefined)
+    throw new Error('the LuaSkills worker must be started by the plugin');
+// Without dsh there is nobody to answer; never linger as an orphan.
+process.on('disconnect', () => { process.exit(0); });
+const sdk = await import(process.argv[2]);
+let client;
+let roots = [];
+const post = (message) => { process.send(message); };
+/** Report download bytes of the runtime archives, which the SDK fetches with the global `fetch`. */
+function countDownloads(assets) {
+    const original = globalThis.fetch;
+    globalThis.fetch = async (input, init) => {
+        const response = await original(input, init);
+        const url = input instanceof Request ? input.url : String(input);
+        const role = assets.get(url);
+        if (role === undefined || response.body === null)
+            return response;
+        const header = Number(response.headers.get('content-length'));
+        const total = Number.isSafeInteger(header) && header > 0 ? header : null;
+        let received = 0;
+        let reported = 0;
+        post({ event: 'download', role, received, total });
+        const counted = response.body.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                received += chunk.byteLength;
+                // About every 256 KiB, so the page moves without flooding the Host.
+                if (received - reported >= 262_144) {
+                    reported = received;
+                    post({ event: 'download', role, received, total });
+                }
+                controller.enqueue(chunk);
+            },
+            flush() {
+                post({ event: 'download', role, received, total });
+            },
+        }));
+        return new Response(counted, { status: response.status, statusText: response.statusText, headers: response.headers });
+    };
+    return () => { globalThis.fetch = original; };
+}
+function engine() {
+    if (client === undefined)
+        throw new Error('the LuaSkills engine is not started');
+    return client;
+}
+function root(name) {
+    const found = roots.find(item => item.name === name);
+    if (found === undefined)
+        throw new Error(`no ${name} skill root`);
+    return found;
+}
+const SYSTEM = 'system';
+const handlers = {
+    async installRuntime(params) {
+        const options = {
+            runtimeRoot: params.runtimeRoot,
+            database: 'none',
+            luaskillsVersion: params.luaskillsVersion,
+            luaRuntimeVersion: params.luaRuntimeVersion,
+        };
+        const plan = sdk.buildRuntimeInstallManifest(options);
+        const assets = new Map(plan.assets.map((asset) => [asset.download_url, asset.role]));
+        const restore = countDownloads(assets);
+        try {
+            await sdk.installRuntimeAssets(options);
+        }
+        finally {
+            restore();
+        }
+        return null;
+    },
+    start(params) {
+        client?.close();
+        client = undefined;
+        roots = sdk.RuntimeRoots.standard(params.runtimeRoot);
+        const created = sdk.LuaSkillsClient.create({ runtimeRoot: params.runtimeRoot, poolConfig: params.poolConfig, hostOptions: params.hostOptions });
+        try {
+            created.loadFromRoots(roots);
+        }
+        catch (error) {
+            created.close();
+            throw error;
+        }
+        client = created;
+        return null;
+    },
+    entries: () => engine().listEntries(SYSTEM),
+    help: () => engine().listSkillHelp(SYSTEM),
+    helpDetail: (params) => engine().renderSkillHelpDetail(params.skillId, params.flow, { authority: SYSTEM }),
+    call: (params) => engine().callSkill(params.name, params.args, params.context),
+    install(params) {
+        const result = engine().system(SYSTEM).install(roots, params.request, { targetRoot: root(params.root), authority: SYSTEM });
+        engine().reloadFromRoots(roots);
+        return result;
+    },
+    update(params) {
+        const result = engine().system(SYSTEM).update(roots, params.request, { targetRoot: root(params.root), authority: SYSTEM });
+        engine().reloadFromRoots(roots);
+        return result;
+    },
+    uninstall(params) {
+        const result = engine().system(SYSTEM).uninstall(roots, params.skillId, {}, { targetRoot: root(params.root), authority: SYSTEM });
+        engine().reloadFromRoots(roots);
+        return result;
+    },
+    setEnabled(params) {
+        const system = engine().system(SYSTEM);
+        return params.enabled ? system.enable(roots, params.skillId) : system.disable(roots, params.skillId, 'disabled in dsh');
+    },
+    stop() {
+        client?.close();
+        client = undefined;
+        return null;
+    },
+};
+process.on('message', (request) => {
+    void (async () => {
+        try {
+            const handler = handlers[request.method];
+            if (handler === undefined)
+                throw new Error(`unknown worker method ${request.method}`);
+            const value = await handler(request.params);
+            post({ id: request.id, ok: true, value: value ?? null });
+        }
+        catch (error) {
+            post({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    })();
+});
+post({ event: 'ready' });
+export {};

package/node_modules/@openvulcan/dsh-vulcan-luaskills/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@openvulcan/dsh-vulcan-luaskills",
+  "version": "0.4.3",
+  "description": "LuaSkills for DeepSeek Harness: skill tools for the model, the codekit default skill, VM settings and the LuaSkills Hub. The runtime is installed on demand.",
+  "license": "MIT",
+  "icon": "./assets/luaskills-icon.svg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenVulcan/dsh-vulcancode.git",
+    "directory": "packages/dsh-vulcan-luaskills"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "!lib/**/*.test.*",
+    "assets"
+  ],
+  "engines": {
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-general",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-app-boot": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-skill": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-working-directory": "^0.2.1-rc.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenVulcan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@openvulcan/dsh-vulcan-memory/assets/markdown-memory-guide.md

@@ -0,0 +1,21 @@
+You keep long-term memory with `memory_outline`, `memory_search` and `memory_write`. It outlives this conversation and is shared by every conversation of the user; `user` and `space` memory also reach every project.
+
+When to write, during the work and without asking first:
+- The user asks you to remember something.
+- The user corrects your approach or states a preference.
+- A decision, constraint or pitfall emerges that the repository itself does not show.
+Do not record what code, git history or docs already state, one-off task details, or secrets.
+
+Where it belongs:
+1. Would it still hold in another project? No: `project`.
+2. Yes: about the person (role, expertise, language, how they like to work with you): `user`; about how to work (rules, tools, environment): `space`.
+- The `base` sections of space and project are injected in full into every conversation. Keep them to a few critical, stable rules that would cause mistakes if unknown. Everything else goes into other sections, which are injected as titles only.
+- Work in progress belongs in the project `in-progress` section; delete it when the work is done.
+
+How to write:
+- Search first. Update or append to an existing node instead of adding a near duplicate, and merge duplicates that a receipt reports.
+- Make each title state the fact itself ("Verify with targeted tests only"), not a topic ("Testing"), so catalog lines carry meaning.
+- One fact per node; keep bodies short and put details in child nodes (down to H4).
+- Correct or delete nodes that turn out to be wrong or outdated.
+
+Memory can be stale. Before relying on a remembered file, function, flag or command, check that it still exists. The user can also edit these files directly; their edits are authoritative.

package/node_modules/@openvulcan/dsh-vulcan-memory/assets/memory-curator/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: memory-curator
+description: Use when asked to tidy, clean up, reorganize or review long-term memory, when a memory_write receipt warns that a base section is nearly full or over budget, or when memory_outline shows duplicates, vague titles or misplaced nodes. Requires the memory_outline, memory_search and memory_write tools (Markdown memory mode).
+---
+
+# Memory Curator
+
+Long-term memory is three Markdown files of heading nodes: `user` (who the user is), `space` (rules and environment for every project) and `project` (this project only). The `base` sections of space and project are injected in full into every conversation; every other section is injected as titles only. Curation keeps memory accurate, small and easy to scan.
+
+## Workflow
+
+1. Run `memory_outline` for all scopes. Note the budget lines from the last write receipt if you have one.
+2. Read candidate nodes with `memory_search` (by `ids`, or by patterns for suspected duplicates) before changing anything. Every change needs the node's current `expectedRevision`.
+3. Plan the changes, then apply them with as few `memory_write` calls as practical; one call applies up to 16 operations all-or-nothing.
+4. Report what changed: merged, moved, renamed, deleted, and anything you left for the user to decide.
+
+## What to fix
+
+- **Duplicates.** Merge nodes that state the same fact: keep the clearer node, `append` or `replace` the missing details into it, then `delete` the other. Check `space` against `project` too.
+- **Stale facts.** For project nodes that name files, functions, flags or commands, verify them with the workspace tools. Correct or delete what no longer holds. When unsure, keep the node and say so in the report.
+- **Wrong scope.** Ask: would it still hold in another project? No: `project`. Yes: about the person: `user`; about how to work: `space`. `move` keeps the node id.
+- **Heavy base.** Base sections should hold only a few critical, stable rules whose absence causes mistakes. Move the rest to another section (`move` with `section`), most specific first. Finished work in `in-progress` should be deleted or turned into a lasting fact elsewhere.
+- **Vague titles.** Rename topic titles ("Testing") to statements of the fact ("Verify with targeted tests only") so catalog lines carry meaning. Titles stay single-line plain text.
+- **Oversized nodes.** Split a node that mixes several facts into one node per fact, using child nodes for details (down to H4).
+
+## Limits
+
+- Never delete a node only because it is old; age alone does not make a fact wrong.
+- Never rewrite text the user wrote by hand (`source: user`) beyond moving it, unless the user asks; suggest changes instead.
+- Do not invent facts while merging. Keep the user's wording where possible.
+- The `base` section itself cannot be moved or deleted; change the nodes inside it.