@stratusagent/cli 0.2.2 → 0.2.5

package/dist/index.js

@@ -1,54 +1,28 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { appendFile, chmod, mkdir, readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { once } from 'node:events';
-import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
-import { createLocalCommandExecutor, defineLocalCommandTool, } from '@stratusagent/executor-local';
-import { createOpenAICompatibleProvider, createProviderResponseBuilder, defineProvider, } from '@stratusagent/providers';
-import { createAnthropicProvider, DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
-import { createClaudeCodeProvider } from '@stratusagent/provider-claude-code';
+import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
+import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
 import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-export const CLI_VERSION = '0.2.2';
-// The agent every run uses when no soul is configured. A Stratus agent is
-// a Stratus agent — never "the model" — whichever provider serves it.
-const DEFAULT_STRATUS_AGENT = {
-    id: 'stratus',
-    name: 'Stratus',
-    instructions: 'You are Stratus, a personal agent on the Stratus Agent platform. Be warm, direct, and concise. When asked who or what you are, you are Stratus — a Stratus agent — regardless of which model is serving the conversation.',
-};
-// Unsouled runs used to remember facts under a per-provider default agent.
-// Stratus inherits all of them: reads for the built-in agent also return
-// entries stored under the legacy ids, while new facts land under 'stratus'.
-const LEGACY_DEFAULT_AGENT_IDS = ['demo-agent', 'anthropic-agent', 'openai-agent'];
-const withLegacyDefaultMemories = (store) => ({
-    append: (agentId, content, metadata) => store.append(agentId, content, metadata),
-    async list(agentId) {
-        if (agentId !== DEFAULT_STRATUS_AGENT.id) {
-            return store.list(agentId);
-        }
-        const batches = await Promise.all([DEFAULT_STRATUS_AGENT.id, ...LEGACY_DEFAULT_AGENT_IDS].map((id) => store.list(id)));
-        return batches.flat().sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    },
-});
-const DEFAULT_CONFIG_FILENAME = 'stratus.config.json';
-const LEGACY_CONFIG_FILENAME = 'stratusclaw.config.json';
-const STRATUS_HOME_DIRNAME = '.stratus';
-const GLOBAL_CONFIG_FILENAME = 'config.json';
-const CREDENTIALS_FILENAME = 'credentials.json';
-const AGENTS_DIRNAME = 'agents';
-const DEFAULT_ANTHROPIC_BASE_URL = 'https://api.anthropic.com';
-const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
-const DEFAULT_OPENAI_MODEL = 'gpt-4.1-mini';
+import { agentsDirPath, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, readWorkingDirectory, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveRuntimeConfig as resolveStateRuntimeConfig, saveCredentials, withLegacyDefaultMemories, } from '@stratusagent/state';
+// The shared state package owns config resolution, credentials, memory, and
+// provider wiring now (the gateway uses the same code); the CLI re-exports
+// its historical surface so existing importers keep working.
+export { createFileMemoryStore } from '@stratusagent/state';
+export const CLI_VERSION = '0.2.5';
 const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 const HELP_TEXT = `Stratus Agent CLI
 
 Usage:
   stratus setup
+  stratus chat
+  stratus chat --soul ./examples/souls/ava.md
   stratus run --prompt "Use the demo tool"
   stratus run "Say hello"
   ANTHROPIC_API_KEY=... stratus run --provider anthropic "Say hello"
@@ -56,6 +30,7 @@ Usage:
   echo "Use the echo tool" | stratus run --stdin
   STRATUS_PROVIDER=openai OPENAI_API_KEY=... stratus run "Say hello"
   stratus run --config ./stratus.config.json --provider openai "Say hello"
+  stratus agents
   stratus dashboard
   stratus dashboard --port 4123 --host 0.0.0.0 --no-open
 
@@ -64,8 +39,16 @@ Commands:
                    subscription or API key), create your agent, and test it —
                    settings go to ~/.stratus/config.json, sign-ins to
                    ~/.stratus/credentials.json (0600)
+  chat             Talk with your agent — the conversation persists across turns
+                   and remembered facts accumulate; /exit or Ctrl+C to leave
   run              Execute one local Stratus Agent session
+  serve            Run stratusd, the always-on gateway: durable sessions, the
+                   whole roster live at once (each agent on its own provider),
+                   delegation, and a watchdog — Ctrl+C / SIGTERM drains cleanly
+                   (--idle-timeout <seconds>, --no-events, --config <path>)
   agent new        Create an agent identity (generates a human-ish name + avatar theme)
+  agents           List your agents: who they are, where their souls live, what
+                   they run on, what they remember (also: stratus agent list)
   dashboard        Start the local Stratus Agent dashboard and open it in your browser
   help             Show this help message
 
@@ -110,207 +93,6 @@ const stringifyValue = (value) => {
     }
     return JSON.stringify(value, null, 2);
 };
-const createDemoTool = () => defineLocalCommandTool({
-    name: 'demo.echo',
-    description: 'Return a tiny transformed summary for CLI demos through a real local process.',
-    parameters: {
-        type: 'object',
-        properties: {
-            text: { type: 'string', description: 'Text to echo back through the local process.' },
-        },
-        required: ['text'],
-    },
-    async createCommand(input) {
-        const text = typeof input.text === 'string' ? input.text : '';
-        const normalized = text.trim() || 'empty input';
-        const script = `const text = ${JSON.stringify(normalized)}; console.log(JSON.stringify({ received: text, uppercase: text.toUpperCase(), length: text.length }));`;
-        return {
-            command: process.execPath,
-            args: ['-e', script],
-        };
-    },
-    parseResult(result) {
-        return JSON.parse(result.stdout);
-    },
-});
-const createDemoProvider = () => defineProvider({
-    name: 'demo',
-    async generate({ session }) {
-        const builder = createProviderResponseBuilder();
-        const lastMessage = session.messages.at(-1);
-        if (lastMessage?.role === 'tool') {
-            const result = lastMessage.toolResult;
-            if (result?.ok) {
-                builder.addText(`The demo.echo tool finished with: ${JSON.stringify(result.output)}`);
-            }
-            else {
-                builder.addText(`The demo.echo tool did not run (${result?.error ?? 'unknown error'}), so this run ends here.`);
-            }
-            return builder.done();
-        }
-        const prompt = [...session.messages].reverse().find((message) => message.role === 'user')?.content?.trim() ?? '';
-        const wantsTool = /\b(tool|echo|uppercase|inspect)\b/i.test(prompt);
-        builder.addText(`Demo provider ready. Prompt received: ${prompt || '(empty)'}`);
-        if (wantsTool) {
-            builder.addToolCall({
-                id: `${session.id}:call:demo-echo`,
-                toolName: 'demo.echo',
-                input: { text: prompt },
-            });
-        }
-        else {
-            builder.addText('No tool call was needed, so this run stays text-only. Mention “tool” or “echo” to trigger the demo tool.');
-        }
-        return builder.done();
-    },
-});
-const MEMORY_FILENAME = 'memory.jsonl';
-const memoryFilePath = (env) => path.join(stratusHomePath(env), MEMORY_FILENAME);
-// Memory used to live under the working directory. Fold any such file into
-// the global store the first time a run happens from that directory, then
-// archive it — an upgrade must never look like the agent forgot.
-//
-// Every import first takes exclusive ownership by atomically renaming its
-// source to a unique claim file: of any competing processes, exactly one
-// wins the rename and the rest see ENOENT. A crash mid-import leaves the
-// claim file behind; later runs re-claim it the same way and finish the
-// job, with entries deduped against the global store by id. Only records
-// that parse as real memory entries are imported — malformed lines stay in
-// the archive instead of poisoning the global store for every agent.
-const isMemoryEntryLine = (line) => {
-    try {
-        const parsed = JSON.parse(line);
-        return typeof parsed === 'object' && parsed !== null
-            && typeof parsed.id === 'string'
-            && typeof parsed.agentId === 'string'
-            && typeof parsed.content === 'string';
-    }
-    catch {
-        return false;
-    }
-};
-const migrateLegacyMemory = async (env) => {
-    const legacyPath = path.join(readWorkingDirectory(env), '.stratus', MEMORY_FILENAME);
-    const globalPath = memoryFilePath(env);
-    if (legacyPath === globalPath) {
-        return;
-    }
-    const legacyDir = path.dirname(legacyPath);
-    const archivePath = `${legacyPath}.migrated`;
-    const claimAndImport = async (sourcePath) => {
-        const claimPath = path.join(legacyDir, `${MEMORY_FILENAME}.migrating-${randomUUID()}`);
-        try {
-            await rename(sourcePath, claimPath);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return; // another process owns it, or there is nothing to migrate
-            }
-            throw error;
-        }
-        const claimed = await readFile(claimPath, 'utf8');
-        let existingIds;
-        try {
-            existingIds = new Set((await readFile(globalPath, 'utf8'))
-                .split('\n')
-                .filter(isMemoryEntryLine)
-                .map((line) => JSON.parse(line).id));
-        }
-        catch {
-            existingIds = new Set();
-        }
-        const entries = claimed
-            .split('\n')
-            .filter((line) => line.trim().length > 0)
-            .filter(isMemoryEntryLine)
-            .filter((line) => !existingIds.has(JSON.parse(line).id));
-        if (entries.length > 0) {
-            await mkdir(path.dirname(globalPath), { recursive: true });
-            await appendFile(globalPath, `${entries.join('\n')}\n`);
-        }
-        // Archive by appending (never overwriting an earlier archive), then
-        // drop the claim — its content is fully preserved in the archive.
-        if (claimed.length > 0) {
-            await appendFile(archivePath, claimed.endsWith('\n') || claimed.length === 0 ? claimed : `${claimed}\n`);
-        }
-        await unlink(claimPath);
-    };
-    await claimAndImport(legacyPath);
-    // Finish any claims a crashed run left behind (both the current unique
-    // names and the fixed .migrating name from earlier versions).
-    let leftovers;
-    try {
-        leftovers = await readdir(legacyDir);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return;
-        }
-        throw error;
-    }
-    for (const name of leftovers) {
-        if (name.startsWith(`${MEMORY_FILENAME}.migrating`)) {
-            await claimAndImport(path.join(legacyDir, name));
-        }
-    }
-};
-// Agents keep the same memory across CLI runs: every remembered fact lands
-// in ~/.stratus/memory.jsonl (keyed by agent id), so the Ava you talk to
-// tomorrow — from any directory — is the Ava you talked to today. One JSON
-// entry per line, written with O_APPEND: concurrent runs each add their own
-// line instead of re-writing the file, so no run can clobber another's
-// remembered fact.
-export const createFileMemoryStore = (filePath) => {
-    const readEntries = async () => {
-        let raw;
-        try {
-            raw = await readFile(filePath, 'utf8');
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return [];
-            }
-            throw error;
-        }
-        return raw
-            .split('\n')
-            .filter((line) => line.trim().length > 0)
-            .map((line) => {
-            try {
-                return JSON.parse(line);
-            }
-            catch {
-                throw new Error(`Memory file has an invalid line: ${filePath}`);
-            }
-        });
-    };
-    return {
-        async append(agentId, content, metadata) {
-            const entry = {
-                id: `${agentId}:memory:${randomUUID()}`,
-                agentId,
-                content,
-                createdAt: new Date().toISOString(),
-                ...(metadata ? { metadata } : {}),
-            };
-            await mkdir(path.dirname(filePath), { recursive: true });
-            await appendFile(filePath, `${JSON.stringify(entry)}\n`);
-            return entry;
-        },
-        async list(agentId) {
-            // Dedupe by id at read time: even if a rare race double-imported a
-            // fact, the agent only ever sees it once.
-            const seen = new Set();
-            return (await readEntries()).filter((entry) => {
-                if (entry.agentId !== agentId || seen.has(entry.id)) {
-                    return false;
-                }
-                seen.add(entry.id);
-                return true;
-            });
-        },
-    };
-};
 const readPromptFromEnvironment = (env) => (env.stdin ?? '').trim();
 const readPromptFromStdin = async (stdin) => {
     stdin.setEncoding('utf8');
@@ -320,54 +102,6 @@ const readPromptFromStdin = async (stdin) => {
     }
     return data.trim();
 };
-const parseProviderName = (value, label) => {
-    if (value === 'demo' || value === 'openai' || value === 'anthropic') {
-        return value;
-    }
-    throw new Error(`Unsupported provider in ${label}: ${value}`);
-};
-const readProcessEnv = (env) => env.processEnv ?? process.env;
-const readWorkingDirectory = (env) => env.cwd ?? process.cwd();
-const readHomeDirectory = (env) => env.homeDir ?? os.homedir();
-const stratusHomePath = (env) => path.join(readHomeDirectory(env), STRATUS_HOME_DIRNAME);
-const globalConfigPath = (env) => path.join(stratusHomePath(env), GLOBAL_CONFIG_FILENAME);
-const credentialsPath = (env) => path.join(stratusHomePath(env), CREDENTIALS_FILENAME);
-const agentsDirPath = (env) => path.join(stratusHomePath(env), AGENTS_DIRNAME);
-const loadCredentials = async (env) => {
-    let raw;
-    try {
-        raw = await readFile(credentialsPath(env), 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return {};
-        }
-        throw error;
-    }
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Credentials file must contain a JSON object: ${credentialsPath(env)}`);
-    }
-    const credentials = {};
-    for (const provider of ['anthropic', 'openai']) {
-        const entry = parsed[provider];
-        if (typeof entry === 'object' && entry !== null && !Array.isArray(entry) &&
-            (entry.type === 'api_key' || entry.type === 'oauth_token') &&
-            typeof entry.value === 'string') {
-            credentials[provider] = entry;
-        }
-    }
-    return credentials;
-};
-// Credentials never live in a project directory or a shell profile — they
-// are written once by `stratus setup` and read on every run, 0600 so only
-// the owner can read them.
-const saveCredentials = async (env, credentials) => {
-    const filePath = credentialsPath(env);
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
-    await chmod(filePath, 0o600);
-};
 const readOptionValue = (tokens, index, flag) => {
     const value = tokens[index + 1];
     if (!value) {
@@ -414,13 +148,130 @@ export const parseCommand = (argv, env = {}) => {
         }
         return { command: 'dashboard', ...(port !== undefined ? { port } : {}), host, openBrowser };
     }
+    if (command === 'serve') {
+        const parsed = { command: 'serve', events: true };
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--config') {
+                parsed.configPath = readOptionValue(rest, index, '--config');
+                index += 1;
+                continue;
+            }
+            if (token === '--idle-timeout') {
+                const seconds = Number(readOptionValue(rest, index, '--idle-timeout'));
+                if (!Number.isFinite(seconds) || seconds < 0) {
+                    throw new Error(`Invalid value for --idle-timeout: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                parsed.idleTimeoutMs = Math.round(seconds * 1000);
+                index += 1;
+                continue;
+            }
+            if (token === '--no-events') {
+                parsed.events = false;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return parsed;
+    }
+    if (command === 'chat') {
+        const parsed = { command: 'chat', events: false, approvals: 'always' };
+        for (let index = 0; index < rest.length; index += 1) {
+            const token = rest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--provider') {
+                parsed.provider = parseProviderName(readOptionValue(rest, index, '--provider'), '--provider');
+                index += 1;
+                continue;
+            }
+            if (token === '--model') {
+                parsed.model = readOptionValue(rest, index, '--model');
+                index += 1;
+                continue;
+            }
+            if (token === '--base-url') {
+                parsed.baseUrl = readOptionValue(rest, index, '--base-url');
+                index += 1;
+                continue;
+            }
+            if (token === '--soul') {
+                parsed.soul = readOptionValue(rest, index, '--soul');
+                index += 1;
+                continue;
+            }
+            if (token === '--config') {
+                parsed.configPath = readOptionValue(rest, index, '--config');
+                index += 1;
+                continue;
+            }
+            if (token === '--approvals') {
+                const value = readOptionValue(rest, index, '--approvals');
+                if (value !== 'always' && value !== 'ask' && value !== 'never') {
+                    throw new Error(`Invalid value for --approvals: ${value}`);
+                }
+                parsed.approvals = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--max-turns') {
+                const value = Number(readOptionValue(rest, index, '--max-turns'));
+                if (!Number.isInteger(value) || value < 1) {
+                    throw new Error(`Invalid value for --max-turns: ${rest[index + 1] ?? '(missing)'}`);
+                }
+                parsed.maxTurns = value;
+                index += 1;
+                continue;
+            }
+            if (token === '--events') {
+                parsed.events = true;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return parsed;
+    }
+    if (command === 'agents' || (command === 'agent' && rest[0] === 'list')) {
+        const agentsRest = command === 'agents' ? rest : rest.slice(1);
+        let format = 'text';
+        for (let index = 0; index < agentsRest.length; index += 1) {
+            const token = agentsRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--format') {
+                const value = readOptionValue(agentsRest, index, '--format');
+                if (value !== 'text' && value !== 'json') {
+                    throw new Error(`Unsupported format: ${value}`);
+                }
+                format = value;
+                index += 1;
+                continue;
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return { command: 'agents', format };
+    }
     if (command === 'agent') {
         const [subcommand, ...agentRest] = rest;
         if (subcommand === '--help' || subcommand === '-h') {
             return { command: 'help' };
         }
         if (subcommand !== 'new') {
-            throw new Error(`Unknown agent subcommand: ${subcommand ?? '(missing)'}. Try: stratus agent new`);
+            throw new Error(`Unknown agent subcommand: ${subcommand ?? '(missing)'}. Try: stratus agent new, stratus agent list`);
         }
         let name;
         let instructions;
@@ -621,359 +472,10 @@ export const formatEvent = (event) => {
             return null;
     }
 };
-const loadConfigFile = async (configPath) => {
-    const raw = await readFile(configPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Config file must contain a JSON object: ${configPath}`);
-    }
-    const config = parsed;
-    const resolved = {};
-    if (typeof config.provider === 'string') {
-        resolved.provider = parseProviderName(config.provider, `config ${configPath}`);
-    }
-    if (typeof config.model === 'string' && config.model.length > 0) {
-        resolved.model = config.model;
-    }
-    if (typeof config.baseUrl === 'string' && config.baseUrl.length > 0) {
-        resolved.baseUrl = config.baseUrl;
-    }
-    if (typeof config.apiKeyEnv === 'string' && config.apiKeyEnv.length > 0) {
-        resolved.apiKeyEnv = config.apiKeyEnv;
-    }
-    if (typeof config.systemPrompt === 'string' && config.systemPrompt.length > 0) {
-        resolved.systemPrompt = config.systemPrompt;
-    }
-    if (typeof config.soul === 'string' && config.soul.length > 0) {
-        resolved.soul = config.soul;
-    }
-    if (typeof config.fallbackModel === 'string' && config.fallbackModel.length > 0) {
-        resolved.fallbackModel = config.fallbackModel;
-    }
-    if (typeof config.fallbackProvider === 'string') {
-        resolved.fallbackProvider = parseProviderName(config.fallbackProvider, `config ${configPath}`);
-    }
-    if (typeof config.fallbackBaseUrl === 'string' && config.fallbackBaseUrl.length > 0) {
-        resolved.fallbackBaseUrl = config.fallbackBaseUrl;
-    }
-    return resolved;
-};
-const resolveConfigLocation = async (command, env) => {
-    const processEnv = readProcessEnv(env);
-    const cwd = readWorkingDirectory(env);
-    const explicit = command.configPath ?? processEnv.STRATUS_CONFIG ?? processEnv.STRATUSCLAW_CONFIG;
-    if (explicit) {
-        return { path: path.resolve(cwd, explicit), trusted: true };
-    }
-    // Project-local configs win; the global ~/.stratus/config.json written by
-    // `stratus setup` is the fallback that makes the CLI work from anywhere.
-    const candidates = [
-        { path: path.join(cwd, DEFAULT_CONFIG_FILENAME), trusted: false },
-        { path: path.join(cwd, LEGACY_CONFIG_FILENAME), trusted: false },
-        { path: globalConfigPath(env), trusted: true },
-    ];
-    for (const candidate of candidates) {
-        try {
-            await readFile(candidate.path, 'utf8');
-            return candidate;
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== 'ENOENT') {
-                throw error;
-            }
-        }
-    }
-    return undefined;
-};
-const readNonEmptyString = (value, map) => {
-    if (typeof value !== 'string') {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (trimmed.length === 0) {
-        return undefined;
-    }
-    return map ? map(trimmed) : trimmed;
-};
-// A soul travels with the run: --soul outranks STRATUS_SOUL, which outranks
-// the config file's "soul" key.
-const resolveSoul = async (command, env, fileConfig) => {
-    const processEnv = readProcessEnv(env);
-    const soulPath = command.soul
-        ?? readNonEmptyString(processEnv.STRATUS_SOUL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL)
-        ?? fileConfig.soul;
-    if (!soulPath) {
-        return undefined;
-    }
-    const resolvedPath = path.resolve(readWorkingDirectory(env), String(soulPath));
-    let raw;
-    try {
-        raw = await readFile(resolvedPath, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            throw new Error(`Soul file not found: ${resolvedPath}`);
-        }
-        throw error;
-    }
-    try {
-        // Seeding with the resolved path keeps an unnamed soul's generated
-        // identity (name, id, avatar) stable across runs — persisted memory is
-        // keyed by that id, so it must not change between invocations.
-        return parseSoul(raw, { seed: resolvedPath });
-    }
-    catch (error) {
-        throw new Error(`Could not parse soul file ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-};
-export const resolveRuntimeConfig = async (command, env = {}) => {
-    const processEnv = readProcessEnv(env);
-    const configLocation = await resolveConfigLocation(command, env);
-    const fileConfig = configLocation ? await loadConfigFile(configLocation.path) : {};
-    const soul = await resolveSoul(command, env, fileConfig);
-    // Explicit flags and env vars outrank the soul's own provider/model hints,
-    // which outrank the config file's defaults.
-    const provider = command.provider
-        ?? readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
-        ?? readNonEmptyString(soul?.provider, (value) => parseProviderName(value, 'soul file'))
-        ?? fileConfig.provider
-        ?? 'demo';
-    if (provider === 'demo') {
-        return { provider: 'demo', ...(soul ? { soul } : {}) };
-    }
-    // A config file's model/baseUrl/apiKeyEnv were written for the provider
-    // named in that file. When a flag, env var, or soul selects a different
-    // provider, those values would point at the wrong API (e.g. an OpenAI
-    // base URL handed to the Anthropic SDK), so they are ignored. A file with
-    // no provider key predates the anthropic option, so its settings are
-    // treated as openai-specific.
-    const fileConfigApplies = (fileConfig.provider ?? 'openai') === provider;
-    // A soul's model was chosen for the soul's own provider. If a flag or env
-    // var overrides that provider, the model hint would target the wrong API
-    // (e.g. a Claude model sent to OpenAI), so it only applies when the soul
-    // names no provider or names the selected one.
-    const soulModelApplies = soul?.provider === undefined || soul.provider === provider;
-    const model = command.model
-        ?? readNonEmptyString(processEnv.STRATUS_MODEL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL)
-        ?? (soulModelApplies ? readNonEmptyString(soul?.model) : undefined)
-        ?? (fileConfigApplies ? fileConfig.model : undefined)
-        ?? (provider === 'anthropic' ? DEFAULT_ANTHROPIC_MODEL : DEFAULT_OPENAI_MODEL);
-    const apiKeyEnvName = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
-        ?? (fileConfigApplies ? fileConfig.apiKeyEnv : undefined)
-        ?? (provider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY');
-    const credentials = await loadCredentials(env);
-    // A custom endpoint chosen by an auto-discovered project config is not a
-    // place the stored sign-in ever gets sent — a cloned repository could
-    // point it anywhere. Flags and env vars are the user's own choice, and
-    // the provider's default endpoint is harmless.
-    const defaultEndpointFor = (target) => target === 'anthropic' ? DEFAULT_ANTHROPIC_BASE_URL : DEFAULT_OPENAI_BASE_URL;
-    const untrustedCustomBaseUrl = configLocation?.trusted === false
-        && command.baseUrl === undefined
-        && readNonEmptyString(processEnv.STRATUS_BASE_URL) === undefined
-        && readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL) === undefined
-        && fileConfigApplies
-        && fileConfig.baseUrl !== undefined
-        && fileConfig.baseUrl.replace(/\/+$/, '') !== defaultEndpointFor(String(provider));
-    // Env vars outrank the stored sign-in from `stratus setup`.
-    const envApiKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
-        ?? readNonEmptyString(processEnv[String(apiKeyEnvName)]);
-    const candidateCredential = credentials[provider];
-    // A bound credential ignores config URLs entirely, so an untrusted
-    // project URL cannot redirect it — only unbound stored keys are blocked.
-    const credentialIsBound = candidateCredential?.type === 'api_key' && candidateCredential.baseUrl !== undefined;
-    const storedCredential = envApiKey || (untrustedCustomBaseUrl && !credentialIsBound)
-        ? undefined
-        : candidateCredential;
-    const apiKey = envApiKey
-        ?? (storedCredential?.type === 'api_key' ? storedCredential.value : undefined);
-    const authToken = provider === 'anthropic' && storedCredential?.type === 'oauth_token'
-        ? storedCredential.value
-        : undefined;
-    // A stored key bound to an endpoint is used ONLY with that endpoint — a
-    // config file can never redirect it, not even to the official default
-    // URL (a project config could otherwise reroute a local-service key to
-    // the official API). An explicit flag or env URL that disagrees refuses
-    // the stored key instead of leaking it. This applies to both providers.
-    const boundBaseUrl = !envApiKey && storedCredential?.type === 'api_key'
-        ? storedCredential.baseUrl
-        : undefined;
-    const explicitBaseUrl = command.baseUrl
-        ?? readNonEmptyString(processEnv.STRATUS_BASE_URL)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_BASE_URL);
-    if (boundBaseUrl && explicitBaseUrl
-        && String(explicitBaseUrl).replace(/\/+$/, '') !== boundBaseUrl.replace(/\/+$/, '')) {
-        throw new Error(`Your saved ${provider} sign-in is bound to ${boundBaseUrl} and is not sent to ${explicitBaseUrl}. Set ${apiKeyEnvName} or STRATUS_API_KEY to use that endpoint.`);
-    }
-    const baseUrl = boundBaseUrl
-        ?? explicitBaseUrl
-        ?? (fileConfigApplies ? fileConfig.baseUrl : undefined)
-        // The Anthropic SDK knows its own endpoint; only openai needs a default.
-        ?? (provider === 'anthropic' ? undefined : DEFAULT_OPENAI_BASE_URL);
-    if (!apiKey && !authToken) {
-        if (untrustedCustomBaseUrl && credentials[provider]) {
-            throw new Error(`The project config at ${configLocation?.path} sets a custom base URL (${fileConfig.baseUrl}), so your saved sign-in is not sent to it. Set ${apiKeyEnvName} or STRATUS_API_KEY to use this endpoint, or run with --config to trust the file explicitly.`);
-        }
-        throw new Error(`Missing API key for provider=${provider}. Run \`stratus setup\` to sign in, or set STRATUS_API_KEY or ${apiKeyEnvName}.`);
-    }
-    const resolved = provider === 'anthropic'
-        ? {
-            provider: 'anthropic',
-            model: String(model),
-            ...(baseUrl ? { baseUrl: String(baseUrl) } : {}),
-            ...(apiKey ? { apiKey: String(apiKey) } : {}),
-            ...(authToken ? { authToken } : {}),
-        }
-        : {
-            provider: 'openai',
-            model: String(model),
-            baseUrl: String(baseUrl),
-            apiKey: String(apiKey),
-        };
-    const systemPrompt = readNonEmptyString(processEnv.STRATUS_SYSTEM_PROMPT)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_SYSTEM_PROMPT)
-        ?? fileConfig.systemPrompt;
-    if (systemPrompt) {
-        resolved.systemPrompt = String(systemPrompt);
-    }
-    if (env.fetch) {
-        resolved.fetch = env.fetch;
-    }
-    if (soul) {
-        resolved.soul = soul;
-    }
-    // A configured fallback model kicks in when the default model errors
-    // mid-run. It needs its own working sign-in; without one the fallback is
-    // quietly skipped rather than failing the run it exists to rescue.
-    // An implicit fallback (no fallbackProvider key) was written for the
-    // config's own provider — when a flag, env var, or soul overrides that
-    // provider, the fallback model would target the wrong API, so it is
-    // ignored. An explicit fallbackProvider stays valid regardless.
-    if (fileConfig.fallbackModel && (fileConfig.fallbackProvider !== undefined || fileConfigApplies)) {
-        const fallbackProvider = fileConfig.fallbackProvider ?? provider;
-        if (fallbackProvider !== 'demo') {
-            // Same precedence as the primary sign-in: environment keys outrank
-            // the stored credential. And the same endpoint rule: an untrusted
-            // project config's custom fallback URL never receives a stored key —
-            // including the primary's stored key when both share a provider.
-            // Only env-supplied keys follow such a URL.
-            const fallbackUntrustedUrl = fallbackProvider === 'openai'
-                && configLocation?.trusted === false
-                && fileConfig.fallbackBaseUrl !== undefined
-                && fileConfig.fallbackBaseUrl.replace(/\/+$/, '') !== DEFAULT_OPENAI_BASE_URL;
-            const fallbackEnvKey = readNonEmptyString(processEnv[fallbackProvider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY']);
-            const fallbackCredential = fallbackEnvKey || fallbackUntrustedUrl ? undefined : credentials[fallbackProvider];
-            const primaryReusable = fallbackProvider === provider
-                && (envApiKey !== undefined || !fallbackUntrustedUrl);
-            const fallbackApiKey = (primaryReusable ? apiKey : undefined)
-                ?? fallbackEnvKey
-                ?? (fallbackCredential?.type === 'api_key' ? fallbackCredential.value : undefined);
-            const fallbackAuthToken = fallbackProvider !== provider && fallbackProvider === 'anthropic' && fallbackCredential?.type === 'oauth_token'
-                ? fallbackCredential.value
-                : (primaryReusable ? authToken : undefined);
-            if (fallbackApiKey || fallbackAuthToken) {
-                // When the fallback key comes out of the credential store (its own
-                // entry, or the primary's reused stored key), its bound endpoint is
-                // authoritative — config URLs cannot redirect it.
-                const fallbackBoundUrl = fallbackCredential?.type === 'api_key'
-                    ? fallbackCredential.baseUrl
-                    : (primaryReusable && !envApiKey ? boundBaseUrl : undefined);
-                // An anthropic fallback on the same provider keeps the primary's
-                // configured endpoint — retrying the same credential against the
-                // official endpoint instead of the configured service would leak
-                // it and likely fail.
-                const fallbackAnthropicBaseUrl = fallbackProvider === 'anthropic'
-                    ? (fallbackProvider === provider && baseUrl ? String(baseUrl) : undefined)
-                        ?? (fallbackCredential?.type === 'api_key' ? fallbackCredential.baseUrl : undefined)
-                    : undefined;
-                resolved.fallback = {
-                    provider: fallbackProvider,
-                    model: fileConfig.fallbackModel,
-                    ...(fallbackProvider === 'openai'
-                        ? {
-                            baseUrl: fallbackBoundUrl
-                                ?? fileConfig.fallbackBaseUrl
-                                ?? (fallbackProvider === provider ? String(baseUrl) : undefined)
-                                ?? DEFAULT_OPENAI_BASE_URL,
-                        }
-                        : (fallbackAnthropicBaseUrl ? { baseUrl: fallbackAnthropicBaseUrl } : {})),
-                    ...(fallbackApiKey ? { apiKey: String(fallbackApiKey) } : {}),
-                    ...(fallbackAuthToken ? { authToken: fallbackAuthToken } : {}),
-                };
-            }
-        }
-    }
-    return resolved;
-};
-// Wraps the fallback runtime as a provider: the primary model serves every
-// turn until it throws, then the run switches to the fallback for good.
-const createFallbackWrappedProvider = (primary, fallback, onFallback) => {
-    let usingFallback = false;
-    return {
-        name: primary.name,
-        async generate(request) {
-            if (!usingFallback) {
-                try {
-                    return await primary.generate(request);
-                }
-                catch (error) {
-                    usingFallback = true;
-                    onFallback(error);
-                }
-            }
-            return fallback.generate(request);
-        },
-    };
-};
-const createRuntimeProvider = (config, onFallback) => {
-    if (config.provider === 'demo') {
-        return createDemoProvider();
-    }
-    if (config.fallback) {
-        const { fallback, ...primaryConfig } = config;
-        const primary = createRuntimeProvider(primaryConfig);
-        const fallbackProvider = createRuntimeProvider({
-            ...fallback,
-            ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-            ...(config.fetch ? { fetch: config.fetch } : {}),
-        });
-        return createFallbackWrappedProvider(primary, fallbackProvider, onFallback ?? (() => { }));
-    }
-    if (config.provider === 'anthropic') {
-        // Subscription setup tokens are only honored inside the Claude Code
-        // harness, so they route through the Agent SDK runtime; API keys use
-        // the raw Messages API.
-        if (config.authToken && !config.apiKey) {
-            return createClaudeCodeProvider({
-                authToken: config.authToken,
-                model: config.model,
-                ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-            });
-        }
-        return createAnthropicProvider({
-            model: config.model,
-            ...(config.apiKey ? { apiKey: config.apiKey } : {}),
-            ...(config.authToken ? { authToken: config.authToken } : {}),
-            ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
-            ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-            ...(config.fetch ? { fetch: config.fetch } : {}),
-        });
-    }
-    return createOpenAICompatibleProvider({
-        name: 'openai',
-        model: config.model,
-        apiKey: config.apiKey,
-        baseUrl: config.baseUrl,
-        ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
-        ...(config.fetch ? { fetch: config.fetch } : {}),
-    });
-};
-const createApprovalPolicy = (mode, streams, env) => {
+// Kept with its historical CLI signature: a parsed run command is a
+// RuntimeSelection plus CLI-only fields the resolver ignores.
+export const resolveRuntimeConfig = (command, env = {}) => resolveStateRuntimeConfig(command, env);
+const createApprovalPolicy = (mode, streams, env, ask) => {
     if (mode === 'always') {
         return new AllowAllApprovalPolicy();
     }
@@ -984,6 +486,16 @@ const createApprovalPolicy = (mode, streams, env) => {
             },
         };
     }
+    // A caller that already owns stdin (chat's readline) supplies its own
+    // asker — two readers on one stream would race for the same bytes.
+    if (ask) {
+        return {
+            async approve({ call }) {
+                const answer = await ask(`Approve tool call ${call.toolName} with input ${JSON.stringify(call.input)}? [y/N] `);
+                return /^y(es)?$/i.test(answer.trim());
+            },
+        };
+    }
     return {
         async approve({ call }) {
             const input = env.approvalInput ?? process.stdin;
@@ -1004,7 +516,11 @@ const createApprovalPolicy = (mode, streams, env) => {
         },
     };
 };
-export const runSingleLoop = async (prompt, streams, options) => {
+// The shared wiring behind every conversational command: memory (with
+// legacy migration), tools, events, provider (with fallback), and the
+// agent the runtime resolved. run uses it for one shot; chat keeps the
+// runner alive and resumes the same session turn after turn.
+const createAgentRuntime = async (streams, options) => {
     const runEnv = options.env ?? {};
     await migrateLegacyMemory(runEnv);
     const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(runEnv)));
@@ -1016,7 +532,13 @@ export const runSingleLoop = async (prompt, streams, options) => {
             writeLine(streams.stderr, `Warning: event handler failed: ${error instanceof Error ? error.message : String(error)}`);
         },
     });
-    if (options.events ?? true) {
+    if (options.onEvent) {
+        const onEvent = options.onEvent;
+        bus.subscribe(async (event) => {
+            onEvent(event);
+        });
+    }
+    else if (options.events ?? true) {
         bus.subscribe(async (event) => {
             const line = formatEvent(event);
             if (line) {
@@ -1024,40 +546,49 @@ export const runSingleLoop = async (prompt, streams, options) => {
             }
         });
     }
+    // The Claude Code runtime executes kernel tools by calling back into the
+    // runner built just below — late-bound because the runner needs the
+    // provider first.
+    let hostedRunner;
     const runtimeProvider = createRuntimeProvider(options.runtime, (error) => {
         const fallback = options.runtime.provider === 'demo' ? undefined : options.runtime.fallback;
         writeLine(streams.stderr, `Warning: the default model failed (${error instanceof Error ? error.message : String(error)}); falling back to ${fallback?.model ?? 'the fallback model'}.`);
-    });
+    }, async (session, call, context) => {
+        if (!hostedRunner) {
+            throw new Error('The Stratus runtime is not ready to execute tools yet.');
+        }
+        return hostedRunner.executeHostedToolCall(session, call, context);
+    }, options.maxTurns);
     const runner = new AgentRunner({
         provider: runtimeProvider,
         tools,
         executor: createLocalCommandExecutor(),
-        approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}),
+        approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}, options.askApproval),
         bus,
         memory,
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
     });
+    hostedRunner = runner;
     await runner.initialize();
     // A soul is a full identity — without one, every provider serves the
     // same built-in Stratus persona.
     const agent = options.runtime.soul?.agent ?? DEFAULT_STRATUS_AGENT;
     const metadata = options.runtime.provider === 'demo'
-        ? { provider: 'demo' }
+        ? { provider: 'demo', executor: 'local-command' }
         : {
             provider: options.runtime.provider,
             model: options.runtime.model,
             ...(options.runtime.provider === 'openai' ? { baseUrl: options.runtime.baseUrl } : {}),
         };
+    return { runner, agent, metadata };
+};
+export const runSingleLoop = async (prompt, streams, options) => {
+    const { runner, agent, metadata } = await createAgentRuntime(streams, options);
     return runner.run({
         sessionId: randomUUID(),
         agent,
         userMessage: prompt,
-        metadata: options.runtime.provider === 'demo'
-            ? {
-                ...metadata,
-                executor: 'local-command',
-            }
-            : metadata,
+        metadata,
     });
 };
 export const printSessionSummary = (session, streams) => {
@@ -1077,6 +608,219 @@ export const printSessionSummary = (session, streams) => {
         writeLine(streams.stdout, `[${message.role}${nameSuffix}] ${content}`);
     }
 };
+const lastAssistantReply = (session) => {
+    for (let index = session.messages.length - 1; index >= 0; index -= 1) {
+        const message = session.messages[index];
+        if (message && message.role === 'assistant' && message.content.trim().length > 0) {
+            return message.content;
+        }
+    }
+    return '(no reply)';
+};
+const CHAT_HELP = [
+    '  /help   show this',
+    '  /exit   leave the chat (Ctrl+C and Ctrl+D work too)',
+    'Everything else is a message to your agent. The conversation persists',
+    'across turns, and facts they remember stick forever.',
+].join('\n');
+export const runChat = async (command, streams, env = {}) => {
+    const runtime = await resolveRuntimeConfig({
+        command: 'run',
+        prompt: '',
+        format: 'text',
+        events: false,
+        approvals: command.approvals,
+        ...(command.provider ? { provider: command.provider } : {}),
+        ...(command.model ? { model: command.model } : {}),
+        ...(command.baseUrl ? { baseUrl: command.baseUrl } : {}),
+        ...(command.soul ? { soul: command.soul } : {}),
+        ...(command.configPath ? { configPath: command.configPath } : {}),
+    }, env);
+    // Interactive means the real terminal: an injected stdinStream is by
+    // definition not a TTY conversation, so it never gets prompts, ANSI
+    // styling, or a terminal readline wired to a stream that can't take it.
+    const interactive = env.setupInput === undefined
+        && env.stdinStream === undefined
+        && process.stdin.isTTY === true;
+    // Styling is for eyes: piped transcripts stay plain text.
+    const bold = (text) => (interactive ? `\u001b[1m${text}\u001b[0m` : text);
+    const dim = (text) => (interactive ? `\u001b[2m${text}\u001b[0m` : text);
+    const input = env.stdinStream ?? process.stdin;
+    const rl = interactive
+        ? createInterface({
+            input,
+            output: streams.stdout,
+            prompt: '\u001b[36myou ›\u001b[0m ',
+            terminal: true,
+        })
+        : createInterface({ input, terminal: false });
+    // One reader owns stdin. Every line lands in this queue, and whoever is
+    // waiting — the chat loop, or an approval question mid-turn — takes the
+    // next one. A second readline would race for the same bytes, and
+    // rl.question cannot be used while the interface is being iterated.
+    const lineQueue = [];
+    let inputClosed = false;
+    let pendingApproval;
+    let notifyLine;
+    rl.on('line', (rawLine) => {
+        if (pendingApproval) {
+            const resolve = pendingApproval;
+            pendingApproval = undefined;
+            resolve(rawLine);
+            return;
+        }
+        lineQueue.push(rawLine);
+        notifyLine?.();
+    });
+    rl.on('close', () => {
+        inputClosed = true;
+        if (pendingApproval) {
+            const resolve = pendingApproval;
+            pendingApproval = undefined;
+            resolve('');
+        }
+        notifyLine?.();
+    });
+    const nextLine = () => {
+        if (lineQueue.length > 0) {
+            return Promise.resolve(lineQueue.shift());
+        }
+        if (inputClosed) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve) => {
+            notifyLine = () => {
+                notifyLine = undefined;
+                resolve(lineQueue.shift());
+            };
+        });
+    };
+    // An approval consumes the next unconsumed line (typed live, or already
+    // queued from piped input). A closed stream denies instead of hanging.
+    const askApproval = (prompt) => {
+        streams.stderr.write(prompt);
+        const queued = lineQueue.shift();
+        if (queued !== undefined) {
+            return Promise.resolve(queued);
+        }
+        if (inputClosed) {
+            return Promise.resolve('');
+        }
+        return new Promise((resolve) => {
+            pendingApproval = resolve;
+        });
+    };
+    const { runner, agent, metadata } = await createAgentRuntime(streams, {
+        runtime,
+        approvals: command.approvals,
+        askApproval,
+        ...(command.maxTurns !== undefined ? { maxTurns: command.maxTurns } : {}),
+        env,
+        onEvent: (event) => {
+            if (command.events) {
+                const line = formatEvent(event);
+                if (line) {
+                    writeLine(streams.stdout, dim(line));
+                }
+                return;
+            }
+            // Quiet by default — just a whisper when the agent reaches for a tool.
+            if (event.type === 'tool.called') {
+                writeLine(streams.stdout, dim(`  · using ${event.call.toolName}`));
+            }
+            else if (event.type === 'tool.denied') {
+                writeLine(streams.stdout, dim(`  · ${event.call.toolName} denied`));
+            }
+        },
+    });
+    const modelLine = runtime.provider === 'demo'
+        ? 'demo (offline)'
+        : `${runtime.provider} · ${runtime.model}`;
+    if (interactive) {
+        streams.stdout.write('\u001b[2J\u001b[H');
+        for (const line of stratusHeaderLines()) {
+            writeLine(streams.stdout, line);
+        }
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, `Chatting with ${bold(agent.name)} — ${modelLine}.`);
+        writeLine(streams.stdout, dim('The conversation persists across turns. /exit to leave, /help for more.'));
+        writeLine(streams.stdout);
+    }
+    // Ctrl+C between turns closes the chat gracefully; mid-turn there is
+    // nothing to cancel in the kernel yet, so leave immediately instead of
+    // silently waiting out a slow provider call.
+    let turnInFlight = false;
+    rl.on('SIGINT', () => {
+        if (turnInFlight) {
+            writeLine(streams.stdout);
+            writeLine(streams.stdout, dim('Interrupted.'));
+            process.exit(130);
+        }
+        rl.close();
+    });
+    // One session for the whole sitting: the first message starts it, every
+    // later message resumes it — the same plumbing a channel will use to
+    // keep a thread alive.
+    let sessionId;
+    if (interactive) {
+        rl.prompt();
+    }
+    for (;;) {
+        const rawLine = await nextLine();
+        if (rawLine === undefined) {
+            break;
+        }
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            if (interactive) {
+                rl.prompt();
+            }
+            continue;
+        }
+        if (line === '/exit' || line === '/quit' || line === 'exit' || line === 'quit') {
+            break;
+        }
+        if (line === '/help') {
+            writeLine(streams.stdout, CHAT_HELP);
+            if (interactive) {
+                rl.prompt();
+            }
+            continue;
+        }
+        if (!interactive) {
+            writeLine(streams.stdout, `you › ${line}`);
+        }
+        try {
+            turnInFlight = true;
+            let session;
+            if (sessionId === undefined) {
+                const id = randomUUID();
+                sessionId = id;
+                session = await runner.run({ sessionId: id, agent, userMessage: line, metadata });
+            }
+            else {
+                session = await runner.resume({ sessionId, userMessage: line });
+            }
+            writeLine(streams.stdout, `${bold(`${agent.name} ›`)} ${lastAssistantReply(session)}`);
+        }
+        catch (error) {
+            writeLine(streams.stderr, `Error: ${error instanceof Error ? error.message : String(error)}`);
+            writeLine(streams.stdout, dim('(that turn failed — the conversation is still here, try again)'));
+        }
+        finally {
+            turnInFlight = false;
+        }
+        writeLine(streams.stdout);
+        if (interactive) {
+            rl.prompt();
+        }
+    }
+    rl.close();
+    if (interactive) {
+        writeLine(streams.stdout, dim(`Bye — ${agent.name} keeps what they remembered.`));
+    }
+    return 0;
+};
 const formatRuntimeBanner = (runtime) => {
     const soulSuffix = runtime.soul ? ` as ${runtime.soul.agent.name}` : '';
     if (runtime.provider === 'demo') {
@@ -2493,6 +2237,150 @@ export const runSetup = async (command, streams, env = {}) => {
         prompter.close();
     }
 };
+const personaSnippet = (instructions) => {
+    const firstLine = instructions?.split('\n').map((line) => line.trim()).find((line) => line.length > 0);
+    if (!firstLine) {
+        return undefined;
+    }
+    return firstLine.length > 78 ? `${firstLine.slice(0, 77)}…` : firstLine;
+};
+export const runAgents = async (command, streams, env = {}) => {
+    // Fold any legacy per-directory memory in first so the counts below
+    // reflect everything each agent actually remembers.
+    await migrateLegacyMemory(env);
+    const memory = withLegacyDefaultMemories(createFileMemoryStore(memoryFilePath(env)));
+    const processEnv = readProcessEnv(env);
+    // Listing must never be blocked by a broken config — it only feeds the
+    // default marker and the "runs on" lines.
+    const { config: activeConfig } = await discoverActiveConfig(env, (message) => {
+        writeLine(streams.stderr, `Warning: ${message}.`);
+    });
+    const envProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
+        ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'));
+    const envModel = readNonEmptyString(processEnv.STRATUS_MODEL)
+        ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL);
+    // What a run as this soul would actually use right now — the same
+    // precedence as resolveRuntimeConfig (env vars, soul hints, config,
+    // demo), so a model-only or provider-only pin still resolves honestly.
+    const runsOnFor = (soulProvider, soulModel) => {
+        const provider = envProvider ?? soulProvider ?? activeConfig.provider ?? 'demo';
+        if (provider === 'demo') {
+            return { provider };
+        }
+        const soulModelApplies = soulProvider === undefined || soulProvider === provider;
+        const configModelApplies = (activeConfig.provider ?? 'openai') === provider;
+        const model = envModel
+            ?? (soulModelApplies ? soulModel : undefined)
+            ?? (configModelApplies ? activeConfig.model : undefined)
+            ?? (provider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
+        return { provider, model };
+    };
+    const defaultSoulPath = readNonEmptyString(processEnv.STRATUS_SOUL)
+        ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL)
+        ?? activeConfig.soul;
+    const resolvedDefaultSoul = defaultSoulPath
+        ? path.resolve(readWorkingDirectory(env), defaultSoulPath)
+        : undefined;
+    const listings = [];
+    const addSoul = async (soulPath) => {
+        let parsed;
+        try {
+            parsed = parseSoul(await readFile(soulPath, 'utf8'), { seed: soulPath });
+        }
+        catch (error) {
+            writeLine(streams.stderr, `Warning: skipping ${soulPath}: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
+        const { agent } = parsed;
+        const persona = personaSnippet(agent.instructions);
+        listings.push({
+            id: agent.id,
+            name: agent.name,
+            isDefault: soulPath === resolvedDefaultSoul,
+            builtIn: false,
+            soulPath,
+            ...(parsed.provider ? { provider: parsed.provider } : {}),
+            ...(parsed.model ? { model: parsed.model } : {}),
+            runsOn: runsOnFor(parsed.provider, parsed.model),
+            memories: (await memory.list(agent.id)).length,
+            ...(persona ? { persona } : {}),
+            ...(agent.avatar ? { avatar: `${agent.avatar.style} theme, hue ${agent.avatar.hue}, palette ${agent.avatar.palette.join(' ')}` } : {}),
+        });
+    };
+    let rosterFiles = [];
+    try {
+        rosterFiles = (await readdir(agentsDirPath(env)))
+            .filter((file) => file.endsWith('.md'))
+            .sort()
+            .map((file) => path.join(agentsDirPath(env), file));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    for (const soulPath of rosterFiles) {
+        await addSoul(soulPath);
+    }
+    // A default soul can live outside ~/.stratus/agents (a project soul, a
+    // hand-written file) — the roster would be lying without it.
+    if (resolvedDefaultSoul && !rosterFiles.includes(resolvedDefaultSoul)) {
+        await addSoul(resolvedDefaultSoul);
+    }
+    // The built-in Stratus persona serves every run that has no soul.
+    const builtInPersona = personaSnippet(DEFAULT_STRATUS_AGENT.instructions);
+    listings.push({
+        id: DEFAULT_STRATUS_AGENT.id,
+        name: DEFAULT_STRATUS_AGENT.name,
+        isDefault: resolvedDefaultSoul === undefined,
+        builtIn: true,
+        runsOn: runsOnFor(),
+        memories: (await memory.list(DEFAULT_STRATUS_AGENT.id)).length,
+        ...(builtInPersona ? { persona: builtInPersona } : {}),
+    });
+    listings.sort((a, b) => {
+        if (a.isDefault !== b.isDefault) {
+            return a.isDefault ? -1 : 1;
+        }
+        if (a.builtIn !== b.builtIn) {
+            return a.builtIn ? 1 : -1;
+        }
+        return a.name.localeCompare(b.name);
+    });
+    if (command.format === 'json') {
+        writeLine(streams.stdout, JSON.stringify({
+            agents: listings.map(({ isDefault, ...rest }) => ({ ...rest, default: isDefault })),
+        }, null, 2));
+        return 0;
+    }
+    const describeRunsOn = (runsOn) => (runsOn.provider === 'demo' ? 'demo (offline)' : `${runsOn.provider}${runsOn.model ? ` · ${runsOn.model}` : ''}`);
+    writeLine(streams.stdout, 'Agents');
+    for (const agent of listings) {
+        const labels = [
+            ...(agent.isDefault ? ['default'] : []),
+            ...(agent.builtIn ? ['built-in'] : []),
+        ];
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, `  ${agent.name}${labels.length > 0 ? `  (${labels.join(', ')})` : ''}`);
+        writeLine(streams.stdout, `    id        ${agent.id}`);
+        if (agent.soulPath) {
+            writeLine(streams.stdout, `    soul      ${agent.soulPath}`);
+        }
+        writeLine(streams.stdout, `    runs on   ${agent.provider ? describeRunsOn(agent.runsOn) : `follows your setup — currently ${describeRunsOn(agent.runsOn)}`}`);
+        writeLine(streams.stdout, `    memory    ${agent.memories === 0 ? 'nothing yet' : `${agent.memories} remembered fact${agent.memories === 1 ? '' : 's'}`}`);
+        if (agent.persona) {
+            writeLine(streams.stdout, `    persona   ${agent.persona}`);
+        }
+        if (agent.avatar) {
+            writeLine(streams.stdout, `    avatar    ${agent.avatar}`);
+        }
+    }
+    writeLine(streams.stdout);
+    writeLine(streams.stdout, listings.length === 1
+        ? 'That is just the built-in default — create your own with: stratus agent new'
+        : 'Talk to the default with stratus run, or to anyone with stratus run --soul <file>.');
+    return 0;
+};
 export const runAgentNew = async (command, streams, env = {}) => {
     // On a real terminal, creating an agent is the same guided experience as
     // setup: a headed screen, a prefilled (editable) name, a personality, and
@@ -2524,18 +2412,11 @@ export const runAgentNew = async (command, streams, env = {}) => {
             // at all: the soul keeps following the machine's configuration
             // instead of demanding credentials nothing has signed in for.
             const processEnv = readProcessEnv(env);
-            const configLocation = await resolveConfigLocation({}, env);
             // Creating an agent must not be blocked by a broken config — it only
             // feeds the soul's provider/model hint, so fall back to defaults.
-            let activeConfig = {};
-            if (configLocation) {
-                try {
-                    activeConfig = await loadConfigFile(configLocation.path);
-                }
-                catch (error) {
-                    writeLine(streams.stdout, `Note: ignoring unreadable config ${configLocation.path} (${error instanceof Error ? error.message : String(error)}).`);
-                }
-            }
+            const { location: configLocation, config: activeConfig } = await discoverActiveConfig(env, (message) => {
+                writeLine(streams.stdout, `Note: ${message}.`);
+            });
             const soulProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
                 ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
                 ?? activeConfig.provider
@@ -2667,6 +2548,119 @@ export const runDashboard = async (command, streams, env = {}) => {
     await handle.close();
     return 0;
 };
+/**
+ * Loads the optional Slack channel package, or undefined when it is not
+ * installed. Only that package being absent is tolerated: an adapter that
+ * fails to load for any other reason (a broken install, a bad transitive
+ * dependency) surfaces rather than silently disabling Slack for a daemon
+ * whose stored tokens say it should be running.
+ */
+const loadSlackAdapter = async () => {
+    // Resolution and loading are separate questions, and only the first one
+    // means "not installed". Inspecting the import's error message cannot
+    // tell them apart: a package that IS installed but is missing one of
+    // its own dependencies throws ERR_MODULE_NOT_FOUND naming that
+    // dependency and this package as the importer — a broken install would
+    // read as an absent one, silently disabling a channel whose tokens say
+    // it should be running.
+    try {
+        import.meta.resolve('@stratusagent/channel-slack');
+    }
+    catch {
+        return undefined;
+    }
+    // Resolvable: any failure from here is a real problem with the
+    // installed package, and surfaces.
+    return (await import('@stratusagent/channel-slack')).createSlackChannelAdapter;
+};
+/**
+ * `stratus serve` — run the gateway (stratusd) in the foreground: load the
+ * roster, accept dispatches, print events, and drain cleanly on SIGTERM,
+ * SIGINT, or the injected shutdown signal.
+ */
+export const runServe = async (command, streams, env = {}) => {
+    // Loaded lazily: the gateway pulls in node:sqlite, which every other CLI
+    // command neither needs nor should pay for (Node still prints an
+    // experimental warning for it).
+    const { createGateway } = await import('@stratusagent/gateway');
+    const log = (line) => writeLine(streams.stdout, line);
+    const warn = (line) => writeLine(streams.stderr, `Warning: ${line}`);
+    // Agents with stored Slack tokens go live in Slack automatically — the
+    // tokens are gateway infrastructure secrets in the channels namespace of
+    // ~/.stratus/credentials.json (see @stratusagent/channel-slack's README
+    // for the 2-minute per-agent app setup).
+    const channelCredentials = await loadChannelCredentials(env);
+    const slackAgents = Object.entries(channelCredentials.slack ?? {});
+    const channels = [];
+    if (slackAgents.length > 0) {
+        // Channel packages are optional peers: the CLI never bundles a
+        // transport nobody asked for (the Slack SDKs alone are ~9 MB). A
+        // missing one degrades like a broken app does — the daemon serves
+        // every other channel — with an actionable line instead of a
+        // module-not-found stack.
+        const adapter = await loadSlackAdapter();
+        if (adapter) {
+            channels.push(adapter({
+                agents: slackAgents.map(([agentId, tokens]) => ({
+                    agentId,
+                    appToken: tokens.appToken,
+                    botToken: tokens.botToken,
+                })),
+                log,
+                warn,
+            }));
+        }
+        else {
+            warn(`Slack tokens are stored for ${slackAgents.length} agent(s), but @stratusagent/channel-slack is not installed. `
+                + 'Run `npm install -g @stratusagent/channel-slack` to bring them online; starting without the Slack channel.');
+        }
+    }
+    const gateway = createGateway({
+        env,
+        ...(command.configPath ? { selection: { configPath: command.configPath } } : {}),
+        ...(command.idleTimeoutMs !== undefined ? { idleTimeoutMs: command.idleTimeoutMs } : {}),
+        ...(channels.length > 0 ? { channels } : {}),
+        log,
+        warn,
+    });
+    if (command.events) {
+        gateway.bus.subscribe((event) => {
+            const line = formatEvent(event);
+            if (line) {
+                writeLine(streams.stdout, line);
+            }
+        });
+    }
+    await gateway.start();
+    writeLine(streams.stdout, 'Press Ctrl+C to stop.');
+    // Hold the event loop open until a shutdown request, then drain: new
+    // dispatches are refused while in-flight turns finish.
+    await new Promise((resolve) => {
+        const keepAlive = setInterval(() => { }, 2_147_000_000);
+        let settled = false;
+        const shutdown = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearInterval(keepAlive);
+            process.off('SIGTERM', shutdown);
+            process.off('SIGINT', shutdown);
+            resolve();
+        };
+        process.once('SIGTERM', shutdown);
+        process.once('SIGINT', shutdown);
+        if (env.shutdownSignal?.aborted) {
+            shutdown();
+        }
+        else {
+            env.shutdownSignal?.addEventListener('abort', shutdown, { once: true });
+        }
+    });
+    writeLine(streams.stdout, 'Stopping — draining in-flight turns.');
+    await gateway.stop();
+    return 0;
+};
 export const runCli = async ({ argv, streams = process, env = {} }) => {
     try {
         const resolvedEnv = argv.includes('--stdin') && env.stdin === undefined
@@ -2683,12 +2677,21 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.command === 'agent-new') {
             return runAgentNew(command, streams, resolvedEnv);
         }
+        if (command.command === 'agents') {
+            return runAgents(command, streams, resolvedEnv);
+        }
+        if (command.command === 'chat') {
+            return runChat(command, streams, resolvedEnv);
+        }
         if (command.command === 'setup') {
             return runSetup(command, streams, resolvedEnv);
         }
         if (command.command === 'dashboard') {
             return runDashboard(command, streams, resolvedEnv);
         }
+        if (command.command === 'serve') {
+            return runServe(command, streams, resolvedEnv);
+        }
         const runtime = await resolveRuntimeConfig(command, resolvedEnv);
         if (command.format === 'text') {
             writeLine(streams.stdout, formatRuntimeBanner(runtime));