qlogicagent 2.13.4 → 2.13.5

package/dist/skills/permissions/rule-engine.js

@@ -0,0 +1,285 @@
+// Permission rule engine.
+//
+// User-visible modes are default, auto, and full_access.
+// Engine decisions are allow, ask, and deny.
+//
+// check() runs the workspace + danger decision pipeline:
+//   0. full_access → allow
+//   1. explicit rules (deny → session → allow; first match wins)
+//   3. deterministic high-risk floor (recursive/destructive) → ask(destructive)
+//   4. semantic high-risk candidates (in-workspace delete, data-carrying egress)
+//   5. mode gate (default + cross-workspace → ask(cross_workspace))
+//   6. allow
+import { resolveToolRisk } from "../../runtime/ports/tool-risk.js";
+// An all-false classification used when callers do not yet pass `op`
+// (incremental-build constraint: hook-runner is wired in a later task).
+const EMPTY_OP = {
+    targetPaths: [],
+    inWorkspace: false,
+    crossWorkspace: false,
+    isDelete: false,
+    isRecursiveDelete: false,
+    isEgress: false,
+    egressCarriesData: false,
+    isDestructive: false,
+    commandNetworkEgress: false,
+};
+// ── Rule Engine ─────────────────────────────────────────────
+export class PermissionRuleEngine {
+    mode;
+    rules;
+    sessionRules;
+    compiledPatterns;
+    constructor(config) {
+        this.mode = config.mode;
+        this.rules = [...config.rules];
+        this.sessionRules = [];
+        this.compiledPatterns = [];
+        this.recompile();
+    }
+    getMode() {
+        return this.mode;
+    }
+    setMode(mode) {
+        this.mode = mode;
+    }
+    getRules() {
+        return this.rules;
+    }
+    /** Replace all persistent rules at once (for settings hot-reload). Session rules are preserved. */
+    replaceRules(rules) {
+        this.rules = [...rules];
+        this.recompile();
+    }
+    addRule(rule) {
+        this.rules.push(rule);
+        this.recompile();
+    }
+    /** Add a session-scoped rule (e.g. "remember directory" approvals). */
+    addSessionRule(rule) {
+        this.sessionRules.push({
+            pattern: rule.pattern ?? "*",
+            pathPrefix: rule.pathPrefix,
+            behavior: rule.behavior ?? "allow",
+            source: "session",
+        });
+        this.recompile();
+    }
+    /** sandbox 可写根:rules + sessionRules 中 allow 且带 pathPrefix 的目录(去重)。 */
+    getAllowedWriteDirectories() {
+        const seen = new Set();
+        for (const r of [...this.rules, ...this.sessionRules]) {
+            if (r.behavior === "allow" && r.pathPrefix)
+                seen.add(r.pathPrefix);
+        }
+        return [...seen];
+    }
+    /**
+     * Workspace + danger decision pipeline.
+     *
+     * `op` is optional and defaults to an all-false classification so callers
+     * that have not yet been wired to the classifier keep compiling.
+     */
+    check(input, op = EMPTY_OP, ctx = {}) {
+        const { toolName } = input;
+        // 0: full_access (bypasses everything below, including extraRules)
+        if (this.mode === "full_access") {
+            return { behavior: "allow", decisionReason: { type: "mode", mode: "full_access" } };
+        }
+        // 0.5: caller-scoped extra rules (e.g. community-skill untrusted-code denials),
+        //      evaluated before the base rules, deny-first. This is the SAME single engine —
+        //      the trust-level restrictions are just additional rules active for this call,
+        //      NOT a second PermissionRuleEngine.
+        if (ctx.extraRules && ctx.extraRules.length > 0) {
+            const hit = this.matchRuleSet(ctx.extraRules, input, op, toolName, (rule) => rule.behavior === "deny");
+            if (hit)
+                return hit;
+        }
+        // 1: explicit rules (deny → session → allow order; first match wins).
+        //    pathPrefix rules match when ALL target paths fall under the prefix; else match by toolName glob.
+        //    requireOp rules additionally require the named op-classification flag.
+        const explicitDeny = this.matchCompiledRules(input, op, toolName, (rule) => rule.behavior === "deny");
+        if (explicitDeny)
+            return explicitDeny;
+        // 2: tool-declared risk floor. This merges PortableTool metadata with the
+        // operation classifier so manifest-level safety requirements cannot be
+        // downgraded by an ordinary-looking argument shape.
+        if (input.meta?.requiresApproval) {
+            return askResult(input, undefined, `Tool "${toolName}" requires confirmation`, undefined, undefined, { type: "tool_check", reason: "requiresApproval" });
+        }
+        const risk = resolveToolRisk(input.meta);
+        if (risk === "system") {
+            return askResult(input, undefined, `Tool "${toolName}" requires confirmation (system risk)`, undefined, undefined, { type: "tool_check", reason: "risk:system" });
+        }
+        if (risk === "external_egress") {
+            return askResult(input, "high_risk_egress", `Tool "${toolName}" may send data to an external service`, undefined, undefined, { type: "tool_check", reason: "risk:external_egress" });
+        }
+        if (ctx.extraRules && ctx.extraRules.length > 0) {
+            const hit = this.matchRuleSet(ctx.extraRules, input, op, toolName, (rule) => rule.behavior !== "deny");
+            if (hit)
+                return hit;
+        }
+        const explicitNonDeny = this.matchCompiledRules(input, op, toolName, (rule) => rule.behavior !== "deny");
+        if (explicitNonDeny)
+            return explicitNonDeny;
+        // 3: deterministic high-risk floor (always, except full_access handled above)
+        if (op.isRecursiveDelete || op.isDestructive) {
+            return askResult(input, "destructive", `Tool "${toolName}" 触发破坏性/递归操作,需确认`);
+        }
+        // 4: semantic high-risk candidates (both default & auto; hook-runner runs classifier)
+        if (op.isDelete && op.inWorkspace) {
+            return askResult(input, "high_risk_delete", `删除工作区内文件需确认`, "delete");
+        }
+        if (op.egressCarriesData) {
+            return askResult(input, "high_risk_egress", `向外发送数据需确认`, "egress");
+        }
+        // 5: mode gate
+        if (this.mode === "default" && op.crossWorkspace) {
+            const dir = op.targetPaths[0] ? dirOf(op.targetPaths[0]) : undefined;
+            return askResult(input, "cross_workspace", `跨工作区操作需确认`, undefined, dir ? { kind: "directory", path: dir } : undefined);
+        }
+        // 6: allow
+        return { behavior: "allow" };
+    }
+    /** Rebuild compiledPatterns: [persistent-deny] → [session] → [persistent non-deny]. */
+    recompile() {
+        const deny = this.rules.filter((r) => r.behavior === "deny");
+        const nonDeny = this.rules.filter((r) => r.behavior !== "deny");
+        const ordered = [...deny, ...this.sessionRules, ...nonDeny];
+        this.compiledPatterns = ordered.map((rule) => ({ rule, regex: globToRegex(rule.pattern) }));
+    }
+    matchCompiledRules(input, op, toolName, include) {
+        for (const { rule, regex } of this.compiledPatterns) {
+            if (!include(rule))
+                continue;
+            if (rule.requireOp && !op[rule.requireOp])
+                continue;
+            const hit = rule.pathPrefix
+                ? op.targetPaths.length > 0 && op.targetPaths.every((p) => withinPrefix(p, rule.pathPrefix))
+                : regex.test(toolName);
+            if (hit)
+                return ruleToResult(rule, input);
+        }
+        return null;
+    }
+    /**
+     * Match a caller-supplied rule set (deny-first) against this call, using the SAME
+     * matching semantics as the base rules (pathPrefix prefix-match, else toolName glob).
+     * Returns the first hit's result, or null if none match. Used for per-call scoped
+     * rules (community-skill turns) so trust-level restrictions stay in the one engine.
+     */
+    matchRuleSet(rules, input, op, toolName, include) {
+        const deny = rules.filter((r) => r.behavior === "deny");
+        const rest = rules.filter((r) => r.behavior !== "deny");
+        for (const rule of [...deny, ...rest]) {
+            if (!include(rule))
+                continue;
+            if (rule.requireOp && !op[rule.requireOp])
+                continue;
+            const hit = rule.pathPrefix
+                ? op.targetPaths.length > 0 && op.targetPaths.every((p) => withinPrefix(p, rule.pathPrefix))
+                : globToRegex(rule.pattern).test(toolName);
+            if (hit)
+                return ruleToResult(rule, input);
+        }
+        return null;
+    }
+}
+// ── Config Parser ───────────────────────────────────────────
+/**
+ * Parse permission config from Gateway-injected or local settings.
+ *
+ * Accepts the user-facing permission mode plus the persistent `rules` channel.
+ * Legacy top-level alias keys (allow/deny/ask arrays, default) are still rejected.
+ */
+export function parsePermissionConfig(raw) {
+    if (!raw || typeof raw !== "object") {
+        return { mode: "default", rules: [] };
+    }
+    const obj = raw;
+    rejectLegacyPermissionAliases(obj);
+    const mode = normalizePermissionMode(obj["mode"]).mode;
+    const rules = Array.isArray(obj["rules"])
+        ? obj["rules"].flatMap(parseRuleEntry)
+        : [];
+    return { mode, rules };
+}
+function parseRuleEntry(r) {
+    if (!r || typeof r !== "object")
+        return [];
+    const o = r;
+    const behavior = o.behavior;
+    if (behavior !== "allow" && behavior !== "deny" && behavior !== "ask")
+        return [];
+    const entry = { pattern: typeof o.pattern === "string" ? o.pattern : "*", behavior };
+    if (typeof o.pathPrefix === "string")
+        entry.pathPrefix = o.pathPrefix;
+    if (typeof o.reason === "string")
+        entry.reason = o.reason;
+    return [entry];
+}
+// ── Helpers ─────────────────────────────────────────────────
+function globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const regexStr = escaped.replace(/\*+/g, ".*");
+    return new RegExp(`^${regexStr}$`, "i");
+}
+function askResult(input, category, message, semanticCheck, rememberScope, decisionReason) {
+    return {
+        behavior: "ask",
+        message,
+        toolName: input.toolName,
+        input: input.arguments,
+        category,
+        semanticCheck,
+        rememberScope,
+        decisionReason,
+    };
+}
+function withinPrefix(p, prefix) {
+    const a = p.replace(/\\/g, "/").toLowerCase();
+    const b = prefix.replace(/\\/g, "/").toLowerCase();
+    return a === b || a.startsWith(b.endsWith("/") ? b : b + "/");
+}
+function dirOf(p) {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i > 0 ? p.slice(0, i) : p;
+}
+function ruleToResult(rule, input) {
+    const reason = { type: "rule", rule };
+    if (rule.behavior === "allow") {
+        return { behavior: "allow", decisionReason: reason };
+    }
+    if (rule.behavior === "deny") {
+        return {
+            behavior: "deny",
+            message: rule.reason ?? `Tool "${input.toolName}" denied by rule "${rule.pattern}"`,
+            decisionReason: reason,
+        };
+    }
+    return {
+        behavior: "ask",
+        message: rule.reason ?? `Tool "${input.toolName}" requires approval (rule "${rule.pattern}")`,
+        toolName: input.toolName,
+        input: input.arguments,
+        decisionReason: reason,
+    };
+}
+function normalizePermissionMode(value) {
+    if (value === "default" || value === "auto" || value === "full_access")
+        return { mode: value };
+    if (typeof value === "string") {
+        throw new Error(`Invalid permission mode: ${value}`);
+    }
+    return { mode: "default" };
+}
+function rejectLegacyPermissionAliases(obj) {
+    if ("default" in obj) {
+        throw new Error("Legacy permissions.default is not supported");
+    }
+    for (const behavior of ["allow", "deny", "ask"]) {
+        if (behavior in obj) {
+            throw new Error(`Legacy permission ${behavior} arrays are not supported`);
+        }
+    }
+}

package/dist/skills/permissions/settings-watcher.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Settings watcher for canonical qlogicagent permission settings.
+ *
+ * Only the `permissions` object is accepted. Removed top-level aliases such as
+ * `permissionMode`, `permissionRules`, and `defaultBehavior` must fail loudly.
+ */
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { PermissionRuleEnginePort } from "../../runtime/ports/index.js";
+export interface SettingsFile {
+    permissions?: unknown;
+}
+export interface SettingsWatcherDeps {
+    projectRoot: string;
+    ruleEngine: PermissionRuleEnginePort;
+    hooks?: HookRegistry;
+    log?: (msg: string) => void;
+}
+export declare function watchSettings(deps: SettingsWatcherDeps): () => void;
+export declare function loadInitialSettings(projectRoot: string, ruleEngine: PermissionRuleEnginePort): Promise<SettingsFile | null>;

package/dist/skills/permissions/settings-watcher.js

@@ -0,0 +1,121 @@
+/**
+ * Settings watcher for canonical qlogicagent permission settings.
+ *
+ * Only the `permissions` object is accepted. Removed top-level aliases such as
+ * `permissionMode`, `permissionRules`, and `defaultBehavior` must fail loudly.
+ */
+import { watch } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { getDefaultPathService } from "../../runtime/infra/default-path-service.js";
+import { parsePermissionConfig } from "./rule-engine.js";
+function getSettingsPath(projectRoot) {
+    return getDefaultPathService().getProjectSettingsPath(projectRoot);
+}
+async function readSettingsFile(filePath) {
+    try {
+        const content = await readFile(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function applySettings(settings, ruleEngine, hooks, log) {
+    let changed = false;
+    const permissions = resolvePermissionConfig(settings);
+    if (!permissions)
+        return;
+    if (permissions.mode !== ruleEngine.getMode()) {
+        ruleEngine.setMode(permissions.mode);
+        log?.(`settings: permission mode -> ${permissions.mode}`);
+        changed = true;
+    }
+    if (!sameRules(permissions.rules, ruleEngine.getRules())) {
+        ruleEngine.replaceRules(permissions.rules);
+        log?.(`settings: ${permissions.rules.length} permission rules loaded`);
+        changed = true;
+    }
+    if (changed && hooks) {
+        hooks.invoke("config.changed", {
+            sessionId: "",
+            key: "permissions",
+            oldValue: undefined,
+            newValue: settings,
+        }).catch(() => { });
+    }
+}
+export function watchSettings(deps) {
+    const settingsPath = getSettingsPath(deps.projectRoot);
+    let watcher = null;
+    let debounceTimer = null;
+    const reload = async () => {
+        const settings = await readSettingsFile(settingsPath);
+        if (settings) {
+            applySettings(settings, deps.ruleEngine, deps.hooks, deps.log);
+        }
+    };
+    reload().catch(() => { });
+    try {
+        watcher = watch(settingsPath, { persistent: false }, () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                reload().catch(() => { });
+            }, 200);
+        });
+        watcher.on("error", () => { });
+    }
+    catch {
+        // Settings files are created lazily.
+    }
+    return () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        watcher?.close();
+        watcher = null;
+    };
+}
+export async function loadInitialSettings(projectRoot, ruleEngine) {
+    const settingsPath = getSettingsPath(projectRoot);
+    const settings = await readSettingsFile(settingsPath);
+    if (settings) {
+        const permissions = resolvePermissionConfig(settings);
+        if (permissions) {
+            ruleEngine.setMode(permissions.mode);
+            ruleEngine.replaceRules(permissions.rules);
+        }
+    }
+    return settings;
+}
+function resolvePermissionConfig(settings) {
+    rejectLegacyTopLevelSettings(settings);
+    if (settings.permissions && typeof settings.permissions === "object") {
+        return parsePermissionConfig(settings.permissions);
+    }
+    return null;
+}
+function sameRules(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((rule, index) => {
+        const other = right[index];
+        return Boolean(other) &&
+            rule.pattern === other.pattern &&
+            rule.behavior === other.behavior &&
+            rule.reason === other.reason &&
+            rule.source === other.source;
+    });
+}
+function rejectLegacyTopLevelSettings(settings) {
+    const record = settings;
+    const legacyKeys = {
+        permissionMode: "permissions.mode",
+        permissionRules: "permissions.rules",
+        defaultBehavior: "permissions.defaultBehavior",
+    };
+    for (const [key, replacement] of Object.entries(legacyKeys)) {
+        if (key in record) {
+            throw new Error(`Legacy top-level ${key} is not supported; use ${replacement}`);
+        }
+    }
+}

package/dist/skills/permissions/types.d.ts

@@ -0,0 +1,2 @@
+export { PERMISSION_MODES, } from "../../runtime/ports/permission-contracts.js";
+export type { ApprovalRequest, ApprovalResponse, PermissionAllowResult, PermissionAskResult, PermissionBehavior, PermissionConfig, PermissionDecisionReason, PermissionDenyResult, PermissionEngineConfig, PermissionMode, PermissionRiskLevel, PermissionResult, PermissionRuleEntry, ToolPermissionCheckInput, } from "../../runtime/ports/permission-contracts.js";

package/dist/skills/permissions/types.js

@@ -0,0 +1 @@
+export { PERMISSION_MODES, } from "../../runtime/ports/permission-contracts.js";

package/dist/skills/plugins/index.d.ts

@@ -0,0 +1,2 @@
+export { PluginLoader, type PluginLoaderConfig } from "./plugin-loader.js";
+export { PLUGIN_HOOK_MAP, type PluginApi, type PluginHookPhase, type PluginModule, type LoadedPlugin, } from "./plugin-api.js";

package/dist/skills/plugins/index.js

@@ -0,0 +1,3 @@
+// Plugin system barrel exports
+export { PluginLoader } from "./plugin-loader.js";
+export { PLUGIN_HOOK_MAP, } from "./plugin-api.js";

package/dist/skills/plugins/plugin-api.d.ts

@@ -0,0 +1,38 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { HookPoint, HookHandler } from "../../contracts/hooks.js";
+import type { WorkspaceSkill } from "../skill-system/skill-types.js";
+export type PluginHookPhase = "preToolUse" | "postToolUse" | "onTurnStart" | "onTurnEnd" | "onSessionEnd";
+/** Map plugin hook phases to internal HookPoint names */
+export declare const PLUGIN_HOOK_MAP: Record<PluginHookPhase, HookPoint>;
+export interface PluginApi {
+    /** Register a tool that will be available to the LLM. */
+    registerTool(tool: PortableTool): void;
+    /** Register a hook at a specific lifecycle phase. */
+    registerHook(phase: PluginHookPhase, handler: HookHandler<any>): void;
+    /** Register a skill (Markdown instructions + metadata). */
+    registerSkill(skill: WorkspaceSkill): void;
+    /** Get plugin-scoped configuration (from openclaw/plugins/name/config.json). */
+    getConfig(): Record<string, unknown>;
+    /**
+     * Set an activation check function. When it returns false, the plugin's
+     * tools and hooks are temporarily deactivated. Results are cached for
+     * `ttlMs` (default: 60 000) to avoid expensive re-checks.
+     */
+    setActivationCheck(checkFn: () => boolean | Promise<boolean>, ttlMs?: number): void;
+    /** Plugin's own name (directory name). */
+    readonly pluginName: string;
+}
+/**
+ * Every plugin must export a `register` function.
+ * Called once during plugin loading.
+ */
+export interface PluginModule {
+    register(api: PluginApi): void | Promise<void>;
+}
+export interface LoadedPlugin {
+    name: string;
+    directory: string;
+    toolCount: number;
+    hookCount: number;
+    skillCount: number;
+}

package/dist/skills/plugins/plugin-api.js

@@ -0,0 +1,18 @@
+// ============================================================
+// Plugin API — interface exposed to plugin authors.
+//
+// Plugins call api.registerTool() / api.registerHook() / api.registerSkill()
+// to extend the agent's capabilities.
+//
+// Aligned with hermes plugin model:
+//   ~/.hermes/plugins/my-plugin/__init__.py → register(api)
+//   ~/.qlogicagent/plugins/my-plugin/index.ts → export register(api)
+// ============================================================
+/** Map plugin hook phases to internal HookPoint names */
+export const PLUGIN_HOOK_MAP = {
+    preToolUse: "tool.before_invoke",
+    postToolUse: "tool.after_invoke",
+    onTurnStart: "turn.submitted",
+    onTurnEnd: "turn.completed",
+    onSessionEnd: "session.ended",
+};

package/dist/skills/plugins/plugin-loader.d.ts

@@ -0,0 +1,57 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { WorkspaceSkill } from "../skill-system/skill-types.js";
+import { type LoadedPlugin } from "./plugin-api.js";
+interface PluginToolRegistry {
+    addTool(tool: PortableTool): void;
+    removeTool(name: string): boolean;
+}
+export interface PluginLoaderConfig {
+    /** Directories to scan for plugins (order = priority) */
+    pluginDirs: string[];
+    /** HookRegistry to wire plugin hooks into */
+    hookRegistry: HookRegistry;
+    /** Logger */
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+    /** Runtime-owned tool catalog used for plugin tool registration. */
+    toolCatalog?: PluginToolRegistry;
+}
+export declare class PluginLoader {
+    private config;
+    private loaded;
+    private pluginSkills;
+    private activations;
+    private log;
+    constructor(config: PluginLoaderConfig);
+    /**
+     * Discover and load all plugins from configured directories.
+     * Returns the list of successfully loaded plugins.
+     */
+    loadAll(): Promise<LoadedPlugin[]>;
+    /**
+     * Get all skills registered by plugins.
+     */
+    getPluginSkills(): WorkspaceSkill[];
+    /**
+     * Get list of all loaded plugins.
+     */
+    getLoaded(): LoadedPlugin[];
+    /**
+     * Discover and load NEW plugins that weren't present during initial loadAll().
+     * Call per-turn to pick up newly-created skill directories (铁律 #16).
+     */
+    discoverNew(): Promise<number>;
+    /**
+     * Re-check activation for plugins whose TTL has expired.
+     * Call this before tool resolution or periodically in the agent loop.
+     * Only re-runs check functions when the cache has expired.
+     */
+    refreshActivations(): Promise<void>;
+    private loadPlugin;
+    private addRegisteredTool;
+    private removeRegisteredTool;
+}
+export {};