@dbx-tools/appkit-mastra 0.9.74 → 0.9.79

package/lib/src/skill-cache.d.ts

@@ -1,70 +1,94 @@
 /**
- * AppKit-backed caching for Databricks workspace skill mounts.
+ * User-scoped workspace skill catalogues cached as one semantic record.
  *
  * @module
  */
-import type { CopyOptions, FileContent, FileEntry, FileStat, FileSystem, ListOptions, MakeDirectoryOptions, ReadFileOptions, RemoveOptions, WriteFileOptions } from "@dbx-tools/shared-fs";
-import { type MastraFileSystemAdapter } from "./filesystems.ts";
-/** Default remote skill metadata and content cache lifetime. */
-export declare const DEFAULT_WORKSPACE_SKILL_CACHE_TTL_MS: number;
-/** Options for one AppKit-cached workspace skill filesystem. */
-export interface AppKitCachedFileSystemOptions {
+import type { RequestContext } from "@mastra/core/request-context";
+import { z } from "zod";
+declare const SkillCatalogueEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    instructions: z.ZodString;
+    sourceId: z.ZodString;
+    sourcePath: z.ZodString;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const SkillCatalogueSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generatedAt: z.ZodString;
+    roots: z.ZodArray<z.ZodString>;
+    skills: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        instructions: z.ZodString;
+        sourceId: z.ZodString;
+        sourcePath: z.ZodString;
+        signature: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Parsed skill retained in a materialized workspace catalogue. */
+export type SkillCatalogueEntry = z.infer<typeof SkillCatalogueEntrySchema>;
+/** Versioned persisted skill catalogue. */
+export type SkillCatalogue = z.infer<typeof SkillCatalogueSchema>;
+/** One ordered filesystem root contributing skills to a catalogue. */
+export interface SkillCatalogueSource {
+    /** Stable source identity including its mount precedence. */
+    id: string;
+    /** List one source-relative directory with provider metadata when available. */
+    list(path: string): Promise<SkillCatalogueFileEntry[]>;
+    /** Read one source-relative file fresh from its owning filesystem. */
+    read(path: string): Promise<string>;
+}
+/** Minimal directory metadata used to compare one catalogue refresh. */
+export interface SkillCatalogueFileEntry {
+    metadata?: Readonly<Record<string, unknown>>;
+    name: string;
+    size?: number;
+    type: "directory" | "file";
+}
+/** Options for one user-scoped workspace skill catalogue. */
+export interface WorkspaceSkillCatalogueOptions {
     host: string;
-    source: FileSystem;
+    sources: readonly SkillCatalogueSource[];
     ttlMs?: number;
     userKey: string;
 }
-/** Stable Mastra mount plus the identity key used for source reuse. */
-export interface CachedWorkspaceSkillMount {
-    cacheKey: string;
-    filesystem: MastraFileSystemAdapter;
+/** Request state used to resolve one user-scoped catalogue owner. */
+export interface SkillCatalogueResolveContext {
+    abortSignal?: AbortSignal;
+    requestContext?: RequestContext;
 }
-/**
- * Cache read-only filesystem operations through AppKit while delegating
- * mutations to the current request's source.
- */
-export declare class AppKitCachedFileSystem implements FileSystem<"appkit-cache"> {
-    readonly backend: "appkit-cache";
-    readonly id: string;
-    readonly readOnly: boolean;
-    readonly root: string;
-    private source;
-    private readonly host;
-    private readonly ttlSec;
-    private readonly userKey;
-    constructor(options: AppKitCachedFileSystemOptions);
-    /** Rebind cache misses and writes to the current request's OBO filesystem. */
-    bind(source: FileSystem): void;
-    init(): Promise<void>;
-    /** Keep the shared scope alive when one request releases its workspace view. */
-    close(): Promise<void>;
-    resolvePath(inputPath: string): string;
-    readFile(inputPath: string): Promise<Uint8Array>;
-    readFile(inputPath: string, options: ReadFileOptions & {
-        encoding: string;
-    }): Promise<string>;
-    writeFile(inputPath: string, content: FileContent, options?: WriteFileOptions): Promise<void>;
-    appendFile(inputPath: string, content: FileContent): Promise<void>;
-    deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
-    copyFile(sourcePath: string, destinationPath: string, options?: CopyOptions): Promise<void>;
-    moveFile(sourcePath: string, destinationPath: string, options?: CopyOptions): Promise<void>;
-    mkdir(inputPath: string, options?: MakeDirectoryOptions): Promise<void>;
-    rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
-    readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]>;
-    exists(inputPath: string): Promise<boolean>;
-    stat(inputPath: string): Promise<FileStat>;
-    /** Rotate this scope's cache generation so the next read reloads it. */
+/** Resolve one request's complete skill catalogue. */
+export type SkillCatalogueResolver = (context: SkillCatalogueResolveContext) => Promise<WorkspaceSkillCatalogue>;
+/** Default lifetime for one complete workspace skill catalogue. */
+export declare const DEFAULT_WORKSPACE_SKILL_CACHE_TTL_MS: number;
+/** Materialized catalogue with one AppKit cache record and fresh auxiliary reads. */
+export declare class WorkspaceSkillCatalogue {
+    private readonly options;
+    readonly cacheKey: string;
+    readonly host: string;
+    readonly userKey: string;
+    private lastValid?;
+    private readonly ttlMs;
+    private sources;
+    constructor(options: WorkspaceSkillCatalogueOptions);
+    /** Rebind refreshes and lazy reads to the current request's filesystem clients. */
+    bind(sources: readonly SkillCatalogueSource[]): void;
+    /** Return the cached catalogue, refreshing all roots once on cache miss. */
+    get(signal?: AbortSignal): Promise<SkillCatalogue>;
+    /** Expire this complete catalogue without touching unrelated cache entries. */
     invalidate(): Promise<void>;
-    private cached;
-    private generation;
-    private generationKey;
-    private mutate;
+    /** Read one selected skill's auxiliary file directly from its current source. */
+    readSkillFile(skillName: string, inputPath: string, signal?: AbortSignal): Promise<string>;
+    private refresh;
+    private rootKey;
+    private persistentKey;
 }
-/** Return one stable Mastra mount per resolved user, host, and source root. */
-export declare function cachedWorkspaceSkillMount(options: AppKitCachedFileSystemOptions): CachedWorkspaceSkillMount;
-/** Invalidate one user's cached workspace skill scope. */
+/** Return one stable catalogue owner for a user, host, and ordered root set. */
+export declare function workspaceSkillCatalogue(options: WorkspaceSkillCatalogueOptions): WorkspaceSkillCatalogue;
+/** Invalidate matching complete catalogues and retain their stable owners. */
 export declare function clearWorkspaceSkillCache(options: {
     host: string;
-    root?: string;
-    userKey: string;
+    userKey?: string;
 }): Promise<void>;
+export {};