qlogicagent 0.5.2 → 0.5.3

package/dist/types/skills/tools/ask-user-tool.d.ts

@@ -0,0 +1,80 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const ASK_USER_TOOL_NAME: "ask_user";
+export interface AskUserOption {
+    label: string;
+    description?: string;
+}
+export interface AskUserQuestion {
+    question: string;
+    header: string;
+    options?: AskUserOption[];
+    multiSelect?: boolean;
+}
+export interface AskUserToolParams {
+    questions: AskUserQuestion[];
+}
+export declare const ASK_USER_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly questions: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 4;
+            readonly description: "1-4 clarifying questions to ask the user.";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly question: {
+                        readonly type: "string";
+                        readonly description: "The question text. Should end with '?'.";
+                    };
+                    readonly header: {
+                        readonly type: "string";
+                        readonly description: "Short identifier/tag for this question (max 50 chars).";
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly description: "2-4 options for the user to choose from. Omit for free text.";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly description: "Display label (1-5 words).";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                    readonly description: "Brief explanation of this option.";
+                                };
+                            };
+                            readonly required: readonly ["label"];
+                        };
+                    };
+                    readonly multiSelect: {
+                        readonly type: "boolean";
+                        readonly description: "Allow selecting multiple options (default: false).";
+                    };
+                };
+                readonly required: readonly ["question", "header"];
+            };
+        };
+    };
+    readonly required: readonly ["questions"];
+};
+export interface AskUserAnswer {
+    question: string;
+    answer: string;
+}
+/**
+ * Host-provided user interaction backend.
+ * The host renders the questions in the UI and collects answers.
+ */
+export interface AskUserToolDeps {
+    /**
+     * Present questions to the user and collect answers.
+     * Returns a map of question text → answer text.
+     * If the user declines, returns null.
+     */
+    askUser(questions: AskUserQuestion[]): Promise<Record<string, string> | null>;
+}
+export declare function createAskUserTool(deps: AskUserToolDeps): PortableTool<AskUserToolParams>;

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

@@ -0,0 +1,74 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const BRIEF_TOOL_NAME: "send_user_message";
+export type BriefMessageStatus = "normal" | "proactive";
+export interface BriefAttachment {
+    /** Absolute or workspace-relative path */
+    path: string;
+    /** Size in bytes (filled by host) */
+    size?: number;
+    /** Whether the file is an image */
+    isImage?: boolean;
+    /** Upload UUID (host may upload for web preview) */
+    fileUuid?: string;
+}
+export interface BriefToolParams {
+    /** Markdown-formatted message to display to the user */
+    message: string;
+    /** File attachments to include with the message */
+    attachments?: string[];
+    /** Message status — 'proactive' for unsolicited updates */
+    status?: BriefMessageStatus;
+}
+export declare const BRIEF_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly message: {
+            readonly type: "string";
+            readonly description: string;
+            readonly minLength: 1;
+        };
+        readonly attachments: {
+            readonly type: "array";
+            readonly description: "Optional file paths to attach (images, documents, etc.).";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly maxItems: 10;
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["normal", "proactive"];
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["message"];
+};
+export interface BriefDeliveryResult {
+    delivered: boolean;
+    attachments?: BriefAttachment[];
+    sentAt?: string;
+    error?: string;
+}
+/**
+ * Host-provided message delivery backend.
+ */
+export interface BriefToolDeps {
+    /** Deliver the message to the user's UI */
+    deliverMessage(params: {
+        message: string;
+        attachments?: string[];
+        status: BriefMessageStatus;
+    }): Promise<BriefDeliveryResult>;
+    /** Validate and resolve attachment paths. Returns resolved attachments or error. */
+    resolveAttachments?(paths: string[]): Promise<BriefAttachment[] | {
+        error: string;
+    }>;
+}
+/** Check if brief mode is active (host determines this) */
+export interface BriefModeConfig {
+    /** Whether the agent is in brief/chat mode */
+    isBriefMode: boolean;
+    /** Whether the user opted in via UI/CLI */
+    userOptIn?: boolean;
+}
+export declare function createBriefTool(deps: BriefToolDeps): PortableTool<BriefToolParams>;

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

@@ -0,0 +1,114 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const BROWSER_TOOL_NAME: "browser";
+export type BrowserAction = "navigate" | "click" | "type" | "scroll" | "snapshot" | "screenshot" | "console" | "cdp";
+export interface BrowserToolParams {
+    /** Browser action to perform */
+    action: BrowserAction;
+    /** URL for navigate action */
+    url?: string;
+    /** Element reference (e.g. "@e5") for click/type actions */
+    ref?: string;
+    /** Text to type */
+    text?: string;
+    /** Scroll direction */
+    direction?: "up" | "down" | "left" | "right";
+    /** CDP method name for raw cdp action */
+    method?: string;
+    /** CDP params object */
+    params?: Record<string, unknown>;
+    /** JavaScript expression for console eval */
+    expression?: string;
+    /** Whether to include full accessibility tree */
+    full?: boolean;
+}
+export declare const BROWSER_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["navigate", "click", "type", "scroll", "snapshot", "screenshot", "console", "cdp"];
+            readonly description: string;
+        };
+        readonly url: {
+            readonly type: "string";
+            readonly description: "URL to navigate to. Required for 'navigate' action.";
+        };
+        readonly ref: {
+            readonly type: "string";
+            readonly description: "Element reference like \"@e5\" from a previous snapshot. Required for click/type.";
+        };
+        readonly text: {
+            readonly type: "string";
+            readonly description: "Text to type into the referenced element. Required for 'type' action.";
+        };
+        readonly direction: {
+            readonly type: "string";
+            readonly enum: readonly ["up", "down", "left", "right"];
+            readonly description: "Scroll direction. Required for 'scroll' action.";
+        };
+        readonly method: {
+            readonly type: "string";
+            readonly description: "CDP method name (e.g. 'Page.reload'). Required for 'cdp' action.";
+        };
+        readonly params: {
+            readonly type: "object";
+            readonly description: "Parameters for the CDP method. Optional for 'cdp' action.";
+        };
+        readonly expression: {
+            readonly type: "string";
+            readonly description: "JavaScript expression to evaluate. Used with 'console' action.";
+        };
+        readonly full: {
+            readonly type: "boolean";
+            readonly description: "Include full accessibility tree (default: compact). Used with 'snapshot'.";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface BrowserSnapshot {
+    elements: Array<{
+        ref: string;
+        role: string;
+        name: string;
+        text?: string;
+    }>;
+    url: string;
+    title: string;
+}
+export interface BrowserScreenshot {
+    base64: string;
+    mimeType: string;
+    width: number;
+    height: number;
+}
+/**
+ * Host-provided browser automation backend.
+ * The host manages Chrome/Chromium lifecycle and CDP connections.
+ */
+export interface BrowserToolDeps {
+    navigate(url: string): Promise<{
+        snapshot: BrowserSnapshot;
+    }>;
+    click(ref: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    type(ref: string, text: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    scroll(direction: "up" | "down" | "left" | "right"): Promise<{
+        success: boolean;
+    }>;
+    snapshot(full?: boolean): Promise<BrowserSnapshot>;
+    screenshot(): Promise<BrowserScreenshot>;
+    consoleEval(expression?: string): Promise<{
+        result?: string;
+        messages?: string[];
+        errors?: string[];
+    }>;
+    cdp(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Validate URL safety (SSRF prevention). Returns error message if blocked, null if safe. */
+    validateUrl(url: string): string | null;
+}
+export declare function createBrowserTool(deps: BrowserToolDeps): PortableTool<BrowserToolParams>;

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

@@ -0,0 +1,66 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const CHECKPOINT_TOOL_NAME: "checkpoint";
+export type CheckpointAction = "create" | "list" | "restore" | "diff";
+export interface CheckpointToolParams {
+    action: CheckpointAction;
+    /** Checkpoint ID (for restore/diff) */
+    checkpointId?: string;
+    /** Optional message for create */
+    message?: string;
+    /** File paths to restore (partial restore). If empty, restores all. */
+    paths?: string[];
+}
+export declare const CHECKPOINT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["create", "list", "restore", "diff"];
+            readonly description: string;
+        };
+        readonly checkpointId: {
+            readonly type: "string";
+            readonly description: "Checkpoint ID. Required for restore and diff.";
+        };
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Optional descriptive message for the checkpoint.";
+        };
+        readonly paths: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "File paths to restore (partial restore). Omit to restore everything.";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface Checkpoint {
+    id: string;
+    message: string;
+    timestamp: string;
+    fileCount: number;
+}
+export interface CheckpointResult {
+    success: boolean;
+    checkpoint?: Checkpoint;
+    checkpoints?: Checkpoint[];
+    diff?: string;
+    error?: string;
+}
+/**
+ * Host-provided checkpoint backend.
+ * Uses shadow git repos (isolated from user project) for snapshots.
+ */
+export interface CheckpointToolDeps {
+    /** Create a snapshot of the current workspace state */
+    createCheckpoint(message?: string): Promise<CheckpointResult>;
+    /** List all available checkpoints */
+    listCheckpoints(): Promise<CheckpointResult>;
+    /** Restore workspace to a checkpoint state (optionally partial) */
+    restoreCheckpoint(checkpointId: string, paths?: string[]): Promise<CheckpointResult>;
+    /** Show diff between current state and a checkpoint */
+    diffCheckpoint(checkpointId: string): Promise<CheckpointResult>;
+}
+export declare function createCheckpointTool(deps: CheckpointToolDeps): PortableTool<CheckpointToolParams>;

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

@@ -0,0 +1,63 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const CONFIG_TOOL_NAME: "config";
+export type ConfigAction = "get" | "set" | "list" | "reset";
+export interface ConfigToolParams {
+    /** Config action */
+    action: ConfigAction;
+    /** Setting key path (e.g. "model", "language", "theme") */
+    key?: string;
+    /** Value to set (for 'set' action) */
+    value?: string | boolean | number;
+}
+export declare const CONFIG_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["get", "set", "list", "reset"];
+            readonly description: string;
+        };
+        readonly key: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly value: {
+            readonly description: "Value to set. Type depends on the setting. Required for 'set' action.";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface ConfigSetting {
+    key: string;
+    value: unknown;
+    type: "string" | "boolean" | "number" | "enum";
+    description: string;
+    options?: string[];
+    readOnly?: boolean;
+}
+export interface ConfigResult {
+    success: boolean;
+    setting?: ConfigSetting;
+    settings?: ConfigSetting[];
+    previousValue?: unknown;
+    error?: string;
+}
+/** Keys that cannot be modified by LLM (security-critical) */
+export declare const CONFIG_READONLY_KEYS: readonly string[];
+/**
+ * Host-provided config backend.
+ * Manages persistent agent settings with safety guardrails.
+ */
+export interface ConfigToolDeps {
+    /** Get a single config value */
+    getConfig(key: string): Promise<ConfigResult>;
+    /** Set a config value (respects readonly/whitelist) */
+    setConfig(key: string, value: unknown): Promise<ConfigResult>;
+    /** List all available config settings */
+    listConfig(): Promise<ConfigResult>;
+    /** Reset a setting to default */
+    resetConfig(key: string): Promise<ConfigResult>;
+    /** Check if a key is supported/valid */
+    isValidKey?(key: string): boolean;
+}
+export declare function createConfigTool(deps: ConfigToolDeps): PortableTool<ConfigToolParams>;

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>;