qlogicagent 0.5.2 → 0.5.3

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

@@ -0,0 +1,51 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const TOOL_SEARCH_TOOL_NAME: "tool_search";
+export interface ToolSearchToolParams {
+    query: string;
+    maxResults?: number;
+}
+export declare const TOOL_SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly maxResults: {
+            readonly type: "number";
+            readonly description: "Maximum number of results to return (default: 5).";
+        };
+    };
+    readonly required: readonly ["query"];
+};
+export interface DeferredToolInfo {
+    name: string;
+    description: string;
+    /** Optional search hint for better discovery */
+    searchHint?: string;
+}
+export interface ToolSearchOutput {
+    matches: DeferredToolInfo[];
+    query: string;
+    totalDeferred: number;
+}
+/**
+ * Host-provided deferred tool registry.
+ * The host manages which tools are loaded vs deferred,
+ * and handles activation when selected.
+ */
+export interface ToolSearchToolDeps {
+    /**
+     * Search deferred tools by query.
+     * Supports "select:name" for direct activation and keyword search.
+     */
+    searchTools(query: string, options?: {
+        maxResults?: number;
+    }): Promise<ToolSearchOutput>;
+    /**
+     * Activate a deferred tool so it appears in subsequent turns.
+     * Returns true if activation succeeded.
+     */
+    activateTool?(name: string): Promise<boolean>;
+}
+export declare function createToolSearchTool(deps: ToolSearchToolDeps): PortableTool<ToolSearchToolParams>;

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

@@ -0,0 +1,38 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const TTS_TOOL_NAME: "tts";
+export interface TtsToolParams {
+    text: string;
+    channel?: string;
+}
+export declare const TTS_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly text: {
+            readonly type: "string";
+            readonly description: "Text to convert to speech.";
+        };
+        readonly channel: {
+            readonly type: "string";
+            readonly description: "Optional channel id to pick output format (e.g. telegram).";
+        };
+    };
+    readonly required: readonly ["text"];
+};
+export interface TtsResult {
+    audioPath: string;
+    provider?: string;
+    voiceCompatible?: boolean;
+    mediaUrls: string[];
+}
+/** Deps injected by the host runtime for TTS. */
+export interface TtsToolDeps {
+    /**
+     * Convert text to speech via the configured backend.
+     * The host handles voice selection, format conversion, and storage.
+     */
+    textToSpeech(params: {
+        text: string;
+        channel?: string;
+    }): Promise<TtsResult>;
+}
+export declare function createTtsTool(deps: TtsToolDeps): PortableTool<TtsToolParams>;

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

@@ -0,0 +1,69 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const VIDEO_EDIT_TOOL_NAME: "video_edit";
+export interface VideoEditToolParams {
+    prompt: string;
+    source_videos: string[];
+    reference_images?: string[];
+    duration?: number;
+    aspect_ratio?: string;
+    resolution?: string;
+}
+export declare const VIDEO_EDIT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly source_videos: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly minItems: 1;
+            readonly maxItems: 3;
+            readonly description: "Video(s) to edit (1-3 URLs). Order: [0]=视频1, [1]=视频2, [2]=视频3.";
+        };
+        readonly reference_images: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Optional reference images for element replacement (up to 9).";
+        };
+        readonly duration: {
+            readonly type: "number";
+            readonly description: "Output duration in seconds (4-15s). Default: same as source.";
+        };
+        readonly aspect_ratio: {
+            readonly type: "string";
+            readonly description: "Output aspect ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9. Default: same as source.";
+        };
+        readonly resolution: {
+            readonly type: "string";
+            readonly description: "Output resolution: '480p' or '720p'. Default: '720p'.";
+        };
+    };
+    readonly required: readonly ["prompt", "source_videos"];
+};
+export interface VideoEditResult {
+    mediaUrls: string[];
+    model?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for video editing. */
+export interface VideoEditToolDeps {
+    /**
+     * Edit a video via the configured backend (Seedance 2.0, etc.).
+     * The host handles URL resolution, model routing, and storage.
+     */
+    editVideo(params: {
+        prompt: string;
+        sourceVideos: string[];
+        referenceImages?: string[];
+        duration?: number;
+        aspectRatio?: string;
+        resolution?: string;
+    }): Promise<VideoEditResult>;
+}
+export declare function createVideoEditTool(deps: VideoEditToolDeps): PortableTool<VideoEditToolParams>;

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

@@ -0,0 +1,62 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const VIDEO_GENERATE_TOOL_NAME: "video_generate";
+export interface VideoGenerateToolParams {
+    prompt: string;
+    purpose?: string;
+    style?: string;
+    image_url?: string;
+    aspect_ratio?: string;
+    duration?: number;
+}
+export declare const VIDEO_GENERATE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "Video generation prompt. MUST be in English. Include scene, movement, camera motion, lighting, style.";
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: "Intended use: 'social-media', 'short-video', 'presentation', etc.";
+        };
+        readonly style: {
+            readonly type: "string";
+            readonly description: "Visual style: 'cinematic', 'anime', 'watercolor', etc.";
+        };
+        readonly image_url: {
+            readonly type: "string";
+            readonly description: "Reference image for image-to-video. Preview image from storyboard Step 3, or user-uploaded image.";
+        };
+        readonly aspect_ratio: {
+            readonly type: "string";
+            readonly description: "Video aspect ratio: '9:16' (vertical), '16:9' (horizontal), '1:1' (square). Default: '16:9'.";
+        };
+        readonly duration: {
+            readonly type: "number";
+            readonly description: "Video duration in seconds (3-10s single-shot, >10s requires multi-shot workflow). Must be confirmed by user.";
+        };
+    };
+    readonly required: readonly ["prompt"];
+};
+export interface VideoGenerateResult {
+    mediaUrls: string[];
+    model?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for video generation. */
+export interface VideoGenerateToolDeps {
+    /**
+     * Generate a video clip via the configured backend.
+     * The host handles model selection, duration snapping, failover,
+     * watermark, and local storage.
+     */
+    generateVideo(params: {
+        prompt: string;
+        purpose?: string;
+        style?: string;
+        imageUrl?: string;
+        aspectRatio?: string;
+        duration?: number;
+    }): Promise<VideoGenerateResult>;
+}
+export declare function createVideoGenerateTool(deps: VideoGenerateToolDeps): PortableTool<VideoGenerateToolParams>;

package/dist/types/skills/tools/video-merge-tool.d.ts

@@ -0,0 +1,105 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const VIDEO_MERGE_TOOL_NAME: "video_merge";
+export interface VideoMergeClip {
+    video: string;
+    audio?: string;
+    trimStart?: number;
+    trimEnd?: number;
+}
+export interface VideoMergeToolParams {
+    clips: VideoMergeClip[];
+    transition?: string;
+    transitionDuration?: number;
+    subtitles?: string;
+    bgm?: string;
+    bgmVolume?: number;
+    outputResolution?: string;
+    outputFps?: number;
+}
+export declare const VIDEO_MERGE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly clips: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly video: {
+                        readonly type: "string";
+                        readonly description: "Video file path.";
+                    };
+                    readonly audio: {
+                        readonly type: "string";
+                        readonly description: "Narration audio file path (from TTS).";
+                    };
+                    readonly trimStart: {
+                        readonly type: "number";
+                        readonly description: "Trim start in seconds (default 0).";
+                    };
+                    readonly trimEnd: {
+                        readonly type: "number";
+                        readonly description: "Trim end in seconds (default: full).";
+                    };
+                };
+                readonly required: readonly ["video"];
+            };
+            readonly minItems: 2;
+            readonly description: "Array of video clips to merge, in order.";
+        };
+        readonly transition: {
+            readonly type: "string";
+            readonly description: "Transition effect: 'crossfade' (default), 'fade', 'wipeleft', 'cut', 'dissolve', etc.";
+        };
+        readonly transitionDuration: {
+            readonly type: "number";
+            readonly description: "Transition duration in seconds (0.1-2.0, default 0.5).";
+        };
+        readonly subtitles: {
+            readonly type: "string";
+            readonly description: "Path to SRT subtitle file to burn-in.";
+        };
+        readonly bgm: {
+            readonly type: "string";
+            readonly description: "Background music file path.";
+        };
+        readonly bgmVolume: {
+            readonly type: "number";
+            readonly description: "BGM volume (0.0-1.0, default 0.15).";
+        };
+        readonly outputResolution: {
+            readonly type: "string";
+            readonly description: "Output resolution: '1920x1080', '1080x1920', etc. Default: auto.";
+        };
+        readonly outputFps: {
+            readonly type: "number";
+            readonly description: "Output FPS (default 30).";
+        };
+    };
+    readonly required: readonly ["clips"];
+};
+export interface VideoMergeResult {
+    localPath: string;
+    servePath: string;
+    durationSec: number;
+    clipCount: number;
+    mediaUrls: string[];
+}
+/** Deps injected by the host runtime for video merging. */
+export interface VideoMergeToolDeps {
+    /**
+     * Merge video clips via the configured backend (ffmpeg, relay, etc.).
+     * The host handles resolution normalization, transition rendering,
+     * subtitle burn-in, BGM mixing, and local storage.
+     */
+    mergeVideos(params: {
+        clips: VideoMergeClip[];
+        transition?: string;
+        transitionDuration?: number;
+        subtitles?: string;
+        bgm?: string;
+        bgmVolume?: number;
+        outputResolution?: string;
+        outputFps?: number;
+    }): Promise<VideoMergeResult>;
+}
+export declare function createVideoMergeTool(deps: VideoMergeToolDeps): PortableTool<VideoMergeToolParams>;

package/dist/types/skills/tools/video-upscale-tool.d.ts

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const VIDEO_UPSCALE_TOOL_NAME: "video_upscale";
+export interface VideoUpscaleToolParams {
+    video: string;
+    targetResolution?: string;
+    sharpness?: string;
+}
+export declare const VIDEO_UPSCALE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly video: {
+            readonly type: "string";
+            readonly description: "Video file path (local or serve path).";
+        };
+        readonly targetResolution: {
+            readonly type: "string";
+            readonly description: "Target resolution: '1080p' (default, 1920x1080/1080x1920), '2k' (2560x1440/1440x2560).";
+        };
+        readonly sharpness: {
+            readonly type: "string";
+            readonly description: "Sharpening intensity: 'light' (default), 'medium', 'strong'.";
+        };
+    };
+    readonly required: readonly ["video"];
+};
+export interface VideoUpscaleResult {
+    localPath: string;
+    servePath: string;
+    resolution: string;
+    durationSec: number;
+    mediaUrls: string[];
+}
+/** Deps injected by the host runtime for video upscaling. */
+export interface VideoUpscaleToolDeps {
+    /**
+     * Upscale a video via the configured backend (ffmpeg Lanczos + unsharp mask, etc.).
+     * The host handles orientation detection, filter chain, and storage.
+     */
+    upscaleVideo(params: {
+        video: string;
+        targetResolution?: string;
+        sharpness?: string;
+    }): Promise<VideoUpscaleResult>;
+}
+export declare function createVideoUpscaleTool(deps: VideoUpscaleToolDeps): PortableTool<VideoUpscaleToolParams>;

package/dist/types/skills/tools/web-fetch-tool.d.ts

@@ -0,0 +1,78 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WEB_FETCH_TOOL_NAME: "web_fetch";
+export interface WebFetchToolParams {
+    url: string;
+    extractMode?: "markdown" | "text" | "json";
+    maxChars?: number;
+    query?: string;
+    extract?: boolean;
+    summarize?: boolean;
+}
+export declare const WEB_FETCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly url: {
+            readonly type: "string";
+            readonly description: "HTTP or HTTPS URL to fetch.";
+        };
+        readonly extractMode: {
+            readonly type: "string";
+            readonly enum: readonly ["markdown", "text", "json"];
+            readonly description: "Extraction mode: \"markdown\" (default), \"text\", or \"json\" (LLM-driven structured extraction).";
+        };
+        readonly maxChars: {
+            readonly type: "number";
+            readonly description: "Maximum characters to return (truncates when exceeded).";
+            readonly minimum: 100;
+        };
+        readonly query: {
+            readonly type: "string";
+            readonly description: "Original search query. When provided, returns the most query-relevant sections.";
+        };
+        readonly extract: {
+            readonly type: "boolean";
+            readonly description: "When true, returns structured extraction (title, summary, key facts, entities, topics, sentiment).";
+        };
+        readonly summarize: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["url"];
+};
+export interface WebFetchResult {
+    content: string;
+    title?: string;
+    relevantExcerpts?: string[];
+    summary?: string;
+    extraction?: {
+        title?: string;
+        summary?: string;
+        keyFacts?: string[];
+        entities?: string[];
+        topics?: string[];
+        sentiment?: string;
+    };
+}
+/** Deps injected by the host runtime for web fetching. */
+export interface WebFetchToolDeps {
+    /**
+     * Fetch a URL and extract content.
+     * The host handles user-agent rotation, anti-block,
+     * JS rendering, caching, and content extraction.
+     */
+    fetchUrl(params: {
+        url: string;
+        extractMode?: "markdown" | "text" | "json";
+        maxChars?: number;
+        query?: string;
+        extract?: boolean;
+    }): Promise<WebFetchResult>;
+    /**
+     * Optional: summarize long content using a small/cheap model.
+     * When provided and summarize=true is requested, called after fetchUrl.
+     * Should return a concise summary (< 500 chars) preserving key information.
+     */
+    summarizeContent?(content: string, query?: string): Promise<string>;
+}
+export declare function createWebFetchTool(deps: WebFetchToolDeps): PortableTool<WebFetchToolParams>;

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

@@ -0,0 +1,57 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WEB_SEARCH_TOOL_NAME: "web_search";
+export interface WebSearchToolParams {
+    query: string;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+}
+export declare const WEB_SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly description: "Search query string. Be specific and concise for best results.";
+        };
+        readonly allowedDomains: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: string;
+        };
+        readonly blockedDomains: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Exclude results from these domains. Cannot be used together with allowedDomains.";
+        };
+    };
+    readonly required: readonly ["query"];
+};
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export interface WebSearchOutput {
+    query: string;
+    results: WebSearchResult[];
+    totalResults?: number;
+}
+/**
+ * Host-provided web search backend.
+ * The host may use any search engine (SearXNG, Brave, Tavily, etc.).
+ */
+export interface WebSearchToolDeps {
+    /**
+     * Execute a web search and return results.
+     * The host is responsible for API key management and rate limiting.
+     */
+    search(query: string, options?: {
+        allowedDomains?: string[];
+        blockedDomains?: string[];
+        maxResults?: number;
+    }): Promise<WebSearchOutput>;
+}
+export declare function createWebSearchTool(deps: WebSearchToolDeps): PortableTool<WebSearchToolParams>;

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

@@ -0,0 +1,44 @@
+import type { PortableTool } from "../portable-tool.js";
+export type WorkflowAction = "list" | "run" | "describe";
+export interface WorkflowStep {
+    /** Step identifier */
+    id: string;
+    /** Tool name to invoke */
+    tool: string;
+    /** Tool arguments (supports ${prev.result} interpolation) */
+    args: Record<string, unknown>;
+    /** Step IDs this step depends on (for DAG ordering) */
+    dependsOn?: string[];
+    /** Condition expression: "always" | "on_success" | "on_failure" (default: "on_success") */
+    condition?: "always" | "on_success" | "on_failure";
+    /** Human-readable label */
+    label?: string;
+}
+export interface WorkflowDefinition {
+    /** Workflow name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Ordered steps (executed in dependency order) */
+    steps: WorkflowStep[];
+    /** Variables that can be overridden at runtime */
+    variables?: Record<string, string>;
+}
+export interface WorkflowToolParams {
+    /** Action to perform */
+    action: WorkflowAction;
+    /** Workflow name (for run/describe) */
+    workflow?: string;
+    /** Variable overrides (for run) */
+    variables?: Record<string, string>;
+}
+export interface WorkflowToolDeps {
+    /** Execute a tool by name and return its text result */
+    invokeTool(toolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<{
+        result: string;
+        error?: string;
+    }>;
+    /** Get current working directory */
+    getCwd(): string;
+}
+export declare function createWorkflowTool(deps: WorkflowToolDeps): PortableTool<WorkflowToolParams>;

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

@@ -0,0 +1,69 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WORKTREE_TOOL_NAME: "worktree";
+export type WorktreeAction = "enter" | "exit" | "list";
+export interface WorktreeToolParams {
+    /** Action: enter (create worktree), exit (leave worktree), list (show all) */
+    action: WorktreeAction;
+    /** Branch/worktree name (for enter). kebab-case, max 64 chars. */
+    name?: string;
+    /** For exit: 'keep' retains the worktree, 'remove' deletes it */
+    exitAction?: "keep" | "remove";
+    /** Required true to discard uncommitted changes on exit with remove */
+    discardChanges?: boolean;
+}
+export declare const WORKTREE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["enter", "exit", "list"];
+            readonly description: string;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly exitAction: {
+            readonly type: "string";
+            readonly enum: readonly ["keep", "remove"];
+            readonly description: "For exit: 'keep' retains the worktree for later use; 'remove' deletes it.";
+        };
+        readonly discardChanges: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface WorktreeInfo {
+    name: string;
+    path: string;
+    branch: string;
+    isCurrent: boolean;
+    hasChanges: boolean;
+    unpushedCommits: number;
+}
+export interface WorktreeResult {
+    success: boolean;
+    worktree?: WorktreeInfo;
+    worktrees?: WorktreeInfo[];
+    previousCwd?: string;
+    error?: string;
+}
+/**
+ * Host-provided git worktree backend.
+ * Manages worktree creation, switching, and cleanup.
+ */
+export interface WorktreeToolDeps {
+    /** Create a new worktree and switch session cwd */
+    enterWorktree(name?: string): Promise<WorktreeResult>;
+    /** Exit worktree (keep or remove) */
+    exitWorktree(action: "keep" | "remove", discardChanges?: boolean): Promise<WorktreeResult>;
+    /** List all worktrees */
+    listWorktrees(): Promise<WorktreeResult>;
+    /** Check if currently in a worktree */
+    isInWorktree(): boolean;
+    /** Get current worktree info */
+    currentWorktree?(): WorktreeInfo | null;
+}
+export declare function createWorktreeTool(deps: WorktreeToolDeps): PortableTool<WorktreeToolParams>;

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

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WRITE_TOOL_NAME: "write";
+export interface WriteToolParams {
+    path: string;
+    content: string;
+}
+export declare const WRITE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Absolute path to the file to write.";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: "Content to write to the file.";
+        };
+    };
+    readonly required: readonly ["path", "content"];
+};
+/** Deps injected by the host runtime for file writing. */
+export interface WriteToolDeps {
+    /** Write content to a file. Create parent dirs as needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Resolve a relative path to absolute. */
+    resolvePath(input: string): string;
+    /**
+     * Check if file has been read before writing (first-read-then-write protection).
+     * Returns null if write is allowed, or a warning message.
+     * If not provided, no protection is applied.
+     */
+    checkReadBeforeWrite?(path: string): string | null;
+    /**
+     * Validate write access for the given path.
+     * Returns null if allowed, or an error message if blocked.
+     */
+    validatePath?(path: string): string | null;
+    /**
+     * Check for concurrent modification before overwriting an existing file.
+     * Returns null if safe to write, or a warning if modified since last read.
+     * If not provided, no concurrent modification check is performed.
+     */
+    checkConcurrentModification?(path: string): string | null;
+}
+export declare function createWriteTool(deps: WriteToolDeps): PortableTool<WriteToolParams>;