zam-core 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,998 @@
+import { Database } from 'libsql';
+
+interface ConnectionOptions {
+    /** Path to the SQLite database file. Defaults to ~/.zam/zam.db */
+    dbPath?: string;
+    /** If true, create the directory and run schema migrations on open */
+    initialize?: boolean;
+    /** Turso sync URL for cloud replication (e.g. libsql://db-name.turso.io) */
+    syncUrl?: string;
+    /** Turso auth token for cloud replication */
+    authToken?: string;
+}
+/**
+ * Open (or create) the ZAM database.
+ * Uses WAL mode for concurrent access from AI CLI and user CLI.
+ * When syncUrl is provided, enables embedded replica sync with Turso.
+ */
+declare function openDatabase(options?: ConnectionOptions): Database;
+/**
+ * Open the database with Turso cloud sync auto-detected from stored settings.
+ * Reads turso.url and turso.token from user_config. If present, reopens
+ * the database with embedded replica sync enabled.
+ */
+declare function openDatabaseWithSync(options?: Omit<ConnectionOptions, "syncUrl" | "authToken">): Database;
+/** Get the default database path */
+declare function getDefaultDbPath(): string;
+
+/**
+ * Token repository — typed wrappers around the tokens table.
+ *
+ * Tokens are atomic knowledge concepts with Bloom taxonomy levels
+ * and optional symbiosis modes (shadowing / copilot / autonomy).
+ */
+
+type BloomLevel$1 = 1 | 2 | 3 | 4 | 5;
+type SymbiosisMode = "shadowing" | "copilot" | "autonomy";
+interface Token {
+    id: string;
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: BloomLevel$1;
+    context: string;
+    symbiosis_mode: SymbiosisMode | null;
+    created_at: string;
+    updated_at: string;
+    deprecated_at: string | null;
+}
+interface CreateTokenInput {
+    slug: string;
+    concept: string;
+    domain?: string;
+    bloom_level?: BloomLevel$1;
+    context?: string;
+    symbiosis_mode?: SymbiosisMode | null;
+}
+interface ListTokensOptions {
+    domain?: string;
+}
+interface ScoredToken extends Token {
+    score: number;
+}
+/**
+ * Create a new knowledge token.
+ * Throws if a token with the same slug already exists.
+ */
+declare function createToken(db: Database, input: CreateTokenInput): Token;
+/**
+ * Look up a token by its unique slug.
+ * Returns undefined if not found.
+ */
+declare function getTokenBySlug(db: Database, slug: string): Token | undefined;
+/**
+ * Look up a token by its ULID.
+ * Returns undefined if not found.
+ */
+declare function getTokenById(db: Database, id: string): Token | undefined;
+/**
+ * Mark a token as deprecated. Deprecated tokens are excluded from review queues
+ * and search results but are not deleted — they can still be consulted.
+ *
+ * Throws if the token does not exist or is already deprecated.
+ */
+declare function deprecateToken(db: Database, slug: string): Token;
+/**
+ * Fuzzy search for tokens by keyword query.
+ *
+ * Ported from the PoC's find-token command: splits the query into word
+ * tokens, scores each database token by word overlap plus a substring
+ * bonus on the concept field, and returns all matches sorted by score
+ * descending.
+ */
+declare function findTokens(db: Database, query: string): ScoredToken[];
+/**
+ * List all tokens, optionally filtered by domain.
+ * Results are ordered by bloom_level then slug.
+ */
+declare function listTokens(db: Database, options?: ListTokensOptions): Token[];
+
+/**
+ * Prerequisite repository — typed wrappers around the prerequisites table.
+ *
+ * Models the dependency graph: "to learn token A, first know token B."
+ */
+
+interface Prerequisite {
+    token_id: string;
+    requires_id: string;
+}
+/** A prerequisite row joined with the token it points to. */
+interface PrerequisiteWithToken extends Prerequisite {
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: number;
+}
+/**
+ * Add a prerequisite edge: tokenId requires requiresId.
+ *
+ * Idempotent — silently ignores duplicate edges.
+ * Throws if either token ID does not exist (FK constraint).
+ * Throws if a token is declared as its own prerequisite.
+ */
+declare function addPrerequisite(db: Database, tokenId: string, requiresId: string): void;
+/**
+ * Get the direct prerequisites of a token — "what does token X require?"
+ *
+ * Returns prerequisite rows joined with the required token's details.
+ */
+declare function getPrerequisites(db: Database, tokenId: string): PrerequisiteWithToken[];
+/**
+ * Get the direct dependents of a token — "what depends on token X?"
+ *
+ * Returns prerequisite rows joined with the dependent token's details.
+ */
+declare function getDependents(db: Database, tokenId: string): PrerequisiteWithToken[];
+
+/**
+ * Card repository — typed wrappers around the cards table.
+ *
+ * Each card tracks one user's scheduling state for one token,
+ * using FSRS fields (stability, difficulty, elapsed_days, etc.).
+ */
+
+type CardState$1 = "new" | "learning" | "review" | "relearning";
+interface Card {
+    id: string;
+    token_id: string;
+    user_id: string;
+    stability: number;
+    difficulty: number;
+    elapsed_days: number;
+    scheduled_days: number;
+    reps: number;
+    lapses: number;
+    state: CardState$1;
+    due_at: string;
+    last_review_at: string | null;
+    blocked: number;
+}
+interface UpdateCardInput {
+    stability?: number;
+    difficulty?: number;
+    elapsed_days?: number;
+    scheduled_days?: number;
+    reps?: number;
+    lapses?: number;
+    state?: CardState$1;
+    due_at?: string;
+    last_review_at?: string | null;
+    blocked?: number;
+}
+/** A due card joined with its token details. */
+interface DueCard extends Card {
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: number;
+}
+/** A blocked card joined with its token details. */
+interface BlockedCard extends Card {
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: number;
+}
+/**
+ * Ensure a card exists for the given token+user pair.
+ *
+ * If one already exists, return it. Otherwise create a new card with
+ * default FSRS values (due immediately) and return it.
+ *
+ * Ported from the PoC's ensureCard helper.
+ */
+declare function ensureCard(db: Database, tokenId: string, userId: string): Card;
+/**
+ * Get a card by token+user. Returns undefined if no card exists.
+ */
+declare function getCard(db: Database, tokenId: string, userId: string): Card | undefined;
+/**
+ * Update a card's scheduling fields.
+ *
+ * Only the fields present in `updates` are changed. Throws if the card
+ * does not exist.
+ */
+declare function updateCard(db: Database, cardId: string, updates: UpdateCardInput): Card;
+/**
+ * Get all cards that are due for review.
+ *
+ * A card is due when it is not blocked and due_at <= now.
+ * Results are ordered by bloom_level ascending (fundamentals first),
+ * then by due_at ascending (oldest first).
+ *
+ * Ported from the PoC's due-tokens command.
+ */
+declare function getDueCards(db: Database, userId: string, now?: string): DueCard[];
+/**
+ * Get all blocked cards for a user.
+ *
+ * Returns cards joined with their token details so the caller can
+ * see what is waiting and why.
+ */
+declare function getBlockedCards(db: Database, userId: string): BlockedCard[];
+
+/**
+ * Review log repository — typed wrappers around the review_logs table.
+ *
+ * The review log is immutable: every rating event is appended, never
+ * updated or deleted. This provides a complete audit trail of a user's
+ * learning history.
+ */
+
+interface ReviewLog {
+    id: string;
+    card_id: string;
+    token_id: string;
+    user_id: string;
+    rating: number;
+    response_time_ms: number | null;
+    reviewed_at: string;
+    scheduled_at: string;
+    session_id: string | null;
+}
+interface CreateReviewInput {
+    card_id: string;
+    token_id: string;
+    user_id: string;
+    rating: number;
+    scheduled_at: string;
+    response_time_ms?: number | null;
+    session_id?: string | null;
+}
+interface ListReviewsOptions {
+    /** Maximum number of reviews to return. */
+    limit?: number;
+    /** Return reviews after this ISO timestamp. */
+    after?: string;
+    /** Return reviews before this ISO timestamp. */
+    before?: string;
+}
+/**
+ * Log an immutable review event.
+ *
+ * Validates that the rating is between 1 and 4 (matching the schema CHECK).
+ * Returns the created review log entry.
+ */
+declare function logReview(db: Database, input: CreateReviewInput): ReviewLog;
+/**
+ * Get all reviews for a specific card, ordered by reviewed_at ascending.
+ */
+declare function getReviewsForCard(db: Database, cardId: string): ReviewLog[];
+/**
+ * Get reviews for a user, with optional filtering.
+ *
+ * Results are ordered by reviewed_at descending (most recent first).
+ */
+declare function getReviewsForUser(db: Database, userId: string, options?: ListReviewsOptions): ReviewLog[];
+
+/**
+ * Session repository — typed wrappers around sessions and session_steps.
+ *
+ * A session represents a work+learning episode. Steps within a session
+ * record which tokens were touched and by whom (user or agent).
+ */
+
+type ExecutionContext = "shell" | "ui" | "reallife";
+interface Session {
+    id: string;
+    user_id: string;
+    task: string;
+    execution_context: ExecutionContext;
+    started_at: string;
+    completed_at: string | null;
+}
+interface SessionStep {
+    id: string;
+    session_id: string;
+    token_id: string;
+    done_by: "user" | "agent";
+    rating: number | null;
+    notes: string | null;
+    created_at: string;
+}
+interface CreateSessionInput {
+    user_id: string;
+    task: string;
+    execution_context?: ExecutionContext;
+}
+interface LogStepInput {
+    session_id: string;
+    token_id: string;
+    done_by: "user" | "agent";
+    rating?: number | null;
+    notes?: string | null;
+}
+/** A step joined with its token details, returned by getSessionSummary. */
+interface StepWithToken extends SessionStep {
+    slug: string;
+    concept: string;
+    domain: string;
+    bloom_level: number;
+}
+interface SessionSummary {
+    session: Session;
+    steps: StepWithToken[];
+}
+/**
+ * Start a new session. Returns the created session.
+ *
+ * Ported from the PoC's start-session command.
+ */
+declare function startSession(db: Database, input: CreateSessionInput): Session;
+/**
+ * End a session by setting its completed_at timestamp.
+ *
+ * Throws if the session does not exist or is already completed.
+ *
+ * Ported from the PoC's end-session command.
+ */
+declare function endSession(db: Database, sessionId: string): Session;
+/**
+ * Log a step within a session.
+ *
+ * Validates that done_by is 'user' or 'agent' and that the rating
+ * (if provided) is between 1 and 4.
+ *
+ * Ported from the PoC's log-step command.
+ */
+declare function logStep(db: Database, input: LogStepInput): SessionStep;
+/**
+ * Get a full session summary: the session record plus all steps
+ * joined with their token details.
+ *
+ * Ported from the PoC's session-summary command.
+ * Throws if the session does not exist.
+ */
+declare function getSessionSummary(db: Database, sessionId: string): SessionSummary;
+
+/**
+ * Agent skills: task recipes the agent learns from user guidance.
+ *
+ * When the agent cannot execute a step, it admits it, asks for guidance,
+ * and saves the successful approach here. Skills are linked to tokens so
+ * FSRS decay naturally resurfaces them for review — automation ≠ retention.
+ */
+
+type SkillSource = "learned" | "builtin";
+interface AgentSkill {
+    id: string;
+    slug: string;
+    description: string;
+    steps: string[];
+    token_slugs: string[];
+    source: SkillSource;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateAgentSkillInput {
+    slug: string;
+    description: string;
+    steps: string[];
+    token_slugs?: string[];
+    source?: SkillSource;
+}
+declare function createAgentSkill(db: Database, input: CreateAgentSkillInput): AgentSkill;
+declare function getAgentSkill(db: Database, slug: string): AgentSkill | undefined;
+declare function listAgentSkills(db: Database): AgentSkill[];
+
+/**
+ * User settings — key/value store backed by the user_config table.
+ */
+
+interface UserSetting {
+    key: string;
+    value: string;
+    updated_at: string;
+}
+/** Get a single setting by key. Returns undefined if not set. */
+declare function getSetting(db: Database, key: string): string | undefined;
+/** Get all settings as a key-value map. */
+declare function getAllSettings(db: Database): Record<string, string>;
+/** Get all settings with metadata. */
+declare function getAllSettingsDetailed(db: Database): UserSetting[];
+/** Set a setting (insert or update). */
+declare function setSetting(db: Database, key: string, value: string): void;
+/** Delete a setting. Returns true if it existed. */
+declare function deleteSetting(db: Database, key: string): boolean;
+
+/**
+ * FSRS-5 — Free Spaced Repetition Scheduler (v5)
+ *
+ * Pure-function implementation of the FSRS algorithm that replaces
+ * the PoC's SM-2 scheduler. This is the mathematical heart of ZAM's
+ * spaced-repetition engine.
+ *
+ * Reference: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm
+ */
+/** 1 = Again (forgot), 2 = Hard, 3 = Good, 4 = Easy */
+type Rating = 1 | 2 | 3 | 4;
+type CardState = "new" | "learning" | "review" | "relearning";
+interface SchedulingCard {
+    /** Memory stability in days — expected half-life of recall probability. */
+    stability: number;
+    /** Intrinsic difficulty on a 1–10 scale. */
+    difficulty: number;
+    /** Days elapsed since the last review. */
+    elapsedDays: number;
+    /** Currently scheduled interval in days. */
+    scheduledDays: number;
+    /** Count of successful consecutive reviews. */
+    reps: number;
+    /** Times the card was forgotten (rated Again). */
+    lapses: number;
+    /** Current learning state. */
+    state: CardState;
+    /** When the card is next due. */
+    dueAt: Date;
+    /** When the card was last reviewed (null for new cards). */
+    lastReviewAt: Date | null;
+}
+interface FSRSParameters {
+    /** 19 optimised weight parameters (w0 – w18). */
+    w: number[];
+    /** Target retention rate, e.g. 0.9 means we aim for 90% recall. */
+    requestRetention: number;
+}
+interface FSRS {
+    /** Return a fully updated card after applying a rating. Pure function. */
+    schedule(card: SchedulingCard, rating: Rating, now?: Date): SchedulingCard;
+    /** The parameters baked into this instance. */
+    readonly params: Readonly<FSRSParameters>;
+}
+/**
+ * Create an FSRS scheduler instance.
+ *
+ * All scheduling is done through pure functions — no side effects,
+ * no database access, no mutation of the input card.
+ */
+declare function createFSRS(params?: Partial<FSRSParameters>): FSRS;
+
+/**
+ * Cascade Block & Unblock — prerequisite-aware blocking logic.
+ *
+ * Ported from the PoC's cascade-block and unblock-ready commands.
+ *
+ * When a user rates a token as "forgot" (rating 1) and that token has
+ * prerequisites, we block the token and surface its prerequisites into
+ * the active deck. When all prerequisites are met, we unblock.
+ */
+
+interface CascadeBlockResult {
+    blockedSlug: string;
+    prerequisites: Array<{
+        slug: string;
+        concept: string;
+        bloomLevel: number;
+    }>;
+}
+interface UnblockResult {
+    unblocked: Array<{
+        slug: string;
+        concept: string;
+    }>;
+}
+/**
+ * Block a token and surface its prerequisites.
+ *
+ * Called when a user rates a token as "forgot" (rating 1). The token is
+ * marked as blocked so it won't appear in review queues. All direct
+ * prerequisites are ensured to have cards (unblocked, due now) so they
+ * appear in the user's next review session.
+ *
+ * @param db - Database connection
+ * @param userId - The user whose card to block
+ * @param tokenSlug - Slug of the token the user forgot
+ * @returns Info about what was blocked and which prerequisites were surfaced
+ */
+declare function cascadeBlock(db: Database, userId: string, tokenSlug: string): CascadeBlockResult;
+/**
+ * Scan all blocked cards for a user and unblock any whose prerequisites are met.
+ *
+ * A blocked card is ready to unblock when ALL of its direct prerequisites have:
+ * - reps >= 1 (the user has successfully recalled it at least once)
+ * - blocked = 0 (the prerequisite itself is not blocked)
+ *
+ * If a blocked card has no prerequisites at all, it is unblocked immediately
+ * (it was likely blocked in error or its prerequisites were removed).
+ *
+ * @param db - Database connection
+ * @param userId - The user whose blocked cards to check
+ * @returns List of cards that were unblocked
+ */
+declare function unblockReady(db: Database, userId: string): UnblockResult;
+
+/**
+ * Reorder items so no domain appears more than `maxConsecutive` times in a row.
+ *
+ * Algorithm: group items by domain, then round-robin across domain groups.
+ * Each round picks one item from each non-exhausted domain. Within a domain,
+ * the original order is preserved (so urgency sorting survives).
+ *
+ * If a domain has more items than others, its extras will appear after all
+ * other domains are exhausted — but the `maxConsecutive` cap is still
+ * respected by inserting items from the largest remaining domains first.
+ *
+ * @param items - Array of items to interleave. Not mutated.
+ * @param maxConsecutive - Max consecutive items from the same domain. Defaults to 2.
+ * @returns A new array with the same items in interleaved order.
+ */
+declare function interleave<T extends {
+    domain: string;
+}>(items: T[], maxConsecutive?: number): T[];
+
+/**
+ * Review Queue Builder — assembles a session's review queue.
+ *
+ * Combines due-card fetching, new-card selection, urgency sorting,
+ * and cross-domain interleaving into a single ready-to-review queue.
+ */
+
+interface ReviewQueueOptions {
+    userId: string;
+    maxNew?: number;
+    maxReviews?: number;
+    now?: Date;
+}
+interface ReviewQueueItem {
+    cardId: string;
+    tokenId: string;
+    slug: string;
+    concept: string;
+    domain: string;
+    bloomLevel: number;
+    state: string;
+    dueAt: string;
+}
+interface ReviewQueue {
+    items: ReviewQueueItem[];
+    newCount: number;
+    reviewCount: number;
+    relearnCount: number;
+    totalDomains: string[];
+}
+/**
+ * Build a review queue for a user's study session.
+ *
+ * The queue is assembled in stages:
+ * 1. Fetch all due cards (not blocked, due_at <= now, state in review/relearning/learning)
+ * 2. Fetch new cards (state = 'new', not blocked) up to maxNew
+ * 3. Sort overdue cards by urgency — most overdue first
+ * 4. Apply cross-domain interleaving to prevent same-domain streaks
+ * 5. Intersperse new cards at regular intervals (every 5th position)
+ * 6. Cap total at maxReviews
+ *
+ * @param db - Database connection
+ * @param options - Queue building options
+ * @returns The assembled review queue with metadata
+ */
+declare function buildReviewQueue(db: Database, options: ReviewQueueOptions): ReviewQueue;
+
+/**
+ * Active Recall Prompt Generation
+ *
+ * Generates review prompts from tokens, adapting the question style
+ * to the token's Bloom taxonomy level. This is NOT an LLM call —
+ * it's template-based prompt assembly for the CLI and bridge.
+ */
+type BloomLevel = 1 | 2 | 3 | 4 | 5;
+interface RecallPrompt {
+    cardId: string;
+    tokenId: string;
+    slug: string;
+    question: string;
+    concept: string;
+    domain: string;
+    bloomLevel: BloomLevel;
+    bloomVerb: string;
+    hints: string[];
+}
+interface PromptInput {
+    cardId: string;
+    tokenId: string;
+    slug: string;
+    concept: string;
+    domain: string;
+    bloomLevel: BloomLevel;
+}
+/**
+ * Generate a recall prompt for a token at its Bloom level.
+ * When called from the CLI, the prompt is rendered in the terminal.
+ * When called from the AI bridge, the JSON is returned for the AI to present conversationally.
+ */
+declare function generatePrompt(input: PromptInput): RecallPrompt;
+
+/**
+ * Rating Evaluator
+ *
+ * Processes a user's self-assessment rating after a recall attempt.
+ * Coordinates between FSRS scheduling, review logging, and blocking.
+ */
+
+interface EvaluateInput {
+    cardId: string;
+    tokenId: string;
+    userId: string;
+    rating: Rating;
+    sessionId?: string;
+    responseTimeMs?: number;
+}
+interface EvaluateResult {
+    nextDueAt: string;
+    stability: number;
+    difficulty: number;
+    state: string;
+    scheduledDays: number;
+    reps: number;
+    lapses: number;
+}
+/**
+ * Process a rating: update the card via FSRS, log the review.
+ * Returns the updated scheduling state.
+ *
+ * Note: blocking logic (cascade-block) is handled separately by the caller
+ * when rating === 1 and the token has prerequisites.
+ */
+declare function evaluateRating(db: Database, input: EvaluateInput): EvaluateResult;
+
+/**
+ * Learning Analytics
+ *
+ * Progress statistics, competence tracking, and session summaries.
+ * Ported from PoC's `stats` command with additions for FSRS and symbiosis modes.
+ */
+
+interface UserStats {
+    userId: string;
+    totalTokens: number;
+    cardsInDeck: number;
+    dueToday: number;
+    blocked: number;
+    mature: number;
+    avgStability: number | null;
+    totalSessions: number;
+    lastSession: string | null;
+}
+interface DomainCompetence {
+    domain: string;
+    totalCards: number;
+    matureCards: number;
+    avgStability: number;
+    retentionRate: number;
+    suggestedMode: "shadowing" | "copilot" | "autonomy";
+}
+/**
+ * Get overall learning stats for a user (ported from PoC's `stats` command).
+ */
+declare function getUserStats(db: Database, userId: string): UserStats;
+/**
+ * Get competence per domain for a user.
+ * Used to suggest symbiosis mode transitions.
+ */
+declare function getDomainCompetence(db: Database, userId: string): DomainCompetence[];
+
+/**
+ * Monitor log analyzer — maps observed shell commands to token ratings.
+ *
+ * Pure functions, no DB or filesystem access. Takes parsed command records
+ * and a token-to-pattern mapping, returns ratings with evidence.
+ */
+interface MonitorEvent {
+    type: "command_start" | "command_end" | "monitor_meta";
+    ts: string;
+    seq?: number;
+    pid?: number;
+    command?: string;
+    cwd?: string;
+    exit_code?: number;
+    event?: "start" | "stop";
+    session_id?: string;
+    shell?: string;
+}
+interface CommandRecord {
+    seq: number;
+    pid: number;
+    command: string;
+    cwd: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+    exitCode: number | null;
+}
+interface TokenPattern {
+    slug: string;
+    patterns: string[];
+}
+interface ObservationRating {
+    tokenSlug: string;
+    rating: 1 | 2 | 3 | 4 | null;
+    confidence: "high" | "medium" | "low";
+    evidence: {
+        matchedCommands: number;
+        helpSeeking: boolean;
+        errorCount: number;
+        selfCorrections: number;
+        medianGapMs: number | null;
+        thinkingGapMs: number | null;
+    };
+    matchedCommandTexts: string[];
+}
+interface AnalysisResult {
+    ratings: ObservationRating[];
+    unmatchedCommands: string[];
+    timeSpan: {
+        start: string;
+        end: string;
+        durationMs: number;
+    } | null;
+}
+/**
+ * Parse a JSONL string into MonitorEvent objects.
+ * Skips malformed lines silently.
+ */
+declare function parseMonitorLog(jsonl: string): MonitorEvent[];
+/**
+ * Pair command_start and command_end events by (pid, seq) into CommandRecords.
+ */
+declare function pairCommands(events: MonitorEvent[]): CommandRecord[];
+/**
+ * Analyze observed commands against token patterns and produce ratings.
+ */
+declare function analyzeObservation(commands: CommandRecord[], tokenPatterns: TokenPattern[]): AnalysisResult;
+
+/**
+ * Monitor I/O — read/write JSONL files for shell observation.
+ *
+ * Monitor logs live at ~/.zam/monitor/<session-id>.jsonl.
+ * Separated from analyzer.ts so the analyzer remains pure-function testable.
+ */
+
+/** Get the monitor directory path. */
+declare function getMonitorDir(): string;
+/** Get the JSONL file path for a session. */
+declare function getMonitorPath(sessionId: string): string;
+/** Ensure the monitor directory exists (mode 0700 for privacy). */
+declare function ensureMonitorDir(): void;
+/** Append a single event to the session's JSONL file. */
+declare function writeMonitorEvent(sessionId: string, event: MonitorEvent): void;
+/** Read and parse all events from a session's monitor log. */
+declare function readMonitorLog(sessionId: string): MonitorEvent[];
+/** Check if a monitor log exists for a session. */
+declare function monitorLogExists(sessionId: string): boolean;
+/** Get basic stats about a monitor log without full parsing. */
+declare function getMonitorLogStats(sessionId: string): {
+    exists: boolean;
+    sizeBytes: number;
+    lineCount: number;
+};
+
+/**
+ * Shell hook code generation for zsh and bash.
+ *
+ * Pure functions that return shell code strings. The CLI command
+ * `zam monitor start/stop` calls these and prints to stdout.
+ * The user wraps with `eval "$(zam monitor start ...)"`.
+ */
+/**
+ * Generate zsh hooks that capture commands to a JSONL file.
+ * Uses $EPOCHREALTIME for sub-second timestamp precision.
+ */
+declare function generateZshHooks(monitorFile: string, sessionId: string): string;
+/**
+ * Generate bash hooks that capture commands to a JSONL file.
+ * Uses DEBUG trap for preexec, PROMPT_COMMAND for precmd.
+ */
+declare function generateBashHooks(monitorFile: string, sessionId: string): string;
+/** Generate zsh code to remove monitor hooks. */
+declare function generateZshUnhooks(): string;
+/** Generate bash code to remove monitor hooks. */
+declare function generateBashUnhooks(): string;
+
+/**
+ * Skill Discovery — identifies recurring non-standard command patterns
+ * across multiple sessions and proposes them as minimal reusable skills.
+ *
+ * The key insight from Increment 2: "The human's demonstrated competence
+ * is the gate for automation — not the other way around." A pattern must
+ * appear consistently across sessions before being proposed as a skill.
+ *
+ * Pure functions — no DB access. Callers provide command records and
+ * existing skills; this module returns proposed skills.
+ */
+
+interface CommandSequence {
+    /** The ordered command prefixes forming the pattern (e.g., ["git checkout", "npm install", "npm run build"]) */
+    steps: string[];
+    /** How many sessions contained this sequence */
+    sessionCount: number;
+    /** Total occurrences across all sessions */
+    totalOccurrences: number;
+    /** Example full commands from the most recent occurrence */
+    examples: string[];
+}
+interface SkillProposal {
+    /** Suggested slug for the skill */
+    slug: string;
+    /** Human-readable description of what the pattern does */
+    description: string;
+    /** The command steps forming the skill */
+    steps: string[];
+    /** How many sessions demonstrated this pattern */
+    sessionCount: number;
+    /** Confidence that this is a real, repeatable skill */
+    confidence: "high" | "medium" | "low";
+    /** Example commands from actual usage */
+    examples: string[];
+}
+interface DiscoveryOptions {
+    /** Minimum number of sessions a pattern must appear in (default: 2) */
+    minSessions?: number;
+    /** Minimum sequence length to consider (default: 2) */
+    minSequenceLength?: number;
+    /** Maximum sequence length to consider (default: 5) */
+    maxSequenceLength?: number;
+    /** Existing skill slugs to exclude from proposals */
+    existingSkillSlugs?: string[];
+}
+/**
+ * Discover recurring command patterns across multiple sessions.
+ *
+ * Takes a map of session ID → command records, finds command sequences
+ * that appear in multiple sessions, and proposes them as skills.
+ *
+ * @param sessionCommands - Map of session ID to that session's commands
+ * @param options - Discovery configuration
+ * @returns Array of skill proposals, sorted by confidence then session count
+ */
+declare function discoverSkills(sessionCommands: Map<string, CommandRecord[]>, options?: DiscoveryOptions): SkillProposal[];
+
+/**
+ * Goal file parser — reads markdown files with YAML-style frontmatter.
+ *
+ * Goals are persisted as markdown files in the personal repo.
+ * Each file has simple key: value frontmatter (no nested structures)
+ * and a markdown body with description, tasks, and token references.
+ */
+type GoalStatus = "active" | "completed" | "paused" | "abandoned";
+interface Goal {
+    slug: string;
+    title: string;
+    status: GoalStatus;
+    parent: string | null;
+    created: string;
+    updated: string;
+    body: string;
+    filePath: string;
+}
+interface GoalFrontmatter {
+    title?: string;
+    status?: string;
+    parent?: string;
+    created?: string;
+    updated?: string;
+}
+/**
+ * Parse a goal markdown file into a Goal object.
+ *
+ * Expected format:
+ * ```
+ * ---
+ * title: Learn Rust fundamentals
+ * status: active
+ * parent: become-systems-programmer
+ * created: 2026-03-28
+ * updated: 2026-03-28
+ * ---
+ *
+ * ## Description
+ * ...
+ * ```
+ *
+ * @param content - Raw file content
+ * @param slug - Goal slug (derived from filename by caller)
+ * @param filePath - Absolute path to the file
+ */
+declare function parseGoalFile(content: string, slug: string, filePath: string): Goal;
+/**
+ * Serialize a Goal back to markdown with frontmatter.
+ */
+declare function serializeGoal(goal: Goal): string;
+/**
+ * Extract tasks (checklist items) from goal body.
+ * Returns items like { text: "Complete Rustlings", done: false }.
+ */
+declare function extractTasks(body: string): Array<{
+    text: string;
+    done: boolean;
+}>;
+/**
+ * Extract token references from goal body.
+ * Looks for lines like `- token/slug` under a "## Tokens" section.
+ */
+declare function extractTokenRefs(body: string): string[];
+
+/**
+ * Goal Engine — manages goal lifecycle via markdown files.
+ *
+ * Goals live as markdown files in a directory (typically the personal repo's
+ * goals/ folder). The engine reads, creates, and updates these files.
+ * It does not depend on the database — goals are git-tracked, not DB-tracked.
+ */
+
+interface GoalSummary {
+    slug: string;
+    title: string;
+    status: GoalStatus;
+    parent: string | null;
+    taskCount: number;
+    tasksDone: number;
+    tokenCount: number;
+}
+interface CreateGoalInput {
+    slug: string;
+    title: string;
+    status?: GoalStatus;
+    parent?: string;
+    description?: string;
+}
+/**
+ * List all goals in the goals directory.
+ * Returns summaries sorted by status (active first) then title.
+ */
+declare function listGoals(goalsDir: string): GoalSummary[];
+/**
+ * Get a single goal by slug (filename without .md).
+ * Returns undefined if the file doesn't exist.
+ */
+declare function getGoal(goalsDir: string, slug: string): Goal | undefined;
+/**
+ * Create a new goal file. Throws if a goal with this slug already exists.
+ */
+declare function createGoal(goalsDir: string, input: CreateGoalInput): Goal;
+/**
+ * Update a goal's status. Writes the updated file back to disk.
+ */
+declare function updateGoalStatus(goalsDir: string, slug: string, status: GoalStatus): Goal;
+/**
+ * Get the goal tree — goals organized by parent relationships.
+ * Returns root goals (no parent) with nested children.
+ */
+declare function getGoalTree(goalsDir: string): Array<GoalSummary & {
+    children: GoalSummary[];
+}>;
+
+/**
+ * Azure DevOps connector — fetches work items from ADO boards.
+ */
+
+interface ADOConfig {
+    orgUrl: string;
+    project: string;
+    pat: string;
+}
+interface WorkItem {
+    id: number;
+    title: string;
+    state: string;
+    type: string;
+    assignedTo: string;
+}
+/** Load ADO config from user settings. Returns null if not configured. */
+declare function loadADOConfig(db: Database): ADOConfig | null;
+/**
+ * Fetch active work items assigned to the current user.
+ * Uses WIQL to query, then batch-fetches work item details.
+ */
+declare function fetchActiveWorkItems(config: ADOConfig): Promise<WorkItem[]>;
+
+export { type ADOConfig, type AgentSkill, type AnalysisResult, type BloomLevel$1 as BloomLevel, type Card, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type DiscoveryOptions, type DomainCompetence, type EvaluateInput, type EvaluateResult, type ExecutionContext, type FSRSParameters, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, type LogStepInput, type MonitorEvent, type ObservationRating, type Prerequisite, type PrerequisiteWithToken, type PromptInput, type Rating, type RecallPrompt, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SkillProposal, type SkillSource, type SymbiosisMode, type Token, type TokenPattern, type UnblockResult, type UpdateCardInput, type UserSetting, type UserStats, type WorkItem, addPrerequisite, analyzeObservation, buildReviewQueue, cascadeBlock, createAgentSkill, createFSRS, createGoal, createToken, deleteSetting, deprecateToken, discoverSkills, endSession, ensureCard, ensureMonitorDir, evaluateRating, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generatePrompt, generateZshHooks, generateZshUnhooks, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getGoal, getGoalTree, getMonitorDir, getMonitorLogStats, getMonitorPath, getPrerequisites, getReviewsForCard, getReviewsForUser, getSessionSummary, getSetting, getTokenById, getTokenBySlug, getUserStats, interleave, listAgentSkills, listGoals, listTokens, loadADOConfig, logReview, logStep, monitorLogExists, openDatabase, openDatabaseWithSync, pairCommands, parseGoalFile, parseMonitorLog, readMonitorLog, serializeGoal, setSetting, startSession, unblockReady, updateCard, updateGoalStatus, writeMonitorEvent };