wisp-agents 0.5.0 → 0.7.0

package/server/adapters/antigravity.js

@@ -0,0 +1,155 @@
+// Antigravity CLI adapter — drives `agy --input-format stream-json --output-format stream-json`
+// (headless mode: one init event, step_update events, one result event per turn).
+//
+// agy has no flag to inject an MCP server (it reads ~/.gemini/config/mcp_config.json and
+// .agents/mcp_config.json), so wisp's ask_user tool isn't available here; the protocol tells
+// the agent to end with a question block. Same for the system prompt: it goes in front of the
+// first message.
+
+import path from 'node:path';
+import { attachmentNote, clip, detectVersion, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+
+const BIN = process.env.WISP_ANTIGRAVITY_BIN || 'agy';
+
+// Headless runs give up after --print-timeout (default 5m); wisp tasks routinely take longer.
+const PRINT_TIMEOUT = '24h';
+
+// `--mode` sets the execution mode; shell commands are governed by permissions, which only
+// --dangerously-skip-permissions lifts in headless mode.
+const MODE_ARGS = {
+  plan: ['--mode', 'plan'],
+  edits: ['--mode', 'accept-edits'],
+  auto: ['--dangerously-skip-permissions'],
+};
+
+const EDIT_TOOL = /write|replace|edit|delete/i;
+const EFFORT_SUFFIX = /-(low|medium|high)$/;
+
+export default {
+  id: 'antigravity',
+  name: 'Antigravity',
+  askTool: null,
+  models: [{ id: '', label: 'Default', hint: 'Whatever Antigravity is set to' }],
+  efforts: ['low', 'medium', 'high'],
+
+  resumeCommand({ resumeId, model, effort }) {
+    return [BIN, ...(resumeId ? ['--conversation', resumeId] : []), ...(model ? ['--model', model] : []), ...(effort ? ['--effort', effort] : [])];
+  },
+
+  async detect() {
+    const found = await detectVersion(BIN);
+    if (!found.available) return found;
+    // `agy models` prints a "Fetching…" line, then "slug<TAB>Label" lines (older builds pad with
+    // spaces). Most slugs bake the effort in (…-high), so those get no separate selector.
+    const models = [];
+    for (const line of (await quietOutput(BIN, ['models'])).split('\n')) {
+      const m = line.trim().match(/^([\w.\-]+)(?:\t|\s{2,})\s*(.+)$/);
+      if (m) models.push({ id: m[1], label: m[2].trim(), hint: m[1], ...(EFFORT_SUFFIX.test(m[1]) ? { efforts: [] } : {}) });
+    }
+    return { ...found, models: [this.models[0], ...models] };
+  },
+
+  run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, onEvent }) {
+    // The prompt goes on stdin as a single `user` event; closing stdin ends the session once
+    // that turn's result is out.
+    const args = ['--input-format', 'stream-json', '--output-format', 'stream-json', '--print-timeout', PRINT_TIMEOUT];
+    args.push(...(MODE_ARGS[mode] || MODE_ARGS.edits));
+    if (model) args.push('--model', model);
+    if (effort) args.push('--effort', effort);
+    if (resumeId) args.push('--conversation', resumeId);
+    for (const d of new Set(attachments.map((a) => path.dirname(a.path)))) args.push('--add-dir', d);
+
+    const content = withProtocol(prompt, systemPrompt, resumeId) + attachmentNote(attachments);
+    const input = JSON.stringify({ event: 'user', message: { content } }) + '\n';
+    const files = fileTracker(cwd);
+    const text = new Map(); // step_index -> text_delta so far
+    const shown = new Set(); // tool steps already announced
+    let sawResult = false;
+    let session = null;
+    const sessionFrom = (id) => {
+      if (id && id !== session) onEvent({ type: 'session', id: (session = id) });
+    };
+
+    return spawnJsonl({
+      bin: BIN,
+      args,
+      cwd,
+      env: process.env,
+      input,
+      onEvent,
+      onJson(msg) {
+        if (msg.event === 'init') sessionFrom(msg.conversation_id);
+        else if (msg.event === 'step_update') {
+          const s = msg.step_update || {};
+          sessionFrom(s.conversation_id);
+          const done = s.state === 'DONE';
+          if (s.step_type === 'agent_response') {
+            const t = (text.get(s.step_index) || '') + (s.text_delta || '');
+            text.set(s.step_index, t);
+            if (done && t.trim()) onEvent({ type: 'text', text: t });
+          } else if (s.subagent_info && !shown.has(s.step_index)) {
+            shown.add(s.step_index);
+            const sub = s.subagent_info.subagents?.[0];
+            onEvent({ type: 'tool', kind: 'agent', label: `Delegating${sub ? ` to ${sub.role || sub.type_name}` : ''}` });
+          } else if (s.step_type === 'tool') {
+            const info = s.tool_info || {};
+            const name = s.tool_name || info.name;
+            const params = info.parameters || {};
+            if (!name) return;
+            const file = fileOf(params);
+            const editing = file && EDIT_TOOL.test(name);
+            // Announce once we know the arguments: on ACTIVE if it carries them, else on DONE.
+            if (!shown.has(s.step_index) && (done || Object.keys(params).length)) {
+              shown.add(s.step_index);
+              if (editing && !done) files.remember(file);
+              onEvent({ type: 'tool', ...describeTool(name, params, cwd) });
+            }
+            if (!done) return;
+            if (info.error) onEvent({ type: 'tool_error', name, text: clip(info.error.message || info.error.type || 'failed', 400) });
+            else if (editing) {
+              const change = files.change(file);
+              if (change) onEvent({ type: 'change', ...change });
+            }
+          }
+        } else if (msg.event === 'result') {
+          const r = msg.result || {};
+          sessionFrom(r.conversation_id);
+          sawResult = true;
+          onEvent({
+            type: 'result',
+            text: r.status === 'SUCCESS' ? r.response ?? '' : r.error || r.response || `Antigravity ended with status ${r.status}`,
+            isError: r.status !== 'SUCCESS',
+            stats: { durationMs: r.duration_seconds != null ? Math.round(r.duration_seconds * 1000) : undefined, inputTokens: r.usage?.input_tokens, outputTokens: r.usage?.output_tokens },
+          });
+        }
+      },
+      onClose({ code, signal, stderr, stopped }) {
+        if (sawResult) return;
+        onEvent({ type: 'result', isError: true, stopped, text: stderr || `agy exited with ${signal || `code ${code}`}` });
+      },
+    });
+  },
+};
+
+// Tool parameters are PascalCase (TargetFile, AbsolutePath, CommandLine, …).
+const pick = (p, ...keys) => {
+  for (const k of keys) if (p[k] != null && p[k] !== '') return p[k];
+};
+const fileOf = (p) => pick(p, 'TargetFile', 'AbsolutePath', 'FilePath', 'File', 'Path', 'path', 'file_path');
+
+function describeTool(name, p, cwd) {
+  const f = rel(fileOf(p), cwd);
+  const n = name.toLowerCase();
+  if (n === 'run_command') return { kind: 'run', label: `Running ${clip(p.CommandLine, 60)}`, detail: p.CommandLine };
+  if (EDIT_TOOL.test(n) && f) return { kind: 'edit', label: `${/delete/.test(n) ? 'Deleting' : 'Editing'} ${f}`, file: f };
+  if (/^view_/.test(n) && f) return { kind: 'read', label: `Reading ${f}`, file: f };
+  if (n === 'list_dir') return { kind: 'search', label: `Listing ${rel(p.DirectoryPath, cwd) || '.'}` };
+  if (n === 'find_by_name') return { kind: 'search', label: `Finding ${clip(p.Pattern, 50)}` };
+  if (/grep/.test(n)) return { kind: 'search', label: `Searching for “${clip(p.Query || p.Pattern, 40)}”` };
+  if (/code_?search|codebase/.test(n)) return { kind: 'search', label: `Searching the codebase: ${clip(p.Query || p.query, 50)}` };
+  if (/search_web|web_search/.test(n)) return { kind: 'web', label: `Searching the web: ${clip(p.query || p.Query, 50)}` };
+  if (/url|fetch/.test(n)) return { kind: 'web', label: `Reading ${clip(p.Url || p.url, 60)}` };
+  if (/browser/.test(n)) return { kind: 'web', label: `Browsing: ${clip(p.Task || p.TaskName || 'browser', 60)}` };
+  if (/task_boundary|todo/.test(n)) return { kind: 'plan', label: clip(p.TaskStatus || p.TaskName || 'Planning') };
+  return { kind: 'tool', label: `Using ${n.replace(/_/g, ' ')}` };
+}

package/server/adapters/index.js

@@ -28,8 +28,9 @@ import claude from './claude.js';
 import codex from './codex.js';
 import opencode from './opencode.js';
 import cursor from './cursor.js';
+import antigravity from './antigravity.js';
 
-export const adapters = Object.fromEntries([claude, codex, opencode, cursor].map((a) => [a.id, a]));
+export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity].map((a) => [a.id, a]));
 
 const detected = new Map();
 
@@ -37,7 +38,10 @@ export async function listAgents() {
   return Promise.all(
     Object.values(adapters).map(async (a) => {
       if (!detected.has(a.id)) detected.set(a.id, a.detect());
-      return { id: a.id, name: a.name, models: a.models, efforts: a.efforts || [], ...(await detected.get(a.id)) };
+      const found = await detected.get(a.id);
+      // Only a hit is cached: a CLI installed while wisp is running shows up on the next call.
+      if (!found.available) detected.delete(a.id);
+      return { id: a.id, name: a.name, models: a.models, efforts: a.efforts || [], ...found };
     }),
   );
 }

package/server/client.js

@@ -0,0 +1,177 @@
+// wisp client SDK: everything the web UI can do, from Node (or anything with fetch).
+// Zero dependencies. Used by the `wisp` CLI and the `wisp mcp` server; importable as
+// `wisp-agents/client`.
+//
+//   import { WispClient } from 'wisp-agents/client';
+//   const wisp = await WispClient.connect();            // finds the running wisp, or starts one
+//   const s = await wisp.launch({ prompt: 'fix the flaky auth test', cwd: process.cwd() });
+//   const done = await wisp.wait(s.id);                  // until it finishes or asks you something
+//   console.log((await wisp.presentation(s.id)).markdown);
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_PORT = 4477;
+const BIN = fileURLToPath(new URL('../bin/wisp.js', import.meta.url));
+const MAX_WAIT_CALL = 280; // seconds per long-poll; fetch gives up on headers after 300s
+
+export const wispHome = () => process.env.WISP_HOME || path.join(os.homedir(), '.wisp');
+
+// The running server advertises itself in ~/.wisp/server.json. Stale files (dead pid) are ignored.
+export function discover(home = wispHome()) {
+  try {
+    const info = JSON.parse(fs.readFileSync(path.join(home, 'server.json'), 'utf8'));
+    if (info.pid) process.kill(info.pid, 0);
+    return info;
+  } catch {
+    return null;
+  }
+}
+
+export class WispError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'WispError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class WispClient {
+  // url: e.g. http://127.0.0.1:4477. Defaults to WISP_PORT, then server.json, then 4477.
+  constructor({ url, port } = {}) {
+    const p = port || Number(process.env.WISP_PORT) || discover()?.port || DEFAULT_PORT;
+    this.url = (url || `http://127.0.0.1:${p}`).replace(/\/$/, '');
+  }
+
+  // Connect to the running wisp; with start (default), launch a headless one if none answers.
+  static async connect({ url, port, start = true, timeoutMs = 15_000 } = {}) {
+    const client = new WispClient({ url, port });
+    if (await client.ping()) return client;
+    if (!start) throw new WispError(`wisp is not running at ${client.url}`, 0);
+    const child = spawn(process.execPath, [BIN, '--no-open', '--port', new URL(client.url).port || String(DEFAULT_PORT)], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+    });
+    child.unref();
+    const end = Date.now() + timeoutMs;
+    while (Date.now() < end) {
+      if (await client.ping()) return client;
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    throw new WispError(`wisp did not start at ${client.url}`, 0);
+  }
+
+  async request(method, p, body, { raw = false, signal } = {}) {
+    const isBuf = body instanceof Uint8Array || body instanceof ArrayBuffer;
+    const res = await fetch(`${this.url}/api${p}`, {
+      method,
+      signal,
+      headers: body === undefined ? {} : { 'content-type': isBuf ? 'application/octet-stream' : 'application/json' },
+      body: body === undefined ? undefined : isBuf ? body : JSON.stringify(body),
+    });
+    if (raw && res.ok) return res;
+    const text = await res.text();
+    let json;
+    try {
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      json = { text };
+    }
+    if (!res.ok) throw new WispError(json.error || res.statusText, res.status, json);
+    return json;
+  }
+
+  async ping() {
+    try {
+      return (await this.health()).ok === true;
+    } catch {
+      return false;
+    }
+  }
+
+  health = () => this.request('GET', '/health');
+  agents = () => this.request('GET', '/agents');
+  config = () => this.request('GET', '/config');
+  updateConfig = (patch) => this.request('PATCH', '/config', patch);
+
+  projects = () => this.request('GET', '/projects');
+  addProject = (dir, { name } = {}) => this.request('POST', '/projects', { path: path.resolve(dir), name });
+  removeProject = (id) => this.request('DELETE', `/projects/${id}`);
+
+  // filter: { state, cwd, project, archived, limit }
+  sessions(filter = {}) {
+    const q = new URLSearchParams(Object.entries(filter).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => [k, String(v)]));
+    return this.request('GET', `/sessions${q.size ? `?${q}` : ''}`);
+  }
+  session = (id) => this.request('GET', `/sessions/${id}`);
+  presentation = (id, { turn } = {}) => this.request('GET', `/sessions/${id}/presentation${turn !== undefined ? `?turn=${encodeURIComponent(turn)}` : ''}`);
+  update = (id, patch) => this.request('PATCH', `/sessions/${id}`, patch); // { title, state, unread, archived }
+  remove = (id) => this.request('DELETE', `/sessions/${id}`);
+  stop = (id) => this.request('POST', `/sessions/${id}/stop`, {});
+  answer = (id, text) => this.request('POST', `/sessions/${id}/answer`, { text });
+  takeover = (id, { open = false } = {}) => this.request(open ? 'POST' : 'GET', `/sessions/${id}/takeover`, open ? {} : undefined);
+
+  // { prompt, cwd, agent, mode, model, effort, attachments: [uploadId] }. Missing agent/mode/model
+  // fall back to the launcher's remembered defaults, like `wisp "…"` does; effort only if given.
+  async launch({ prompt, cwd = process.cwd(), agent, mode, model, effort, attachments } = {}) {
+    if (!agent || !mode || model === undefined) {
+      const { defaults = {} } = await this.config();
+      agent ||= defaults.agent || 'claude';
+      mode ||= defaults.mode || 'edits';
+      model ??= defaults.models?.[agent] ?? (agent === defaults.agent ? defaults.model || '' : '');
+    }
+    return this.request('POST', '/sessions', { prompt, cwd: path.resolve(cwd), agent, mode, model, effort, attachments });
+  }
+
+  // A follow-up. If the agent is blocked on ask_user, this answers it. queue: wait for the
+  // current run instead of interrupting it (default: the user's setting).
+  reply = (id, text, { attachments, queue } = {}) => this.request('POST', `/sessions/${id}/reply`, { text, attachments, queue });
+
+  // Upload a file (path, Buffer or Uint8Array) to attach to a launch or reply. Returns { id, … }.
+  async upload(file, { name, type } = {}) {
+    const data = typeof file === 'string' ? fs.readFileSync(file) : file;
+    name ||= typeof file === 'string' ? path.basename(file) : 'file';
+    const q = new URLSearchParams({ name, ...(type ? { type } : {}) });
+    return this.request('POST', `/uploads?${q}`, data);
+  }
+
+  // Resolve once the session needs you: finished (review/done) or waiting on a question.
+  // Returns the session summary plus { timedOut } when timeoutMs runs out first.
+  async wait(id, { timeoutMs = 30 * 60_000, signal } = {}) {
+    const end = Date.now() + timeoutMs;
+    for (;;) {
+      const left = Math.max(0, Math.ceil((end - Date.now()) / 1000));
+      const s = await this.request('GET', `/sessions/${id}/wait?timeout=${Math.min(left, MAX_WAIT_CALL)}`, undefined, { signal });
+      if (!s.timedOut || left <= MAX_WAIT_CALL) return s;
+    }
+  }
+
+  // Live server events (the same stream the UI uses), as an async iterator of { event, data }.
+  // Events: summary, activity, turn, finished, removed, config, ping.
+  async *events({ signal } = {}) {
+    const res = await this.request('GET', '/events', undefined, { raw: true, signal });
+    const decoder = new TextDecoder();
+    let buf = '';
+    for await (const chunk of res.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      let at;
+      while ((at = buf.indexOf('\n\n')) !== -1) {
+        const frame = buf.slice(0, at);
+        buf = buf.slice(at + 2);
+        const event = /^event: (.*)$/m.exec(frame)?.[1] || 'message';
+        const data = frame.split('\n').filter((l) => l.startsWith('data: ')).map((l) => l.slice(6)).join('\n');
+        try {
+          yield { event, data: data ? JSON.parse(data) : null };
+        } catch {
+          yield { event, data };
+        }
+      }
+    }
+  }
+}

package/server/index.js

@@ -12,6 +12,10 @@ import { adapters, listAgents } from './adapters/index.js';
 import { welcomeSession } from './welcome.js';
 import { openInTerminal, TERMINALS, shq } from './terminal.js';
 import { Telemetry, envDisabled } from './telemetry.js';
+import { blocksToMarkdown, sessionToMarkdown } from './render.js';
+import { openapi } from './openapi.js';
+import { Updater } from './update.js';
+import { Preferences, Retro, KINDS } from './preferences.js';
 
 const WEB = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'web');
 
@@ -32,6 +36,13 @@ const MIME = {
   '.pdf': 'application/pdf',
 };
 const MAX_UPLOAD = 500 * 1024 * 1024;
+const MAX_WAIT_S = 290; // long-poll cap per request; clients loop (fetch drops headers after 300s)
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export const API_VERSION = 1;
+
+// A session "needs you" once it stops running: finished, or blocked on ask_user. A finished run
+// with follow-ups still queued is about to start the next one, so it doesn't count yet.
+const settled = (s) => s.state === 'waiting' || (s.state !== 'running' && !s.queue?.length);
 const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
 
 export async function startServer({ port = 4477, host = '127.0.0.1', handleSignals = true } = {}) {
@@ -61,9 +72,29 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
   runner.on('activity', (a) => broadcast('activity', a));
   runner.on('turn', (t) => broadcast('turn', t));
   runner.on('finished', (f) => broadcast('finished', f));
+  runner.on('finished', ({ session }) => notifyWebhooks(store, session));
   setInterval(() => broadcast('ping', {}), 25_000).unref();
 
   const telemetry = new Telemetry(store);
+  const updater = new Updater({ port, onChange: (u) => broadcast('update', u) });
+
+  // Learned preferences: injected into every turn, refreshed by a background retro per session.
+  const prefs = new Preferences(store.home);
+  const learning = () => store.config.defaults.learn !== 'off';
+  const projectOf = (cwd) => store.projectFor(cwd)?.path || cwd;
+  runner.promptExtra = (s) => (learning() && s.agent !== 'wisp' ? prefs.prompt(projectOf(s.cwd)) : '');
+  const retro = new Retro({
+    store,
+    runner,
+    prefs,
+    projectOf,
+    enabled: learning,
+    onStart: () => broadcast('preferences', {}),
+    onDone: ({ session, ok, added = [], removed = [] }) => {
+      telemetry.track('retro', { agent: session.agent, ok, added: added.length, removed: removed.length });
+      broadcast('preferences', { added: added.length, removed: removed.length });
+    },
+  });
   const run = (s, t) => ({ agent: s.agent, model: s.model || 'default', mode: s.mode, effort: s.effort || 'default', followUp: s.turns.indexOf(t) > 0 });
   runner.on('started', ({ session, turn }) => telemetry.track('turn_started', { ...run(session, turn), attachments: turn.attachments.length }));
   runner.on('ended', ({ session, turn, interrupted, errorText }) => {
@@ -123,6 +154,27 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
       return;
     }
 
+    if (root === 'health' && m === 'GET') return send(res, 200, { ok: true, name: 'wisp', version: VERSION, apiVersion: API_VERSION, pid: process.pid, url: `http://127.0.0.1:${port}` });
+    // New wisp-agents on npm? POST installs it and relaunches; running agents are stopped, so the
+    // client must pass force once it has confirmed that with the user.
+    if (root === 'update') {
+      if (m === 'GET') {
+        if (url.searchParams.has('check')) return send(res, 200, await updater.check());
+        updater.maybeCheck(); // the UI asks on focus and reconnect: a day-old check gets refreshed
+        return send(res, 200, updater.view());
+      }
+      if (m === 'POST') {
+        const body = await readJson(req);
+        if (runner.live.size && !body.force) return send(res, 409, { error: 'agents are running', running: runner.live.size });
+        await updater.install();
+        send(res, 202, updater.view());
+        telemetry.track('update', { from: updater.state.current, to: updater.state.latest, method: updater.method });
+        setTimeout(() => (shutdown(), process.exit(0)), 300);
+        return;
+      }
+    }
+    if (root === 'openapi.json' && m === 'GET') return send(res, 200, openapi({ version: VERSION, port }));
+
     if (root === 'agents' && m === 'GET') return send(res, 200, await listAgents());
 
     // Bridge for the ask_user MCP server running inside an agent process.
@@ -178,12 +230,40 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
       if (m === 'PATCH') {
         const body = await readJson(req);
         if (body.defaults) Object.assign(store.config.defaults, body.defaults);
+        if (body.webhooks !== undefined) {
+          const hooks = Array.isArray(body.webhooks) ? body.webhooks : [];
+          const bad = hooks.find((h) => !/^https?:\/\/\S+$/.test(String(h?.url ?? h)));
+          if (bad !== undefined) return send(res, 400, { error: `Not an http(s) URL: ${bad?.url ?? bad}` });
+          store.config.webhooks = hooks.map((h) => (typeof h === 'string' ? { url: h } : { url: h.url, events: Array.isArray(h.events) ? h.events : undefined }));
+        }
         store.saveConfig();
         broadcast('config', {});
         return send(res, 200, store.config);
       }
     }
 
+    // What wisp learned: preferences and lessons, global and per project (scope = 'global' or a project path).
+    if (root === 'preferences') {
+      const view = () => ({
+        enabled: learning(),
+        global: prefs.data.global,
+        projects: Object.entries(prefs.data.projects).map(([p, v]) => ({ path: p, name: store.projectFor(p)?.name || path.basename(p), ...v })),
+        history: prefs.data.history.slice().reverse(),
+        running: retro.running,
+      });
+      if (m === 'GET') return send(res, 200, view());
+      if (m === 'PUT') {
+        const body = await readJson(req);
+        const scope = String(body.scope || '');
+        if (scope !== 'global' && !path.isAbsolute(scope)) return send(res, 400, { error: 'scope must be "global" or a project path' });
+        if (!KINDS.includes(body.kind)) return send(res, 400, { error: `kind must be one of ${KINDS.join(', ')}` });
+        if (!Array.isArray(body.items)) return send(res, 400, { error: 'items must be an array of strings' });
+        prefs.set(scope, body.kind, body.items);
+        broadcast('preferences', {});
+        return send(res, 200, view());
+      }
+    }
+
     if (root === 'projects') {
       if (!id && m === 'GET') return send(res, 200, store.config.projects);
       if (!id && m === 'POST') {
@@ -254,7 +334,18 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
 
     if (root === 'sessions') {
       if (!id) {
-        if (m === 'GET') return send(res, 200, store.all().map((x) => summarize(x, store)).sort((a, b) => b.updatedAt - a.updatedAt));
+        if (m === 'GET') {
+          const q = Object.fromEntries(url.searchParams);
+          const cwd = q.cwd && path.resolve(q.cwd.replace(/^~(?=$|[\\/])/, os.homedir()));
+          let list = store.all().map((x) => summarize(x, store)).sort((a, b) => b.updatedAt - a.updatedAt);
+          if (q.state) list = list.filter((x) => q.state.split(',').includes(x.state));
+          if (q.agent) list = list.filter((x) => x.agent === q.agent);
+          if (q.project) list = list.filter((x) => x.projectId === q.project || x.project === q.project);
+          if (cwd) list = list.filter((x) => x.cwd === cwd || x.cwd?.startsWith(cwd + path.sep));
+          if (q.archived !== undefined) list = list.filter((x) => x.archived === (q.archived === 'true' || q.archived === '1'));
+          if (Number(q.limit) > 0) list = list.slice(0, Number(q.limit));
+          return send(res, 200, list);
+        }
         if (m === 'POST') {
           const body = await readJson(req);
           if (!body.prompt?.trim()) return send(res, 400, { error: 'prompt required' });
@@ -279,6 +370,7 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
           if (typeof body.unread === 'boolean') s.unread = body.unread;
           if (body.archived === true && s.state !== 'running' && s.state !== 'waiting') Object.assign(s, { archived: true, unread: false });
           if (body.archived === false) delete s.archived;
+          if (s.state === 'done' || s.archived) retro.schedule(s, 0); // finished with it: learn now
           store.save(s);
           broadcast('summary', summarize(s, store));
           return send(res, 200, summarize(s, store));
@@ -291,6 +383,45 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
         }
       }
 
+      // Long-poll until the session needs the user (finished, or asking). ?timeout=seconds.
+      if (action === 'wait' && m === 'GET') {
+        const timeout = Math.min(Math.max(Number(url.searchParams.get('timeout')) || 60, 0), MAX_WAIT_S) * 1000;
+        const end = Date.now() + timeout;
+        let gone = false;
+        req.on('close', () => (gone = true));
+        while (!gone && store.get(id) && !settled(s) && Date.now() < end) await new Promise((r) => setTimeout(r, 200));
+        if (!store.get(id)) return send(res, 404, { error: 'session was deleted' });
+        return send(res, 200, { ...summarize(s, store), timedOut: !settled(s) });
+      }
+
+      // The latest (or ?turn=<id|index>) presentation, as blocks and as markdown.
+      if (action === 'presentation' && m === 'GET') {
+        const q = url.searchParams.get('turn');
+        const turn = q === null ? s.turns.at(-1) : s.turns.find((t) => t.id === q) || s.turns.at(Number(q));
+        if (!turn) return send(res, 404, { error: 'no such turn' });
+        const latest = turn === s.turns.at(-1);
+        const markdown = latest ? sessionToMarkdown(s) : blocksToMarkdown(turn.presentation?.blocks, turn);
+        if (url.searchParams.get('format') === 'markdown') {
+          res.writeHead(200, { 'content-type': 'text/markdown; charset=utf-8' });
+          return res.end(markdown);
+        }
+        return send(res, 200, {
+          sessionId: s.id,
+          turnId: turn.id,
+          turnIndex: s.turns.indexOf(turn),
+          state: s.state,
+          status: turn.status,
+          prompt: turn.prompt,
+          blocks: turn.presentation?.blocks || [],
+          notes: turn.presentation?.notes,
+          fallback: !!turn.presentation?.fallback,
+          changes: turn.changes.map((c) => ({ file: c.file, op: c.op, edits: c.edits.length })),
+          stats: turn.stats,
+          ask: latest ? s.ask || null : null,
+          markdown,
+        });
+      }
+
       if (action === 'reply' && m === 'POST') {
         const { text, attachments, queue } = await readJson(req);
         if (!text?.trim()) return send(res, 400, { error: 'text required' });
@@ -365,7 +496,13 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
     fs.createReadStream(p).pipe(res);
   }
 
+  // Advertise this server so integrations (CLI, MCP, editors) can find it without knowing the port.
+  const serverFile = path.join(store.home, 'server.json');
   const shutdown = () => {
+    try {
+      if (JSON.parse(fs.readFileSync(serverFile, 'utf8')).pid === process.pid) fs.rmSync(serverFile, { force: true });
+    } catch {}
+    retro.stop();
     for (const s of store.all()) runner.stop(s);
     store.flush();
     telemetry.persist();
@@ -380,6 +517,8 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
     server.once('error', reject);
     server.listen(port, host, resolve);
   });
+  fs.writeFileSync(serverFile, JSON.stringify({ url: `http://127.0.0.1:${port}`, port, pid: process.pid, version: VERSION, apiVersion: API_VERSION, startedAt: Date.now() }, null, 2));
+  updater.start();
 
   if (telemetry.enabled) {
     if (store.config.defaults.telemetryNotice !== 'seen') console.log('wisp sends anonymous usage stats and error reports (no prompts, paths or code). Opt out: Settings, or WISP_TELEMETRY=0 / DO_NOT_TRACK=1.');
@@ -391,6 +530,23 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
   return { url: `http://localhost:${port}`, server, store, runner, shutdown, telemetry };
 }
 
+// POST { event, session, markdown } to each configured webhook (Slack bridges, CI, notifiers).
+// event: session.waiting (blocked on ask_user) | session.finished. Fire and forget.
+function notifyWebhooks(store, summary) {
+  const hooks = store.config.webhooks || [];
+  if (!hooks.length) return;
+  const s = store.get(summary.id);
+  if (!s) return;
+  const event = s.state === 'waiting' ? 'session.waiting' : 'session.finished';
+  const body = JSON.stringify({ event, session: summary, markdown: sessionToMarkdown(s), at: Date.now() });
+  for (const h of hooks) {
+    if (h.events?.length && !h.events.includes(event)) continue;
+    fetch(h.url, { method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': `wisp/${VERSION}` }, body, signal: AbortSignal.timeout(10_000) }).catch((err) =>
+      console.warn(`wisp: webhook ${h.url} failed: ${err.message}`),
+    );
+  }
+}
+
 function send(res, status, body) {
   res.writeHead(status, { 'content-type': 'application/json' });
   res.end(JSON.stringify(body));