qlogicagent 0.5.2 → 0.6.0

package/dist/types/skills/tools/music-generate-tool.d.ts

@@ -0,0 +1,55 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const MUSIC_GENERATE_TOOL_NAME: "music_generate";
+export interface MusicGenerateToolParams {
+    prompt: string;
+    purpose?: string;
+    style?: string;
+    lyrics?: string;
+    duration?: number;
+}
+export declare const MUSIC_GENERATE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: "Intended use: 'background-music', 'ringtone', 'short-video-bgm', 'full-song', 'notification-sound', etc.";
+        };
+        readonly style: {
+            readonly type: "string";
+            readonly description: "Musical style/genre: 'lo-fi', 'pop', 'rock', 'jazz', 'classical', 'electronic', 'ambient', etc.";
+        };
+        readonly lyrics: {
+            readonly type: "string";
+            readonly description: "Optional lyrics for vocal music. Structure with [verse], [chorus], [bridge] tags if desired.";
+        };
+        readonly duration: {
+            readonly type: "number";
+            readonly description: "Duration in seconds (5-300). Infer from purpose: ringtone 15-30s, BGM 30-60s, full song 120-180s.";
+        };
+    };
+    readonly required: readonly ["prompt"];
+};
+export interface MusicGenerateResult {
+    mediaUrls: string[];
+    model?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for music generation. */
+export interface MusicGenerateToolDeps {
+    /**
+     * Generate music via the configured backend.
+     * The host handles model selection, failover, and storage.
+     */
+    generateMusic(params: {
+        prompt: string;
+        purpose?: string;
+        style?: string;
+        lyrics?: string;
+        duration?: number;
+    }): Promise<MusicGenerateResult>;
+}
+export declare function createMusicGenerateTool(deps: MusicGenerateToolDeps): PortableTool<MusicGenerateToolParams>;

package/dist/types/skills/tools/notebook-edit-tool.d.ts

@@ -0,0 +1,15 @@
+import type { PortableTool } from "../portable-tool.js";
+export type NotebookEditMode = "replace" | "insert" | "delete";
+export interface NotebookEditParams {
+    /** Absolute path to the .ipynb file */
+    notebook_path: string;
+    /** Cell number (1-based) to operate on */
+    cell_number: number;
+    /** New cell source content (required for replace/insert) */
+    new_source?: string;
+    /** Cell type for insert (default: "code") */
+    cell_type?: "code" | "markdown";
+    /** Edit mode (default: "replace") */
+    edit_mode?: NotebookEditMode;
+}
+export declare function createNotebookEditTool(): PortableTool<NotebookEditParams>;

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

@@ -0,0 +1,53 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const NOTIFY_TOOL_NAME: "notify";
+export interface NotifyToolParams {
+    /** Notification message */
+    message: string;
+    /** Optional title/subject */
+    title?: string;
+    /** Priority level */
+    priority?: "low" | "normal" | "high";
+    /** Target channel override (default: user's primary channel) */
+    channel?: string;
+}
+export declare const NOTIFY_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Notification content to send to the user.";
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly description: "Optional notification title/subject line.";
+        };
+        readonly priority: {
+            readonly type: "string";
+            readonly enum: readonly ["low", "normal", "high"];
+            readonly description: "Notification priority (default: normal). High may trigger sound/vibration.";
+        };
+        readonly channel: {
+            readonly type: "string";
+            readonly description: "Target delivery channel (e.g. 'wechat', 'feishu', 'discord'). Default: user's primary.";
+        };
+    };
+    readonly required: readonly ["message"];
+};
+export interface NotifyResult {
+    delivered: boolean;
+    channel: string;
+    error?: string;
+}
+/**
+ * Host-provided notification delivery backend.
+ */
+export interface NotifyToolDeps {
+    /** Send notification to user. Host routes to correct platform. */
+    sendNotification(params: {
+        message: string;
+        title?: string;
+        priority?: string;
+        channel?: string;
+    }): Promise<NotifyResult>;
+}
+export declare function createNotifyTool(deps: NotifyToolDeps): PortableTool<NotifyToolParams>;

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

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const PATCH_TOOL_NAME: "patch";
+export interface PatchToolParams {
+    /** V4A unified diff or simple find-replace */
+    input: string;
+    /** When true, replace all occurrences in each file (default: false) */
+    replaceAll?: boolean;
+}
+export declare const PATCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly input: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly replaceAll: {
+            readonly type: "boolean";
+            readonly description: "Replace all occurrences instead of first only (default: false).";
+        };
+    };
+    readonly required: readonly ["input"];
+};
+export interface PatchResult {
+    filesModified: string[];
+    filesAdded: string[];
+    filesDeleted: string[];
+    strategies: Record<string, string>;
+    errors: string[];
+}
+export interface PatchToolDeps {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    fileExists(path: string): Promise<boolean>;
+    resolvePath(input: string): string;
+}
+export type MatchStrategy = "exact" | "line_trimmed" | "whitespace_normalized" | "indentation_flexible" | "escape_normalized" | "trimmed_boundary" | "unicode_normalized" | "block_anchor" | "context_aware";
+interface MatchResult {
+    start: number;
+    end: number;
+    strategy: MatchStrategy;
+}
+declare function fuzzyFind(content: string, search: string, replaceAll: boolean): MatchResult[];
+export declare function createPatchTool(deps: PatchToolDeps): PortableTool<PatchToolParams>;
+export { fuzzyFind, type MatchResult };

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

@@ -0,0 +1,98 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const PLAN_MODE_TOOL_NAME: "plan_mode";
+export type PlanModeAction = "enter" | "exit";
+export interface PlanModeToolParams {
+    /** Action: enter or exit plan mode */
+    action: PlanModeAction;
+    /** Plan text (for exit — the finalized plan to present for approval) */
+    plan?: string;
+    /** File path where plan was saved (optional) */
+    planFilePath?: string;
+    /**
+     * Semantic permissions to request on exit (CC ExitPlanModeV2 parity).
+     * Each entry describes a tool + intent the agent wants permission for.
+     */
+    allowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+export declare const PLAN_MODE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["enter", "exit"];
+            readonly description: string;
+        };
+        readonly plan: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly planFilePath: {
+            readonly type: "string";
+            readonly description: "Optional file path where the plan was saved for reference.";
+        };
+        readonly allowedPrompts: {
+            readonly type: "array";
+            readonly description: string;
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly tool: {
+                        readonly type: "string";
+                        readonly description: "Tool name to pre-approve.";
+                    };
+                    readonly prompt: {
+                        readonly type: "string";
+                        readonly description: "Intent description for this permission.";
+                    };
+                };
+                readonly required: readonly ["tool", "prompt"];
+            };
+        };
+    };
+    readonly required: readonly ["action"];
+};
+/** Tools allowed during plan mode (read-only + reasoning) */
+export declare const PLAN_MODE_ALLOWED_TOOLS: readonly string[];
+export interface PlanModeState {
+    active: boolean;
+    enteredAt?: string;
+    plan?: string;
+    planFilePath?: string;
+}
+export interface PlanModeResult {
+    success: boolean;
+    state: PlanModeState;
+    allowedTools?: readonly string[];
+    error?: string;
+}
+/**
+ * Host-provided plan mode backend.
+ * The host is responsible for filtering tool availability based on mode state.
+ */
+export interface PlanModeToolDeps {
+    /** Get current plan mode state */
+    getState(): PlanModeState;
+    /** Enter plan mode — host should restrict tool availability */
+    enterPlanMode(): Promise<PlanModeResult>;
+    /** Exit plan mode — host restores full tool availability */
+    exitPlanMode(plan?: string, planFilePath?: string): Promise<PlanModeResult>;
+    /** Check if in agent/sub-agent context (plan mode not allowed in sub-agents) */
+    isAgentContext?(): boolean;
+    /**
+     * Request approval for the plan from the user/coordinator.
+     * CC parity: ExitPlanModeV2 triggers an approval dialog on exit.
+     * Returns true if approved, false if rejected.
+     */
+    requestPlanApproval?(plan: string, allowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>): Promise<boolean>;
+    /**
+     * Persist plan to disk (CC parity: plan is saved to planFilePath).
+     */
+    persistPlan?(plan: string, filePath: string): Promise<void>;
+}
+export declare function createPlanModeTool(deps: PlanModeToolDeps): PortableTool<PlanModeToolParams>;

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

@@ -0,0 +1,51 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const READ_TOOL_NAME: "read";
+export interface ReadToolParams {
+    path: string;
+    offset?: number;
+    limit?: number;
+}
+export declare const READ_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Absolute path to the file to read.";
+        };
+        readonly offset: {
+            readonly type: "number";
+            readonly description: "Line number to start reading from (1-indexed). Default: 1.";
+        };
+        readonly limit: {
+            readonly type: "number";
+            readonly description: "Maximum number of lines to read. Default/max: 2000.";
+        };
+    };
+    readonly required: readonly ["path"];
+};
+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. */
+    readFile(path: string): Promise<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        base64: string;
+        mimeType: string;
+    } | {
+        type: "binary";
+        mimeType: string;
+    }>;
+    /** Resolve a relative path to absolute. */
+    resolvePath(input: string): string;
+    /**
+     * Validate read access for the given path.
+     * Returns null if allowed, or an error message if blocked.
+     * Blocks device paths (/dev/zero, /dev/random, etc.) and
+     * paths outside the allowed workspace.
+     */
+    validatePath?(path: string): string | null;
+}
+export declare function createReadTool(deps: ReadToolDeps): PortableTool<ReadToolParams>;

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

@@ -0,0 +1,70 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const REPL_TOOL_NAME: "repl";
+export interface ReplToolParams {
+    /** JavaScript code to execute in the persistent VM context */
+    code: string;
+}
+export declare const REPL_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["code"];
+};
+export interface ReplExecResult {
+    output: string;
+    error?: string;
+    duration: number;
+}
+/** Primitive operations injected into the VM context. */
+export interface ReplPrimitives {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    editFile(path: string, edits: Array<{
+        oldText: string;
+        newText: string;
+    }>): Promise<string>;
+    exec(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    glob(pattern: string): Promise<string[]>;
+    grep(pattern: string, path?: string): Promise<Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>>;
+}
+/**
+ * Host-provided REPL execution backend.
+ */
+export interface ReplToolDeps {
+    /**
+     * Execute JavaScript code within a persistent VM context.
+     * The VM is pre-initialized with the primitive functions above.
+     * Each tool invocation reuses the same VM (preserving variable state).
+     */
+    executeInVm(code: string): Promise<ReplExecResult>;
+    /**
+     * Reset the VM context (clear state). Optional hook called on errors.
+     */
+    resetVm?(): void;
+    /**
+     * The host-provided primitives injected into the VM.
+     * When provided, the tool validates that the host has set up all required primitives.
+     */
+    primitives?: ReplPrimitives;
+    /**
+     * Permission check for individual primitive operations.
+     * Called before each primitive executes inside the VM.
+     * Returns null if allowed, or an error message if denied.
+     */
+    checkPermission?(operation: string, args: unknown[]): Promise<string | null>;
+}
+/** Tool names that should be hidden from direct LLM access when REPL is active. */
+export declare const REPL_HIDES_TOOLS: readonly string[];
+export declare function createReplTool(deps: ReplToolDeps): PortableTool<ReplToolParams>;

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

@@ -0,0 +1,112 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SEARCH_TOOL_NAME: "search";
+export type SearchMode = "filename" | "content" | "both";
+export interface SearchToolParams {
+    mode: SearchMode;
+    pattern: string;
+    path?: string;
+    fileGlob?: string;
+    contextLines?: number;
+    caseInsensitive?: boolean;
+    headLimit?: number;
+    offset?: number;
+}
+export declare const SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly mode: {
+            readonly type: "string";
+            readonly enum: readonly ["filename", "content", "both"];
+            readonly description: string;
+        };
+        readonly pattern: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Directory to search in. Defaults to workdir/cwd if omitted.";
+        };
+        readonly fileGlob: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly contextLines: {
+            readonly type: "number";
+            readonly description: string;
+        };
+        readonly caseInsensitive: {
+            readonly type: "boolean";
+            readonly description: "Case insensitive search (content/both modes). Default: false.";
+        };
+        readonly headLimit: {
+            readonly type: "number";
+            readonly description: string;
+        };
+        readonly offset: {
+            readonly type: "number";
+            readonly description: "Skip first N results before applying headLimit. Default: 0.";
+        };
+    };
+    readonly required: readonly ["mode", "pattern"];
+};
+export interface SearchFileResult {
+    path: string;
+}
+export interface SearchContentResult {
+    path: string;
+    line: number;
+    text: string;
+    contextBefore?: string[];
+    contextAfter?: string[];
+}
+export interface SearchOutput {
+    mode: SearchMode;
+    totalMatches: number;
+    truncated: boolean;
+    fileResults?: SearchFileResult[];
+    contentResults?: SearchContentResult[];
+}
+/** Host-provided search backend. */
+export interface SearchToolDeps {
+    /**
+     * Find files matching a glob pattern.
+     * Returns array of relative file paths.
+     * The host SHOULD auto-exclude VCS directories (.git, .svn, .hg, .bzr)
+     * unless the user explicitly includes them.
+     */
+    glob(pattern: string, options: {
+        cwd: string;
+        limit: number;
+    }): Promise<{
+        files: string[];
+        truncated: boolean;
+    }>;
+    /**
+     * Search file contents using regex.
+     * The implementation may use ripgrep, native grep, or a custom engine.
+     * Returns match records.
+     * The host SHOULD auto-exclude VCS directories (.git, .svn, .hg, .bzr)
+     * and enforce --max-columns 500 to avoid minified file noise.
+     */
+    grep(pattern: string, options: {
+        cwd: string;
+        fileGlob?: string;
+        caseInsensitive?: boolean;
+        contextLines?: number;
+        headLimit?: number;
+        offset?: number;
+    }): Promise<{
+        matches: Array<{
+            path: string;
+            line: number;
+            text: string;
+            contextBefore?: string[];
+            contextAfter?: string[];
+        }>;
+        truncated: boolean;
+    }>;
+    /** Resolve relative path to absolute. If omitted, cwd is used. */
+    resolvePath?(input: string): string;
+}
+export declare function createSearchTool(deps: SearchToolDeps): PortableTool<SearchToolParams>;

package/dist/types/skills/tools/send-message-tool.d.ts

@@ -0,0 +1,51 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const SEND_MESSAGE_TOOL_NAME: "send_message";
+export interface SendMessageToolParams {
+    /** Target agent name or '*' for broadcast */
+    to: string;
+    /** Message content */
+    message: string;
+    /** Optional short summary for routing/display */
+    summary?: string;
+}
+export declare const SEND_MESSAGE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly to: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Message content to send to the target agent.";
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly description: "Optional short summary (for logging/routing).";
+        };
+    };
+    readonly required: readonly ["to", "message"];
+};
+export interface SendMessageResult {
+    success: boolean;
+    recipients?: string[];
+    error?: string;
+}
+/**
+ * Host-provided message routing backend.
+ * Messages are delivered asynchronously via mailbox pattern.
+ */
+export interface SendMessageToolDeps {
+    /** Send message to target agent(s). Returns delivery status. */
+    sendMessage(params: {
+        to: string;
+        message: string;
+        summary?: string;
+        senderId: string;
+    }): Promise<SendMessageResult>;
+    /** Get the current agent's ID */
+    getSenderId(): string;
+    /** List available teammates */
+    listTeammates?(): string[];
+}
+export declare function createSendMessageTool(deps: SendMessageToolDeps): PortableTool<SendMessageToolParams>;

package/dist/types/skills/tools/shell/bash-provider.d.ts

@@ -0,0 +1,26 @@
+import type { ShellProvider } from "./shell-provider.js";
+export interface BashProviderOptions {
+    /**
+     * Absolute path to a pre-saved shell snapshot file.
+     * If provided, will be `source`d before every command
+     * to restore environment (virtualenvs, PATHs, etc.).
+     */
+    snapshotFilePath?: string;
+    /**
+     * Script fragment that sets session-specific env vars.
+     * Injected between snapshot sourcing and command execution.
+     */
+    sessionEnvScript?: string;
+}
+/**
+ * Create a bash ShellProvider.
+ *
+ * @param shellPath Absolute path to bash (e.g. `/bin/bash`, `/usr/bin/bash`)
+ * @param options   Optional snapshot / session env
+ */
+export declare function createBashProvider(shellPath: string, options?: BashProviderOptions): ShellProvider;
+/**
+ * Update the snapshot file path at runtime (e.g. after re-snapshotting).
+ * This is a convenience — in practice the provider is re-created infrequently.
+ */
+export declare function updateSnapshot(provider: ShellProvider, snapshotFilePath: string | undefined): void;

package/dist/types/skills/tools/shell/command-classification.d.ts

@@ -0,0 +1,44 @@
+/** Commands that search/find content (collapsible in UI). */
+export declare const SEARCH_COMMANDS: Set<string>;
+/** Commands that read/display file content (collapsible in UI). */
+export declare const READ_COMMANDS: Set<string>;
+/** Commands that list directory contents. */
+export declare const LIST_COMMANDS: Set<string>;
+/**
+ * Commands that are semantically neutral — they don't interact
+ * with the file system in a meaningful way. Skipped when
+ * classifying piped commands.
+ */
+export declare const SEMANTIC_NEUTRAL_COMMANDS: Set<string>;
+/**
+ * Commands that produce no stdout on success.
+ * For these, the tool shows "Done" instead of "(No output)".
+ */
+export declare const SILENT_COMMANDS: Set<string>;
+export interface CommandClassification {
+    /** First "real" command word (after env vars / wrappers). */
+    firstCommand: string | null;
+    /** Whether the command is search-like (find, grep, etc.). */
+    isSearch: boolean;
+    /** Whether the command only reads (cat, head, stat, etc.). */
+    isRead: boolean;
+    /** Whether the command lists files (ls, tree, du). */
+    isList: boolean;
+    /** Whether the command is expected to produce no stdout. */
+    isSilent: boolean;
+    /** Whether the command is safe to run in parallel with others. */
+    isConcurrencySafe: boolean;
+    /** Whether the command only reads state (never mutates). */
+    isReadOnly: boolean;
+}
+/**
+ * Check whether a command has any `cd` or pushd/popd that changes CWD.
+ * Ported from cc's `commandHasAnyCd()`.
+ */
+export declare function commandHasAnyCd(command: string): boolean;
+/**
+ * Classify a shell command.
+ *
+ * Mirrors cc's `isSearchOrReadBashCommand()` + `isSilentBashCommand()`.
+ */
+export declare function classifyCommand(command: string): CommandClassification;

package/dist/types/skills/tools/shell/command-semantics.d.ts

@@ -0,0 +1,14 @@
+export interface CommandSemanticResult {
+    isError: boolean;
+    message?: string;
+}
+/**
+ * Interpret a command's exit code using semantic rules.
+ *
+ * @param command - The shell command that was executed
+ * @param exitCode - The process exit code
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @returns Semantic interpretation (isError + optional message)
+ */
+export declare function interpretCommandResult(command: string, exitCode: number, stdout: string, stderr: string): CommandSemanticResult;

package/dist/types/skills/tools/shell/destructive-command-warning.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check a bash/sh command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export declare function getDestructiveCommandWarning(command: string): string | null;
+/**
+ * Check a PowerShell command for destructive patterns.
+ * Returns the first matching warning, or null.
+ */
+export declare function getPowerShellDestructiveCommandWarning(command: string): string | null;