qlogicagent 0.5.2 → 0.6.0

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

@@ -0,0 +1,116 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const CRON_TOOL_NAME: "cron";
+export type CronAction = "create" | "list" | "get" | "update" | "delete" | "pause" | "resume" | "trigger";
+export interface CronToolParams {
+    action: CronAction;
+    /** Job ID (required for get/update/delete/pause/resume/trigger) */
+    jobId?: string;
+    /** Task prompt to execute on schedule */
+    prompt?: string;
+    /** Cron expression or shorthand ('5m', '1h', '0 9 * * *') */
+    schedule?: string;
+    /** Human-readable job name */
+    name?: string;
+    /** Repeat count (null = infinite) */
+    repeat?: number | null;
+    /** Allowed tools for the scheduled task */
+    allowedTools?: string[];
+    /** Whether the job is enabled */
+    enabled?: boolean;
+}
+export declare const CRON_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["create", "list", "get", "update", "delete", "pause", "resume", "trigger"];
+            readonly description: "CRUD action: create/list/get/update/delete/pause/resume/trigger.";
+        };
+        readonly jobId: {
+            readonly type: "string";
+            readonly description: "Job ID. Required for get/update/delete/pause/resume/trigger.";
+        };
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "Task prompt to execute on schedule. Required for create.";
+        };
+        readonly schedule: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: "Human-readable job name.";
+        };
+        readonly repeat: {
+            readonly type: "number";
+            readonly description: "Number of times to repeat (null = infinite). Default: null.";
+        };
+        readonly allowedTools: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Tools the scheduled task is allowed to use.";
+        };
+        readonly enabled: {
+            readonly type: "boolean";
+            readonly description: "Whether the job is enabled (for update).";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface CronJob {
+    id: string;
+    name: string;
+    prompt: string;
+    schedule: string;
+    scheduleDisplay: string;
+    state: "scheduled" | "paused";
+    enabled: boolean;
+    repeat: {
+        times: number | null;
+        completed: number;
+    };
+    nextRunAt?: string;
+    lastRunAt?: string;
+    lastStatus?: "success" | "error" | null;
+    allowedTools?: string[];
+}
+export interface CronResult {
+    success: boolean;
+    job?: CronJob;
+    jobs?: CronJob[];
+    error?: string;
+}
+/**
+ * Host-provided cron scheduler backend.
+ * Jobs are persisted locally and survive restarts.
+ */
+export interface CronToolDeps {
+    createJob(params: {
+        prompt: string;
+        schedule: string;
+        name?: string;
+        repeat?: number | null;
+        allowedTools?: string[];
+    }): Promise<CronResult>;
+    listJobs(): Promise<CronResult>;
+    getJob(jobId: string): Promise<CronResult>;
+    updateJob(jobId: string, updates: Partial<{
+        prompt: string;
+        schedule: string;
+        name: string;
+        enabled: boolean;
+        repeat: number | null;
+        allowedTools: string[];
+    }>): Promise<CronResult>;
+    deleteJob(jobId: string): Promise<CronResult>;
+    pauseJob(jobId: string): Promise<CronResult>;
+    resumeJob(jobId: string): Promise<CronResult>;
+    triggerJob(jobId: string): Promise<CronResult>;
+    /** Validate cron schedule expression. Returns error or null. */
+    validateSchedule?(schedule: string): string | null;
+}
+export declare const MAX_CRON_JOBS = 50;
+export declare function createCronTool(deps: CronToolDeps): PortableTool<CronToolParams>;

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

@@ -0,0 +1,43 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const EDIT_TOOL_NAME: "edit";
+export interface EditToolParams {
+    path: string;
+    oldText: string;
+    newText: string;
+}
+export declare const EDIT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly description: "Path to the file to edit (relative or absolute).";
+        };
+        readonly oldText: {
+            readonly type: "string";
+            readonly description: "Exact text to find and replace (must match exactly, including whitespace).";
+        };
+        readonly newText: {
+            readonly type: "string";
+            readonly description: "New text to replace the old text with.";
+        };
+    };
+    readonly required: readonly ["path", "oldText", "newText"];
+};
+/** Deps injected by the host runtime for file editing. */
+export interface EditToolDeps {
+    /** Read file content as text. */
+    readFile(path: string): Promise<string>;
+    /** Write content back. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Resolve a relative path to absolute. */
+    resolvePath(input: string): string;
+    /**
+     * Check for concurrent modification before writing.
+     * The host tracks when each file was last read vs last modified on disk.
+     * Returns null if safe to write, or a descriptive warning if the file
+     * has been modified since last read (by user, another tool, or external process).
+     * If not provided, no concurrent modification check is performed.
+     */
+    checkConcurrentModification?(path: string): string | null;
+}
+export declare function createEditTool(deps: EditToolDeps): PortableTool<EditToolParams>;

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

@@ -0,0 +1,97 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { CommandClassification } from "./shell/command-classification.js";
+export declare const EXEC_TOOL_NAME: "exec";
+export interface ExecToolParams {
+    command: string;
+    description?: string;
+    workdir?: string;
+    timeout?: number;
+    /** Explicit background request (cc: run_in_background). */
+    background?: boolean;
+}
+export declare const EXEC_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly command: {
+            readonly type: "string";
+            readonly description: "Shell command to execute. On Windows uses PowerShell, on Unix uses bash.";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly workdir: {
+            readonly type: "string";
+            readonly description: "Working directory for the command.";
+        };
+        readonly timeout: {
+            readonly type: "number";
+            readonly description: string;
+        };
+        readonly background: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["command"];
+};
+export interface ExecToolOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    interrupted: boolean;
+    rawOutputPath?: string;
+    backgroundTaskId?: string;
+    assistantAutoBackgrounded?: boolean;
+    returnCodeInterpretation?: string;
+    noOutputExpected?: boolean;
+    persistedOutputPath?: string;
+    persistedOutputSize?: number;
+    classification?: CommandClassification;
+}
+export interface ExecProgress {
+    type: "exec_progress";
+    output: string;
+    fullOutput: string;
+    elapsedTimeSeconds: number;
+    totalLines: number;
+    totalBytes: number;
+    taskId?: string;
+}
+/**
+ * Minimal host dependency — ONLY for permission checking.
+ * The tool owns everything else (spawn, lifecycle, output).
+ *
+ * This replaces the old ExecToolDeps which required the host to
+ * implement the entire exec() pipeline. Now the tool owns the
+ * process directly (cc architecture).
+ */
+export interface ExecToolHost {
+    /**
+     * Validate a command before execution.
+     * Returns null/undefined if allowed, or an error message if blocked.
+     */
+    validateCommand?(command: string): Promise<string | null | undefined>;
+    /**
+     * Interpret a non-zero exit code.
+     * E.g. 127 → "command not found", 137 → "killed by SIGKILL".
+     */
+    interpretExitCode?(exitCode: number, stderr: string): string | undefined;
+    /**
+     * Called during foreground execution with incremental progress.
+     * The host can forward these to the UI for real-time output display.
+     */
+    onProgress?(progress: ExecProgress): void;
+}
+/**
+ * Auto-background trigger threshold (assistant mode).
+ * cc: ASSISTANT_BLOCKING_BUDGET_MS = 15_000
+ */
+export declare const ASSISTANT_BLOCKING_BUDGET_MS = 15000;
+/**
+ * Create the exec tool with direct process ownership (cc architecture).
+ *
+ * @param host Minimal host interface — only permission checking.
+ *             Pass `{}` for unrestricted mode (tests only).
+ */
+export declare function createExecTool(host?: ExecToolHost): PortableTool<ExecToolParams>;

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

@@ -0,0 +1,62 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const IMAGE_GENERATE_TOOL_NAME: "image_generate";
+export interface ImageGenerateToolParams {
+    prompt: string;
+    purpose?: string;
+    style?: string;
+    size?: string;
+    image_url?: string;
+    n?: number;
+}
+export declare const IMAGE_GENERATE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "Image generation prompt. Enrich vague requests with style, lighting, composition, color, mood details.";
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: "Intended use: 'social-media', 'short-video-cover', 'phone-wallpaper', 'avatar', 'poster', etc.";
+        };
+        readonly style: {
+            readonly type: "string";
+            readonly description: "Visual art style: 'photorealistic', 'anime', 'watercolor', 'oil-painting', '3d-render', etc.";
+        };
+        readonly size: {
+            readonly type: "string";
+            readonly description: "Dimensions: e.g. '1024x1792' (portrait), '1792x1024' (landscape), '1024x1024' (square). Default: '1024x1024'.";
+        };
+        readonly image_url: {
+            readonly type: "string";
+            readonly description: "Reference image URL for image-to-image generation (img2img). Character reference sheet or style transfer.";
+        };
+        readonly n: {
+            readonly type: "number";
+            readonly description: "Number of images to generate (1-4). Default: 1.";
+        };
+    };
+    readonly required: readonly ["prompt"];
+};
+export interface ImageGenerateResult {
+    mediaUrls: string[];
+    model?: string;
+    size?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for image generation. */
+export interface ImageGenerateToolDeps {
+    /**
+     * Generate images via the configured backend (relay, direct API, etc.).
+     * The host handles model selection, failover, watermark, and storage.
+     */
+    generateImage(params: {
+        prompt: string;
+        purpose?: string;
+        style?: string;
+        size?: string;
+        imageUrl?: string;
+        n?: number;
+    }): Promise<ImageGenerateResult>;
+}
+export declare function createImageGenerateTool(deps: ImageGenerateToolDeps): PortableTool<ImageGenerateToolParams>;

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

@@ -0,0 +1,65 @@
+import type { PortableTool } from "../portable-tool.js";
+/** A single instruction file entry. */
+export interface InstructionFileInfo {
+    filename: string;
+    path: string;
+    size: number;
+    updatedAt: string;
+}
+/** Full instruction file (with content). */
+export interface InstructionFileContent extends InstructionFileInfo {
+    content: string;
+}
+/** Deps injected by the host runtime for instructions CRUD. */
+export interface InstructionsToolDeps {
+    /** List all instruction files for a project (recursive). */
+    list(projectId: string): InstructionFileInfo[];
+    /** Read a single instruction file. Returns null if not found. */
+    read(projectId: string, filename: string): InstructionFileContent | null;
+    /** Write (create or overwrite) an instruction file. */
+    write(projectId: string, filename: string, content: string): InstructionFileContent;
+    /** Remove an instruction file. Returns true if deleted. */
+    remove(projectId: string, filename: string): boolean;
+}
+export declare const INSTRUCTIONS_TOOL_NAME: "instructions";
+export type InstructionsAction = "list" | "read" | "write" | "edit" | "delete";
+export interface InstructionsToolParams {
+    action: InstructionsAction;
+    project_id: string;
+    filename?: string;
+    content?: string;
+    old_text?: string;
+    new_text?: string;
+}
+export declare const INSTRUCTIONS_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["list", "read", "write", "edit", "delete"];
+            readonly description: "Operation: list all files, read a file, write (create/overwrite), edit (partial replace), or delete a file.";
+        };
+        readonly project_id: {
+            readonly type: "string";
+            readonly description: "Project ID. Use \"default\" for the default project.";
+        };
+        readonly filename: {
+            readonly type: "string";
+            readonly description: "Instruction file name ending in .md (e.g. \"code-style.md\"). Required for read/write/delete. Sub-paths like \"testing/unit-test.md\" are supported.";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: "Markdown content for the instruction file. Required for write action.";
+        };
+        readonly old_text: {
+            readonly type: "string";
+            readonly description: "Required for edit action: the exact existing text to find and replace (must appear exactly once).";
+        };
+        readonly new_text: {
+            readonly type: "string";
+            readonly description: "Required for edit action: the replacement text.";
+        };
+    };
+    readonly required: readonly ["action", "project_id"];
+};
+export declare function createInstructionsTool(deps: InstructionsToolDeps): PortableTool<InstructionsToolParams>;

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

@@ -0,0 +1,153 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const LSP_TOOL_NAME: "lsp";
+export type LspOperation = "goToDefinition" | "findReferences" | "hover" | "documentSymbol" | "diagnostics" | "completion" | "signatureHelp" | "rename" | "codeAction";
+export interface LspToolParams {
+    /** LSP operation to perform */
+    operation: LspOperation;
+    /** File path (absolute or relative to workspace root) */
+    filePath: string;
+    /** Line number (1-indexed) */
+    line?: number;
+    /** Character position (1-indexed) */
+    character?: number;
+    /** New name (for rename operation) */
+    newName?: string;
+    /** Include context lines around results */
+    includeContext?: boolean;
+}
+export declare const LSP_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly operation: {
+            readonly type: "string";
+            readonly enum: readonly ["goToDefinition", "findReferences", "hover", "documentSymbol", "diagnostics", "completion", "signatureHelp", "rename", "codeAction"];
+            readonly description: string;
+        };
+        readonly filePath: {
+            readonly type: "string";
+            readonly description: "File path. Absolute or relative to workspace root.";
+        };
+        readonly line: {
+            readonly type: "number";
+            readonly description: "Line number (1-indexed). Required for positional operations.";
+        };
+        readonly character: {
+            readonly type: "number";
+            readonly description: "Character position (1-indexed). Required for positional operations.";
+        };
+        readonly newName: {
+            readonly type: "string";
+            readonly description: "New name for rename operation.";
+        };
+        readonly includeContext: {
+            readonly type: "boolean";
+            readonly description: "Include surrounding code context in results (default: true).";
+        };
+    };
+    readonly required: readonly ["operation", "filePath"];
+};
+export interface LspLocation {
+    filePath: string;
+    line: number;
+    character: number;
+    endLine?: number;
+    endCharacter?: number;
+    context?: string;
+}
+export interface LspSymbol {
+    name: string;
+    kind: string;
+    range: {
+        startLine: number;
+        endLine: number;
+    };
+    children?: LspSymbol[];
+}
+export interface LspDiagnostic {
+    message: string;
+    severity: "error" | "warning" | "info" | "hint";
+    line: number;
+    character: number;
+    source?: string;
+    code?: string | number;
+}
+export interface LspHoverInfo {
+    contents: string;
+    range?: {
+        startLine: number;
+        startCharacter: number;
+        endLine: number;
+        endCharacter: number;
+    };
+}
+export interface LspCompletion {
+    label: string;
+    kind: string;
+    detail?: string;
+    insertText?: string;
+}
+export interface LspRenameEdit {
+    filePath: string;
+    edits: Array<{
+        line: number;
+        character: number;
+        endLine: number;
+        endCharacter: number;
+        newText: string;
+    }>;
+}
+export interface LspCodeAction {
+    title: string;
+    kind?: string;
+    isPreferred?: boolean;
+}
+export type LspResult = {
+    type: "locations";
+    locations: LspLocation[];
+} | {
+    type: "symbols";
+    symbols: LspSymbol[];
+} | {
+    type: "diagnostics";
+    diagnostics: LspDiagnostic[];
+} | {
+    type: "hover";
+    hover: LspHoverInfo | null;
+} | {
+    type: "completions";
+    completions: LspCompletion[];
+} | {
+    type: "rename";
+    edits: LspRenameEdit[];
+} | {
+    type: "codeActions";
+    actions: LspCodeAction[];
+} | {
+    type: "signatureHelp";
+    signatures: string[];
+};
+/**
+ * Host-provided LSP backend.
+ * The host manages language server lifecycle and connections.
+ */
+export interface LspToolDeps {
+    /** Execute an LSP operation. Host dispatches to appropriate language server. */
+    executeOperation(params: {
+        operation: LspOperation;
+        filePath: string;
+        line?: number;
+        character?: number;
+        newName?: string;
+        includeContext?: boolean;
+    }): Promise<LspResult>;
+    /** Check if file exists and get its size */
+    statFile?(filePath: string): Promise<{
+        exists: boolean;
+        size: number;
+    } | null>;
+    /** Resolve relative path to absolute */
+    resolvePath(filePath: string): string;
+    /** List supported language IDs (e.g. ['typescript', 'python', 'rust']) */
+    supportedLanguages?(): string[];
+}
+export declare function createLspTool(deps: LspToolDeps): PortableTool<LspToolParams>;