qlogicagent 2.0.0 → 2.2.0

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

@@ -5,7 +5,12 @@
 export interface ToolContentBlock {
     type: "text" | "image";
     text?: string;
-    /** base64-encoded image data (only when type === "image") */
+    /**
+     * base64-encoded image data (only when type === "image").
+     * Used by browser screenshots and MCP tools where data is already in memory.
+     * The tool invoker promotes these to data-URL imageUrls for transport resolution.
+     * For file-based images, prefer returning localPath via PortableToolResult.imageUrls.
+     */
     data?: string;
     mimeType?: string;
 }
@@ -16,6 +21,12 @@ export interface PortableToolResult {
     content: ToolContentBlock[];
     /** Arbitrary structured metadata for the calling runtime. */
     details?: Record<string, unknown>;
+    /**
+     * Local image file paths produced by this tool (e.g. read tool reading an image).
+     * Transport layer resolves these via FileUploadAdapter before sending to the LLM.
+     * This avoids loading large files into memory as base64.
+     */
+    imageUrls?: string[];
 }
 /**
  * A runtime-agnostic tool definition.
@@ -23,7 +34,7 @@ export interface PortableToolResult {
  * @typeParam TParams The expected parameter shape (for TypeScript consumers).
  */
 export interface PortableTool<TParams = Record<string, unknown>> {
-    /** Unique tool name (e.g. "think", "todo", "memory"). */
+    /** Unique tool name (e.g. "think", "task", "memory"). */
     name: string;
     /** Human-readable label. */
     label: string;

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/skill-tool.d.ts

@@ -1,7 +1,7 @@
 import type { PortableTool } from "../portable-tool.js";
 import type { WorkspaceSkill } from "../skill-system/skill-types.js";
 export declare const SKILL_TOOL_NAME: "skill";
-export type SkillAction = "invoke" | "list" | "view" | "create" | "edit" | "patch" | "delete";
+export type SkillAction = "invoke" | "list" | "view" | "create" | "edit" | "patch" | "delete" | "promote" | "install";
 export interface SkillToolParams {
     action: SkillAction;
     name?: string;
@@ -12,18 +12,20 @@ export interface SkillToolParams {
     fileContent?: string;
     oldString?: string;
     newString?: string;
+    /** URL to download skill from (for 'install' action). */
+    url?: string;
 }
 export declare const SKILL_TOOL_SCHEMA: {
     readonly type: "object";
     readonly properties: {
         readonly action: {
             readonly type: "string";
-            readonly enum: readonly ["invoke", "list", "view", "create", "edit", "patch", "delete"];
+            readonly enum: readonly ["invoke", "list", "view", "create", "edit", "patch", "delete", "promote", "install"];
             readonly description: string;
         };
         readonly name: {
             readonly type: "string";
-            readonly description: "Skill name (required for invoke/view/create/edit/patch/delete).";
+            readonly description: "Skill name (required for invoke/view/create/edit/patch/delete/promote).";
         };
         readonly args: {
             readonly type: "string";
@@ -53,6 +55,10 @@ export declare const SKILL_TOOL_SCHEMA: {
             readonly type: "string";
             readonly description: "Replacement text for patch action.";
         };
+        readonly url: {
+            readonly type: "string";
+            readonly description: "URL to download a skill from (for 'install' action). Supports skill stores (skillhub.cn, skill.io, GitHub raw links, etc.) and any direct .md URL.";
+        };
     };
     readonly required: readonly ["action"];
 };
@@ -61,6 +67,8 @@ export interface SkillListItem {
     description: string;
     version?: string;
     category?: string;
+    /** Where the skill lives: "global" (user-level) or "project" (cwd-level). */
+    scope?: "global" | "project" | "plugin" | "config";
 }
 export interface SkillListOutput {
     skills: SkillListItem[];
@@ -91,11 +99,16 @@ export interface SkillToolDeps {
     manageSkill(params: {
         action: string;
         name: string;
+        category?: string;
         content?: string;
         filePath?: string;
         fileContent?: string;
         oldString?: string;
         newString?: string;
     }): Promise<SkillManageResult>;
+    /** Promote a project-level skill to user/global level. Returns success message. */
+    promoteSkill?(name: string): Promise<SkillManageResult>;
+    /** Install a skill from a URL. Downloads .md content and saves it. */
+    installSkill?(url: string, name?: string): Promise<SkillManageResult>;
 }
 export declare function createSkillMetaTool(deps: SkillToolDeps): PortableTool<SkillToolParams>;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "2.0.0",
+  "version": "2.2.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-store.d.ts

@@ -1,86 +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;
-    /** When true, mutations automatically persist to ~/.qlogicagent/memory.json */
-    persistToDisk?: boolean;
-}
-export interface MemoryStoreSerialized {
-    memory: string;
-    user: string;
-}
-export declare class MemoryStore {
-    private memoryEntries;
-    private userEntries;
-    private frozenSnapshot;
-    private snapshotFrozen;
-    private saveTimer;
-    private readonly memoryCharLimit;
-    private readonly userCharLimit;
-    private readonly persistToDisk;
-    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;
-    /**
-     * Load from disk (~/.qlogicagent/memory.json). No-op if file doesn't exist.
-     * Call this at startup when persistToDisk is enabled.
-     */
-    loadFromDisk(): Promise<void>;
-    /**
-     * Synchronous variant for use in sync constructors / init paths.
-     */
-    loadFromDiskSync(): void;
-    /**
-     * Schedule a debounced save to disk (500ms). Multiple rapid mutations
-     * coalesce into a single disk write.
-     */
-    private scheduleSave;
-    /** Flush any pending save immediately. Call before shutdown. */
-    flush(): Promise<void>;
-    /**
-     * 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/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>;

package/dist/types/skills/tools/skill-invoke-tool.d.ts

@@ -1,46 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-import type { WorkspaceSkill } from "../skill-system/skill-types.js";
-export declare const SKILL_TOOL_NAME: "skill_invoke";
-export interface SkillInvokeParams {
-    skill: string;
-    args?: string;
-}
-export declare const SKILL_INVOKE_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly skill: {
-            readonly type: "string";
-            readonly description: "Name of the skill to invoke. Use skill_list to see available skills.";
-        };
-        readonly args: {
-            readonly type: "string";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["skill"];
-};
-export interface SkillToolDeps {
-    /**
-     * Get all available skills (Layer 0 metadata).
-     * Returns name + description pairs for tool manifest enrichment.
-     */
-    listSkills(): WorkspaceSkill[];
-    /**
-     * Read skill content (Layer 1 instructions).
-     * Returns the full SKILL.md content for the named skill.
-     * Returns null if skill not found.
-     */
-    readSkillContent(name: string): Promise<string | null>;
-    /**
-     * Execute the skill instructions as a sub-turn.
-     * The implementation should:
-     *   1. Build system prompt from SKILL.md content
-     *   2. Run a sub-turn (fork) with skill instructions
-     *   3. Return the sub-turn's final response
-     *
-     * If not provided, the skill content is returned directly
-     * (the LLM can then follow the instructions in context).
-     */
-    executeSkillSubturn?(skillName: string, skillContent: string, userArgs: string | undefined, signal?: AbortSignal): Promise<string>;
-}
-export declare function createSkillTool(deps: SkillToolDeps): PortableTool<SkillInvokeParams>;

package/dist/types/skills/tools/skill-list-tool.d.ts

@@ -1,33 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const SKILL_LIST_TOOL_NAME: "skill_list";
-export interface SkillListToolParams {
-    category?: string;
-}
-export declare const SKILL_LIST_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly category: {
-            readonly type: "string";
-            readonly description: "Filter skills by category (e.g. 'devops', 'mlops'). Omit to list all.";
-        };
-    };
-    readonly required: readonly [];
-};
-export interface SkillListItem {
-    name: string;
-    description: string;
-    version?: string;
-    category?: string;
-}
-export interface SkillListOutput {
-    skills: SkillListItem[];
-    categories: string[];
-}
-/**
- * Host-provided skill registry for listing.
- */
-export interface SkillListToolDeps {
-    /** List all available skills, optionally filtered by category. */
-    listSkills(category?: string): Promise<SkillListOutput>;
-}
-export declare function createSkillListTool(deps: SkillListToolDeps): PortableTool<SkillListToolParams>;