qlogicagent 0.3.0 → 0.5.0

package/dist/types/skills/memory-query-tool.d.ts

@@ -1,43 +0,0 @@
-import type { PortableTool } from "./portable-tool.js";
-export declare const MEMORY_QUERY_TOOL_NAME: "memory_query";
-export declare const MEMORY_QUERY_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly query: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly category: {
-            readonly type: "string";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["query"];
-};
-export interface MediaPreferencesSummary {
-    imageStyle?: string;
-    videoStyle?: string;
-    musicGenre?: string;
-    musicMood?: string;
-    primaryPurpose?: string;
-    colorPreference?: string;
-}
-/**
- * Dependency-injected callbacks for memory query.
- * Consumers provide these from their own memory system.
- */
-export interface MemoryQueryToolDeps {
-    /** Query recalled facts/memories by natural language. */
-    queryGraph?: (query: string, userId: string) => string[];
-    /** Retrieve user profile summary. */
-    getProfileSummary?: (userId: string) => string | null;
-    /** Retrieve media preferences. */
-    getMediaPreferences?: (userId: string) => MediaPreferencesSummary | null;
-    /** User ID for this session. */
-    userId?: string;
-}
-export interface MemoryQueryToolParams {
-    query: string;
-    category?: string;
-}
-export declare function createMemoryQueryTool(deps?: MemoryQueryToolDeps): PortableTool<MemoryQueryToolParams>;

package/dist/types/skills/memory-store.d.ts

@@ -1,66 +0,0 @@
-export declare const MEMORY_ENTRY_DELIMITER = "\n\u00A7\n";
-export declare const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
-export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
-export type MemoryStoreTarget = "memory" | "user";
-export interface MemoryStoreResult {
-    ok: boolean;
-    message: string;
-    target: MemoryStoreTarget;
-    entries: readonly string[];
-    entryCount: number;
-    usage: string;
-    errorCode?: string;
-}
-export interface MemoryStoreOptions {
-    memoryCharLimit?: number;
-    userCharLimit?: number;
-}
-export interface MemoryStoreSerialized {
-    memory: string;
-    user: string;
-}
-export declare class MemoryStore {
-    private memoryEntries;
-    private userEntries;
-    private frozenSnapshot;
-    private snapshotFrozen;
-    private readonly memoryCharLimit;
-    private readonly userCharLimit;
-    constructor(options?: MemoryStoreOptions);
-    /**
-     * Load from serialized form (e.g. from PG or filesystem).
-     * Deduplicates entries on load.
-     */
-    loadFromSerialized(data: Partial<MemoryStoreSerialized>): void;
-    /**
-     * Serialize current live state for persistence.
-     */
-    serialize(): MemoryStoreSerialized;
-    /**
-     * Freeze current entries for system prompt injection.
-     * Call once at session start. After freezing, mutations update
-     * live state but NOT the system prompt block.
-     */
-    freezeSnapshot(): void;
-    /**
-     * Get frozen system prompt block for the given target.
-     * Returns empty string if no entries or not yet frozen.
-     */
-    getSystemPromptBlock(target: MemoryStoreTarget): string;
-    add(target: MemoryStoreTarget, content: string): MemoryStoreResult;
-    replace(target: MemoryStoreTarget, oldText: string, newContent: string): MemoryStoreResult;
-    remove(target: MemoryStoreTarget, oldText: string): MemoryStoreResult;
-    getEntries(target: MemoryStoreTarget): readonly string[];
-    getUsage(target: MemoryStoreTarget): {
-        used: number;
-        limit: number;
-        percent: number;
-    };
-    isEmpty(): boolean;
-    private entriesFor;
-    private charLimitFor;
-    private formatUsage;
-    private renderBlock;
-    private successResult;
-    private errorResult;
-}

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

@@ -1,67 +0,0 @@
-import type { MemoryProvider, MemorySearchResult } from "qlogicagent-runtime-contracts";
-import type { MemoryStore, MemoryStoreTarget } from "./memory-store.js";
-export declare const MEMORY_TOOL_NAME: "memory";
-export declare const MEMORY_TOOL_MAX_CONTENT_LENGTH = 2000;
-export declare const MEMORY_TOOL_ACTIONS: readonly ["add", "replace", "remove", "search"];
-export type MemoryToolAction = (typeof MEMORY_TOOL_ACTIONS)[number];
-export declare const MEMORY_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: string[];
-            readonly description: string;
-        };
-        readonly target: {
-            readonly type: "string";
-            readonly enum: readonly ["memory", "user"];
-            readonly description: string;
-        };
-        readonly content: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly old_text: {
-            readonly type: "string";
-            readonly description: "Required for 'replace' and 'remove'. A substring that uniquely identifies the note entry to modify.";
-        };
-        readonly query: {
-            readonly type: "string";
-            readonly description: "Required for 'search'. Natural language query to find relevant memories.";
-        };
-    };
-    readonly required: readonly ["action"];
-};
-export declare const MEMORY_TOOL_DESCRIPTION: string;
-export declare const MEMORY_TOOL_LABEL = "Memory";
-export declare function isMemoryContentSafe(text: string): boolean;
-export interface MemoryToolParams {
-    action: MemoryToolAction;
-    target?: MemoryStoreTarget;
-    content?: string;
-    old_text?: string;
-    query?: string;
-}
-export interface MemoryToolResult {
-    ok: boolean;
-    message: string;
-    action: string;
-    /** For MD store operations: live entry count */
-    entryCount?: number;
-    /** For MD store operations: usage string */
-    usage?: string;
-    /** For search: qmemory results */
-    results?: MemorySearchResult[];
-    /** Indicates MD store was mutated (consumer should persist) */
-    storeModified?: boolean;
-    errorCode?: string;
-}
-export interface MemoryToolExecutorDeps {
-    /** QMemory provider for semantic search. */
-    provider: MemoryProvider;
-    /** Local MD memory store for notes. */
-    store?: MemoryStore;
-    userId: string;
-    sessionId?: string;
-}
-export declare function executeMemoryTool(params: MemoryToolParams, deps: MemoryToolExecutorDeps): Promise<MemoryToolResult>;

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

@@ -1,71 +0,0 @@
-/**
- * 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_query"). */
-    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;
-    /**
-     * 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>;
-}

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

@@ -1,52 +0,0 @@
-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.
- *
- * @example
- * ```ts
- * const provider = createQMemoryAdapter({
- *   baseUrl: "http://localhost:18800",
- *   apiKey: "sk-...",
- * });
- *
- * const results = await provider.search("last meeting notes", "alice");
- * await provider.ingest([{ role: "user", content: "..." }], "alice");
- * ```
- */
-export declare function createQMemoryAdapter(config: QMemoryAdapterConfig): MemoryProvider & {
-    /** Check qmemory server health. */
-    health(): Promise<QMemoryHealthStatus>;
-    /** Write pre-extracted memories (no LLM extraction on qmemory side). */
-    ingestExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<{
-        memoriesAdded: number;
-    }>;
-};

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

@@ -1,19 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,119 +0,0 @@
-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

@@ -1,199 +0,0 @@
-/**
- * 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;
-}