@dpantani/tdmcp 0.1.0 → 0.3.0

package/dist/cli/agent.d.ts

@@ -7,6 +7,12 @@ interface Logger {
     error(message: string, meta?: Record<string, unknown>): void;
 }
 
+interface TdEvent {
+    event: string;
+    data?: unknown;
+}
+type TdEventHandler = (event: TdEvent) => void;
+
 interface OperatorParameter {
     name: string;
     label?: string;
@@ -201,6 +207,38 @@ declare class KnowledgeBase {
     stats(): KnowledgeStats;
 }
 
+interface ParsedNote {
+    /** Parsed YAML frontmatter (empty object when the note has none). */
+    data: Record<string, unknown>;
+    /** Markdown body with the frontmatter stripped. */
+    body: string;
+}
+
+/**
+ * A thin, safe wrapper over an Obsidian vault (a folder of markdown files on the
+ * local filesystem). Every path is resolved relative to the vault root and is
+ * refused if it escapes that root, so user-supplied note names cannot reach
+ * outside the vault.
+ */
+declare class Vault {
+    readonly root: string;
+    private readonly logger;
+    constructor(root: string, logger?: Logger);
+    /** Resolves a vault-relative path, throwing if it would escape the vault root. */
+    resolve(relPath: string): string;
+    exists(relPath: string): boolean;
+    read(relPath: string): string;
+    write(relPath: string, content: string): void;
+    writeBinary(relPath: string, data: Buffer): void;
+    ensureDir(relPath: string): void;
+    /** Lists file names directly inside `subdir`, optionally filtered by extension. */
+    list(subdir: string, ext?: string): string[];
+    /** Reads a markdown note and splits its frontmatter from its body. */
+    readNote(relPath: string): ParsedNote;
+    /** Writes a markdown note from frontmatter data + body. */
+    writeNote(relPath: string, data: Record<string, unknown>, body: string): void;
+}
+
 declare const RecipeSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -252,6 +290,24 @@ declare const RecipeSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     glsl_code: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     python_code: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    controls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            string: "string";
+            int: "int";
+            float: "float";
+            toggle: "toggle";
+            menu: "menu";
+            rgb: "rgb";
+            pulse: "pulse";
+        }>>;
+        label: z.ZodOptional<z.ZodString>;
+        min: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        max: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+        menu_items: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bind_to: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
     preview_description: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 type Recipe = z.infer<typeof RecipeSchema>;
@@ -266,11 +322,14 @@ interface RecipeSummary {
 interface RecipeLibraryOptions {
     dir?: string;
     logger?: Logger;
+    /** Optional Obsidian vault; recipes in `<vault>/Recipes/*.md` are merged in (and override built-ins by id). */
+    vault?: Vault;
 }
-/** Loads and validates recipe JSON files from the recipes directory. */
+/** Loads and validates recipe JSON files from the recipes directory, plus any vault recipes. */
 declare class RecipeLibrary {
     private readonly dir;
     private readonly logger;
+    private readonly vault?;
     private cache?;
     constructor(options?: RecipeLibraryOptions);
     private load;
@@ -320,6 +379,16 @@ interface TouchDesignerClientOptions {
     token?: string;
     /** Overridable for tests (defaults to global `fetch`). */
     fetchImpl?: typeof fetch;
+    /**
+     * Extra attempts for a transient connection failure on an **idempotent** (GET)
+     * request — e.g. TD briefly stalls mid-build. Default 2 (so up to 3 tries).
+     * Only `TdConnectionError` is retried; timeouts and bridge errors are not (a
+     * timeout may mean the request was received, and non-GET methods aren't safe
+     * to repeat). Set 0 to disable.
+     */
+    retries?: number;
+    /** Base backoff between retries, in ms (linear: delay × attempt). Default 150. */
+    retryDelayMs?: number;
 }
 /**
  * HTTP client for the TouchDesigner REST bridge. Every method maps to one of the
@@ -332,9 +401,12 @@ declare class TouchDesignerClient {
     private readonly logger;
     private readonly token;
     private readonly fetchImpl;
+    private readonly retries;
+    private readonly retryDelayMs;
     constructor(options: TouchDesignerClientOptions);
     get endpoint(): string;
     private request;
+    private attemptRequest;
     getInfo(): Promise<{
         td_version?: string | undefined;
         python_version?: string | undefined;
@@ -346,6 +418,7 @@ declare class TouchDesignerClient {
         path: string;
         type: string;
         name: string;
+        parameter_warnings?: string[] | undefined;
     }>;
     deleteNode(path: string): Promise<{
         deleted: string;
@@ -355,6 +428,7 @@ declare class TouchDesignerClient {
             path: string;
             type: string;
             name: string;
+            parameter_warnings?: string[] | undefined;
         }[];
     }>;
     getNode(path: string): Promise<{
@@ -362,6 +436,7 @@ declare class TouchDesignerClient {
         type: string;
         name: string;
         parameters: Record<string, unknown>;
+        parameter_warnings?: string[] | undefined;
         inputs?: string[] | undefined;
         outputs?: string[] | undefined;
         family?: string | undefined;
@@ -372,6 +447,7 @@ declare class TouchDesignerClient {
         type: string;
         name: string;
         parameters: Record<string, unknown>;
+        parameter_warnings?: string[] | undefined;
         inputs?: string[] | undefined;
         outputs?: string[] | undefined;
         family?: string | undefined;
@@ -420,6 +496,7 @@ declare class TouchDesignerClient {
             path: string;
             type: string;
             name: string;
+            parameter_warnings?: string[] | undefined;
         }[];
         connections: {
             source_path: string;
@@ -428,7 +505,7 @@ declare class TouchDesignerClient {
             target_input: number;
         }[];
     }>;
-    getNetworkPerformance(path: string): Promise<{
+    getNetworkPerformance(path: string, recursive?: boolean): Promise<{
         nodes: {
             path: string;
             cook_time_ms: number;
@@ -445,6 +522,8 @@ interface ToolContext {
     knowledge: KnowledgeBase;
     recipes: RecipeLibrary;
     logger: Logger;
+    /** Optional Obsidian vault (set via TDMCP_VAULT_PATH); undefined when not configured. */
+    vault?: Vault;
     /**
      * Whether the raw Python escape-hatch tools may be registered. Undefined means
      * allowed (the default); only an explicit `false` locks them out.
@@ -452,6 +531,39 @@ interface ToolContext {
     allowRawPython?: boolean;
 }
 
+declare const ConfigSchema: z.ZodObject<{
+    tdHost: z.ZodDefault<z.ZodString>;
+    tdPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    transport: z.ZodDefault<z.ZodEnum<{
+        stdio: "stdio";
+        http: "http";
+    }>>;
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        silent: "silent";
+    }>>;
+    requestTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    httpPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    events: z.ZodDefault<z.ZodEnum<{
+        on: "on";
+        off: "off";
+    }>>;
+    rawPython: z.ZodDefault<z.ZodEnum<{
+        on: "on";
+        off: "off";
+    }>>;
+    bridgeToken: z.ZodOptional<z.ZodString>;
+    llmBaseUrl: z.ZodDefault<z.ZodString>;
+    llmModel: z.ZodDefault<z.ZodString>;
+    llmApiKey: z.ZodOptional<z.ZodString>;
+    chatPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    vaultPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TdmcpConfig = z.infer<typeof ConfigSchema>;
+
 interface CliResult {
     stdout: string;
     stderr: string;
@@ -462,5 +574,29 @@ interface RunCliOptions {
     makeCtx?: () => ToolContext;
 }
 declare function runCli(argv: string[], opts?: RunCliOptions): Promise<CliResult>;
+interface RunWatchOptions {
+    config?: TdmcpConfig;
+    includeHighFrequency?: boolean;
+    /** Where each event line goes; defaults to stdout. Overridable for tests. */
+    write?: (line: string) => void;
+    /** Inject a stream factory for tests; defaults to a real `TdEventStream`. */
+    makeStream?: (args: {
+        url: string;
+        onEvent: TdEventHandler;
+        includeHighFrequency: boolean;
+    }) => {
+        start: () => void;
+        close: () => void;
+    };
+    /** Resolve the returned promise when aborted; defaults to listening for SIGINT. */
+    signal?: AbortSignal;
+}
+/**
+ * Streams TouchDesigner bridge events to stdout as ndjson until interrupted.
+ * Runs outside `runCli` because it is a long-lived stream, not a request/response.
+ */
+declare function runWatch(opts?: RunWatchOptions): Promise<void>;
+/** Interactive read-eval-print loop: each line is tokenized and run through runCli. */
+declare function runRepl(opts?: RunCliOptions): Promise<void>;
 
-export { type CliResult, type RunCliOptions, runCli };
+export { type CliResult, type RunCliOptions, type RunWatchOptions, runCli, runRepl, runWatch };