qlogicagent 2.13.3 → 2.13.5

package/dist/skills/portable-tool.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Content block returned by tool execution.
+ * Compatible with OpenAI / Anthropic content array format.
+ */
+import type { PermissionRiskLevel } from "../runtime/ports/index.js";
+export interface ToolContentBlock {
+    type: "text" | "image";
+    text?: string;
+    /**
+     * base64-encoded image data (only when type === "image").
+     * Used by browser screenshots and MCP tools where data is already in memory.
+     * The tool invoker promotes these to data-URL imageUrls for transport resolution.
+     * For file-based images, prefer returning localPath via PortableToolResult.imageUrls.
+     */
+    data?: string;
+    mimeType?: string;
+}
+export type LocaleCode = "zh-CN" | "en-US" | (string & {});
+export interface LocalizedText {
+    /**
+     * Stable translation key. UI clients decide the final language.
+     * Backends must not localize this string.
+     */
+    key: string;
+    /** Safe fallback for clients that do not have the key yet. */
+    fallback: string;
+    /** Optional bundled values for offline clients. */
+    values?: Partial<Record<LocaleCode, string>>;
+}
+export type CapabilityCategory = "orchestration" | "filesystem" | "web" | "search" | "memory" | "media" | "developer" | "mcp" | "automation" | "system" | "other";
+export type ToolRiskLevel = PermissionRiskLevel;
+/**
+ * Result of executing a portable tool.
+ */
+export interface PortableToolResult {
+    content: ToolContentBlock[];
+    /** Arbitrary structured metadata for the calling runtime. */
+    details?: Record<string, unknown>;
+    /**
+     * Local image file paths produced by this tool (e.g. read tool reading an image).
+     * Transport layer resolves these via FileUploadAdapter before sending to the LLM.
+     * This avoids loading large files into memory as base64.
+     */
+    imageUrls?: string[];
+}
+/**
+ * A runtime-agnostic tool definition.
+ *
+ * @typeParam TParams The expected parameter shape (for TypeScript consumers).
+ */
+export interface PortableTool<TParams = Record<string, unknown>> {
+    /** Unique tool name (e.g. "task", "memory"). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /**
+     * UI category declared by the tool registration.
+     * Clients must not infer this from name/description.
+     */
+    category?: CapabilityCategory;
+    /** UI-facing localized name. */
+    displayName?: LocalizedText;
+    /** UI-facing localized summary. The LLM-only description stays separate. */
+    displayDescription?: LocalizedText;
+    /** Tool description shown to the LLM. */
+    description: string;
+    /** JSON Schema object describing the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /**
+     * When true, the tool should NOT appear in the default tool list.
+     * The host injects it only for complex tasks (e.g. multi-step reasoning)
+     * or when explicitly activated via tool_search.
+     * This saves context tokens in simple conversations.
+     */
+    shouldDefer?: boolean;
+    /**
+     * Whether the tool can safely run concurrently with other tools.
+     * When true, the runtime may execute this tool in parallel with others.
+     * Default: false (sequential execution assumed).
+     */
+    isConcurrencySafe?: boolean;
+    /**
+     * Whether the tool only reads state and never mutates anything.
+     * Read-only tools can skip confirmation prompts in strict permission modes.
+     */
+    isReadOnly?: boolean;
+    /**
+     * Unified permission risk class.
+     * - read: no mutation, local or remote read-only operation
+     * - write: workspace-local mutation
+     * - system: shell/process/computer control or host-level mutation
+     * - external_egress: sends prompts/files/data to an external service
+     */
+    riskLevel?: ToolRiskLevel;
+    /**
+     * Whether the tool is currently available.
+     * CC parity: tools that return false are excluded from getTools().
+     * Default: true (always enabled).
+     */
+    isEnabled?: () => boolean;
+    /**
+     * Whether the tool performs destructive operations (delete, overwrite, etc.).
+     * CC parity: Tool.isDestructive field.
+     * Used by permission system to require confirmation.
+     */
+    isDestructive?: boolean;
+    /**
+     * Whether this tool deletes data (files, records, resources).
+     * Distinct from isDestructive (shell-level) — this is a semantic annotation
+     * on tools that explicitly delete. Downstream uses separate delete-specific
+     * confirmation logic from the general destructive-shell path.
+     */
+    isDelete?: boolean;
+    /**
+     * Whether this tool sends data to an external service (egress).
+     * When true, the tool is classified as external_egress risk.
+     */
+    isEgress?: boolean;
+    /**
+     * Whether egress carries user data (as opposed to read-only queries).
+     * Only meaningful when isEgress is true.
+     * Examples: file_upload (true), web_search (false).
+     */
+    egressCarriesData?: boolean;
+    /**
+     * Tool-specific permission check before execution.
+     * CC parity: Tool.checkPermissions — returns allow/deny with reason.
+     * Default (via buildTool): always allow, deferring to general permission system.
+     */
+    checkPermissions?: (params: TParams) => {
+        behavior: "allow" | "deny";
+        reason?: string;
+    };
+    /**
+     * Brief keyword hint for tool_search to match against
+     * (e.g. "return the final response as structured JSON").
+     */
+    searchHint?: string;
+    /**
+     * Maximum allowed content size in characters for the tool result.
+     * The runtime should truncate/reject results exceeding this.
+     */
+    maxResultSizeChars?: number;
+    /**
+     * Execute the tool.
+     *
+     * @param toolCallId - Unique ID for this tool invocation (for tracing).
+     * @param params     - Parsed parameters matching the JSON Schema.
+     * @param signal     - Optional abort signal.
+     * @returns Tool result with content blocks + optional details.
+     */
+    execute(toolCallId: string, params: TParams, signal?: AbortSignal): Promise<PortableToolResult>;
+}
+/**
+ * Build a complete PortableTool from a partial definition, filling safe defaults.
+ * CC parity: buildTool() factory in Tool.ts.
+ *
+ * Defaults (fail-closed where it matters):
+ * - isEnabled → true
+ * - isConcurrencySafe → false
+ * - isReadOnly → false
+ * - isDestructive → false
+ * - checkPermissions → { behavior: "allow" } (defer to general permission system)
+ */
+export declare function buildTool<TParams = Record<string, unknown>>(partial: PortableTool<TParams>): PortableTool<TParams>;

package/dist/skills/portable-tool.js

@@ -0,0 +1,34 @@
+// ============================================================
+// Portable Tool Contract — runtime-agnostic tool interface.
+//
+// This is the minimal tool definition that any agent runtime
+// (openclaw, Hub, Electron, third-party) can consume. It uses
+// plain JSON Schema objects instead of @sinclair/typebox so
+// there are zero external dependencies.
+//
+// Consumers wrap PortableTool into their own tool system:
+//   - openclaw → AgentTool<TSchema>  (via typebox adapter)
+//   - Hub      → hub-managed tool registration
+//   - Electron → desktop tool host
+// ============================================================
+/**
+ * Build a complete PortableTool from a partial definition, filling safe defaults.
+ * CC parity: buildTool() factory in Tool.ts.
+ *
+ * Defaults (fail-closed where it matters):
+ * - isEnabled → true
+ * - isConcurrencySafe → false
+ * - isReadOnly → false
+ * - isDestructive → false
+ * - checkPermissions → { behavior: "allow" } (defer to general permission system)
+ */
+export function buildTool(partial) {
+    return {
+        isEnabled: () => true,
+        isConcurrencySafe: false,
+        isReadOnly: false,
+        isDestructive: false,
+        checkPermissions: () => ({ behavior: "allow" }),
+        ...partial,
+    };
+}

package/dist/skills/skill-system/skill-frontmatter.d.ts

@@ -0,0 +1,19 @@
+import type { ParsedSkillFrontmatter, SkillInvocationPolicy, SkillMetadata } from "./skill-types.js";
+/**
+ * Parse a YAML-like frontmatter block into a flat key→value record.
+ * Uses a lightweight line parser to avoid a YAML library dependency.
+ */
+export declare function parseFrontmatter(content: string): ParsedSkillFrontmatter;
+/**
+ * Resolve structured metadata from the `metadata:` frontmatter field.
+ * Expects `metadata: {"openclaw": {...}}` (JSON format).
+ */
+export declare function resolveSkillMetadata(frontmatter: ParsedSkillFrontmatter): SkillMetadata | undefined;
+/**
+ * Resolve invocation policy from frontmatter fields.
+ */
+export declare function resolveSkillInvocationPolicy(frontmatter: ParsedSkillFrontmatter): SkillInvocationPolicy;
+/**
+ * Get the canonical key for a skill (metadata.skillKey or skill.name).
+ */
+export declare function resolveSkillKey(skillName: string, metadata?: SkillMetadata): string;

package/dist/skills/skill-system/skill-frontmatter.js

@@ -0,0 +1,344 @@
+//-------------------------------------------------------------------------
+// SKILL.md frontmatter parser — portable, zero external dependencies.
+// Mirrors openclaw/src/markdown/frontmatter.ts + src/agents/skills/frontmatter.ts
+// but without YAML library (uses simple line parser + JSON5-free metadata).
+//-------------------------------------------------------------------------
+//-------------------------------------------------------------------------
+// Block extraction
+//-------------------------------------------------------------------------
+function extractFrontmatterBlock(content) {
+    const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    if (!normalized.startsWith("---")) {
+        return undefined;
+    }
+    const endIndex = normalized.indexOf("\n---", 3);
+    if (endIndex === -1) {
+        return undefined;
+    }
+    return normalized.slice(4, endIndex);
+}
+//-------------------------------------------------------------------------
+// Line parser (handles both inline and multi-line values)
+//-------------------------------------------------------------------------
+function stripQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function extractMultiLineValue(lines, startIndex) {
+    const valueLines = [];
+    let i = startIndex + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.length > 0 && !line.startsWith(" ") && !line.startsWith("\t")) {
+            break;
+        }
+        valueLines.push(line);
+        i += 1;
+    }
+    return { value: valueLines.join("\n").trim(), linesConsumed: i - startIndex };
+}
+/**
+ * Parse a YAML-like frontmatter block into a flat key→value record.
+ * Uses a lightweight line parser to avoid a YAML library dependency.
+ */
+export function parseFrontmatter(content) {
+    const block = extractFrontmatterBlock(content);
+    if (!block) {
+        return {};
+    }
+    const result = {};
+    const lines = block.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const match = line.match(/^([\w-]+):\s*(.*)$/);
+        if (!match) {
+            i += 1;
+            continue;
+        }
+        const key = match[1];
+        const inlineValue = match[2].trim();
+        if (!key) {
+            i += 1;
+            continue;
+        }
+        // Check for multi-line value
+        if (!inlineValue && i + 1 < lines.length) {
+            const nextLine = lines[i + 1];
+            if (nextLine.startsWith(" ") || nextLine.startsWith("\t")) {
+                const { value, linesConsumed } = extractMultiLineValue(lines, i);
+                if (value) {
+                    result[key] = value;
+                }
+                i += linesConsumed;
+                continue;
+            }
+        }
+        const value = stripQuotes(inlineValue);
+        if (value) {
+            result[key] = value;
+        }
+        i += 1;
+    }
+    return result;
+}
+//-------------------------------------------------------------------------
+// Metadata resolver (from `metadata:` JSON block)
+//-------------------------------------------------------------------------
+function parseMetadataJson(raw) {
+    // Try direct JSON first: `metadata: {"openclaw": {...}}`
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            const obj = parsed;
+            const nested = obj["openclaw"];
+            if (nested && typeof nested === "object") {
+                return nested;
+            }
+            return obj;
+        }
+    }
+    catch {
+        // Not JSON — fall through to YAML-like parser
+    }
+    // Handle YAML-like multi-line: `key: value` per line
+    return parseYamlLikeMetadata(raw);
+}
+/**
+ * Parse simple YAML-like `key: value` lines where values may be JSON
+ * literals (objects, arrays, booleans, numbers) or plain strings.
+ */
+function parseYamlLikeMetadata(raw) {
+    const result = {};
+    let found = false;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const m = trimmed.match(/^([\w-]+):\s*(.+)$/);
+        if (!m)
+            continue;
+        const key = m[1];
+        const val = m[2].trim();
+        found = true;
+        // Try JSON parse for objects / arrays / booleans / numbers
+        try {
+            result[key] = JSON.parse(val);
+        }
+        catch {
+            // Plain string — normalise booleans / numbers
+            if (val === "true")
+                result[key] = true;
+            else if (val === "false")
+                result[key] = false;
+            else if (/^-?\d+(\.\d+)?$/.test(val))
+                result[key] = Number(val);
+            else
+                result[key] = val;
+        }
+    }
+    return found ? result : undefined;
+}
+function normalizeStringList(input) {
+    if (!input)
+        return [];
+    if (Array.isArray(input)) {
+        return input.map((v) => String(v).trim()).filter(Boolean);
+    }
+    if (typeof input === "string") {
+        return input
+            .split(",")
+            .map((v) => v.trim())
+            .filter(Boolean);
+    }
+    return [];
+}
+function parseBool(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const lower = value.toLowerCase().trim();
+    if (lower === "true" || lower === "1" || lower === "yes")
+        return true;
+    if (lower === "false" || lower === "0" || lower === "no")
+        return false;
+    return fallback;
+}
+//-------------------------------------------------------------------------
+// Install spec validation (safe input normalization)
+//-------------------------------------------------------------------------
+const BREW_FORMULA_PATTERN = /^[A-Za-z0-9][A-Za-z0-9@+._/-]*$/;
+const GO_MODULE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~+\-/]*(?:@[A-Za-z0-9][A-Za-z0-9._~+\-/]*)?$/;
+const UV_PACKAGE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._\-[\]=<>!~+,]*$/;
+const NPM_SPEC_PATTERN = /^(@[a-z0-9][\w.\-]*\/)?[a-z0-9][\w.\-]*(@[~^]?[\d.*]+[\w.\-+]*)?$/;
+function normalizeSafeBrewFormula(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const formula = raw.trim();
+    if (!formula || formula.startsWith("-") || formula.includes("\\") || formula.includes("..")) {
+        return undefined;
+    }
+    return BREW_FORMULA_PATTERN.test(formula) ? formula : undefined;
+}
+function normalizeSafeNpmSpec(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const spec = raw.trim();
+    if (!spec || spec.startsWith("-"))
+        return undefined;
+    return NPM_SPEC_PATTERN.test(spec) ? spec : undefined;
+}
+function normalizeSafeGoModule(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const mod = raw.trim();
+    if (!mod || mod.startsWith("-") || mod.includes("\\") || mod.includes("://"))
+        return undefined;
+    return GO_MODULE_PATTERN.test(mod) ? mod : undefined;
+}
+function normalizeSafeUvPackage(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const pkg = raw.trim();
+    if (!pkg || pkg.startsWith("-") || pkg.includes("\\") || pkg.includes("://"))
+        return undefined;
+    return UV_PACKAGE_PATTERN.test(pkg) ? pkg : undefined;
+}
+function normalizeSafeDownloadUrl(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const value = raw.trim();
+    if (!value || /\s/.test(value))
+        return undefined;
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+            return undefined;
+        return parsed.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseInstallSpec(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const raw = input;
+    const kindRaw = typeof raw.kind === "string" ? raw.kind : typeof raw.type === "string" ? raw.type : "";
+    const kind = kindRaw.trim().toLowerCase();
+    const ALLOWED_KINDS = ["brew", "node", "go", "uv", "download"];
+    if (!ALLOWED_KINDS.includes(kind))
+        return undefined;
+    const spec = { kind: kind };
+    if (typeof raw.id === "string")
+        spec.id = raw.id;
+    if (typeof raw.label === "string")
+        spec.label = raw.label;
+    const bins = normalizeStringList(raw.bins);
+    if (bins.length > 0)
+        spec.bins = bins;
+    const osList = normalizeStringList(raw.os);
+    if (osList.length > 0)
+        spec.os = osList;
+    // Kind-specific fields
+    const formula = normalizeSafeBrewFormula(raw.formula) ?? normalizeSafeBrewFormula(raw.cask);
+    if (formula)
+        spec.formula = formula;
+    if (kind === "node") {
+        const pkg = normalizeSafeNpmSpec(raw.package);
+        if (pkg)
+            spec.package = pkg;
+    }
+    else if (kind === "uv") {
+        const pkg = normalizeSafeUvPackage(raw.package);
+        if (pkg)
+            spec.package = pkg;
+    }
+    const mod = normalizeSafeGoModule(raw.module);
+    if (mod)
+        spec.module = mod;
+    const url = normalizeSafeDownloadUrl(raw.url);
+    if (url)
+        spec.url = url;
+    if (typeof raw.archive === "string")
+        spec.archive = raw.archive;
+    if (typeof raw.extract === "boolean")
+        spec.extract = raw.extract;
+    if (typeof raw.stripComponents === "number")
+        spec.stripComponents = raw.stripComponents;
+    if (typeof raw.targetDir === "string")
+        spec.targetDir = raw.targetDir;
+    // Validate required field per kind
+    if (kind === "brew" && !spec.formula)
+        return undefined;
+    if (kind === "node" && !spec.package)
+        return undefined;
+    if (kind === "go" && !spec.module)
+        return undefined;
+    if (kind === "uv" && !spec.package)
+        return undefined;
+    if (kind === "download" && !spec.url)
+        return undefined;
+    return spec;
+}
+//-------------------------------------------------------------------------
+// Public API
+//-------------------------------------------------------------------------
+/**
+ * Resolve structured metadata from the `metadata:` frontmatter field.
+ * Expects `metadata: {"openclaw": {...}}` (JSON format).
+ */
+export function resolveSkillMetadata(frontmatter) {
+    const raw = frontmatter["metadata"];
+    if (!raw)
+        return undefined;
+    const metadataObj = parseMetadataJson(raw);
+    if (!metadataObj)
+        return undefined;
+    const requiresRaw = typeof metadataObj.requires === "object" && metadataObj.requires !== null
+        ? metadataObj.requires
+        : undefined;
+    const requires = requiresRaw
+        ? {
+            bins: normalizeStringList(requiresRaw.bins),
+            anyBins: normalizeStringList(requiresRaw.anyBins),
+            env: normalizeStringList(requiresRaw.env),
+            config: normalizeStringList(requiresRaw.config),
+        }
+        : undefined;
+    const installRaw = Array.isArray(metadataObj.install)
+        ? metadataObj.install
+        : [];
+    const install = installRaw
+        .map((entry) => parseInstallSpec(entry))
+        .filter((entry) => Boolean(entry));
+    const osRaw = normalizeStringList(metadataObj.os);
+    return {
+        always: typeof metadataObj.always === "boolean" ? metadataObj.always : undefined,
+        emoji: typeof metadataObj.emoji === "string" ? metadataObj.emoji : undefined,
+        homepage: typeof metadataObj.homepage === "string" ? metadataObj.homepage : undefined,
+        skillKey: typeof metadataObj.skillKey === "string" ? metadataObj.skillKey : undefined,
+        primaryEnv: typeof metadataObj.primaryEnv === "string" ? metadataObj.primaryEnv : undefined,
+        os: osRaw.length > 0 ? osRaw : undefined,
+        category: typeof metadataObj.category === "string" ? metadataObj.category : undefined,
+        requires,
+        install: install.length > 0 ? install : undefined,
+    };
+}
+/**
+ * Resolve invocation policy from frontmatter fields.
+ */
+export function resolveSkillInvocationPolicy(frontmatter) {
+    return {
+        userInvocable: parseBool(frontmatter["user-invocable"], true),
+        disableModelInvocation: parseBool(frontmatter["disable-model-invocation"], false),
+    };
+}
+/**
+ * Get the canonical key for a skill (metadata.skillKey or skill.name).
+ */
+export function resolveSkillKey(skillName, metadata) {
+    return metadata?.skillKey ?? skillName;
+}

package/dist/skills/skill-system/skill-guard.d.ts

@@ -0,0 +1,23 @@
+import type { SkillFsDeps, SkillPathDeps, SkillScanFinding, SkillScanOptions, SkillScanSummary } from "./skill-types.js";
+/**
+ * Scan a source string for security findings.
+ * This is a pure function — no file I/O.
+ */
+export declare function scanSource(source: string, filePath: string): SkillScanFinding[];
+export interface SkillGuardDeps {
+    fs: SkillFsDeps;
+    path: SkillPathDeps;
+}
+/**
+ * Scan an entire skill directory for security issues.
+ * Returns a summary with per-file findings.
+ */
+export declare function scanSkillDirectory(deps: SkillGuardDeps, skillDir: string, opts?: SkillScanOptions): Promise<SkillScanSummary>;
+/**
+ * Quick check: does this source have any critical findings?
+ */
+export declare function hasCriticalFindings(source: string, filePath: string): boolean;
+/**
+ * Check if a file extension is scannable by the guard.
+ */
+export declare function isScannable(filePath: string, pathDeps: SkillPathDeps): boolean;