qlogicagent 2.1.0 → 2.3.0

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

@@ -60,6 +60,33 @@ export interface SkillStorageDeps {
     /** Write the registry lock file. */
     writeLockfile(lockfile: SkillLockfile): Promise<void>;
 }
+/**
+ * A single version history entry for a skill.
+ */
+export interface SkillVersionEntry {
+    version: string;
+    updatedAt: string;
+    changelog?: string;
+    /** Integrity hash of the SKILL.md content at this version (sha256). */
+    integrity?: string;
+}
+/**
+ * Usage statistics for a skill.
+ */
+export interface SkillUsageStats {
+    /** Total number of times this skill has been invoked/applied. */
+    invokeCount: number;
+    /** Number of turns where the skill was active and contributed. */
+    activeCount: number;
+    /** Number of times the skill received positive feedback. */
+    positiveCount: number;
+    /** Number of times the skill received negative feedback. */
+    negativeCount: number;
+    /** ISO 8601 timestamp of last use. */
+    lastUsedAt?: string;
+    /** Derived success rate = (invokeCount - negativeCount) / invokeCount */
+    successRate?: number;
+}
 /**
  * Single entry in the skill lockfile.
  */
@@ -71,6 +98,12 @@ export interface SkillLockEntry {
     scanSummary?: SkillScanSummary;
     /** Integrity hash of the SKILL.md content (sha256). */
     integrity?: string;
+    /** Current version (from frontmatter or auto-incremented). */
+    currentVersion?: string;
+    /** Version history — newest first. */
+    versionHistory?: SkillVersionEntry[];
+    /** Usage statistics. */
+    usage?: SkillUsageStats;
 }
 /**
  * Complete lockfile for all installed skills.
@@ -79,6 +112,38 @@ export interface SkillLockfile {
     version: 1;
     entries: Record<string, SkillLockEntry>;
 }
+/**
+ * Record a skill usage event. Mutates the lockfile entry in-place.
+ */
+export declare function recordSkillUsage(lockfile: SkillLockfile, skillName: string, feedback?: "positive" | "negative" | null): void;
+/**
+ * Record a skill version update. Pushes current version to history.
+ */
+export declare function recordSkillVersionUpdate(lockfile: SkillLockfile, skillName: string, newVersion: string, changelog?: string, integrity?: string): void;
+/**
+ * Lightweight per-skill stats stored in `~/.qlogicagent/skill-stats.json`.
+ * This is independent of the lockfile — covers learned, promoted, and installed skills.
+ */
+export interface SkillStatsFile {
+    [skillName: string]: SkillUsageStats;
+}
+/**
+ * Record a skill invocation. Fire-and-forget — never throws.
+ * @param agentHome - path to `~/.qlogicagent/`
+ * @param skillName - the skill that was invoked
+ * @param success - whether the invocation completed without error
+ */
+export declare function trackSkillInvocation(agentHome: string, skillName: string, success: boolean): void;
+/**
+ * Read stats for a skill. Returns undefined if no stats recorded.
+ */
+export declare function getSkillStats(agentHome: string, skillName: string): SkillUsageStats | undefined;
+/**
+ * Get all skill stats. Useful for UI display.
+ */
+export declare function getAllSkillStats(agentHome: string): SkillStatsFile;
+/** Reset cache (for testing). */
+export declare function resetStatsCache(): void;
 /**
  * Result of a skill install operation.
  */

package/dist/types/skills/tools/plan-mode-tool.d.ts

@@ -54,7 +54,7 @@ export declare const PLAN_MODE_TOOL_SCHEMA: {
     };
     readonly required: readonly ["action"];
 };
-/** Tools allowed during plan mode (read-only + reasoning) */
+/** Tools allowed during plan mode (read-only + reasoning + task tracking) */
 export declare const PLAN_MODE_ALLOWED_TOOLS: readonly string[];
 export interface PlanModeState {
     active: boolean;

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

@@ -26,13 +26,13 @@ export declare const READ_TOOL_SCHEMA: {
 export type ReadResultType = "text" | "image" | "binary_rejected";
 /** Deps injected by the host runtime for file reading. */
 export interface ReadToolDeps {
-    /** Read file content. Return string for text, base64 for images, or rejection. */
+    /** Read file content. Return string for text, image path for images, or rejection. */
     readFile(path: string): Promise<{
         type: "text";
         text: string;
     } | {
         type: "image";
-        base64: string;
+        localPath: string;
         mimeType: string;
     } | {
         type: "binary";

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

@@ -1,104 +1,93 @@
 import type { PortableTool } from "../portable-tool.js";
 export declare const TASK_TOOL_NAME: "task";
-export type TaskAction = "create" | "get" | "list" | "output" | "stop";
-export type TaskStatus = "pending" | "running" | "completed" | "failed" | "stopped";
+export declare const TASK_ACTIONS: readonly ["create", "update", "delete", "list", "get"];
+export type TaskAction = (typeof TASK_ACTIONS)[number];
+export type TaskStatus = "not-started" | "in-progress" | "completed";
+export declare const TASK_STATUS_VALUES: readonly TaskStatus[];
+export interface TaskItem {
+    id: number;
+    title: string;
+    status: TaskStatus;
+    description?: string;
+    owner?: string;
+    blockedBy?: number[];
+    blocks?: number[];
+}
+export interface TaskListSummary {
+    total: number;
+    completed: number;
+    inProgress: number;
+    notStarted: number;
+    blocked: number;
+}
 export interface TaskToolParams {
     action: TaskAction;
-    /** Task ID (required for get/output/stop) */
-    taskId?: string;
-    /** Task prompt (required for create) */
-    prompt?: string;
-    /** Short description (3-7 words, for create) */
+    id?: number;
+    title?: string;
     description?: string;
-    /** Allowed tools for the background agent */
-    allowedTools?: string[];
-    /** Working directory for the task */
-    cwd?: string;
-    /** Model override for the task agent */
-    model?: string;
-    /** Max output lines to return (for output action, default 100) */
-    maxLines?: number;
+    status?: TaskStatus;
+    owner?: string;
+    addBlocks?: number[];
+    addBlockedBy?: number[];
 }
 export declare const TASK_TOOL_SCHEMA: {
     readonly type: "object";
     readonly properties: {
         readonly action: {
             readonly type: "string";
-            readonly enum: readonly ["create", "get", "list", "output", "stop"];
+            readonly enum: readonly ["create", "update", "delete", "list", "get"];
             readonly description: string;
         };
-        readonly taskId: {
-            readonly type: "string";
-            readonly description: "Task ID. Required for get/output/stop.";
+        readonly id: {
+            readonly type: "number";
+            readonly description: "[update|delete|get] Task id to operate on.";
         };
-        readonly prompt: {
+        readonly title: {
             readonly type: "string";
-            readonly description: string;
+            readonly description: "[create|update] Task title (3-7 words, imperative form).";
         };
         readonly description: {
             readonly type: "string";
-            readonly description: "Short (3-7 word) description of the task. Used for tracking and display.";
-        };
-        readonly allowedTools: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "string";
-            };
-            readonly description: "Restrict background agent to only these tools. If omitted, inherits parent's tools.";
+            readonly description: "[create|update] Detailed task description.";
         };
-        readonly cwd: {
+        readonly status: {
             readonly type: "string";
-            readonly description: "Working directory for the background task (absolute path).";
+            readonly enum: readonly ["not-started", "in-progress", "completed"];
+            readonly description: "[create|update] Task status. create defaults to not-started.";
         };
-        readonly model: {
+        readonly owner: {
             readonly type: "string";
-            readonly description: "Model override for the task agent (e.g. 'sonnet', 'opus').";
+            readonly description: "[create|update] Owner agent/subagent identifier.";
         };
-        readonly maxLines: {
-            readonly type: "number";
-            readonly description: "Max output lines to return for the 'output' action (default: 100).";
-            readonly minimum: 1;
-            readonly maximum: 2000;
+        readonly addBlocks: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly description: "[update] Task IDs that this task should block (they depend on this task).";
+        };
+        readonly addBlockedBy: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly description: "[update] Task IDs that should block this task (this task depends on them).";
         };
     };
     readonly required: readonly ["action"];
 };
-export interface TaskInfo {
-    taskId: string;
-    status: TaskStatus;
-    description?: string;
-    prompt?: string;
-    createdAt: number;
-    completedAt?: number;
-    result?: string;
-    error?: string;
-}
-export interface TaskResult {
-    success: boolean;
-    task?: TaskInfo;
-    tasks?: TaskInfo[];
-    output?: string;
-    error?: string;
+export interface TaskToolOptions {
+    /** Unique agent/session identifier for per-agent task isolation. */
+    agentId?: string;
+    /** Enable verification nudge (default: true). */
+    verificationNudge?: boolean;
 }
-/** Host-provided task management backend. */
-export interface TaskToolDeps {
-    /** Create a new background agent task. Returns the created task info. */
-    createTask(params: {
-        prompt: string;
-        description?: string;
-        allowedTools?: string[];
-        cwd?: string;
-        model?: string;
-    }): Promise<TaskInfo>;
-    /** Get a task by ID. Returns null if not found. */
-    getTask(taskId: string): Promise<TaskInfo | null>;
-    /** List all tasks (optionally filtered by status). */
-    listTasks(filter?: {
-        status?: TaskStatus;
-    }): Promise<TaskInfo[]>;
-    /** Get output/logs from a task. */
-    getTaskOutput(taskId: string, maxLines?: number): Promise<string>;
-    /** Stop a running task. Returns true if stopped successfully. */
-    stopTask(taskId: string): Promise<boolean>;
+export interface TaskToolHooks {
+    onTaskCreated?: (task: TaskItem) => void;
+    onTaskCompleted?: (task: TaskItem) => void;
 }
-export declare function createTaskTool(deps: TaskToolDeps): PortableTool<TaskToolParams>;
+export declare function summarizeTaskList(items: readonly TaskItem[]): TaskListSummary;
+/**
+ * Create a stateful task tool instance (V2 — CC TaskCreate/Update/List/Get aligned).
+ */
+export declare function createTaskTool(options?: TaskToolOptions, hooks?: TaskToolHooks): PortableTool<TaskToolParams>;

package/dist/types/transport/acp-server.d.ts

@@ -89,6 +89,8 @@ export declare class AcpServer {
     private activeSessionId;
     /** Pending permission requests (agent → host) waiting for response */
     private pendingPermissions;
+    /** Map from outbound JSON-RPC request id → permissionId for response matching */
+    private outboundRequestMap;
     constructor(transport: Transport, handler: AcpRequestHandler, config?: AcpServerConfig);
     /**
      * Route an incoming raw message through ACP protocol handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",

package/dist/types/contracts/planner.d.ts

@@ -1,35 +0,0 @@
-export declare const TASK_STEP_STATUS_VALUES: readonly ["pending", "in-progress", "completed", "skipped"];
-export type TaskStepStatus = (typeof TASK_STEP_STATUS_VALUES)[number];
-export declare const TASK_PLAN_STATUS_VALUES: readonly ["active", "completed", "abandoned"];
-export type TaskPlanStatus = (typeof TASK_PLAN_STATUS_VALUES)[number];
-export interface TaskStep {
-    index: number;
-    description: string;
-    status: TaskStepStatus;
-    result?: string;
-}
-export interface TaskPlan {
-    id: string;
-    sessionId: string;
-    userId: string;
-    goal: string;
-    steps: TaskStep[];
-    status: TaskPlanStatus;
-    createdAt: string;
-    updatedAt: string;
-    constraints?: string[];
-    keyIdentifiers?: string[];
-}
-export interface TaskPlanContextSnippet {
-    text: string;
-    tokens: number;
-    planId: string;
-}
-export interface TaskPlanProgressSnapshot {
-    goal: string;
-    steps: Array<{
-        description: string;
-        status: TaskStepStatus | string;
-        result?: string;
-    }>;
-}

package/dist/types/orchestration/error-handling/failover-error.d.ts

@@ -1,33 +0,0 @@
-import { type FailoverReason } from "./failover-classification.js";
-export declare class FailoverError extends Error {
-    readonly reason: FailoverReason;
-    readonly provider?: string;
-    readonly model?: string;
-    readonly profileId?: string;
-    readonly status?: number;
-    readonly code?: string;
-    constructor(message: string, params: {
-        reason: FailoverReason;
-        provider?: string;
-        model?: string;
-        profileId?: string;
-        status?: number;
-        code?: string;
-        cause?: unknown;
-    });
-}
-export declare function isFailoverError(err: unknown): err is FailoverError;
-export declare function resolveFailoverStatus(reason: FailoverReason): number | undefined;
-export declare function isTimeoutError(err: unknown): boolean;
-export declare function resolveFailoverReasonFromError(err: unknown): FailoverReason | null;
-export declare function describeFailoverError(err: unknown): {
-    message: string;
-    reason?: FailoverReason;
-    status?: number;
-    code?: string;
-};
-export declare function coerceToFailoverError(err: unknown, context?: {
-    provider?: string;
-    model?: string;
-    profileId?: string;
-}): FailoverError | null;

package/dist/types/skills/memory/memory-write-gate.d.ts

@@ -1,46 +0,0 @@
-import type { MemorySearchResult } from "qlogicagent-runtime-contracts";
-/**
- * Memory categories for QMemory writes.
- * Each has different value thresholds and retention policies.
- */
-export type QMemoryCategory = "lesson" | "preference" | "pattern" | "fact" | "decision" | "skill-learning";
-/**
- * A candidate memory extracted from a turn.
- */
-export interface MemoryCandidate {
-    text: string;
-    category: QMemoryCategory;
-    importance: number;
-    tags: string[];
-}
-/**
- * Extract memory candidates from a completed turn.
- *
- * Strategy: scan assistant response for category signal patterns.
- * This is a fast pattern-based approach (no LLM call needed).
- * Only extracts segments that match high-value patterns.
- */
-export declare function extractCandidates(userPrompt: string, assistantResponse: string): MemoryCandidate[];
-/**
- * Quality gate: filter candidates by minimum importance threshold.
- */
-export declare function applyQualityGate(candidates: MemoryCandidate[], minImportance?: number): MemoryCandidate[];
-/**
- * Result of supersedes check for a single candidate.
- */
-export interface SupersedesCheckResult {
-    candidate: MemoryCandidate;
-    supersedes: string[];
-}
-/**
- * Check if candidates supersede existing memories.
- *
- * Strategy: for each candidate, search QMemory for semantically similar
- * existing entries. If similarity is high (>0.80) and the candidate is
- * newer/more specific, mark the old one for supersede.
- *
- * @param candidates - Memory candidates to check
- * @param existingSearch - Function to search existing memories
- * @returns Candidates with supersedes info
- */
-export declare function checkSupersedes(candidates: MemoryCandidate[], existingSearch: (query: string) => Promise<MemorySearchResult[]>): Promise<SupersedesCheckResult[]>;

package/dist/types/skills/memory/memory-write-hook.d.ts

@@ -1,44 +0,0 @@
-import type { MemorySearchResult } from "qlogicagent-runtime-contracts";
-import type { ExtractedMemoryItem } from "./qmemory-adapter.js";
-export declare const WRITE_HOOK_CONFIG: {
-    /** Minimum importance to pass the quality gate. */
-    readonly MIN_IMPORTANCE: 0.4;
-    /** Max candidates to write per turn (prevent flood). */
-    readonly MAX_PER_TURN: 3;
-    /** Cooldown between writes (ms) — prevents rapid duplicate writes. */
-    readonly COOLDOWN_MS: 5000;
-};
-export interface MemoryWriteHookDeps {
-    /** Write extracted items to QMemory. */
-    ingestExtracted: (items: ExtractedMemoryItem[], userId: string) => Promise<{
-        memoriesAdded: number;
-    }>;
-    /** Search existing memories (for supersedes check). */
-    searchMemories: (query: string, userId: string) => Promise<MemorySearchResult[]>;
-    /** Remove a superseded memory by ID. */
-    removeMemory?: (memoryId: string) => Promise<boolean>;
-    /** User ID for QMemory writes. */
-    userId: string;
-    /** Logger. */
-    log: {
-        debug(msg: string): void;
-        warn(msg: string): void;
-    };
-}
-/** Per-session state for the write hook. */
-export interface MemoryWriteState {
-    /** Timestamp of last write (for cooldown). */
-    lastWriteAt: number;
-    /** Total memories written this session (for budget). */
-    sessionWrites: number;
-    /** Recent write texts (for intra-session dedup). */
-    recentTexts: Set<string>;
-}
-export declare function createMemoryWriteState(): MemoryWriteState;
-/**
- * Process a completed turn for memory-worthy content.
- * Called directly from stdio-server after turn.end (fire-and-forget).
- *
- * Pipeline: extract → gate → dedup → supersedes check → write.
- */
-export declare function processMemoryWriteGate(userPrompt: string, assistantResponse: string, deps: MemoryWriteHookDeps, state: MemoryWriteState): Promise<void>;

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

@@ -1,72 +0,0 @@
-import type { TodoItemStatus } from "../contracts/todo.js";
-import type { PortableTool } from "./portable-tool.js";
-export declare const TODO_TOOL_NAME: "todo";
-export declare const TODO_ACTIONS: readonly ["create", "update", "delete", "list"];
-export type TodoAction = (typeof TODO_ACTIONS)[number];
-export interface TodoToolParams {
-    action: TodoAction;
-    id?: number;
-    title?: string;
-    description?: string;
-    status?: TodoItemStatus;
-    owner?: string;
-    addBlocks?: number[];
-    addBlockedBy?: number[];
-}
-export declare const TODO_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: readonly ["create", "update", "delete", "list"];
-            readonly description: string;
-        };
-        readonly id: {
-            readonly type: "number";
-            readonly description: "[update|delete] Task id to operate on.";
-        };
-        readonly title: {
-            readonly type: "string";
-            readonly description: "[create|update] Task title (3-7 words).";
-        };
-        readonly description: {
-            readonly type: "string";
-            readonly description: "[create|update] Detailed task description.";
-        };
-        readonly status: {
-            readonly type: "string";
-            readonly enum: readonly ["not-started", "in-progress", "completed"];
-            readonly description: "[create|update] Task status. create defaults to not-started.";
-        };
-        readonly owner: {
-            readonly type: "string";
-            readonly description: "[create|update] Owner agent/subagent identifier.";
-        };
-        readonly addBlocks: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "number";
-            };
-            readonly description: "[update] Task IDs that this task should block.";
-        };
-        readonly addBlockedBy: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "number";
-            };
-            readonly description: "[update] Task IDs that should block this task.";
-        };
-    };
-    readonly required: readonly ["action"];
-};
-/**
- * Configuration for todo tool behavior.
- */
-export interface TodoToolOptions {
-    /** Unique agent/session identifier for per-agent todo isolation. */
-    agentId?: string;
-}
-/**
- * Create a stateful todo tool instance (V2 — incremental CRUD).
- */
-export declare function createTodoTool(options?: TodoToolOptions): PortableTool<TodoToolParams>;