qlogicagent 0.5.2 → 0.5.3

package/dist/types/skills/qmemory-adapter.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryIngestOptions, MemoryProvider } from "qlogicagent-runtime-contracts";
+/** A pre-extracted memory item ready to be stored (no LLM needed). */
+export interface ExtractedMemoryItem {
+    text: string;
+    category?: string;
+    importance?: number;
+    speaker?: string;
+    event_date?: string;
+    tags?: string[];
+}
+/** Configuration for the QMemory HTTP adapter. */
+export interface QMemoryAdapterConfig {
+    /** Base URL of the qmemory server (e.g. "http://localhost:18800"). */
+    baseUrl: string;
+    /** Optional API key for authentication. */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 5000). */
+    timeoutMs?: number;
+    /** Prefix prepended to userId for multi-tenant isolation. */
+    userIdPrefix?: string;
+}
+/** Health status returned by qmemory `/v1/health/`. */
+export interface QMemoryHealthStatus {
+    status: string;
+    version: string;
+    memoryCount: number;
+    dbSizeBytes: number;
+    embeddingModel: string;
+    uptimeSeconds: number;
+}
+/**
+ * Create a MemoryProvider backed by a QMemory HTTP server.
+ *
+ * Uses `qlogicagent-adapter-claw` for HTTP transport.
+ */
+export declare function createQMemoryAdapter(config: QMemoryAdapterConfig): MemoryProvider & {
+    health(): Promise<QMemoryHealthStatus>;
+    ingestExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<{
+        memoriesAdded: number;
+    }>;
+    feedback(memoryIds: string[], signal: string, sessionId?: string): Promise<void>;
+};

package/dist/types/skills/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-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-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-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-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>;

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

@@ -0,0 +1,63 @@
+import type { TodoItem } from "../contracts/todo.js";
+import type { PortableTool } from "./portable-tool.js";
+export declare const TODO_TOOL_NAME: "todo";
+export interface TodoToolParams {
+    todoList: TodoItem[];
+}
+export declare const TODO_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly todoList: {
+            readonly type: "array";
+            readonly description: string;
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "number";
+                        readonly description: "Unique numeric id (sequential from 1).";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                        readonly description: "Concise action-oriented label (3-7 words). Displayed in UI.";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["not-started", "in-progress", "completed"];
+                        readonly description: "not-started | in-progress (max 1) | completed";
+                    };
+                };
+                readonly required: readonly ["id", "title", "status"];
+            };
+        };
+    };
+    readonly required: readonly ["todoList"];
+};
+/**
+ * Configuration for todo tool behavior (CC-aligned features).
+ */
+export interface TodoToolOptions {
+    /**
+     * Unique agent/session identifier for per-agent todo isolation.
+     * When provided, different agents have independent todo lists.
+     */
+    agentId?: string;
+    /**
+     * Whether verification nudge is enabled.
+     * When all items are completed (≥3 items, none matching /verif/i),
+     * the tool signals that a verification sub-agent should be spawned.
+     */
+    enableVerificationNudge?: boolean;
+    /**
+     * Whether to auto-clear the list when all items are completed.
+     * Matches CC behavior: allDone → newTodos = [].
+     */
+    autoClearOnComplete?: boolean;
+}
+/**
+ * Create a stateful todo tool instance.
+ *
+ * Each call returns a tool with its own session-local list.
+ * Multiple instances can exist for different sessions/agents.
+ */
+export declare function createTodoTool(options?: TodoToolOptions): PortableTool<TodoToolParams>;

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

@@ -0,0 +1,29 @@
+import type { PortableTool, PortableToolResult } from "./portable-tool.js";
+import type { ToolDefinition } from "../agent/types.js";
+export declare class ToolRegistry {
+    private tools;
+    /** Register a single tool. Overwrites if name already exists. */
+    register(tool: PortableTool<any>): void;
+    /** Register multiple tools at once. */
+    registerAll(tools: PortableTool<any>[]): void;
+    /** Unregister a tool by name. */
+    unregister(name: string): boolean;
+    /** Find a tool by name. Returns undefined if not registered. */
+    findTool(name: string): PortableTool | undefined;
+    /** Check if a tool is registered locally. */
+    has(name: string): boolean;
+    /**
+     * Execute a tool by name.
+     * @throws Error if the tool is not registered.
+     */
+    execute(name: string, toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<PortableToolResult>;
+    /**
+     * Generate ToolDefinition[] manifest for LLM tool_use.
+     * Excludes deferred tools by default.
+     */
+    getToolManifest(includeDeferred?: boolean): ToolDefinition[];
+    /** Get all registered tool names. */
+    getToolNames(): string[];
+    /** Number of registered tools. */
+    get size(): number;
+}

package/dist/types/skills/tools/agent-tool.d.ts

@@ -0,0 +1,91 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const AGENT_TOOL_NAME: "agent";
+/**
+ * Built-in agent types (CC-aligned registry).
+ * The LLM selects which agent to fork based on the task.
+ */
+export type BuiltInAgentType = "general" | "explore" | "plan" | "code" | "research" | "verify";
+export declare const BUILT_IN_AGENT_TYPES: BuiltInAgentType[];
+export interface AgentToolParams {
+    /** Built-in agent type to invoke. */
+    agent: BuiltInAgentType;
+    /** Detailed task prompt for the sub-agent. */
+    prompt: string;
+    /** Short description of the task (3-7 words). Used for status display. */
+    description?: string;
+    /** Max turns override (default varies by agent type). */
+    maxTurns?: number;
+    /** Run in background (returns task_id immediately). */
+    background?: boolean;
+}
+export declare const AGENT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly agent: {
+            readonly type: "string";
+            readonly enum: readonly ["general", "explore", "plan", "code", "research", "verify"];
+            readonly description: string;
+        };
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Short description (3-7 words) for status tracking.";
+        };
+        readonly maxTurns: {
+            readonly type: "number";
+            readonly description: "Max turns for the sub-agent. Defaults: general=200, explore=50, plan=80, code=200, research=30, verify=40.";
+        };
+        readonly background: {
+            readonly type: "boolean";
+            readonly description: "If true, runs in background and returns a task_id. Poll with task tool. Default: false.";
+        };
+    };
+    readonly required: readonly ["agent", "prompt"];
+    readonly additionalProperties: false;
+};
+export interface AgentResult {
+    agentId: string;
+    status: "completed" | "running" | "failed";
+    output?: string;
+    error?: string;
+    maxTurnsReached?: boolean;
+    tokensUsed?: number;
+}
+/**
+ * Host-provided fork execution backend (CC-aligned).
+ *
+ * Key properties of the fork mechanism:
+ * 1. Child shares parent's message prefix (prompt cache hit)
+ * 2. Child uses byte-identical prefix via placeholder results
+ * 3. Child has independent tool context (isolation)
+ * 4. Results flow back via in-memory streaming (not DB)
+ * 5. Fork depth tracked in-memory (max 4 layers)
+ */
+export interface AgentToolDeps {
+    /**
+     * Fork and run a sub-agent.
+     * The implementation must:
+     * - Share parent's rendered system prompt (byte-identical for cache)
+     * - Inherit parent's tool pool (filtered by agent definition)
+     * - Track fork depth (reject if > MAX_FORK_DEPTH)
+     * - Return output via in-memory streaming backflow
+     */
+    forkAgent(params: {
+        agent: BuiltInAgentType;
+        prompt: string;
+        description?: string;
+        maxTurns?: number;
+        background?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<AgentResult>;
+    /** Abort signal from the parent turn. */
+    abortSignal?: AbortSignal;
+    /** Current fork depth (0 = root). Used for depth guard. */
+    currentForkDepth?: number;
+}
+/** Maximum fork depth for in-memory agents. */
+export declare const MAX_FORK_DEPTH = 4;
+export declare function createAgentTool(deps: AgentToolDeps): PortableTool<AgentToolParams>;

package/dist/types/skills/tools/apply-patch-tool.d.ts

@@ -0,0 +1,29 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const APPLY_PATCH_TOOL_NAME: "apply_patch";
+export interface ApplyPatchToolParams {
+    input: string;
+}
+export declare const APPLY_PATCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly input: {
+            readonly type: "string";
+            readonly description: "Patch content using the *** Begin Patch / *** End Patch format.";
+        };
+    };
+    readonly required: readonly ["input"];
+};
+export interface ApplyPatchSummary {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+}
+/** Deps injected by the host runtime for file patching. */
+export interface ApplyPatchToolDeps {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    fileExists(path: string): Promise<boolean>;
+    resolvePath(input: string): string;
+}
+export declare function createApplyPatchTool(deps: ApplyPatchToolDeps): PortableTool<ApplyPatchToolParams>;