tuplet 2.7.0

package/dist/workspace.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Workspace - A virtual filesystem for agent communication
+ *
+ * Wraps a WorkspaceProvider. AI agents interact with workspace
+ * using bash-like commands (cat, echo, ls, grep, etc.) through the shell.
+ *
+ * All paths are relative — absolute paths (starting with /) are not allowed.
+ *
+ * Usage:
+ * ```typescript
+ * const workspace = new Workspace({
+ *   paths: {
+ *     'user/preferences.json': { value: { theme: 'dark' } }
+ *   }
+ * })
+ *
+ * // Get the shell for AI to use
+ * const shell = workspace.getShell()
+ *
+ * // AI uses bash commands:
+ * // cat user/preferences.json
+ * // echo '{"theme": "light"}' > user/preferences.json
+ * // ls
+ * // grep "theme" user/preferences.json
+ *
+ * // Read results after run
+ * const prefs = await workspace.read('user/preferences.json')
+ * ```
+ */
+import type { JSONSchema, EnvironmentProvider } from './types.js';
+import { Shell } from './shell/shell.js';
+import type { ShellConfig } from './shell/types.js';
+import type { WorkspaceProvider } from './providers/workspace/types.js';
+export interface WorkspaceEntry {
+    value: unknown;
+    createdAt: number;
+    updatedAt: number;
+    /** Optional metadata about who wrote this entry */
+    writtenBy?: string;
+}
+export interface WorkspaceListItem {
+    path: string;
+    updatedAt: number;
+    writtenBy?: string;
+    /** Preview of value (for objects: type, for primitives: value) */
+    preview: string;
+}
+/** Custom validator function */
+export type ValidatorFn = (value: unknown) => ValidationError[] | null;
+/** Zod-like schema interface (duck typing to avoid hard dependency) */
+export interface ZodLike {
+    safeParse(value: unknown): {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: {
+            errors: Array<{
+                path: (string | number)[];
+                message: string;
+            }>;
+        };
+    };
+}
+/**
+ * Path configuration with optional validator and initial value
+ */
+export interface PathConfig {
+    /** Validator for this path (null = format validation only from extension) */
+    validator?: JSONSchema | ValidatorFn | ZodLike | null;
+    /** Initial value to populate */
+    value?: unknown;
+    /** Description shown to AI */
+    description?: string;
+}
+export interface WorkspaceConfig {
+    /**
+     * Strict mode: only allow writing to defined paths.
+     * - true: writes to undefined paths will fail
+     * - false (default): any path can be written to
+     */
+    strict?: boolean;
+    /**
+     * Path definitions with validators and optional initial values.
+     *
+     * Format extensions (basic validation from extension):
+     * - 'path/name.json' → validates valid JSON object/array
+     * - 'path/name.md' → validates string (markdown)
+     * - 'path/name.txt' → validates string
+     * - 'path/name.num' → validates number
+     * - 'path/name.bool' → validates boolean
+     *
+     * Values can be:
+     * - null → just format validation from extension
+     * - JSONSchema → schema validation
+     * - ValidatorFn → custom function
+     * - ZodLike → zod schema
+     * - PathConfig → { validator, value, description }
+     *
+     * @example
+     * ```typescript
+     * const workspace = new Workspace({
+     *   strict: true,
+     *   paths: {
+     *     // Format validation only
+     *     "notes.md": null,
+     *
+     *     // With initial value
+     *     "user.json": {
+     *       validator: { type: 'object', properties: { name: { type: 'string' } } },
+     *       value: { name: "Guest" }
+     *     },
+     *
+     *     // Just initial value, format validation from extension
+     *     "today/meals.json": { value: [] }
+     *   }
+     * })
+     * ```
+     */
+    paths?: Record<string, JSONSchema | ValidatorFn | ZodLike | PathConfig | null>;
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+    expected?: string;
+    received?: string;
+}
+export interface WriteResult {
+    success: boolean;
+    errors?: ValidationError[];
+}
+/** Supported format extensions */
+type FormatExt = 'json' | 'md' | 'txt' | 'num' | 'bool';
+type SchemaExt = 'schema' | 'zod' | 'validate';
+type ValidatorType = FormatExt | SchemaExt;
+export interface WorkspaceConfigExt extends WorkspaceConfig {
+    /** Shell configuration for HTTP requests */
+    shell?: ShellConfig;
+    /** Async persistence provider */
+    provider?: WorkspaceProvider;
+}
+/**
+ * Workspace provides a virtual filesystem for agent communication.
+ * Uses WorkspaceProvider directly and provides Shell access for AI to use bash commands.
+ */
+export declare class Workspace {
+    private provider;
+    private shell;
+    private validators;
+    private definedPaths;
+    private strict;
+    private initialized;
+    private unsubscribe;
+    /** Extension to type mapping */
+    private static readonly EXT_MAP;
+    constructor(config?: WorkspaceConfigExt);
+    /**
+     * Get the shell instance for AI to execute bash commands.
+     * AI uses: cat, echo, ls, grep, find, curl, jq, etc.
+     */
+    getShell(): Shell;
+    /**
+     * Set environment provider for secure variable resolution in the shell.
+     * Variables are resolved at execution time — values never appear in conversation history.
+     */
+    setEnvProvider(provider: EnvironmentProvider): void;
+    /**
+     * Get the underlying WorkspaceProvider
+     */
+    getProvider(): WorkspaceProvider;
+    /**
+     * Initialize the workspace.
+     * Sets up real-time subscriptions if the provider supports them.
+     * No-op when no provider subscription is available.
+     */
+    init(): Promise<void>;
+    /**
+     * Dispose the workspace provider.
+     * Unsubscribes, flushes pending writes, and disposes the provider.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Check if strict mode is enabled
+     */
+    isStrict(): boolean;
+    /**
+     * Check if a path is defined (registered)
+     */
+    isDefined(path: string): boolean;
+    /**
+     * Get all defined paths
+     */
+    getDefinedPaths(): string[];
+    /**
+     * Register a path with optional validator and initial value
+     */
+    registerPath(path: string, config: JSONSchema | ValidatorFn | ZodLike | PathConfig | null): void;
+    /**
+     * Set validator for a path
+     */
+    private setValidator;
+    /** Parse path and extension */
+    private parsePathExt;
+    /** Check if extension is a format type */
+    private isFormatExt;
+    /** Check if value looks like a Zod schema */
+    private isZodLike;
+    /**
+     * Write a value to the workspace at the given path
+     *
+     * @param path - Path (e.g., 'meals.today', 'user/preferences')
+     * @param value - Any JSON-serializable value
+     * @param _writtenBy - Optional identifier of who wrote this (unused, kept for API compatibility)
+     * @returns WriteResult with success status and any validation errors
+     */
+    write(path: string, value: unknown, _writtenBy?: string): WriteResult;
+    /**
+     * Get validator info for a path
+     */
+    getValidator(path: string): {
+        type: ValidatorType;
+        schema?: JSONSchema;
+        description?: string;
+    } | undefined;
+    /**
+     * Get schema for a path (if JSON schema validator)
+     */
+    getSchema(path: string): JSONSchema | undefined;
+    /**
+     * Get validator description for a path
+     */
+    getValidatorDescription(path: string): string | undefined;
+    /**
+     * Get all paths with validators
+     */
+    getValidatorPaths(): string[];
+    /**
+     * Validate a value against a JSON schema
+     */
+    private validateSchema;
+    /**
+     * Validate a single property
+     */
+    private validateProperty;
+    /**
+     * Validate a value using Zod schema
+     */
+    private validateZod;
+    /**
+     * Validate a value against a format extension
+     */
+    private validateFormat;
+    /**
+     * Read a value from the workspace
+     *
+     * @param path - Path to read from (with or without / prefix)
+     * @returns The value, or undefined if not found
+     */
+    read<T = unknown>(path: string): Promise<T | undefined>;
+    /**
+     * Check if a path exists in the workspace
+     */
+    has(path: string): Promise<boolean>;
+    /**
+     * Delete a path from the workspace
+     */
+    delete(path: string): Promise<boolean>;
+    /**
+     * List all paths, optionally filtered by prefix
+     */
+    list(prefix?: string): Promise<WorkspaceListItem[]>;
+    /**
+     * Get all paths (just the keys, no metadata)
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clear all data from the workspace
+     */
+    clear(): Promise<void>;
+    /**
+     * Get number of entries
+     */
+    getSize(): Promise<number>;
+    private getPreview;
+}
+export {};
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

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