orcasynth 1.4.3 → 1.4.5

package/dist/advisor/mcpConfig.js

@@ -0,0 +1,28 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Write the per-program MCP config into the advisor session's cwd so the spawned CLI auto-connects
+ *  to Orca's MCP server. Each CLI has its own config schema — claude reads `.mcp.json`, opencode reads
+ *  `opencode.json`, codex reads a TOML config. The schemas are version-sensitive: VERIFY each against
+ *  the installed CLI version's docs. The `orca api` CLI verb is the always-available fallback, so an
+ *  imperfect MCP wiring for one program degrades gracefully rather than removing the advisor's reach. */
+export function writeMcpConfig(program, cwd, token, mcpUrl) {
+    const auth = `Bearer ${token}`;
+    // The config carries the advisor's full-scope bearer token, so lock the file to the daemon user (0600).
+    const opts = { mode: 0o600 };
+    if (program.startsWith('claude')) {
+        writeFileSync(join(cwd, '.mcp.json'), JSON.stringify({
+            mcpServers: { orca: { type: 'http', url: mcpUrl, headers: { Authorization: auth } } },
+        }, null, 2), opts);
+    }
+    else if (program.startsWith('opencode')) {
+        writeFileSync(join(cwd, 'opencode.json'), JSON.stringify({
+            $schema: 'https://opencode.ai/config.json',
+            mcp: { orca: { type: 'remote', url: mcpUrl, headers: { Authorization: auth }, enabled: true } },
+        }, null, 2), opts);
+    }
+    else if (program.startsWith('codex')) {
+        // Codex reads MCP servers from its TOML config. Written project-local; VERIFY the exact key/path
+        // (and whether the installed codex needs a `--config`/`-c` flag to pick this up) for the version.
+        writeFileSync(join(cwd, '.codex-mcp.toml'), `[mcp_servers.orca]\nurl = "${mcpUrl}"\nbearer_token = "${token}"\n`, opts);
+    }
+}

package/dist/advisor/service.js

@@ -0,0 +1,74 @@
+import { resolveExecutor } from '../overseer/routing.js';
+import { render } from '../prompts/index.js';
+import { logger } from '../shared/logger.js';
+const log = logger('advisor');
+/** Per-user advisor lifecycle: a persistent `orca-advisor-<userId>` agent session that controls Orca
+ *  on the user's behalf with a full-scope token. Chosen exec is remembered and auto-started on login. */
+export class AdvisorService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    session(userId) { return `orca-advisor-${userId}`; }
+    /** An exec must be globally allowed AND (for a restricted non-admin) on the user's own allow-list. */
+    execAllowed(userId, exec) {
+        const u = this.d.users.get(userId);
+        if (!u)
+            return false;
+        if (!this.d.config.get().allowedExecs.includes(exec))
+            return false;
+        if (u.is_admin || u.allowed_execs.length === 0)
+            return true;
+        return u.allowed_execs.includes(exec);
+    }
+    async status(userId) {
+        const u = this.d.users.get(userId);
+        const name = this.session(userId);
+        const running = (await this.d.tmux.list()).includes(name);
+        return { running, exec: u?.advisor_exec ?? '', session: running ? name : null };
+    }
+    async start(userId, exec) {
+        if (!this.execAllowed(userId, exec))
+            throw new Error('exec not allowed for user');
+        const name = this.session(userId);
+        if ((await this.d.tmux.list()).includes(name))
+            return { session: name }; // already live — idempotent
+        this.d.users.setAdvisorExec(userId, exec); // remember the choice for autostart
+        const spec = resolveExecutor([`exec:${exec}`], this.d.fallback);
+        const token = this.d.users.ensureAdvisorToken(userId); // full-scope, reused across restarts
+        const cwd = this.d.advisorDir(userId);
+        await this.d.prepareMcp?.(spec.program, cwd, token, this.d.url);
+        const u = this.d.users.get(userId);
+        const rawPrompt = render('advisor', { userName: u.name || u.username });
+        // agentName `advisor-<id>` → SpawnService names the tmux session `orca-advisor-<id>`. The full
+        // advisor token overrides the daemon's agent service token via extraEnv, so the advisor acts with
+        // the user's own rights. The cwd is a neutral per-user dir, not a project checkout.
+        await this.d.spawn.launch({
+            projectId: this.d.projectId ?? 0,
+            projectPath: cwd,
+            taskId: name,
+            agentName: `advisor-${userId}`,
+            spec,
+            rawPrompt,
+            extraEnv: { ORCA_TOKEN: token, ORCA_URL: this.d.url },
+        });
+        log.info(`advisor started for user ${userId} (${spec.program}/${spec.model})`);
+        return { session: name };
+    }
+    async stop(userId) {
+        await this.d.tmux.kill(this.session(userId));
+    }
+    /** Bring the user's advisor back up after login, if they set one up and left autostart on. Never
+     *  throws — a spawn failure must not block the login response. */
+    async ensureOnLogin(userId) {
+        const u = this.d.users.get(userId);
+        if (!u || !u.advisor_exec || !u.advisor_autostart)
+            return;
+        try {
+            await this.start(userId, u.advisor_exec);
+        }
+        catch (e) {
+            log.error(`advisor autostart failed for user ${userId}`, e);
+        }
+    }
+}

package/dist/api/server.js

@@ -21,6 +21,7 @@ import { RelayClient } from '../inference/client.js';
 import { uniqueName } from '../daemon/uniqueName.js';
 import { assembleMissionDetail } from '../store/missionDetail.js';
 import { authMiddleware } from './auth.js';
+import { handleMcpRequest } from '../mcp/server.js';
 import { logger } from '../shared/logger.js';
 import { shortId } from '../shared/id.js';
 /** How many times an L3 mission auto-re-spawns a phase that the post-done review rejected before it
@@ -37,6 +38,8 @@ const ORCA_VERSION = (() => {
         return '0.0.0';
     }
 })();
+/** Port the daemon listens on — the MCP route reaches back into this same daemon's REST API at it. */
+const ORCA_PORT = Number(process.env.ORCA_PORT ?? 4400);
 export function createServer(d) {
     const log = logger('api');
     // Core reasoning stores are optional in deps for back-compat with existing call sites/tests; the
@@ -108,6 +111,12 @@ export function createServer(d) {
                 const p = c.req.path;
                 if (!GATED.some((g) => p === g || p.startsWith(g + '/')))
                     return next();
+                // An advisor session is per-user, not project-scoped: its access is governed by ownership in
+                // the route's own sessionAccessible check, so the project gate must not pre-empt it (the user
+                // need not be assigned to the daemon's project to reach their own advisor).
+                const sess = p.match(/^\/sessions\/([^/]+)/);
+                if (sess?.[1] && classifySession(decodeURIComponent(sess[1])).role === 'advisor')
+                    return next();
                 if (users.count() === 0)
                     return next(); // setup mode — no users to gate yet
                 const u = c.get('user');
@@ -149,7 +158,9 @@ export function createServer(d) {
             if (!user)
                 return c.json({ error: 'invalid credentials' }, 401);
             loginHits.delete(ip); // a valid login clears the counter so an earlier typo streak can't lock the user out
-            return c.json({ token: users.issueToken(user.id), user });
+            const token = users.issueToken(user.id);
+            void d.advisor?.ensureOnLogin(user.id); // fire-and-forget: bring the user's advisor back up; never block login
+            return c.json({ token, user });
         });
         app.post('/auth/logout', (c) => { const t = c.get('token'); if (t)
             users.revokeToken(t); return c.json({ ok: true }); });
@@ -428,6 +439,14 @@ export function createServer(d) {
         if (!d.userProjects || !d.users)
             return true; // open / single-user mode — no tenancy boundary
         const u = c.get('user');
+        // An advisor session belongs to exactly one user: only its owner (or an admin) may reach it, and
+        // never via an agent-scoped token. It has no task row, so the project check below can't apply.
+        const info = classifySession(name);
+        if (info.role === 'advisor') {
+            if (c.get('tokenScope') === 'agent')
+                return false;
+            return !!u && (u.id === info.userId || d.userProjects.isAdmin(u.id));
+        }
         // Admin sees every session — but NOT via an agent-scoped token (it's owned by the admin user yet
         // must stay confined to its working set; fall through to the project check below).
         if (c.get('tokenScope') !== 'agent' && u && d.userProjects.isAdmin(u.id))
@@ -1382,6 +1401,18 @@ export function createServer(d) {
         await d.tmux.sendKeys(c.req.param('name'), keys);
         return c.json({ ok: true });
     });
+    app.post('/sessions/:name/input', async (c) => {
+        // Raw interactive input: the xterm `onData` bytes (printable chars, control codes, ESC sequences)
+        // are forwarded verbatim to the pane via `send-keys -l`, so the advisor terminal behaves like a
+        // real one. `-l` + `--` (in the driver) make a leading '-' safe, so no flag-token validation here.
+        if (!sessionAccessible(c, c.req.param('name')))
+            return c.json({ error: 'forbidden' }, 403);
+        const { data } = await c.req.json().catch(() => ({}));
+        if (typeof data !== 'string' || data.length === 0)
+            return c.json({ error: 'data must be a non-empty string' }, 400);
+        await d.tmux.sendRaw(c.req.param('name'), data);
+        return c.json({ ok: true });
+    });
     app.post('/sessions/:name/resize', async (c) => {
         if (!sessionAccessible(c, c.req.param('name')))
             return c.json({ error: 'forbidden' }, 403);
@@ -1424,6 +1455,47 @@ export function createServer(d) {
             clear();
         });
     });
+    // Per-user advisor lifecycle. Full-scope (non-agent) callers only — a spawned agent must not be able
+    // to start/stop a human's advisor. Each acts on the caller's own session (`orca-advisor-<userId>`).
+    app.get('/advisor/status', async (c) => {
+        if (!d.advisor)
+            return c.json({ running: false, exec: '', session: null });
+        if (c.get('tokenScope') === 'agent')
+            return c.json({ error: 'forbidden' }, 403);
+        return c.json(await d.advisor.status(c.get('user').id));
+    });
+    app.post('/advisor/start', async (c) => {
+        if (!d.advisor)
+            return c.json({ error: 'advisor unavailable' }, 503);
+        if (c.get('tokenScope') === 'agent')
+            return c.json({ error: 'forbidden' }, 403);
+        const { exec } = await c.req.json().catch(() => ({}));
+        if (typeof exec !== 'string' || !exec)
+            return c.json({ error: 'exec required' }, 400);
+        try {
+            return c.json(await d.advisor.start(c.get('user').id, exec), 201);
+        }
+        catch (e) {
+            // A permission rejection is the user's fault (403); a spawn/tmux failure is ours (500).
+            const msg = e.message;
+            return c.json({ error: msg }, msg === 'exec not allowed for user' ? 403 : 500);
+        }
+    });
+    app.post('/advisor/stop', async (c) => {
+        if (!d.advisor)
+            return c.json({ ok: true });
+        if (c.get('tokenScope') === 'agent')
+            return c.json({ error: 'forbidden' }, 403);
+        await d.advisor.stop(c.get('user').id);
+        return c.json({ ok: true });
+    });
+    // MCP endpoint: the advisor agent connects here to control Orca with native tools. Each request is
+    // handled statelessly with the toolset bound to the caller's token, and every tool delegates to the
+    // same `callOrcaApi` core as the `orca api` CLI verb — so a new REST endpoint needs zero edits here.
+    app.all('/mcp', async (c) => {
+        const token = c.get('token');
+        return handleMcpRequest(c.req.raw, { url: `http://localhost:${ORCA_PORT}`, token });
+    });
     app.get('/missions', c => {
         const allowed = accessibleProjects(c);
         const live = d.missions.live();

package/dist/cli/commands.js

@@ -1,5 +1,31 @@
 import { start as realStart, stop as realStop, status as realStatus } from './launcher.js';
 import { update as realUpdate } from './update.js';
+/** `orca api <METHOD> <path> [jsonBody]` — generic authenticated REST passthrough. Reads
+ *  ORCA_URL/ORCA_TOKEN from the env the daemon injects into every spawned agent, so an agent can
+ *  drive ANY endpoint without a per-endpoint CLI command (and a new endpoint needs zero CLI edits).
+ *  Injectable for tests; returns a process exit code. */
+export async function runApiCommand(args, env, deps) {
+    const [method, path, rawBody] = args;
+    if (!method || !path) {
+        deps.err('usage: orca api <METHOD> <path> [jsonBody]');
+        return 2;
+    }
+    let body;
+    if (rawBody !== undefined) {
+        try {
+            body = JSON.parse(rawBody);
+        }
+        catch {
+            deps.err('api: body must be valid JSON');
+            return 2;
+        }
+    }
+    const url = env.ORCA_URL ?? 'http://localhost:4400';
+    const token = env.ORCA_TOKEN ?? '';
+    const res = await deps.call(method, path, body, { url, token });
+    deps.out(res.data !== undefined ? JSON.stringify(res.data, null, 2) : res.text);
+    return res.ok ? 0 : 1;
+}
 export function defaultLifecycleDeps(version) {
     return {
         version,

package/dist/cli/index.js

@@ -4,7 +4,8 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { OrcaClient } from './client.js';
-import { defaultLifecycleDeps, runLifecycle } from './commands.js';
+import { defaultLifecycleDeps, runLifecycle, runApiCommand } from './commands.js';
+import { callOrcaApi } from '../shared/apiClient.js';
 import { menu } from './menu.js';
 const BASE = process.env.ORCA_URL ?? 'http://localhost:4400';
 const USAGE = "usage: orca [command] [options]  —  run `orca --help` for the full command list";
@@ -35,6 +36,7 @@ TASKS
                                     --outcome ok|fail         record the outcome
 
 AGENT-FACING                      (invoked by running agents — rarely needed by hand)
+  api <METHOD> <path> [body]      generic authenticated REST call (needs ORCA_URL/ORCA_TOKEN)
   plan submit --phases '<json>'   submit an autopilot plan        (needs ORCA_PLAN_JOB)
   overseer poll                   wait for the next decision       (needs ORCA_MISSION)
   overseer decide --id <id> …     resolve a decision: --approve | --escalate | --choice <optionId>
@@ -49,7 +51,7 @@ Docs & issues: https://github.com/dragocz1995/orcasynth`;
 /** Commands that talk to the daemon API — only these justify auto-starting it. Everything else
  *  (help, unknown verbs) must NOT spawn a daemon: a stray detached daemon squats the port and starves
  *  the systemd-managed one into a restart loop. */
-const API_COMMANDS = new Set(['ls', 'ready', 'sessions', 'close', 'plan', 'overseer']);
+const API_COMMANDS = new Set(['ls', 'ready', 'sessions', 'close', 'plan', 'overseer', 'api']);
 /** True only for verbs that need the daemon API up — the gate for ensureDaemon's auto-spawn. */
 export function needsDaemon(cmd) {
     return cmd !== undefined && API_COMMANDS.has(cmd);
@@ -102,6 +104,11 @@ export async function run(argv, c, env) {
         case 'sessions':
             console.log(JSON.stringify(await c.sessions(), null, 2));
             break;
+        case 'api': {
+            const code = await runApiCommand(argv.slice(1), env, { call: callOrcaApi, out: (s) => console.log(s), err: (s) => console.error(s) });
+            process.exit(code);
+            break;
+        }
         case 'close': {
             if (!arg) {
                 console.error('usage: orca close <taskId> [--summary "<text>"] [--outcome ok|fail]');

package/dist/daemon/bootstrap.js

@@ -27,9 +27,12 @@ import { UserProjectStore } from '../store/userProjectStore.js';
 import { RealGitReader } from '../git/gitReader.js';
 import { uniqueName } from './uniqueName.js';
 import { logger } from '../shared/logger.js';
+import { AdvisorService } from '../advisor/service.js';
+import { writeMcpConfig } from '../advisor/mcpConfig.js';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
 const log = logger('daemon');
 /** Build the overseer-model prompt that turns a finished mission's phase results into a short,
  *  human-readable Czech summary shown on the epic in the dashboard. Kept terse so the relay returns
@@ -226,7 +229,17 @@ export function buildApp(opts) {
     // Per-process secret for short-lived signed avatar URLs (finding W2) — keeps the long-lived session
     // token out of <img> src query strings. Rotates on restart; links live ~5 min, so that's harmless.
     const avatarSecret = randomBytes(32).toString('hex');
-    const app = createServer({ tasks, readiness, missions, engine, spawn, tmux, bus, events, agents, project: opts.project, fallback: { program: 'claude-code', model: 'sonnet' }, clock: new SystemClock(), config, users, projects, userProjects, git, avatarsDir, avatarSecret, planJobs, decisionQueue, pilot });
+    // Per-user advisor: a persistent assistant session controlling Orca on the user's behalf. Its cwd
+    // is a neutral per-user dir (alongside the DB, NOT a project checkout) so the per-program MCP config
+    // never pollutes a repo. Disabled for the in-memory DB (tests build their own AdvisorService).
+    const mcpUrl = `${orcaCli.url}/mcp`; // the daemon hosts the MCP server on its own /mcp route
+    const advisor = opts.dbPath === ':memory:' ? undefined : new AdvisorService({
+        spawn, tmux, users, config, fallback: { program: 'claude-code', model: 'sonnet' },
+        projectId: opts.project.id, url: orcaCli.url,
+        advisorDir: (id) => { const p = join(dirname(opts.dbPath), 'advisor', String(id)); mkdirSync(p, { recursive: true }); return p; },
+        prepareMcp: (program, cwd, token) => writeMcpConfig(program, cwd, token, mcpUrl),
+    });
+    const app = createServer({ tasks, readiness, missions, engine, spawn, tmux, bus, events, agents, project: opts.project, fallback: { program: 'claude-code', model: 'sonnet' }, clock: new SystemClock(), config, users, projects, userProjects, git, avatarsDir, avatarSecret, planJobs, decisionQueue, pilot, advisor });
     // Root-cause recovery: after a daemon crash/restart, tasks left 'in_progress' whose tmux
     // session is gone are zombies — revert them to 'open' so they can be picked up again. No grace
     // or relaunch counter here: a restart isn't an agent death, so it shouldn't spend the budget.

package/dist/mcp/server.js

@@ -0,0 +1,34 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { z } from 'zod';
+import { makeOrcaTools } from './tools.js';
+/** Build an MCP server exposing the Orca toolset bound to one caller's token. Every tool delegates to
+ *  `makeOrcaTools` → the shared `callOrcaApi` core, so there is no request logic here to maintain. */
+function createOrcaMcpServer(deps) {
+    const tools = makeOrcaTools(deps);
+    const server = new McpServer({ name: 'orca', version: '1.0.0' });
+    const text = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data ?? null, null, 2) }] });
+    server.registerTool('orca_request', {
+        description: 'Call any Orca REST endpoint (full control). Generic escape hatch — every endpoint works without a dedicated tool.',
+        inputSchema: { method: z.string(), path: z.string(), body: z.unknown().optional() },
+    }, async (a) => text(await tools.orca_request({ method: a.method, path: a.path, body: a.body })));
+    server.registerTool('orca_tasks', { description: 'List all tasks.', inputSchema: {} }, async () => text(await tools.orca_tasks()));
+    server.registerTool('orca_create_task', {
+        description: 'Create a task.',
+        inputSchema: { title: z.string(), project_id: z.number().optional(), description: z.string().optional() },
+    }, async (a) => text(await tools.orca_create_task(a)));
+    server.registerTool('orca_plan', {
+        description: 'Plan a goal into an epic with phases (autopilot).',
+        inputSchema: { goal: z.string(), project_id: z.number().optional() },
+    }, async (a) => text(await tools.orca_plan(a)));
+    server.registerTool('orca_sessions', { description: 'List live agent sessions.', inputSchema: {} }, async () => text(await tools.orca_sessions()));
+    return server;
+}
+/** Stateless HTTP handler: a fresh server + transport per request, with the toolset bound to the
+ *  request's bearer token, so each advisor connection acts with exactly its user's rights. */
+export async function handleMcpRequest(req, deps) {
+    const server = createOrcaMcpServer(deps);
+    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    await server.connect(transport);
+    return transport.handleRequest(req);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,17 @@
+import { callOrcaApi } from '../shared/apiClient.js';
+export function makeOrcaTools(d) {
+    const call = d.call ?? callOrcaApi;
+    const req = async (method, path, body) => {
+        const r = await call(method, path, body, { url: d.url, token: d.token });
+        if (!r.ok)
+            throw new Error(`orca ${r.status}: ${r.text || JSON.stringify(r.data)}`);
+        return r.data;
+    };
+    return {
+        orca_request: (a) => req(a.method, a.path, a.body),
+        orca_tasks: () => req('GET', '/tasks'),
+        orca_create_task: (a) => req('POST', '/tasks', a),
+        orca_plan: (a) => req('POST', '/tasks/plan', a),
+        orca_sessions: () => req('GET', '/sessions'),
+    };
+}

package/dist/overseer/sessionInfo.js

@@ -1,13 +1,19 @@
 const ORCA = 'orca-';
 const OVERSEER = 'overseer-';
 const PILOT = 'pilot-';
+const ADVISOR = 'advisor-';
 /** Classify a live session name into its role + identity. Mirrors the spawn-time conventions:
- *  overseer → `orca-overseer-<missionId>`, pilot → `orca-pilot-<name>`, worker → `orca-<name>`. */
+ *  overseer → `orca-overseer-<missionId>`, pilot → `orca-pilot-<name>`, advisor → `orca-advisor-<userId>`,
+ *  worker → `orca-<name>`. */
 export function classifySession(name) {
     const bare = name.startsWith(ORCA) ? name.slice(ORCA.length) : name;
     if (bare.startsWith(OVERSEER))
         return { name, role: 'overseer', agent: '', missionId: bare.slice(OVERSEER.length) };
     if (bare.startsWith(PILOT))
         return { name, role: 'pilot', agent: bare.slice(PILOT.length) };
+    if (bare.startsWith(ADVISOR)) {
+        const userId = Number(bare.slice(ADVISOR.length));
+        return { name, role: 'advisor', agent: '', userId: Number.isInteger(userId) ? userId : undefined };
+    }
     return { name, role: 'agent', agent: bare };
 }

package/dist/prompts/advisor.md

@@ -0,0 +1,13 @@
+You are {{userName}}'s personal Orca advisor — an always-available assistant that manages their Orca instance on their behalf. You run in an interactive terminal the user types into directly.
+
+You have FULL control of Orca as this user. There are two equivalent ways to act, both authenticated by the ORCA_TOKEN already in your environment:
+  - The `orca_request` MCP tool (and the typed helpers orca_tasks / orca_create_task / orca_plan / orca_sessions) when MCP tools are available to you.
+  - The shell command `orca api <METHOD> <path> [jsonBody]`, which is always available. Examples:
+      orca api GET /tasks
+      orca api POST /tasks '{"title":"Fix the build","project_id":1}'
+      orca api POST /tasks/plan '{"goal":"Add dark mode","project_id":1}'
+      orca api GET /sessions
+
+Both paths go through the same Orca REST API, so use whichever is handier.
+
+Be proactive, concise, and friendly. Before any destructive action (deleting or cancelling tasks, killing sessions) confirm in plain language first. After you change something, briefly report what you did. Everything you do is scoped to this user's own projects and permissions.

package/dist/shared/apiClient.js

@@ -0,0 +1,23 @@
+export async function callOrcaApi(method, path, body, opts) {
+    const f = opts.fetchImpl ?? fetch;
+    const m = method.toUpperCase();
+    const headers = { authorization: `Bearer ${opts.token}` };
+    const hasBody = body !== undefined && m !== 'GET' && m !== 'HEAD';
+    if (hasBody)
+        headers['content-type'] = 'application/json';
+    const res = await f(`${opts.url}${path.startsWith('/') ? path : `/${path}`}`, {
+        method: m,
+        headers,
+        body: hasBody ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let data;
+    // External/daemon response — parse defensively so a non-JSON body never throws here.
+    try {
+        data = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        data = undefined;
+    }
+    return { status: res.status, ok: res.ok, data, text };
+}

package/dist/store/db.js

@@ -38,6 +38,10 @@ export function openDb(path) {
     addColumn(db, 'users', 'email', "TEXT NOT NULL DEFAULT ''");
     addColumn(db, 'users', 'avatar', "TEXT NOT NULL DEFAULT ''");
     addColumn(db, 'users', 'default_exec', "TEXT NOT NULL DEFAULT ''");
+    // Per-user advisor: the remembered agent exec (empty = not set up yet) and whether it auto-starts
+    // on login. Additive so existing DBs gain them with sensible defaults (autostart on once chosen).
+    addColumn(db, 'users', 'advisor_exec', "TEXT NOT NULL DEFAULT ''");
+    addColumn(db, 'users', 'advisor_autostart', 'INTEGER NOT NULL DEFAULT 1');
     // Token scope: spawned agents get a 'agent'-scoped token (worker/overseer/pilot verbs only),
     // never the admin's full token. Pre-existing rows default to 'full' (interactive user sessions).
     addColumn(db, 'auth_tokens', 'scope', "TEXT NOT NULL DEFAULT 'full'");

package/dist/store/schema.sql

@@ -32,7 +32,9 @@ CREATE TABLE IF NOT EXISTS users (
   name TEXT NOT NULL DEFAULT '',
   email TEXT NOT NULL DEFAULT '',
   avatar TEXT NOT NULL DEFAULT '',
-  default_exec TEXT NOT NULL DEFAULT ''
+  default_exec TEXT NOT NULL DEFAULT '',
+  advisor_exec TEXT NOT NULL DEFAULT '',
+  advisor_autostart INTEGER NOT NULL DEFAULT 1
 );
 CREATE TABLE IF NOT EXISTS auth_tokens (
   token TEXT PRIMARY KEY, user_id INTEGER NOT NULL,

package/dist/store/userStore.js

@@ -3,7 +3,7 @@ import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
  *  own (e.g. tests). The live value comes from config.security.tokenTtlDays. */
 const DEFAULT_TOKEN_TTL_DAYS = 30;
 const ttlDays = (days) => typeof days === 'number' && Number.isFinite(days) && days >= 1 ? Math.floor(days) : DEFAULT_TOKEN_TTL_DAYS;
-const mask = (r) => ({ id: r.id, username: r.username, created_at: r.created_at, is_admin: !!r.is_admin, allowed_execs: r.allowed_execs ? r.allowed_execs.split(',').filter(Boolean) : [], name: r.name ?? '', email: r.email ?? '', avatar: r.avatar ?? '', default_exec: r.default_exec ?? '' });
+const mask = (r) => ({ id: r.id, username: r.username, created_at: r.created_at, is_admin: !!r.is_admin, allowed_execs: r.allowed_execs ? r.allowed_execs.split(',').filter(Boolean) : [], name: r.name ?? '', email: r.email ?? '', avatar: r.avatar ?? '', default_exec: r.default_exec ?? '', advisor_exec: r.advisor_exec ?? '', advisor_autostart: r.advisor_autostart === undefined ? true : !!r.advisor_autostart });
 function hashPassword(password) {
     const salt = randomBytes(16);
     const hash = scryptSync(password, salt, 64);
@@ -69,6 +69,16 @@ export class UserStore {
             this.db.prepare(`UPDATE users SET ${sets.join(', ')} WHERE id = @id`).run(p);
         return this.get(id);
     }
+    /** Remember which agent exec the user's advisor runs (chosen at first open). Empty = not set up. */
+    setAdvisorExec(id, exec) {
+        this.db.prepare('UPDATE users SET advisor_exec = ? WHERE id = ?').run(exec, id);
+        return this.get(id);
+    }
+    /** Toggle whether the advisor auto-starts on login. */
+    setAdvisorAutostart(id, on) {
+        this.db.prepare('UPDATE users SET advisor_autostart = ? WHERE id = ?').run(on ? 1 : 0, id);
+        return this.get(id);
+    }
     /** Record the stored avatar filename (or '' to clear). */
     setAvatar(id, filename) {
         this.db.prepare('UPDATE users SET avatar = ? WHERE id = ?').run(filename, id);
@@ -150,6 +160,21 @@ export class UserStore {
             return this.issueToken(userId, 'agent');
         })();
     }
+    /** The user's advisor token, reused across restarts. Stored under DB scope 'advisor' so it is
+     *  isolated from login ('full') and worker ('agent') tokens — stopping/rotating the advisor never
+     *  disturbs the user's web session. principalForToken maps any non-'agent' scope to full access, so
+     *  the advisor acts with the user's own rights (mirrors ensureAgentToken's reuse-within-TTL shape). */
+    ensureAdvisorToken(userId, days) {
+        return this.db.transaction(() => {
+            const existing = this.db
+                .prepare(`SELECT token FROM auth_tokens WHERE user_id = ? AND scope = 'advisor' AND created_at > datetime('now', '-${ttlDays(days)} days') ORDER BY created_at DESC LIMIT 1`)
+                .get(userId);
+            if (existing?.token)
+                return existing.token;
+            this.db.prepare("DELETE FROM auth_tokens WHERE user_id = ? AND scope = 'advisor'").run(userId);
+            return this.issueToken(userId, 'advisor');
+        })();
+    }
     revokeToken(token) {
         this.db.prepare('DELETE FROM auth_tokens WHERE token = ?').run(token);
     }

package/dist/tmux/driver.js

@@ -26,6 +26,14 @@ export class RealTmuxDriver {
             throw new Error('sendKeys: keys must be a non-empty array of non-flag strings');
         await run('tmux', ['send-keys', '-t', session, ...keys]);
     }
+    /** Forward raw terminal bytes (xterm onData) to the pane verbatim. `-l` disables key-name lookup
+     *  so control chars / ESC sequences pass through exactly as a real terminal would deliver them;
+     *  `--` stops option parsing so `data` can safely begin with '-'. Powers the interactive advisor. */
+    async sendRaw(session, data) {
+        if (typeof data !== 'string' || data.length === 0)
+            return;
+        await run('tmux', ['send-keys', '-t', session, '-l', '--', data]);
+    }
     async capturePane(session, tailLines) {
         try {
             const { stdout } = await run('tmux', ['capture-pane', '-p', '-t', session, '-S', `-${tailLines}`], { maxBuffer: 512 * 1024 });

package/dist/tmux/fakeDriver.js

@@ -1,6 +1,7 @@
 export class FakeTmuxDriver {
     panes = new Map();
     keys = new Map();
+    raw = new Map();
     commands = new Map();
     setPane(session, text) { this.panes.set(session, text); }
     sentKeys(session) { return this.keys.get(session) ?? []; }
@@ -9,11 +10,19 @@ export class FakeTmuxDriver {
     sizeFor(session) { return this.sizes.get(session); }
     async spawn(session, opts) { this.panes.set(session, ''); this.commands.set(session, opts.command); }
     async resize(session, cols, rows) { this.sizes.set(session, { cols, rows }); }
+    sentRaw(session) { return this.raw.get(session) ?? []; }
     async sendKeys(session, keys) {
         const arr = this.keys.get(session) ?? [];
         arr.push(keys);
         this.keys.set(session, arr);
     }
+    async sendRaw(session, data) {
+        if (typeof data !== 'string' || data.length === 0)
+            return;
+        const arr = this.raw.get(session) ?? [];
+        arr.push(data);
+        this.raw.set(session, arr);
+    }
     async capturePane(session, _tail) { return this.panes.get(session) ?? ''; }
     async capturePaneAnsi(session, _tail) { return this.panes.get(session) ?? ''; }
     async list() { return [...this.panes.keys()]; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcasynth",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "ORCA — an autonomous coding-agent orchestrator with an autopilot overseer, daemon API and web UI. Install globally and run `orca`.",
   "license": "MIT",
   "type": "module",
@@ -47,8 +47,10 @@
   "dependencies": {
     "@clack/prompts": "^1.6.0",
     "@hono/node-server": "^1.13.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^11.0.0",
-    "hono": "^4.6.0"
+    "hono": "^4.6.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",

package/prompts/advisor.md

@@ -0,0 +1,13 @@
+You are {{userName}}'s personal Orca advisor — an always-available assistant that manages their Orca instance on their behalf. You run in an interactive terminal the user types into directly.
+
+You have FULL control of Orca as this user. There are two equivalent ways to act, both authenticated by the ORCA_TOKEN already in your environment:
+  - The `orca_request` MCP tool (and the typed helpers orca_tasks / orca_create_task / orca_plan / orca_sessions) when MCP tools are available to you.
+  - The shell command `orca api <METHOD> <path> [jsonBody]`, which is always available. Examples:
+      orca api GET /tasks
+      orca api POST /tasks '{"title":"Fix the build","project_id":1}'
+      orca api POST /tasks/plan '{"goal":"Add dark mode","project_id":1}'
+      orca api GET /sessions
+
+Both paths go through the same Orca REST API, so use whichever is handier.
+
+Be proactive, concise, and friendly. Before any destructive action (deleting or cancelling tasks, killing sessions) confirm in plain language first. After you change something, briefly report what you did. Everything you do is scoped to this user's own projects and permissions.

package/web-dist/.next/BUILD_ID

@@ -1 +1 @@
--qI9ABgqZPR_Ri56jzVI5
+Vc91G_QEn5enhyqIYkLiV

package/web-dist/.next/build-manifest.json

@@ -7,9 +7,9 @@
     "static/chunks/0cz1d0mv5g_q7.js"
   ],
   "lowPriorityFiles": [
-    "static/-qI9ABgqZPR_Ri56jzVI5/_buildManifest.js",
-    "static/-qI9ABgqZPR_Ri56jzVI5/_ssgManifest.js",
-    "static/-qI9ABgqZPR_Ri56jzVI5/_clientMiddlewareManifest.js"
+    "static/Vc91G_QEn5enhyqIYkLiV/_buildManifest.js",
+    "static/Vc91G_QEn5enhyqIYkLiV/_ssgManifest.js",
+    "static/Vc91G_QEn5enhyqIYkLiV/_clientMiddlewareManifest.js"
   ],
   "rootMainFiles": [
     "static/chunks/310vm2bl3xxpt.js",