@dex-ai/coding-agent-sdk 0.1.21

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@dex-ai/coding-agent-sdk",
+  "version": "0.1.21",
+  "description": "Coding agent SDK — extensions for workspace, config, approval, session.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.18",
+    "@dex-ai/core-extensions": "^0.1.5",
+    "zod": "^3.23.8"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/create.ts

@@ -0,0 +1,76 @@
+/**
+ * CodingAgent.create() — composes SDK extensions into a ready-to-use coding agent.
+ */
+
+import { Agent } from "@dex-ai/sdk";
+import type { Agent as AgentType } from "@dex-ai/sdk";
+import type { CodingAgentOptions } from "./types";
+
+import { workspaceExtension } from "./extensions/workspace";
+import { configExtension } from "./extensions/config";
+import { settingsExtension } from "./extensions/settings";
+import { approvalExtension } from "./extensions/approval";
+import { sessionExtension } from "./extensions/session";
+import { envExtension } from "./extensions/env";
+import { buildSystemPrompt } from "./extensions/system-prompt";
+import {
+	skillsExtension,
+	allFsExtensions,
+	bashExtension,
+	tasksExtension,
+	askExtension,
+} from "@dex-ai/core-extensions";
+
+export const CodingAgent = {
+	async create(opts: CodingAgentOptions): Promise<AgentType> {
+		const cwd = opts.cwd ?? process.cwd();
+
+		// Create env extension first — it provides getCwd() for tools
+		const env = envExtension({
+			cwd,
+			rootDirs: opts.rootDirs,
+		});
+
+		// Tools use the env's dynamic cwd getter so `cd` takes effect immediately
+		const cwdGetter = env.getCwd;
+		const rootsGetter = env.getRootDirs;
+
+		return Agent.create({
+			name: "dex-coding-agent",
+			provider: opts.provider,
+			model: opts.model,
+			systemPrompt: opts.systemPrompt ?? buildSystemPrompt(),
+			...(opts.messages !== undefined ? { messages: opts.messages } : {}),
+			toolResultCache: { excludedTools: ["read"] },
+			extensions: [
+				// Provider(s)
+				opts.providerExtension,
+				...(opts.providerExtensions ?? []),
+				// SDK extensions
+				env,
+				workspaceExtension({ cwd }),
+				configExtension(
+					opts.config !== undefined ? { config: opts.config } : {},
+				),
+				settingsExtension(),
+				skillsExtension(),
+				...(opts.onApproval
+					? [approvalExtension({ handler: opts.onApproval })]
+					: []),
+				sessionExtension({
+					...(opts.sessionId !== undefined
+						? { sessionId: opts.sessionId }
+						: {}),
+					...(opts.sessionDir !== undefined ? { dir: opts.sessionDir } : {}),
+				}),
+				// Tools — use dynamic cwd and roots from env extension
+				...allFsExtensions({ cwd: cwdGetter, roots: rootsGetter }),
+				bashExtension({ cwd: cwdGetter }),
+				tasksExtension(),
+				askExtension(),
+				// Additional extensions from consumer
+				...(opts.extensions ?? []),
+			],
+		});
+	},
+};

package/src/extensions/approval.ts

@@ -0,0 +1,164 @@
+/**
+ * Approval Extension — permission-mode-aware tool approval gate.
+ *
+ * Reads permission state from the "settings" extension (via actx.state).
+ *
+ * Permission modes:
+ *   - 'read': read-access tools pass, all others require one-time session approval
+ *   - 'auto': read tools pass + always-allowed tools pass, others require one-time session approval
+ *   - 'yolo': all tools pass except denied tools (which are always blocked)
+ *
+ * The mode is loaded from the settings extension and can be changed at runtime
+ * (Shift+Tab in the TUI cycles modes via the settings extension).
+ */
+
+import type { Extension, ToolCall, ToolResult, GenerateContext, AnyTool, AgentContext } from "@dex-ai/sdk";
+import type {
+	ApprovalHandler,
+	ApprovalRequest,
+	ApprovalResult,
+	ToolCategory,
+} from "../types";
+import type { SettingsExtensionState } from "./settings";
+
+export interface ApprovalExtensionOptions {
+	handler: ApprovalHandler;
+}
+
+function categorize(toolName: string): ToolCategory {
+	switch (toolName) {
+		case "read":
+		case "search":
+			return "safe";
+		case "write":
+		case "edit":
+			return "write";
+		case "bash":
+			return "execute";
+		default:
+			return "write";
+	}
+}
+
+function reasonForCategory(toolName: string, category: ToolCategory): string {
+	switch (category) {
+		case "safe":
+			return "read-only operation";
+		case "write":
+			return `writes to file system (${toolName})`;
+		case "execute":
+			return "executes a shell command";
+		case "dangerous":
+			return "potentially destructive operation";
+	}
+}
+
+/**
+ * Resolve the access level for a tool by checking its metadata.
+ * Falls back to 'write' (conservative — requires approval).
+ */
+function resolveAccess(toolName: string, extensions: ReadonlyArray<Extension>): "read" | "write" {
+	for (const ext of extensions) {
+		if (!ext.tools) continue;
+		const tools: ReadonlyArray<AnyTool> = Array.isArray(ext.tools)
+			? ext.tools
+			: [ext.tools as AnyTool];
+		for (const t of tools) {
+			if (t.name === toolName) {
+				return t.access ?? "write";
+			}
+		}
+	}
+	return "write";
+}
+
+export function approvalExtension(opts: ApprovalExtensionOptions): Extension {
+	// Session-scoped approvals (cleared on session restart)
+	const sessionApproved = new Set<string>();
+
+	// References set during init
+	let allExtensions: ReadonlyArray<Extension> = [];
+	let settingsState: SettingsExtensionState | null = null;
+
+	return {
+		name: "approval",
+
+		init(actx: AgentContext) {
+			allExtensions = actx.extensions;
+			settingsState = actx.state.get("settings") as SettingsExtensionState | undefined ?? null;
+		},
+
+		on: {
+			"tool-start": async (
+				call: ToolCall,
+				_gctx: GenerateContext,
+			): Promise<ToolCall | ToolResult | void> => {
+				// If no settings extension, fall back to allowing everything
+				if (!settingsState) return;
+
+				const mode = settingsState.permissionMode;
+				const toolAccess = resolveAccess(call.toolName, allExtensions);
+
+				// --- YOLO mode: allow everything except denied tools ---
+				if (mode === "yolo") {
+					if (settingsState.deniedTools.has(call.toolName)) {
+						return {
+							toolCallId: call.toolCallId,
+							toolName: call.toolName,
+							output: {
+								type: "error-text",
+								value: `Tool "${call.toolName}" is on the deny list.`,
+							},
+						};
+					}
+					return; // allow
+				}
+
+				// --- Read tools always pass in both 'read' and 'auto' modes ---
+				if (toolAccess === "read") return;
+
+				// --- Session-approved tools pass through (both modes) ---
+				if (sessionApproved.has(call.toolName)) return;
+
+				// --- AUTO mode: also check the always-allowed list ---
+				if (mode === "auto") {
+					if (settingsState.allowedTools.has(call.toolName)) return;
+				}
+
+				// --- Need approval ---
+				const category = categorize(call.toolName);
+				const request: ApprovalRequest = {
+					toolName: call.toolName,
+					toolCallId: call.toolCallId,
+					input: call.input,
+					category,
+					reason: reasonForCategory(call.toolName, category),
+				};
+
+				const result = await opts.handler(request);
+
+				switch (result.decision) {
+					case "allow":
+						return; // one-time allow
+					case "allow-session":
+						sessionApproved.add(call.toolName);
+						return;
+					case "allow-always":
+						sessionApproved.add(call.toolName);
+						// Persist via settings extension
+						settingsState.allowAlways(call.toolName);
+						return;
+					case "deny": {
+						const reason =
+							result.reason ?? `User denied ${call.toolName} execution.`;
+						return {
+							toolCallId: call.toolCallId,
+							toolName: call.toolName,
+							output: { type: "error-text", value: reason },
+						};
+					}
+				}
+			},
+		},
+	};
+}

package/src/extensions/config.ts

@@ -0,0 +1,86 @@
+/**
+ * Config Extension — loads and merges configuration from file + env + overrides.
+ *
+ * Reads extension-specific config from:
+ *   - (global)    ~/.dex/extensions/config.json
+ *   - (workspace) .dex/extensions/config.json
+ *   - Environment variables: DEX_<KEY>
+ *   - Explicit opts.config overrides
+ *
+ * The config file is keyed by extension name:
+ *   { "workspace": { "maxDepth": 3 }, "openai": { "maxTokens": 4096 } }
+ */
+
+import type { Extension, AgentContext } from "@dex-ai/sdk";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { CodingAgentConfig, Workspace } from "../types";
+
+export interface ConfigExtensionOptions {
+	config?: Partial<CodingAgentConfig>;
+}
+
+const GLOBAL_DEX_DIR = join(homedir(), ".dex");
+const GLOBAL_EXTENSIONS_CONFIG = join(
+	GLOBAL_DEX_DIR,
+	"extensions",
+	"config.json",
+);
+
+/**
+ * Load JSON from a path, returning empty object on failure.
+ */
+function loadJsonFile(path: string): Record<string, unknown> {
+	if (!existsSync(path)) return {};
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+function loadEnvConfig(): Partial<CodingAgentConfig> {
+	const config: Partial<CodingAgentConfig> = {};
+	if (process.env.DEX_PROVIDER)
+		(config as any).provider = process.env.DEX_PROVIDER;
+	if (process.env.DEX_MODEL) (config as any).model = process.env.DEX_MODEL;
+	if (process.env.DEX_MAX_STEPS)
+		(config as any).maxSteps = parseInt(process.env.DEX_MAX_STEPS, 10);
+	if (process.env.DEX_MAX_TOKENS)
+		(config as any).maxTokens = parseInt(process.env.DEX_MAX_TOKENS, 10);
+	return config;
+}
+
+export function configExtension(opts: ConfigExtensionOptions = {}): Extension {
+	return {
+		name: "config",
+
+		init(actx: AgentContext) {
+			const workspace = actx.state.get("workspace") as Workspace | undefined;
+			const workspaceDexDir = workspace?.dexDir;
+
+			// Load extensions config: global → workspace (workspace overrides global)
+			const globalExtConfig = loadJsonFile(GLOBAL_EXTENSIONS_CONFIG);
+			const workspaceExtConfig = workspaceDexDir
+				? loadJsonFile(join(workspaceDexDir, "extensions", "config.json"))
+				: {};
+
+			// Merge: global extensions config → workspace extensions config
+			const extensionsConfig = { ...globalExtConfig, ...workspaceExtConfig };
+
+			// Load env + explicit overrides for agent-level config
+			const fromEnv = loadEnvConfig();
+			const merged: CodingAgentConfig = {
+				provider: actx.providerName,
+				model: actx.modelId,
+				cwd: workspace?.cwd ?? process.cwd(),
+				...fromEnv,
+				...opts.config,
+			};
+
+			actx.state.set("config", merged);
+			actx.state.set("extensions-config", extensionsConfig);
+		},
+	};
+}

package/src/extensions/env.ts

@@ -0,0 +1,281 @@
+/**
+ * Env Extension — manages runtime environment state for the coding agent.
+ *
+ * Responsibilities:
+ * - Maintains a list of rootDirs (sandbox boundaries). The CLI entry point
+ *   is the first root; users can add more via /add-dir.
+ * - Maintains a mutable cwd that must reside within one of the rootDirs.
+ * - Provides a `cd` tool so the agent can change cwd at runtime.
+ * - Injects per-turn environment context (rootDirs, cwd, datetime) via
+ *   model-start as a system message so the model always knows where it is.
+ * - Exposes getCwd() for other extensions/tools to read dynamically.
+ */
+
+import type {
+	Extension,
+	AgentContext,
+	GenerateContext,
+	Content,
+	ModelRequest,
+	Message,
+} from "@dex-ai/sdk";
+import { resolve, sep } from "node:path";
+import { realpathSync, existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { z } from "zod";
+import type { Tool, ToolOutput } from "@dex-ai/sdk";
+
+/* ------------------------------------------------------------------ */
+/* Types                                                               */
+/* ------------------------------------------------------------------ */
+
+export interface EnvExtensionOptions {
+	/** Initial working directory. Becomes the first rootDir. */
+	cwd: string;
+	/** Additional root directories to allow. Default: []. */
+	rootDirs?: string[] | undefined;
+}
+
+export interface EnvState {
+	/** Allowed root directories (sandbox boundaries). */
+	readonly rootDirs: string[];
+	/** Current working directory (mutable, always inside a rootDir). */
+	cwd: string;
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+function expandTilde(p: string): string {
+	if (p === "~") return homedir();
+	if (p.startsWith("~/") || p.startsWith("~" + sep)) {
+		return homedir() + p.slice(1);
+	}
+	return p;
+}
+
+function realDir(dir: string): string {
+	const resolved = resolve(expandTilde(dir));
+	try {
+		return realpathSync(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+function isInsideRoots(target: string, roots: string[]): boolean {
+	const realTarget = realDir(target);
+	for (const root of roots) {
+		const realRoot = realDir(root);
+		if (realTarget === realRoot || realTarget.startsWith(realRoot + sep)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension                                                           */
+/* ------------------------------------------------------------------ */
+
+export function envExtension(opts: EnvExtensionOptions): Extension & {
+	/** Get the current working directory. Use as a cwd getter for tools. */
+	getCwd: () => string;
+	/** Get the list of allowed root directories. */
+	getRootDirs: () => ReadonlyArray<string>;
+	/** Add a root directory to the sandbox. Returns true if added successfully. */
+	addRootDir: (dir: string) => boolean;
+} {
+	const initialCwd = realDir(opts.cwd);
+	const rootDirs: string[] = [initialCwd];
+
+	// Add any additional root dirs
+	if (opts.rootDirs) {
+		for (const d of opts.rootDirs) {
+			const rd = realDir(d);
+			if (!rootDirs.includes(rd)) {
+				rootDirs.push(rd);
+			}
+		}
+	}
+
+	let cwd = initialCwd;
+
+	const getCwd = () => cwd;
+	const getRootDirs = () => rootDirs as ReadonlyArray<string>;
+
+	const addRootDir = (dir: string): boolean => {
+		const rd = realDir(dir);
+		if (!existsSync(rd)) return false;
+		try {
+			if (!statSync(rd).isDirectory()) return false;
+		} catch {
+			return false;
+		}
+		if (!rootDirs.includes(rd)) {
+			rootDirs.push(rd);
+		}
+		return true;
+	};
+
+	/* ---------------------------------------------------------------- */
+	/* cd tool                                                          */
+	/* ---------------------------------------------------------------- */
+
+	const cdParamsSchema = z.object({
+		path: z
+			.string()
+			.min(1)
+			.describe(
+				"Directory to change to. Absolute or relative to current cwd. Must be within the sandbox (rootDirs).",
+			),
+	});
+
+	type CdParams = z.infer<typeof cdParamsSchema>;
+
+	const cdTool: Tool<CdParams, string> = {
+		name: "cd",
+		displayName: "Cd",
+		access: "write",
+		description:
+			"Change the working directory. The new path must be within the allowed root directories (sandbox). All subsequent tool calls (read, write, edit, search, bash) will operate relative to the new cwd.",
+		parameters: cdParamsSchema,
+		async execute(input): Promise<ToolOutput> {
+			const target = resolve(cwd, input.path);
+			const realTarget = realDir(target);
+
+			// Validate target exists and is a directory
+			if (!existsSync(realTarget)) {
+				return {
+					type: "error-text",
+					value: `Directory not found: ${input.path}`,
+				};
+			}
+			try {
+				if (!statSync(realTarget).isDirectory()) {
+					return {
+						type: "error-text",
+						value: `Not a directory: ${input.path}`,
+					};
+				}
+			} catch {
+				return {
+					type: "error-text",
+					value: `Cannot access: ${input.path}`,
+				};
+			}
+
+			// Validate within sandbox
+			if (!isInsideRoots(realTarget, rootDirs)) {
+				return {
+					type: "error-text",
+					value: `Path outside sandbox: ${input.path}. Allowed roots: ${rootDirs.join(", ")}`,
+				};
+			}
+
+			cwd = realTarget;
+			return { type: "text", value: `cwd: ${cwd}` };
+		},
+	};
+
+	/* ---------------------------------------------------------------- */
+	/* model-start context injection                                    */
+	/* ---------------------------------------------------------------- */
+
+	function buildEnvContext(actx: AgentContext): string {
+		const now = new Date();
+		const session = actx.state.get("session") as
+			| { id: string; path: string }
+			| undefined;
+		const lines = [
+			`<env>`,
+			`  cwd: ${cwd}`,
+			`  rootDirs: ${rootDirs.join(", ")}`,
+			...(session ? [`  sessionId: ${session.id}`] : []),
+			`  datetime: ${now.toISOString()}`,
+			`  platform: ${process.platform}/${process.arch}`,
+			`</env>`,
+		];
+		return lines.join("\n");
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Extension definition                                             */
+	/* ---------------------------------------------------------------- */
+
+	const ext: Extension & {
+		getCwd: () => string;
+		getRootDirs: () => ReadonlyArray<string>;
+		addRootDir: (dir: string) => boolean;
+	} = {
+		name: "env",
+		description: "Environment state: cwd, rootDirs, datetime, platform info.",
+
+		tools: cdTool,
+
+		init(actx: AgentContext) {
+			const state: EnvState = { rootDirs, cwd };
+			actx.state.set("env", state);
+		},
+
+		on: {
+			"model-start"(
+				req: ModelRequest,
+				gctx: GenerateContext,
+			): ModelRequest | void {
+				// Sync state in case cwd changed since last generate
+				const actx = gctx.agent;
+				const state = actx.state.get("env") as EnvState | undefined;
+				if (state) {
+					state.cwd = cwd;
+				}
+
+				const text = buildEnvContext(actx);
+
+				// Inject as a system message after the first system prompt.
+				// This keeps it fresh (datetime updates each step) without
+				// creating a role-order violation like appending a user message.
+				const envMsg: Message = {
+					role: "system",
+					content: [{ type: "text" as const, text }],
+				};
+				const messages = [...req.messages];
+				// Insert after the first system message (or at index 0 if none)
+				const insertIdx = messages[0]?.role === "system" ? 1 : 0;
+				messages.splice(insertIdx, 0, envMsg);
+				return { ...req, messages };
+			},
+		},
+
+		// Expose methods for external use
+		getCwd,
+		getRootDirs,
+		addRootDir,
+
+		// Declare available commands for CLI discovery
+		commands: [
+			{ name: "add-dir", description: "Add a directory to the sandbox" },
+		],
+
+		// Handle /add-dir command (duck-typed for CLI host)
+		onCommand(name: string, args: string): boolean | string {
+			if (name === "add-dir") {
+				const dir = args.trim();
+				if (!dir) {
+					return "Usage: /add-dir <path>";
+				}
+				const expanded = expandTilde(dir);
+				const resolved = resolve(cwd, expanded);
+				const success = addRootDir(resolved);
+				if (!success) {
+					return `Failed to add directory: ${dir} (not found or not a directory)`;
+				}
+				return `✓ Added root directory: ${realDir(resolved)}`;
+			}
+			return false;
+		},
+	} as any;
+
+	return ext;
+}