qlogicagent 0.5.2 → 0.5.3

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,103 @@
+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_LIST_TOOL_NAME: "instructions_list";
+export interface InstructionsListParams {
+    project_id: string;
+}
+export declare const INSTRUCTIONS_LIST_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly project_id: {
+            readonly type: "string";
+            readonly description: "Project ID to list instructions for. Use \"default\" for the default project.";
+        };
+    };
+    readonly required: readonly ["project_id"];
+};
+export declare function createInstructionsListTool(deps: InstructionsToolDeps): PortableTool<InstructionsListParams>;
+export declare const INSTRUCTIONS_READ_TOOL_NAME: "instructions_read";
+export interface InstructionsReadParams {
+    project_id: string;
+    filename: string;
+}
+export declare const INSTRUCTIONS_READ_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        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 (e.g. \"code-style.md\"). Supports sub-paths like \"testing/unit-test.md\".";
+        };
+    };
+    readonly required: readonly ["project_id", "filename"];
+};
+export declare function createInstructionsReadTool(deps: InstructionsToolDeps): PortableTool<InstructionsReadParams>;
+export declare const INSTRUCTIONS_WRITE_TOOL_NAME: "instructions_write";
+export interface InstructionsWriteParams {
+    project_id: string;
+    filename: string;
+    content: string;
+}
+export declare const INSTRUCTIONS_WRITE_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        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\"). Sub-paths like \"testing/unit-test.md\" are supported.";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: "Markdown content for the instruction file.";
+        };
+    };
+    readonly required: readonly ["project_id", "filename", "content"];
+};
+export declare function createInstructionsWriteTool(deps: InstructionsToolDeps): PortableTool<InstructionsWriteParams>;
+export declare const INSTRUCTIONS_DELETE_TOOL_NAME: "instructions_delete";
+export interface InstructionsDeleteParams {
+    project_id: string;
+    filename: string;
+}
+export declare const INSTRUCTIONS_DELETE_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        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 to delete (e.g. \"code-style.md\").";
+        };
+    };
+    readonly required: readonly ["project_id", "filename"];
+};
+export declare function createInstructionsDeleteTool(deps: InstructionsToolDeps): PortableTool<InstructionsDeleteParams>;

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

package/dist/types/skills/tools/mcp-client-types.d.ts

@@ -0,0 +1,269 @@
+/** Supported MCP transport types */
+export type McpTransportType = "stdio" | "sse" | "http" | "ws" | "in-process";
+/** Stdio transport configuration */
+export interface McpStdioConfig {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** SSE transport configuration */
+export interface McpSseConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+    /** OAuth config for auth-required SSE servers */
+    oauth?: McpOAuthConfig;
+}
+/** Streamable HTTP transport configuration (MCP 2025-03-26) */
+export interface McpHttpConfig {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+    /** OAuth config for auth-required HTTP servers */
+    oauth?: McpOAuthConfig;
+}
+/** WebSocket transport configuration */
+export interface McpWsConfig {
+    type: "ws";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** In-process transport (bundled MCP servers) */
+export interface McpInProcessConfig {
+    type: "in-process";
+    /** Module identifier to load */
+    moduleId: string;
+    /** Init args passed to the in-process server */
+    initArgs?: Record<string, unknown>;
+}
+/** Union of all transport configurations */
+export type McpServerConfig = McpStdioConfig | McpSseConfig | McpHttpConfig | McpWsConfig | McpInProcessConfig;
+/** OAuth configuration for remote MCP servers */
+export interface McpOAuthConfig {
+    /** Client ID (or URL-based client_id per CIMD/SEP-991) */
+    clientId?: string;
+    /** Client secret (optional, for confidential clients) */
+    clientSecret?: string;
+    /** Override authorization endpoint (otherwise discovered via RFC 8414) */
+    authorizationEndpoint?: string;
+    /** Override token endpoint */
+    tokenEndpoint?: string;
+    /** Requested scopes */
+    scopes?: string[];
+    /** Fixed callback port (otherwise picks random available port) */
+    callbackPort?: number;
+    /** Audience for token exchange (RFC 8693) */
+    audience?: string;
+}
+/** OAuth token set */
+export interface McpOAuthTokens {
+    accessToken: string;
+    tokenType: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+}
+/** Authentication state of a server */
+export type McpAuthState = {
+    status: "authenticated";
+    tokens: McpOAuthTokens;
+} | {
+    status: "needs-auth";
+    authUrl?: string;
+    message?: string;
+} | {
+    status: "refreshing";
+} | {
+    status: "step-up-required";
+    scope: string;
+    authUrl?: string;
+} | {
+    status: "not-applicable";
+};
+/** Server connection status */
+export type McpConnectionStatus = "connected" | "connecting" | "disconnected" | "failed" | "needs-auth" | "disabled";
+/** Server capabilities (as reported by initialize) */
+export interface McpServerCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        subscribe?: boolean;
+        listChanged?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, unknown>;
+    experimental?: Record<string, unknown>;
+}
+/** Full server connection state */
+export interface McpServerState {
+    name: string;
+    config: McpServerConfig;
+    status: McpConnectionStatus;
+    capabilities?: McpServerCapabilities;
+    serverVersion?: string;
+    serverInstructions?: string;
+    error?: string;
+    /** Timestamp of last successful connection */
+    connectedAt?: number;
+    /** Number of reconnect attempts since last disconnect */
+    reconnectAttempts?: number;
+}
+/**
+ * An MCP tool definition as reported by tools/list.
+ * The host converts these into PortableTool entries for the LLM.
+ */
+export interface McpExternalTool {
+    /** Tool name on the MCP server (original) */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** JSON Schema for input parameters */
+    inputSchema?: Record<string, unknown>;
+    /** Annotations from the server (readOnlyHint, destructiveHint, etc.) */
+    annotations?: McpToolAnnotations;
+}
+/** Tool behavior annotations (MCP 2025-03-26 spec) */
+export interface McpToolAnnotations {
+    /** Hints that the tool performs only reads */
+    readOnlyHint?: boolean;
+    /** Hints that the tool may be destructive */
+    destructiveHint?: boolean;
+    /** Hints that the tool is idempotent */
+    idempotentHint?: boolean;
+    /** Hints about concurrency safety */
+    openWorldHint?: boolean;
+    /** Human-readable title for UI display */
+    title?: string;
+}
+/**
+ * Prefixed tool name format: mcp__{normalizedServer}__{normalizedTool}
+ * This ensures no collisions with built-in tools.
+ */
+export interface McpToolIdentifier {
+    serverName: string;
+    toolName: string;
+    /** Full prefixed name: mcp__{server}__{tool} */
+    prefixedName: string;
+}
+/**
+ * Notification payload when a server's tool list changes.
+ * The host should re-fetch tools/list and hot-swap the tool set.
+ */
+export interface McpToolsChangedEvent {
+    serverName: string;
+    /** Previous tool names (for diff-based cleanup) */
+    previousTools: string[];
+    /** Updated tool list */
+    currentTools: McpExternalTool[];
+}
+/** MCP Resource definition */
+export interface McpResourceDefinition {
+    uri: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+    /** Size in bytes (if known) */
+    size?: number;
+}
+/** Resource template (parameterized URI) */
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+}
+/** Content of a read resource */
+export interface McpResourceContentItem {
+    uri: string;
+    mimeType?: string;
+    /** Text content (mutually exclusive with blob) */
+    text?: string;
+    /** Base64-encoded binary (mutually exclusive with text) */
+    blob?: string;
+}
+/** Persisted resource content (after binary blob handling) */
+export interface McpPersistedResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    /** Path where binary was saved to disk */
+    blobSavedTo?: string;
+    /** Size of persisted binary in bytes */
+    blobSize?: number;
+}
+/** MCP Prompt definition from prompts/list */
+export interface McpPromptDefinition {
+    name: string;
+    description?: string;
+    arguments?: McpPromptArgument[];
+}
+/** Argument for an MCP prompt */
+export interface McpPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+/** Result of prompts/get — prompt content messages */
+export interface McpPromptMessage {
+    role: "user" | "assistant";
+    content: McpPromptContent;
+}
+export type McpPromptContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    };
+};
+/** MCP Elicitation request (server asks user for input) */
+export interface McpElicitRequest {
+    message: string;
+    requestedSchema?: Record<string, unknown>;
+}
+/** Elicitation response */
+export interface McpElicitResult {
+    action: "accept" | "deny" | "cancel";
+    content?: Record<string, unknown>;
+}
+export type McpLogLevel = "debug" | "info" | "warning" | "error" | "critical";
+export interface McpLogEntry {
+    serverName: string;
+    level: McpLogLevel;
+    logger?: string;
+    data: unknown;
+    timestamp: number;
+}
+export declare const MCP_CONNECTION_TIMEOUT_MS = 30000;
+export declare const MCP_REQUEST_TIMEOUT_MS = 60000;
+export declare const MCP_TOOL_CALL_TIMEOUT_MS = 100000;
+export declare const MCP_MAX_RECONNECT_ATTEMPTS = 5;
+export declare const MCP_RECONNECT_BASE_DELAY_MS = 1000;
+export declare const MCP_RECONNECT_MAX_DELAY_MS = 30000;
+export declare const MCP_MAX_DESCRIPTION_LENGTH = 2048;
+export declare const MCP_AUTH_CACHE_TTL_MS: number;
+export declare const MCP_BATCH_SIZE_LOCAL = 3;
+export declare const MCP_BATCH_SIZE_REMOTE = 20;
+/** Normalize a name for use in the prefixed tool name format */
+export declare function normalizeNameForMcp(name: string): string;
+/** Build a prefixed tool name: mcp__{server}__{tool} */
+export declare function buildMcpToolName(serverName: string, toolName: string): string;
+/** Get the prefix for a server (for batch removal) */
+export declare function getMcpServerPrefix(serverName: string): string;
+/** Parse a prefixed tool name back into server + tool */
+export declare function parseMcpToolName(prefixedName: string): McpToolIdentifier | null;
+/** Check if a tool name is an MCP-injected tool */
+export declare function isMcpToolName(name: string): boolean;

package/dist/types/skills/tools/mcp-resource-tools.d.ts

@@ -0,0 +1,14 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { McpManager } from "../mcp/mcp-manager.js";
+export interface ListMcpResourcesParams {
+    /** Filter by MCP server name (optional — omit to list from all servers) */
+    server?: string;
+}
+export declare function createListMcpResourcesTool(getMcpManager: () => McpManager | null): PortableTool<ListMcpResourcesParams>;
+export interface ReadMcpResourceParams {
+    /** MCP server name */
+    server: string;
+    /** Resource URI to read */
+    uri: string;
+}
+export declare function createReadMcpResourceTool(getMcpManager: () => McpManager | null): PortableTool<ReadMcpResourceParams>;