qlogicagent 0.5.2 → 0.5.3

package/dist/types/runtime/infra/worktree-backend.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Worktree Backend — git command implementation for WorktreeToolDeps.
+ *
+ * CC reference: claude-code-haha/src/utils/worktree.ts
+ *
+ * Implements the host-provided git worktree backend:
+ *   - enterWorktree(): git worktree add -B <branch> <path> HEAD
+ *   - exitWorktree(): git worktree remove / keep
+ *   - listWorktrees(): git worktree list --porcelain
+ *   - isInWorktree(): check if cwd is inside a worktree
+ *   - currentWorktree(): get current worktree info
+ *
+ * State management:
+ *   - Tracks current worktree session in memory
+ *   - CWD switching via process.chdir()
+ *   - Safety checks: uncommitted changes, unpushed commits
+ *
+ * Security: validateWorktreeSlug() prevents path traversal.
+ */
+import type { WorktreeToolDeps } from "../../skills/tools/worktree-tool.js";
+interface WorktreeSession {
+    originalCwd: string;
+    worktreePath: string;
+    worktreeName: string;
+    worktreeBranch: string;
+    /** tmux session name (CC parity). */
+    tmuxSessionName?: string;
+    /** Whether worktree was created via a user hook (CC hookBased). */
+    hookBased?: boolean;
+    /** Creation duration in ms (unset on resume). */
+    creationDurationMs?: number;
+    /** True if sparse-checkout was applied. */
+    usedSparsePaths?: boolean;
+}
+/** Get the current worktree session (CC getCurrentWorktreeSession parity). */
+export declare function getCurrentWorktreeSession(): WorktreeSession | null;
+/** Restore session on resume (CC restoreWorktreeSession parity). */
+export declare function restoreWorktreeSession(session: WorktreeSession | null): void;
+/** Check whether tmux is available on the system. */
+export declare function isTmuxAvailable(): Promise<boolean>;
+/** Generate a tmux session name from repo path and branch (CC parity). */
+export declare function generateTmuxSessionName(repoPath: string, branch: string): string;
+/**
+ * Create a tmux session for a worktree (CC createTmuxSessionForWorktree parity).
+ * Returns the session name, or null if tmux is not available.
+ */
+export declare function createTmuxSession(worktreePath: string, sessionName: string): Promise<string | null>;
+/** Kill a tmux session (CC killTmuxSession parity). */
+export declare function killTmuxSession(sessionName: string): Promise<boolean>;
+/**
+ * Create a lightweight worktree for a sub-agent without modifying the
+ * global session. CC reference: createAgentWorktree().
+ */
+export declare function createAgentWorktree(gitRoot: string, slug: string, log?: {
+    info(msg: string): void;
+    warn(msg: string): void;
+}): Promise<{
+    worktreePath: string;
+    branch: string;
+} | null>;
+/** Remove an agent worktree (CC removeAgentWorktree parity). */
+export declare function removeAgentWorktree(gitRoot: string, worktreePath: string, branch: string, log?: {
+    info(msg: string): void;
+    warn(msg: string): void;
+}): Promise<boolean>;
+/**
+ * Clean up stale agent worktrees older than maxAgeDays (CC cleanupStaleAgentWorktrees parity).
+ */
+export declare function cleanupStaleAgentWorktrees(gitRoot: string, maxAgeDays?: number, log?: {
+    info(msg: string): void;
+    warn(msg: string): void;
+}): Promise<number>;
+export interface WorktreeBackendOptions {
+    /** Logger for worktree operations */
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+    /** Directories to symlink from main repo (CC parity: node_modules, etc.) */
+    symlinkDirs?: string[];
+    /** Sparse-checkout paths (CC settings.worktree.sparsePaths parity). */
+    sparsePaths?: string[];
+}
+export declare function createWorktreeBackend(opts: WorktreeBackendOptions): WorktreeToolDeps;
+export {};

package/dist/types/runtime/prompt/environment-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Environment Context — CC environment-aware system prompt parity.
+ *
+ * Injects OS, shell, CWD, and platform info into the system prompt
+ * so the agent can generate platform-appropriate commands.
+ *
+ * CC reference: ShellSnapshot.ts (shell type detection),
+ *               shellCompletion.ts (platform-aware command generation)
+ *
+ * This is a system prompt section that provides:
+ *   - OS name + version
+ *   - Shell type (bash/powershell/zsh)
+ *   - Current working directory
+ *   - Node.js version
+ *   - Available package managers
+ */
+import { type SystemPromptSection } from "./system-prompt-sections.js";
+export type ShellType = "bash" | "powershell" | "zsh" | "cmd" | "fish" | "unknown";
+/**
+ * Create a system prompt section that provides environment context.
+ * Memoized — computed once per session (environment doesn't change mid-session).
+ */
+export declare function createEnvironmentContextSection(): SystemPromptSection;

package/dist/types/runtime/prompt/index.d.ts

@@ -0,0 +1,3 @@
+export { assembleSystemPrompt, clearSystemPromptSections, systemPromptSection, type SystemPromptSection, } from "./system-prompt-sections.js";
+export { getInstructions, buildInstructionsPrompt, resetInstructionCache, } from "./instruction-loader.js";
+export { createEnvironmentContextSection } from "./environment-context.js";

package/dist/types/runtime/prompt/instruction-loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Instruction Loader — CC claudemd.ts parity (adapted for qlogicagent).
+ *
+ * Discovers and loads instruction files following CC's load order:
+ *   1. User instructions (~/.openclaw/INSTRUCTIONS.md)
+ *   2. Project instructions (INSTRUCTIONS.md, .openclaw/INSTRUCTIONS.md,
+ *      .openclaw/rules/*.md — walkup from cwd to git root)
+ *   3. Local instructions (INSTRUCTIONS.local.md — private, not checked in)
+ *
+ * Features ported from CC:
+ *   - Walkup discovery (cwd → root)
+ *   - @include directive support (text files only)
+ *   - Frontmatter globs for conditional rules
+ *   - HTML comment stripping
+ *   - Memoized loading with cache invalidation
+ *   - TEXT_FILE_EXTENSIONS whitelist
+ *   - MAX_INCLUDE_DEPTH circular reference prevention
+ *
+ * Reference: claude-code src/utils/claudemd.ts
+ */
+import type { HookRegistry } from "../../contracts/hooks.js";
+export type InstructionType = "User" | "Project" | "Local";
+export interface InstructionFileInfo {
+    path: string;
+    type: InstructionType;
+    content: string;
+    /** Path of the file that @included this one */
+    parent?: string;
+    /** Glob patterns from frontmatter — file only applies when target path matches */
+    globs?: string[];
+}
+/**
+ * Load all instruction files following CC's discovery order.
+ *
+ * Discovery order (priority: last loaded = highest):
+ *   1. User: ~/.openclaw/INSTRUCTIONS.md, ~/.openclaw/rules/*.md
+ *   2. Project: Walk from git root → cwd, each dir:
+ *      - INSTRUCTIONS.md
+ *      - .openclaw/INSTRUCTIONS.md
+ *      - .openclaw/rules/*.md (unconditional)
+ *   3. Local: INSTRUCTIONS.local.md (per dir, walkup)
+ *
+ * @param cwd - Starting directory for walkup discovery
+ * @param hooks - Optional hook registry for instructions.loaded event
+ */
+export declare function loadInstructions(cwd: string, hooks?: HookRegistry): Promise<InstructionFileInfo[]>;
+/**
+ * Build the instructions prompt string from loaded files.
+ * CC parity: getClaudeMds()
+ */
+export declare function buildInstructionsPrompt(files: InstructionFileInfo[]): string;
+/**
+ * Get conditional rules that match a target file path.
+ * CC parity: getManagedAndUserConditionalRules() + getMemoryFilesForNestedDirectory()
+ */
+export declare function getConditionalRules(cwd: string, targetPath: string): Promise<InstructionFileInfo[]>;
+/**
+ * Load instructions with memoization.
+ * CC parity: getMemoryFiles() with memoize.
+ * Returns cached result if cwd hasn't changed.
+ */
+export declare function getInstructions(cwd: string, hooks?: HookRegistry): Promise<InstructionFileInfo[]>;
+/** Clear the instruction cache. Called after file changes or compaction. */
+export declare function resetInstructionCache(): void;

package/dist/types/runtime/prompt/system-prompt-sections.d.ts

@@ -0,0 +1,63 @@
+/**
+ * System Prompt Sections — CC systemPromptSections.ts parity.
+ *
+ * Provides a section-based system prompt assembly mechanism:
+ *   - Memoized sections (computed once, cached until clear)
+ *   - Volatile sections (recompute every turn, cache-breaking)
+ *   - User-provided appendSystemPrompt / customSystemPrompt
+ *   - Clear on session reset / compact
+ *
+ * CC reference: src/constants/systemPromptSections.ts
+ */
+type ComputeFn = () => string | null | Promise<string | null>;
+export interface SystemPromptSection {
+    name: string;
+    compute: ComputeFn;
+    /** If true, recompute every turn (breaks prompt cache). CC: cacheBreak. */
+    cacheBreak: boolean;
+}
+/**
+ * Create a memoized system prompt section.
+ * Computed once, cached until clearSystemPromptSections() is called.
+ */
+export declare function systemPromptSection(name: string, compute: ComputeFn): SystemPromptSection;
+/**
+ * Create a volatile system prompt section that recomputes every turn.
+ * WARNING: This WILL break prompt cache when the value changes.
+ * Use sparingly — only for time-sensitive or frequently changing context.
+ *
+ * @param _reason - Why this section must be volatile (documentation only, CC parity).
+ */
+export declare function volatileSystemPromptSection(name: string, compute: ComputeFn, _reason?: string): SystemPromptSection;
+/**
+ * Resolve all system prompt sections, returning non-null prompt strings.
+ * Memoized sections are cached; volatile sections are always recomputed.
+ */
+export declare function resolveSystemPromptSections(sections: SystemPromptSection[]): Promise<string[]>;
+/**
+ * Clear all section caches. Called on session reset, /clear, or /compact.
+ */
+export declare function clearSystemPromptSections(): void;
+export interface SystemPromptAssemblyOptions {
+    /** Base system prompt (from Gateway config) */
+    basePrompt?: string;
+    /** Prepended instruction block (from INSTRUCTIONS.md files) */
+    instructionBlock?: string;
+    /** User-provided custom system prompt (replaces base) */
+    customSystemPrompt?: string;
+    /** User-provided append text (appended after all sections) */
+    appendSystemPrompt?: string;
+    /** Dynamic sections to resolve */
+    sections?: SystemPromptSection[];
+}
+/**
+ * Assemble the final system prompt from all sources.
+ *
+ * Order:
+ *   1. Instruction block (INSTRUCTIONS.md files)
+ *   2. Custom system prompt (replaces base) OR base prompt
+ *   3. Resolved sections
+ *   4. Append system prompt (user-provided suffix)
+ */
+export declare function assembleSystemPrompt(opts: SystemPromptAssemblyOptions): Promise<string>;
+export {};

package/dist/types/runtime/session/index.d.ts

@@ -0,0 +1,2 @@
+export { SessionState, type SessionCostSnapshot } from "./session-state.js";
+export { appendMessage, saveSessionState, loadSessionForResume, listSessions, deleteSession, pruneOldSessions, shouldGenerateTaskSummary, maybeGenerateTaskSummary, type SessionMetadata, type PersistedSession, type SessionListEntry, type TaskSummaryDeps, } from "./session-persistence.js";

package/dist/types/runtime/session/session-memory.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Session Memory — CC SessionMemory background extraction parity.
+ *
+ * Automatically extracts key insights from the conversation and saves
+ * them to session memory files. Runs as a forked sub-agent with restricted
+ * tool access after each turn when extraction thresholds are met.
+ *
+ * CC reference:
+ *   - src/services/SessionMemory/sessionMemory.ts
+ *   - src/services/SessionMemory/extractMemories.ts
+ *
+ * Extraction process:
+ *   1. Check thresholds (tokens + tool calls since last extraction)
+ *   2. Fork a sub-agent with restricted tools (read-only + memory write)
+ *   3. Sub-agent reviews conversation, extracts key facts/decisions
+ *   4. Sub-agent writes to session-memory.md file
+ *   5. Reset threshold counters
+ *
+ * Tool restrictions for extractor:
+ *   ✅ read, search, grep, glob (read-only fs)
+ *   ✅ memory_write (to session-memory path only)
+ *   ❌ Everything else (no file edits, no bash, no network)
+ */
+import type { ChatMessage, ToolDefinition, ToolInvoker, AgentLogger, HookRegistry } from "../../agent/types.js";
+import type { LLMTransport } from "../../llm/transport.js";
+import type { SessionState } from "./session-state.js";
+/** Tool permission check function (mirrors execution/forked-agent CanUseToolFn). */
+export type CanUseToolFn = (toolName: string, input: Record<string, unknown>) => {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Forked agent runner signature (injected by CLI layer). */
+export type ForkedAgentRunner = (params: {
+    promptMessages: ChatMessage[];
+    systemPrompt?: string;
+    tools: ToolDefinition[];
+    canUseTool?: CanUseToolFn;
+    transport: LLMTransport;
+    toolInvoker: ToolInvoker;
+    apiKey: string;
+    model: string;
+    log: AgentLogger;
+    hooks?: HookRegistry;
+    forkLabel: string;
+    sidechainType?: "planner" | "research" | "plan-repair" | "code-repair" | "media-prep";
+    maxTurns?: number;
+    parentSignal?: AbortSignal;
+    skipTranscript?: boolean;
+}) => Promise<{
+    ok: boolean;
+    content?: string;
+    error?: string;
+    durationMs: number;
+    totalUsage: {
+        prompt: number;
+        completion: number;
+    };
+}>;
+export interface SessionMemoryDeps {
+    /** Session state (for threshold tracking) */
+    sessionState: SessionState;
+    /** LLM transport for the extractor agent */
+    transport: LLMTransport;
+    /** Tool invoker */
+    toolInvoker: ToolInvoker;
+    /** Available tools (will be filtered for extraction) */
+    tools: ToolDefinition[];
+    /** API key */
+    apiKey: string;
+    /** Model for extraction (can use a cheaper/faster model) */
+    model: string;
+    /** Logger */
+    log: AgentLogger;
+    /** Hook registry */
+    hooks?: HookRegistry;
+    /** Path where session memory should be written */
+    memoryFilePath: string;
+    /** Parent abort signal */
+    parentSignal?: AbortSignal;
+    /** Forked agent runner (injected by CLI layer, decoupled from execution/) */
+    runForkedAgent: ForkedAgentRunner;
+}
+/**
+ * Check if memory extraction should run and execute if thresholds are met.
+ *
+ * Call this at the end of each turn (after turn.completed hook).
+ * It's a no-op if thresholds aren't met.
+ */
+export declare function maybeExtractSessionMemory(deps: SessionMemoryDeps, conversationMessages: ChatMessage[]): Promise<boolean>;

package/dist/types/runtime/session/session-persistence.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Session Persistence — CC sessionRestore.ts + conversationRecovery.ts parity.
+ *
+ * Enables conversation resume by persisting:
+ *   1. Message transcript (JSONL-based, append-only)
+ *   2. Cost snapshot (atomic JSON)
+ *   3. Session metadata (model, cwd, agent mode)
+ *
+ * Storage layout:
+ *   ~/.openclaw/sessions/<session-id>/
+ *     transcript.jsonl   — append-only message log
+ *     state.json          — cost snapshot + metadata
+ *
+ * Resume flow (CC processResumedConversation parity):
+ *   1. loadSessionForResume(sessionId) → messages + cost
+ *   2. Restore cost state into SessionState
+ *   3. Feed messages as initial context to agent
+ *
+ * Reference: claude-code src/utils/sessionRestore.ts
+ *            claude-code src/utils/conversationRecovery.ts
+ */
+import type { ChatMessage } from "../../agent/types.js";
+import type { SessionCostSnapshot } from "./session-state.js";
+export interface SessionMetadata {
+    sessionId: string;
+    createdAt: number;
+    lastActiveAt: number;
+    model?: string;
+    cwd?: string;
+    turnCount: number;
+    messageCount: number;
+    /** Title / description (auto-generated or user-set) */
+    title?: string;
+    /** Task summary generated by LLM (CC maybeGenerateTaskSummary parity) */
+    taskSummary?: string;
+    /** Timestamp of last task summary generation */
+    taskSummaryGeneratedAt?: number;
+}
+export interface PersistedSession {
+    metadata: SessionMetadata;
+    messages: ChatMessage[];
+    costSnapshot?: SessionCostSnapshot;
+}
+export interface SessionListEntry {
+    sessionId: string;
+    title?: string;
+    lastActiveAt: number;
+    messageCount: number;
+    model?: string;
+}
+/**
+ * Append a message to the session transcript.
+ * Creates the session directory if it doesn't exist.
+ */
+export declare function appendMessage(sessionId: string, message: ChatMessage): Promise<void>;
+/**
+ * Save session state (cost + metadata) atomically.
+ */
+export declare function saveSessionState(sessionId: string, costSnapshot: SessionCostSnapshot, metadata: Partial<SessionMetadata>): Promise<void>;
+/**
+ * Load a persisted session for resume — CC loadConversationForResume parity.
+ *
+ * Returns null if the session doesn't exist or is corrupted.
+ */
+export declare function loadSessionForResume(sessionId: string): Promise<PersistedSession | null>;
+/**
+ * List available sessions for resume — CC ResumeConversation picker.
+ * Returns most-recent-first, up to `limit` entries.
+ */
+export declare function listSessions(limit?: number): Promise<SessionListEntry[]>;
+/**
+ * Delete a session (cleanup).
+ */
+export declare function deleteSession(sessionId: string): Promise<void>;
+/**
+ * Prune old sessions beyond MAX_SESSIONS limit.
+ * Deletes oldest sessions first.
+ */
+export declare function pruneOldSessions(): Promise<number>;
+export interface TaskSummaryDeps {
+    transport: import("../../llm/transport.js").LLMTransport;
+    apiKey: string;
+    model: string;
+}
+/**
+ * Check if a task summary should be generated for this session.
+ * Triggers after TASK_SUMMARY_TURN_THRESHOLD turns, then every REGEN_INTERVAL turns.
+ */
+export declare function shouldGenerateTaskSummary(metadata: SessionMetadata): boolean;
+/**
+ * Generate and persist a task summary for a long session.
+ * Fire-and-forget — errors are swallowed.
+ */
+export declare function maybeGenerateTaskSummary(sessionId: string, metadata: SessionMetadata, recentMessages: ChatMessage[], deps: TaskSummaryDeps): Promise<string | null>;

package/dist/types/runtime/session/session-state.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Session State — CC session state parity.
+ *
+ * Unified state container for a single agent session:
+ *   - Token usage / cost accumulation across turns
+ *   - Session trust acceptance (per-session, non-persistent)
+ *   - Background memory extraction trigger thresholds
+ *   - Session-level settings
+ *
+ * This module is the qlogicagent equivalent of CC's:
+ *   - bootstrap/state.ts (session state fields)
+ *   - cost-tracker.ts (cost accumulation + persistence)
+ *   - sessionRestore.ts (cost restore guard)
+ *
+ * Reference: claude-code src/bootstrap/state.ts, src/cost-tracker.ts
+ */
+import type { TokenUsage } from "../../agent/types.js";
+/** Per-model usage accumulation — CC modelUsage parity */
+export interface ModelUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cacheCreation: number;
+    costUSD: number;
+}
+/** Snapshot of the session state for persistence / restore */
+export interface SessionCostSnapshot {
+    sessionId: string;
+    totalCostUSD: number;
+    modelUsage: Record<string, ModelUsage>;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    turnCount: number;
+    lastSavedAt: number;
+}
+/** Thresholds for background memory extraction — CC sessionMemory.ts parity */
+export interface MemoryExtractionThresholds {
+    /** Token threshold before FIRST extraction (default 10000) */
+    initialTokenThreshold: number;
+    /** Token threshold between UPDATES (default 5000) */
+    updateTokenThreshold: number;
+    /** Tool call threshold (default 3) */
+    toolCallThreshold: number;
+}
+export declare class SessionState {
+    readonly sessionId: string;
+    private _trustAccepted;
+    private _totalCostUSD;
+    private _modelUsage;
+    private _totalInputTokens;
+    private _totalOutputTokens;
+    private _turnCount;
+    private _toolCallCount;
+    private _tokensSinceLastExtraction;
+    private _toolCallsSinceLastExtraction;
+    private _hasExtractedOnce;
+    private _listeners;
+    /** Memory extraction thresholds — CC sessionMemory defaults */
+    readonly extractionThresholds: MemoryExtractionThresholds;
+    constructor(sessionId: string, thresholds?: Partial<MemoryExtractionThresholds>);
+    get trustAccepted(): boolean;
+    setTrustAccepted(accepted: boolean): void;
+    get totalCostUSD(): number;
+    get totalInputTokens(): number;
+    get totalOutputTokens(): number;
+    get turnCount(): number;
+    get toolCallCount(): number;
+    /** Get usage for a specific model */
+    getModelUsage(model: string): ModelUsage | undefined;
+    /** Get all model usages as a plain object */
+    getAllModelUsage(): Record<string, ModelUsage>;
+    /**
+     * Add usage from an API response — CC addToTotalSessionCost() parity.
+     *
+     * @param usage - Token counts from the API response
+     * @param model - Model identifier
+     * @param costUSD - Calculated cost (caller computes based on pricing)
+     */
+    addUsage(usage: TokenUsage, model: string, costUSD?: number): void;
+    /** Record a tool call (for extraction threshold tracking) */
+    recordToolCall(): void;
+    /** Increment turn count */
+    recordTurnCompleted(): void;
+    /**
+     * Check whether background memory extraction should trigger.
+     * CC sessionMemory.ts shouldExtract() parity.
+     *
+     * Logic:
+     *   - Token threshold is ALWAYS required
+     *   - Tool call threshold is an additional gate
+     *   - Token threshold: initialTokenThreshold before first extraction,
+     *     updateTokenThreshold after
+     */
+    shouldExtractMemory(): boolean;
+    /** Mark that extraction was performed — reset counters */
+    markExtractionDone(): void;
+    /**
+     * Create a snapshot for persistence.
+     * CC saveCurrentSessionCosts() parity.
+     */
+    createSnapshot(): SessionCostSnapshot;
+    /**
+     * Restore from a previous snapshot.
+     * CC setCostStateForRestore() parity.
+     *
+     * GUARD: Only restores if the snapshot's sessionId matches this session.
+     * Prevents cross-session cost leakage (CC's lastSessionId guard).
+     */
+    restoreFromSnapshot(snapshot: SessionCostSnapshot): boolean;
+    /** Register a state change listener. Returns unsubscribe function. */
+    onStateChange(listener: () => void): () => void;
+    private notifyListeners;
+}
+/**
+ * Create a new session state instance.
+ */
+export declare function createSessionState(sessionId: string, thresholds?: Partial<MemoryExtractionThresholds>): SessionState;