qlogicagent 2.2.0 → 2.4.0

package/dist/types/protocol/wire/agent-methods.d.ts

@@ -0,0 +1,587 @@
+/**
+ * Agent RPC Method Map — complete typed contract for ALL agent JSON-RPC methods.
+ *
+ * This extends GatewayRpcMethodMap (26 methods Gateway directly calls) with all
+ * additional agent-specific methods (thread, memory, config, agents, solo, product, etc.).
+ *
+ * Consumers use this for fully typed RPC clients:
+ *   import type { AgentRpcMethodMap } from "qlogicagent/protocol";
+ *   async function call<M extends keyof AgentRpcMethodMap>(method: M, params: AgentRpcMethodMap[M]["params"]): Promise<AgentRpcMethodMap[M]["result"]> { ... }
+ */
+import type { ChatMessage, ToolDefinition } from "./chat-types.js";
+import type { GatewayRpcMethodMap } from "./gateway-rpc.js";
+import type { WireTokenUsage } from "./notification-payloads.js";
+export type AgentCategory = "sub-agent" | "teammate";
+export type AgentProtocol = "internal" | "acp";
+export type AgentStatus = "available" | "unavailable" | "handshake_failed" | "not_installed";
+export interface AgentCapabilities {
+    supportsMcp: boolean;
+    supportsResume: boolean;
+    supportsUsageUpdate: boolean;
+    skillsDirs?: string[];
+}
+/** Descriptor for a discovered or registered agent. */
+export interface AgentDescriptor {
+    id: string;
+    name: string;
+    category: AgentCategory;
+    protocol: AgentProtocol;
+    status: AgentStatus;
+    cliPath?: string;
+    version?: string;
+    capabilities?: AgentCapabilities;
+    authRequired: boolean;
+    hasConfig: boolean;
+    supportsBaseUrlOverride: boolean;
+}
+/** User-provided custom agent definition. */
+export interface CustomAgentDef {
+    id: string;
+    name: string;
+    cliCommand: string;
+    acpArgs: string[];
+    env?: Record<string, string>;
+    authRequired?: boolean;
+    skillsDirs?: string[];
+    supportsBaseUrlOverride?: boolean;
+}
+/** Persisted per-agent configuration. */
+export interface AgentConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    env?: Record<string, string>;
+    customArgs?: string[];
+    customCliPath?: string;
+    modelIdMap?: Record<string, string>;
+}
+export type SoloState = "running" | "evaluating" | "completed" | "cancelled" | "failed";
+export type SoloAgentState = "pending" | "running" | "completed" | "failed";
+export interface SoloAgentResult {
+    id: string;
+    state: SoloAgentState;
+    progress?: string;
+    resultText?: string;
+    diff?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    error?: string;
+    worktreePath?: string;
+}
+export interface SoloStatus {
+    soloId: string;
+    state: SoloState;
+    agents: SoloAgentResult[];
+    evaluation?: {
+        winnerId: string;
+        reasoning: string;
+    };
+}
+export type ProductPhase = "active" | "paused" | "completed" | "failed";
+export type ProductTaskStatus = "pending" | "running" | "completed" | "failed" | "paused";
+export interface ProductInstanceDef {
+    name: string;
+    role: string;
+    agentId: string;
+}
+export interface ProductTaskDef {
+    taskId: string;
+    assignee: string;
+    prompt: string;
+    dependsOn?: string[];
+}
+export interface ProductStatus {
+    productId: string;
+    name: string;
+    phase: ProductPhase;
+    instances: Array<{
+        instanceId: string;
+        name: string;
+        agentId: string;
+        state: string;
+        worktreePath?: string;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>;
+    tasks: Array<{
+        taskId: string;
+        assignee: string;
+        status: ProductTaskStatus;
+        result?: string;
+        error?: string;
+        startedAt?: string;
+        completedAt?: string;
+    }>;
+    budget: {
+        maxTotalTokens?: number;
+        maxDuration?: number;
+        usedTokens: number;
+        elapsed: number;
+    };
+    lastCheckpointAt: string;
+}
+export interface ProductSummary {
+    productId: string;
+    name: string;
+    phase: ProductPhase;
+    instanceCount: number;
+    taskCount: number;
+    completedTasks: number;
+    createdAt: string;
+    lastCheckpointAt: string;
+}
+/**
+ * All agent RPC methods — superset of GatewayRpcMethodMap.
+ *
+ * Methods from GatewayRpcMethodMap (session.*, project.*, files.*, instructions.*)
+ * are inherited. This adds the agent-specific protocol methods.
+ */
+export interface AgentRpcMethodMap extends GatewayRpcMethodMap {
+    "initialize": {
+        params: {
+            protocolVersion: string;
+            host?: {
+                name: string;
+                version: string;
+            };
+            hostName?: string;
+            hostVersion?: string;
+            capabilities?: {
+                streaming?: boolean;
+                toolApproval?: boolean;
+                threads?: boolean;
+            };
+            config?: Record<string, unknown>;
+        };
+        result: {
+            protocolVersion: string;
+            agent: {
+                name: string;
+                version: string;
+            };
+            capabilities: {
+                tools: string[];
+                streaming: boolean;
+                threads: boolean;
+                notifications: string[];
+                methods: string[];
+            };
+        };
+    };
+    "thread.create": {
+        params: {
+            id?: string;
+            title?: string;
+            cwd?: string;
+            config?: Record<string, unknown>;
+        };
+        result: {
+            id: string;
+            title?: string;
+            status: "active";
+            createdAt: string;
+        };
+    };
+    "thread.list": {
+        params: {
+            limit?: number;
+        };
+        result: {
+            threads: Array<{
+                id: string;
+                title?: string;
+                status: "active" | "archived";
+                turnCount?: number;
+                createdAt: string;
+                lastActiveAt: string;
+            }>;
+        };
+    };
+    "thread.turn": {
+        params: {
+            turnId?: string;
+            sessionId: string;
+            messages?: ChatMessage[];
+            tools?: ToolDefinition[];
+            config?: Record<string, unknown>;
+        };
+        result: {
+            accepted: boolean;
+            turnId: string;
+        };
+    };
+    "session.resume": {
+        params: {
+            sessionId: string;
+        };
+        result: {
+            metadata: {
+                sessionId: string;
+                createdAt: number;
+                lastActiveAt: number;
+                model?: string;
+                cwd?: string;
+                turnCount: number;
+                messageCount: number;
+                title?: string;
+            };
+            messages: ChatMessage[];
+            costSnapshot?: Record<string, unknown>;
+        };
+    };
+    "session.getInfo": {
+        params: {
+            sessionId?: string;
+        };
+        result: {
+            sessionId: string;
+            paths: {
+                sessionDir: string;
+                transcript: string;
+                state: string;
+                agentHome: string;
+                settings: string;
+                cwd: string;
+            };
+            model?: string;
+            provider?: string;
+            turnCount: number;
+            title?: string;
+            usage?: {
+                totalPromptTokens: number;
+                totalCompletionTokens: number;
+                totalCost?: number;
+            };
+        };
+    };
+    "memory.list": {
+        params: {
+            source?: "local" | "store" | "qmemory" | "all";
+        };
+        result: {
+            entries: Array<{
+                source: "local" | "store" | "qmemory";
+                target?: string;
+                path?: string;
+                content?: string;
+                lines?: number;
+            }>;
+        };
+    };
+    "memory.read": {
+        params: {
+            source?: string;
+            target?: string;
+            path?: string;
+        };
+        result: {
+            content: string;
+            source: string;
+            path?: string;
+        };
+    };
+    "memory.write": {
+        params: {
+            source?: string;
+            target?: string;
+            path?: string;
+            content: string;
+            mode?: "overwrite" | "append";
+        };
+        result: {
+            ok: boolean;
+            path?: string;
+        };
+    };
+    "memory.search": {
+        params: {
+            query: string;
+            source?: "local" | "qmemory" | "all";
+            limit?: number;
+        };
+        result: {
+            results: Array<{
+                source: string;
+                target?: string;
+                content: string;
+                score?: number;
+                path?: string;
+            }>;
+        };
+    };
+    "memory.delete": {
+        params: {
+            source?: string;
+            target?: string;
+            path?: string;
+        };
+        result: {
+            ok: boolean;
+            deleted?: number;
+        };
+    };
+    "memory.dream": {
+        params: {
+            scope?: "session" | "project" | "all";
+        };
+        result: {
+            ok: boolean;
+            consolidated: number;
+            archived: number;
+            durationMs: number;
+        };
+    };
+    "tools.list": {
+        params: {
+            category?: string;
+            includeDisabled?: boolean;
+        };
+        result: {
+            tools: Array<{
+                name: string;
+                description: string;
+                category: string;
+                enabled: boolean;
+                parameters?: Record<string, unknown>;
+            }>;
+        };
+    };
+    "media.listModels": {
+        params: {
+            mediaType?: string;
+        };
+        result: {
+            models: Array<{
+                id: string;
+                name: string;
+                mediaType: string;
+                provider: string;
+                capabilities?: Record<string, unknown>;
+            }>;
+        };
+    };
+    "config.get": {
+        params: {
+            keys?: string[];
+        };
+        result: {
+            config: Record<string, unknown>;
+        };
+    };
+    "config.update": {
+        params: {
+            updates: Record<string, unknown>;
+        };
+        result: {
+            ok: boolean;
+        };
+    };
+    "todos.list": {
+        params: {
+            sessionId?: string;
+        };
+        result: {
+            items: Array<{
+                id: number;
+                title: string;
+                status: string;
+                owner?: string;
+                blockedBy?: number[];
+            }>;
+            summary: string;
+        };
+    };
+    "tasks.list": {
+        params: {
+            status?: string;
+        };
+        result: {
+            tasks: Array<{
+                id: string;
+                type: string;
+                status: string;
+                progress?: number;
+                createdAt: string;
+            }>;
+        };
+    };
+    "tasks.cancel": {
+        params: {
+            taskId: string;
+        };
+        result: {
+            ok: boolean;
+        };
+    };
+    "agent.ping": {
+        params: undefined;
+        result: {
+            status: "idle" | "busy";
+            uptime: number;
+            version: string;
+            usage?: WireTokenUsage;
+        };
+    };
+    "agent.abort": {
+        params: {
+            turnId?: string;
+            reason?: string;
+        };
+        result: {
+            aborted: boolean;
+        };
+    };
+    "tool.approval.response": {
+        params: {
+            approvalId: string;
+            approved: boolean;
+            message?: string;
+        };
+        result: {
+            received: boolean;
+        };
+    };
+    "agents.scan": {
+        params: {
+            force?: boolean;
+        };
+        result: AgentDescriptor[];
+    };
+    "agents.list": {
+        params: undefined;
+        result: AgentDescriptor[];
+    };
+    "agents.config": {
+        params: {
+            action: "register" | "unregister" | "update";
+            agent: CustomAgentDef;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "agents.setConfig": {
+        params: {
+            agentId: string;
+            apiKey?: string;
+            baseUrl?: string;
+            model?: string;
+            env?: Record<string, string>;
+            customArgs?: string[];
+            customCliPath?: string;
+            modelIdMap?: Record<string, string>;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "agents.getConfig": {
+        params: {
+            agentId: string;
+        };
+        result: AgentConfig | null;
+    };
+    "agents.removeConfig": {
+        params: {
+            agentId: string;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "agents.setGateway": {
+        params: {
+            url: string;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "solo.start": {
+        params: {
+            task: string;
+            agents: string[];
+            cwd: string;
+        };
+        result: {
+            soloId: string;
+        };
+    };
+    "solo.status": {
+        params: {
+            soloId: string;
+        };
+        result: SoloStatus | null;
+    };
+    "solo.cancel": {
+        params: {
+            soloId: string;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "solo.select": {
+        params: {
+            soloId: string;
+            winnerId: string;
+        };
+        result: {
+            ok: true;
+            mergedBranch: string;
+        };
+    };
+    "product.create": {
+        params: {
+            name: string;
+            cwd: string;
+            instances: ProductInstanceDef[];
+            tasks: ProductTaskDef[];
+            budget?: {
+                maxTotalTokens?: number;
+                maxDuration?: number;
+            };
+        };
+        result: {
+            productId: string;
+        };
+    };
+    "product.resume": {
+        params: {
+            productId: string;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "product.pause": {
+        params: {
+            productId: string;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "product.checkpoint": {
+        params: {
+            productId: string;
+        };
+        result: {
+            ok: true;
+        };
+    };
+    "product.status": {
+        params: {
+            productId: string;
+        };
+        result: ProductStatus | null;
+    };
+    "product.list": {
+        params: undefined;
+        result: ProductSummary[];
+    };
+}

package/dist/types/protocol/wire/agent-rpc.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Protocol version. Both sides exchange this during `agent.hello`
+ * handshake. If major versions differ the host MUST reject.
+ */
+export declare const AGENT_RPC_PROTOCOL_VERSION: "1.0.0";
+export declare const AGENT_RPC_ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly TURN_ABORTED: -32000;
+    readonly TURN_TIMEOUT: -32001;
+    readonly LLM_ERROR: -32010;
+    readonly LLM_AUTH_ERROR: -32011;
+    readonly LLM_RATE_LIMIT: -32012;
+    readonly LLM_QUOTA_EXHAUSTED: -32013;
+    readonly LLM_MODEL_NOT_FOUND: -32014;
+    readonly TOOL_INVOKE_FAILED: -32020;
+    readonly TOOL_TIMEOUT: -32021;
+    readonly PROTOCOL_MISMATCH: -32030;
+};
+export type AgentRpcErrorCode = (typeof AGENT_RPC_ERROR_CODES)[keyof typeof AGENT_RPC_ERROR_CODES];
+export interface AgentRpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number;
+}
+export interface AgentRpcError {
+    code: AgentRpcErrorCode | number;
+    message: string;
+    data?: unknown;
+}
+export interface AgentRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: AgentRpcError;
+}
+export interface AgentRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params: Record<string, unknown>;
+}
+export type AgentRpcMessage = AgentRpcRequest | AgentRpcResponse | AgentRpcNotification;
+/** Sent by host to agent CLI as params of `agent.hello` request. */
+export interface AgentHelloParams {
+    protocolVersion: string;
+    hostName: string;
+    hostVersion: string;
+    capabilities?: string[];
+}
+/** Returned by agent CLI as result of `agent.hello` request. */
+export interface AgentHelloResult {
+    protocolVersion: string;
+    agentName: string;
+    agentVersion: string;
+    capabilities?: string[];
+}
+/**
+ * Agent → Host notification: agent requests human approval before executing a tool.
+ * Method name: `tool.approval.request`
+ */
+export interface ToolApprovalRequestParams {
+    /** Unique id for this approval request (used to correlate the response). */
+    approvalId: string;
+    /** Tool call id from the LLM. */
+    callId: string;
+    /** Tool name. */
+    toolName: string;
+    /** Serialized arguments JSON. */
+    arguments: string;
+    /** Human-readable reason for requiring approval. */
+    message?: string;
+    /** Suggested actions the user can pick (allow-once, allow-always, deny). */
+    suggestions?: string[];
+}
+/**
+ * Host → Agent notification: host relays the user's approval decision.
+ * Method name: `tool.approval.response`
+ */
+export interface ToolApprovalResponseParams {
+    /** Must match the `approvalId` from the request. */
+    approvalId: string;
+    /** User's decision. */
+    decision: "allow-once" | "allow-session" | "allow-always" | "deny";
+}
+/** Well-known method names for the approval protocol. */
+export declare const AGENT_RPC_APPROVAL_METHODS: {
+    readonly REQUEST: "tool.approval.request";
+    readonly RESPONSE: "tool.approval.response";
+};
+export declare function isAgentRpcRequest(msg: unknown): msg is AgentRpcRequest;
+export declare function isAgentRpcResponse(msg: unknown): msg is AgentRpcResponse;
+export declare function isAgentRpcNotification(msg: unknown): msg is AgentRpcNotification;
+export declare function parseAgentRpcMessage(raw: string): AgentRpcMessage | null;