@shuyhere/takotako 0.0.1

package/dist/auth/storage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Auth storage — read/write provider credentials to ~/.tako/auth/<provider>.json
+ *
+ * Supports multiple auth methods per provider:
+ *   - api_key: traditional API key
+ *   - setup_token: Anthropic subscription setup token
+ *   - oauth: OAuth2 access/refresh tokens (OpenAI Codex, etc.)
+ *
+ * Resolution order:
+ *   1. Environment variables (highest priority)
+ *   2. Auth files (~/.tako/auth/<provider>.json)
+ *   3. Legacy .env file (~/.tako/.env)
+ */
+export type AuthMethod = 'api_key' | 'setup_token' | 'oauth';
+export interface BaseCredential {
+    provider: string;
+    auth_method: AuthMethod;
+    created_at: number;
+}
+export interface ApiKeyCredential extends BaseCredential {
+    auth_method: 'api_key';
+    api_key: string;
+}
+export interface SetupTokenCredential extends BaseCredential {
+    auth_method: 'setup_token';
+    setup_token: string;
+}
+export interface OAuthCredential extends BaseCredential {
+    auth_method: 'oauth';
+    access_token: string;
+    refresh_token?: string;
+    expires_at?: number;
+    token_type?: string;
+    scope?: string;
+    email?: string;
+    client_id?: string;
+}
+export type AuthCredential = ApiKeyCredential | SetupTokenCredential | OAuthCredential;
+export declare function readAuthCredential(provider: string): Promise<AuthCredential | null>;
+export declare function writeAuthCredential(credential: AuthCredential): Promise<void>;
+export declare function removeAuthCredential(provider: string): Promise<boolean>;
+export interface AuthStatus {
+    provider: string;
+    authenticated: boolean;
+    method?: AuthMethod;
+    source?: 'env' | 'auth_file' | 'legacy_env';
+    expires_at?: number;
+    expired?: boolean;
+}
+export declare function getAuthStatus(provider: string): Promise<AuthStatus>;
+export declare function getAllAuthStatuses(): Promise<AuthStatus[]>;
+export interface ResolvedAuth {
+    token: string;
+    method: AuthMethod;
+    source: 'env' | 'auth_file';
+}
+/**
+ * Resolve the effective API key or access token for a provider.
+ * Returns null if no auth is available.
+ */
+export declare function resolveAuthToken(provider: string): Promise<string | null>;
+/**
+ * Resolve auth with method metadata so callers know whether to use
+ * the token as an API key or a Bearer token.
+ */
+export declare function resolveAuth(provider: string): Promise<ResolvedAuth | null>;
+export declare function isTokenExpired(cred: OAuthCredential): boolean;
+export declare function isTokenNearExpiry(cred: OAuthCredential): boolean;
+//# sourceMappingURL=storage.d.ts.map

package/dist/auth/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,WAAW,EAAE,SAAS,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,WAAW,EAAE,aAAa,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAcvF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAUzF;AAED,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU7E;AAID,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,KAAK,GAAG,WAAW,GAAG,YAAY,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AASD,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BzE;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAmBhE;AAID,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,KAAK,GAAG,WAAW,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG/E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CA2BhF;AAID,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAI7D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAIhE"}

package/dist/auth/storage.js

@@ -0,0 +1,157 @@
+/**
+ * Auth storage — read/write provider credentials to ~/.tako/auth/<provider>.json
+ *
+ * Supports multiple auth methods per provider:
+ *   - api_key: traditional API key
+ *   - setup_token: Anthropic subscription setup token
+ *   - oauth: OAuth2 access/refresh tokens (OpenAI Codex, etc.)
+ *
+ * Resolution order:
+ *   1. Environment variables (highest priority)
+ *   2. Auth files (~/.tako/auth/<provider>.json)
+ *   3. Legacy .env file (~/.tako/.env)
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, readFile, writeFile, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+// ─── Auth directory ─────────────────────────────────────────────────
+function getAuthDir() {
+    return join(homedir(), '.tako', 'auth');
+}
+function getAuthFilePath(provider) {
+    return join(getAuthDir(), `${provider}.json`);
+}
+// ─── Read / Write ───────────────────────────────────────────────────
+export async function readAuthCredential(provider) {
+    const filePath = getAuthFilePath(provider);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = await readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeAuthCredential(credential) {
+    const authDir = getAuthDir();
+    await mkdir(authDir, { recursive: true });
+    const filePath = getAuthFilePath(credential.provider);
+    await writeFile(filePath, JSON.stringify(credential, null, 2) + '\n', { mode: 0o600 });
+}
+export async function removeAuthCredential(provider) {
+    const filePath = getAuthFilePath(provider);
+    if (!existsSync(filePath))
+        return false;
+    try {
+        await unlink(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Env vars to check for each provider. */
+const PROVIDER_ENV_VARS = {
+    anthropic: ['ANTHROPIC_API_KEY', 'ANTHROPIC_API_KEYS', 'OPENCLAW_LIVE_ANTHROPIC_KEY'],
+    openai: ['OPENAI_API_KEY'],
+    litellm: ['LITELLM_API_KEY'],
+};
+export async function getAuthStatus(provider) {
+    // 1. Check env vars
+    const envVars = PROVIDER_ENV_VARS[provider] ?? [`${provider.toUpperCase()}_API_KEY`];
+    for (const envVar of envVars) {
+        if (process.env[envVar]) {
+            return { provider, authenticated: true, method: 'api_key', source: 'env' };
+        }
+    }
+    // 2. Check auth file
+    const cred = await readAuthCredential(provider);
+    if (cred) {
+        const expired = cred.auth_method === 'oauth' && cred.expires_at
+            ? cred.expires_at < Date.now() / 1000
+            : false;
+        return {
+            provider,
+            authenticated: !expired,
+            method: cred.auth_method,
+            source: 'auth_file',
+            expires_at: cred.auth_method === 'oauth' ? cred.expires_at : undefined,
+            expired,
+        };
+    }
+    return { provider, authenticated: false };
+}
+export async function getAllAuthStatuses() {
+    const providers = ['anthropic', 'openai', 'litellm'];
+    // Also check for any auth files for providers not in the default list
+    const authDir = getAuthDir();
+    if (existsSync(authDir)) {
+        const { readdir } = await import('node:fs/promises');
+        const files = await readdir(authDir);
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const name = file.replace('.json', '');
+                if (!providers.includes(name)) {
+                    providers.push(name);
+                }
+            }
+        }
+    }
+    return Promise.all(providers.map(getAuthStatus));
+}
+/**
+ * Resolve the effective API key or access token for a provider.
+ * Returns null if no auth is available.
+ */
+export async function resolveAuthToken(provider) {
+    const resolved = await resolveAuth(provider);
+    return resolved?.token ?? null;
+}
+/**
+ * Resolve auth with method metadata so callers know whether to use
+ * the token as an API key or a Bearer token.
+ */
+export async function resolveAuth(provider) {
+    // 1. Env vars first
+    const envVars = PROVIDER_ENV_VARS[provider] ?? [`${provider.toUpperCase()}_API_KEY`];
+    for (const envVar of envVars) {
+        if (process.env[envVar]) {
+            return { token: process.env[envVar], method: 'api_key', source: 'env' };
+        }
+    }
+    // 2. Auth file
+    const cred = await readAuthCredential(provider);
+    if (!cred)
+        return null;
+    switch (cred.auth_method) {
+        case 'api_key':
+            return { token: cred.api_key, method: 'api_key', source: 'auth_file' };
+        case 'setup_token':
+            return { token: cred.setup_token, method: 'setup_token', source: 'auth_file' };
+        case 'oauth': {
+            // Check if expired
+            if (cred.expires_at && cred.expires_at < Date.now() / 1000) {
+                // Token expired — caller should refresh
+                return null;
+            }
+            return { token: cred.access_token, method: 'oauth', source: 'auth_file' };
+        }
+    }
+}
+// ─── Token validity helpers ─────────────────────────────────────────
+export function isTokenExpired(cred) {
+    if (!cred.expires_at)
+        return false;
+    // Consider expired if within 5 minutes of expiry
+    return cred.expires_at < (Date.now() / 1000) + 300;
+}
+export function isTokenNearExpiry(cred) {
+    if (!cred.expires_at)
+        return false;
+    // Near expiry = within 10 minutes
+    return cred.expires_at < (Date.now() / 1000) + 600;
+}
+//# sourceMappingURL=storage.js.map

package/dist/auth/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"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"}

package/dist/cache/file-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * File Content Cache — in-memory LRU cache for file reads.
+ *
+ * Validates entries using mtime + sha256 hash to detect stale content.
+ * Automatically evicts least-recently-used entries when maxSizeBytes is exceeded.
+ */
+import type { FileCacheConfig } from '../config/schema.js';
+export interface FileCacheEntry {
+    content: string;
+    size: number;
+    mtimeMs: number;
+    hash: string;
+    lastAccessed: number;
+}
+export interface FileCacheStats {
+    entries: number;
+    totalBytes: number;
+    maxBytes: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    hitRate: number;
+}
+export declare class FileCache {
+    private config;
+    private cache;
+    private totalBytes;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(config: FileCacheConfig);
+    /**
+     * Get cached file content if valid, or null if stale/missing.
+     */
+    get(path: string): Promise<string | null>;
+    /**
+     * Store file content in cache with mtime and hash validation.
+     */
+    set(path: string, content: string): Promise<void>;
+    /**
+     * Invalidate a cached file (e.g. after a write).
+     */
+    invalidate(path: string): void;
+    /**
+     * Invalidate all entries under a directory prefix.
+     */
+    invalidateDir(dirPath: string): void;
+    /**
+     * Clear the entire cache.
+     */
+    clear(): void;
+    /**
+     * Run auto-clean: evict entries not accessed recently.
+     * Called periodically by the CacheManager.
+     */
+    autoClean(maxAgeMs?: number): number;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): FileCacheStats;
+    /**
+     * Reset counters (for testing).
+     */
+    resetStats(): void;
+    private remove;
+    private evictLRU;
+}
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/cache/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../src/cache/file-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAAK;gBAEV,MAAM,EAAE,eAAe;IAInC;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8B/C;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CvD;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IASpC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,SAAS,CAAC,QAAQ,SAAgB,GAAG,MAAM;IAY3C;;OAEG;IACH,QAAQ,IAAI,cAAc;IAa1B;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,QAAQ;CAcjB"}

package/dist/cache/file-cache.js

@@ -0,0 +1,176 @@
+/**
+ * File Content Cache — in-memory LRU cache for file reads.
+ *
+ * Validates entries using mtime + sha256 hash to detect stale content.
+ * Automatically evicts least-recently-used entries when maxSizeBytes is exceeded.
+ */
+import { stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+// ─── File Content Cache ─────────────────────────────────────────────
+export class FileCache {
+    config;
+    cache = new Map();
+    totalBytes = 0;
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get cached file content if valid, or null if stale/missing.
+     */
+    async get(path) {
+        if (!this.config.enabled)
+            return null;
+        const entry = this.cache.get(path);
+        if (!entry) {
+            this.misses++;
+            return null;
+        }
+        // Validate mtime — if file changed on disk, invalidate
+        try {
+            const st = await stat(path);
+            if (st.mtimeMs !== entry.mtimeMs) {
+                this.remove(path);
+                this.misses++;
+                return null;
+            }
+        }
+        catch {
+            // File gone — remove from cache
+            this.remove(path);
+            this.misses++;
+            return null;
+        }
+        // Cache hit — update access time
+        entry.lastAccessed = Date.now();
+        this.hits++;
+        return entry.content;
+    }
+    /**
+     * Store file content in cache with mtime and hash validation.
+     */
+    async set(path, content) {
+        if (!this.config.enabled)
+            return;
+        const size = Buffer.byteLength(content, 'utf-8');
+        // Skip files larger than max single file size
+        if (size > this.config.maxFileSizeBytes)
+            return;
+        // Get file mtime
+        let mtimeMs;
+        try {
+            const st = await stat(path);
+            mtimeMs = st.mtimeMs;
+        }
+        catch {
+            return; // Can't stat — don't cache
+        }
+        const hash = createHash('sha256').update(content).digest('hex');
+        // Remove existing entry first (to update totalBytes correctly)
+        if (this.cache.has(path)) {
+            this.remove(path);
+        }
+        // Evict LRU entries until we have space
+        while (this.totalBytes + size > this.config.maxSizeBytes && this.cache.size > 0) {
+            this.evictLRU();
+        }
+        // If single file is bigger than the entire budget, skip
+        if (size > this.config.maxSizeBytes)
+            return;
+        this.cache.set(path, {
+            content,
+            size,
+            mtimeMs,
+            hash,
+            lastAccessed: Date.now(),
+        });
+        this.totalBytes += size;
+    }
+    /**
+     * Invalidate a cached file (e.g. after a write).
+     */
+    invalidate(path) {
+        this.remove(path);
+    }
+    /**
+     * Invalidate all entries under a directory prefix.
+     */
+    invalidateDir(dirPath) {
+        const prefix = dirPath.endsWith('/') ? dirPath : dirPath + '/';
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.remove(key);
+            }
+        }
+    }
+    /**
+     * Clear the entire cache.
+     */
+    clear() {
+        this.cache.clear();
+        this.totalBytes = 0;
+    }
+    /**
+     * Run auto-clean: evict entries not accessed recently.
+     * Called periodically by the CacheManager.
+     */
+    autoClean(maxAgeMs = 5 * 60 * 1000) {
+        const cutoff = Date.now() - maxAgeMs;
+        let cleaned = 0;
+        for (const [path, entry] of this.cache) {
+            if (entry.lastAccessed < cutoff) {
+                this.remove(path);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            entries: this.cache.size,
+            totalBytes: this.totalBytes,
+            maxBytes: this.config.maxSizeBytes,
+            hits: this.hits,
+            misses: this.misses,
+            evictions: this.evictions,
+            hitRate: total > 0 ? this.hits / total : 0,
+        };
+    }
+    /**
+     * Reset counters (for testing).
+     */
+    resetStats() {
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+    }
+    // ─── Private ────────────────────────────────────────────────────
+    remove(path) {
+        const entry = this.cache.get(path);
+        if (entry) {
+            this.totalBytes -= entry.size;
+            this.cache.delete(path);
+        }
+    }
+    evictLRU() {
+        let oldest = null;
+        let oldestTime = Infinity;
+        for (const [path, entry] of this.cache) {
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldest = path;
+            }
+        }
+        if (oldest) {
+            this.remove(oldest);
+            this.evictions++;
+        }
+    }
+}
+//# sourceMappingURL=file-cache.js.map

package/dist/cache/file-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.js","sourceRoot":"","sources":["../../src/cache/file-cache.ts"],"names":[],"mappings":"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"}

package/dist/cache/manager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Cache Manager — orchestrates all cache layers.
+ *
+ * Provides a unified interface for:
+ * - Auto-clean intervals across all layers
+ * - Combined status/stats
+ * - Per-layer or global clear
+ * - File write invalidation hooks
+ */
+import type { CacheConfig } from '../config/schema.js';
+import { FileCache, type FileCacheStats } from './file-cache.js';
+import { ToolCache, type ToolCacheStats } from './tool-cache.js';
+import { SymbolIndex, type SymbolIndexStats } from './symbol-index.js';
+export type CacheLayer = 'file' | 'tool' | 'symbols';
+export interface CacheStatus {
+    enabled: boolean;
+    file: FileCacheStats;
+    tool: ToolCacheStats;
+    symbols: SymbolIndexStats;
+}
+export declare class CacheManager {
+    readonly file: FileCache;
+    readonly tool: ToolCache;
+    readonly symbols: SymbolIndex;
+    private config;
+    private cleanTimer;
+    constructor(config: CacheConfig);
+    /**
+     * Start the auto-clean interval.
+     */
+    startAutoClean(): void;
+    /**
+     * Stop the auto-clean interval.
+     */
+    stopAutoClean(): void;
+    /**
+     * Run auto-clean on all layers.
+     */
+    autoClean(): {
+        file: number;
+        tool: number;
+    };
+    /**
+     * Clear a specific layer or all layers.
+     */
+    clear(layer?: CacheLayer): void;
+    /**
+     * Get combined status from all layers.
+     */
+    getStatus(): CacheStatus;
+    /**
+     * Notify all layers that a file was written/modified.
+     * Invalidates file cache entry and marks tool cache as potentially stale.
+     */
+    onFileWrite(filePath: string): void;
+    /**
+     * Persist symbol index to disk.
+     */
+    persistSymbols(): Promise<void>;
+    /**
+     * Load symbol index from disk.
+     */
+    loadSymbols(): Promise<number>;
+    /**
+     * Dispose: stop timers, persist symbols.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/cache/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/cache/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAIvE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAID,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,UAAU,CAA+C;gBAErD,MAAM,EAAE,WAAW;IAO/B;;OAEG;IACH,cAAc,IAAI,IAAI;IActB;;OAEG;IACH,aAAa,IAAI,IAAI;IAOrB;;OAEG;IACH,SAAS,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAW3C;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI;IAM/B;;OAEG;IACH,SAAS,IAAI,WAAW;IASxB;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQnC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAIpC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAM/B"}