@anhlp/alp-client 0.0.0-stage → 0.0.1-beta.4

package/src/rpc/registry.js

@@ -0,0 +1,161 @@
+/** Typed registry methods for portable clients. Mutations are sent once: callers retain requestId
+ * and ifRevision to reconcile a timeout by repeating the identical request. @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client */
+export function workspaceRegistry(client) {
+  return {
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.options']['result']>} */
+    worktreeOptions: workspaceId => client.request('workspace.worktree.options', { workspaceId }),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['result']>} */
+    createWorktree: params => client.request('workspace.worktree.create', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['result']>} */
+    removeWorktree: params => client.request('workspace.worktree.remove', params),
+    /** Read-only Git status of a registry workspace (capability `workspace.git`, §12.5). @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.status']['result']>} */
+    gitStatus: workspaceId => client.request('workspace.git.status', { workspaceId }),
+    /** One page of a read-only Git diff; pass `nextCursor` back as `cursor` with the same comparison and path. @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.diff']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.diff']['result']>} */
+    gitDiff: params => client.request('workspace.git.diff', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.list']['result']>} */
+    projects: (params = {}) => client.request('project.list', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['result']>} */
+    workspaces: (params = {}) => client.request('workspace.list', params),
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.get']['result']>} */
+    get: workspaceId => client.request('workspace.get', { workspaceId }),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.register']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.register']['result']>} */
+    register: params => client.request('project.register', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['result']>} */
+    remove: params => client.request('project.remove', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['result']>} */
+    update: params => client.request('workspace.update', params),
+  };
+}
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Canonical base64 of `bytes`, without Buffer or btoa, so it runs in browsers and Node alike. @param {Uint8Array} bytes */
+export function base64Encode(bytes) {
+  let out = '';
+  let index = 0;
+  for (; index + 2 < bytes.length; index += 3) {
+    const n = (bytes[index] << 16) | (bytes[index + 1] << 8) | bytes[index + 2];
+    out += BASE64[n >> 18] + BASE64[(n >> 12) & 63] + BASE64[(n >> 6) & 63] + BASE64[n & 63];
+  }
+  if (index < bytes.length) {
+    const n = (bytes[index] << 16) | ((index + 1 < bytes.length ? bytes[index + 1] : 0) << 8);
+    out += BASE64[n >> 18] + BASE64[(n >> 12) & 63] + (index + 1 < bytes.length ? BASE64[(n >> 6) & 63] : '=') + '=';
+  }
+  return out;
+}
+
+/** Lowercase hex SHA-256 of `bytes` through WebCrypto (browsers' secure contexts, Node 19+). @param {Uint8Array} bytes */
+export async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error('SHA-256 needs WebCrypto here; pass sha256 yourself');
+  const digest = new Uint8Array(await subtle.digest('SHA-256', bytes));
+  return Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Typed attachment methods (capability `attachments`, docs/protocol/alp-json-rpc-v1.md §12.6) and a
+ * chunked upload that keeps to the limits the daemon (or gateway) advertised. Mutations are sent
+ * once: `upload` resumes an interrupted upload by repeating its begin with the same requestId and
+ * continues from what the daemon holds.
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
+ */
+export function attachments(client) {
+  /** @typedef {import('@anhlp/alp-protocol').RpcMethodMap} Map */
+  const api = {
+    /** @param {Map['attachment.begin']['params']} params @returns {Promise<Map['attachment.begin']['result']>} */
+    begin: params => client.request('attachment.begin', params),
+    /** @param {Map['attachment.chunk']['params']} params @returns {Promise<Map['attachment.chunk']['result']>} */
+    chunk: params => client.request('attachment.chunk', params),
+    /** @param {Map['attachment.commit']['params']} params @returns {Promise<Map['attachment.commit']['result']>} */
+    commit: params => client.request('attachment.commit', params),
+    /** @param {string} uploadId @returns {Promise<Map['attachment.abort']['result']>} */
+    abort: uploadId => client.request('attachment.abort', { uploadId }),
+    /** Metadata only (no bytes, no path). @param {string} attachmentId @returns {Promise<Map['attachment.get']['result']>} */
+    get: attachmentId => client.request('attachment.get', { attachmentId }),
+    /** Refused (1004 attachment_referenced) while a prompt references it. @param {string} attachmentId @returns {Promise<Map['attachment.delete']['result']>} */
+    delete: attachmentId => client.request('attachment.delete', { attachmentId }),
+    /**
+     * Uploads `data` and commits it: begin (or resume, with the same requestId), chunks of at most
+     * the smaller of `maxChunkBytes` and what begin answered, commit with its SHA-256. A chunk
+     * refused `offset_mismatch` continues from the daemon's `received`. Returns the attachment.
+     * @param {{ sessionId: string, name: string, mimeType: string, data: Uint8Array, requestId: string, sha256?: string, maxChunkBytes?: number, onProgress?: (received: number, size: number) => void }} options
+     */
+    async upload({ sessionId, name, mimeType, data, requestId, sha256, maxChunkBytes, onProgress }) {
+      const digest = sha256 ?? await sha256Hex(data);
+      const begun = await api.begin({ sessionId, name, size: data.length, mimeType, sha256: digest, requestId });
+      if (begun.state === 'committed' && begun.attachmentId) return (await api.get(begun.attachmentId)).attachment;
+      const size = Math.max(1, Math.min(begun.maxChunkBytes, maxChunkBytes ?? Infinity));
+      let offset = begun.received;
+      for (let realigned = 0; offset < data.length;) {
+        const end = Math.min(data.length, offset + size);
+        try {
+          const { received } = await api.chunk({ uploadId: begun.uploadId, offset, data: base64Encode(data.subarray(offset, end)) });
+          offset = received;
+        } catch (error) {
+          const held = /** @type {any} */ (error)?.data;
+          // Another attempt got further (or less far) than this one knew: continue where the daemon is.
+          if (held?.reason !== 'offset_mismatch' || !Number.isSafeInteger(held.received) || ++realigned > 3) throw error;
+          offset = held.received;
+          continue;
+        }
+        onProgress?.(offset, data.length);
+      }
+      return (await api.commit({ uploadId: begun.uploadId, sha256: digest })).attachment;
+    },
+  };
+  return api;
+}
+
+/**
+ * Typed conversation methods (capabilities `session.fork` and `session.rewind`, docs/protocol/
+ * alp-json-rpc-v1.md §12.7; `session.reload` and `session.resumeCommand`, §12.8). Both change the conversation only, never a file. Mutations are sent
+ * once: keep `requestId` (and `ifGeneration`) to repeat the identical request after a timeout, which
+ * answers the first result with `duplicate: true`. After a rewind, attached clients get a
+ * `history.reset` event: drop cached history, fetch a new tail and attach with its generation.
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
+ */
+export function conversation(client) {
+  /** @typedef {import('@anhlp/alp-protocol').RpcMethodMap} Map */
+  return {
+    /**
+     * A new closed root whose conversation is the source root's through or before a turn (`boundary`),
+     * or a branch a rewind set aside (`branchId`); resume it with session.create { sessionId, resume: true }.
+     * Principal fields are set by a trusted gateway on its own connection, never by a remote client.
+     * @param {Map['session.fork']['params']} params @returns {Promise<Map['session.fork']['result']>}
+     */
+    fork: params => client.request('session.fork', params),
+    /**
+     * Continues the root's conversation from before `beforeTurnId` under the same session id; the
+     * later turns stay a branch (`branch.branchId`) that `fork({ branchId })` recovers.
+     * @param {Map['session.rewind']['params']} params @returns {Promise<Map['session.rewind']['result']>}
+     */
+    rewind: params => client.request('session.rewind', params),
+    /**
+     * Restarts a live root's native process on its own conversation and configuration at the idle
+     * barrier (capability `session.reload`, §12.8); id, history and receipts stay. Sent once: repeat
+     * the same `requestId` after a lost answer.
+     * @param {Map['session.reload']['params']} params @returns {Promise<Map['session.reload']['result']>}
+     */
+    reload: params => client.request('session.reload', params),
+    /**
+     * The ALP CLI command that follows the session in a terminal (capability `session.resumeCommand`,
+     * §12.8), built by alpd: for the clipboard only, never to run.
+     * @param {Map['session.resumeCommand']['params']} params @returns {Promise<Map['session.resumeCommand']['result']>}
+     */
+    resumeCommand: params => client.request('session.resumeCommand', params),
+    /**
+     * Changes a live root's model, effort or team (capability `session.configure.live`, §12.9) at the
+     * idle barrier, through a restart of its native process on the same conversation; `configured` says
+     * what it runs with now. Sent once: repeat the same `requestId` after a lost answer. A change to
+     * another runtime is refused (1005 runtime_mismatch, `data.action: 'session.create'`).
+     * @param {Map['session.configure']['params'] & { requestId: string; ifGeneration: string }} params @returns {Promise<Map['session.configure']['result']>}
+     */
+    configure: params => client.request('session.configure', params),
+    /**
+     * What a change of model, effort, team or mode would run a live root with, and whether it would be
+     * taken now (capability `session.configure.live`, §12.9). Reads only.
+     * @param {Map['session.configure.preview']['params']} params @returns {Promise<Map['session.configure.preview']['result']>}
+     */
+    configurePreview: params => client.request('session.configure.preview', params),
+  };
+}

package/src/rpc/timers.js

@@ -0,0 +1,16 @@
+/** The longest delay setTimeout honours; a longer one fires at once, in browsers, Node and Hermes. */
+export const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * A timeout option as a setTimeout delay. `undefined` means no timer: no timeout given, Infinity,
+ * or a wait longer than any timer can (about 24.8 days). Anything that is not a non-negative
+ * number is a TypeError, so a typo cannot turn into an instant timeout.
+ * @param {unknown} value
+ * @param {string} [name]
+ * @returns {number | undefined}
+ */
+export function timerDelay(value, name = 'timeoutMs') {
+  if (value === undefined || value === Infinity) return undefined;
+  if (typeof value !== 'number' || Number.isNaN(value) || value < 0) throw new TypeError(`${name} must be a non-negative number of milliseconds`);
+  return value > MAX_TIMER_MS ? undefined : value;
+}

package/src/service.js

@@ -0,0 +1,154 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runCommand } from './command.js';
+
+/**
+ * alpd as a user service (ALPD §37): a LaunchAgent on macOS, a systemd user unit on
+ * Linux. The service manager starts alpd at login and starts it again after a crash;
+ * a clean stop (`alp daemon stop`, exit 0) stays stopped until `alp daemon start`.
+ * Paths can be redirected for tests: ALP_SERVICE_DIR for the definition's directory,
+ * ALP_LAUNCHCTL and ALP_SYSTEMCTL for the managers.
+ */
+
+/** Variables alpd reads, carried into the service when the installing shell sets them. */
+const CARRIED = ['ALP_RUN_LOG_DIR', 'ALP_CODEX_BIN', 'ALP_CLAUDE_BIN', 'ALP_ANTIGRAVITY_BIN', 'ALP_GH_BIN'];
+
+const escapeXml = value => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const quoteUnit = value => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/**
+ * Where and how alpd for `home` is defined as a service on `platform`, or undefined
+ * where ALP has no service support. Each ALP_HOME gets its own service.
+ */
+export function serviceFor({ home, env = process.env, platform = process.platform, uid = process.getuid?.() ?? 0 }) {
+  const custom = path.resolve(home) !== path.join(os.homedir(), '.alp');
+  const suffix = custom ? createHash('sha256').update(path.resolve(home)).digest('hex').slice(0, 8) : '';
+  if (platform === 'darwin') {
+    const label = `com.alp.alpd${suffix ? `.${suffix}` : ''}`;
+    const directory = env.ALP_SERVICE_DIR || path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const launchctl = env.ALP_LAUNCHCTL || 'launchctl';
+    const target = `gui/${uid}/${label}`;
+    const file = path.join(directory, `${label}.plist`);
+    return {
+      kind: 'launchd', name: label, file,
+      install: [[launchctl, ['bootout', target], { ignore: true }], [launchctl, ['bootstrap', `gui/${uid}`, file]]],
+      start: [[launchctl, ['kickstart', target]]],
+      uninstall: [[launchctl, ['bootout', target], { ignore: true }]],
+    };
+  }
+  if (platform === 'linux') {
+    const name = `alpd${suffix ? `-${suffix}` : ''}`;
+    const directory = env.ALP_SERVICE_DIR || path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
+    const systemctl = env.ALP_SYSTEMCTL || 'systemctl';
+    return {
+      kind: 'systemd', name, file: path.join(directory, `${name}.service`),
+      install: [[systemctl, ['--user', 'daemon-reload']], [systemctl, ['--user', 'enable', '--now', `${name}.service`]]],
+      start: [[systemctl, ['--user', 'start', `${name}.service`]]],
+      uninstall: [[systemctl, ['--user', 'disable', '--now', `${name}.service`], { ignore: true }]],
+      afterUninstall: [[systemctl, ['--user', 'daemon-reload'], { ignore: true }]],
+    };
+  }
+  return undefined;
+}
+
+/** The service definition that runs `entry` with `execPath` for `home`. */
+export function serviceDefinition(service, { home, entry, execPath = process.execPath, env = process.env }) {
+  const variables = { ALP_HOME: path.resolve(home), PATH: env.PATH ?? '' };
+  for (const name of CARRIED) if (env[name]) variables[name] = env[name];
+  const program = [execPath, entry, '--service'];
+  const fatal = path.join(path.resolve(home), 'logs', 'alpd.service.log');
+  if (service.kind === 'launchd') {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(service.name)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${program.map(arg => `    <string>${escapeXml(arg)}</string>`).join('\n')}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(variables).map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`).join('\n')}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>Crashed</key>
+    <true/>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(fatal)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(fatal)}</string>
+</dict>
+</plist>
+`;
+  }
+  return `[Unit]
+Description=ALP daemon (alpd) for ${path.resolve(home)}
+
+[Service]
+ExecStart=${program.map(quoteUnit).join(' ')}
+${Object.entries(variables).map(([key, value]) => `Environment=${quoteUnit(`${key}=${value}`)}`).join('\n')}
+Restart=on-failure
+RestartSec=10
+StandardOutput=append:${fatal}
+StandardError=append:${fatal}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** The program an installed definition runs: [node, alpd.js], or undefined when it is not installed. */
+export async function installedProgram(service) {
+  const text = await readFile(service.file, 'utf8').catch(() => undefined);
+  if (text === undefined) return undefined;
+  if (service.kind === 'launchd') {
+    const array = text.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1] ?? '';
+    const unescape = value => value.replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
+    return [...array.matchAll(/<string>([\s\S]*?)<\/string>/g)].map(match => unescape(match[1])).slice(0, 2);
+  }
+  const line = text.match(/^ExecStart=(.*)$/m)?.[1] ?? '';
+  return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map(match => match[1].replace(/\\(.)/g, '$1')).slice(0, 2);
+}
+
+async function runAll(steps, run) {
+  for (const [command, args, { ignore = false } = {}] of steps) {
+    const result = await run(command, args);
+    if (result.code !== 0 && !ignore) throw new Error(`${command} ${args.join(' ')} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.code}`}`);
+  }
+}
+
+/** Writes the definition and loads it, which starts alpd. */
+export async function installService(service, options, run = runCommand) {
+  await mkdir(path.dirname(service.file), { recursive: true });
+  await mkdir(path.join(path.resolve(options.home), 'logs'), { recursive: true, mode: 0o700 });
+  await writeFile(service.file, serviceDefinition(service, options), { mode: 0o644 });
+  await runAll(service.install, run);
+}
+
+/** Starts an installed service's alpd. */
+export async function startService(service, run = runCommand) {
+  await runAll(service.start, run);
+}
+
+/** Unloads the service, which stops its alpd, and removes the definition; false when none was installed. */
+export async function uninstallService(service, run = runCommand) {
+  if (await installedProgram(service) === undefined) return false;
+  await runAll(service.uninstall, run);
+  await unlink(service.file).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  await runAll(service.afterUninstall ?? [], run);
+  return true;
+}

package/src/setup.js

@@ -0,0 +1,150 @@
+import { copyFile, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { initProject } from '@anhlp/alp-core/init';
+import { MODELS } from '@anhlp/alp-core/models';
+import { fitEffort, modelEfforts } from '@anhlp/alp-core/profiles';
+import { resolveTeam } from '@anhlp/alp-core/teams';
+import { validateSettings } from '@anhlp/alp-core/validation';
+import { Cancelled, select, text } from './prompt.js';
+
+const PROVIDERS = ['claude', 'codex'];
+const PROVIDER_LABEL = { claude: 'Claude', codex: 'Codex' };
+/** Each seat's model and effort per provider. Main runs on the preferred provider's only; peers may run on any model of an enabled provider. */
+const DEFAULTS = {
+  main: { claude: ['claude-opus-5-5', 'high'], codex: ['gpt-6.1-sol', 'high'] },
+  worker: { claude: ['claude-opus-5-5', 'high'], codex: ['gpt-6.1-sol', 'high'] },
+  supervisor: { claude: ['claude-sonnet-5', 'medium'], codex: ['gpt-6-luna', 'medium'] },
+  oracle: { claude: ['claude-fable-5-1', 'high'], codex: ['gpt-6-astra', 'high'] },
+};
+const FLAGS = { main: 'model', worker: 'model', supervisor: 'supervisor', oracle: 'oracle' };
+const SEAT_LABEL = { main: 'main', worker: 'lead, reviewer', supervisor: 'supervisor', oracle: 'oracle' };
+const ANY_EFFORT = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+/** Write Phở and Cafe's agent profiles into a project's .alp/settings.json, without installing software or calling models. */
+export async function setup(args, home) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: Object.fromEntries(
+    ['runtime', 'prefer', ...PROVIDERS.flatMap(provider => Object.values(FLAGS).map(flag => `${provider}-${flag}`))].map(name => [name, { type: 'string' }]),
+  ) });
+  if (positionals.length > 1) throw new Error('setup takes at most one directory');
+  const root = path.resolve(positionals[0] ?? process.cwd());
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  try {
+    const runtime = values.runtime ?? (interactive ? await select({ message: 'Runtime', initial: 'mix', choices: [
+      { label: 'Mix', value: 'mix', hint: 'Claude and Codex: main runs on one, the others can run on either' },
+      { label: 'Codex only', value: 'codex' },
+      { label: 'Claude only', value: 'claude' },
+    ] }) : undefined);
+    if (runtime === undefined) throw new Error('Pass --runtime codex, claude or mix when setup is not running in a terminal');
+    if (!['codex', 'claude', 'mix'].includes(runtime)) throw new Error('--runtime must be codex, claude or mix');
+    const prefer = values.prefer ?? (runtime !== 'mix' ? runtime : interactive ? await select({ message: 'Main runs on', initial: 'claude', choices: [
+      { label: 'Claude', value: 'claude', hint: 'Claude first for the others too' },
+      { label: 'Codex', value: 'codex', hint: 'Codex first for the others too' },
+    ] }) : 'claude');
+    if (!PROVIDERS.includes(prefer) || (runtime !== 'mix' && prefer !== runtime)) throw new Error('--prefer must be an enabled runtime');
+    // The preferred provider comes first: it is each agent's default, the other one a choice.
+    const enabled = runtime === 'mix' ? [prefer, ...PROVIDERS.filter(provider => provider !== prefer)] : [runtime];
+    for (const provider of PROVIDERS) {
+      for (const flag of Object.values(FLAGS)) {
+        if (!enabled.includes(provider) && values[`${provider}-${flag}`]) throw new Error(`--${provider}-${flag} is unavailable in ${runtime}-only mode`);
+      }
+    }
+    /** @type {Record<string, Array<{ provider: string, model: string, effort?: string }>>} */
+    const seats = {};
+    for (const [seat, flag] of Object.entries(FLAGS)) {
+      seats[seat] = (seat === 'main' ? [prefer] : enabled).map(provider => {
+        const option = `${provider}-${flag}`;
+        const [fallback, effort] = DEFAULTS[seat][provider];
+        const model = nativeModel(values[option] ?? fallback, provider, `--${option}`);
+        return { provider, model, effort: fitEffort(`${provider}:${model}`, effort) };
+      });
+    }
+    const peers = enabled.map(provider => `${provider}:*`);
+
+    const file = path.join(root, '.alp/settings.json');
+    const settings = await readFile(file, 'utf8').then(content => {
+      try { return JSON.parse(content); } catch (error) { throw new Error(`${file} is not valid JSON: ${error.message}`); }
+    }, error => {
+      if (error.code === 'ENOENT') return undefined;
+      throw new Error(`${file}: ${error.message}`);
+    });
+    const show = () => {
+      for (const [seat, choices] of Object.entries(seats)) console.log(`  ${SEAT_LABEL[seat]}: ${choices.map(describe).join(', ')}`);
+      console.log(`  peer: ${peers.join(', ')} (any model: whoever assigns a peer picks its model and effort for the task)`);
+    };
+    console.log(`Profiles for Phở and Cafe in ${file}:`);
+    show();
+    const replaced = ['pho', 'cafe'].filter(id => (settings?.team ?? settings?.profile)?.[id]);
+    if (replaced.length) console.log(`These replace the ${replaced.join(' and ')} profiles already in the file; a backup is kept in ${file}.bak.`);
+    if (interactive) {
+      for (;;) {
+        const next = await select({ message: 'Save these profiles?', initial: 'save', choices: [
+          { label: 'Save', value: 'save' },
+          { label: 'Change a model', value: 'change' },
+          { label: 'Cancel', value: 'cancel' },
+        ] });
+        if (next === 'cancel') throw new Cancelled();
+        if (next === 'save') break;
+        await change(seats);
+        show();
+      }
+    }
+    const profile = await profiles(root, home, seats, peers, settings);
+    validateSettings({ ...(settings ?? {}), team: { ...(settings?.profile ?? {}), ...(settings?.team ?? {}), ...profile } }, file);
+    if (!settings) await initProject(root, { library: home });
+    else if (replaced.length) await copyFile(file, `${file}.bak`);
+    const written = settings ?? JSON.parse(await readFile(file, 'utf8'));
+    const next = { ...written, team: { ...(written.profile ?? {}), ...(written.team ?? {}), ...profile } };
+    delete next.profile;
+    await writeFile(file, JSON.stringify(next, null, 2) + '\n');
+    console.log('Setup saved. New sessions in this project use these profiles; edit the file to change one agent. Run alp doctor to check that each CLI is installed and logged in.');
+  } catch (error) {
+    if (!(error instanceof Cancelled)) throw error;
+    console.log(error.message);
+  }
+}
+
+const describe = choice => `${choice.provider}:${choice.model}${choice.effort ? `:${choice.effort}` : ''}`;
+
+/** Pick one seat and provider, then its model and effort. */
+async function change(seats) {
+  const [seat, at] = await select({ message: 'Which model?', choices: Object.entries(seats).flatMap(([seat, choices]) =>
+    choices.map((choice, at) => ({ label: `${SEAT_LABEL[seat]} · ${PROVIDER_LABEL[choice.provider]}`, value: [seat, at], hint: describe(choice) }))) });
+  const current = seats[seat][at];
+  const offered = MODELS.filter(model => model.runtime === current.provider);
+  const picked = await select({ message: `${SEAT_LABEL[seat]} on ${PROVIDER_LABEL[current.provider]}`, initial: current.model, choices: [
+    ...offered.map(model => ({ label: model.label, value: model.id, hint: `${model.id} · ${model.description}` })),
+    { label: 'Other…', value: undefined, hint: 'type a model ID' },
+  ] });
+  const model = picked ?? nativeModel(await text(`${PROVIDER_LABEL[current.provider]} model ID:`), current.provider, 'The model ID');
+  const efforts = modelEfforts(`${current.provider}:${model}`) ?? ANY_EFFORT;
+  const effort = efforts.length > 1 ? await select({ message: 'Effort', initial: efforts.includes(current.effort) ? current.effort : DEFAULTS[seat][current.provider][1],
+    choices: efforts.map(effort => ({ label: effort, value: effort })) }) : efforts[0];
+  seats[seat][at] = { provider: current.provider, model, ...(effort ? { effort } : {}) };
+}
+
+/** Every Phở and Cafe agent's profiles, keeping each agent's own compaction setting. */
+async function profiles(root, home, seats, peers, settings) {
+  const profile = {};
+  for (const id of ['pho', 'cafe']) {
+    const team = await resolveTeam(root, id, { library: home });
+    const agents = {};
+    const seat = (name, choices) => {
+      agents[name] = { profiles: choices.map(choice => typeof choice === 'string' ? choice : describe(choice)), autocompact: (settings?.team ?? settings?.profile)?.[id]?.[name]?.autocompact ?? 'auto' };
+    };
+    for (const [name, member] of Object.entries(team.members)) {
+      if (name !== 'oracle') seat(name, name === team.main ? seats.main : member.role === 'peer' ? peers : seats.worker);
+    }
+    if (team.supervisor) seat(team.supervisor.agent, seats.supervisor);
+    if (team.members.oracle) seat('oracle', seats.oracle);
+    profile[id] = agents;
+  }
+  return profile;
+}
+
+/** A model for one provider: a native ID, or one prefixed with that provider. */
+function nativeModel(id, provider, where) {
+  const model = id.startsWith(`${provider}:`) ? id.slice(provider.length + 1) : id;
+  if (!model || /\s/.test(model) || /^(codex|claude):/.test(model) || (model.includes(':') && !id.startsWith(`${provider}:`))) throw new Error(`${where} expects a ${provider} model, got '${id}'`);
+  return model;
+}

package/src/supervise.d.ts

@@ -0,0 +1,14 @@
+export function holdDaemon(home: string, by?: string): Promise<void>;
+export function releaseHold(home: string): Promise<void>;
+export function daemonHeld(home: string): Promise<boolean>;
+export function startDaemon(options: { home: string; entry?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<string>;
+export function superviseDaemon(options: {
+  home: string;
+  entry?: string | (() => string | undefined);
+  env?: NodeJS.ProcessEnv;
+  intervalMs?: number;
+  misses?: number;
+  log?: (message: string) => void;
+  /** Who keeps alpd up, for the log: "alpd started with <by>". */
+  by?: string;
+}): (() => Promise<void>) & { started: Promise<void> };

package/src/supervise.js

@@ -0,0 +1,92 @@
+import { mkdir, unlink, writeFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDaemon, lockAlive, readLock, withDaemonLifecycle } from './index.js';
+import { installedProgram, serviceFor, startService } from './service.js';
+
+/**
+ * Keeping alpd up (ALPD §40). Whoever starts alpd goes through its login service when
+ * one is installed, so the service keeps managing it; otherwise alpd starts detached.
+ * A deliberate `alp daemon stop` leaves a hold, which watchers respect: they start
+ * alpd again only when someone asks for it.
+ */
+
+const holdFile = home => path.join(home, 'state', 'alpd.held');
+
+/** Records that the user stopped alpd on purpose. */
+export async function holdDaemon(home, by = 'alp daemon stop') {
+  await mkdir(path.dirname(holdFile(home)), { recursive: true, mode: 0o700 });
+  await writeFile(holdFile(home), JSON.stringify({ by, at: new Date().toISOString() }) + '\n', { mode: 0o600 });
+}
+
+export async function releaseHold(home) {
+  await unlink(holdFile(home)).catch(() => {});
+}
+
+export async function daemonHeld(home) {
+  return stat(holdFile(home)).then(() => true, () => false);
+}
+
+/** Polls until an alpd for `home` is ready; returns its socket. */
+async function whenReady(home, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const lock = await readLock(home);
+    if (lockAlive(lock) && lock.ready) return lock.socket;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`alpd did not become ready within ${timeoutMs / 1000} s; see ${path.join(home, 'logs')}`);
+}
+
+/**
+ * Starts alpd for `home` unless it runs, and lifts a hold: someone asked for it.
+ * Returns its socket.
+ */
+export async function startDaemon({ home, entry, env = process.env, timeoutMs = 15_000, automatic = false }) {
+  return withDaemonLifecycle(home, 'start', async () => {
+    if (automatic) {
+      if (await daemonHeld(home)) return;
+    } else await releaseHold(home);
+    const lock = await readLock(home);
+    if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
+    const service = serviceFor({ home, env });
+    if (service && await installedProgram(service)) {
+      await startService(service);
+      return whenReady(home, timeoutMs);
+    }
+    return ensureDaemon({ home, entry, env, timeoutMs, lifecycleLocked: true });
+  });
+}
+
+/**
+ * Starts alpd now and starts it again whenever it is found down on `misses` checks in a
+ * row, `intervalMs` apart, unless the user holds it. Two misses let `alp daemon restart`
+ * and `install` finish their own stop and start first. Returns a function that stops
+ * watching, and resolves once a start it began has settled; alpd keeps running. `by` names the
+ * caller in the log line of the first start ("alpd started with <by>").
+ */
+export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5_000, misses = 2, log = () => {}, by }) {
+  let stopped = false;
+  let missed = 0;
+  let starting;
+  // The first start is the caller's own request (it lifts a hold); later ones are automatic.
+  const start = (reason, automatic = true) => {
+    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env, automatic })
+      .then(socket => { if (socket) log(`alpd ${reason}`); }, error => log(`could not start alpd: ${error?.message ?? error}`))
+      .finally(() => { starting = undefined; missed = 0; });
+    return starting;
+  };
+  const check = async () => {
+    if (stopped || starting) return;
+    if (lockAlive(await readLock(home))) { missed = 0; return; }
+    if (await daemonHeld(home)) { missed = 0; return; }
+    // Stopped while this check looked: start nothing.
+    if (++missed >= misses && !stopped) await start('was down; started it again');
+  };
+  // `by` names the supervising service in the log, for example `Paseo` or `alp web`.
+  const initial = start(by ? `started with ${by}` : 'started', false);
+  const timer = setInterval(() => { void check(); }, intervalMs);
+  timer.unref?.();
+  const stop = () => { stopped = true; clearInterval(timer); return starting ?? Promise.resolve(); };
+  stop.started = initial;
+  return stop;
+}