codeep 2.1.4 → 2.3.1

package/dist/utils/agent.js

@@ -13,6 +13,7 @@ const debug = (...args) => {
 // Import chat layer (prompt building + API calls)
 import { agentChat, getAgentSystemPrompt, getFallbackSystemPrompt, loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent, summarizeEarlierHistory, } from './agentChat.js';
 import { ApiError } from '../api/index.js';
+import { loadUserProfilePrompt } from './userProfile.js';
 export { loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent };
 /**
  * Calculate dynamic timeout based on task complexity
@@ -127,8 +128,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
     const startTime = Date.now();
     const actions = [];
     const messages = [];
-    // Start history session for undo support
-    const sessionId = startSession(prompt, projectContext.root || process.cwd());
+    // Start history session for undo support. Skipped for nested (delegated)
+    // runs so we don't reset the parent's currentSession singleton — the
+    // sub-agent's actions still record into the parent's open session.
+    const sessionId = opts.nested ? '' : startSession(prompt, projectContext.root || process.cwd());
     // Task planning phase (if enabled)
     // Use planning for complex keywords or multi-word prompts
     let taskPlan = null;
@@ -221,10 +224,53 @@ export async function runAgent(prompt, projectContext, options = {}) {
     catch {
         // Skill loading failure shouldn't fail the whole agent run.
     }
+    // Sub-agents — the `delegate` tool lets the top-level agent hand a
+    // self-contained sub-task to a specialist that runs in its own context and
+    // returns a summary. Only advertised at depth 0, so sub-agents can't recurse
+    // (delegation depth is capped at 1 for v1).
+    let agentsCatalogBlock = '';
+    if ((opts.depth ?? 0) === 0) {
+        try {
+            const { loadAgents, formatAgentsForSysprompt } = await import('./agents.js');
+            const agents = loadAgents(projectContext.root);
+            if (agents.length > 0) {
+                mcpToolDefs.push({
+                    name: 'delegate',
+                    description: 'Delegate a self-contained sub-task to a specialist sub-agent that runs in its own fresh context and returns a summary. Use it to keep your own context focused.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            agent: { type: 'string', description: 'Sub-agent name from the catalog (e.g. "researcher"). Omit for a general-purpose sub-agent.' },
+                            task: { type: 'string', description: 'A clear, self-contained instruction for the sub-agent.' },
+                        },
+                        required: ['task'],
+                    },
+                });
+                agentsCatalogBlock = formatAgentsForSysprompt(agents);
+            }
+        }
+        catch {
+            // Agent loading must never block the run.
+        }
+    }
     // Build system prompt - use fallback format if native tools not supported
     let systemPrompt = useNativeTools
         ? getAgentSystemPrompt(projectContext)
         : getFallbackSystemPrompt(projectContext, mcpToolDefs);
+    // Delegated sub-agent role — its defining instruction. Injected right after
+    // the base prompt so it frames everything that follows. Empty for normal runs.
+    if (opts.roleAddendum) {
+        systemPrompt += '\n\n## Your role (delegated sub-agent)\n' + opts.roleAddendum;
+    }
+    // Inject the user profile (global ~/.codeep/profile.md + project
+    // .codeep/profile.md) so the agent adapts to who it's working with —
+    // reply language, style, stack, hard preferences. User-authored and gated
+    // by config.userProfile. Lives here (not in the base prompt) so every
+    // surface — CLI, ACP, VS Code, Zed — inherits it via this single path.
+    const userProfileBlock = loadUserProfilePrompt(projectContext.root);
+    if (userProfileBlock) {
+        systemPrompt += userProfileBlock;
+    }
     // Inject project rules (from .codeep/rules.md or CODEEP.md)
     const projectRules = loadProjectRules(projectContext.root);
     if (projectRules) {
@@ -259,6 +305,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
     if (skillCatalogBlock) {
         systemPrompt += '\n\n' + skillCatalogBlock;
     }
+    // Sub-agent catalog (delegate) — only present at depth 0.
+    if (agentsCatalogBlock) {
+        systemPrompt += agentsCatalogBlock;
+    }
     // Active personality goes LAST — appended after skills / project rules /
     // smart context so its tone overrides earlier conventions. Set via
     // `/personality <name>`; empty when no personality is active.
@@ -297,6 +347,95 @@ export async function runAgent(prompt, projectContext, options = {}) {
         ...(config.get('agentConfirmExecuteCommand') !== false ? ['execute_command'] : []),
         ...(config.get('agentConfirmWriteFile') === true ? ['write_file', 'edit_file'] : []),
     ]);
+    // Delegation handler: run a named (or generic) sub-agent in its own fresh
+    // context and return its summary as the tool result. Reachable only when the
+    // `delegate` tool was advertised (depth 0). The sub-agent runs nested (no own
+    // undo session) at depth 1 and never gets `delegate`, so depth is capped at 1.
+    const runDelegate = async (toolCall) => {
+        const params = (toolCall.parameters || {});
+        const task = String(params.task || '').trim();
+        const fail = (error) => ({ success: false, output: '', error, tool: 'delegate', parameters: toolCall.parameters });
+        if (!task)
+            return fail('delegate requires a non-empty "task".');
+        let def = null;
+        try {
+            const { findAgent } = await import('./agents.js');
+            def = params.agent ? findAgent(params.agent, projectContext.root) : null;
+            if (params.agent && !def)
+                return fail(`No sub-agent named "${params.agent}". Run /agents to see available agents.`);
+        }
+        catch { /* fall back to a generic sub-agent */ }
+        let roleAddendum = def?.prompt
+            || 'You are a general-purpose sub-agent. Complete the task in your own context and return a concise, self-contained summary of what you did and the outcome.';
+        if (def?.tools)
+            roleAddendum += `\n\nYou may use ONLY these tools: ${def.tools.join(', ')}.`;
+        if (def?.personality) {
+            try {
+                const { findPersonality } = await import('./personalities.js');
+                const p = findPersonality(def.personality, projectContext.root);
+                if (p)
+                    roleAddendum += '\n' + p.prompt;
+            }
+            catch { /* ignore */ }
+        }
+        const label = def?.name || 'agent';
+        opts.onIteration?.(iteration, `⤷ delegating to ${label}…`);
+        const tag = (text) => `⤷ ${label}: ${text}`;
+        // Model override — swap config for the nested run, restore in finally.
+        const prevModel = config.get('model');
+        const prevProvider = config.get('provider');
+        let swapped = false;
+        if (def?.model) {
+            try {
+                const m = String(def.model);
+                if (m.includes('/')) {
+                    const { setProvider } = await import('../config/index.js');
+                    setProvider(m.slice(0, m.indexOf('/')));
+                    config.set('model', m.slice(m.indexOf('/') + 1));
+                }
+                else {
+                    config.set('model', m);
+                }
+                swapped = true;
+            }
+            catch { /* keep parent's model */ }
+        }
+        try {
+            const sub = await runAgent(task, projectContext, {
+                ...DEFAULT_OPTIONS,
+                nested: true,
+                depth: (opts.depth ?? 0) + 1,
+                allowedTools: def?.tools,
+                roleAddendum,
+                maxIterations: def?.maxIterations ?? Math.min(15, opts.maxIterations),
+                maxDuration: opts.maxDuration,
+                abortSignal: opts.abortSignal,
+                onRequestPermission: opts.onRequestPermission,
+                onExecuteCommand: opts.onExecuteCommand,
+                fs: opts.fs,
+                mcpSessionId: opts.mcpSessionId,
+                autoVerify: false,
+                onIteration: (_i, msg) => opts.onIteration?.(iteration, tag(msg)),
+                onThinking: (t) => opts.onThinking?.(tag(t)),
+                // No chatHistory → the sub-agent gets a fresh context window.
+            });
+            const summary = sub.finalResponse?.trim() || '(sub-agent finished without a summary)';
+            return { success: sub.success, output: `[${label}] ${summary}`, tool: 'delegate', parameters: toolCall.parameters };
+        }
+        catch (err) {
+            return fail(`Sub-agent "${label}" failed: ${err.message}`);
+        }
+        finally {
+            if (swapped) {
+                try {
+                    const { setProvider } = await import('../config/index.js');
+                    setProvider(String(prevProvider));
+                    config.set('model', prevModel);
+                }
+                catch { /* ignore restore failure */ }
+            }
+        }
+    };
     const maxTimeoutRetries = 3;
     const maxConsecutiveTimeouts = 30; // Allow more consecutive timeouts before giving up
     const maxConsecutiveRateLimits = 5; // Stop after 5 consecutive rate-limited iterations
@@ -328,7 +467,8 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     finalResponse: partialLines.join('\n'),
                     error: `Exceeded maximum duration of ${durationMin} min`,
                 };
-                writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
+                if (!opts.nested)
+                    writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
                 return result;
             }
             // Check abort signal
@@ -590,6 +730,21 @@ export async function runAgent(prompt, projectContext, options = {}) {
             const toolResults = [];
             for (const toolCall of toolCalls) {
                 opts.onToolCall?.(toolCall);
+                // Tool scoping for delegated sub-agents: reject any tool outside the
+                // agent's allowlist up front — no permission prompt, no execution.
+                if (opts.allowedTools && !opts.allowedTools.includes(toolCall.tool)) {
+                    const denied = {
+                        success: false,
+                        output: '',
+                        error: `Tool "${toolCall.tool}" is not available to this sub-agent.`,
+                        tool: toolCall.tool,
+                        parameters: toolCall.parameters,
+                    };
+                    opts.onToolResult?.(denied, toolCall);
+                    actions.push(createActionLog(toolCall, denied));
+                    toolResults.push(`Tool ${toolCall.tool} is not allowed for this sub-agent. Use only: ${opts.allowedTools.join(', ')}.`);
+                    continue;
+                }
                 // Permission check for dangerous tools (only when callback is provided, e.g. ACP/Zed)
                 if (opts.onRequestPermission && dangerousTools.has(toolCall.tool) && !alwaysAllowedTools.has(toolCall.tool)) {
                     const rejectResult = () => {
@@ -625,7 +780,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     }
                 }
                 let toolResult;
-                if (opts.dryRun) {
+                if (toolCall.tool === 'delegate') {
+                    toolResult = await runDelegate(toolCall);
+                }
+                else if (opts.dryRun) {
                     toolResult = {
                         success: true,
                         output: `[DRY RUN] Would execute: ${toolCall.tool}`,
@@ -750,7 +908,8 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 finalResponse: partialLines.join('\n'),
                 error: `Exceeded maximum of ${opts.maxIterations} iterations`,
             };
-            writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
+            if (!opts.nested)
+                writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
             return result;
         }
         // Self-verification: Run build/test and fix errors if needed
@@ -876,13 +1035,39 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 }
             }
         }
+        // Pipeline (Phase 2): optional automatic review pass. After a top-level run
+        // that changed files, delegate to the `reviewer` sub-agent and append its
+        // findings — guaranteeing a review stage without relying on the model to
+        // self-delegate one. Opt-in (agentAutoReview); depth-0 only; never fatal.
+        if (!opts.nested
+            && (opts.depth ?? 0) === 0
+            && !opts.dryRun
+            && config.get('agentAutoReview') === true
+            && !opts.abortSignal?.aborted
+            && actions.some(a => a.type === 'write' || a.type === 'edit' || a.type === 'delete')) {
+            try {
+                const reviewTask = `Review the changes just made for this task:\n\n${prompt}\n\nInspect the current state of the changed files (and the git diff). Report concrete issues by severity — correctness/bugs, security, then design — with file:line and a one-line fix each. If it's solid, say so briefly.`;
+                const review = await runDelegate({
+                    id: 'auto-review',
+                    tool: 'delegate',
+                    parameters: { agent: 'reviewer', task: reviewTask },
+                });
+                const body = (review.output || '').replace(/^\[reviewer\]\s*/, '').trim();
+                if (body)
+                    finalResponse += `\n\n---\n### Auto-review (reviewer)\n${body}`;
+            }
+            catch {
+                // A failed review must never fail the run.
+            }
+        }
         result = {
             success: true,
             iterations: iteration,
             actions,
             finalResponse,
         };
-        writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
+        if (!opts.nested)
+            writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
         return result;
     }
     catch (error) {
@@ -897,8 +1082,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
         return result;
     }
     finally {
-        // End session and save history
-        endSession();
+        // End session and save history. Skipped for nested runs so we don't write
+        // a separate session file or null out the parent's open session.
+        if (!opts.nested)
+            endSession();
     }
 }
 /**

package/dist/utils/agents.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Sub-agents — named, scoped agent definitions the main ("orchestrator") agent
+ * can delegate work to via the `delegate` tool. Each runs as a NESTED agent
+ * loop with its own fresh context window, an optional tool allowlist, an
+ * optional model override, and a role system prompt — then returns only its
+ * final summary to the parent. This keeps the parent's context small and lets
+ * each sub-task run with a specialist persona.
+ *
+ * Storage (mirrors personalities/skills):
+ *   - **Built-in**: hardcoded below (researcher, reviewer, tester).
+ *   - **Project**: `<workspace>/.codeep/agents/<name>.md`
+ *   - **Global**:  `~/.codeep/agents/<name>.md`
+ * Project shadows global shadows built-in, by name.
+ *
+ * File format — YAML-ish frontmatter + Markdown body (the role prompt):
+ *   ```
+ *   ---
+ *   name: reviewer
+ *   description: Reviews a diff for correctness & security
+ *   tools: [read_file, search_code, execute_command]   # allowlist; omit = all
+ *   model: glm-5.1            # optional provider/model or model override
+ *   personality: security     # optional — reuse a personality preset
+ *   maxIterations: 15         # optional budget
+ *   ---
+ *   You are a senior reviewer. Find correctness & security issues…
+ *   ```
+ */
+export type AgentScope = 'builtin' | 'project' | 'global';
+export interface AgentDef {
+    /** Slug (filename without .md, or built-in id). Lowercase, hyphens. */
+    name: string;
+    /** Human display label. */
+    displayName: string;
+    /** One-line description shown in the catalog + `/agents`. */
+    description: string;
+    /** Markdown body — the role system prompt for the sub-agent. */
+    prompt: string;
+    /** Tool allowlist. Undefined = inherit all of the parent's tools. */
+    tools?: string[];
+    /** Optional model override ("provider/model" or just "model"). */
+    model?: string;
+    /** Optional personality preset to layer on (by name). */
+    personality?: string;
+    /** Optional per-run iteration budget. */
+    maxIterations?: number;
+    scope: AgentScope;
+}
+export declare function loadAgents(workspaceRoot?: string): AgentDef[];
+export declare function findAgent(name: string, workspaceRoot?: string): AgentDef | null;
+/**
+ * The catalog block appended to the orchestrator's system prompt so the model
+ * knows which sub-agents it can `delegate` to. Empty string is never returned
+ * (built-ins always exist), but callers can choose not to inject it.
+ */
+export declare function formatAgentsForSysprompt(agents: AgentDef[]): string;
+/** `/agents` list view (mirrors formatPersonalityList). */
+export declare function formatAgentList(workspaceRoot?: string): string;

package/dist/utils/agents.js

@@ -0,0 +1,188 @@
+/**
+ * Sub-agents — named, scoped agent definitions the main ("orchestrator") agent
+ * can delegate work to via the `delegate` tool. Each runs as a NESTED agent
+ * loop with its own fresh context window, an optional tool allowlist, an
+ * optional model override, and a role system prompt — then returns only its
+ * final summary to the parent. This keeps the parent's context small and lets
+ * each sub-task run with a specialist persona.
+ *
+ * Storage (mirrors personalities/skills):
+ *   - **Built-in**: hardcoded below (researcher, reviewer, tester).
+ *   - **Project**: `<workspace>/.codeep/agents/<name>.md`
+ *   - **Global**:  `~/.codeep/agents/<name>.md`
+ * Project shadows global shadows built-in, by name.
+ *
+ * File format — YAML-ish frontmatter + Markdown body (the role prompt):
+ *   ```
+ *   ---
+ *   name: reviewer
+ *   description: Reviews a diff for correctness & security
+ *   tools: [read_file, search_code, execute_command]   # allowlist; omit = all
+ *   model: glm-5.1            # optional provider/model or model override
+ *   personality: security     # optional — reuse a personality preset
+ *   maxIterations: 15         # optional budget
+ *   ---
+ *   You are a senior reviewer. Find correctness & security issues…
+ *   ```
+ */
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+const BUILTIN = [
+    {
+        name: 'planner',
+        displayName: 'Planner',
+        description: 'Read-only planner — investigates, then returns a concrete step-by-step implementation plan.',
+        scope: 'builtin',
+        tools: ['read_file', 'search_code', 'list_files', 'find_files'],
+        prompt: `You are a planning sub-agent. Investigate, then produce a plan — do NOT write code or run commands.
+- Read the relevant files to ground the plan in how the code actually works.
+- Return a concise, numbered, step-by-step plan: each step names the file(s) to touch and what changes.
+- Call out risks, assumptions, and anything the implementer must verify.
+- Keep it actionable — the implementer will follow it directly. No code, just the plan.`,
+    },
+    {
+        name: 'researcher',
+        displayName: 'Researcher',
+        description: 'Read-only explorer — digs through the codebase / web and returns a tight summary.',
+        scope: 'builtin',
+        tools: ['read_file', 'search_code', 'list_files', 'find_files', 'web_search', 'web_read', 'fetch_url'],
+        prompt: `You are a research sub-agent. Your job is to investigate and report — never modify anything.
+- Explore the codebase (and the web when relevant) to answer the task precisely.
+- You CANNOT write or edit files or run commands — read and search only.
+- Return a tight, structured summary: the answer first, then the specific files/lines/sources that back it up.
+- Omit dead ends. The caller only sees your final message, so make it self-contained.`,
+    },
+    {
+        name: 'reviewer',
+        displayName: 'Reviewer',
+        description: 'Read-only senior review — finds correctness, security, and design issues.',
+        scope: 'builtin',
+        tools: ['read_file', 'search_code', 'list_files', 'find_files', 'execute_command'],
+        personality: 'security',
+        prompt: `You are a senior code-review sub-agent. Review only — do not change code.
+- Read the relevant files (and run read-only git/inspection commands) to understand the change in context.
+- Report concrete issues grouped by severity: correctness/bugs, security, then design/naming/tests.
+- Cite file:line for each finding and suggest the fix in one sentence.
+- If it's solid, say so briefly — don't invent problems.`,
+    },
+    {
+        name: 'tester',
+        displayName: 'Tester',
+        description: 'Writes and runs tests for a target, then reports pass/fail.',
+        scope: 'builtin',
+        tools: ['read_file', 'write_file', 'edit_file', 'search_code', 'list_files', 'find_files', 'execute_command'],
+        prompt: `You are a testing sub-agent. Write focused tests for the target and run them.
+- Match the project's existing test framework and conventions (look at neighbouring tests first).
+- Cover the happy path plus the obvious edge cases; don't over-test.
+- Run the tests and iterate until they pass (or you've found a real bug — then report it).
+- Final message: what you added, the command to run them, and the pass/fail result.`,
+    },
+];
+/** Parse `tools: [a, b]` or `tools: a, b` out of a frontmatter line value. */
+function parseToolsValue(raw) {
+    const inner = raw.trim().replace(/^\[/, '').replace(/\]$/, '');
+    const list = inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    return list.length > 0 ? list : undefined;
+}
+/** Load custom agents from a `.codeep/agents/` directory. */
+function loadFromDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const slug = entry.slice(0, -3).toLowerCase();
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(slug))
+            continue;
+        try {
+            const raw = readFileSync(join(dir, entry), 'utf8');
+            if (raw.length > 64 * 1024)
+                continue;
+            const fm = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+            const meta = {};
+            let body = raw;
+            if (fm) {
+                body = fm[2];
+                for (const line of fm[1].split('\n')) {
+                    const m = line.match(/^([a-zA-Z]+):\s*(.*)$/);
+                    if (m)
+                        meta[m[1].toLowerCase()] = m[2].trim();
+                }
+            }
+            const displayName = meta.name || slug;
+            const description = meta.description || `Custom agent from ${entry}`;
+            const tools = meta.tools ? parseToolsValue(meta.tools) : undefined;
+            const maxIterations = meta.maxiterations ? parseInt(meta.maxiterations, 10) : undefined;
+            out.push({
+                name: slug,
+                displayName,
+                description: description.length > 200 ? description.slice(0, 197) + '…' : description,
+                prompt: body.trim(),
+                tools,
+                model: meta.model || undefined,
+                personality: meta.personality || undefined,
+                maxIterations: Number.isFinite(maxIterations) ? maxIterations : undefined,
+                scope,
+            });
+        }
+        catch {
+            // Skip broken files — never crash agent loading.
+        }
+    }
+    return out;
+}
+export function loadAgents(workspaceRoot) {
+    const project = workspaceRoot ? loadFromDir(join(workspaceRoot, '.codeep', 'agents'), 'project') : [];
+    const global = loadFromDir(join(homedir(), '.codeep', 'agents'), 'global');
+    const byName = new Map();
+    for (const a of BUILTIN)
+        byName.set(a.name, a);
+    for (const a of global)
+        byName.set(a.name, a);
+    for (const a of project)
+        byName.set(a.name, a);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findAgent(name, workspaceRoot) {
+    const lower = name.toLowerCase();
+    return loadAgents(workspaceRoot).find((a) => a.name === lower) ?? null;
+}
+/**
+ * The catalog block appended to the orchestrator's system prompt so the model
+ * knows which sub-agents it can `delegate` to. Empty string is never returned
+ * (built-ins always exist), but callers can choose not to inject it.
+ */
+export function formatAgentsForSysprompt(agents) {
+    if (agents.length === 0)
+        return '';
+    const lines = [
+        '\n\n## Sub-agents (delegation)',
+        'You can delegate a self-contained sub-task to a specialist sub-agent with the `delegate` tool. It runs in its own fresh context and returns only a summary — use it to keep your own context focused (e.g. send a researcher to explore, a reviewer to critique, a tester to write tests). Available agents:',
+        '',
+    ];
+    for (const a of agents)
+        lines.push(`- \`${a.name}\` — ${a.description}`);
+    lines.push('', 'Call `delegate({ "agent": "<name>", "task": "<clear, self-contained instruction>" })`. Omit `agent` for a general-purpose sub-agent. Do the work yourself for small/quick tasks — delegation has overhead.');
+    return lines.join('\n');
+}
+/** `/agents` list view (mirrors formatPersonalityList). */
+export function formatAgentList(workspaceRoot) {
+    const list = loadAgents(workspaceRoot);
+    const lines = ['## Sub-agents', '', 'The agent can `delegate` self-contained sub-tasks to these. Each runs in its own context and returns a summary.', '', '| Name | Scope | Tools | Description |', '|---|---|---|---|'];
+    for (const a of list) {
+        const tag = a.scope === 'builtin' ? 'built-in' : a.scope;
+        const tools = a.tools ? `${a.tools.length} scoped` : 'all';
+        lines.push(`| \`${a.name}\` | ${tag} | ${tools} | ${a.description} |`);
+    }
+    lines.push('', 'Add your own: drop a `<name>.md` with frontmatter (name, description, tools, model, personality) in `.codeep/agents/` (project) or `~/.codeep/agents/` (global).');
+    return lines.join('\n');
+}

package/dist/utils/codeepCloud.d.ts

@@ -110,4 +110,9 @@ export declare function pullLearning(): Promise<{
 } | null>;
 export declare function pushProfiles(profiles: Record<string, object>): Promise<boolean>;
 export declare function pullProfiles(): Promise<Record<string, object> | null>;
+/** Push the local global profile.md to the dashboard. */
+export declare function pushUserProfile(): Promise<boolean>;
+/** Pull the dashboard profile.md — additive: writes only when no local profile
+ *  exists. Returns 1 if written, 0 if skipped, null on error / not linked. */
+export declare function pullUserProfile(): Promise<number | null>;
 export declare function syncMemoryNotes(projectName: string, notes: string[]): Promise<void>;

package/dist/utils/codeepCloud.js

@@ -421,6 +421,64 @@ export async function pullProfiles() {
         return null;
     }
 }
+// ─── User profile sync (~/.codeep/profile.md) ──────────────────────────────────
+//
+// The hand-written global "About me" profile. One blob per user. Pull is
+// additive — it writes only when no local profile.md exists, so a web edit can
+// never clobber local work (same philosophy as the personalities/commands sync).
+function userProfilePath() {
+    return join(homedir(), '.codeep', 'profile.md');
+}
+/** Push the local global profile.md to the dashboard. */
+export async function pushUserProfile() {
+    const syncToken = getSyncToken();
+    if (!syncToken)
+        return false;
+    const path = userProfilePath();
+    if (!existsSync(path))
+        return false;
+    let content = '';
+    try {
+        content = readFileSync(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (content.length > 32 * 1024)
+        content = content.slice(0, 32 * 1024);
+    const res = await fetchWithRetry(`${API_BASE}/api/sync/user-profile`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-sync-token': syncToken },
+        body: JSON.stringify({ content }),
+    });
+    return res?.ok ?? false;
+}
+/** Pull the dashboard profile.md — additive: writes only when no local profile
+ *  exists. Returns 1 if written, 0 if skipped, null on error / not linked. */
+export async function pullUserProfile() {
+    const syncToken = getSyncToken();
+    if (!syncToken)
+        return null;
+    const res = await fetchWithRetry(`${API_BASE}/api/sync/user-profile`, { headers: { 'x-sync-token': syncToken } });
+    if (!res?.ok)
+        return null;
+    try {
+        const data = await res.json();
+        if (!data.ok || !data.content)
+            return 0;
+        const path = userProfilePath();
+        if (existsSync(path))
+            return 0; // never clobber local
+        const dir = join(homedir(), '.codeep');
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(path, data.content);
+        return 1;
+    }
+    catch {
+        return null;
+    }
+}
 export async function syncMemoryNotes(projectName, notes) {
     const syncToken = getSyncToken();
     if (!syncToken)