@apolloyh/apollo-agent 0.1.5 → 0.1.7

package/.apollo/config.example.json

@@ -1,6 +1,7 @@
 {
   "workspaceRoot": ".",
   "systemPrompt": "",
+  "modeInstructions": "",
   "maxTurns": 40,
   "context": {
     "maxChars": 262144,

package/README.md

@@ -35,9 +35,18 @@ apollo -r <session-id>
 
 Apollo loads project `.apollo/.env`, project `.env`, then user-level `~/.apollo/.env`; use `--env-file <path>` to override discovery.
 
-Optional project configuration lives at `.apollo/config.json`; Apollo also reads the legacy
-`agent.config.json` during migration. Copy `.apollo/config.example.json` to get started.
-Set `systemPrompt` there to append stable custom system instructions; restart Apollo to reload them.
+Apollo creates global defaults at `~/.apollo/config.json` and copies the complete option
+reference to `~/.apollo/config.example.json`. Project overrides live at
+`.apollo/config.json`; Apollo also reads the legacy `agent.config.json` during migration.
+Configuration layers as built-in defaults → user config → project config → `--config`.
+Set `systemPrompt` in either config to append stable custom system instructions; restart Apollo to reload them.
+
+Apollo also loads `~/.apollo/APOLLO.md` followed by the project `APOLLO.md` (lowercase
+`apollo.md` is accepted). If no project Apollo file exists, the standard `AGENTS.md` and
+`.apollo/instructions.md` paths remain supported. These instructions are frozen for the session.
+
+While Apollo is working, type and press Enter to queue another user message. Queued messages
+run in FIFO order after the current turn; press Esc to interrupt the current turn safely.
 
 Commands: `/help` · `/skills` · `/agents` · `/sessions` · `/resume` · `/verbose` · `/stream` · `/clear` · `/exit`
 

package/dist/brand.d.ts

@@ -1,7 +1,7 @@
 /** Product identity — single source of truth for display strings. */
 export declare const PRODUCT: {
     readonly name: "Apollo";
-    readonly version: "0.1.5";
+    readonly version: "0.1.7";
     readonly tagline: "Your personal agent — answer first, act when needed.";
     readonly packageName: "@apolloyh/apollo-agent";
     readonly userAgent: "ApolloAgent/0.1";

package/dist/brand.js

@@ -1,7 +1,7 @@
 /** Product identity — single source of truth for display strings. */
 export const PRODUCT = {
     name: "Apollo",
-    version: "0.1.5",
+    version: "0.1.7",
     tagline: "Your personal agent — answer first, act when needed.",
     packageName: "@apolloyh/apollo-agent",
     userAgent: "ApolloAgent/0.1",

package/dist/config.d.ts

@@ -6,6 +6,14 @@ export declare function ensureUserEnvFile(): {
     path: string;
     created: boolean;
 };
+export declare function ensureUserConfigFile(): {
+    path: string;
+    created: boolean;
+};
+export declare function ensureUserConfigExampleFile(): {
+    path: string;
+    created: boolean;
+};
 export declare function loadAgentConfig(configPath?: string): Promise<AgentConfig>;
 /**
  * Load an explicit env file, or discover project env then ~/.apollo/.env.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzE,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,cAAc,EA4B1C,CAAC;AAsBF,eAAO,MAAM,0BAA0B,oHAC4E,CAAC;AAWpH,wBAAgB,iBAAiB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAatE;AAED,wBAAsB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA0B/E;AAiBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAwB3F;AAYD,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,SAAS,CAkCrF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzE,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,cAAc,EA4B1C,CAAC;AAsBF,eAAO,MAAM,0BAA0B,oHAC4E,CAAC;AAwBpH,wBAAgB,iBAAiB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAatE;AAED,wBAAgB,oBAAoB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAazE;AAED,wBAAgB,2BAA2B,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAchF;AAED,wBAAsB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAkD/E;AAiBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAwB3F;AAYD,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,SAAS,CAkCrF"}

package/dist/config.js

@@ -2,6 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 /** Default subagents — Claude Code–style Task roles. */
 export const DEFAULT_AGENTS = [
     {
@@ -57,6 +58,15 @@ ANTHROPIC_AUTH_TOKEN=
 # ANTHROPIC_BASE_URL=https://api.anthropic.com
 # ANTHROPIC_MODEL=claude-haiku-4-5
 `;
+const USER_CONFIG_TEMPLATE = `${JSON.stringify({
+    systemPrompt: "",
+    maxTurns: defaultConfig.maxTurns,
+    context: defaultConfig.context,
+    permissions: defaultConfig.permissions,
+    skills: defaultConfig.skills,
+    mcpServers: defaultConfig.mcpServers,
+}, null, 2)}\n`;
+const BUNDLED_CONFIG_EXAMPLE_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../.apollo/config.example.json");
 export function ensureUserEnvFile() {
     const directory = path.join(os.homedir(), ".apollo");
     const envPath = path.join(directory, ".env");
@@ -73,27 +83,86 @@ export function ensureUserEnvFile() {
         throw error;
     }
 }
+export function ensureUserConfigFile() {
+    const directory = path.join(os.homedir(), ".apollo");
+    const configPath = path.join(directory, "config.json");
+    if (fsSync.existsSync(configPath))
+        return { path: configPath, created: false };
+    fsSync.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    try {
+        fsSync.writeFileSync(configPath, USER_CONFIG_TEMPLATE, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        return { path: configPath, created: true };
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return { path: configPath, created: false };
+        throw error;
+    }
+}
+export function ensureUserConfigExampleFile() {
+    const directory = path.join(os.homedir(), ".apollo");
+    const examplePath = path.join(directory, "config.example.json");
+    if (fsSync.existsSync(examplePath))
+        return { path: examplePath, created: false };
+    const template = fsSync.readFileSync(BUNDLED_CONFIG_EXAMPLE_PATH, "utf8");
+    fsSync.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    try {
+        fsSync.writeFileSync(examplePath, template, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        return { path: examplePath, created: true };
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return { path: examplePath, created: false };
+        throw error;
+    }
+}
 export async function loadAgentConfig(configPath) {
-    const discoveredPath = configPath ?? [DEFAULT_CONFIG_PATH, LEGACY_CONFIG_PATH].find(fsSync.existsSync);
-    if (!discoveredPath) {
-        return { ...defaultConfig, workspaceRoot: path.resolve(defaultConfig.workspaceRoot) };
-    }
-    const raw = await fs.readFile(discoveredPath, "utf8");
-    const parsed = JSON.parse(raw);
-    const resolvedConfigPath = path.resolve(discoveredPath);
-    const configDir = path.dirname(resolvedConfigPath);
-    const baseDir = path.basename(configDir) === ".apollo" ? path.dirname(configDir) : configDir;
-    const agents = normalizeAgents(parsed.agents ?? parsed.workers) ?? defaultConfig.agents;
-    const config = {
+    const userConfigPath = path.join(os.homedir(), ".apollo", "config.json");
+    const projectConfigPath = [DEFAULT_CONFIG_PATH, LEGACY_CONFIG_PATH].find(fsSync.existsSync);
+    const layers = [
+        ...(fsSync.existsSync(userConfigPath) ? [{ file: userConfigPath, projectScoped: false }] : []),
+        ...(projectConfigPath ? [{ file: projectConfigPath, projectScoped: true }] : []),
+        ...(configPath ? [{ file: configPath, projectScoped: true }] : []),
+    ];
+    const seen = new Set();
+    let config = {
         ...defaultConfig,
-        ...parsed,
-        workspaceRoot: path.resolve(baseDir, parsed.workspaceRoot ?? defaultConfig.workspaceRoot),
-        context: { ...defaultConfig.context, ...parsed.context },
-        permissions: { ...defaultConfig.permissions, ...parsed.permissions },
-        skills: { ...defaultConfig.skills, ...parsed.skills },
-        mcpServers: parsed.mcpServers ?? defaultConfig.mcpServers,
-        agents,
+        workspaceRoot: path.resolve(defaultConfig.workspaceRoot),
+        context: { ...defaultConfig.context },
+        permissions: { ...defaultConfig.permissions },
+        skills: { ...defaultConfig.skills },
+        mcpServers: { ...defaultConfig.mcpServers },
+        agents: [...defaultConfig.agents],
     };
+    for (const layer of layers) {
+        const resolvedConfigPath = path.resolve(layer.file);
+        if (seen.has(resolvedConfigPath))
+            continue;
+        seen.add(resolvedConfigPath);
+        const raw = await fs.readFile(resolvedConfigPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const { workers: _workers, ...overrides } = parsed;
+        if (typeof overrides.systemPrompt === "string" && !overrides.systemPrompt.trim())
+            delete overrides.systemPrompt;
+        if (typeof overrides.modeInstructions === "string" && !overrides.modeInstructions.trim())
+            delete overrides.modeInstructions;
+        const configDir = path.dirname(resolvedConfigPath);
+        const baseDir = path.basename(configDir) === ".apollo" ? path.dirname(configDir) : configDir;
+        const agents = normalizeAgents(parsed.agents ?? parsed.workers) ?? config.agents;
+        const workspaceRoot = layer.projectScoped && parsed.workspaceRoot !== undefined
+            ? path.resolve(baseDir, parsed.workspaceRoot)
+            : config.workspaceRoot;
+        config = {
+            ...config,
+            ...overrides,
+            workspaceRoot,
+            context: { ...config.context, ...parsed.context },
+            permissions: { ...config.permissions, ...parsed.permissions },
+            skills: { ...config.skills, ...parsed.skills },
+            mcpServers: { ...config.mcpServers, ...parsed.mcpServers },
+            agents,
+        };
+    }
     validateAgentConfig(config);
     return config;
 }

package/dist/index.js

@@ -4,7 +4,7 @@ import readline from "node:readline/promises";
 import { ASCII_LOGO, PRODUCT } from "./brand.js";
 import { parseArgs } from "./cli-args.js";
 import { createPastedTextBlock, pastedTextPreview, renderInputView, resolvePastedText, } from "./cli-input.js";
-import { ensureUserEnvFile, loadAgentConfig, loadEnvFile, loadLlmConfig, MISSING_AUTH_TOKEN_MESSAGE, } from "./config.js";
+import { ensureUserEnvFile, ensureUserConfigExampleFile, ensureUserConfigFile, loadAgentConfig, loadEnvFile, loadLlmConfig, MISSING_AUTH_TOKEN_MESSAGE, } from "./config.js";
 import { pickSpinnerVerb } from "./constants/spinner-verbs.js";
 import { QueryEngine } from "./runtime/query-engine.js";
 import { createCliApprovalProvider } from "./runtime/permissions.js";
@@ -14,7 +14,6 @@ import { ThoughtFoldManager } from "./thought-fold.js";
 import { workflowStatusBar } from "./coordinator/workflow.js";
 import { CliTraceRenderer, stripTerminalEscapes } from "./trace.js";
 let activeCliInput;
-let pinnedCliInput;
 let modalActive = false;
 let resolveModal;
 let modalDone;
@@ -59,6 +58,8 @@ function filterSlashCommands(buffer) {
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     const userEnv = ensureUserEnvFile();
+    const userConfig = ensureUserConfigFile();
+    const userConfigExample = ensureUserConfigExampleFile();
     loadEnvFile(args.envPath);
     const task = args.task ?? (stdin.isTTY ? undefined : (await readStdin()).trim());
     if (!task && !stdin.isTTY) {
@@ -99,6 +100,7 @@ async function main() {
     const rendererSink = renderer.sink();
     const taskActivity = new TaskActivityLog();
     const inputHistory = [];
+    const pendingUserMessages = [];
     // traceSink closes over the runtime, but the runtime is created after this. Hold it in a
     // mutable ref that createRuntime populates, so goal_status events don't hit a TDZ (task mode
     // never reaches the interactive `runtime` binding). Also lets SIGINT close whichever is active.
@@ -241,6 +243,12 @@ async function main() {
     if (userEnv.created) {
         stdout.write(`\nCreated ${shortenHome(userEnv.path)}. Add ANTHROPIC_AUTH_TOKEN there, then restart Apollo.\n`);
     }
+    if (userConfig.created) {
+        stdout.write(`Created ${shortenHome(userConfig.path)} with default settings.\n`);
+    }
+    if (userConfigExample.created) {
+        stdout.write(`Created ${shortenHome(userConfigExample.path)} with all configuration options.\n`);
+    }
     const approvalProvider = createCliApprovalProvider(agentConfig, traceSink, () => yolo, {
         beforePrompt: () => {
             stopLiveStatus("none");
@@ -274,7 +282,7 @@ async function main() {
                 await modalDone;
                 continue;
             }
-            const text = (await readCliLine({ color: traceOptions.color, history: inputHistory })).trim();
+            const text = (pendingUserMessages.shift() ?? await readCliLine({ color: traceOptions.color, history: inputHistory })).trim();
             if (!text)
                 continue;
             if (text === "/exit" || text === "/quit") {
@@ -406,12 +414,12 @@ async function main() {
                 outcomePrintedThisTurn = false;
                 activeVerb = pickSpinnerVerb(goalBody);
                 const firstPrompt = `Start Goal mode.\nGoal: ${goalBody}\nMake the first concrete step. Use tools as needed.\nEnd with GOAL_PROGRESS / GOAL_DONE / GOAL_BLOCKED / GOAL_FAILED.`;
-                startPinnedCliInput(traceOptions.color);
+                const turnInput = startTurnInput(runtime, traceOptions.color, inputHistory, pendingUserMessages);
                 try {
                     await runGoalLoop(runtime, renderer, thoughtFold, traceOptions, firstPrompt);
                 }
                 finally {
-                    stopPinnedCliInput();
+                    await turnInput.stop();
                 }
                 continue;
             }
@@ -531,12 +539,12 @@ async function main() {
                 continue;
             }
             // ── user turn ──────────────────────────────────────────────
-            // Keep an empty input chrome pinned below streaming output while this turn runs.
+            // Keep a live queue input below streaming output while this turn runs.
             runningTaskCount = 0;
             assistantResponseStarted = false;
             outcomePrintedThisTurn = false;
             activeVerb = pickSpinnerVerb(text);
-            startPinnedCliInput(traceOptions.color);
+            const turnInput = startTurnInput(runtime, traceOptions.color, inputHistory, pendingUserMessages);
             try {
                 if (!llmConfig.authToken)
                     throw new Error(MISSING_AUTH_TOKEN_MESSAGE);
@@ -558,7 +566,7 @@ async function main() {
                     writeAboveActiveInput(runtime.renderWorkflowBar(traceOptions.color));
                 }
                 void runtime.saveCurrentSession().catch(() => null);
-                stopPinnedCliInput();
+                await turnInput.stop();
             }
         }
         const sessionId = runtime.getSessionId();
@@ -952,67 +960,42 @@ function writeAboveActiveInput(text) {
         input?.renderAfterExternalOutput();
     }
 }
-function startPinnedCliInput(color) {
-    if (!stdin.isTTY || !stdout.isTTY || modalActive)
-        return;
-    stopPinnedCliInput();
-    let renderedLines = 0;
-    let renderedCursorLine = 0;
-    const clear = () => {
-        if (renderedLines === 0)
-            return;
-        if (renderedCursorLine > 0)
-            stdout.write(`\x1b[${renderedCursorLine}A\r`);
-        else
-            stdout.write("\r");
-        for (let index = 0; index < renderedLines; index += 1) {
-            stdout.write("\x1b[2K");
-            if (index < renderedLines - 1)
-                stdout.write("\x1b[1B\r");
+function startTurnInput(runtime, color, history, pendingMessages) {
+    if (!stdin.isTTY || !stdout.isTTY)
+        return { stop: async () => undefined };
+    let accepting = true;
+    const done = (async () => {
+        while (accepting) {
+            if (modalActive && modalDone) {
+                await modalDone;
+                continue;
+            }
+            const value = await readCliLine({
+                color,
+                history,
+                queueMode: true,
+                onEscape: () => {
+                    const cancelled = runtime.cancelCurrentTurn();
+                    if (cancelled)
+                        accepting = false;
+                    return cancelled;
+                },
+            });
+            const queued = value.trim();
+            if (queued)
+                pendingMessages.push(queued);
+            if (!accepting)
+                break;
         }
-        if (renderedLines > 1)
-            stdout.write(`\x1b[${renderedLines - 1}A\r`);
-        renderedLines = 0;
-        renderedCursorLine = 0;
-    };
-    const render = () => {
-        if (modalActive || activeCliInput !== pinnedCliInput)
-            return;
-        clear();
-        const statusLine = renderLiveStatusLine(color);
-        const lines = [
-            ...(statusLine ? [statusLine] : []),
-            renderInputBorder("top", color),
-            renderInputPrompt(color),
-            renderInputBorder("bottom", color),
-        ];
-        stdout.write(lines.join("\n"));
-        renderedLines = lines.length;
-        renderedCursorLine = statusLine ? 2 : 1;
-        const rowsBelowInput = lines.length - 1 - renderedCursorLine;
-        stdout.write(`\x1b[${rowsBelowInput}A\r\x1b[3G`);
-    };
-    const pinned = {
-        clearForExternalOutput: clear,
-        renderAfterExternalOutput: render,
-        cancelForModal: () => {
-            clear();
-            if (activeCliInput === pinned)
-                activeCliInput = undefined;
+    })();
+    return {
+        stop: async () => {
+            accepting = false;
+            activeCliInput?.cancelForModal();
+            await done;
+            stdout.write("\x1b[?25h");
         },
     };
-    pinnedCliInput = pinned;
-    activeCliInput = pinned;
-    render();
-}
-function stopPinnedCliInput() {
-    const pinned = pinnedCliInput;
-    if (!pinned)
-        return;
-    pinned.clearForExternalOutput();
-    if (activeCliInput === pinned)
-        activeCliInput = undefined;
-    pinnedCliInput = undefined;
 }
 async function readCliLine(options) {
     if (!stdin.isTTY || !stdout.isTTY) {
@@ -1044,6 +1027,8 @@ async function readCliLine(options) {
         done = true;
         if (onData)
             stdin.off("data", onData);
+        if (stdin.isTTY)
+            stdout.write("\x1b[?25h");
         if (stdin.isTTY)
             stdout.write("\x1b[?2004l");
         if (stdin.isTTY)
@@ -1059,8 +1044,10 @@ async function readCliLine(options) {
             lines.push(liveStatusLine);
         lines.push(renderInputBorder("top", options.color));
         const view = renderInputView(buffer, cursor, inputContentWidth(), pastedTextBlocks);
-        lines.push(`${renderInputPrompt(options.color)}${view.lines[0] ?? ""}`);
-        lines.push(...view.lines.slice(1).map((line) => `  ${line}`));
+        const idleQueue = options.queueMode && !buffer;
+        lines.push(`${renderInputPrompt(options.color)}${idleQueue ? renderTurnInputHint(options.color) : (view.lines[0] ?? "")}`);
+        if (!idleQueue)
+            lines.push(...view.lines.slice(1).map((line) => `  ${line}`));
         if (paletteOpen) {
             const filtered = filterSlashCommands(buffer);
             lines.push(...renderSlashPaletteLines(selected, options.color, filtered, buffer));
@@ -1096,6 +1083,7 @@ async function readCliLine(options) {
         renderedCursorLine = (renderLiveStatusLine(options.color) ? 2 : 1) + view.cursorLine;
         const rowsBelowInput = lines.length - 1 - renderedCursorLine;
         stdout.write(`\x1b[${rowsBelowInput}A\r\x1b[${3 + view.cursorWidth}G`);
+        stdout.write(options.queueMode && !buffer ? "\x1b[?25l" : "\x1b[?25h");
     };
     const finish = (value) => {
         clearRendered();
@@ -1106,7 +1094,14 @@ async function readCliLine(options) {
             if (options.history.length > 100)
                 options.history.splice(0, options.history.length - 100);
             const preview = pastedTextPreview(value, pastedTextBlocks).replace(/\n/g, " ↵ ").replace(/\t/g, "  ");
-            stdout.write(`${renderInputBorder("top", options.color)}\n${renderInputPrompt(options.color)}${preview === value ? submittedInputLabel(resolvedValue) : preview}\n${renderInputBorder("bottom", options.color)}\n`);
+            const submitted = preview === value ? submittedInputLabel(resolvedValue) : preview;
+            if (options.queueMode) {
+                const label = options.color ? "\x1b[90m• Queued\x1b[0m" : "• Queued";
+                stdout.write(`${label} ${submitted}\n`);
+            }
+            else {
+                stdout.write(`${renderInputBorder("top", options.color)}\n${renderInputPrompt(options.color)}${submitted}\n${renderInputBorder("bottom", options.color)}\n`);
+            }
         }
         complete(resolvedValue);
     };
@@ -1174,7 +1169,13 @@ async function readCliLine(options) {
                 finish("/exit");
             return;
         }
+        if (chunk === "\x1b" && options.onEscape?.()) {
+            finish("");
+            return;
+        }
         if (chunk === "\r" || chunk === "\n") {
+            if (options.queueMode && !buffer)
+                return;
             finish(buffer);
             return;
         }
@@ -1364,10 +1365,6 @@ function endModalInput() {
     resolveModal?.();
     resolveModal = undefined;
     modalDone = undefined;
-    if (pinnedCliInput && !activeCliInput) {
-        activeCliInput = pinnedCliInput;
-        pinnedCliInput.renderAfterExternalOutput();
-    }
 }
 async function askPlainQuestion(prompt) {
     const wasRaw = stdin.isTTY ? stdin.isRaw : false;
@@ -1610,6 +1607,10 @@ function compactLine(text, max) {
 function renderInputPrompt(useColor) {
     return useColor ? "\x1b[38;2;96;165;250m›\x1b[0m " : "› ";
 }
+function renderTurnInputHint(useColor) {
+    const hint = "Type to queue a message · Esc to interrupt";
+    return useColor ? `\x1b[90m${hint}\x1b[0m` : hint;
+}
 function renderLiveStatusLine(useColor) {
     if (!liveStatus)
         return undefined;

package/dist/project-instructions.d.ts

@@ -1,8 +1,7 @@
-/** Same spirit as CLAUDE.md / AGENTS.md discovery. */
-export declare const PROJECT_INSTRUCTION_FILES: readonly ["APOLLO.md", "CLAUDE.md", "AGENTS.md", ".apollo/instructions.md", ".claude/CLAUDE.md"];
+export declare const PROJECT_INSTRUCTION_FILES: readonly ["APOLLO.md", "apollo.md", "AGENTS.md", ".apollo/instructions.md"];
 export type ProjectInstructions = {
     path: string;
     content: string;
 };
-export declare function loadProjectInstructions(workspaceRoot: string, maxChars?: number): Promise<ProjectInstructions | null>;
+export declare function loadProjectInstructions(workspaceRoot: string, maxChars?: number, userHome?: string): Promise<ProjectInstructions | null>;
 //# sourceMappingURL=project-instructions.d.ts.map

package/dist/project-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-instructions.d.ts","sourceRoot":"","sources":["../src/project-instructions.ts"],"names":[],"mappings":"AAOA,sDAAsD;AACtD,eAAO,MAAM,yBAAyB,kGAM5B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,QAAQ,SAAQ,GACf,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAgBrC"}
+{"version":3,"file":"project-instructions.d.ts","sourceRoot":"","sources":["../src/project-instructions.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,yBAAyB,6EAK5B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,QAAQ,SAAQ,EAChB,QAAQ,SAAe,GACtB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAgCrC"}

package/dist/project-instructions.js

@@ -1,18 +1,27 @@
-/**
- * Claude Code–style project instructions.
- * Loads the first matching file from the workspace root (in order).
- */
+/** Apollo project instructions. Loads the first matching workspace file in order. */
 import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { safeRealResolve } from "./utils.js";
-/** Same spirit as CLAUDE.md / AGENTS.md discovery. */
 export const PROJECT_INSTRUCTION_FILES = [
     "APOLLO.md",
-    "CLAUDE.md",
+    "apollo.md",
     "AGENTS.md",
     ".apollo/instructions.md",
-    ".claude/CLAUDE.md",
 ];
-export async function loadProjectInstructions(workspaceRoot, maxChars = 24000) {
+export async function loadProjectInstructions(workspaceRoot, maxChars = 24000, userHome = os.homedir()) {
+    const loaded = [];
+    for (const fileName of ["APOLLO.md", "apollo.md"]) {
+        try {
+            const content = (await fs.readFile(path.join(userHome, ".apollo", fileName), "utf8")).trim();
+            if (content)
+                loaded.push({ path: `~/.apollo/${fileName}`, content });
+            break;
+        }
+        catch {
+            // User-level instructions are optional.
+        }
+    }
     for (const rel of PROJECT_INSTRUCTION_FILES) {
         try {
             const full = await safeRealResolve(workspaceRoot, rel);
@@ -20,14 +29,20 @@ export async function loadProjectInstructions(workspaceRoot, maxChars = 24000) {
             const content = raw.trim();
             if (!content)
                 continue;
-            return {
-                path: rel,
-                content: content.length > maxChars ? `${content.slice(0, maxChars)}\n\n…(truncated)` : content,
-            };
+            loaded.push({ path: rel, content });
+            break;
         }
         catch {
             // try next
         }
     }
-    return null;
+    if (!loaded.length)
+        return null;
+    const combined = loaded
+        .map((instruction) => `## ${instruction.path}\n${instruction.content}`)
+        .join("\n\n");
+    return {
+        path: loaded.map((instruction) => instruction.path).join(" + "),
+        content: combined.length > maxChars ? `${combined.slice(0, maxChars)}\n\n…(truncated)` : combined,
+    };
 }

package/dist/runtime/prompt-builder.d.ts

@@ -3,7 +3,7 @@ type PromptBuilderOptions = {
     agentConfig: AgentConfig;
     tools: AnthropicTool[];
     subagent?: SubagentConfig;
-    /** Claude Code–style project instructions (APOLLO.md / CLAUDE.md / AGENTS.md) */
+    /** Apollo project instructions (APOLLO.md / AGENTS.md). */
     projectInstructions?: {
         path: string;
         content: string;

package/dist/runtime/prompt-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../../src/runtime/prompt-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI9E,KAAK,oBAAoB,GAAG;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,iFAAiF;IACjF,mBAAmB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChE,CAAC;AAEF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAE1D,KAAK,IAAI,MAAM;IAqBf,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,yBAAyB;IAOjC,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,WAAW;CAQpB"}
+{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../../src/runtime/prompt-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI9E,KAAK,oBAAoB,GAAG;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChE,CAAC;AAEF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAE1D,KAAK,IAAI,MAAM;IAqBf,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,yBAAyB;IAOjC,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,WAAW;CAQpB"}

package/dist/runtime/prompt-builder.js

@@ -55,7 +55,7 @@ ${PRODUCT.tagline}`;
         if (!proj?.content)
             return "";
         return `# Project Instructions
-These instructions come from \`${proj.path}\` in the workspace. Follow them for this project.
+These instructions were loaded from \`${proj.path}\`. Follow them for this project; project-level instructions take precedence over user-level instructions when they conflict.
 
 ${proj.content}`;
     }

package/docs/sdk.md

@@ -89,7 +89,7 @@ const engine = await createQueryEngine({
 
 | 参数 | 类型 | 说明 |
 |---|---|---|
-| `configPath` | `string` | Agent 配置路径；默认发现 `.apollo/config.json`，兼容旧 `agent.config.json` |
+| `configPath` | `string` | Agent 显式配置路径；在用户配置和项目配置之后覆盖，默认还会发现 `~/.apollo/config.json`、`.apollo/config.json`，并兼容旧 `agent.config.json` |
 | `envPath` | `string` | 可选环境变量文件；未提供模型配置时默认发现 `.apollo/.env`，然后 `.env` |
 | `agentConfig` | `AgentConfig` | 直接传入完整 Agent 配置；优先于 `configPath` |
 | `llmConfig` | `LlmConfig` | 直接传入模型配置；优先于环境变量 |
@@ -104,7 +104,7 @@ const engine = await createQueryEngine({
 
 ## 系统提示词与缓存
 
-`.apollo/config.json` 可以配置：
+`~/.apollo/config.json` 和项目的 `.apollo/config.json` 都可以配置：
 
 ```json
 {
@@ -114,6 +114,10 @@ const engine = await createQueryEngine({
 
 Engine 创建时读取配置，首次请求时拼接 System Prompt 和工具定义，随后在该 Engine 生命周期内冻结。修改配置文件不会影响已经存在的 Engine，必须关闭并创建新 Engine。
 
+配置合并顺序为：内置默认值 → 用户配置 → 项目配置 → `configPath`。用户配置中的 `workspaceRoot` 会被忽略，避免全局配置把所有项目锁定到用户目录；工作区路径由项目配置或显式配置决定。
+
+系统提示词还会依次拼接用户级 `~/.apollo/APOLLO.md` 和项目级 `APOLLO.md`（兼容小写 `apollo.md`）。如果项目中没有 Apollo 指令文件，则继续读取通用的 `AGENTS.md` 或 `.apollo/instructions.md`。指令在 Engine 首次请求时冻结。
+
 运行中主要变化的是 `messages`，接近上下文上限时会执行语义压缩；稳定的 `system` 和 `tools` 有利于命中模型厂商的 Prompt Cache。
 
 ## 流式事件

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apolloyh/apollo-agent",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Apollo — your personal agent. Answer first, act when needed. Claude Code–style Task subagents.",
   "bin": {