qlogicagent 0.5.2 → 0.5.3

package/dist/types/contracts/skill-candidate.d.ts

@@ -0,0 +1,63 @@
+export declare const SKILL_CANDIDATE_STATUS_VALUES: readonly ["draft", "in_review", "approved", "rejected", "canary", "published", "stale", "superseded", "rolled_back"];
+export declare const SKILL_CANDIDATE_ACTION_VALUES: readonly ["submit-review", "approve", "reject", "start-canary", "record-effectiveness", "promote", "publish", "mark-stale", "mark-superseded", "rollback"];
+export declare const SKILL_CANDIDATE_EFFECTIVENESS_PHASE_VALUES: readonly ["canary", "published"];
+export type SkillCandidateStatus = (typeof SKILL_CANDIDATE_STATUS_VALUES)[number];
+export type SkillCandidateAction = (typeof SKILL_CANDIDATE_ACTION_VALUES)[number];
+export type SkillCandidateEffectivenessPhase = (typeof SKILL_CANDIDATE_EFFECTIVENESS_PHASE_VALUES)[number];
+export type SkillCandidateArtifactContract = {
+    uri: string;
+    sha256?: string;
+    workspaceDir?: string;
+    relativePath?: string;
+    sourceWorkspaceDir?: string;
+    stagedAt?: string;
+};
+export type SkillCandidateSourceExecutionContract = {
+    executionId?: string;
+    rootExecutionId?: string;
+    parentExecutionId?: string;
+    sidechainId?: string;
+    attemptId?: string;
+    outcomeId?: string;
+    sessionId?: string;
+    turnId?: string;
+};
+export type SkillCandidateReviewContract = {
+    action: SkillCandidateAction;
+    actor?: string | null;
+    notes?: string | null;
+    payload?: Record<string, unknown>;
+    createdAt?: string;
+};
+export type SkillCandidateEffectivenessContract = {
+    phase: SkillCandidateEffectivenessPhase;
+    sampleCount: number;
+    successCount: number;
+    failureCount: number;
+    regressionCount: number;
+    successRate: number;
+    regressionRate: number;
+    avgLatencyMs?: number;
+    avgCostUsd?: number;
+    score?: number;
+    staleReason?: string | null;
+    notes?: string | null;
+    summary?: Record<string, unknown>;
+    lastObservedAt?: string;
+    updatedAt?: string;
+    /** ISO-8601 timestamp of last skill invocation/view/patch activity. */
+    lastActivityAt?: string;
+    /** Cumulative activity count (use + view + patch). */
+    activityCount?: number;
+};
+export declare function coerceSkillCandidateJsonObject(value: unknown): Record<string, unknown>;
+export declare function isSkillCandidateStatus(value: unknown): value is SkillCandidateStatus;
+export declare function isSkillCandidateAction(value: unknown): value is SkillCandidateAction;
+export declare function isSkillCandidateEffectivenessPhase(value: unknown): value is SkillCandidateEffectivenessPhase;
+export declare function normalizeSkillCandidateStatus(value: unknown, fallback?: SkillCandidateStatus): SkillCandidateStatus;
+export declare function normalizeSkillCandidateAction(value: unknown): SkillCandidateAction | null;
+export declare function normalizeSkillCandidateEffectivenessPhase(value: unknown): SkillCandidateEffectivenessPhase | null;
+export declare function normalizeSkillCandidateArtifact(value: unknown): SkillCandidateArtifactContract | null;
+export declare function normalizeSkillCandidateSourceExecution(value: unknown): SkillCandidateSourceExecutionContract | null;
+export declare function normalizeSkillCandidateReview(value: unknown): SkillCandidateReviewContract | null;
+export declare function normalizeSkillCandidateEffectiveness(value: unknown): SkillCandidateEffectivenessContract | null;

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

@@ -0,0 +1,14 @@
+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;
+}
+export interface TodoListSummary {
+    total: number;
+    completed: number;
+    inProgress: number;
+    notStarted: number;
+}
+export declare function summarizeTodoList(items: readonly TodoItem[]): TodoListSummary;

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { 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 (~/.openclaw/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;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * ProviderRegistry — three-layer merge registry for LLM providers.
+ *
+ * Layer 1: builtin-providers.ts hardcoded (lowest priority, ~20 providers)
+ * Layer 2: model-catalog.ts remote (models.dev — enriches model metadata)
+ * Layer 3: user config override (from agent.turn.config — highest priority)
+ *
+ * Merge strategy: Layer 3 > Layer 2 > Layer 1 (later layers override same-id fields)
+ *
+ * Aligned with Hermes provider_registry.py.
+ */
+import type { ModelInfo, ProviderDef } from "./provider-def.js";
+import { ModelCatalog } from "./model-catalog.js";
+export declare class ProviderRegistry {
+    /** Layer 1: builtin hardcoded providers */
+    private builtins;
+    /** Layer 2: remote model catalog (models.dev) */
+    private catalog;
+    /** Layer 3: user overrides (from agent.turn.config) */
+    private overrides;
+    constructor(opts?: {
+        catalog?: ModelCatalog;
+    });
+    /**
+     * Apply user config override for a provider.
+     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
+     */
+    applyOverride(providerId: string, override: Partial<ProviderDef>): void;
+    /**
+     * Get merged ProviderDef by id (Layer 3 > Layer 1).
+     * Returns undefined if provider not found.
+     * Supports common aliases (e.g., "claude" → "anthropic").
+     */
+    getProvider(id: string): ProviderDef | undefined;
+    /**
+     * List all known provider ids.
+     */
+    listProviders(): ProviderDef[];
+    /**
+     * List models for a specific provider.
+     * Merges: Layer 3 override > Layer 1 builtin > Layer 2 catalog enrichment.
+     */
+    listModels(providerId: string): ModelInfo[];
+    /**
+     * Trigger background refresh of the remote model catalog.
+     */
+    refreshCatalog(): Promise<boolean>;
+    /**
+     * Resolve API key for a provider:
+     *   1. Explicit key (from agent.turn.config)
+     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
+     */
+    resolveApiKey(providerId: string, explicitKey?: string): string | undefined;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * LLMTransport — abstract interface for LLM inference calls.
+ *
+ * Aligned with Hermes `ProviderTransport` ABC:
+ *   stream(request, apiKey, signal) → AsyncGenerator<LLMChunk>
+ *
+ * Two concrete implementations:
+ *   - OpenAI Chat Completions (covers 95% of providers)
+ *   - Anthropic Messages API
+ */
+import type { ChatMessage, ToolDefinition } from "../agent/types.js";
+export interface LLMRequest {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    toolChoice?: "auto" | "none" | "required";
+    temperature?: number;
+    maxTokens?: number;
+    reasoning?: {
+        effort: "low" | "medium" | "high";
+    };
+}
+export type LLMChunk = {
+    type: "delta";
+    text: string;
+} | {
+    type: "tool_call_delta";
+    index: number;
+    id?: string;
+    name?: string;
+    arguments: string;
+} | {
+    type: "reasoning_delta";
+    text: string;
+} | {
+    type: "usage";
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens?: number;
+} | {
+    type: "done";
+    finishReason: string;
+};
+export interface AccumulatedToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface LLMTransport {
+    /**
+     * Stream an LLM inference request.
+     * apiKey is passed explicitly (from agent.turn.config, not env).
+     */
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+}
+/**
+ * Accumulate tool_call_delta chunks into complete ToolCall objects.
+ * Modeled after admin-infer-proxy-client's Map<index, toolCall> accumulator.
+ */
+export declare function accumulateToolCalls(accumulator: Map<number, AccumulatedToolCall>, chunk: LLMChunk & {
+    type: "tool_call_delta";
+}): void;

package/dist/types/llm/transports/anthropic-messages.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anthropic Messages Transport — SSE streaming for Claude API.
+ *
+ * POST {baseUrl}/v1/messages with stream: true
+ * Auth: x-api-key: {apiKey} + anthropic-version header
+ *
+ * SSE event types:
+ *   message_start, content_block_start, content_block_delta,
+ *   content_block_stop, message_delta, message_stop
+ *
+ * Tool use is via content blocks with type "tool_use" + "input_json_delta".
+ *
+ * Aligned with Hermes anthropic_messages.py transport.
+ */
+import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+export interface AnthropicTransportConfig {
+    baseUrl: string;
+    /** anthropic-version header (default "2023-06-01") */
+    apiVersion?: string;
+    /** Timeout in ms (default 180_000) */
+    timeoutMs?: number;
+}
+export declare class AnthropicMessagesTransport implements LLMTransport {
+    private baseUrl;
+    private apiVersion;
+    private timeoutMs;
+    constructor(config: AnthropicTransportConfig);
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    private parseSSEStream;
+    private mapEvent;
+}

package/dist/types/llm/transports/openai-chat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenAI Chat Completions Transport — SSE streaming implementation.
+ *
+ * Covers all OpenAI-compatible providers:
+ *   DeepSeek, Qwen, 硅基, Minimax, Moonshot, Groq, Together, OpenRouter, etc.
+ *
+ * POST {baseUrl}/v1/chat/completions with stream: true
+ * Auth: Authorization: Bearer {apiKey}
+ *
+ * SSE format: lines prefixed with "data: ", JSON parsing per event.
+ *
+ * Adapted from admin-infer-proxy-client.ts SSE logic + Hermes openai_chat.py transport.
+ */
+import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
+export interface OpenAIChatTransportConfig {
+    baseUrl: string;
+    /** Additional headers (e.g. for specific providers) */
+    extraHeaders?: Record<string, string>;
+    /** Timeout in ms (default 180_000) */
+    timeoutMs?: number;
+    /** Whether to include stream_options (default true). Set false for providers that reject it. */
+    supportsStreamOptions?: boolean;
+    /** Whether to omit temperature when it equals 0 (e.g. Moonshot rejects 0) */
+    omitZeroTemperature?: boolean;
+}
+export declare class OpenAIChatTransport implements LLMTransport {
+    private baseUrl;
+    private extraHeaders;
+    private timeoutMs;
+    private supportsStreamOptions;
+    private omitZeroTemperature;
+    constructor(config: OpenAIChatTransportConfig);
+    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+    private parseSSEStream;
+    private mapChunk;
+}

package/dist/types/orchestration/agent-registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Built-in Agent Registry — CC-aligned agent definitions for fork/subagent.
+ *
+ * Each built-in agent defines a role with constrained tools, system prompt,
+ * and execution budget. The LLM can invoke these via the AgentTool.
+ */
+import type { PermissionRole, IsolationMode } from "./task-types.js";
+export interface AgentDefinition {
+    /** Unique identifier for the agent (kebab-case). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** Short description (appears in tool_search / LLM prompt). */
+    description: string;
+    /** Maximum turns this agent can execute before forced stop. */
+    maxTurns: number;
+    /** Tool access mode. */
+    toolAccessMode: "full" | "read-only" | "none";
+    /** Explicit allowed tool names (if empty, uses toolAccessMode filter). */
+    allowedTools?: string[];
+    /** Whether this agent can fork sub-agents itself. */
+    canFork: boolean;
+    /** System prompt override for this agent. */
+    systemPromptSuffix?: string;
+    /** Permission role context (CC: interactive/coordinator/worker). Default: "worker". */
+    permissionRole?: PermissionRole;
+    /** Isolation mode (CC: shared/worktree/container). Default: "shared". */
+    isolation?: IsolationMode;
+}
+/**
+ * Get the full list of built-in agent definitions.
+ */
+export declare function getBuiltInAgents(): AgentDefinition[];
+/**
+ * Look up a built-in agent by name.
+ */
+export declare function getBuiltInAgent(name: string): AgentDefinition | undefined;
+/**
+ * Check if a given agent name is a built-in agent.
+ */
+export declare function isBuiltInAgent(name: string): boolean;
+/**
+ * Resolve tool access for an agent definition.
+ * Returns the set of tool names the agent is allowed to use.
+ */
+export declare function resolveAgentToolSet(agent: AgentDefinition, availableTools: string[]): string[];

package/dist/types/orchestration/context-collapse.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Context Collapse — staged lightweight context reduction that runs
+ * BEFORE autocompact and can drain on 413 BEFORE reactive compact.
+ *
+ * CC parity: services/contextCollapse/index.ts
+ *
+ * Architecture:
+ * 1. applyCollapsesIfNeeded() — runs every iteration, projects the
+ *    collapsed view and maybe commits more collapses (by summarizing
+ *    old tool-result groups into compact summaries).
+ * 2. recoverFromOverflow() — drain all staged collapses on a real
+ *    API 413. If it can free enough context, the retry may succeed
+ *    without reactive compact (which is heavier and destroys more
+ *    context).
+ *
+ * Collapses are ordered "stages" — oldest first. Each stage replaces
+ * a contiguous run of old messages with a single summary line.
+ */
+export interface CollapseStage {
+    /** UUID of the stage (for dedup and ordering). */
+    id: string;
+    /** Index range [start, end) in the original message array. */
+    range: [number, number];
+    /** Summary text that replaces the range. */
+    summary: string;
+    /** Whether this stage has been committed (applied to messages). */
+    committed: boolean;
+}
+export interface CollapseStore {
+    stages: CollapseStage[];
+}
+export declare function createCollapseStore(): CollapseStore;
+/**
+ * Evaluate whether new collapses should be staged.
+ *
+ * Heuristic: if the conversation has > thresholdMessages non-system messages,
+ * group old tool-result runs into collapse stages.
+ */
+export declare function applyCollapsesIfNeeded<T extends {
+    role: string;
+    content?: string | unknown;
+}>(messages: T[], store: CollapseStore, opts?: {
+    thresholdMessages?: number;
+}): {
+    messages: T[];
+    stagedCount: number;
+};
+/**
+ * Drain all staged (uncommitted) collapses — called on 413 recovery.
+ * Commits every pending stage and returns the collapsed messages.
+ */
+export declare function recoverFromOverflow<T extends {
+    role: string;
+    content?: string | unknown;
+}>(messages: T[], store: CollapseStore): {
+    messages: T[];
+    committed: number;
+};