qlogicagent 0.5.2 → 0.5.3

package/dist/types/agent/tool-loop.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Tool loop state machine — CC query.ts aligned.
+ *
+ * Architecture:
+ *   - Infinite while(true) loop with centralized State object (CC parity)
+ *   - 7 labeled continue sites matching CC's query loop transitions
+ *   - Error Withholding: 413 / max_output_tokens / media errors are
+ *     withheld from callers during recovery attempts
+ *   - Context Collapse drain: staged collapses committed on 413
+ *     BEFORE falling through to reactive compact
+ *   - Media error recovery: image/media errors → reactive compact retry
+ *   - Hermes delta suppression preserved
+ *   - StreamingToolExecutor preserved
+ *   - Sidechain depth/policy preserved
+ *   - Skill learning evaluation preserved
+ *
+ * CC reference: src/query.ts queryLoop()
+ *
+ * Zero imports from express/pg/ioredis/ws.
+ */
+import type { AgentLogger, ChatMessage, ToolDefinition, ToolInvoker, TurnEvent, HookRegistry } from "./types.js";
+import type { LLMTransport } from "../llm/transport.js";
+export interface ToolLoopParams {
+    turnId: string;
+    sessionId: string;
+    messages: ChatMessage[];
+    tools: ToolDefinition[];
+    model: string;
+    apiKey: string;
+    temperature?: number;
+    maxRounds?: number;
+    /** Context window size in tokens (for turn-loop-guard budget checks) */
+    contextWindowTokens?: number;
+    /** Max output tokens for current model */
+    maxOutputTokens?: number;
+    /** Model's absolute max output tokens (escalation ceiling) */
+    modelMaxOutputTokens?: number;
+    /** Tool choice strategy (default "auto") */
+    toolChoice?: "auto" | "none" | "required";
+    /** Parent sidechain depth (0 = top-level) */
+    parentDepth?: number;
+    /** Sidechain type for tool access policy (default "code-repair" = full access) */
+    sidechainType?: import("../orchestration/index.js").SidechainType;
+    /** Tool eligibility context for policy-based filtering */
+    toolEligibilityContext?: import("../runtime/execution/tool-eligibility.js").ToolEligibilityContext;
+    /** Hook registry for lifecycle events (optional, fire-and-forget) */
+    hooks?: HookRegistry;
+    /** Max turns (loop iterations). 0 = use maxRounds. */
+    maxTurns?: number;
+    /** Fallback model to switch to after repeated 529 errors (CC parity). */
+    fallbackModel?: string;
+    /** Query source for foreground/background retry distinction (CC parity). */
+    querySource?: string;
+    /** Token budget for this turn (>0 enables budget continuation). */
+    tokenBudget?: number;
+    /**
+     * Refresh tools callback — called between turns (CC refreshTools parity).
+     * Returns updated tool definitions if tools have changed (e.g. MCP reconnect),
+     * or the same array reference if unchanged.
+     */
+    refreshTools?: () => ToolDefinition[];
+    /**
+     * Generate a human-readable summary label for a tool batch (CC generateToolUseSummary parity).
+     * Fire-and-forget: called after tool execution, result yielded as tool_use_summary event
+     * when the next LLM round starts streaming. ~30 chars, git-commit-subject style.
+     */
+    generateToolUseSummary?: (toolCalls: Array<{
+        name: string;
+        arguments: string;
+        result?: string;
+    }>) => Promise<string | null>;
+    /**
+     * Post-sampling hooks — fire-and-forget after LLM response completes (CC executePostSamplingHooks parity).
+     * Cannot modify messages. Used for background tasks (memory extraction, skill learning, etc.).
+     */
+    postSamplingHooks?: Array<(context: {
+        messages: unknown[];
+        model: string;
+        sessionId: string;
+    }) => Promise<void> | void>;
+    /** Max concurrent tool executions (0 = unlimited, CC parity: semantic concurrency control). */
+    maxConcurrentTools?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Execute the tool loop — CC query.ts queryLoop() aligned.
+ *
+ * Yields TurnEvent stream. The caller (Agent class) wraps this with
+ * start/end lifecycle and error handling.
+ *
+ * Architecture: infinite while(true) with centralized State + 7 continue
+ * labels. Error withholding gates recoverable errors through collapse
+ * drain → reactive compact → escalation → recovery message pipeline
+ * before surfacing to callers.
+ */
+export declare function executeToolLoop(params: ToolLoopParams, transport: LLMTransport, toolInvoker: ToolInvoker, log: AgentLogger): AsyncGenerator<TurnEvent>;

package/dist/types/agent/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Pure agent types — zero I/O framework dependencies.
+ *
+ * These types define the contract between:
+ *   - CLI stdio layer ↔ Agent class
+ *   - Agent class ↔ LLM Provider
+ *   - Agent class ↔ Tool loop
+ *
+ * Ported from Hub semantic-turn-shared.ts / semantic-turn-tools.ts,
+ * with Hub infrastructure (WS/PG/Redis) replaced by DI interfaces.
+ *
+ * No imports from express/pg/ioredis/ws.
+ */
+import type { SkillInstruction } from "../orchestration/index.js";
+import type { HookRegistry } from "../contracts/hooks.js";
+export type ChatMessageRole = "system" | "user" | "assistant" | "tool";
+export interface ChatMessage {
+    role: ChatMessageRole;
+    content: string | null;
+    /** For assistant messages with tool calls */
+    tool_calls?: ToolCallMessage[];
+    /** For tool result messages */
+    tool_call_id?: string;
+    /** For tool result messages — tool name */
+    name?: string;
+}
+export interface ToolCallMessage {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+    };
+    /** Tool scheduling metadata from host manifest (optional) */
+    meta?: {
+        serialOnly?: boolean;
+        parallelSafe?: boolean;
+        /** If true, host should request user approval before execution (CC PreToolUse parity) */
+        requiresApproval?: boolean;
+        /** Tool is read-only / safe — skip approval even in strict mode */
+        isReadOnly?: boolean;
+        /** Tool can cause irreversible side-effects — force approval in default mode */
+        isDangerous?: boolean;
+    };
+    /**
+     * Backfill derived/legacy fields onto a shallow copy of the tool input
+     * before hooks and observers see it (CC backfillObservableInput parity).
+     * The original API-bound input is never modified.
+     */
+    backfillObservableInput?: (input: Record<string, unknown>) => void;
+}
+export interface TokenUsage {
+    prompt: number;
+    completion: number;
+    /** Reasoning tokens (for models like o1/DeepSeek-R1) */
+    reasoning?: number;
+    /** Prompt cache read tokens (CC cache_read_input_tokens parity) */
+    cacheRead?: number;
+    /** Prompt cache creation tokens (CC cache_creation_input_tokens parity) */
+    cacheCreation?: number;
+}
+/**
+ * Why the previous iteration continued — each variant corresponds to one of
+ * the 7 `continue` sites in the main while(true) loop.
+ * Tests can assert recovery paths fired without inspecting message contents.
+ */
+export type ToolLoopTransition = {
+    reason: "collapse_drain_retry";
+    committed: number;
+} | {
+    reason: "reactive_compact_retry";
+} | {
+    reason: "max_output_tokens_escalate";
+} | {
+    reason: "max_output_tokens_recovery";
+    attempt: number;
+} | {
+    reason: "stop_hook_blocking";
+} | {
+    reason: "token_budget_continuation";
+} | {
+    reason: "next_turn";
+};
+/** Terminal exit reasons from the tool loop. */
+export type ToolLoopTerminal = {
+    reason: "completed";
+} | {
+    reason: "aborted";
+} | {
+    reason: "prompt_too_long";
+} | {
+    reason: "image_error";
+} | {
+    reason: "model_error";
+    error?: unknown;
+} | {
+    reason: "max_turns";
+} | {
+    reason: "budget_exhausted";
+} | {
+    reason: "tool_loop_limit";
+} | {
+    reason: "stop_hook_prevented";
+} | {
+    reason: "hook_stopped";
+};
+export interface TurnRequest {
+    turnId: string;
+    sessionId: string;
+    messages: ChatMessage[];
+    tools: ToolDefinition[];
+    systemPrompt?: string;
+    config?: TurnConfig;
+}
+export interface TurnConfig {
+    /** LLM 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;
+    /** Max tool-call rounds per turn (default 25, max 100) */
+    maxRounds?: number;
+    /** Temperature override */
+    temperature?: number;
+    /** Context window size in tokens (for turn-loop-guard budget checks) */
+    contextWindowTokens?: number;
+    /** Max output tokens for current model */
+    maxOutputTokens?: number;
+    /** Model's absolute max output tokens (for escalation ceiling) */
+    modelMaxOutputTokens?: number;
+    /** Tool choice strategy: "auto" (default), "none", "required" */
+    toolChoice?: "auto" | "none" | "required";
+    /** Parent sidechain depth (0 = top-level, default 0) */
+    parentDepth?: number;
+    /** Sidechain type for tool access policy (default "code-repair" = full access) */
+    sidechainType?: import("../orchestration/index.js").SidechainType;
+    /** Per-turn token budget (prompt + completion). 0 or undefined = unlimited. */
+    tokenBudget?: number;
+    /** Fallback model to switch to after repeated 529 errors (CC parity). */
+    fallbackModel?: string;
+    /** Max turns (tool loop iterations). 0 or undefined = use maxRounds. */
+    maxTurns?: number;
+    /** Model for generating tool use summaries (CC parity: Haiku). If set, enables summary generation. */
+    summaryModel?: string;
+    /** Max concurrent tool executions (0 = unlimited). */
+    maxConcurrentTools?: number;
+}
+export type TurnEvent = {
+    type: "start";
+    turnId: string;
+} | {
+    type: "delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "tool_call";
+    turnId: string;
+    callId: string;
+    name: string;
+    arguments: string;
+} | {
+    type: "end";
+    turnId: string;
+    content: string;
+    usage?: TokenUsage;
+    model?: string;
+    provider?: string;
+} | {
+    type: "error";
+    turnId: string;
+    error: string;
+    code?: string;
+} | {
+    type: "skill_instruction";
+    turnId: string;
+    instruction: SkillInstruction;
+} | {
+    type: "tool_result";
+    turnId: string;
+    callId: string;
+    name: string;
+    ok: boolean;
+    error?: string;
+} | {
+    type: "sidechain_started";
+    turnId: string;
+    depth: number;
+    role: "orchestrator" | "leaf";
+} | {
+    type: "sidechain_completed";
+    turnId: string;
+    depth: number;
+    toolCallCount: number;
+} | {
+    type: "tool_blocked";
+    turnId: string;
+    callId: string;
+    name: string;
+    reason: string;
+} | {
+    type: "recovery";
+    turnId: string;
+    action: string;
+    detail?: string;
+} | {
+    type: "plan_update";
+    turnId: string;
+    slug: string;
+    content: string;
+} | {
+    type: "heartbeat";
+    turnId: string;
+    message: string;
+} | {
+    type: "tool_use_summary";
+    turnId: string;
+    summary: string;
+};
+/**
+ * ToolInvoker: request tool execution from the host process (Gateway).
+ * In CLI mode this sends a JSON-RPC notification over stdio and waits for result.
+ */
+export interface ToolInvoker {
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal): Promise<{
+        result: string;
+        error?: string;
+    }>;
+}
+/**
+ * AgentLogger: structured logging interface.
+ * In CLI mode this writes to stderr; in Hub mode this uses pino.
+ */
+export interface AgentLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+export type { HookRegistry };

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * qlogicagent CLI — Agent subprocess entry point.
+ *
+ * Communicates with openclaw Gateway via JSON-RPC over stdio.
+ * All log/debug output goes to stderr (never pollutes the stdio protocol).
+ *
+ * Usage:
+ *   qlogicagent [--verbose]
+ */
+export {};

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

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+export interface StdioServerConfig {
+    verbose: boolean;
+}
+export declare class StdioServer {
+    private running;
+    private activeTurn;
+    private verbose;
+    private registry;
+    private toolRegistry;
+    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;
+    private handleHello;
+    private handlePing;
+    private handleAbort;
+    private handleApprovalResponse;
+    private handleSessionList;
+    private handleSessionResume;
+    private handleTurn;
+    private handleDream;
+    private resolveAgent;
+    private sendResponse;
+    private sendNotification;
+    private writeStdout;
+    private log;
+}

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

@@ -0,0 +1,21 @@
+import { ToolRegistry } from "../skills/tool-registry.js";
+import { type ExecProgress } from "../skills/tools/exec-tool.js";
+import type { AgentLogger } from "../agent/types.js";
+export interface BootstrapConfig {
+    workdir?: string;
+    log?: AgentLogger;
+    /** Called during foreground shell execution with incremental progress. */
+    onExecProgress?(progress: ExecProgress): void;
+}
+/**
+ * Create and populate a ToolRegistry with all locally-executable tools.
+ *
+ * Tools registered here execute IN-PROCESS (zero IPC).
+ * All tools are agent-local — no Gateway relay.
+ */
+export declare function bootstrapToolRegistry(config?: BootstrapConfig): ToolRegistry;
+/**
+ * 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/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,10 @@
+/**
+ * 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/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;
+    }>;
+}