coding-agent-adapters 0.2.17 → 0.2.19

package/dist/index.d.cts

@@ -39,6 +39,31 @@ interface ModelRecommendations {
     /** Fastest/cheapest model for simple tasks */
     fast: string;
 }
+/**
+ * Describes a file that a coding agent CLI reads from the workspace.
+ * Orchestration systems use this to write instructions/config before spawning agents.
+ */
+interface AgentFileDescriptor {
+    /** File path relative to workspace root (e.g., "CLAUDE.md", ".aider.conf.yml") */
+    relativePath: string;
+    /** Human-readable description of what this file does */
+    description: string;
+    /** Whether the CLI reads this file automatically on startup */
+    autoLoaded: boolean;
+    /** File category */
+    type: 'memory' | 'config' | 'rules';
+    /** File format */
+    format: 'markdown' | 'yaml' | 'json' | 'text';
+}
+/**
+ * Options for writing a memory file into a workspace
+ */
+interface WriteMemoryOptions {
+    /** Custom file name override (default: adapter's primary memory file) */
+    fileName?: string;
+    /** Append to existing file instead of overwriting */
+    append?: boolean;
+}
 /**
  * Extended config with credentials and mode support
  */
@@ -69,6 +94,17 @@ declare abstract class BaseCodingAdapter extends BaseCLIAdapter {
      * Installation information for this CLI tool
      */
     abstract readonly installation: InstallationInfo;
+    /**
+     * Workspace files this CLI reads automatically.
+     * Orchestration systems use this to know where to write instructions/config
+     * before spawning an agent.
+     */
+    abstract getWorkspaceFiles(): AgentFileDescriptor[];
+    /**
+     * The primary memory file for this CLI (the one it reads for project instructions).
+     * Returns the relativePath of the first 'memory' type file from getWorkspaceFiles().
+     */
+    get memoryFilePath(): string;
     /**
      * Get credentials from config
      */
@@ -110,6 +146,16 @@ declare abstract class BaseCodingAdapter extends BaseCLIAdapter {
      * Extract the main content from CLI output, removing common artifacts
      */
     protected extractContent(output: string, promptPattern: RegExp): string;
+    /**
+     * Write content to this agent's memory file in a workspace.
+     * Creates parent directories as needed.
+     *
+     * @param workspacePath - Absolute path to the workspace root
+     * @param content - The memory/instructions content to write
+     * @param options - Optional: custom fileName, append mode
+     * @returns The absolute path of the written file
+     */
+    writeMemoryFile(workspacePath: string, content: string, options?: WriteMemoryOptions): Promise<string>;
 }
 
 /**
@@ -128,6 +174,7 @@ declare class ClaudeAdapter extends BaseCodingAdapter {
      * Explicit responseType: 'text' prevents the usesTuiMenus default from kicking in.
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(_credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -159,6 +206,7 @@ declare class GeminiAdapter extends BaseCodingAdapter {
      * Source: FolderTrustDialog.tsx, MultiFolderTrustDialog.tsx, CloudFreePrivacyNotice.tsx
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(_credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -196,6 +244,7 @@ declare class CodexAdapter extends BaseCodingAdapter {
      * Source: trust_directory.rs, update_prompt.rs, model_migration.rs, cwd_prompt.rs, chatwidget.rs, main.rs
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(_credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -244,6 +293,7 @@ declare class AiderAdapter extends BaseCodingAdapter {
      * Decline rules come first to override the generic accept patterns.
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -431,4 +481,4 @@ declare function checkAllAdapters(): Promise<PreflightResult[]>;
  */
 declare function printMissingAdapters(types?: AdapterType[]): Promise<void>;
 
-export { ADAPTER_TYPES, type AdapterPatterns, type AdapterType, type AgentCredentials, AiderAdapter, BaseCodingAdapter, ClaudeAdapter, CodexAdapter, type CodingAgentConfig, GeminiAdapter, type InstallationInfo, type ModelRecommendations, type PreflightResult, checkAdapters, checkAllAdapters, clearPatternCache, createAdapter, createAllAdapters, getBaselinePatterns, hasDynamicPatterns, loadPatterns, loadPatternsSync, preloadAllPatterns, printMissingAdapters };
+export { ADAPTER_TYPES, type AdapterPatterns, type AdapterType, type AgentCredentials, type AgentFileDescriptor, AiderAdapter, BaseCodingAdapter, ClaudeAdapter, CodexAdapter, type CodingAgentConfig, GeminiAdapter, type InstallationInfo, type ModelRecommendations, type PreflightResult, type WriteMemoryOptions, checkAdapters, checkAllAdapters, clearPatternCache, createAdapter, createAllAdapters, getBaselinePatterns, hasDynamicPatterns, loadPatterns, loadPatternsSync, preloadAllPatterns, printMissingAdapters };

package/dist/index.d.ts

@@ -39,6 +39,31 @@ interface ModelRecommendations {
     /** Fastest/cheapest model for simple tasks */
     fast: string;
 }
+/**
+ * Describes a file that a coding agent CLI reads from the workspace.
+ * Orchestration systems use this to write instructions/config before spawning agents.
+ */
+interface AgentFileDescriptor {
+    /** File path relative to workspace root (e.g., "CLAUDE.md", ".aider.conf.yml") */
+    relativePath: string;
+    /** Human-readable description of what this file does */
+    description: string;
+    /** Whether the CLI reads this file automatically on startup */
+    autoLoaded: boolean;
+    /** File category */
+    type: 'memory' | 'config' | 'rules';
+    /** File format */
+    format: 'markdown' | 'yaml' | 'json' | 'text';
+}
+/**
+ * Options for writing a memory file into a workspace
+ */
+interface WriteMemoryOptions {
+    /** Custom file name override (default: adapter's primary memory file) */
+    fileName?: string;
+    /** Append to existing file instead of overwriting */
+    append?: boolean;
+}
 /**
  * Extended config with credentials and mode support
  */
@@ -69,6 +94,17 @@ declare abstract class BaseCodingAdapter extends BaseCLIAdapter {
      * Installation information for this CLI tool
      */
     abstract readonly installation: InstallationInfo;
+    /**
+     * Workspace files this CLI reads automatically.
+     * Orchestration systems use this to know where to write instructions/config
+     * before spawning an agent.
+     */
+    abstract getWorkspaceFiles(): AgentFileDescriptor[];
+    /**
+     * The primary memory file for this CLI (the one it reads for project instructions).
+     * Returns the relativePath of the first 'memory' type file from getWorkspaceFiles().
+     */
+    get memoryFilePath(): string;
     /**
      * Get credentials from config
      */
@@ -110,6 +146,16 @@ declare abstract class BaseCodingAdapter extends BaseCLIAdapter {
      * Extract the main content from CLI output, removing common artifacts
      */
     protected extractContent(output: string, promptPattern: RegExp): string;
+    /**
+     * Write content to this agent's memory file in a workspace.
+     * Creates parent directories as needed.
+     *
+     * @param workspacePath - Absolute path to the workspace root
+     * @param content - The memory/instructions content to write
+     * @param options - Optional: custom fileName, append mode
+     * @returns The absolute path of the written file
+     */
+    writeMemoryFile(workspacePath: string, content: string, options?: WriteMemoryOptions): Promise<string>;
 }
 
 /**
@@ -128,6 +174,7 @@ declare class ClaudeAdapter extends BaseCodingAdapter {
      * Explicit responseType: 'text' prevents the usesTuiMenus default from kicking in.
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(_credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -159,6 +206,7 @@ declare class GeminiAdapter extends BaseCodingAdapter {
      * Source: FolderTrustDialog.tsx, MultiFolderTrustDialog.tsx, CloudFreePrivacyNotice.tsx
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(_credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -196,6 +244,7 @@ declare class CodexAdapter extends BaseCodingAdapter {
      * Source: trust_directory.rs, update_prompt.rs, model_migration.rs, cwd_prompt.rs, chatwidget.rs, main.rs
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(_credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -244,6 +293,7 @@ declare class AiderAdapter extends BaseCodingAdapter {
      * Decline rules come first to override the generic accept patterns.
      */
     readonly autoResponseRules: AutoResponseRule[];
+    getWorkspaceFiles(): AgentFileDescriptor[];
     getRecommendedModels(credentials?: AgentCredentials): ModelRecommendations;
     getCommand(): string;
     getArgs(config: SpawnConfig): string[];
@@ -431,4 +481,4 @@ declare function checkAllAdapters(): Promise<PreflightResult[]>;
  */
 declare function printMissingAdapters(types?: AdapterType[]): Promise<void>;
 
-export { ADAPTER_TYPES, type AdapterPatterns, type AdapterType, type AgentCredentials, AiderAdapter, BaseCodingAdapter, ClaudeAdapter, CodexAdapter, type CodingAgentConfig, GeminiAdapter, type InstallationInfo, type ModelRecommendations, type PreflightResult, checkAdapters, checkAllAdapters, clearPatternCache, createAdapter, createAllAdapters, getBaselinePatterns, hasDynamicPatterns, loadPatterns, loadPatternsSync, preloadAllPatterns, printMissingAdapters };
+export { ADAPTER_TYPES, type AdapterPatterns, type AdapterType, type AgentCredentials, type AgentFileDescriptor, AiderAdapter, BaseCodingAdapter, ClaudeAdapter, CodexAdapter, type CodingAgentConfig, GeminiAdapter, type InstallationInfo, type ModelRecommendations, type PreflightResult, type WriteMemoryOptions, checkAdapters, checkAllAdapters, clearPatternCache, createAdapter, createAllAdapters, getBaselinePatterns, hasDynamicPatterns, loadPatterns, loadPatternsSync, preloadAllPatterns, printMissingAdapters };

package/dist/index.js

@@ -1,3 +1,5 @@
+import { mkdir, appendFile, writeFile } from 'fs/promises';
+import { join, dirname } from 'path';
 import { BaseCLIAdapter } from 'pty-manager';
 
 // src/base-coding-adapter.ts
@@ -6,6 +8,17 @@ var BaseCodingAdapter = class extends BaseCLIAdapter {
    * Coding agent CLIs use TUI menus that require arrow-key navigation.
    */
   usesTuiMenus = true;
+  /**
+   * The primary memory file for this CLI (the one it reads for project instructions).
+   * Returns the relativePath of the first 'memory' type file from getWorkspaceFiles().
+   */
+  get memoryFilePath() {
+    const memoryFile = this.getWorkspaceFiles().find((f) => f.type === "memory");
+    if (!memoryFile) {
+      throw new Error(`${this.displayName} adapter has no memory file defined`);
+    }
+    return memoryFile.relativePath;
+  }
   /**
    * Get credentials from config
    */
@@ -99,6 +112,26 @@ Docs: ${this.installation.docsUrl}`
     content = content.trim();
     return content;
   }
+  /**
+   * Write content to this agent's memory file in a workspace.
+   * Creates parent directories as needed.
+   *
+   * @param workspacePath - Absolute path to the workspace root
+   * @param content - The memory/instructions content to write
+   * @param options - Optional: custom fileName, append mode
+   * @returns The absolute path of the written file
+   */
+  async writeMemoryFile(workspacePath, content, options) {
+    const relativePath = options?.fileName ?? this.memoryFilePath;
+    const fullPath = join(workspacePath, relativePath);
+    await mkdir(dirname(fullPath), { recursive: true });
+    if (options?.append) {
+      await appendFile(fullPath, content, "utf-8");
+    } else {
+      await writeFile(fullPath, content, "utf-8");
+    }
+    return fullPath;
+  }
 };
 
 // src/claude-adapter.ts
@@ -171,6 +204,31 @@ var ClaudeAdapter = class extends BaseCodingAdapter {
       safe: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: "CLAUDE.md",
+        description: "Project-level instructions read automatically on startup",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".claude/settings.json",
+        description: "Project-scoped settings (allowed tools, permissions)",
+        autoLoaded: true,
+        type: "config",
+        format: "json"
+      },
+      {
+        relativePath: ".claude/commands",
+        description: "Custom slash commands directory",
+        autoLoaded: false,
+        type: "config",
+        format: "markdown"
+      }
+    ];
+  }
   getRecommendedModels(_credentials) {
     return {
       powerful: "claude-sonnet-4-20250514",
@@ -377,6 +435,31 @@ var GeminiAdapter = class extends BaseCodingAdapter {
       once: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: "GEMINI.md",
+        description: "Project-level instructions read automatically on startup",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".gemini/settings.json",
+        description: "Project-scoped settings (tool permissions, sandbox config)",
+        autoLoaded: true,
+        type: "config",
+        format: "json"
+      },
+      {
+        relativePath: ".gemini/styles",
+        description: "Custom style/persona definitions directory",
+        autoLoaded: false,
+        type: "config",
+        format: "markdown"
+      }
+    ];
+  }
   getRecommendedModels(_credentials) {
     return {
       powerful: "gemini-3-pro",
@@ -657,6 +740,31 @@ var CodexAdapter = class extends BaseCodingAdapter {
       safe: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: "AGENTS.md",
+        description: "Project-level instructions read automatically on startup",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: "codex.md",
+        description: "Additional project context file",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".codex/config.json",
+        description: "Project-scoped Codex configuration",
+        autoLoaded: true,
+        type: "config",
+        format: "json"
+      }
+    ];
+  }
   getRecommendedModels(_credentials) {
     return {
       powerful: "o3",
@@ -1030,6 +1138,31 @@ var AiderAdapter = class extends BaseCodingAdapter {
       safe: true
     }
   ];
+  getWorkspaceFiles() {
+    return [
+      {
+        relativePath: ".aider.conventions.md",
+        description: "Project conventions and instructions read on startup (--read flag)",
+        autoLoaded: true,
+        type: "memory",
+        format: "markdown"
+      },
+      {
+        relativePath: ".aider.conf.yml",
+        description: "Project-scoped Aider configuration (model, flags, options)",
+        autoLoaded: true,
+        type: "config",
+        format: "yaml"
+      },
+      {
+        relativePath: ".aiderignore",
+        description: "Gitignore-style file listing paths Aider should not edit",
+        autoLoaded: true,
+        type: "rules",
+        format: "text"
+      }
+    ];
+  }
   getRecommendedModels(credentials) {
     if (credentials?.anthropicKey) {
       return {