@cerebriline/core 4.100.240

package/dist/cron/service/schedule-tool.d.ts

@@ -0,0 +1,81 @@
+import type { AgentTool, GatewayModelSelection, HubScheduleCreateInput, HubScheduleUpdateInput, ITelemetryService, ScheduleExecutionRecord, ScheduleRecord } from "@cerebriline/shared";
+import { z } from "zod";
+import type { ListSchedulesOptions } from "./schedule-service";
+export declare const ScheduledTaskInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        list: "list";
+        delete: "delete";
+        resume: "resume";
+        pause: "pause";
+        update: "update";
+        create: "create";
+        get: "get";
+        run_now: "run_now";
+    }>;
+    schedule_id: z.ZodOptional<z.ZodString>;
+    schedule_type: z.ZodOptional<z.ZodEnum<{
+        once: "once";
+        recurring: "recurring";
+    }>>;
+    name: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    run_at: z.ZodOptional<z.ZodString>;
+    cron_pattern: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        plan: "plan";
+        act: "act";
+        yolo: "yolo";
+    }>>;
+    system_prompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    max_iterations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    timeout_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    max_parallel: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    model_selection: z.ZodOptional<z.ZodObject<{
+        provider_id: z.ZodString;
+        model_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScheduledTaskInput = z.infer<typeof ScheduledTaskInputSchema>;
+export interface ScheduleSessionDefaults {
+    workspaceRoot: string;
+    cwd?: string;
+    modelSelection?: GatewayModelSelection;
+    interactive: boolean;
+}
+export interface AgentScheduleServiceApi {
+    createSchedule(input: HubScheduleCreateInput): ScheduleRecord;
+    getSchedule(scheduleId: string): ScheduleRecord | undefined;
+    listSchedules(options?: ListSchedulesOptions): ScheduleRecord[];
+    updateSchedule(scheduleId: string, updates: HubScheduleUpdateInput): ScheduleRecord | undefined;
+    deleteSchedule(scheduleId: string): boolean;
+    pauseSchedule(scheduleId: string): ScheduleRecord | undefined;
+    resumeSchedule(scheduleId: string): ScheduleRecord | undefined;
+    triggerScheduleNowDetached(scheduleId: string): ScheduleExecutionRecord | undefined;
+}
+export interface ScheduleTaskOperationOptions {
+    schedules: AgentScheduleServiceApi;
+    telemetry?: ITelemetryService;
+    resolveSessionDefaults: (sessionId: string) => Promise<ScheduleSessionDefaults | undefined>;
+    publish?: (event: "schedule.created" | "schedule.updated" | "schedule.deleted" | "schedule.triggered", payload: Record<string, unknown>, sessionId: string) => void;
+}
+export type ScheduledTaskResult = {
+    ok: true;
+    operation: ScheduledTaskInput["operation"];
+    schedule?: ScheduleRecord;
+    schedules?: ScheduleRecord[];
+    execution?: ScheduleExecutionRecord;
+    deleted?: boolean;
+} | {
+    ok: false;
+    operation?: ScheduledTaskInput["operation"];
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Execute a scheduled-work operation through the Hub schedule service. */
+export declare function executeScheduleOperation(options: ScheduleTaskOperationOptions, rawInput: unknown, context: Parameters<AgentTool<ScheduledTaskInput, ScheduledTaskResult>["execute"]>[1]): Promise<ScheduledTaskResult>;

package/dist/cron/specs/cron-reconciler.d.ts

@@ -0,0 +1,61 @@
+import type { CronSpecParseResult } from "@cerebriline/shared";
+import { type ResolveCronSpecsDirOptions } from "@cerebriline/shared/storage";
+import { type CronSpecRecord, type SqliteCronStore, type UpsertSpecResult } from "../store/sqlite-cron-store";
+/**
+ * Scan the configured cron specs directory on disk, parse every file, and
+ * upsert spec state into the cron DB. This is the startup source of truth:
+ * watcher events are triggers to re-run reconciliation for one file, not a
+ * replacement.
+ */
+export interface CronReconcilerOptions {
+    store: SqliteCronStore;
+    /**
+     * Cron spec source location. Defaults to global `~/.cline/cron`.
+     * Pass `{ scope: "workspace", workspaceRoot }` later to enable
+     * workspace-level cron sources without changing reconciler internals.
+     */
+    specs?: ResolveCronSpecsDirOptions;
+    /** @deprecated Use `specs: { scope: "workspace", workspaceRoot }`. */
+    workspaceRoot?: string;
+}
+export interface ReconcileChange {
+    relativePath: string;
+    result: UpsertSpecResult;
+    parse: CronSpecParseResult;
+}
+export interface ReconcileSummary {
+    scanned: number;
+    upserted: number;
+    invalidParses: number;
+    removed: number;
+    changes: ReconcileChange[];
+}
+export declare class CronReconciler {
+    private readonly store;
+    private readonly cronDir;
+    constructor(options: CronReconcilerOptions);
+    getCronDir(): string;
+    /**
+     * Reconcile every file under the cron specs directory into the DB and mark specs
+     * whose source files no longer exist as `removed=1`.
+     */
+    reconcileAll(): Promise<ReconcileSummary>;
+    /**
+     * Reconcile a single file (absolute path). `relativePath` is expected to
+     * be POSIX-relative to the cron specs directory. Returns the reconciliation change
+     * or undefined if the file could not be read.
+     */
+    reconcileFile(relativePath: string, absolutePath: string): Promise<ReconcileChange | undefined>;
+    /**
+     * Handle a file that disappeared from disk between reconciliations.
+     * Marks the spec as removed and cancels any queued runs for it.
+     */
+    handleFileDeleted(spec: CronSpecRecord): void;
+    /**
+     * Refresh next_run_at for every enabled schedule spec.
+     * Used at startup to handle the "one overdue catch-up on startup then
+     * advance to next slot" policy.
+     */
+    refreshScheduleNextRunAt(): void;
+    private applyScheduleNextRunAt;
+}

package/dist/cron/specs/cron-spec-parser.d.ts

@@ -0,0 +1,26 @@
+import type { CronSpecParseResult, CronTriggerKind } from "@cerebriline/shared";
+/**
+ * Markdown frontmatter parser for `.cline/cron/*.md` automation specs.
+ *
+ * Lives in @cline/core because it depends on `yaml`. The spec types
+ * themselves live in @cline/shared so other packages can consume them
+ * without pulling in a YAML parser.
+ *
+ * The parser never throws for a single bad file — it produces a
+ * `CronSpecParseResult` with an `error` message so the reconciler can record
+ * `parse_status='invalid'` durably instead of dropping state.
+ */
+export declare function inferTriggerKindFromPath(relativePath: string): CronTriggerKind;
+export declare function splitFrontmatter(raw: string): {
+    frontmatter: string | undefined;
+    body: string;
+};
+export declare function computeContentHash(frontmatterJson: unknown, body: string): string;
+export interface ParseCronSpecInput {
+    relativePath: string;
+    raw: string;
+}
+/**
+ * Parse a single cron spec file. Never throws; always returns a result.
+ */
+export declare function parseCronSpecFile(input: ParseCronSpecInput): CronSpecParseResult;

package/dist/cron/specs/cron-watcher.d.ts

@@ -0,0 +1,22 @@
+import type { CronReconciler } from "./cron-reconciler";
+export interface CronWatcherOptions {
+    reconciler: CronReconciler;
+    debounceMs?: number;
+    onError?: (error: unknown) => void;
+    onReconciled?: () => void | Promise<void>;
+}
+export declare class CronWatcher {
+    private readonly reconciler;
+    private readonly debounceMs;
+    private readonly onError;
+    private readonly onReconciled;
+    private watcher?;
+    private readonly pending;
+    private disposed;
+    constructor(options: CronWatcherOptions);
+    start(): void;
+    stop(): void;
+    dispose(): void;
+    private scheduleReconcile;
+    private reconcileNow;
+}

package/dist/cron/store/cron-schema.d.ts

@@ -0,0 +1,2 @@
+import type { SqliteDb } from "@cerebriline/shared/db";
+export declare function ensureCronSchema(db: SqliteDb): void;

package/dist/cron/store/sqlite-cron-store.d.ts

@@ -0,0 +1,261 @@
+import { type AutomationEventEnvelope, type CronSpec, type CronSpecExtensionKind, type CronTriggerKind, type HubScheduleCreateInput, type HubScheduleUpdateInput } from "@cerebriline/shared";
+/**
+ * Generalized cron/automation store backed by `cron.db`. Sessions stay in
+ * their own database (see @cline/shared `ensureSessionSchema`). cron_runs
+ * here absorb one-off, recurring, and event-driven work under one queue.
+ */
+export type CronRunStatus = "queued" | "running" | "done" | "failed" | "cancelled";
+export type CronRunTriggerKind = "one_off" | "schedule" | "event" | "manual" | "retry";
+export type CronParseStatus = "valid" | "invalid";
+export type CronEventProcessingStatus = "received" | "unmatched" | "queued" | "suppressed" | "failed";
+export interface CronSpecRecord {
+    specId: string;
+    externalId: string;
+    sourcePath: string;
+    triggerKind: CronTriggerKind;
+    sourceMtimeMs?: number;
+    sourceHash?: string;
+    parseStatus: CronParseStatus;
+    parseError?: string;
+    enabled: boolean;
+    removed: boolean;
+    title: string;
+    prompt?: string;
+    workspaceRoot?: string;
+    scheduleExpr?: string;
+    timezone?: string;
+    eventType?: string;
+    filters?: Record<string, unknown>;
+    debounceSeconds?: number;
+    dedupeWindowSeconds?: number;
+    cooldownSeconds?: number;
+    mode?: string;
+    systemPrompt?: string;
+    providerId?: string;
+    modelId?: string;
+    maxIterations?: number;
+    timeoutSeconds?: number;
+    maxParallel?: number;
+    tools?: string[];
+    notesDirectory?: string;
+    extensions?: CronSpecExtensionKind[];
+    source?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    revision: number;
+    lastMaterializedRunId?: string;
+    lastRunAt?: string;
+    nextRunAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CronRunRecord {
+    runId: string;
+    specId: string;
+    specRevision: number;
+    triggerKind: CronRunTriggerKind;
+    status: CronRunStatus;
+    claimToken?: string;
+    claimStartedAt?: string;
+    claimUntilAt?: string;
+    scheduledFor?: string;
+    triggerEventId?: string;
+    startedAt?: string;
+    completedAt?: string;
+    sessionId?: string;
+    reportPath?: string;
+    error?: string;
+    attemptCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CronEventLogRecord {
+    eventId: string;
+    eventType: string;
+    source: string;
+    subject?: string;
+    occurredAt: string;
+    receivedAt: string;
+    workspaceRoot?: string;
+    dedupeKey?: string;
+    payload?: Record<string, unknown>;
+    attributes?: Record<string, unknown>;
+    processingStatus: CronEventProcessingStatus;
+    matchedSpecCount: number;
+    queuedRunCount: number;
+    suppressedCount: number;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UpsertSpecInput {
+    externalId: string;
+    sourcePath: string;
+    triggerKind: CronTriggerKind;
+    sourceMtimeMs?: number;
+    sourceHash: string;
+    parseStatus: CronParseStatus;
+    parseError?: string;
+    spec?: CronSpec;
+}
+export interface UpsertSpecResult {
+    record: CronSpecRecord;
+    created: boolean;
+    revisionChanged: boolean;
+}
+export interface SqliteCronStoreOptions {
+    dbPath?: string;
+}
+/**
+ * DB-native hub schedules (created via the schedule tools/UI) live only in
+ * cron.db under a virtual sourcePath that never exists on disk. File-backed
+ * specs can spoof `source: hub-schedule` in frontmatter — even inside a
+ * physical `hub/schedules/` directory — but reconciliation always records
+ * their source file's mtime, which DB-native rows never have. All three
+ * markers are required to identify a DB-native hub schedule.
+ */
+export declare function isHubManagedSpec(spec: Pick<CronSpecRecord, "source" | "sourcePath" | "sourceMtimeMs">): boolean;
+export interface ListSpecsOptions {
+    triggerKind?: CronTriggerKind;
+    enabled?: boolean;
+    parseStatus?: CronParseStatus;
+    includeRemoved?: boolean;
+    limit?: number;
+}
+export interface ListRunsOptions {
+    specId?: string;
+    status?: CronRunStatus | CronRunStatus[];
+    limit?: number;
+}
+export interface ClaimRunOptions {
+    nowIso: string;
+    leaseMs: number;
+    limit?: number;
+}
+export interface ClaimedCronRun {
+    run: CronRunRecord;
+    claimToken: string;
+    claimUntilAt: string;
+}
+interface ClaimBoundUpdate {
+    runId: string;
+    claimToken: string;
+}
+export interface MaterializeScheduleRunResult {
+    queued: boolean;
+    run?: CronRunRecord;
+    nextRunAt?: string;
+}
+export interface EnqueueRunInput {
+    specId: string;
+    specRevision: number;
+    triggerKind: CronRunTriggerKind;
+    scheduledFor?: string;
+    triggerEventId?: string;
+}
+export interface InsertEventLogResult {
+    record: CronEventLogRecord;
+    created: boolean;
+}
+export interface ListEventLogsOptions {
+    eventType?: string;
+    source?: string;
+    processingStatus?: CronEventProcessingStatus;
+    limit?: number;
+}
+export declare class SqliteCronStore {
+    private readonly db;
+    constructor(options?: SqliteCronStoreOptions);
+    close(): void;
+    getSpecBySourcePath(sourcePath: string): CronSpecRecord | undefined;
+    getSpec(specId: string): CronSpecRecord | undefined;
+    getSpecByExternalId(externalId: string): CronSpecRecord | undefined;
+    listSpecs(options?: ListSpecsOptions): CronSpecRecord[];
+    createHubSchedule(input: HubScheduleCreateInput): CronSpecRecord;
+    getHubSchedule(scheduleId: string): CronSpecRecord | undefined;
+    listHubSchedules(options?: {
+        enabled?: boolean;
+        limit?: number;
+        tags?: string[];
+        workspaceRoot?: string;
+    }): CronSpecRecord[];
+    updateHubSchedule(scheduleId: string, updates: HubScheduleUpdateInput): CronSpecRecord | undefined;
+    private initializeHubScheduleNextRun;
+    deleteHubSchedule(scheduleId: string): boolean;
+    enqueueHubScheduleRun(scheduleId: string, triggerKind?: "manual" | "retry"): CronRunRecord | undefined;
+    private consumeOneOffWithManualRun;
+    listEventSpecsForType(eventType: string): CronSpecRecord[];
+    upsertSpec(input: UpsertSpecInput): UpsertSpecResult;
+    private insertSpecRow;
+    private updateSpecRow;
+    markSpecRemoved(specId: string): void;
+    updateSpecNextRunAt(specId: string, nextRunAt: string | undefined): void;
+    updateSpecLastRunAt(specId: string, lastRunAt: string): void;
+    updateLastMaterializedRunId(specId: string, runId: string): void;
+    private initializeScheduleNextRun;
+    materializeDueScheduleRun(options: {
+        specId: string;
+        nowMs: number;
+    }): MaterializeScheduleRunResult;
+    getRun(runId: string): CronRunRecord | undefined;
+    /**
+     * 1-based position of a run among every run ever created for its spec,
+     * in creation order. Counts runs of every status (including cancelled and
+     * failed ones) so the number is stable: a later cancellation never shifts
+     * the numbers already stamped onto earlier sessions. Returns undefined
+     * for an unknown run.
+     */
+    getRunOrdinal(runId: string): number | undefined;
+    insertEventLog(event: AutomationEventEnvelope, options?: {
+        receivedAtIso?: string;
+    }): InsertEventLogResult;
+    getEventLog(eventId: string): CronEventLogRecord | undefined;
+    listEventLogs(options?: ListEventLogsOptions): CronEventLogRecord[];
+    updateEventLogProcessing(eventId: string, update: {
+        status: CronEventProcessingStatus;
+        matchedSpecCount?: number;
+        queuedRunCount?: number;
+        suppressedCount?: number;
+        error?: string;
+    }): boolean;
+    listRuns(options?: ListRunsOptions): CronRunRecord[];
+    hasRecentEventRunForDedupe(options: {
+        specId: string;
+        dedupeKey: string;
+        sinceIso: string;
+    }): boolean;
+    hasRecentEventRunForSpec(options: {
+        specId: string;
+        sinceIso: string;
+    }): boolean;
+    findQueuedEventRunForDedupe(options: {
+        specId: string;
+        dedupeKey: string;
+    }): CronRunRecord | undefined;
+    updateQueuedEventRunForDebounce(options: {
+        runId: string;
+        triggerEventId: string;
+        scheduledFor: string;
+    }): CronRunRecord | undefined;
+    hasConsumedOneOffRevision(specId: string, revision: number): boolean;
+    enqueueRun(input: EnqueueRunInput): CronRunRecord;
+    cancelQueuedRunsForSpec(specId: string): number;
+    private cancelQueuedOneOffRunsForSpec;
+    claimDueRuns(options: ClaimRunOptions): ClaimedCronRun[];
+    renewClaim(runId: string, claimToken: string, leaseUntilAt: string): boolean;
+    completeRun(runId: string, update: {
+        status: "done" | "failed" | "cancelled";
+        sessionId?: string;
+        reportPath?: string;
+        error?: string;
+        completedAtIso?: string;
+        claimToken?: string;
+    }): boolean;
+    requeueRun(update: ClaimBoundUpdate & {
+        error?: string;
+        scheduledFor?: string;
+    }): boolean;
+    attachSessionIdToRun(runId: string, sessionId: string): void;
+    attachReportPathToRun(runId: string, reportPath: string): void;
+}
+export {};

package/dist/extensions/agent-plugin/agent-skill.d.ts

@@ -0,0 +1,21 @@
+export interface AgentSkillMetadata {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    "allowed-tools"?: string;
+}
+export interface ParsedAgentSkill {
+    metadata: AgentSkillMetadata;
+    instructions: string;
+    frontmatter: Record<string, unknown>;
+}
+/**
+ * Parse and validate one Agent Skills specification `SKILL.md` document.
+ *
+ * Cline's own skill files intentionally remain backwards-compatible and more
+ * permissive. Agent Plugin skills go through this strict path because the
+ * Agent Plugins contract requires an invalid skill to be skipped in isolation.
+ */
+export declare function parseAgentSkillMarkdown(content: string, directoryName: string): ParsedAgentSkill;

package/dist/extensions/agent-plugin/index.d.ts

@@ -0,0 +1,4 @@
+export type { AgentSkillMetadata, ParsedAgentSkill } from "./agent-skill";
+export { parseAgentSkillMarkdown } from "./agent-skill";
+export { AGENT_PLUGINS_V1_MANIFEST_SCHEMA, AGENT_PLUGINS_V1_MCP_SCHEMA, getAgentPluginPackageDisplayName, loadAgentPluginPackages, } from "./loader";
+export type { AgentPluginPackageDiagnostic, AgentPluginPackageDiagnosticScope, AgentPluginPackageLoadReport, AgentPluginPackageManifest, AgentPluginPackageMcpServer, AgentPluginPackageSkill, LoadAgentPluginPackagesOptions, LoadedAgentPluginPackage, } from "./types";

package/dist/extensions/agent-plugin/loader.d.ts

@@ -0,0 +1,10 @@
+import type { AgentPluginPackageLoadReport, LoadAgentPluginPackagesOptions } from "./types";
+export declare const AGENT_PLUGINS_V1_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export declare const AGENT_PLUGINS_V1_MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+/**
+ * Discover and load Agent Plugins v1 from runtime-host-local filesystem paths.
+ * No schema is fetched over the network: canonical identifiers select the
+ * validation code bundled with this SDK build.
+ */
+export declare function loadAgentPluginPackages(options?: LoadAgentPluginPackagesOptions): Promise<AgentPluginPackageLoadReport>;
+export declare function getAgentPluginPackageDisplayName(path: string): string;

package/dist/extensions/agent-plugin/types.d.ts

@@ -0,0 +1,67 @@
+import type { McpServerRegistration } from "../mcp";
+import type { AgentSkillMetadata } from "./agent-skill";
+export interface AgentPluginPackageManifest {
+    $schema: string;
+    name: string;
+    version?: string;
+    description?: string;
+    author?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    extensions?: Record<string, unknown>;
+}
+export interface AgentPluginPackageSkill {
+    pluginName: string;
+    pluginRoot: string;
+    directoryPath: string;
+    filePath: string;
+    metadata: AgentSkillMetadata;
+}
+export interface AgentPluginPackageMcpServer {
+    pluginName: string;
+    pluginRoot: string;
+    pluginDataPath?: string;
+    serverName: string;
+    registration: McpServerRegistration;
+}
+export type AgentPluginPackageDiagnosticScope = "plugin" | "manifest" | "skills" | "skill" | "mcp" | "mcp-server";
+export interface AgentPluginPackageDiagnostic {
+    level: "warning" | "error";
+    scope: AgentPluginPackageDiagnosticScope;
+    pluginPath: string;
+    pluginName?: string;
+    componentPath?: string;
+    componentName?: string;
+    message: string;
+}
+export interface LoadedAgentPluginPackage {
+    rootPath: string;
+    manifestPath: string;
+    manifest: AgentPluginPackageManifest;
+    skills: AgentPluginPackageSkill[];
+    mcpServers: AgentPluginPackageMcpServer[];
+}
+export interface AgentPluginPackageLoadReport {
+    plugins: LoadedAgentPluginPackage[];
+    skills: AgentPluginPackageSkill[];
+    mcpServers: AgentPluginPackageMcpServer[];
+    diagnostics: AgentPluginPackageDiagnostic[];
+}
+export interface LoadAgentPluginPackagesOptions {
+    /** Explicit plugin roots, resolved on the runtime host relative to `cwd`. */
+    pluginPaths?: ReadonlyArray<string>;
+    /** Base directory for resolving relative explicit plugin paths. */
+    cwd?: string;
+    /** Override automatic search roots. Primarily useful to embedded hosts/tests. */
+    searchPaths?: ReadonlyArray<string>;
+    /** Override the client-managed persistent Agent Plugin data root. */
+    pluginDataRoot?: string;
+    /** Manifest names disabled by the runtime host. Disabled names still reserve precedence. */
+    disabledPluginNames?: ReadonlyArray<string>;
+}

package/dist/extensions/complexity/grammars.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Loading a tree-sitter grammar, lazily and never fatally.
+ *
+ * The whole grammar set ships -- 50 MB of `tree-sitter-wasms`, which is a
+ * deliberate choice over a curated subset: a subset means picking the languages
+ * that matter now, and the first file in an unpicked language reads as "no
+ * complexity" rather than "not measured". Nothing is loaded until a file in
+ * that language is actually asked about, so the cost is disk rather than
+ * memory or start-up.
+ *
+ * Every failure path here answers `undefined`, which callers must treat as *no
+ * input* rather than as a complexity of zero. A missing wasm, a runtime that
+ * cannot instantiate it, a language nothing ships a grammar for: all of them
+ * mean the same thing, and none of them is evidence about the code.
+ */
+/** Whether a grammar exists for this file at all. */
+export declare function grammarFor(filePath: string): string | undefined;
+/** The minimum of web-tree-sitter this module uses, so tests can stand in. */
+export interface ParsedTree {
+    rootNode: SyntaxNode;
+    /** Trees live in wasm memory too, and are freed the same way. */
+    delete?(): void;
+}
+export interface SyntaxNode {
+    readonly type: string;
+    /**
+     * Whether anything under this node failed to parse.
+     *
+     * Read on the root, where it is the difference between a tree that can be
+     * scored and one that cannot. See `scoreComplexity`, which answers nothing
+     * for a tree that has it.
+     */
+    readonly hasError?: boolean;
+    readonly startPosition: {
+        row: number;
+        column: number;
+    };
+    readonly endPosition: {
+        row: number;
+        column: number;
+    };
+    readonly childCount: number;
+    child(index: number): SyntaxNode | null;
+    childForFieldName(name: string): SyntaxNode | null;
+    readonly text: string;
+}
+export interface ParserLike {
+    setLanguage(language: unknown): void;
+    parse(source: string): ParsedTree | null;
+    /** web-tree-sitter holds parsers in wasm memory and frees none of them. */
+    delete?(): void;
+}
+/**
+ * Where the wasm files are. Three places, in the order a host would want.
+ *
+ * `createRequire` rather than a bundler import: the grammars are data the
+ * runtime reads, not modules, and a bundler asked to inline 50 MB of wasm
+ * produces a bundle nobody can ship.
+ *
+ * The middle case is the shipped one. A bundled host has no `node_modules` to
+ * resolve against, so the build copies the grammars to a `grammars/` directory
+ * beside the bundle and this finds them there -- by looking, not by being told.
+ * Being told was the alternative and it is the weaker design: a `grammarDir`
+ * threaded through the runtime config is a field every layer has to remember to
+ * copy, and the failure when one does not is this feature going quiet rather
+ * than anything breaking. The explicit option stays for a host that puts them
+ * somewhere else entirely.
+ */
+export declare function resolveGrammarPath(grammar: string, grammarDir?: string, 
+/** The bundle's directory. A parameter so a test can be somewhere else. */
+besideDir?: string): string | undefined;
+/**
+ * A parser for this file's language, or nothing.
+ *
+ * Nothing is a normal answer and is never an error the caller has to handle as
+ * one: the complexity input is optional everywhere it is read.
+ */
+export declare function parserFor(filePath: string, options?: {
+    grammarDir?: string;
+}): Promise<ParserLike | undefined>;
+/**
+ * A parser for a grammar named directly, rather than inferred from a path.
+ *
+ * The embedded-language pass needs this: the `<script>` bodies inside an HTML
+ * file are JavaScript, and there is no filename to infer that from. Same
+ * caching, same silence on every failure.
+ */
+export declare function parserForGrammar(grammar: string, options?: {
+    grammarDir?: string;
+}): Promise<ParserLike | undefined>;
+/** Drop the cached grammars. For tests, and for a host that swaps the directory. */
+export declare function forgetGrammars(): void;