trellis/dist/garden/garden.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Idea Garden — Query Layer + Revive
 *
 * DESIGN.md §7.4–7.5 — Search and revive idea clusters.
 *
 * The Garden is a query layer over the causal stream that surfaces
 * abandoned work as searchable idea clusters. It also provides the
 * ability to revive clusters into new branches.
 */
import type { VcsOp } from '../vcs/types.js';
import { type IdeaCluster, type ClusterDetector } from './cluster.js';
export interface ScoredCluster {
    cluster: IdeaCluster;
    score: number;
}
export interface GardenSearchOpts {
    /** Filter by affected file path (substring match). */
    file?: string;
    /** Filter by keyword in affected files or estimated intent. */
    keyword?: string;
    /** Filter by cluster status. */
    status?: IdeaCluster['status'];
    /** Maximum results to return. */
    limit?: number;
    /** Use vector similarity when an EmbeddingManager is available (default: true). */
    semantic?: boolean;
}
/**
 * Optional embedding manager interface for vector-enhanced search.
 * Avoids hard dependency on the embeddings module.
 */
export interface GardenEmbedder {
    search(query: string, opts?: {
        limit?: number;
        filePrefix?: string;
    }): Promise<Array<{
        chunk: {
            filePath?: string;
            content: string;
        };
        score: number;
    }>>;
}
export interface GardenContext {
    /** All ops in the stream. */
    readAllOps(): VcsOp[];
    /** Set of op hashes that belong to a milestone range. */
    getMilestonedOpHashes(): Set<string>;
}
export declare class IdeaGarden {
    private ctx;
    private detectors;
    private _cache;
    private _revivedIds;
    private _embedder;
    constructor(ctx: GardenContext, detectors?: ClusterDetector[]);
    /**
     * Attach an embedding manager for vector-enhanced search.
     */
    setEmbedder(embedder: GardenEmbedder | null): void;
    /**
     * Invalidate the cluster cache (call after new ops are added).
     */
    invalidate(): void;
    /**
     * Detect and return all idea clusters.
     */
    listClusters(): IdeaCluster[];
    /**
     * Get a single cluster by ID.
     */
    getCluster(clusterId: string): IdeaCluster | null;
    /**
     * Search clusters with filters (synchronous keyword search).
     */
    search(opts?: GardenSearchOpts): IdeaCluster[];
    /**
     * Vector-enhanced search: uses embeddings to find clusters whose affected
     * files are semantically similar to the query. Falls back to keyword search
     * if no embedder is attached.
     */
    semanticSearch(opts?: GardenSearchOpts): Promise<ScoredCluster[]>;
    /**
     * Mark a cluster as revived. Returns the ops to replay.
     */
    revive(clusterId: string): VcsOp[] | null;
    /**
     * Get summary statistics for the garden.
     */
    stats(): {
        total: number;
        abandoned: number;
        draft: number;
        revived: number;
        totalOps: number;
        totalFiles: number;
    };
}
/**
 * Build a set of op hashes that fall within milestone ranges.
 * Used by the engine to provide GardenContext.getMilestonedOpHashes().
 */
export declare function buildMilestonedOpHashes(ops: VcsOp[]): Set<string>;
//# sourceMappingURL=garden.d.ts.map