@dex-ai/coding-agent-sdk 0.1.21

package/src/extensions/settings.ts

@@ -0,0 +1,416 @@
+/**
+ * Settings Extension — loads and manages ~/.dex/settings.json (global user settings).
+ *
+ * Responsibilities:
+ *   - Load permission mode, allowed/denied tool lists on init
+ *   - Expose settings via actx.state.get("settings")
+ *   - Provide mutation methods for runtime changes (mode cycling, allow-always)
+ *   - Persist changes back to disk
+ *
+ * Other extensions (e.g. approval) read from actx.state.get("settings").
+ */
+
+import type { Extension, AgentContext, ThinkingLevel } from "@dex-ai/sdk";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { PermissionMode, PermissionSettings } from "../types";
+
+/* ------------------------------------------------------------------ */
+/* Types                                                               */
+/* ------------------------------------------------------------------ */
+
+export interface GlobalSettings {
+	readonly permissions: PermissionSettings;
+	/** Enable debug mode (stderr capture + /debug panel). Default: false. */
+	readonly debug?: boolean;
+	/** Hide thinking/reasoning text from display. Default: false (show thinking). */
+	readonly hideThinking?: boolean;
+	/** Default thinking/reasoning level. Default: "high". */
+	readonly defaultThinking?: ThinkingLevel | undefined;
+	/** Configured providers (name → config). */
+	readonly providers?: Record<string, ProviderSettingsConfig>;
+	/** Default provider name. */
+	readonly defaultProvider?: string;
+	/** Default model ID. */
+	readonly defaultModel?: string;
+}
+
+export interface ProviderSettingsConfig {
+	readonly type: string;
+	readonly apiKey?: string;
+	readonly baseUrl?: string;
+	readonly models?: Array<
+		string | { id: string; contextWindow?: number; maxTokens?: number }
+	>;
+}
+
+/* ------------------------------------------------------------------ */
+/* File I/O                                                            */
+/* ------------------------------------------------------------------ */
+
+const DEX_DIR = join(homedir(), ".dex");
+const AGENT_DIR = join(DEX_DIR, "agent");
+const SETTINGS_PATH = join(AGENT_DIR, "settings.json");
+const STATE_PATH = join(AGENT_DIR, "state.json");
+
+const DEFAULT_SETTINGS: GlobalSettings = {
+	permissions: {
+		mode: "auto",
+		allowedTools: [],
+		deniedTools: [],
+	},
+};
+
+function validateMode(mode: unknown): PermissionMode | undefined {
+	if (mode === "read" || mode === "auto" || mode === "yolo") return mode;
+	return undefined;
+}
+
+const THINKING_LEVELS: ThinkingLevel[] = [
+	"off",
+	"min",
+	"low",
+	"med",
+	"high",
+	"max",
+];
+
+function validateThinkingLevel(level: unknown): ThinkingLevel | undefined {
+	if (
+		typeof level === "string" &&
+		THINKING_LEVELS.includes(level as ThinkingLevel)
+	) {
+		return level as ThinkingLevel;
+	}
+	return undefined;
+}
+
+/**
+ * Ensure ~/.dex/agent/settings.json exists.
+ * Creates an empty file if nothing exists.
+ */
+export function ensureSettingsFile(): void {
+	if (existsSync(SETTINGS_PATH)) return;
+
+	mkdirSync(AGENT_DIR, { recursive: true });
+	writeFileSync(SETTINGS_PATH, "{}\n", "utf-8");
+}
+
+/**
+ * Parse a settings JSON object into a validated GlobalSettings.
+ */
+function parseSettings(parsed: Partial<GlobalSettings>): GlobalSettings {
+	return {
+		permissions: {
+			mode: validateMode(parsed.permissions?.mode) ?? "auto",
+			allowedTools: Array.isArray(parsed.permissions?.allowedTools)
+				? parsed.permissions!.allowedTools
+				: [],
+			deniedTools: Array.isArray(parsed.permissions?.deniedTools)
+				? parsed.permissions!.deniedTools
+				: [],
+		},
+		...(parsed.debug === true ? { debug: true } : {}),
+		...(parsed.hideThinking === true ? { hideThinking: true } : {}),
+		...(validateThinkingLevel(parsed.defaultThinking)
+			? { defaultThinking: validateThinkingLevel(parsed.defaultThinking) }
+			: {}),
+		...(parsed.providers
+			? {
+					providers: parsed.providers as Record<string, ProviderSettingsConfig>,
+				}
+			: {}),
+		...(parsed.defaultProvider
+			? { defaultProvider: parsed.defaultProvider }
+			: {}),
+		...(parsed.defaultModel ? { defaultModel: parsed.defaultModel } : {}),
+	};
+}
+
+/**
+ * Load a settings file from a path, returning null if not found/invalid.
+ */
+function loadSettingsFile(path: string): GlobalSettings | null {
+	if (!existsSync(path)) return null;
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw) as Partial<GlobalSettings>;
+		return parseSettings(parsed);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Load global settings from ~/.dex/agent/settings.json.
+ * Returns defaults if the file doesn't exist or is invalid.
+ */
+export function loadGlobalSettings(): GlobalSettings {
+	return loadSettingsFile(SETTINGS_PATH) ?? DEFAULT_SETTINGS;
+}
+
+/**
+ * Load resolved settings: global merged with workspace overrides.
+ * Workspace .dex/agent/settings.json overrides global values.
+ */
+export function loadResolvedSettings(workspaceDexDir?: string): GlobalSettings {
+	const global = loadGlobalSettings();
+	if (!workspaceDexDir) return global;
+
+	const workspacePath = join(workspaceDexDir, "agent", "settings.json");
+	const workspace = loadSettingsFile(workspacePath);
+	if (!workspace) return global;
+
+	// Workspace overrides global (shallow merge per section)
+	return {
+		...global,
+		...workspace,
+		permissions: {
+			...global.permissions,
+			...workspace.permissions,
+		},
+		// Providers: merge workspace providers on top of global
+		...(global.providers || workspace.providers
+			? { providers: { ...global.providers, ...workspace.providers } }
+			: {}),
+	};
+}
+
+/**
+ * Save global settings to ~/.dex/agent/settings.json.
+ */
+export function saveGlobalSettings(settings: GlobalSettings): void {
+	mkdirSync(AGENT_DIR, { recursive: true });
+	writeFileSync(
+		SETTINGS_PATH,
+		JSON.stringify(settings, null, 2) + "\n",
+		"utf-8",
+	);
+}
+
+/* ------------------------------------------------------------------ */
+/* Mutation helpers (used by the extension and exported for CLI)       */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Add a tool to the always-allowed list and persist.
+ */
+export function addAllowedTool(toolName: string): GlobalSettings {
+	const settings = loadGlobalSettings();
+	const allowed = new Set(settings.permissions.allowedTools ?? []);
+	allowed.add(toolName);
+	const updated: GlobalSettings = {
+		...settings,
+		permissions: {
+			...settings.permissions,
+			allowedTools: [...allowed],
+		},
+	};
+	saveGlobalSettings(updated);
+	return updated;
+}
+
+/**
+ * Update the permission mode and persist.
+ */
+export function setPermissionMode(mode: PermissionMode): GlobalSettings {
+	const settings = loadGlobalSettings();
+	const updated: GlobalSettings = {
+		...settings,
+		permissions: {
+			...settings.permissions,
+			mode,
+		},
+	};
+	saveGlobalSettings(updated);
+	return updated;
+}
+
+/**
+ * Set the default thinking level and persist.
+ */
+export function setDefaultThinking(level: ThinkingLevel): GlobalSettings {
+	const settings = loadGlobalSettings();
+	const updated: GlobalSettings = {
+		...settings,
+		defaultThinking: level === "off" ? undefined : level,
+	};
+	// Remove the key entirely if off (clean JSON)
+	if (level === "off") {
+		delete (updated as any).defaultThinking;
+	}
+	saveGlobalSettings(updated);
+	return updated;
+}
+
+/**
+ * Add or update a provider config and persist.
+ */
+export function saveProviderConfig(
+	name: string,
+	config: ProviderSettingsConfig,
+): GlobalSettings {
+	const settings = loadGlobalSettings();
+	const providers = { ...(settings.providers ?? {}), [name]: config };
+	const updated: GlobalSettings = { ...settings, providers };
+	saveGlobalSettings(updated);
+	return updated;
+}
+
+/**
+ * Set the default provider and model, and persist.
+ */
+export function setDefaultProvider(
+	providerName: string,
+	model?: string,
+): GlobalSettings {
+	const settings = loadGlobalSettings();
+	const updated: GlobalSettings = {
+		...settings,
+		defaultProvider: providerName,
+		...(model ? { defaultModel: model } : {}),
+	};
+	saveGlobalSettings(updated);
+	return updated;
+}
+
+/**
+ * Transient agent state (persisted separately from settings).
+ */
+export interface AgentState {
+	lastProvider?: string;
+	lastModel?: string;
+}
+
+/**
+ * Load transient agent state from ~/.dex/agent/state.json.
+ */
+export function loadAgentState(): AgentState {
+	try {
+		if (!existsSync(STATE_PATH)) return {};
+		const raw = JSON.parse(readFileSync(STATE_PATH, "utf-8"));
+		return raw && typeof raw === "object" ? raw : {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Save transient agent state to ~/.dex/agent/state.json.
+ */
+function saveAgentState(state: AgentState): void {
+	mkdirSync(AGENT_DIR, { recursive: true });
+	writeFileSync(STATE_PATH, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Save the last used provider/model (auto-persisted on model switch).
+ */
+export function saveLastUsedModel(providerName: string, model: string): void {
+	// Don't persist empty values — only save when there's an actual selection
+	if (!providerName && !model) return;
+	const state = loadAgentState();
+	const updated: AgentState = {
+		...state,
+		...(providerName ? { lastProvider: providerName } : {}),
+		...(model ? { lastModel: model } : {}),
+	};
+	saveAgentState(updated);
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension                                                           */
+/* ------------------------------------------------------------------ */
+
+export interface SettingsExtensionState {
+	/** Current permission mode (mutable at runtime). */
+	permissionMode: PermissionMode;
+	/** Current thinking level (mutable at runtime). undefined means off. */
+	thinkingLevel: ThinkingLevel | undefined;
+	/** Set of always-allowed tools. */
+	readonly allowedTools: Set<string>;
+	/** Set of always-denied tools. */
+	readonly deniedTools: Set<string>;
+	/** Cycle to the next permission mode. Returns the new mode. */
+	cycleMode(): PermissionMode;
+	/** Set the thinking level and persist. */
+	setThinking(level: ThinkingLevel): void;
+	/** Cycle to the next thinking level. Returns the new level. */
+	cycleThinking(): ThinkingLevel;
+	/** Add a tool to the always-allowed list (persists). */
+	allowAlways(toolName: string): void;
+	/** Reload settings from disk. */
+	reload(): void;
+}
+
+export function settingsExtension(): Extension {
+	return {
+		name: "settings",
+
+		init(actx: AgentContext) {
+			// Ensure agent/settings.json exists (migrates from legacy if needed)
+			ensureSettingsFile();
+
+			const workspace = actx.state.get("workspace") as
+				| { dexDir?: string }
+				| undefined;
+			let settings = loadResolvedSettings(workspace?.dexDir);
+
+			const state: SettingsExtensionState = {
+				permissionMode: settings.permissions.mode,
+				thinkingLevel: settings.defaultThinking ?? "high",
+				allowedTools: new Set(settings.permissions.allowedTools ?? []),
+				deniedTools: new Set(settings.permissions.deniedTools ?? []),
+
+				cycleMode(): PermissionMode {
+					const modes: PermissionMode[] = ["read", "auto", "yolo"];
+					const idx = modes.indexOf(state.permissionMode);
+					const next = modes[(idx + 1) % modes.length]!;
+					state.permissionMode = next;
+					setPermissionMode(next);
+					return next;
+				},
+
+				setThinking(level: ThinkingLevel): void {
+					state.thinkingLevel = level === "off" ? undefined : level;
+					setDefaultThinking(level);
+				},
+
+				cycleThinking(): ThinkingLevel {
+					const current = state.thinkingLevel ?? "off";
+					const idx = THINKING_LEVELS.indexOf(current);
+					const next = THINKING_LEVELS[(idx + 1) % THINKING_LEVELS.length]!;
+					state.thinkingLevel = next === "off" ? undefined : next;
+					setDefaultThinking(next);
+					return next;
+				},
+
+				allowAlways(toolName: string): void {
+					const updated = addAllowedTool(toolName);
+					state.allowedTools.add(toolName);
+					// Sync the full state
+					for (const t of updated.permissions.allowedTools ?? []) {
+						state.allowedTools.add(t);
+					}
+				},
+
+				reload(): void {
+					settings = loadGlobalSettings();
+					state.permissionMode = settings.permissions.mode;
+					state.thinkingLevel = settings.defaultThinking ?? "high";
+					state.allowedTools.clear();
+					for (const t of settings.permissions.allowedTools ?? []) {
+						state.allowedTools.add(t);
+					}
+					state.deniedTools.clear();
+					for (const t of settings.permissions.deniedTools ?? []) {
+						state.deniedTools.add(t);
+					}
+				},
+			};
+
+			actx.state.set("settings", state);
+		},
+	};
+}

package/src/extensions/system-prompt.ts

@@ -0,0 +1,208 @@
+/**
+ * System Prompt — the core coding assistant identity, tool usage guidelines,
+ * safety rules, and output format.
+ *
+ * This is injected as the actual system prompt via Agent.create({ systemPrompt })
+ * so it's always in context without needing a get_skill() call.
+ */
+
+/* ------------------------------------------------------------------ */
+/* Prompt sections                                                     */
+/* ------------------------------------------------------------------ */
+
+const SYSTEM_PROMPT = `You are Dex, an expert AI coding agent. You help users understand, write, debug, and improve code by directly reading, editing, and creating files in their projects.
+
+## Principles
+
+- Be concise. Explain only what's needed.
+- Show code, not just descriptions. Use fenced code blocks with language tags.
+- Prefer small, targeted changes over large rewrites.
+- Read before writing. Always understand existing code before modifying it.
+- Preserve existing style and conventions in the codebase.
+- Ask for clarification when requirements are ambiguous.
+- Take initiative — when the intent is clear, act rather than asking for permission.
+- Think step by step for complex tasks, but execute without unnecessary narration.`;
+
+const TOOL_GUIDELINES = `## Tool Usage Guidelines
+
+- **read**: Always read a file before editing it. Never assume file contents.
+- **edit**: Prefer edit over write for existing files. Provide enough context in the oldString to match uniquely.
+- **write**: Use only for new files or complete rewrites. Never overwrite without reading first.
+- **search**: Use to find relevant code before making changes. Search for function names, imports, and related patterns.
+- **bash**: Use for running tests, installing dependencies, checking git status, and other shell operations.
+  - Prefer non-destructive commands. Avoid \`rm -rf\`, \`git reset --hard\`, etc. without explicit user approval.
+  - Keep commands focused and single-purpose.
+  - Always quote file paths that may contain spaces.
+  - **OUTPUT EFFICIENCY IS CRITICAL.** Every byte of tool output consumes context window tokens. Unbounded output degrades performance and can truncate important information.
+    - ALWAYS constrain output: pipe through \`| tail -n 20\`, \`| head -n 30\`, \`| grep -E 'pattern'\`, or \`2>&1 | tail -n 50\`.
+    - For builds/tests: use \`2>&1 | tail -n 30\` or \`2>&1 | grep -A 3 'error\\|fail\\|Error'\` to capture only relevant diagnostics.
+    - For listing files: use \`| head -n 20\` or combine with \`grep\` to filter. Never dump entire directory trees.
+    - For git: \`git log --oneline -10\`, \`git diff --stat\`, or \`git diff -- file.ts | head -50\`.
+    - For \`find\`: always add \`| head -n 20\` or narrow the search with specific patterns.
+    - For \`cat\`/viewing: prefer the \`read\` tool instead. If you must use cat, pipe through \`head\` or \`sed -n '10,30p'\`.
+    - Combine filters: \`command 2>&1 | grep -v 'noise' | tail -n 20\`.
+  - NEVER run a command that may produce unbounded output without piping through a limiter.
+  - If a command produces no useful output on success, append \`&& echo 'done'\` rather than dumping stdout.
+
+When making function calls using tools that accept array or object parameters ensure those are structured using JSON. For example:
+\`\`\`json
+{"edits": [{"oldString": "foo", "newString": "bar"}]}
+\`\`\`
+
+String and scalar parameters should be specified as is, while lists and objects should use JSON format.`;
+
+const SAFETY_RULES = `## Safety Rules
+
+- Never commit secrets, API keys, passwords, or credentials to files.
+- Never run destructive commands (delete, force push, reset) without user confirmation.
+- Never modify files outside the project working directory unless explicitly asked.
+- If a command might have side effects (network calls, installs, writes), explain before executing.
+- When unsure about the impact of a change, explain the risks and ask for confirmation.`;
+
+const OUTPUT_FORMAT = `## Output Format
+
+- Use fenced code blocks with language identifiers for all code.
+- When showing changes, include enough surrounding context for the user to locate them.
+- For multi-step tasks, outline the plan briefly before executing.
+- After completing a task, summarize what was done and any follow-up needed.`;
+
+const SKILL_USAGE = `## Skill Usage
+
+Skills are your expert playbooks. Use them proactively — don't just rely on general knowledge.
+
+- **Load skills early.** When starting a task, check if a relevant skill exists in the catalog and \`get_skill\` it before diving in.
+- **Switch skills as you go.** Complex tasks span multiple phases (design → implement → debug → review). Load the appropriate skill for each phase rather than working from memory alone.
+- **Follow skill workflows.** Skills encode tested procedures. When a loaded skill prescribes specific steps, follow them rather than improvising.
+- **Combine skills.** Many tasks benefit from layering — e.g. use \`debug-investigate\` to find the issue, then \`spec-implementation\` to fix it properly.
+- **Don't hoard.** You don't need to load every skill upfront. Load what you need for the current phase, then load the next when you transition.`;
+
+const EXTENDING_DEX = `## Extending Dex
+
+You can create custom tools and skills by writing extensions.
+
+### Extension Locations
+
+Extensions are loaded in layers (later layers override earlier ones):
+
+1. **Built-in** — bundled with Dex (tools, skills, providers)
+2. **Global** — \`~/.dex/extensions/\` — available in all projects
+3. **Project** — \`<project>/.dex/extensions/\` — scoped to a single project
+
+### Creating a Tool
+
+A tool is an action the model can invoke. Create an extension file:
+
+\`\`\`typescript
+import { Extension, Tool } from "@dex-ai/sdk";
+import { z } from "zod";
+
+export default Extension.define({
+  name: "my-tools",
+  tools: [
+    Tool.define({
+      name: "my_tool",
+      description: "What the tool does",
+      parameters: z.object({
+        input: z.string().describe("Description of the input"),
+      }),
+      access: "read", // "read" = no side effects, "write" = modifies state
+      async execute(input, gctx) {
+        // Implementation
+        return { result: "value" };
+      },
+    }),
+  ],
+});
+\`\`\`
+
+### Creating a Skill
+
+A skill injects structured instructions into the system prompt. Create a folder:
+
+\`\`\`
+~/.dex/skills/<skill-name>/SKILL.md
+\`\`\`
+
+With optional YAML frontmatter:
+
+\`\`\`markdown
+---
+name: my-skill
+description: Short description for the catalog
+---
+
+## Instructions
+
+Your skill content here (markdown).
+\`\`\`
+
+Skills can also be defined programmatically in an extension:
+
+\`\`\`typescript
+import { Extension } from "@dex-ai/sdk";
+
+export default Extension.define({
+  name: "my-skills",
+  skills: [{
+    name: "my-skill",
+    description: "Guidance for X",
+    content: "## How to do X\\n\\n- Step 1...\\n- Step 2...",
+    when: (actx) => true, // optional: conditional activation
+  }],
+});
+\`\`\`
+
+### Extension Lifecycle
+
+Extensions can also hook into events (\`on\`), provide models, declare config schemas, and define canvas panels. Use \`init()\` and \`dispose()\` for setup/teardown of long-lived resources.`;
+
+/* ------------------------------------------------------------------ */
+/* Builder                                                             */
+/* ------------------------------------------------------------------ */
+
+export interface SystemPromptOptions {
+	/** Override the base system prompt entirely. */
+	systemPrompt?: string;
+	/** Include tool usage guidelines. Default: true. */
+	toolGuidelines?: boolean;
+	/** Include safety rules. Default: true. */
+	safetyRules?: boolean;
+	/** Include output format guidelines. Default: true. */
+	outputFormat?: boolean;
+	/** Include skill usage instructions. Default: true. */
+	skillUsage?: boolean;
+	/** Include extending Dex instructions. Default: true. */
+	extendingDex?: boolean;
+}
+
+/**
+ * Build the Dex coding agent system prompt string.
+ * Composes identity, tool guidelines, safety rules, and output format.
+ */
+export function buildSystemPrompt(opts: SystemPromptOptions = {}): string {
+	const parts: string[] = [];
+
+	parts.push(opts.systemPrompt ?? SYSTEM_PROMPT);
+
+	if (opts.toolGuidelines ?? true) {
+		parts.push(TOOL_GUIDELINES);
+	}
+
+	if (opts.safetyRules ?? true) {
+		parts.push(SAFETY_RULES);
+	}
+
+	if (opts.outputFormat ?? true) {
+		parts.push(OUTPUT_FORMAT);
+	}
+
+	if (opts.skillUsage ?? true) {
+		parts.push(SKILL_USAGE);
+	}
+
+	if (opts.extendingDex ?? true) {
+		parts.push(EXTENDING_DEX);
+	}
+
+	return parts.join("\n\n");
+}