qlogicagent 1.1.0 → 1.2.0

package/dist/types/runtime/infra/acp-types.d.ts

@@ -0,0 +1,397 @@
+/**
+ * ACP (Agent-Client Protocol) type definitions for third-party agent management.
+ *
+ * These types define the contract for discovering, registering, and managing
+ * external ACP-compatible agent CLIs alongside qlogicagent's internal agents.
+ */
+/**
+ * Two-level agent taxonomy:
+ *   - sub-agent: internal qlogicagent instance, budget/tool restricted
+ *   - teammate:  external ACP CLI agent, full capability
+ */
+export type AgentCategory = "sub-agent" | "teammate";
+/** Communication protocol with the agent. */
+export type AgentProtocol = "internal" | "acp";
+/** Agent availability status. */
+export type AgentStatus = "available" | "unavailable" | "handshake_failed" | "not_installed";
+/** Pre-defined configuration for a known ACP backend. */
+export interface AcpBackendConfig {
+    /** Backend ID, e.g. "claude" | "codex" | "goose". */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** CLI command name (target for which/where scan). */
+    cliCommand: string;
+    /** ACP mode launch arguments. */
+    acpArgs: string[];
+    /** npx fallback path when CLI is not in PATH. */
+    defaultCliPath?: string;
+    /** Environment variables injected at launch. */
+    env?: Record<string, string>;
+    /** Whether authentication is required. */
+    authRequired: boolean;
+    /** Native skill directories. */
+    skillsDirs?: string[];
+    /** Whether this backend supports base URL override. */
+    supportsBaseUrlOverride: boolean;
+    /** Environment variable name for the API key. */
+    apiKeyEnvVar?: string;
+    /** Environment variable name for the base URL. */
+    baseUrlEnvVar?: string;
+}
+/** Capabilities discovered during ACP handshake. */
+export interface AgentCapabilities {
+    /** Whether the agent supports MCP server injection via session/new. */
+    supportsMcp: boolean;
+    /** Whether the agent supports session/resume. */
+    supportsResume: boolean;
+    /** Whether the agent sends usage_update notifications. */
+    supportsUsageUpdate: boolean;
+    /** Native skill directories, if any. */
+    skillsDirs?: string[];
+}
+/**
+ * Descriptor for a discovered or registered agent.
+ * Returned by `agents.scan` and `agents.list` RPCs.
+ */
+export interface AgentDescriptor {
+    /** Backend ID, e.g. "claude", "codex", "qlogicagent". */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** sub-agent (internal) or teammate (external). */
+    category: AgentCategory;
+    /** Communication protocol. */
+    protocol: AgentProtocol;
+    /** Current availability. */
+    status: AgentStatus;
+    /** Resolved CLI binary path (teammates only). */
+    cliPath?: string;
+    /** CLI version string (teammates only). */
+    version?: string;
+    /** Capabilities (populated after handshake). */
+    capabilities?: AgentCapabilities;
+    /** Whether auth is required. */
+    authRequired: boolean;
+    /** Whether user has configured this agent (apiKey / baseUrl). */
+    hasConfig: boolean;
+    /** Whether this agent supports LLM base URL redirection. */
+    supportsBaseUrlOverride: boolean;
+}
+/**
+ * Extended descriptor for external agents,
+ * used internally by AgentProcessManager to spawn.
+ */
+export interface ExternalAgentDescriptor {
+    /** Backend ID. */
+    id: string;
+    /** Resolved CLI binary path. */
+    cliPath: string;
+    /** ACP launch arguments. */
+    acpArgs: string[];
+    /** Extra environment variables for spawn. */
+    env?: Record<string, string>;
+    /** Communication protocol. */
+    protocol: "acp";
+}
+/** User-provided custom agent definition for agents.config RPC. */
+export interface CustomAgentDef {
+    /** Unique ID (user-chosen). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** CLI command or absolute path. */
+    cliCommand: string;
+    /** ACP mode launch arguments. */
+    acpArgs: string[];
+    /** Additional environment variables. */
+    env?: Record<string, string>;
+    /** Whether auth is required. */
+    authRequired?: boolean;
+    /** Native skill directories. */
+    skillsDirs?: string[];
+    /** Whether base URL override is supported. */
+    supportsBaseUrlOverride?: boolean;
+}
+/** Persisted per-agent configuration. */
+export interface AgentConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    env?: Record<string, string>;
+    customArgs?: string[];
+    customCliPath?: string;
+    /** Model ID translation: qlogicModelId → externalModelId. */
+    modelIdMap?: Record<string, string>;
+}
+/** Root config store schema (persisted to JSON). */
+export interface AgentConfigStoreData {
+    /** Global gateway proxy URL. */
+    gatewayUrl?: string;
+    /** Per-agent override configurations. */
+    agents: Record<string, AgentConfig>;
+    /** User-registered custom agents. */
+    customAgents?: Record<string, CustomAgentDef>;
+}
+/** ACP initialize result (from agent's response). */
+export interface AcpInitializeResult {
+    protocolVersion: number;
+    capabilities: {
+        prompts?: boolean;
+        /** Whether this agent supports session/resume (D-1). */
+        supportsResume?: boolean;
+        [key: string]: unknown;
+    };
+    serverInfo?: {
+        name: string;
+        version?: string;
+    };
+}
+/** ACP session/new result. */
+export interface AcpSessionResult {
+    id: string;
+}
+/** ACP prompt response content item. */
+export interface AcpContentItem {
+    type: "text" | "image" | "resource";
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+/** ACP prompt response. */
+export interface AcpPromptResponse {
+    content: AcpContentItem[];
+    usage?: AcpPromptResponseUsage;
+}
+/** ACP per-turn usage stats. */
+export interface AcpPromptResponseUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cachedReadTokens?: number;
+    thoughtTokens?: number;
+}
+/** ACP usage_update notification payload (session-level). */
+export interface AcpUsageUpdatePayload {
+    used?: number;
+    size?: number;
+    cost?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+/** MCP server config to inject into ACP session/new. */
+export interface McpServerConfig {
+    name: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface AgentsScanParams {
+    force?: boolean;
+}
+export interface AgentsConfigParams {
+    action: "register" | "unregister" | "update";
+    agent: CustomAgentDef;
+}
+export interface AgentsSetConfigParams {
+    agentId: string;
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    env?: Record<string, string>;
+    customArgs?: string[];
+    customCliPath?: string;
+    modelIdMap?: Record<string, string>;
+}
+export interface AgentsGetConfigParams {
+    agentId: string;
+}
+export interface AgentsRemoveConfigParams {
+    agentId: string;
+}
+export interface AgentsSetGatewayParams {
+    url: 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 SoloEvaluation {
+    winnerId: string;
+    reasoning: string;
+}
+export interface SoloStatus {
+    soloId: string;
+    state: SoloState;
+    agents: SoloAgentResult[];
+    evaluation?: SoloEvaluation;
+}
+/** solo.start RPC params. */
+export interface SoloStartParams {
+    task: string;
+    agents: string[];
+    cwd: string;
+}
+/** solo.status / solo.cancel / solo.select RPC params. */
+export interface SoloIdParams {
+    soloId: string;
+}
+/** solo.select RPC params. */
+export interface SoloSelectParams {
+    soloId: string;
+    winnerId: string;
+}
+export type ProductPhase = "active" | "paused" | "completed" | "failed";
+export type ProductInstanceState = "idle" | "running" | "completed" | "failed" | "paused";
+export type ProductTaskStatus = "pending" | "running" | "completed" | "failed" | "paused";
+/** Product budget configuration & runtime counters. */
+export interface ProductBudget {
+    maxTotalTokens?: number;
+    maxDuration?: number;
+    usedTokens: number;
+    elapsed: number;
+}
+/** Instance definition within a product. */
+export interface ProductInstanceDef {
+    name: string;
+    role: string;
+    agentId: string;
+}
+/** Task definition within a product DAG. */
+export interface ProductTaskDef {
+    taskId: string;
+    assignee: string;
+    prompt: string;
+    dependsOn?: string[];
+}
+/** product.create RPC params. */
+export interface ProductCreateParams {
+    name: string;
+    cwd: string;
+    instances: ProductInstanceDef[];
+    tasks: ProductTaskDef[];
+    budget?: {
+        maxTotalTokens?: number;
+        maxDuration?: number;
+    };
+}
+/** product.resume / product.pause / product.checkpoint / product.status RPC params. */
+export interface ProductIdParams {
+    productId: string;
+}
+/** Runtime instance state. */
+export interface ProductInstanceStatus {
+    instanceId: string;
+    name: string;
+    agentId: string;
+    state: ProductInstanceState;
+    worktreePath?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** Runtime task state. */
+export interface ProductTaskState {
+    taskId: string;
+    assignee: string;
+    status: ProductTaskStatus;
+    result?: string;
+    error?: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+/** Full product status (product.status response). */
+export interface ProductStatus {
+    productId: string;
+    name: string;
+    phase: ProductPhase;
+    instances: ProductInstanceStatus[];
+    tasks: ProductTaskState[];
+    budget: ProductBudget;
+    lastCheckpointAt: string;
+}
+/** Summary for product.list response. */
+export interface ProductSummary {
+    productId: string;
+    name: string;
+    phase: ProductPhase;
+    instanceCount: number;
+    taskCount: number;
+    completedTasks: number;
+    createdAt: string;
+    lastCheckpointAt: string;
+}
+/** agents.getGateway response. */
+export interface AgentsGetGatewayResult {
+    url?: string;
+}
+/** agents.listConfigured response item. */
+export interface AgentsListConfiguredItem {
+    agentId: string;
+    hasApiKey: boolean;
+    hasBaseUrl: boolean;
+    hasModel: boolean;
+}
+/** agents.processes response item. */
+export interface AgentsProcessInfo {
+    memberId: string;
+    name: string;
+    pid: number;
+    state: string;
+    startedAt: number;
+    endedAt?: number;
+    source: "solo" | "product";
+}
+/** agents.kill RPC params. */
+export interface AgentsKillParams {
+    memberId: string;
+}
+/** agents.getLog RPC params. */
+export interface AgentsGetLogParams {
+    agentId: string;
+    tail?: number;
+}
+/** agents.getLog response. */
+export interface AgentsGetLogResult {
+    log: string;
+}
+/** agents.testConnection RPC params. */
+export interface AgentsTestConnectionParams {
+    agentId: string;
+    timeoutMs?: number;
+}
+/** agents.testConnection response. */
+export interface AgentsTestConnectionResult {
+    ok: boolean;
+    version?: string;
+    capabilities?: AgentCapabilities;
+    error?: string;
+    durationMs: number;
+}
+/** solo.delete / solo.cancel cleanup RPC params. */
+export interface SoloDeleteParams {
+    soloId: string;
+}
+/** product.delete cleanup RPC params. */
+export interface ProductDeleteParams {
+    productId: string;
+}
+/** Agent source attribution, attached to turn events when delegated. */
+export interface AgentSource {
+    id: string;
+    name: string;
+    role: "main" | "teammate";
+}

package/dist/types/runtime/infra/acp-usage-tracker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ACP Usage Tracker — 3-tier token usage tracking for external ACP agents.
+ *
+ * Tier 1: Real-time `usage_update` notifications (preferred).
+ * Tier 2: Per-turn `PromptResponse.usage` fallback.
+ * Tier 3: Graceful degradation — no usage data, no budget enforcement.
+ *
+ * The tracker prevents double-counting when an agent sends both
+ * usage_update notifications AND prompt response usage.
+ */
+import type { AcpUsageUpdatePayload, AcpPromptResponseUsage } from "./acp-types.js";
+export interface AccumulatedUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedReadTokens: number;
+    thoughtTokens: number;
+    /** Total cost (USD), if reported. */
+    cost: number;
+    /** Whether at least one usage_update was received (Tier 1 active). */
+    hasTier1: boolean;
+    /** Number of turns processed (Tier 2 fallback). */
+    turnCount: number;
+}
+export declare class AcpUsageTracker {
+    private usage;
+    /**
+     * Tier 1: Handle a `usage_update` notification from ACP agent.
+     * Sets the hasTier1 flag to prevent double-counting from Tier 2.
+     */
+    onUsageUpdate(payload: AcpUsageUpdatePayload): void;
+    /**
+     * Tier 2: Handle per-turn usage from PromptResponse.
+     * Only applied if Tier 1 is NOT active (prevents double-counting).
+     */
+    onPromptResponseUsage(usage: AcpPromptResponseUsage | undefined): void;
+    /** Get the current accumulated usage snapshot. */
+    getUsage(): Readonly<AccumulatedUsage>;
+    /** Reset all counters. */
+    reset(): void;
+    /**
+     * Check whether we have any usage data.
+     * Returns false in Tier 3 (graceful degradation).
+     */
+    hasData(): boolean;
+}

package/dist/types/runtime/infra/acp-usage-tracker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/infra/agent-config-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent Config Store — persistent per-agent configuration with project + global fallback.
+ *
+ * Storage paths:
+ *   - Project-level: `<cwd>/.qlogicagent/agent-configs.json`
+ *   - User-level:    `~/.qlogicagent/agent-configs.json`
+ *
+ * Merge strategy: project-level overrides take precedence.
+ * Sensitive fields (apiKey) use file permissions 0o600 on Unix.
+ */
+import type { AgentConfig, AgentConfigStoreData, CustomAgentDef } from "./acp-types.js";
+export declare class AgentConfigStore {
+    private data;
+    private cwd;
+    constructor(cwd?: string);
+    /** Load config from disk. Project-level merges on top of user-level. */
+    load(): Promise<void>;
+    /** Get the full store data (for AcpDetector.setConfigStore). */
+    getData(): AgentConfigStoreData;
+    getAgentConfig(agentId: string): AgentConfig | null;
+    setAgentConfig(agentId: string, config: AgentConfig): Promise<void>;
+    removeAgentConfig(agentId: string): Promise<void>;
+    getGatewayUrl(): string | undefined;
+    setGatewayUrl(url: string): Promise<void>;
+    registerCustomAgent(def: CustomAgentDef): void;
+    unregisterCustomAgent(agentId: string): void;
+    getCustomAgents(): Record<string, CustomAgentDef>;
+    /** Save to user-level config. Restricts permissions for sensitive data. */
+    private save;
+}

package/dist/types/runtime/infra/agent-config-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/infra/agent-paths.d.ts

@@ -53,5 +53,13 @@ export declare function getProjectSettingsPath(cwd?: string): string;
 export declare function getProjectInstructionsPath(cwd?: string): string;
 /** `<cwd>/.qlogicagent/rules/` */
 export declare function getProjectRulesDir(cwd?: string): string;
+/** `<cwd>/.qlogicagent/sessions/` */
+export declare function getProjectSessionsRoot(cwd: string): string;
+/** `<cwd>/.qlogicagent/sessions/{sessionId}` */
+export declare function getProjectSessionDir(cwd: string, sessionId: string): string;
+/** `<cwd>/.qlogicagent/checkpoints/` or `<cwd>/.qlogicagent/checkpoints/{sessionId}` */
+export declare function getProjectCheckpointsDir(cwd: string, sessionId?: string): string;
+/** `<cwd>/.qlogicagent/memory.json` */
+export declare function getProjectMemoryPath(cwd: string): string;
 /** `<gitRoot>/.qlogicagent/hooks/` */
 export declare function getGitRootHooksDir(gitRoot: string): string;