@geraldmaron/construct 1.1.1 → 1.2.0

package/lib/chat/harness/driver.mjs

@@ -0,0 +1,91 @@
+/**
+ * lib/chat/harness/driver.mjs — normalized harness driver contract for the
+ * construct terminal chat surface.
+ *
+ * A driver runs the agent loop and normalizes its streaming output into one event
+ * model, so the transparency engine and the TUI never depend on how the loop is
+ * produced. ADR-0041: Construct's owned loop (apps/chat/engine) implements this
+ * contract; the union stays the stable seam between the engine and the renderers.
+ * Every driver exposes the same shape:
+ *   start()             opens a session and returns { sessionId, capabilities }
+ *   prompt(text, opts)  async-iterable of normalized events for one turn; opts may
+ *                       carry { model, sandbox, permissionMode } when the host supports them
+ *   cancel()            aborts the active turn
+ *   stop()              tears down the host process / connection
+ *   listModels()        optional: returns [{ id, label, ... }] when the host can enumerate models
+ *
+ * Normalized event union consumed by the rest of the surface:
+ *   { type: 'thinking',    text, messageId }      agent internal reasoning chunk
+ *   { type: 'text',        text, messageId }      agent message chunk
+ *   { type: 'plan',        entries }              planned path / task entries
+ *   { type: 'tool_call',   id, title, kind, status }
+ *   { type: 'tool_update', id, status, content }
+ *   { type: 'usage',       tokens, cost, context, model }
+ *                          tokens: { input, output, cacheRead, cacheWrite, reasoning, total }
+ *                          cost:   { amount, currency }  context: { used, size }
+ *                          every field optional — adapters emit only what the host
+ *                          reports (no fabricated splits)
+ *   { type: 'specialist',  role, status, detail } construct orchestration overlay
+ *   { type: 'permission',  requestId, toolCall, options }
+ *   { type: 'notice',      level, code, message } surface-visible advisory (e.g. context-pressure)
+ *   { type: 'context_continuation', packet, compacted } persisted continuation packet (construct-6zga.1.10)
+ *   { type: 'error',       message }
+ *   { type: 'done',        stopReason }
+ *
+ * Keeping this union stable is what lets ACP agents and per-host adapters be
+ * swapped without touching the transparency or rendering layers.
+ */
+
+export const EVENT_TYPES = Object.freeze({
+  THINKING: 'thinking',
+  TEXT: 'text',
+  PLAN: 'plan',
+  TOOL_CALL: 'tool_call',
+  TOOL_UPDATE: 'tool_update',
+  USAGE: 'usage',
+  SPECIALIST: 'specialist',
+  PERMISSION: 'permission',
+  NOTICE: 'notice',
+  CONTEXT_CONTINUATION: 'context_continuation',
+  ERROR: 'error',
+  DONE: 'done',
+});
+
+// A single-producer/single-consumer queue that is also an async iterable. The
+// line-router pushes normalized events as they arrive; the turn loop awaits them
+// until the producer closes the queue on stop reason or error.
+
+export class AsyncEventQueue {
+  constructor() {
+    this.buffer = [];
+    this.waiters = [];
+    this.closed = false;
+  }
+
+  push(value) {
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (waiter) waiter({ value, done: false });
+    else this.buffer.push(value);
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length) this.waiters.shift()({ value: undefined, done: true });
+  }
+
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.buffer.length) return Promise.resolve({ value: this.buffer.shift(), done: false });
+        if (this.closed) return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => this.waiters.push(resolve));
+      },
+      return: () => {
+        this.close();
+        return Promise.resolve({ value: undefined, done: true });
+      },
+    };
+  }
+}

package/lib/chat/list-picker.mjs

@@ -0,0 +1,112 @@
+/**
+ * lib/chat/list-picker.mjs — searchable list picker for construct chat Ink.
+ *
+ * Pure state/helpers for arrow-key overlays: type-to-filter, windowed viewport,
+ * and selection index clamping for model, setting, and permission pickers.
+ */
+
+export function filterPickerItems(items = [], query = '') {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return items;
+  return items.filter((item) => {
+    const hay = [item.id, item.label, item.detail, item.tag]
+      .filter(Boolean)
+      .join(' ')
+      .toLowerCase();
+    return hay.includes(q);
+  });
+}
+
+export function pickerStartIndex(items, selectedId, idKey = 'id') {
+  if (!items?.length) return 0;
+  const idx = items.findIndex((item) => item[idKey] === selectedId);
+  if (idx >= 0 && !items[idx]?.disabled) return idx;
+  const firstEnabled = items.findIndex((item) => !item.disabled);
+  if (firstEnabled >= 0) return firstEnabled;
+  return idx >= 0 ? idx : 0;
+}
+
+export function windowPickerItems(items, index, windowSize = 12) {
+  if (!items?.length) return { items: [], offset: 0 };
+  const size = Math.max(5, windowSize);
+  let start = Math.max(0, index - Math.floor(size / 2));
+  if (start + size > items.length) start = Math.max(0, items.length - size);
+  return { items: items.slice(start, start + size), offset: start };
+}
+
+export function clampPickerIndex(state) {
+  const visible = filterPickerItems(state.items, state.query);
+  const max = Math.max(0, visible.length - 1);
+  return { ...state, index: Math.min(state.index, max) };
+}
+
+/**
+ * @param {{
+ *   kind?: string,
+ *   title?: string,
+ *   items?: Array<Record<string, unknown>>,
+ *   selectedId?: string | null,
+ *   context?: string | null,
+ *   query?: string,
+ * }} [opts]
+ */
+export function createListPickerState({
+  kind, title, items, selectedId = null, context = null, query = '',
+} = {}) {
+  const visible = filterPickerItems(items, query);
+  return {
+    kind,
+    title,
+    items,
+    query,
+    index: pickerStartIndex(visible, selectedId),
+    context,
+  };
+}
+
+export function getPickerVisibleItems(state) {
+  return filterPickerItems(state?.items || [], state?.query || '');
+}
+
+export function getPickerSelectedItem(state) {
+  const visible = getPickerVisibleItems(state);
+  return visible[state?.index ?? 0] || null;
+}
+
+export function movePickerIndex(state, delta) {
+  const visible = getPickerVisibleItems(state);
+  if (!visible.length) return state;
+  let idx = state.index ?? 0;
+  for (let step = 0; step < visible.length; step++) {
+    idx = Math.max(0, Math.min(visible.length - 1, idx + delta));
+    if (!visible[idx]?.disabled) return { ...state, index: idx };
+    if ((delta < 0 && idx === 0) || (delta > 0 && idx === visible.length - 1)) break;
+  }
+  return { ...state, index: idx };
+}
+
+export function appendPickerQuery(state, char) {
+  if (!char) return state;
+  return clampPickerIndex({ ...state, query: `${state.query || ''}${char}`, index: 0 });
+}
+
+export function backspacePickerQuery(state) {
+  return clampPickerIndex({ ...state, query: (state.query || '').slice(0, -1), index: 0 });
+}
+
+export function reducePickerKey(state, { char, key } = {}) {
+  if (!state) return { state: null, action: 'none' };
+  if (key?.escape) return { state: null, action: 'cancel' };
+  if (key?.return) return { state, action: 'commit' };
+  if (key?.upArrow) return { state: movePickerIndex(state, -1), action: 'none' };
+  if (key?.downArrow) return { state: movePickerIndex(state, 1), action: 'none' };
+  if (key?.backspace || key?.delete) return { state: backspacePickerQuery(state), action: 'none' };
+  if (char && !key?.ctrl && !key?.meta) return { state: appendPickerQuery(state, char), action: 'none' };
+  return { state, action: 'none' };
+}
+
+export function pickerViewport(state, windowSize = 14) {
+  const visible = getPickerVisibleItems(state);
+  const clamped = clampPickerIndex({ ...state, items: visible });
+  return windowPickerItems(visible, clamped.index, windowSize);
+}

package/lib/chat/model-picker.mjs

@@ -0,0 +1,356 @@
+/**
+ * lib/chat/model-picker.mjs — model list data for the construct chat picker.
+ *
+ * Curates a short list: free-router auto-pick, live OpenRouter free models,
+ * configured provider tier defaults, and the active session model. Persistence
+ * reuses saveChatConfig from lib/chat/config.mjs.
+ */
+
+import { saveChatConfig } from './config.mjs';
+import { hasAnySecret } from '../providers/secret-resolver.mjs';
+import { getProviderModelCatalog, isChatModelAvailable } from '../model-router.mjs';
+import {
+  pollConfiguredProviders,
+  readProviderCatalogCache,
+} from '../models/provider-poll.mjs';
+import { resolveFreeOpenRouterModel } from '../../apps/chat/engine/models.mjs';
+import { filterPickerItems, pickerStartIndex, windowPickerItems } from './list-picker.mjs';
+
+export { filterPickerItems, pickerStartIndex, windowPickerItems };
+
+export const FREE_ROUTER_ITEM_ID = '__free_router__';
+
+export function sortModelsForPicker(models = []) {
+  return [...models].sort(
+    (a, b) => Number(Boolean(b.action === 'free-router')) - Number(Boolean(a.action === 'free-router'))
+      || Number(Boolean(b.isFree)) - Number(Boolean(a.isFree))
+      || Number(b.suitable !== false) - Number(a.suitable !== false)
+      || Number(Boolean(b.isProviderDefault)) - Number(Boolean(a.isProviderDefault))
+      || String(a.label || a.id).localeCompare(String(b.label || b.id)),
+  );
+}
+
+function shortModelLabel(id) {
+  if (!id) return id;
+  const name = id.replace(/^openrouter\//, '');
+  const slash = name.lastIndexOf('/');
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+function catalogItem(model) {
+  const id = model.id;
+  const isFree = id.includes(':free') || model.isFree === true;
+  return {
+    id,
+    label: model.label || (isFree ? shortModelLabel(id) : id),
+    tag: model.action === 'free-router' ? 'router' : isFree ? 'free' : model.local ? 'local' : model.tier || null,
+    detail: model.detail || model.name || (model.configured === false ? 'not configured' : null),
+    isFree,
+    action: model.action || null,
+    suitable: model.suitable,
+    disabled: model.disabled === true,
+  };
+}
+
+export function configuredTierPickerItems({ env = process.env } = {}) {
+  const { providers } = getProviderModelCatalog({ env });
+  const items = [];
+  const seen = new Set();
+  for (const provider of providers) {
+    if (!provider.configured) continue;
+    for (const tier of ['reasoning', 'standard', 'fast']) {
+      const id = provider.tiers?.[tier];
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      const availability = isChatModelAvailable(id, { env });
+      const notPulled = availability.reason === 'model_not_pulled';
+      items.push(catalogItem({
+        id,
+        label: id,
+        name: `${provider.label} · ${tier}`,
+        tier,
+        configured: availability.ok,
+        suitable: availability.ok,
+        isProviderDefault: tier === 'standard',
+        disabled: !availability.ok,
+        detail: notPulled
+          ? `not installed — run ollama pull ${availability.nativeModel || id.replace(/^ollama\//, '')}`
+          : availability.ok ? null : availability.reason?.replace(/_/g, ' ') || 'unavailable',
+      }));
+    }
+  }
+  return { items, seen };
+}
+
+function capabilityBadges(model) {
+  const badges = [];
+  if (model.reasoning) badges.push('reasoning');
+  if (model.vision) badges.push('vision');
+  if (model.tools) badges.push('tools');
+  return badges;
+}
+
+function priceLabel(pricing) {
+  if (!pricing) return null;
+  if (pricing.input === 0 && pricing.output === 0) return null;
+  const fmt = (n) => (n >= 1 ? n.toFixed(2) : n.toFixed(3));
+  return `$${fmt(pricing.input)} in · $${fmt(pricing.output)} out / 1M`;
+}
+
+function contextLabel(context) {
+  if (!context) return null;
+  if (context >= 1_000_000) return `${(context / 1_000_000).toFixed(1).replace(/\.0$/, '')}M ctx`;
+  if (context >= 1000) return `${Math.round(context / 1000)}K ctx`;
+  return `${context} ctx`;
+}
+
+function pickerItemFromModel(model, groupLabel) {
+  if (model.source === 'hint' || model.disabled) {
+    return {
+      id: model.id,
+      label: model.label || model.id,
+      group: groupLabel,
+      tag: null,
+      badges: [],
+      detail: null,
+      isFree: false,
+      suitable: false,
+      disabled: true,
+      source: model.source || 'hint',
+    };
+  }
+  const badges = capabilityBadges(model);
+  const price = priceLabel(model.pricing);
+  const detailParts = [];
+  if (model.free) detailParts.push(model.provider === 'ollama' ? 'free · runs locally' : 'free');
+  else if (price) detailParts.push(price);
+  const ctx = contextLabel(model.context);
+  if (ctx) detailParts.push(ctx);
+  if (model.source === 'cached') detailParts.push('cached — provider offline');
+
+  // The OpenRouter free router answers from whatever free model is available, so
+  // quality and behavior vary turn to turn — say so before it is selected.
+  if (/^openrouter\/openrouter\/(free|auto)\b/.test(String(model.id))) {
+    detailParts.push('variable quality — routes to a random free model');
+  }
+  return {
+    id: model.id,
+    label: model.label || shortModelLabel(model.id),
+    group: groupLabel,
+    tag: model.free ? 'free' : null,
+    badges,
+    price: model.free ? null : price,
+    context: model.context || null,
+    detail: detailParts.join(' · ') || null,
+    isFree: Boolean(model.free),
+    suitable: true,
+    disabled: false,
+    source: model.source || 'live',
+  };
+}
+
+// One picker payload: the free-router auto-pick on top, then every configured
+// provider's live catalog grouped under its label. Polling is best-effort; on a
+// total failure the cached groups (or nothing beyond free-router) are used so the
+// picker still opens.
+export async function loadModelPickerItems(_driver, { env = process.env, cwd = process.cwd(), currentModel = null, modelMode = 'pinned', pollProviders = pollConfiguredProviders } = {}) {
+  const items = [];
+  const seen = new Set();
+
+  const hasOpenRouter = hasAnySecret(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], { env });
+  items.push({
+    id: FREE_ROUTER_ITEM_ID,
+    label: 'OpenRouter free router — auto-pick best standard model',
+    group: 'Smart routing',
+    tag: 'router',
+    badges: [],
+    detail: hasOpenRouter
+      ? 'auto-picks a free model + retries on failure; not pinned — quality varies'
+      : 'needs OPENROUTER_API_KEY in ~/.construct/config.env',
+    action: 'free-router',
+    configured: hasOpenRouter,
+    disabled: !hasOpenRouter,
+  });
+  seen.add(FREE_ROUTER_ITEM_ID);
+
+  let groups = [];
+  try {
+    groups = await pollProviders({ env, cwd });
+  } catch {
+    groups = readProviderCatalogCache() || [];
+  }
+
+  for (const group of groups) {
+    const sorted = [...group.models].sort(
+      (a, b) => Number(Boolean(b.free)) - Number(Boolean(a.free))
+        || String(a.label || a.id).localeCompare(String(b.label || b.id)),
+    );
+    for (const model of sorted) {
+      if (seen.has(model.id)) continue;
+
+      // The chat loop always dispatches tools, so a model the provider reports as
+      // tool-incapable can only ever error out — drop it from the picker. Only
+      // filter when the provider actually told us (toolsKnown); an unknown
+      // capability (e.g. a local Ollama tag) stays selectable.
+      if (!model.disabled && model.source !== 'hint' && model.toolsKnown === true && !model.tools) {
+        seen.add(model.id);
+        continue;
+      }
+
+      seen.add(model.id);
+      items.push(pickerItemFromModel(model, group.label));
+    }
+  }
+
+  if (currentModel && modelMode !== 'free-router' && !seen.has(currentModel)) {
+    seen.add(currentModel);
+    items.push(pickerItemFromModel(
+      { id: currentModel, label: currentModel, free: false, source: 'live' },
+      'Current session',
+    ));
+  }
+
+  return items;
+}
+
+export async function resolveModelPickerSelection(item, { env = process.env } = {}) {
+  if (!item) return null;
+  if (item.action === 'free-router' || item.id === FREE_ROUTER_ITEM_ID) {
+    const modelId = await resolveFreeOpenRouterModel({ env, tier: 'standard' });
+    return modelId ? { mode: 'free-router', modelId } : null;
+  }
+  return { mode: 'pinned', modelId: item.id };
+}
+
+export function commitPickerModel(session, selection, { cwd, hostId = 'construct', layers = null } = {}) {
+  const normalized = typeof selection === 'string'
+    ? { mode: 'pinned', modelId: selection }
+    : selection;
+  if (!normalized?.modelId && normalized?.mode !== 'free-router') return null;
+
+  session.modelMode = normalized.mode || 'pinned';
+  session.model = normalized.modelId;
+  session.savedModel = session.modelMode === 'pinned' ? normalized.modelId : null;
+  session.modelNotice = null;
+
+  try {
+    saveChatConfig({
+      host: hostId,
+      model: session.modelMode === 'pinned' ? session.model : null,
+      modelMode: session.modelMode,
+      layers: layers || session.layers,
+      thinking: (layers || session.layers)?.thinking,
+      permissionMode: session.permissionMode,
+      sandbox: session.sandbox,
+      ui: session.ui,
+    }, { cwd });
+  } catch { /* persistence is best-effort */ }
+  return normalized;
+}
+
+export function pickerSelectedId(session) {
+  if (session?.modelMode === 'free-router') return FREE_ROUTER_ITEM_ID;
+  return session?.savedModel || session?.model || null;
+}
+
+export function formatModelHeader(session) {
+  if (session?.modelMode === 'free-router') {
+    const slug = session.model ? session.model.replace(/^openrouter\//, '') : '(resolving…)';
+    return { label: `free router → ${slug}`, isRouter: true };
+  }
+  const active = session?.model || '(no model)';
+  const saved = session?.savedModel;
+  if (saved && saved !== session?.model) {
+    return { label: active, savedPin: saved, isRouter: false };
+  }
+  return { label: active, isRouter: false };
+}
+
+function formatPickerLine(item, colors, { selected = false } = {}) {
+  const marker = selected ? `${colors.green}●${colors.reset}` : ' ';
+  const tag = item.tag ? `${colors.dim} [${item.tag}]${colors.reset}` : '';
+  const badges = item.badges?.length ? `${colors.dim} ${item.badges.map((b) => `·${b}`).join(' ')}${colors.reset}` : '';
+  const disabled = item.disabled ? `${colors.dim} (unavailable)${colors.reset}` : '';
+  const detail = item.detail ? `\n      ${colors.dim}${item.detail}${colors.reset}` : '';
+  return `  ${marker} ${item.label || item.id}${tag}${badges}${disabled}${detail}`;
+}
+
+export async function promptModelPickerTerminal({
+  output,
+  colors,
+  session,
+  rl = null,
+  askFn = null,
+  env = process.env,
+  cwd = process.cwd(),
+  hostId = 'construct',
+  layers = session?.layers,
+  pollProviders = pollConfiguredProviders,
+} = {}) {
+  const items = await loadModelPickerItems(null, {
+    env,
+    cwd,
+    currentModel: session?.model,
+    modelMode: session?.modelMode || 'pinned',
+    pollProviders,
+  });
+  if (!items.length) {
+    output.write(`${colors.dim}no models to pick from — set a provider key in ~/.construct/config.env or use /model <id>${colors.reset}\n`);
+    return null;
+  }
+
+  const selectedId = pickerSelectedId(session);
+  output.write(`${colors.bold}select a model${colors.reset}\n`);
+  output.write(`${colors.dim}enter a number, or press enter to cancel${colors.reset}\n`);
+  const groupCounts = new Map();
+  for (const item of items) {
+    if (!item.group || item.disabled) continue;
+    groupCounts.set(item.group, (groupCounts.get(item.group) || 0) + 1);
+  }
+  let lastGroup = null;
+  items.forEach((item, i) => {
+    if (item.group && item.group !== lastGroup) {
+      lastGroup = item.group;
+      const count = groupCounts.get(item.group);
+      const suffix = count ? ` (${count})` : '';
+      output.write(`\n${colors.dim}── ${item.group}${suffix} ──${colors.reset}\n`);
+    }
+    output.write(`${String(i + 1).padStart(2)}.${formatPickerLine(item, colors, { selected: item.id === selectedId })}\n`);
+  });
+
+  const prompt = `${colors.green}model #${colors.reset} `;
+  const answer = rl
+    ? (await new Promise((resolve) => rl.question(prompt, resolve))).trim()
+    : askFn
+      ? String(await askFn(prompt)).trim()
+      : '';
+  if (!answer) {
+    output.write(`${colors.dim}${rl || askFn ? 'cancelled' : 'pick one with /model <id> or use the Ink UI for search'}${colors.reset}\n`);
+    return null;
+  }
+
+  const idx = Number(answer) - 1;
+  if (!Number.isInteger(idx) || idx < 0 || idx >= items.length) {
+    output.write(`${colors.red}invalid selection${colors.reset}\n`);
+    return null;
+  }
+
+  const item = items[idx];
+  if (item.disabled) {
+    output.write(`${colors.red}${item.detail || 'model not available'}${colors.reset}\n`);
+    return null;
+  }
+
+  const selection = await resolveModelPickerSelection(item, { env });
+  if (!selection?.modelId && selection?.mode !== 'free-router') {
+    output.write(`${colors.red}could not resolve model${colors.reset}\n`);
+    return null;
+  }
+
+  commitPickerModel(session, selection, { cwd, hostId, layers });
+  const label = selection.mode === 'free-router'
+    ? `free-router → ${selection.modelId}`
+    : selection.modelId;
+  output.write(`${colors.green}model set:${colors.reset} ${label} ${colors.dim}(saved)${colors.reset}\n`);
+  return selection;
+}