@anweat/dsh-browser 0.1.17 → 0.2.0-rc.1

package/lib/skill.js

@@ -0,0 +1,181 @@
+/**
+ * The bundled `dsh-browser` skill: usage guidance for the browser tools.
+ *
+ * The skill is registered with the Host's skill registry when that service
+ * exists. It must never be a hard dependency of the plugin: Cordis 4.0.4 treats
+ * every declared `inject` as required, so a missing `skills` service would hang
+ * the whole plugin. The plugin therefore asks for it through a scoped
+ * `ctx.inject(['skills'], …)` and works the same without it.
+ * @module dsh-browser/skill
+ */
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { SKILL_BODY_FILE_LIMIT } from "./prompt-limits.js";
+export const SKILL_NAME = 'dsh-browser';
+const PROVIDER_NAME = 'dsh-browser';
+/** Same rank the Host gives packaged skills (`BUNDLED_SKILL_RANK`). */
+const BUNDLED_SKILL_RANK = 600;
+/** `assets/skills/dsh-browser/`, resolved next to `src/` or the built `lib/`. */
+export const SKILL_DIR = fileURLToPath(new URL('../assets/skills/dsh-browser/', import.meta.url));
+/** Parse `name` and `description` out of a SKILL.md and return the body without the front matter. */
+export function parseSkillFile(raw) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!match)
+        throw new Error('SKILL.md is missing its front matter');
+    const field = (key) => {
+        const line = new RegExp(`^${key}:\\s*(.*)$`, 'm').exec(match[1]);
+        return line ? line[1].trim().replace(/^["']|["']$/g, '') : '';
+    };
+    return { name: field('name'), description: field('description'), body: match[2].replace(/^\s+/, '') };
+}
+export function readSkill(dir = SKILL_DIR) {
+    return parseSkillFile(fs.readFileSync(dir + 'SKILL.md', 'utf8'));
+}
+export { SKILL_BODY_FILE_LIMIT };
+/**
+ * Read a replacement skill body. A leading front matter block is dropped (the name and description come from the
+ * packaged file or `prompts.skill.description`). Never throws: a missing, unreadable, empty or oversized file is
+ * reported as a reason, and the caller falls back to the packaged body.
+ */
+export function loadSkillBodyFile(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        const code = error?.code;
+        return { ok: false, reason: code === 'ENOENT' ? `skill.bodyFile does not exist: ${file}` : `skill.bodyFile cannot be read (${code ?? 'error'}): ${file}` };
+    }
+    const front = /^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    const body = (front ? front[1] : raw).replace(/^\s+/, '');
+    if (body.trim() === '')
+        return { ok: false, reason: `skill.bodyFile is empty: ${file}` };
+    if (body.length > SKILL_BODY_FILE_LIMIT)
+        return { ok: false, reason: `skill.bodyFile is ${body.length} characters, over the limit of ${SKILL_BODY_FILE_LIMIT}: ${file}` };
+    return { ok: true, body };
+}
+/** What the skill says right now: the packaged file with the `prompts.skill` overrides applied. */
+export function currentSkill(dir = SKILL_DIR, prompts) {
+    const packaged = readSkill(dir);
+    const overrides = prompts?.current().skill;
+    if (!overrides)
+        return packaged;
+    let body = packaged.body;
+    if (overrides.bodyFile) {
+        const loaded = loadSkillBodyFile(overrides.bodyFile);
+        if (loaded.ok)
+            body = loaded.body;
+    }
+    if (overrides.append)
+        body = body.replace(/\s+$/, '') + '\n\n' + overrides.append;
+    return { name: packaged.name, description: overrides.description ?? packaged.description, body };
+}
+/** Identifies the skill text in force, so a change (config edit or an edited body file) can be noticed. */
+function skillSignature(prompts) {
+    const skill = prompts?.current().skill;
+    if (!skill)
+        return '';
+    let file = '';
+    if (skill.bodyFile) {
+        try {
+            const stat = fs.statSync(skill.bodyFile);
+            file = `${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            file = 'missing';
+        }
+    }
+    return JSON.stringify([skill.enabled, skill.description, skill.bodyFile, skill.append, file]);
+}
+/**
+ * A provider object shaped like the Host's `SkillProvider` (declared locally to avoid a build-time dependency).
+ * It reads the packaged file and the `prompts.skill` overrides on every call, so it is never stale.
+ */
+export function createSkillProvider(dir = SKILL_DIR, prompts) {
+    const resourceBase = { kind: 'directory', path: dir };
+    const invocation = { modelInvocable: true, userInvocable: true };
+    // Fail at creation, as before, when the packaged file is missing or malformed.
+    readSkill(dir);
+    return {
+        name: PROVIDER_NAME,
+        list: async () => {
+            const skill = currentSkill(dir, prompts);
+            return [{
+                    name: skill.name,
+                    description: skill.description,
+                    invocation,
+                    provider: PROVIDER_NAME,
+                    source: 'bundled',
+                    resourceBase,
+                    rank: BUNDLED_SKILL_RANK,
+                    locator: dir + 'SKILL.md',
+                }];
+        },
+        // Re-read on each load so edits to the packaged file are never stale.
+        get: async () => {
+            const current = currentSkill(dir, prompts);
+            return { name: current.name, description: current.description, invocation, provider: PROVIDER_NAME, source: 'bundled', resourceBase, content: current.body };
+        },
+    };
+}
+/**
+ * Register the skill when the Host provides a skill registry, and track whether
+ * it is registered so the index can fall back to its compact guide otherwise.
+ * With `prompts.skill.enabled=false` nothing is registered.
+ */
+export function registerSkillWhenAvailable(ctx, dir = SKILL_DIR, prompts) {
+    let available = false;
+    let sync = () => { };
+    ctx.inject(['skills'], (skillCtx) => {
+        let provider;
+        try {
+            provider = createSkillProvider(dir, prompts);
+        }
+        catch (error) {
+            skillCtx.logger?.(PROVIDER_NAME)?.warn?.('dsh-browser skill not registered: ' + String(error));
+            return;
+        }
+        let unregister;
+        let invalidate;
+        let signature = '';
+        let alive = true;
+        const register = () => {
+            const handle = skillCtx.skills.registerProvider((control) => {
+                invalidate = control?.invalidate?.bind(control);
+                return provider;
+            });
+            unregister = typeof handle === 'function' ? handle : () => { };
+            available = true;
+        };
+        const withdraw = () => {
+            try {
+                unregister?.();
+            }
+            catch { /* the Host may already have dropped it */ }
+            unregister = undefined;
+            invalidate = undefined;
+            available = false;
+        };
+        sync = () => {
+            if (!alive)
+                return;
+            const enabled = prompts?.current().skill.enabled !== false;
+            const next = skillSignature(prompts);
+            if (enabled && !available)
+                register();
+            else if (!enabled && available)
+                withdraw();
+            else if (available && next !== signature) {
+                try {
+                    invalidate?.();
+                }
+                catch { /* a stale handle is harmless */ }
+            }
+            signature = next;
+        };
+        sync();
+        skillCtx.effect?.(() => () => { alive = false; withdraw(); });
+    });
+    return { isAvailable: () => available, refresh: () => sync() };
+}
+//# sourceMappingURL=skill.js.map

package/lib/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}

package/lib/tool-defs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The model-facing definitions of the two `indexed` tools (L0): name, description and parameter schema.
+ *
+ * Kept apart from `tools.ts` so the plugin registers them, the budget check measures them, and
+ * `prompts:dump` lists their defaults from one definition. Only the description is configurable
+ * (`prompts.tools.<name>.description`); the parameter schema is structural and fixed.
+ * @module dsh-browser/tool-defs
+ */
+/** Default `browser_index` description. */
+export declare const DEFAULT_INDEX_DESCRIPTION = "Browser capability index. No args: groups and environment state. {group}: that group's actions. {action}: one action's full schema. {query}: keyword search.";
+/**
+ * Default `browser_call` description, WITHOUT the compliance notice. The notice is appended to whatever
+ * description is in force (configured or default): it states who is responsible for how the capability is used,
+ * so a deployment can reword the guidance around it but cannot drop it.
+ */
+export declare const DEFAULT_CALL_DESCRIPTION = "Run one browser action; browser_index shows the names. Args are validated server-side: INVALID_ARGS replies include the schema. Reply: {ok, action, executionStatus, result | error{code,message,hint}}.";
+export declare const INDEX_PARAMETERS: {
+    readonly group: {
+        readonly type: "string";
+        readonly description: "Group name, e.g. act.";
+    };
+    readonly action: {
+        readonly type: "string";
+        readonly description: "Action name, e.g. act.click.";
+    };
+    readonly query: {
+        readonly type: "string";
+        readonly description: "Keywords.";
+    };
+};
+export declare const CALL_PARAMETERS: {
+    readonly action: {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "Action name, e.g. target.open.";
+    };
+    readonly args: {
+        readonly type: "object";
+        readonly additionalProperties: true;
+        readonly description: "Arguments for the action.";
+    };
+};
+/** The two overridable tool names. */
+export declare const PROMPT_TOOL_NAMES: readonly ["browser_index", "browser_call"];
+export type PromptToolName = typeof PROMPT_TOOL_NAMES[number];
+export declare function indexDescription(override?: string): string;
+export declare function callDescription(override?: string): string;
+/** One tool as the host sends it to the model. */
+export interface ModelFacingTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+/**
+ * What the host sends to the model for the two indexed tools (name + description + parameters).
+ * The parameters are the JSON Schema form (`type`/`properties`/`required`), which is what is registered and what the
+ * model is billed for, not the shorthand map the tools are declared with.
+ */
+export declare function indexedToolDefinitions(overrides?: {
+    browser_index?: string;
+    browser_call?: string;
+}): ModelFacingTool[];
+/** Characters per token of the surface estimate. */
+export declare const CHARS_PER_TOKEN = 3.5;
+/** Estimated tokens of a character count. The one rounding rule for the settings card, `runtime.status` and the measure script. */
+export declare function estimateTokens(chars: number): number;
+/** Serialized size of tools as the host sends them: the one input of every L0 estimate. */
+export declare function modelFacingChars(tools: readonly {
+    name: string;
+    description?: unknown;
+    parameters?: unknown;
+}[]): number;

package/lib/tool-defs.js

@@ -0,0 +1,67 @@
+/**
+ * The model-facing definitions of the two `indexed` tools (L0): name, description and parameter schema.
+ *
+ * Kept apart from `tools.ts` so the plugin registers them, the budget check measures them, and
+ * `prompts:dump` lists their defaults from one definition. Only the description is configurable
+ * (`prompts.tools.<name>.description`); the parameter schema is structural and fixed.
+ * @module dsh-browser/tool-defs
+ */
+import { CALL_TOOL, INDEX_TOOL } from "./actions/registry.js";
+import { COMPLIANCE_NOTICE } from "./actions/shared.js";
+/** Default `browser_index` description. */
+export const DEFAULT_INDEX_DESCRIPTION = 'Browser capability index. No args: groups and environment state. {group}: that group\'s actions. {action}: one action\'s full schema. {query}: keyword search.';
+/**
+ * Default `browser_call` description, WITHOUT the compliance notice. The notice is appended to whatever
+ * description is in force (configured or default): it states who is responsible for how the capability is used,
+ * so a deployment can reword the guidance around it but cannot drop it.
+ */
+export const DEFAULT_CALL_DESCRIPTION = 'Run one browser action; browser_index shows the names. Args are validated server-side: INVALID_ARGS replies include the schema. Reply: {ok, action, executionStatus, result | error{code,message,hint}}.';
+export const INDEX_PARAMETERS = {
+    group: { type: 'string', description: 'Group name, e.g. act.' },
+    action: { type: 'string', description: 'Action name, e.g. act.click.' },
+    query: { type: 'string', description: 'Keywords.' },
+};
+export const CALL_PARAMETERS = {
+    action: { type: 'string', required: true, description: 'Action name, e.g. target.open.' },
+    args: { type: 'object', additionalProperties: true, description: 'Arguments for the action.' },
+};
+/** The two overridable tool names. */
+export const PROMPT_TOOL_NAMES = [INDEX_TOOL, CALL_TOOL];
+export function indexDescription(override) {
+    return override ?? DEFAULT_INDEX_DESCRIPTION;
+}
+export function callDescription(override) {
+    return `${(override ?? DEFAULT_CALL_DESCRIPTION).trimEnd()} ${COMPLIANCE_NOTICE}`;
+}
+/**
+ * The JSON Schema `defineTool` produces from a parameter shorthand map: `required: true` moves to a `required` list.
+ * Kept here, not imported, so the budget code does not need the tool runtime; test/l0-estimate.test.ts holds it equal
+ * to what `defineTool` really registers.
+ */
+function jsonSchemaOf(shorthand) {
+    const properties = Object.fromEntries(Object.entries(shorthand).map(([name, spec]) => [name, Object.fromEntries(Object.entries(spec).filter(([key]) => key !== 'required'))]));
+    const required = Object.entries(shorthand).filter(([, spec]) => spec.required === true).map(([name]) => name);
+    return { type: 'object', properties, ...required.length ? { required } : {} };
+}
+/**
+ * What the host sends to the model for the two indexed tools (name + description + parameters).
+ * The parameters are the JSON Schema form (`type`/`properties`/`required`), which is what is registered and what the
+ * model is billed for, not the shorthand map the tools are declared with.
+ */
+export function indexedToolDefinitions(overrides = {}) {
+    return [
+        { name: INDEX_TOOL, description: indexDescription(overrides.browser_index), parameters: jsonSchemaOf(INDEX_PARAMETERS) },
+        { name: CALL_TOOL, description: callDescription(overrides.browser_call), parameters: jsonSchemaOf(CALL_PARAMETERS) },
+    ];
+}
+/** Characters per token of the surface estimate. */
+export const CHARS_PER_TOKEN = 3.5;
+/** Estimated tokens of a character count. The one rounding rule for the settings card, `runtime.status` and the measure script. */
+export function estimateTokens(chars) {
+    return Math.round(chars / CHARS_PER_TOKEN);
+}
+/** Serialized size of tools as the host sends them: the one input of every L0 estimate. */
+export function modelFacingChars(tools) {
+    return tools.reduce((sum, tool) => sum + JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters }).length, 0);
+}
+//# sourceMappingURL=tool-defs.js.map

package/lib/tool-defs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-defs.js","sourceRoot":"","sources":["../src/tool-defs.ts"],"names":[],"mappings":"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"}

package/lib/tools.d.ts

@@ -1,11 +1,26 @@
 /**
- * Model-facing browser tools for dsh-browser: an interactive, multi-step
- * browser over a persistent page (open/click/type/scroll/read/screenshot/close)
- * plus status and chromium-install helpers.
+ * Model-facing tool surfaces for dsh-browser.
+ *
+ * Every capability is an action in the registry (`src/actions/`). This module
+ * only projects that registry into tools:
+ *
+ * - `indexed` (default): two small tools, `browser_index` for progressive
+ *   disclosure and `browser_call` to run an action. Constant, tiny context cost.
+ * - `flat`: one tool per usable action, named `browser_<group>_<action>`.
+ *   Every action is described up front; useful for comparison and debugging.
+ *
+ * Both surfaces dispatch through the same {@link runAction}, so validation,
+ * the result envelope, and the error codes are identical.
  * @module dsh-browser/tools
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { ResolvedConfig } from './config.ts';
 import type { BrowserService } from './browser-service.ts';
 import type { AutomationAssetStore } from './automation-assets.ts';
-export declare function registerTools(ctx: Context, config: ResolvedConfig, service: BrowserService, assets?: AutomationAssetStore): void;
+export interface ToolRuntime {
+    /** Whether the `dsh-browser` skill is currently registered; read at call time. */
+    skillAvailable?: () => boolean;
+    /** Bring the skill registration in line with the current `prompts.skill` (called at the start of each index/call). */
+    refreshSkill?: () => void;
+}
+export declare function registerTools(ctx: Context, config: ResolvedConfig, service: BrowserService, assets?: AutomationAssetStore, runtime?: ToolRuntime): void;