clementine-agent 1.0.0

package/dist/agent/assistant.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Clementine TypeScript — Core assistant (Agent Layer).
+ *
+ * Uses @anthropic-ai/claude-agent-sdk query() with built-in tools + external MCP stdio server.
+ * Features:
+ *   - canUseTool: SDK-level security enforcement (blocks dangerous operations)
+ *   - Auto-memory: background Haiku pass extracts facts after every exchange
+ *   - Session rotation: auto-clears sessions before hitting context limits
+ *   - Session expiry: sessions expire after 24 hours of inactivity
+ *   - Env isolation: Claude subprocess doesn't see credential env vars
+ */
+import type { AgentProfile, OnTextCallback, OnToolActivityCallback, VerboseLevel } from '../types.js';
+import { AgentManager } from './agent-manager.js';
+/**
+ * Estimate token count using a weighted heuristic.
+ * BPE tokenizers average ~4 chars/token for prose, but code, punctuation,
+ * and whitespace-heavy content tokenize differently.
+ */
+export declare function estimateTokens(text: string): number;
+export interface ProjectMeta {
+    path: string;
+    description?: string;
+    keywords?: string[];
+}
+/** Find a linked project by name (case-insensitive, supports partial match). */
+export declare function findProjectByName(query: string): ProjectMeta | null;
+/** Get all linked projects. */
+export declare function getLinkedProjects(): ProjectMeta[];
+export declare class PersonalAssistant {
+    static readonly MAX_SESSION_EXCHANGES = 40;
+    private sessions;
+    private exchangeCounts;
+    private sessionTimestamps;
+    private lastExchanges;
+    private pendingContext;
+    private restoredSessions;
+    private profileManager;
+    private promptCache;
+    private _lastDailyNotePath;
+    private memoryStore;
+    private _lastUserMessage?;
+    private onUnleashedComplete;
+    private onPhaseComplete;
+    private onPhaseProgress;
+    onSkillProposed: ((skill: import('../types.js').SkillDocument) => void) | null;
+    private _lastMcpStatus;
+    private _lastMcpStatusTime;
+    /** Terminal reason from the last SDK query — consumed by cron scheduler for precise error classification. */
+    private _lastTerminalReason?;
+    /** Per-session stall nudge — set after a query shows stall signals, consumed on the next query. */
+    private stallNudges;
+    private _compactedSessions;
+    /** Hot correction buffer — explicit behavioral corrections applied before nightly SI. */
+    private hotCorrections;
+    constructor();
+    private initPromptWatchers;
+    /** Log SDK result metrics and store usage. Shared across all query methods. */
+    private logQueryResult;
+    /** Capture MCP server status from system init messages. */
+    private captureMcpStatus;
+    setUnleashedCompleteCallback(cb: (jobName: string, result: string) => void): void;
+    setPhaseCompleteCallback(cb: (jobName: string, phase: number, totalPhases: number, output: string) => void): void;
+    setPhaseProgressCallback(cb: (jobName: string, phase: number, summary: string) => void): void;
+    setSkillProposedCallback(cb: (skill: import('../types.js').SkillDocument) => void): void;
+    getMcpStatus(): {
+        servers: Array<{
+            name: string;
+            status: string;
+        }>;
+        updatedAt: string;
+    };
+    /** Inject a background work result into the session so the next chat naturally references it. */
+    injectPendingContext(sessionKey: string, userPrompt: string, result: string): void;
+    private initMemoryStore;
+    private loadSessions;
+    private saveSessions;
+    getExchangeCount(sessionKey: string): number;
+    getMemoryChunkCount(): number;
+    private buildSystemPrompt;
+    private buildOptions;
+    private retrieveContext;
+    /** Cached active goals — avoids N file reads per query. Refreshes every 30s. */
+    private _goalCache;
+    private static readonly GOAL_CACHE_TTL_MS;
+    private loadGoalsFromCache;
+    /**
+     * Match a user message against active goals by keyword overlap.
+     * Returns formatted goal status block for injection into system prompt,
+     * or empty string if no goals match.
+     */
+    private matchGoals;
+    chat(text: string, sessionKey?: string | null, options?: {
+        onText?: OnTextCallback;
+        onToolActivity?: OnToolActivityCallback;
+        model?: string;
+        maxTurns?: number;
+        profile?: AgentProfile;
+        securityAnnotation?: string;
+        projectOverride?: ProjectMeta;
+        verboseLevel?: VerboseLevel;
+        abortController?: AbortController;
+    }): Promise<[string, string]>;
+    private static readonly RATE_LIMIT_MAX_RETRIES;
+    private static readonly RATE_LIMIT_BACKOFF;
+    private runQuery;
+    /**
+     * Compact a session's context when nearing the context window limit.
+     *
+     * Inspired by Anthropic's context compaction pattern: summarize what happened,
+     * write to working memory (which is injected into every new system prompt),
+     * and rotate the session so the next message starts fresh with the summary.
+     *
+     * No LLM call — uses buildLocalSummary for instant summarization.
+     */
+    private compactContext;
+    /**
+     * Build an instant local summary from in-memory exchange history.
+     * No LLM call — returns immediately. Used during session rotation
+     * to avoid blocking the user's query.
+     */
+    private buildLocalSummary;
+    /**
+     * Auto-save a lightweight handoff file when a session rotates.
+     * Uses in-memory exchange history — no LLM call.
+     */
+    private saveAutoHandoff;
+    /**
+     * Load a handoff file for a session if one exists.
+     * Returns formatted context string or empty string.
+     */
+    private loadHandoff;
+    /**
+     * Run an LLM summary in the background and save to memoryStore.
+     * Does not block the caller — for future retrieval context only.
+     */
+    private summarizeSessionAsync;
+    private summarizeSession;
+    /**
+     * Parse a structured checkpoint from an unleashed phase's STATUS SUMMARY output.
+     * Returns null if no recognizable structure is found.
+     */
+    static parseUnleashedCheckpoint(output: string): {
+        summary: string;
+        completed: string[];
+        remaining: string[];
+        artifacts: string[];
+        nextAction?: string;
+    } | null;
+    /** Fire-and-forget: extract a reusable skill from a successful execution. */
+    private extractSkillFromExecution;
+    private preRotationFlush;
+    private lastExtractionTime;
+    private worthExtracting;
+    private spawnMemoryExtraction;
+    private static readonly MEMORY_TOOL_NAMES;
+    private extractMemory;
+    heartbeat(standingInstructions: string, changesSummary?: string, timeContext?: string, dedupContext?: string, profile?: AgentProfile | null): Promise<string>;
+    runPlanStep(stepId: string, prompt: string, opts?: {
+        tier?: number;
+        maxTurns?: number;
+        model?: string;
+        disableTools?: boolean;
+        outputFormat?: {
+            type: 'json_schema';
+            schema: Record<string, unknown>;
+        };
+        delegateProfile?: AgentProfile;
+    }): Promise<string>;
+    runCronJob(jobName: string, jobPrompt: string, tier?: number, maxTurns?: number, model?: string, workDir?: string, timeoutMs?: number, successCriteria?: string[]): Promise<string>;
+    /**
+     * Goal-backward verification pass using Haiku after cron job execution.
+     * Instead of vague quality ratings, verifies actual outcomes:
+     * 1. Did the output address the task? (existence)
+     * 2. Is it substantive, not a stub/placeholder? (substance)
+     * 3. Does it connect to the goal / produce actionable results? (wired)
+     */
+    private runCronReflection;
+    runUnleashedTask(jobName: string, jobPrompt: string, tier?: number, maxTurns?: number, model?: string, workDir?: string, maxHours?: number): Promise<string>;
+    /**
+     * Run a team message as an unleashed-style autonomous task.
+     * Gives team agents the same multi-phase execution as cron jobs,
+     * instead of being killed by the 5-minute interactive chat timeout.
+     *
+     * @param onText  Streaming callback for real-time progress updates
+     */
+    runTeamTask(fromName: string, fromSlug: string, content: string, profile: AgentProfile, onText?: (token: string) => void): Promise<string>;
+    /**
+     * Inject a user/assistant exchange into a session's context without running
+     * a query.  Used to give the DM session visibility of cron/heartbeat outputs
+     * so follow-up conversation has context.
+     */
+    injectContext(sessionKey: string, userText: string, assistantText: string): void;
+    getRecentActivity(sinceIso: string): Array<{
+        sessionKey: string;
+        role: string;
+        content: string;
+        createdAt: string;
+    }>;
+    searchMemory(query: string, limit?: number): Array<{
+        sourceFile: string;
+        section: string;
+        content: string;
+        score: number;
+    }>;
+    /** Expose memory store for direct operations (consolidation, etc.). */
+    getMemoryStore(): any;
+    /** Get the terminal reason from the last SDK query (consumed after read). */
+    consumeLastTerminalReason(): string | undefined;
+    /**
+     * List subagent IDs for a given session.
+     * Uses the new SDK listSubagents() API for cross-agent introspection.
+     */
+    getSubagentList(sessionId: string): Promise<string[]>;
+    /**
+     * Get conversation messages from a subagent's transcript.
+     * Enables cross-agent learning — feed into memory extraction.
+     */
+    getSubagentHistory(sessionId: string, agentId: string, limit?: number): Promise<Array<{
+        type: string;
+        content: string;
+    }>>;
+    clearSession(sessionKey: string): void;
+    getProfileManager(): AgentManager;
+}
+//# sourceMappingURL=assistant.d.ts.map