qlogicagent 0.5.2 → 0.6.0

package/dist/types/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/types/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/types/skills/plugins/plugin-loader.d.ts

@@ -0,0 +1,42 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { WorkspaceSkill } from "../skill-system/skill-types.js";
+import { type LoadedPlugin } from "./plugin-api.js";
+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;
+    };
+}
+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[];
+    /**
+     * 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;
+}

package/dist/types/skills/plugins/plugin-marketplace.d.ts

@@ -0,0 +1,61 @@
+export interface MarketplaceSource {
+    /** Source type */
+    type: "npm" | "git" | "url";
+    /** Package name (npm), git URL, or zip URL */
+    specifier: string;
+    /** Optional version constraint (npm only) */
+    version?: string;
+}
+export interface MarketplaceConfig {
+    /** Enabled plugins from marketplace */
+    enabledPlugins: MarketplaceSource[];
+    /**
+     * Enterprise policy: only allow plugins matching these names.
+     * If set, any plugin not in the allowlist is blocked.
+     */
+    allowlist?: string[];
+    /**
+     * Enterprise policy: block these plugin names.
+     */
+    blocklist?: string[];
+}
+export interface MarketplaceCatalogEntry {
+    /** Plugin name */
+    name: string;
+    /** Installed version */
+    version: string;
+    /** Source that provided this plugin */
+    source: MarketplaceSource;
+    /** Local install path */
+    installPath: string;
+    /** Install timestamp */
+    installedAt: string;
+}
+export interface InstalledPluginsManifest {
+    version: 1;
+    plugins: MarketplaceCatalogEntry[];
+}
+export interface MarketplaceLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+/**
+ * Load plugins from cache only (no network). Fast startup path.
+ * CC parity: loadAllPluginsCacheOnly()
+ */
+export declare function loadCachedPlugins(): string[];
+/**
+ * Install/update marketplace plugins and return their local paths.
+ * CC parity: loadAllPluginsWithDynamic()
+ */
+export declare function installMarketplacePlugins(config: MarketplaceConfig, log: MarketplaceLogger): Promise<string[]>;
+/**
+ * Get the marketplace config from user settings.
+ * Reads ~/.qlogicagent/marketplace.json
+ */
+export declare function loadMarketplaceConfig(): MarketplaceConfig | null;
+/**
+ * Combine local plugin dirs + marketplace plugin dirs for PluginLoader.
+ * CC parity: loadAllPlugins() merges session + marketplace + builtin.
+ */
+export declare function resolveAllPluginDirs(localDirs: string[], log: MarketplaceLogger): Promise<string[]>;

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

@@ -0,0 +1,104 @@
+/**
+ * Content block returned by tool execution.
+ * Compatible with OpenAI / Anthropic content array format.
+ */
+export interface ToolContentBlock {
+    type: "text" | "image";
+    text?: string;
+    /** base64-encoded image data (only when type === "image") */
+    data?: string;
+    mimeType?: string;
+}
+/**
+ * Result of executing a portable tool.
+ */
+export interface PortableToolResult {
+    content: ToolContentBlock[];
+    /** Arbitrary structured metadata for the calling runtime. */
+    details?: Record<string, unknown>;
+}
+/**
+ * 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. "think", "todo", "memory"). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** 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;
+    /**
+     * 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;
+    /**
+     * 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/types/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/types/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;

package/dist/types/skills/skill-system/skill-loader.d.ts

@@ -0,0 +1,16 @@
+import type { SkillEntry, SkillLoadLimits, SkillLoaderDeps, SkillSnapshot } from "./skill-types.js";
+/**
+ * Discover all skills from configured search paths, applying precedence merge
+ * and size/count limits. Returns fully parsed `SkillEntry` objects.
+ */
+export declare function loadSkillEntries(deps: SkillLoaderDeps): SkillEntry[];
+/**
+ * Filter skill entries by a name-based filter list.
+ * If filter is undefined or empty, returns all entries.
+ */
+export declare function filterSkillEntries(entries: SkillEntry[], skillFilter?: string[]): SkillEntry[];
+/**
+ * Build a system-prompt-embeddable skill snapshot.
+ * Applies count and character limits from the provided config.
+ */
+export declare function buildSkillSnapshot(entries: SkillEntry[], limits?: SkillLoadLimits, skillFilter?: string[]): SkillSnapshot;

package/dist/types/skills/skill-system/skill-source.d.ts

@@ -0,0 +1,119 @@
+import type { SkillScanSummary } from "./skill-types.js";
+/**
+ * Trust level for a skill based on its origin.
+ * Higher trust = fewer restrictions.
+ */
+export type TrustLevel = "builtin" | "verified" | "community" | "unknown";
+/**
+ * Result of a skill security scan decision.
+ */
+export type ScanVerdict = "pass" | "quarantine" | "reject";
+/**
+ * A resolved skill source descriptor.
+ */
+export interface SkillSourceDescriptor {
+    /** Source type. */
+    kind: "bundled" | "github" | "npm" | "local" | "tap";
+    /** Human-readable identifier, e.g. "github:user/repo" or "npm:@scope/pkg". */
+    identifier: string;
+    /** Trust level derived from source type + verification status. */
+    trust: TrustLevel;
+    /** Version constraint (semver or tag). */
+    version?: string;
+}
+/**
+ * Result of fetching a skill from a remote source.
+ */
+export interface SkillFetchResult {
+    /** Local directory where fetched content was placed. */
+    quarantineDir: string;
+    /** Manifest metadata if found. */
+    name?: string;
+    version?: string;
+}
+/**
+ * Dependencies for the skill fetch step.
+ * Consumers inject actual HTTP/git/npm implementations.
+ */
+export interface SkillFetchDeps {
+    /**
+     * Download / clone / extract a skill from its source into a quarantine dir.
+     * Must NOT place content in the final install location.
+     */
+    fetch(source: SkillSourceDescriptor, quarantineDir: string): Promise<SkillFetchResult>;
+}
+/**
+ * Dependencies for the skill storage step.
+ * Manages the local skill directory and registry.
+ */
+export interface SkillStorageDeps {
+    /** Root directory for installed skills (e.g. ~/.xiaozhiclaw/skills/). */
+    skillsDir: string;
+    /** Registry subdirectory (e.g. ~/.xiaozhiclaw/skills/.registry/). */
+    registryDir: string;
+    /** Move content from quarantine to final location. */
+    moveToInstallDir(quarantineDir: string, skillName: string): Promise<string>;
+    /** Remove an installed skill directory. */
+    removeSkill(skillName: string): Promise<void>;
+    /** Read the registry lock file. */
+    readLockfile(): Promise<SkillLockfile>;
+    /** Write the registry lock file. */
+    writeLockfile(lockfile: SkillLockfile): Promise<void>;
+}
+/**
+ * Single entry in the skill lockfile.
+ */
+export interface SkillLockEntry {
+    name: string;
+    source: SkillSourceDescriptor;
+    installedAt: string;
+    scanVerdict: ScanVerdict;
+    scanSummary?: SkillScanSummary;
+    /** Integrity hash of the SKILL.md content (sha256). */
+    integrity?: string;
+}
+/**
+ * Complete lockfile for all installed skills.
+ */
+export interface SkillLockfile {
+    version: 1;
+    entries: Record<string, SkillLockEntry>;
+}
+/**
+ * Result of a skill install operation.
+ */
+export interface SkillInstallResult {
+    success: boolean;
+    name: string;
+    installDir?: string;
+    verdict: ScanVerdict;
+    scanSummary?: SkillScanSummary;
+    error?: string;
+}
+/**
+ * Orchestrate the full install pipeline:
+ * Fetch → Quarantine → Scan → Validate → Move → Lock
+ *
+ * This function is pure orchestration — actual I/O is delegated to deps.
+ */
+export declare function installSkill(params: {
+    source: SkillSourceDescriptor;
+    fetchDeps: SkillFetchDeps;
+    storageDeps: SkillStorageDeps;
+    scanSkillDir: (dir: string) => Promise<SkillScanSummary>;
+    quarantineDir: string;
+}): Promise<SkillInstallResult>;
+/**
+ * Uninstall a skill: remove from disk + update lockfile.
+ */
+export declare function uninstallSkill(params: {
+    skillName: string;
+    storageDeps: SkillStorageDeps;
+}): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Create an empty lockfile.
+ */
+export declare function createEmptyLockfile(): SkillLockfile;

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

@@ -0,0 +1,199 @@
+/**
+ * Parsed YAML frontmatter from a SKILL.md file.
+ * Keys are lowercased header names; values are always coerced to strings.
+ */
+export type ParsedSkillFrontmatter = Record<string, string>;
+/**
+ * A discovered skill on the filesystem.
+ */
+export interface WorkspaceSkill {
+    /** Display name (directory name by default). */
+    name: string;
+    /** One-line description extracted from frontmatter. */
+    description?: string;
+    /** Source tag for precedence/debugging, e.g. "bundled", "user", "project". */
+    source: string;
+    /** Absolute path to the SKILL.md file. */
+    filePath: string;
+    /** Absolute path to the skill directory (parent of SKILL.md). */
+    baseDir: string;
+    /** Primary runtime environment hint, e.g. "node", "python". */
+    primaryEnv?: string;
+    /** Environment variables the skill requires. */
+    requiredEnv?: string[];
+}
+/**
+ * Package-manager install specification for a skill dependency.
+ */
+export interface SkillInstallSpec {
+    id?: string;
+    kind: "brew" | "node" | "go" | "uv" | "download";
+    label?: string;
+    bins?: string[];
+    os?: string[];
+    formula?: string;
+    package?: string;
+    module?: string;
+    url?: string;
+    archive?: string;
+    extract?: boolean;
+    stripComponents?: number;
+    targetDir?: string;
+}
+/**
+ * Structured metadata from the `openclaw:` block inside SKILL.md frontmatter.
+ */
+export interface SkillMetadata {
+    /** If true, always include in prompt regardless of filter. */
+    always?: boolean;
+    /** Override key for deduplication / user-facing identification. */
+    skillKey?: string;
+    primaryEnv?: string;
+    emoji?: string;
+    homepage?: string;
+    /** Platform restriction: "win32", "darwin", "linux". */
+    os?: string[];
+    /** Use-case category for UI grouping. */
+    category?: string;
+    requires?: {
+        bins?: string[];
+        anyBins?: string[];
+        env?: string[];
+        config?: string[];
+    };
+    install?: SkillInstallSpec[];
+}
+/**
+ * Controls how a skill may be activated by user commands or model tool calls.
+ */
+export interface SkillInvocationPolicy {
+    /** Whether users can directly invoke this skill via slash-command. */
+    userInvocable: boolean;
+    /** If true, the model cannot trigger this skill autonomously. */
+    disableModelInvocation: boolean;
+}
+/**
+ * A fully resolved skill entry with parsed metadata.
+ */
+export interface SkillEntry {
+    skill: WorkspaceSkill;
+    frontmatter: ParsedSkillFrontmatter;
+    metadata?: SkillMetadata;
+    invocation?: SkillInvocationPolicy;
+}
+/**
+ * Slash-command dispatch specification for a skill.
+ */
+export interface SkillCommandDispatchSpec {
+    kind: "tool";
+    toolName: string;
+    argMode?: "raw";
+}
+/**
+ * A skill-derived slash-command for IM platforms.
+ */
+export interface SkillCommandSpec {
+    name: string;
+    skillName: string;
+    description: string;
+    dispatch?: SkillCommandDispatchSpec;
+}
+/**
+ * Serialized skill snapshot for system-prompt embedding.
+ */
+export interface SkillSnapshot {
+    prompt: string;
+    skills: Array<{
+        name: string;
+        primaryEnv?: string;
+        requiredEnv?: string[];
+    }>;
+    skillFilter?: string[];
+    version?: number;
+}
+export type SkillScanSeverity = "info" | "warn" | "critical";
+export interface SkillScanFinding {
+    ruleId: string;
+    severity: SkillScanSeverity;
+    file: string;
+    line: number;
+    message: string;
+    evidence: string;
+}
+export interface SkillScanSummary {
+    scannedFiles: number;
+    critical: number;
+    warn: number;
+    info: number;
+    findings: SkillScanFinding[];
+}
+export interface SkillScanOptions {
+    includeFiles?: string[];
+    maxFiles?: number;
+    maxFileBytes?: number;
+}
+/**
+ * Filesystem dependencies injected by the host runtime.
+ * Keeps the skill system decoupled from Node.js `fs` / `path`.
+ */
+export interface SkillFsDeps {
+    readFileSync(path: string, encoding: "utf-8"): string;
+    readFile(path: string, encoding: "utf-8"): Promise<string>;
+    existsSync(path: string): boolean;
+    statSync(path: string): {
+        size: number;
+        mtimeMs: number;
+        isDirectory(): boolean;
+    };
+    readdirSync(path: string, opts: {
+        withFileTypes: true;
+    }): Array<{
+        name: string;
+        isDirectory(): boolean;
+        isSymbolicLink(): boolean;
+    }>;
+    realpathSync(path: string): string;
+}
+export interface SkillPathDeps {
+    join(...segments: string[]): string;
+    resolve(...segments: string[]): string;
+    extname(p: string): string;
+    sep: string;
+}
+/**
+ * Configurable limits for skill discovery to prevent abuse.
+ */
+export interface SkillLoadLimits {
+    maxCandidatesPerRoot?: number;
+    maxSkillsLoadedPerSource?: number;
+    maxSkillsInPrompt?: number;
+    maxSkillsPromptChars?: number;
+    maxSkillFileBytes?: number;
+}
+/**
+ * Search paths for skill discovery, ordered by precedence (low → high).
+ */
+export interface SkillSearchPaths {
+    /** Bundled with npm package or app install. */
+    bundled?: string;
+    /** Extra directories from config. */
+    extra?: string[];
+    /** Managed skills (installed via CLI). */
+    managed?: string;
+    /** Personal agent skills: ~/.agents/skills/ */
+    personalAgents?: string;
+    /** Project agent skills: <workspace>/.agents/skills/ */
+    projectAgents?: string;
+    /** Workspace-level: <workspace>/skills/ */
+    workspace?: string;
+}
+/**
+ * Aggregate deps for the skill loader.
+ */
+export interface SkillLoaderDeps {
+    fs: SkillFsDeps;
+    path: SkillPathDeps;
+    homeDir: string;
+    searchPaths: SkillSearchPaths;
+    limits?: SkillLoadLimits;
+}

package/dist/types/skills/think-tool.d.ts

@@ -0,0 +1,16 @@
+import type { PortableTool } from "./portable-tool.js";
+export declare const THINK_TOOL_NAME: "think";
+export interface ThinkToolParams {
+    thought: string;
+}
+export declare const THINK_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly thought: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["thought"];
+};
+export declare function createThinkTool(): PortableTool<ThinkToolParams>;