qlogicagent 0.5.2 → 0.6.0

package/dist/types/cli/stdio-server.d.ts

@@ -0,0 +1,78 @@
+/**
+ * StdioServer — JSON-RPC 2.0 protocol handler.
+ *
+ * Receives JSON-RPC messages from a Transport, dispatches to handlers,
+ * writes JSON-RPC responses/notifications back through the Transport.
+ * All log output goes to stderr.
+ *
+ * Protocol: each message is a single JSON-RPC 2.0 object.
+ * The physical I/O layer is abstracted via the Transport interface.
+ */
+import type { Transport } from "./transport.js";
+export interface StdioServerConfig {
+    verbose: boolean;
+    transport?: Transport;
+}
+export declare class StdioServer {
+    private running;
+    private activeTurn;
+    private verbose;
+    private transport;
+    private registry;
+    private agent;
+    private lastLlmConfigKey;
+    private currentSessionId;
+    private currentHooks;
+    private mcpManager;
+    private pluginLoader;
+    private permissionChecker;
+    private permissionUnregister;
+    /** Cached LLM transport for sub-agent forks (dream, session-memory) */
+    private currentTransport;
+    private currentApiKey;
+    private currentModel;
+    private sessionState;
+    private taskStore;
+    /** Session-scoped memory prefetch state (LRU dedup + byte limit). */
+    private memoryPrefetchState;
+    /** QMemory adapter (when QMEMORY_BASE_URL env is set). Used by Dream hippocampus bridge. */
+    private qmemoryAdapter;
+    private qmemoryUserId;
+    private fileWatcher;
+    constructor(config: StdioServerConfig);
+    start(): void;
+    stop(): void;
+    private handleMessage;
+    /**
+     * `initialize` — the sole handshake handler.
+     * Accepts both legacy flat params (`hostName`, `hostVersion`) and
+     * Codex-style nested params (`host.name`, `host.version`).
+     * Always returns the InitializeResult shape.
+     */
+    private handleInitialize;
+    /**
+     * `thread.create` — create a new thread (session container).
+     * Maps threadId → sessionId for the underlying session system.
+     */
+    private handleThreadCreate;
+    /**
+     * `thread.list` — list available threads. Delegates to session listing.
+     */
+    private handleThreadList;
+    private handlePing;
+    private handleAbort;
+    private handleApprovalResponse;
+    private handleSessionResume;
+    private handleTurn;
+    private handleDream;
+    private resolveAgent;
+    /**
+     * Load LLM settings from ~/.qlogicagent/settings.json (sync).
+     * Returns provider/model/apiKey if found, undefined otherwise.
+     */
+    private loadSettingsSync;
+    private sendResponse;
+    private sendNotification;
+    private writeStdout;
+    private log;
+}

package/dist/types/cli/tool-bootstrap.d.ts

@@ -0,0 +1,40 @@
+import type { PortableTool } from "../skills/portable-tool.js";
+import { type ExecProgress } from "../skills/tools/exec-tool.js";
+import type { AgentLogger } from "../agent/types.js";
+export interface MediaRelayConfig {
+    imageEndpoint?: string;
+    ttsEndpoint?: string;
+    videoEndpoint?: string;
+    videoEditEndpoint?: string;
+    videoMergeEndpoint?: string;
+    videoUpscaleEndpoint?: string;
+    musicEndpoint?: string;
+}
+/**
+ * Set the media relay config for multimedia tools.
+ * CC parity: tools use isEnabled() gates instead of conditional addTool().
+ * Call this before getAllBaseTools() or when config changes.
+ */
+export declare function setMediaConfig(config: MediaRelayConfig | undefined): void;
+export interface BootstrapConfig {
+    workdir?: string;
+    log?: AgentLogger;
+    /** Called during foreground shell execution with incremental progress. */
+    onExecProgress?(progress: ExecProgress): void;
+}
+/**
+ * Create all locally-executable tools and install into centralized tool pool.
+ *
+ * CC parity: getAllBaseTools() returns flat array, installed via setToolPool().
+ * Tools execute IN-PROCESS (zero IPC).
+ *
+ * @alias initToolDeps — kept for backward compat with existing call sites.
+ */
+export declare function getAllBaseTools(config?: BootstrapConfig): PortableTool[];
+/** @deprecated Use getAllBaseTools() instead. */
+export declare const initToolDeps: typeof getAllBaseTools;
+/**
+ * Update the working directory for all local tool deps.
+ * Called when Gateway sends a new workdir via config.
+ */
+export declare function setBootstrapWorkdir(newWorkdir: string): void;

package/dist/types/cli/transport.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Transport — abstract I/O layer for JSON-RPC message exchange.
+ *
+ * Decouples the agent protocol handler from the physical transport
+ * (stdin/stdout, WebSocket, Unix Domain Socket, etc.).
+ *
+ * Each transport reads incoming JSON-RPC messages and emits them
+ * to a registered handler; outgoing messages are sent via send().
+ */
+export interface Transport {
+    /** Register the message handler (called for each valid parsed message). */
+    onMessage(handler: (msg: unknown) => void): void;
+    /** Register the close handler (called when the transport closes). */
+    onClose(handler: () => void): void;
+    /** Send a JSON-RPC message (object will be serialized to JSON). */
+    send(msg: unknown): void;
+    /** Start listening for incoming messages. */
+    start(): void;
+    /** Close the transport gracefully. */
+    close(): void;
+}
+/**
+ * Line-delimited JSON over stdin/stdout.
+ * Each line on stdin is a JSON message; each send() writes one JSON line to stdout.
+ * All diagnostic logging goes to stderr.
+ */
+export declare class StdioTransport implements Transport {
+    private messageHandler;
+    private closeHandler;
+    private verbose;
+    constructor(opts?: {
+        verbose?: boolean;
+    });
+    onMessage(handler: (msg: unknown) => void): void;
+    onClose(handler: () => void): void;
+    send(msg: unknown): void;
+    start(): void;
+    close(): void;
+    private log;
+}

package/dist/types/config/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Centralized CLI startup configuration.
+ *
+ * Parses and validates all configuration from CLI args and environment.
+ * Single source of truth for qlogicagent runtime config.
+ */
+export interface AgentConfig {
+    /** Enable verbose logging to stderr. */
+    verbose: boolean;
+}
+/**
+ * Parse CLI arguments into AgentConfig.
+ *
+ * Supports:
+ *   --verbose / -v   Enable verbose logging
+ */
+export declare function parseCliArgs(argv: string[]): AgentConfig;

package/dist/types/contracts/hooks.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Hook system types for the Agent Runtime.
+ *
+ * Hooks allow hosts and middleware to intercept, modify, or observe events
+ * at well-defined lifecycle points during session, turn, and tool execution.
+ */
+/**
+ * All supported hook points in the Agent Runtime lifecycle.
+ */
+export type HookPoint = "session.created" | "session.ended" | "turn.submitted" | "turn.before_inference" | "turn.after_inference" | "turn.completed" | "turn.failed" | "tool.before_invoke" | "tool.after_invoke" | "tool.invoke_failed" | "approval.requested" | "approval.responded" | "permission.denied" | "context.before_compact" | "context.after_compact" | "memory.before_recall" | "memory.after_recall" | "subagent.started" | "subagent.stopped" | "stop" | "stop.failed" | "stop.failure" | "task.created" | "task.completed" | "file.changed" | "cwd.changed" | "config.changed" | "instructions.loaded";
+export interface HookSessionContext {
+    sessionId: string;
+    gatewayId?: string;
+    deviceId?: string;
+    mode?: string;
+}
+export interface HookTurnContext extends HookSessionContext {
+    turnId: string;
+    executionId?: string;
+    rootExecutionId?: string;
+}
+export interface HookToolContext extends HookTurnContext {
+    callId: string;
+    toolName: string;
+    arguments?: Record<string, unknown>;
+}
+export interface HookApprovalContext extends HookTurnContext {
+    approvalId: string;
+    callId?: string;
+    toolName?: string;
+    decision?: "approved" | "denied" | "expired" | "cancelled";
+}
+export interface HookSubagentContext extends HookTurnContext {
+    subagentId: string;
+    agentType?: string;
+    parentExecutionId?: string;
+    /** Exit reason when stopped (normal / error / timeout) */
+    reason?: string;
+    error?: string;
+}
+export interface HookStopContext extends HookSessionContext {
+    reason?: string;
+    error?: string;
+}
+export interface HookTaskContext extends HookSessionContext {
+    taskId: string;
+    taskType?: string;
+    label?: string;
+    error?: string;
+}
+export interface HookFileChangedContext extends HookSessionContext {
+    filePath: string;
+    changeType: "created" | "modified" | "deleted";
+}
+export interface HookCwdChangedContext extends HookSessionContext {
+    oldCwd: string;
+    newCwd: string;
+}
+export interface HookConfigChangedContext extends HookSessionContext {
+    key: string;
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+export interface HookInstructionsLoadedContext extends HookSessionContext {
+    source: string;
+    fileCount: number;
+}
+export interface HookContextMap {
+    "session.created": HookSessionContext;
+    "session.ended": HookSessionContext;
+    "turn.submitted": HookTurnContext & {
+        prompt?: string;
+    };
+    "turn.before_inference": HookTurnContext & {
+        model?: string;
+        messages?: unknown[];
+    };
+    "turn.after_inference": HookTurnContext & {
+        model?: string;
+        response?: unknown;
+        success?: boolean;
+        error?: string;
+    };
+    "turn.completed": HookTurnContext & {
+        outcomeId?: string;
+    };
+    "turn.failed": HookTurnContext & {
+        code?: string;
+        error?: string;
+    };
+    "tool.before_invoke": HookToolContext;
+    "tool.after_invoke": HookToolContext & {
+        result?: unknown;
+        ok: boolean;
+    };
+    "tool.invoke_failed": HookToolContext & {
+        error?: string;
+    };
+    "approval.requested": HookApprovalContext;
+    "approval.responded": HookApprovalContext;
+    "permission.denied": HookApprovalContext & {
+        reason?: string;
+    };
+    "context.before_compact": HookTurnContext & {
+        tokenCount?: number;
+        messageCount?: number;
+    };
+    "context.after_compact": HookTurnContext & {
+        tokenCount?: number;
+        removedCount?: number;
+    };
+    "memory.before_recall": HookTurnContext & {
+        query?: string;
+        recalledMemories?: Array<{
+            text: string;
+            score?: number;
+        }>;
+    };
+    "memory.after_recall": HookTurnContext & {
+        blockCount?: number;
+    };
+    "subagent.started": HookSubagentContext;
+    "subagent.stopped": HookSubagentContext;
+    "stop": HookStopContext;
+    "stop.failed": HookStopContext;
+    "stop.failure": HookStopContext & {
+        errorDetails?: string;
+    };
+    "task.created": HookTaskContext;
+    "task.completed": HookTaskContext;
+    "file.changed": HookFileChangedContext;
+    "cwd.changed": HookCwdChangedContext;
+    "config.changed": HookConfigChangedContext;
+    "instructions.loaded": HookInstructionsLoadedContext;
+}
+/**
+ * Result of a hook handler invocation.
+ *
+ * - `continue`: proceed normally (optionally with modified context)
+ * - `abort`: stop execution (for "before" hooks only)
+ * - `skip`: skip this step but continue the overall flow
+ */
+export interface HookResult<T = unknown> {
+    action: "continue" | "abort" | "skip" | "prevent";
+    /** Modified context to pass downstream (only for "continue") */
+    context?: T;
+    /** Reason for abort/skip/prevent (for logging) */
+    reason?: string;
+}
+/**
+ * A hook handler function.
+ *
+ * @param point - The hook point being invoked
+ * @param context - Event-specific context data
+ * @returns A HookResult or void (treated as "continue")
+ */
+export type HookHandler<P extends HookPoint = HookPoint> = (point: P, context: HookContextMap[P]) => HookResult<HookContextMap[P]> | void | Promise<HookResult<HookContextMap[P]> | void>;
+/**
+ * Hook registration entry.
+ */
+export interface HookRegistration<P extends HookPoint = HookPoint> {
+    point: P;
+    handler: HookHandler<P>;
+    /** Priority (lower = earlier). Default: 100 */
+    priority?: number;
+    /** Optional label for debugging */
+    label?: string;
+}
+/**
+ * Interface for a hook registry that manages hook handlers.
+ */
+export interface HookRegistry {
+    register<P extends HookPoint>(registration: HookRegistration<P>): () => void;
+    invoke<P extends HookPoint>(point: P, context: HookContextMap[P]): Promise<HookResult<HookContextMap[P]>>;
+}

package/dist/types/contracts/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal contracts — types internalized from qlogicagent-runtime-contracts.
+ *
+ * These types are only consumed within qlogicagent itself (agent runtime + hub).
+ * They were removed from the public npm package to slim the cross-repo API surface.
+ */
+export * from "./planner.js";
+export * from "./todo.js";
+export * from "./hooks.js";

package/dist/types/contracts/planner.d.ts

@@ -0,0 +1,35 @@
+export declare const TASK_STEP_STATUS_VALUES: readonly ["pending", "in-progress", "completed", "skipped"];
+export type TaskStepStatus = (typeof TASK_STEP_STATUS_VALUES)[number];
+export declare const TASK_PLAN_STATUS_VALUES: readonly ["active", "completed", "abandoned"];
+export type TaskPlanStatus = (typeof TASK_PLAN_STATUS_VALUES)[number];
+export interface TaskStep {
+    index: number;
+    description: string;
+    status: TaskStepStatus;
+    result?: string;
+}
+export interface TaskPlan {
+    id: string;
+    sessionId: string;
+    userId: string;
+    goal: string;
+    steps: TaskStep[];
+    status: TaskPlanStatus;
+    createdAt: string;
+    updatedAt: string;
+    constraints?: string[];
+    keyIdentifiers?: string[];
+}
+export interface TaskPlanContextSnippet {
+    text: string;
+    tokens: number;
+    planId: string;
+}
+export interface TaskPlanProgressSnapshot {
+    goal: string;
+    steps: Array<{
+        description: string;
+        status: TaskStepStatus | string;
+        result?: string;
+    }>;
+}

package/dist/types/contracts/todo.d.ts

@@ -0,0 +1,23 @@
+export declare const TODO_ITEM_STATUS_VALUES: readonly ["not-started", "in-progress", "completed"];
+export type TodoItemStatus = (typeof TODO_ITEM_STATUS_VALUES)[number];
+export interface TodoItem {
+    id: number;
+    title: string;
+    status: TodoItemStatus;
+    /** Detailed task description (V2). */
+    description?: string;
+    /** Owner agent/subagent identifier for per-agent isolation (V2). */
+    owner?: string;
+    /** IDs of tasks that must complete before this one can start (V2). */
+    blockedBy?: number[];
+    /** IDs of tasks this one blocks from starting (V2). */
+    blocks?: number[];
+}
+export interface TodoListSummary {
+    total: number;
+    completed: number;
+    inProgress: number;
+    notStarted: number;
+    blocked: number;
+}
+export declare function summarizeTodoList(items: readonly TodoItem[]): TodoListSummary;

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * qlogicagent — Public API surface.
+ *
+ * Re-exports core types and constructors for programmatic embedding.
+ */
+export { Agent } from "./agent/agent.js";
+export type { AgentLogger, ChatMessage, ToolDefinition, ToolInvoker, TurnConfig, TurnEvent, TurnRequest, HookRegistry, } from "./agent/types.js";
+export { parseCliArgs } from "./config/config.js";
+export type { AgentConfig } from "./config/config.js";
+export type { Transport } from "./cli/transport.js";
+export { StdioTransport } from "./cli/transport.js";
+export { StdioServer, type StdioServerConfig } from "./cli/stdio-server.js";
+export { ProviderRegistry, createLLMClient, autoDetectProvider, } from "./llm/index.js";
+export type { LLMTransport, LLMRequest, LLMChunk } from "./llm/index.js";
+export { createHookRegistry } from "./runtime/hooks/hook-registry.js";
+export { buildSkillInstruction, } from "./orchestration/index.js";

package/dist/types/llm/builtin-providers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Builtin provider definitions — hardcoded fallback list (~30 providers).
+ *
+ * This is Layer 1 (lowest priority) of the three-layer merge strategy.
+ * Used when remote model catalog is unavailable.
+ *
+ * Aligned with Hermes hermes_cli/models.py hardcoded fallback.
+ */
+import type { ProviderDef } from "./provider-def.js";
+export declare const BUILTIN_PROVIDERS: ProviderDef[];

package/dist/types/llm/debug-transport.d.ts

@@ -0,0 +1,12 @@
+import type { LLMTransport } from "./transport.js";
+/**
+ * Check whether debug transport should be enabled.
+ */
+export declare function isDebugTransportEnabled(): boolean;
+/**
+ * Create a DebugTransport decorator that wraps a base LLMTransport,
+ * logging request metadata + timing + usage to JSONL.
+ *
+ * CC parity: createDumpPromptsFetch — but vendor-agnostic via transport abstraction.
+ */
+export declare function createDebugTransport(base: LLMTransport, sessionId: string): LLMTransport;

package/dist/types/llm/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LLM Provider layer — public API surface.
+ *
+ * Provides: ProviderDef + LLMTransport + ProviderRegistry + LLMClient factory
+ */
+export type { ProviderDef, ModelInfo, TransportType, AuthType } from "./provider-def.js";
+export type { LLMTransport, LLMRequest, LLMChunk, AccumulatedToolCall, } from "./transport.js";
+export { accumulateToolCalls } from "./transport.js";
+export { ProviderRegistry } from "./provider-registry.js";
+export { BUILTIN_PROVIDERS } from "./builtin-providers.js";
+export { ModelCatalog } from "./model-catalog.js";
+export type { LLMClientConfig, LLMClient } from "./llm-client.js";
+export { createLLMClient, autoDetectProvider } from "./llm-client.js";
+export { OpenAIChatTransport } from "./transports/openai-chat.js";
+export { AnthropicMessagesTransport } from "./transports/anthropic-messages.js";
+export { isDebugTransportEnabled, createDebugTransport } from "./debug-transport.js";

package/dist/types/llm/llm-client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * LLM Client factory — resolves ProviderDef → creates LLMTransport instance.
+ *
+ * Replaces the old createAdminInferProxyClient() call chain.
+ * User API key + ProviderDef → direct provider connection.
+ */
+import type { ProviderDef } from "./provider-def.js";
+import type { LLMTransport } from "./transport.js";
+import { ProviderRegistry } from "./provider-registry.js";
+export interface LLMClientConfig {
+    /** Provider id, e.g. "deepseek" */
+    provider: string;
+    /** Model id, e.g. "deepseek-chat" */
+    model: string;
+    /** User API key */
+    apiKey: string;
+    /** Optional base URL override */
+    baseUrl?: string;
+}
+export interface LLMClient {
+    transport: LLMTransport;
+    apiKey: string;
+    resolvedModel: string;
+    providerDef: ProviderDef;
+}
+/**
+ * Create an LLM client from config + registry.
+ *
+ * 1. Look up provider in registry
+ * 2. Apply baseUrl override if provided
+ * 3. Instantiate the correct transport
+ */
+export declare function createLLMClient(config: LLMClientConfig, registry: ProviderRegistry): LLMClient;
+/**
+ * Auto-detect provider from API key environment variables.
+ * Scans registry for providers whose env vars are set.
+ * Returns the first match.
+ */
+export declare function autoDetectProvider(registry: ProviderRegistry): {
+    providerId: string;
+    apiKey: string;
+    defaultModel: string;
+} | undefined;

package/dist/types/llm/model-catalog.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ModelCatalog — remote model directory with disk cache + fallback.
+ *
+ * Fetches model metadata from models.dev (open community catalog, 4000+ models).
+ * Aligned with Hermes agent/models_dev.py caching strategy.
+ *
+ * Three-layer fallback:
+ *   1. In-memory cache (process-level, TTL check against disk mtime)
+ *   2. Disk cache (~/.qlogicagent/cache/model_catalog.json)
+ *   3. Remote fetch (https://models.dev/api.json)
+ *   4. Stale disk cache (if remote fails)
+ *   5. Empty (caller falls back to builtin-providers.ts hardcoded)
+ *
+ * Non-blocking: first startup without cache returns empty immediately,
+ * triggers background async fetch. Agent uses builtin providers until
+ * catalog arrives.
+ */
+import type { ModelInfo } from "./provider-def.js";
+export declare class ModelCatalog {
+    private cache;
+    private cacheDir;
+    private cacheFile;
+    private ttlMs;
+    private fetching;
+    private lastFetchAttempt;
+    constructor(opts?: {
+        cacheDir?: string;
+        ttlMs?: number;
+    });
+    /**
+     * Get models for a provider. Non-blocking: returns whatever is cached.
+     * Triggers background refresh if stale.
+     */
+    getModels(providerId: string): ModelInfo[];
+    /**
+     * Get a single model by provider + model id.
+     */
+    getModel(providerId: string, modelId: string): ModelInfo | undefined;
+    /**
+     * List all known provider ids from the catalog.
+     */
+    listProviderIds(): string[];
+    /**
+     * Force refresh from remote. Returns true if successful.
+     */
+    refreshCatalog(): Promise<boolean>;
+    private ensureLoaded;
+    private isStale;
+    private loadFromDisk;
+    private saveToDisk;
+    private backgroundFetch;
+    private fetchRemote;
+}

package/dist/types/llm/provider-def.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ProviderDef — defines how to connect to an LLM provider.
+ *
+ * Aligned with Hermes `ProviderDef` dataclass pattern:
+ *   id + name + transport type + baseUrl + auth config + model list
+ *
+ * Three-layer merge strategy (Layer 3 > Layer 2 > Layer 1):
+ *   Layer 1: builtin-providers.ts hardcoded (fallback)
+ *   Layer 2: model-catalog.ts remote (models.dev)
+ *   Layer 3: user config (from agent.turn.config)
+ */
+export type TransportType = "openai-chat" | "anthropic-messages";
+export type AuthType = "bearer" | "x-api-key" | "none";
+export interface ProviderDef {
+    /** Unique provider id, e.g. "deepseek", "openai", "anthropic" */
+    id: string;
+    /** Display name, e.g. "DeepSeek" */
+    name: string;
+    /** Which transport to use for LLM calls */
+    transport: TransportType;
+    /** API base URL, e.g. "https://api.deepseek.com" */
+    baseUrl: string;
+    /** Env var names for API key (priority order) */
+    apiKeyEnvVars: string[];
+    /** Auth header style */
+    authType: AuthType;
+    /** Is an aggregator (OpenRouter, 硅基) — model ids may have prefix */
+    isAggregator: boolean;
+    /** Recommended default model */
+    defaultModel?: string;
+    /** Known models for this provider */
+    models?: ModelInfo[];
+    /** Extra headers to send with every request (e.g. aggregator-specific) */
+    extraHeaders?: Record<string, string>;
+    /** Whether this provider supports stream_options (default true for openai-chat) */
+    supportsStreamOptions?: boolean;
+    /** Whether to omit temperature when it equals 0 (some providers reject 0) */
+    omitZeroTemperature?: boolean;
+}
+export interface ModelInfo {
+    /** Model id, e.g. "deepseek-chat" */
+    id: string;
+    /** Display name, e.g. "DeepSeek Chat V3" */
+    name: string;
+    /** Context window in tokens */
+    contextWindow: number;
+    /** Max output tokens */
+    maxOutput: number;
+    /** Supports function/tool calling */
+    toolCall: boolean;
+    /** Has reasoning/thinking mode */
+    reasoning: boolean;
+    /** Supports vision (image input) */
+    vision: boolean;
+    /** Cost per 1M input tokens (USD) */
+    costInput?: number;
+    /** Cost per 1M output tokens (USD) */
+    costOutput?: number;
+}