qlogicagent 2.13.4 → 2.13.5

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

@@ -0,0 +1,106 @@
+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" | "promote";
+export interface SkillToolParams {
+    action: SkillAction;
+    name?: string;
+    args?: string;
+    category?: string;
+    content?: string;
+    filePath?: string;
+    fileContent?: string;
+    oldString?: string;
+    newString?: 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", "promote"];
+            readonly description: string;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Skill name (required for invoke/view/create/edit/patch/delete/promote).";
+        };
+        readonly args: {
+            readonly type: "string";
+            readonly description: "Arguments or context to pass when invoking a skill.";
+        };
+        readonly category: {
+            readonly type: "string";
+            readonly description: "Filter skills by category (for 'list' action).";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: "Full SKILL.md content for create/edit actions.";
+        };
+        readonly filePath: {
+            readonly type: "string";
+            readonly description: "Path of a file inside the skill folder: read it (view) or write it with fileContent (create/edit). SKILL.md itself always goes through 'content'.";
+        };
+        readonly fileContent: {
+            readonly type: "string";
+            readonly description: "Supporting file content. With filePath, writes that file inside the skill folder (create: alongside SKILL.md; edit: file-only update).";
+        };
+        readonly oldString: {
+            readonly type: "string";
+            readonly description: "Text to find for patch action.";
+        };
+        readonly newString: {
+            readonly type: "string";
+            readonly description: "Replacement text for patch action.";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface SkillListItem {
+    name: string;
+    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[];
+    categories: string[];
+}
+export interface SkillViewOutput {
+    name: string;
+    content: string;
+    referenceFiles?: string[];
+}
+export interface SkillManageResult {
+    success: boolean;
+    message: string;
+    path?: string;
+}
+export interface SkillToolDeps {
+    /** List all available skills (Layer 0 metadata). */
+    listSkills(): WorkspaceSkill[];
+    /** List skills with full detail (for list action). */
+    listSkillsFull(category?: string): Promise<SkillListOutput>;
+    /** Read skill content (Layer 1 instructions). */
+    readSkillContent(name: string): Promise<string | null>;
+    /** View skill with optional file path. */
+    viewSkill(name: string, filePath?: string): Promise<SkillViewOutput | null>;
+    /** Execute skill as sub-turn. */
+    executeSkillSubturn?(skillName: string, skillContent: string, userArgs: string | undefined, signal?: AbortSignal): Promise<string>;
+    /** Manage skill (create/edit/patch/delete). */
+    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>;
+}
+export declare function createSkillMetaTool(deps: SkillToolDeps): PortableTool<SkillToolParams>;

package/dist/skills/tools/skill-tool.js

@@ -0,0 +1,265 @@
+// ============================================================
+// Skill Tool — CC-aligned single meta-tool for all skill operations.
+//
+// CC reference: claude-code-haha/src/tools.ts (SkillTool)
+// CC keeps skills as ONE tool in the primary manifest.
+// Actions: invoke, list, view, create, edit, patch, delete, promote
+//
+// This replaces the 4 separate tools (skill_invoke, skill_list,
+// skill_view, skill_manage) with a single cognitive-load-friendly tool.
+// ============================================================
+export const SKILL_TOOL_NAME = "skill";
+export const SKILL_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["invoke", "list", "view", "create", "edit", "patch", "delete", "promote"],
+            description: [
+                "The operation to perform:",
+                "• 'invoke' — Run a skill by name (provide 'name', optional 'args')",
+                "• 'list' — List all available skills (optional 'category' filter)",
+                "• 'view' — View full skill content (provide 'name', optional 'filePath')",
+                "• 'create' — Create a new skill (provide 'name', 'content')",
+                "• 'edit' — Overwrite skill content (provide 'name', 'content')",
+                "• 'patch' — Find/replace in skill (provide 'name', 'oldString', 'newString')",
+                "• 'delete' — Remove a skill (provide 'name')",
+                "• 'promote' — Promote a project-level skill to global/user-level (provide 'name')",
+            ].join("\n"),
+        },
+        name: {
+            type: "string",
+            description: "Skill name (required for invoke/view/create/edit/patch/delete/promote).",
+        },
+        args: {
+            type: "string",
+            description: "Arguments or context to pass when invoking a skill.",
+        },
+        category: {
+            type: "string",
+            description: "Filter skills by category (for 'list' action).",
+        },
+        content: {
+            type: "string",
+            description: "Full SKILL.md content for create/edit actions.",
+        },
+        filePath: {
+            type: "string",
+            description: "Path of a file inside the skill folder: read it (view) or write it with fileContent (create/edit). SKILL.md itself always goes through 'content'.",
+        },
+        fileContent: {
+            type: "string",
+            description: "Supporting file content. With filePath, writes that file inside the skill folder (create: alongside SKILL.md; edit: file-only update).",
+        },
+        oldString: {
+            type: "string",
+            description: "Text to find for patch action.",
+        },
+        newString: {
+            type: "string",
+            description: "Replacement text for patch action.",
+        },
+    },
+    required: ["action"],
+};
+// ── Factory ─────────────────────────────────────────────────
+export function createSkillMetaTool(deps) {
+    return {
+        name: SKILL_TOOL_NAME,
+        label: "Skill",
+        category: "system",
+        description: buildDescription(deps),
+        parameters: SKILL_TOOL_SCHEMA,
+        isConcurrencySafe: false,
+        isReadOnly: false,
+        searchHint: "skill invoke list view create edit delete command workflow",
+        execute: async (_toolCallId, params, signal) => {
+            const { action } = params;
+            switch (action) {
+                case "invoke":
+                    return handleInvoke(deps, params, signal);
+                case "list":
+                    return handleList(deps, params);
+                case "view":
+                    return handleView(deps, params);
+                case "create":
+                case "edit":
+                case "patch":
+                case "delete":
+                    return handleManage(deps, params);
+                case "promote":
+                    return handlePromote(deps, params);
+                default:
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Unknown action: ${action}. Use invoke, list, view, create, edit, patch, delete, or promote.`,
+                            }],
+                    };
+            }
+        },
+    };
+}
+// ── Action handlers ─────────────────────────────────────────
+async function handleInvoke(deps, params, signal) {
+    const { name, args } = params;
+    if (!name) {
+        const available = deps.listSkills().map(s => s.name).join(", ");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Error: 'name' is required for invoke. Available skills: ${available || "(none)"}`,
+                }],
+        };
+    }
+    const content = await deps.readSkillContent(name);
+    if (!content) {
+        const available = deps.listSkills().map(s => s.name).join(", ");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Skill "${name}" not found. Available skills: ${available || "(none)"}`,
+                }],
+        };
+    }
+    if (deps.executeSkillSubturn) {
+        try {
+            const result = await deps.executeSkillSubturn(name, content, args, signal);
+            return {
+                content: [{ type: "text", text: result }],
+                details: { skillName: name, action: "invoke", mode: "subturn" },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Skill execution error: ${msg}` }],
+                details: { error: msg, skillName: name },
+            };
+        }
+    }
+    // Fallback: return skill content as inline instructions
+    const header = `## Skill: ${name}\n\n`;
+    const argsBlock = args ? `\n\n### User Context\n${args}` : "";
+    return {
+        content: [{
+                type: "text",
+                text: `${header}Follow these instructions:\n\n${content}${argsBlock}`,
+            }],
+        details: { skillName: name, action: "invoke", mode: "inline" },
+    };
+}
+async function handleList(deps, params) {
+    const output = await deps.listSkillsFull(params.category);
+    if (output.skills.length === 0) {
+        const msg = params.category
+            ? `No skills found in category "${params.category}".`
+            : "No skills available.";
+        return {
+            content: [{ type: "text", text: msg }],
+            details: { action: "list", count: 0 },
+        };
+    }
+    const lines = [`Available skills (${output.skills.length}):`];
+    if (output.categories.length > 0) {
+        lines.push(`Categories: ${output.categories.join(", ")}`);
+    }
+    lines.push("");
+    for (const s of output.skills) {
+        const cat = s.category ? ` [${s.category}]` : "";
+        const ver = s.version ? ` (v${s.version})` : "";
+        const scope = s.scope ? ` {${s.scope}}` : "";
+        lines.push(`- **${s.name}**${ver}${cat}${scope}: ${s.description}`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { action: "list", count: output.skills.length },
+    };
+}
+async function handleView(deps, params) {
+    if (!params.name) {
+        return {
+            content: [{ type: "text", text: "Error: 'name' is required for view." }],
+        };
+    }
+    const result = await deps.viewSkill(params.name, params.filePath);
+    if (!result) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Skill "${params.name}" not found. Use action: "list" to see available skills.`,
+                }],
+            details: { action: "view", error: "not_found" },
+        };
+    }
+    const lines = [`## Skill: ${result.name}\n`, result.content];
+    if (result.referenceFiles && result.referenceFiles.length > 0) {
+        lines.push(`\n### Reference Files\n${result.referenceFiles.map(f => `- ${f}`).join("\n")}`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { action: "view", name: result.name },
+    };
+}
+async function handleManage(deps, params) {
+    if (!params.name) {
+        return {
+            content: [{ type: "text", text: `Error: 'name' is required for ${params.action}.` }],
+        };
+    }
+    const result = await deps.manageSkill({
+        action: params.action,
+        name: params.name,
+        category: params.category,
+        content: params.content,
+        filePath: params.filePath,
+        fileContent: params.fileContent,
+        oldString: params.oldString,
+        newString: params.newString,
+    });
+    return {
+        content: [{ type: "text", text: result.message }],
+        details: { action: params.action, success: result.success, path: result.path },
+    };
+}
+// ── Promote handler ─────────────────────────────────────────
+async function handlePromote(deps, params) {
+    if (!params.name) {
+        return {
+            content: [{ type: "text", text: "Error: 'name' is required for promote." }],
+        };
+    }
+    if (!deps.promoteSkill) {
+        return {
+            content: [{
+                    type: "text",
+                    text: "Promote is not available in this configuration. Skills may already be at user-level.",
+                }],
+        };
+    }
+    const result = await deps.promoteSkill(params.name);
+    return {
+        content: [{ type: "text", text: result.message }],
+        details: { action: "promote", success: result.success, name: params.name },
+    };
+}
+// ── Helpers ─────────────────────────────────────────────────
+function buildDescription(deps) {
+    const skills = deps.listSkills();
+    const base = "Manage and invoke skills — reusable workflows and domain-specific knowledge packages. " +
+        "Use action: 'list' to discover skills, 'view' to read content, 'invoke' to run a skill. " +
+        "Skills can also be created, edited, patched, or deleted. " +
+        "Use 'promote' (with name) to copy a project skill to global (user-level) so it's available across all projects.\n\n" +
+        "CROSS-PROJECT RECALL: When you see '[Cross-project skill available]' in recalled memories, " +
+        "it means a relevant skill exists in another project. You should proactively inform the user " +
+        "and offer to use it (invoke) or promote it to global. Do not wait for explicit instructions — " +
+        "the user may not know the skill exists. Typical user signals: '之前做过', '参考XX项目', " +
+        "'didn't you do this before', 'same as the other project'.";
+    if (skills.length === 0)
+        return base;
+    const catalog = skills
+        .slice(0, 50)
+        .map((s) => `- ${s.name}: ${s.description ?? "(no description)"}`)
+        .join("\n");
+    return `${base}\n\nAvailable skills:\n${catalog}`;
+}

package/dist/skills/tools/sleep-tool.d.ts

@@ -0,0 +1,49 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SLEEP_TOOL_NAME: "sleep";
+export interface SleepToolParams {
+    /** Duration to sleep in seconds (1–3600). */
+    duration: number;
+    /** Reason for sleeping — helps the runtime decide whether to interrupt. */
+    reason?: string;
+}
+export declare const SLEEP_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly duration: {
+            readonly type: "number";
+            readonly description: "Duration to sleep in seconds (1–3600). Prefer short sleeps (10–60s) to stay responsive.";
+            readonly minimum: 1;
+            readonly maximum: 3600;
+        };
+        readonly reason: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["duration"];
+};
+/** The result returned after a sleep completes or is interrupted. */
+export interface SleepResult {
+    /** Actual time slept in seconds (may be less if interrupted). */
+    sleptSeconds: number;
+    /** Whether the sleep was interrupted before completing. */
+    interrupted: boolean;
+    /** The event that caused the interruption (undefined if not interrupted). */
+    interruptReason?: string;
+}
+/**
+ * Runtime dependencies injected by the host.
+ *
+ * The sleep mechanism is host-provided — the tool itself does NOT call
+ * setTimeout. The host decides how to implement the wait (timer, event loop
+ * integration, tick prompt scheduling, etc.).
+ */
+export interface SleepToolDeps {
+    /**
+     * Perform the actual sleep. Must resolve after `durationMs` or when
+     * interrupted (whichever is first). The AbortSignal fires if the user
+     * or the system requests an interrupt.
+     */
+    sleep(durationMs: number, signal: AbortSignal): Promise<SleepResult>;
+}
+export declare function createSleepTool(deps: SleepToolDeps): PortableTool<SleepToolParams>;

package/dist/skills/tools/sleep-tool.js

@@ -0,0 +1,81 @@
+// ============================================================
+// Sleep Tool — lightweight wait with tick/interrupt support.
+// Reference: claude-code-haha/src/tools/SleepTool/prompt.ts
+// Category: autonomous / proactive mode
+// ============================================================
+export const SLEEP_TOOL_NAME = "sleep";
+export const SLEEP_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        duration: {
+            type: "number",
+            description: "Duration to sleep in seconds (1–3600). Prefer short sleeps (10–60s) to stay responsive.",
+            minimum: 1,
+            maximum: 3600,
+        },
+        reason: {
+            type: "string",
+            description: "Brief reason for sleeping. Examples: \"waiting for build to finish\", " +
+                "\"nothing to do\", \"user asked to rest\".",
+        },
+    },
+    required: ["duration"],
+};
+export function createSleepTool(deps) {
+    return {
+        name: SLEEP_TOOL_NAME,
+        label: "Sleep",
+        shouldDefer: true,
+        isConcurrencySafe: true,
+        isReadOnly: true,
+        searchHint: "wait sleep rest idle tick proactive 等待 休眠 暂停",
+        description: [
+            "Wait for a specified duration. The user can interrupt the sleep at any time.",
+            "",
+            "Use this when:",
+            "• You have nothing useful to do right now",
+            "• You're waiting for an external process to complete",
+            "• The user tells you to sleep or rest",
+            "• You receive a <tick> check-in with no actionable work",
+            "",
+            "Prefer this over `exec(sleep ...)` — it doesn't hold a shell process.",
+            "You can call this concurrently with other tools — it won't interfere with them.",
+            "",
+            "Each wake-up costs an API call, but the prompt cache expires after 5 minutes " +
+                "of inactivity — balance accordingly.",
+        ].join("\n"),
+        parameters: SLEEP_TOOL_SCHEMA,
+        execute: async (_toolCallId, params, signal) => {
+            const durationSec = Math.max(1, Math.min(3600, Math.round(params.duration)));
+            const durationMs = durationSec * 1000;
+            // Create a child AbortController so we can forward the outer signal
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            // Handle pre-aborted signal
+            if (signal?.aborted)
+                controller.abort();
+            try {
+                const result = await deps.sleep(durationMs, controller.signal);
+                const lines = [];
+                if (result.interrupted) {
+                    lines.push(`Sleep interrupted after ${result.sleptSeconds}s.`);
+                    if (result.interruptReason) {
+                        lines.push(`Reason: ${result.interruptReason}`);
+                    }
+                    lines.push("Check for new messages or tasks.");
+                }
+                else {
+                    lines.push(`Slept for ${result.sleptSeconds}s. Waking up.`);
+                }
+                return {
+                    content: [{ type: "text", text: lines.join("\n") }],
+                    details: { ...result, requestedSeconds: durationSec },
+                };
+            }
+            finally {
+                signal?.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}

package/dist/skills/tools/structured-output-tool.d.ts

@@ -0,0 +1,116 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const STRUCTURED_OUTPUT_TOOL_NAME: "structured_output";
+/** Maximum content size for structured output results. */
+export declare const STRUCTURED_OUTPUT_MAX_CHARS = 100000;
+export interface StructuredOutputToolParams {
+    /** The structured data to return. Must conform to the session's output schema. */
+    data: Record<string, unknown>;
+}
+/**
+ * Base schema — accepts any object.
+ * When used with createConfiguredStructuredOutputTool, the host overrides
+ * this with the actual JSON Schema from `response_format.json_schema`.
+ */
+export declare const STRUCTURED_OUTPUT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly data: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: true;
+        };
+    };
+    readonly required: readonly ["data"];
+};
+/** Schema validation error detail. */
+export interface SchemaValidationError {
+    path: string;
+    message: string;
+    keyword?: string;
+}
+/** Result of structured output validation. */
+export interface StructuredOutputResult {
+    valid: boolean;
+    errors?: SchemaValidationError[];
+}
+/**
+ * Whether the structured output tool should be enabled for this session.
+ * CC equivalent: `isSyntheticOutputToolEnabled`.
+ */
+export declare function isStructuredOutputEnabled(opts: {
+    isNonInteractiveSession: boolean;
+}): boolean;
+/**
+ * Runtime dependencies injected by the host.
+ *
+ * The host provides:
+ * 1. The JSON Schema to validate against (from session config)
+ * 2. A validator function (host may use Ajv, Zod, or any validator)
+ * 3. An output sink to deliver the validated data
+ *
+ * The tool is only available in non-interactive (SDK/API) sessions
+ * where a `response_format.json_schema` has been specified.
+ */
+export interface StructuredOutputToolDeps {
+    /**
+     * Get the JSON Schema that the output must conform to.
+     * Returns undefined if no schema is configured (tool should not be registered).
+     */
+    getOutputSchema(): Record<string, unknown> | undefined;
+    /**
+     * Validate data against the output schema.
+     * Returns { valid: true } or { valid: false, errors: [...] }.
+     */
+    validateOutput(data: Record<string, unknown>): StructuredOutputResult;
+    /**
+     * Deliver the validated output to the caller.
+     * Called only after successful validation.
+     */
+    deliverOutput(data: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Create the base structured output tool with DI-based validation.
+ * This is the standard factory for runtime integration.
+ */
+export declare function createStructuredOutputTool(deps: StructuredOutputToolDeps): PortableTool<StructuredOutputToolParams>;
+/**
+ * Result of creating a configured structured output tool.
+ * Success: { tool } — ready-to-use tool with compiled schema.
+ * Failure: { error } — schema was invalid.
+ */
+export type ConfiguredToolResult = {
+    tool: PortableTool<StructuredOutputToolParams>;
+} | {
+    error: string;
+};
+/**
+ * Host-provided schema compilation interface.
+ * Allows the host to use any validator (Ajv, Zod, custom).
+ */
+export interface SchemaCompiler {
+    /**
+     * Validate that the schema itself is a valid JSON Schema.
+     * Returns null if valid, or an error message string if invalid.
+     */
+    validateSchema(schema: Record<string, unknown>): string | null;
+    /**
+     * Compile the schema into a reusable validator function.
+     * Returns a function that validates data and returns StructuredOutputResult.
+     */
+    compile(schema: Record<string, unknown>): (data: Record<string, unknown>) => StructuredOutputResult;
+}
+/**
+ * Create a StructuredOutputTool configured with a specific JSON Schema.
+ * Mirrors CC's `createSyntheticOutputTool(jsonSchema)`.
+ *
+ * Features:
+ * - Validates the schema itself at creation time
+ * - Compiles the validator for reuse (cached via WeakMap)
+ * - Overrides the tool's `parameters` with the provided schema (dynamic input)
+ * - Returns { tool } on success or { error } if schema is invalid
+ *
+ * @param jsonSchema  The JSON Schema to validate output against.
+ * @param compiler    Schema compiler/validator provided by the host.
+ * @param deliver     Output delivery function (called after successful validation).
+ */
+export declare function createConfiguredStructuredOutputTool(jsonSchema: Record<string, unknown>, compiler: SchemaCompiler, deliver: (data: Record<string, unknown>) => Promise<void>): ConfiguredToolResult;