qlogicagent 0.2.1 → 0.4.0

package/dist/cli/stdio-server.js

@@ -1,463 +0,0 @@
-/**
- * StdioServer — JSON-RPC 2.0 over stdio protocol handler.
- *
- * Reads line-delimited JSON from stdin, dispatches to handlers,
- * writes JSON-RPC responses/notifications to stdout.
- * All log output goes to stderr.
- *
- * Protocol: each line on stdin/stdout is a single JSON-RPC 2.0 message.
- */
-import { createInterface } from "node:readline";
-import { randomUUID } from "node:crypto";
-import { Agent } from "../agent/agent.js";
-import { ProviderRegistry, createLLMClient, autoDetectProvider, } from "../llm/index.js";
-import { createHookRegistry } from "../runtime/hook-registry.js";
-import { registerMemoryHooks } from "../runtime/memory-hooks.js";
-import { createQMemoryAdapter } from "../skills/qmemory-adapter.js";
-import { AGENT_RPC_ERROR_CODES, AGENT_RPC_PROTOCOL_VERSION, isAgentRpcRequest, } from "qlogicagent-runtime-contracts";
-export class StdioServer {
-    running = false;
-    activeTurn = null;
-    pendingToolResults = new Map();
-    verbose;
-    registry;
-    agent = null;
-    lastLlmConfigKey = "";
-    currentSessionId = "";
-    currentHooks = null;
-    constructor(config) {
-        this.verbose = config.verbose;
-        this.registry = new ProviderRegistry();
-    }
-    start() {
-        this.running = true;
-        this.log("qlogicagent CLI started, waiting for JSON-RPC on stdin...");
-        const rl = createInterface({
-            input: process.stdin,
-            crlfDelay: Number.POSITIVE_INFINITY,
-        });
-        rl.on("line", (line) => {
-            const trimmed = line.trim();
-            if (!trimmed)
-                return;
-            try {
-                const parsed = JSON.parse(trimmed);
-                if (!isAgentRpcRequest(parsed)) {
-                    this.log(`[warn] ignoring non-request message: ${trimmed.slice(0, 200)}`);
-                    return;
-                }
-                this.handleMessage(parsed);
-            }
-            catch {
-                this.log(`[warn] invalid JSON on stdin: ${trimmed.slice(0, 200)}`);
-            }
-        });
-        rl.on("close", () => {
-            this.log("stdin closed, shutting down");
-            this.stop();
-        });
-    }
-    stop() {
-        if (!this.running)
-            return;
-        this.running = false;
-        // Fire session.ended for active session
-        if (this.currentSessionId && this.currentHooks) {
-            this.currentHooks.invoke("session.ended", { sessionId: this.currentSessionId }).catch(() => { });
-        }
-        // Abort active turn if any
-        if (this.activeTurn) {
-            this.activeTurn.abort();
-            this.activeTurn = null;
-        }
-        // Reject all pending tool results
-        for (const [callId, pending] of this.pendingToolResults) {
-            pending.resolve({ result: "", error: "Agent process shutting down" });
-        }
-        this.pendingToolResults.clear();
-        this.log("stopped");
-    }
-    // ── Message dispatch ──────────────────────────────────────────────────
-    handleMessage(msg) {
-        switch (msg.method) {
-            case "agent.hello":
-                this.handleHello(msg);
-                break;
-            case "agent.ping":
-                this.handlePing(msg);
-                break;
-            case "agent.turn":
-                this.handleTurn(msg);
-                break;
-            case "memory.dream":
-                // Dream turns use the same agent.turn pipeline with dream-specific
-                // system prompt and messages. The Gateway sends memory.dream but the
-                // agent treats it as a regular turn with dream context.
-                this.handleTurn(msg);
-                break;
-            case "agent.abort":
-                this.handleAbort(msg);
-                break;
-            case "tool.result":
-                this.handleToolResult(msg);
-                break;
-            default:
-                if (msg.id !== undefined) {
-                    this.sendResponse(msg.id, undefined, {
-                        code: AGENT_RPC_ERROR_CODES.METHOD_NOT_FOUND,
-                        message: `Unknown method: ${msg.method}`,
-                    });
-                }
-        }
-    }
-    // ── Handlers ──────────────────────────────────────────────────────────
-    handleHello(msg) {
-        const params = msg.params;
-        const hostVersion = params?.protocolVersion ?? "unknown";
-        const majorHost = hostVersion.split(".")[0];
-        const majorSelf = AGENT_RPC_PROTOCOL_VERSION.split(".")[0];
-        if (majorHost !== majorSelf) {
-            this.log(`protocol mismatch: host=${hostVersion} agent=${AGENT_RPC_PROTOCOL_VERSION}`);
-            if (msg.id !== undefined) {
-                this.sendResponse(msg.id, undefined, {
-                    code: AGENT_RPC_ERROR_CODES.PROTOCOL_MISMATCH,
-                    message: `Protocol version mismatch: host=${hostVersion}, agent=${AGENT_RPC_PROTOCOL_VERSION}`,
-                });
-            }
-            return;
-        }
-        this.log(`hello from ${params?.hostName ?? "unknown"} v${params?.hostVersion ?? "?"} (protocol ${hostVersion})`);
-        if (msg.id !== undefined) {
-            this.sendResponse(msg.id, {
-                protocolVersion: AGENT_RPC_PROTOCOL_VERSION,
-                agentName: "qlogicagent",
-                agentVersion: "0.1.0",
-                capabilities: ["turn", "tool-invoke", "streaming"],
-            });
-        }
-    }
-    handlePing(msg) {
-        if (msg.id !== undefined) {
-            this.sendResponse(msg.id, { status: "ok" });
-        }
-        this.sendNotification("pong", {});
-    }
-    handleAbort(msg) {
-        const turnId = msg.params?.turnId ?? "";
-        this.log(`abort requested for turn ${turnId}`);
-        if (this.activeTurn) {
-            this.activeTurn.abort();
-            this.activeTurn = null;
-        }
-        if (msg.id !== undefined) {
-            this.sendResponse(msg.id, { aborted: true });
-        }
-    }
-    handleToolResult(msg) {
-        const callId = msg.params?.callId;
-        const result = msg.params?.result ?? "";
-        const error = msg.params?.error;
-        if (!callId) {
-            this.log("[warn] tool.result missing callId");
-            return;
-        }
-        const pending = this.pendingToolResults.get(callId);
-        if (pending) {
-            pending.resolve({ result, error });
-            this.pendingToolResults.delete(callId);
-        }
-        else {
-            this.log(`[warn] no pending tool call for callId ${callId}`);
-        }
-    }
-    async handleTurn(msg) {
-        const params = msg.params ?? {};
-        const turnId = params.turnId ?? randomUUID();
-        const sessionId = params.sessionId;
-        const messages = params.messages ?? [];
-        const tools = params.tools ?? [];
-        const config = params.config;
-        if (msg.id !== undefined) {
-            this.sendResponse(msg.id, { accepted: true, turnId });
-        }
-        // Session lifecycle: fire session.created when sessionId changes
-        if (sessionId && sessionId !== this.currentSessionId) {
-            if (this.currentSessionId && this.currentHooks) {
-                this.currentHooks.invoke("session.ended", { sessionId: this.currentSessionId }).catch(() => { });
-            }
-            this.currentSessionId = sessionId;
-            // session.created is fired after hooks are available (below in resolveAgent)
-        }
-        const ac = new AbortController();
-        this.activeTurn = ac;
-        this.log(`turn ${turnId} starting (session: ${sessionId})`);
-        try {
-            // ─── Resolve or create Agent with LLM config ──────────────
-            const turnConfig = {
-                provider: config?.provider,
-                model: config?.model,
-                apiKey: config?.apiKey,
-                baseUrl: config?.baseUrl,
-                maxRounds: config?.maxRounds,
-                temperature: config?.temperature,
-                contextWindowTokens: config?.contextWindowTokens,
-                maxOutputTokens: config?.maxOutputTokens,
-                modelMaxOutputTokens: config?.modelMaxOutputTokens,
-            };
-            const agent = this.resolveAgent(turnConfig);
-            if (!agent) {
-                this.sendNotification("turn.start", { turnId });
-                this.sendNotification("turn.error", {
-                    turnId,
-                    error: "No LLM provider configured. Provide provider/model/apiKey in agent.turn config, " +
-                        "or set DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY environment variable.",
-                    code: "NO_PROVIDER",
-                });
-                return;
-            }
-            // ─── Stream events from Agent ─────────────────────────────
-            const systemPrompt = config?.systemPrompt;
-            for await (const event of agent.run({
-                turnId,
-                sessionId,
-                messages,
-                tools,
-                systemPrompt,
-                config: turnConfig,
-            }, ac.signal)) {
-                // Forward all TurnEvent as JSON-RPC notifications
-                switch (event.type) {
-                    case "start":
-                        this.sendNotification("turn.start", { turnId: event.turnId });
-                        break;
-                    case "delta":
-                        this.sendNotification("turn.delta", {
-                            turnId: event.turnId,
-                            text: event.text,
-                        });
-                        break;
-                    case "end":
-                        this.sendNotification("turn.end", {
-                            turnId: event.turnId,
-                            content: event.content,
-                            usage: event.usage,
-                            model: event.model,
-                            provider: event.provider,
-                        });
-                        break;
-                    case "error":
-                        this.sendNotification("turn.error", {
-                            turnId: event.turnId,
-                            error: event.error,
-                            code: event.code,
-                        });
-                        break;
-                    case "skill_instruction":
-                        this.sendNotification("turn.skill_instruction", {
-                            turnId: event.turnId,
-                            instruction: event.instruction,
-                        });
-                        break;
-                    case "tool_call":
-                        // Informational only — actual execution RPC is handled
-                        // by requestToolExecution() when toolInvoker.invoke() is called.
-                        break;
-                    case "tool_result":
-                        this.sendNotification("turn.tool_result", {
-                            turnId: event.turnId,
-                            callId: event.callId,
-                            name: event.name,
-                            ok: event.ok,
-                            ...(event.error ? { error: event.error } : {}),
-                        });
-                        break;
-                    case "sidechain_started":
-                        this.sendNotification("turn.sidechain_started", {
-                            turnId: event.turnId,
-                            depth: event.depth,
-                            role: event.role,
-                        });
-                        break;
-                    case "sidechain_completed":
-                        this.sendNotification("turn.sidechain_completed", {
-                            turnId: event.turnId,
-                            depth: event.depth,
-                            toolCallCount: event.toolCallCount,
-                        });
-                        break;
-                    case "tool_blocked":
-                        this.sendNotification("turn.tool_blocked", {
-                            turnId: event.turnId,
-                            callId: event.callId,
-                            name: event.name,
-                            reason: event.reason,
-                        });
-                        break;
-                    case "recovery":
-                        this.sendNotification("turn.recovery", {
-                            turnId: event.turnId,
-                            action: event.action,
-                            ...(event.detail ? { detail: event.detail } : {}),
-                        });
-                        break;
-                    case "plan_update":
-                        this.sendNotification("turn.plan_update", {
-                            turnId: event.turnId,
-                            slug: event.slug,
-                            content: event.content,
-                        });
-                        break;
-                }
-            }
-            this.log(`turn ${turnId} completed`);
-        }
-        catch (err) {
-            if (ac.signal.aborted) {
-                this.sendNotification("turn.error", {
-                    turnId,
-                    error: "Turn aborted",
-                    code: "ABORTED",
-                });
-            }
-            else {
-                const message = err instanceof Error ? err.message : String(err);
-                this.sendNotification("turn.error", {
-                    turnId,
-                    error: message,
-                    code: "INTERNAL_ERROR",
-                });
-            }
-        }
-        finally {
-            if (this.activeTurn === ac) {
-                this.activeTurn = null;
-            }
-        }
-    }
-    // ── Agent resolution (lazy create / re-create on config change) ───────
-    resolveAgent(config) {
-        // Build a config key to detect provider/model/key changes
-        const configKey = `${config.provider ?? ""}:${config.model ?? ""}:${config.apiKey?.slice(0, 8) ?? ""}:${config.baseUrl ?? ""}`;
-        if (this.agent && this.lastLlmConfigKey === configKey) {
-            return this.agent;
-        }
-        // Try explicit config first
-        let provider = config.provider;
-        let model = config.model;
-        let apiKey = config.apiKey;
-        const baseUrl = config.baseUrl;
-        if (!provider || !apiKey) {
-            // Fallback: auto-detect from env
-            const detected = autoDetectProvider(this.registry);
-            if (detected) {
-                provider = provider ?? detected.providerId;
-                apiKey = apiKey ?? detected.apiKey;
-                model = model ?? detected.defaultModel;
-                this.log(`auto-detected provider: ${provider}, model: ${model}`);
-            }
-        }
-        if (!provider || !apiKey) {
-            return null;
-        }
-        model = model ?? this.registry.getProvider(provider)?.defaultModel ?? "";
-        const client = createLLMClient({ provider, model, apiKey, baseUrl }, this.registry);
-        const log = {
-            info: (m) => this.log(m),
-            warn: (m) => this.log(`[warn] ${m}`),
-            error: (m) => this.log(`[error] ${m}`),
-            debug: (m) => {
-                if (this.verbose)
-                    this.log(`[debug] ${m}`);
-            },
-        };
-        const toolInvoker = {
-            invoke: (turnId, name, args, signal) => this.requestToolExecution(turnId, name, args, signal),
-        };
-        // ─── HookRegistry ────────────────────────────────────────
-        // Skill learning: handled directly in tool-loop (has full metrics context).
-        // The tool-loop yields `skill_instruction` events → forwarded above in handleTurn().
-        // HookRegistry is available for context-compression and future hooks.
-        const hooks = createHookRegistry(log);
-        this.currentHooks = hooks;
-        // ─── Memory hooks (qmemory REST API) ─────────────────────
-        const qmemoryBaseUrl = (process.env.QMEMORY_BASE_URL ??
-            process.env.QLOGICAGENT_QMEMORY_BASE_URL ??
-            "").trim().replace(/\/+$/, "");
-        if (qmemoryBaseUrl) {
-            const memoryProvider = createQMemoryAdapter({
-                baseUrl: qmemoryBaseUrl,
-                apiKey: (process.env.QMEMORY_API_KEY ?? "").trim() || undefined,
-                timeoutMs: 5_000,
-            });
-            registerMemoryHooks(hooks, {
-                memoryProvider,
-                userId: this.currentSessionId ?? "default",
-                log: { debug: (m) => log.debug(m), warn: (m) => log.warn(m) },
-            });
-        }
-        // Fire session.created for the current session
-        if (this.currentSessionId) {
-            hooks.invoke("session.created", { sessionId: this.currentSessionId }).catch(() => { });
-        }
-        this.agent = new Agent({
-            llmTransport: client.transport,
-            apiKey: client.apiKey,
-            toolInvoker,
-            log,
-            hooks,
-            maxRounds: config.maxRounds,
-            verbose: this.verbose,
-        });
-        this.lastLlmConfigKey = configKey;
-        this.log(`created Agent (provider: ${provider}, model: ${model})`);
-        return this.agent;
-    }
-    // ── Tool call request (used by real Agent in Phase 2+) ────────────────
-    /**
-     * Request tool execution from the Gateway host.
-     * Sends a turn.tool_call notification and waits for tool.result.
-     */
-    async requestToolExecution(turnId, name, args, signal) {
-        const callId = `tc_${randomUUID().slice(0, 8)}`;
-        return new Promise((resolve, reject) => {
-            if (signal?.aborted) {
-                reject(new Error("Aborted"));
-                return;
-            }
-            this.pendingToolResults.set(callId, { resolve });
-            const onAbort = () => {
-                this.pendingToolResults.delete(callId);
-                reject(new Error("Aborted"));
-            };
-            signal?.addEventListener("abort", onAbort, { once: true });
-            this.sendNotification("turn.tool_call", {
-                turnId,
-                callId,
-                name,
-                arguments: args,
-            });
-        });
-    }
-    // ── Helpers ───────────────────────────────────────────────────────────
-    // ── I/O ───────────────────────────────────────────────────────────────
-    sendResponse(id, result, error) {
-        const msg = { jsonrpc: "2.0", id };
-        if (error)
-            msg.error = error;
-        else
-            msg.result = result;
-        this.writeStdout(msg);
-    }
-    sendNotification(method, params) {
-        const msg = { jsonrpc: "2.0", method, params };
-        this.writeStdout(msg);
-    }
-    writeStdout(msg) {
-        process.stdout.write(`${JSON.stringify(msg)}\n`);
-    }
-    log(message) {
-        if (this.verbose) {
-            process.stderr.write(`[qlogicagent] ${message}\n`);
-        }
-    }
-}

package/dist/config/config.d.ts

@@ -1,17 +0,0 @@
-/**
- * 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/config/config.js

@@ -1,21 +0,0 @@
-/**
- * Centralized CLI startup configuration.
- *
- * Parses and validates all configuration from CLI args and environment.
- * Single source of truth for qlogicagent runtime config.
- */
-/**
- * Parse CLI arguments into AgentConfig.
- *
- * Supports:
- *   --verbose / -v   Enable verbose logging
- */
-export function parseCliArgs(argv) {
-    const config = { verbose: false };
-    for (const arg of argv.slice(2)) {
-        if (arg === "--verbose" || arg === "-v") {
-            config.verbose = true;
-        }
-    }
-    return config;
-}

package/dist/contracts/hooks.d.ts

@@ -1,120 +0,0 @@
-/**
- * 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" | "context.before_compact" | "context.after_compact" | "memory.before_recall" | "memory.after_recall";
-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 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;
-    "context.before_compact": HookTurnContext & {
-        tokenCount?: number;
-        messageCount?: number;
-    };
-    "context.after_compact": HookTurnContext & {
-        tokenCount?: number;
-        removedCount?: number;
-    };
-    "memory.before_recall": HookTurnContext & {
-        query?: string;
-    };
-    "memory.after_recall": HookTurnContext & {
-        blockCount?: number;
-    };
-}
-/**
- * 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";
-    /** Modified context to pass downstream (only for "continue") */
-    context?: T;
-    /** Reason for abort/skip (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/contracts/hooks.js

@@ -1,7 +0,0 @@
-/**
- * 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.
- */
-export {};

package/dist/contracts/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * 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";
-export * from "./skill-candidate.js";

package/dist/contracts/index.js

@@ -1,10 +0,0 @@
-/**
- * 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";
-export * from "./skill-candidate.js";

package/dist/contracts/planner.d.ts

@@ -1,35 +0,0 @@
-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;
-    }>;
-}