@chatpanel/events 0.84.1 → 0.88.0

package/route-strategies.js

@@ -0,0 +1,232 @@
+// HOW A MODEL IS CHOSEN — the strategies and the one step that is never optional.
+//
+// The routing CONTRACT (createModelRouter, signals, requirements, failover order) has lived
+// in this package since it was written; the DECISIONS layered on it — escalate hard work,
+// replace like with like, honour "use claude" — were typed in the extension, so the desktop
+// was about to copy them. They are pure functions of the candidates and the need, so they
+// belong here, and both clients build the same router from the same declarations.
+//
+// `needForTurn` builds the need from the turn's facts. The source guard (which page or
+// record the turn is about, and what that caps reach at) is INJECTED as `guard`, because
+// reading it means reading a client's settings; the ceiling itself is enforced here.
+
+import {
+  defineMiddleware, defineRouteStrategy, signalsFrom, requirementsFor, preferenceFor,
+  failoverOrder, pinnedOrderOf,
+} from './router.js';
+
+/**
+ * Redaction is REQUIRED for anything that leaves the user's machine.
+ *
+ * Declared as middleware with `requiredFor` so the router refuses to route to a third party
+ * when it is not active. That is the difference between "we always redact" as a habit and as
+ * a property: a disabled plugin, a refactor or a new caller cannot quietly skip it.
+ */
+export const redactionStep = defineMiddleware({
+  id: 'redaction',
+  label: 'Redaction',
+  stage: 'request',
+  priority: 10,   // before anything that reads the text
+  requiredFor: (model) => model.reach === 'any',
+  // The actual redaction still happens in streamChat's harness. This declares the
+  // REQUIREMENT; wiring the implementation through here is the next step, and doing both at
+  // once would mean changing what redaction does in the same commit that changes when it runs.
+  run: async (request) => request,
+});
+
+/**
+ * Escalate when the task is actually hard.
+ *
+ * The router was picking the cheapest eligible model for everything, which is right for
+ * "hello" and wrong for "draw a circle around Mickey" — a request needing spatial reasoning
+ * and a structured payload went to a 26B model because it was free. Cost is the correct
+ * tie-breaker among models that can all do the job; it is the wrong one when they cannot.
+ *
+ * Class R: length, code fences, image content and page tools are all readable for nothing.
+ * The escalation itself costs no model call — only the answer does, and that is the point.
+ */
+export const complexityStrategy = defineRouteStrategy({
+  id: 'escalate-on-complexity',
+  label: 'Escalate hard tasks',
+  classUsed: 'R',
+  decide: async (eligible, need) => {
+    const sig = need.signals;
+    // ASKED FOR NOTHING, ESCALATES TO NOTHING. This fired on 'hello' because the caller was
+    // passing `structured: structured || pageTools`, so every turn on a page with actions
+    // armed looked like exact structured work. Equipment is not demand — the same conflation
+    // that put a quality floor on a greeting, in a second place.
+    if (sig?.smalltalk) return null;
+    // NOR DOES BACKGROUND WORK ESCALATE. Dropping the quality floor for a topic pass and then
+    // letting escalation rank by quality anyway would move the same decision one step down
+    // and change nothing — the floor eliminated the local models, this would simply rank them
+    // last. Both read 'high' from the size of the material rather than the difficulty of the
+    // ask, so both have to abstain.
+    if (need.background) return null;
+    const hard = sig?.complexity === 'high' || sig?.modality === 'vision' || need.structured;
+    if (!hard) return null;   // no opinion on easy work — let cost decide
+    // Prefer a model that claims what this task actually wants. Not a hard filter: declaring
+    // "reasoning" required would eliminate every model on a setup where nobody has ticked
+    // the box, and an empty candidate list is a worse answer than a merely adequate model.
+    const wants = new Set();
+    if (sig?.complexity === 'high') wants.add('reasoning');
+    if (need.structured) wants.add('tools');
+    if (sig?.modality === 'vision') wants.add('vision');
+    if (sig?.approxTokens > 20_000) wants.add('long-context');
+    const fit = (m) => [...wants].filter((c) => m.capabilities.includes(c)).length;
+    const best = Math.max(...eligible.map(fit));
+    let shortlist = best > 0 ? eligible.filter((m) => fit(m) === best) : eligible;
+
+    // STRUCTURED WORK WANTS A MODEL, NOT AN AGENT.
+    //
+    // A canvas or spreadsheet adapter is one call: hand it the data, it applies it, done. A
+    // CLI agent runs its OWN loop — it explores, reads files, decides what to do next — and
+    // having applied the shapes correctly it carries on, because finishing is not something
+    // its loop is told about. A user watched the circle appear and then waited until they
+    // killed the process.
+    //
+    // Not a hard filter: on a setup with only agents, an agent that overruns still beats no
+    // answer.
+    if (need.structured) {
+      const models = shortlist.filter((m) => m.classUsed !== 'A');
+      if (models.length) shortlist = models;
+    }
+    // Rank by declared quality — the axis this strategy exists to judge — then by the ORDER
+    // the user set, and only then by cost. A model with an unknown quality sits mid-table
+    // rather than last, so a newly added model is not permanently skipped.
+    //
+    // ORDER BEFORE COST, and this is the fix for a real complaint: three CLI agents of
+    // identical quality, one of them pinned to Order 1, and escalation picked a different one
+    // because it is cheaper per 1k. A hand-set order is a statement — they can see the prices
+    // and chose anyway — and it was being honoured in the score path and nowhere else, so
+    // the moment any strategy had an opinion the user's own preference stopped existing.
+    //
+    // Still only a TIE-BREAK: quality decides first, so a genuinely better model beats the
+    // pinned one, and an INFERRED order stays below cost where a guess belongs.
+    const q = (m) => (Number.isFinite(m.quality) ? m.quality : 0.5);
+    return [...shortlist].sort((a, b) => q(b) - q(a)
+      || pinnedOrderOf(a) - pinnedOrderOf(b) || a.costPer1k - b.costPer1k);
+  },
+});
+
+/**
+ * When a model declines, replace it with the closest thing available — not the cheapest.
+ *
+ * A frontier model that ran out of credits mid-task should be replaced by the same model at
+ * another provider, or by something comparably capable. Falling back to a small local model
+ * is how a drawing that was going well turns into a circle in the wrong place: the task did
+ * not get easier when the provider said no.
+ *
+ * Ranked by closeness to what failed, in the order that actually matters:
+ *   1. the SAME model somewhere else — identical capability, merely a different bill;
+ *   2. a model with every capability the failed one had, best quality first;
+ *   3. anything else, so the turn still completes rather than dying.
+ */
+export const failoverStrategy = defineRouteStrategy({
+  id: 'failover-to-similar',
+  label: 'Replace like with like',
+  classUsed: 'R',
+  decide: async (eligible, need) => {
+    const failed = need.like;
+    if (!failed) return null;
+    // THE ORDERING ITSELF LIVES IN @chatpanel/events, because two things need it: this
+    // strategy, and the projected chain the trace draws before any of it happens. A picture
+    // computed by a second implementation would eventually disagree with the real failover,
+    // and one that lies about what the router will do is worse than no picture. The strategy
+    // is the thin part — knowing there IS something to replace.
+    return failoverOrder(eligible, failed);
+  },
+});
+
+/**
+ * "use claude" is an instruction, not a topic.
+ *
+ * A user naming a model in their message was being ignored entirely — the router read
+ * length, modality and tools, and not the one signal that is an explicit answer to the
+ * question it was asking. Asking for a specific model and being given another is the most
+ * annoying possible failure of a router, because it looks like the request was not read.
+ *
+ * DELIBERATELY CONSERVATIVE. Only imperative forms count — "use X", "with X", "ask X",
+ * "switch to X" — so "tell me about claude" stays a question about Claude rather than a
+ * routing instruction. A false positive here silently sends work to the wrong model, which
+ * is worse than missing an unusual phrasing.
+ *
+ * It still cannot widen reach: like every strategy it only ever chooses among candidates the
+ * hard constraints already allowed. A device-only request naming a cloud model still stays
+ * on-device.
+ */
+export const explicitModelStrategy = defineRouteStrategy({
+  id: 'named-by-user',
+  label: 'Use the model you asked for',
+  classUsed: 'R',
+  decide: async (eligible, need) => {
+    const text = String(need.requestText || '').toLowerCase();
+    if (!text) return null;
+    const directive = /\b(?:use|using|with|via|ask|switch to|route to|try)\s+([a-z0-9][a-z0-9.\- ]{1,28})/g;
+    const asked = [];
+    for (const m of text.matchAll(directive)) asked.push(m[1].trim());
+    if (!asked.length) return null;
+
+    const matches = eligible.filter((cand) => {
+      const names = [cand.label, cand.model, cand.id].filter(Boolean).map((x) => String(x).toLowerCase());
+      return asked.some((want) => names.some((n) => n.includes(want) || want.includes(n.split(' · ')[0])));
+    });
+    if (!matches.length) return null;   // named something we do not have? say nothing and let the rest decide
+    // WHICH ONE, when the name matches several. This took the FIRST match in score order, so
+    // "use claude" on a setup with three Claude routes picked whichever happened to score
+    // best — a cost-and-latency guess deciding a question the user had already answered
+    // twice: once by naming the model, and once by ordering the routes to it.
+    //
+    // Returned as a LIST rather than a single model, so the ones that also matched become the
+    // runners-up: if the first declines, failover replaces it with another route to the model
+    // that was actually asked for.
+    return [...matches].sort((a, b) => pinnedOrderOf(a) - pinnedOrderOf(b));
+  },
+});
+
+// Ordered deliberately: an explicit request outranks every heuristic, because the user has
+// answered the question the router was about to guess at. Failover next — a decline is newer
+// information than the preference that made the original choice. Escalation is the general
+// case.
+export const ROUTE_STRATEGIES = [explicitModelStrategy, failoverStrategy, complexityStrategy];
+export const ROUTE_MIDDLEWARE = [redactionStep];
+
+export function needForTurn({ capabilities = [], request = null, structured = false, pageTools = false, force = false, background = false, guard = null } = {}) {
+  const signals = request ? signalsFrom(request) : {};
+  // REQUIREMENTS FIRST. What the work needs eliminates candidates; cost and speed only order
+  // what survives. A preference lets an unsuitable model win once the better ones decline,
+  // which is exactly how a chain of five ended on one that could not do the job.
+  const req = requirementsFor(signals, { structured, pageTools, hasTools: capabilities.includes('tools'), background });
+  // WHERE IT CAME FROM IS A CEILING, NOT A PREFERENCE. Routing asked what the work needed and
+  // never asked what it was about, so an internal page was summarised by a public inference
+  // host. This narrows reach and can only narrow it — reach is never relaxed (see the
+  // relaxation order in the router), so no later step can trade it away for capability.
+  // WHICH AXIS THIS REQUEST CARES ABOUT, read from the request rather than fixed at
+  // 'balanced' for everything. A greeting means fast — no answer to "hi" is improved by a
+  // frontier model thinking about it. A refactor means good — three seconds saved on an
+  // answer that has to be redone is not a saving. It only ever ORDERS what already
+  // qualifies; `req` above is what eliminates.
+  const pref = preferenceFor(signals, {
+    structured,
+    minQuality: req.minQuality,
+    // The same fact requirementsFor was given: a turn carrying tools is one that might use
+    // them, so it is never "answer fast at any quality".
+    hasTools: capabilities.includes('tools'),
+    background,
+  });
+  return {
+    prefer: pref.prefer,
+    reach: guard ? guard.reach : 'any',
+    capabilities: [...new Set([...capabilities, ...req.required])],
+    minQuality: req.minQuality,
+    // Which requirements may be given up if nothing qualifies — never `tools`, and never
+    // reach. See requirementsFor.
+    negotiable: req.negotiable,
+    requirementReasons: [...(guard ? [...req.why, guard.why] : req.why), pref.why],
+    sourceGuard: guard,
+    signals,
+    requestText: request ? String(request.text || (request.messages || []).map((m) => m?.content || '').join('\n')).slice(-2000) : '',
+    structured,
+    force,
+    background,
+  };
+}

package/scm-connection.js

@@ -0,0 +1,180 @@
+// An SCM CONNECTION — how a harness engine reaches the organisation's source-control hub —
+// and the two names a job gets in it: its branch and its worktree directory.
+// (architecture-pillars.md §14: the repository is the source of truth.)
+//
+// ChatPanel is not a git host and not a git client. The harness runs `git`, `gh`, `glab`;
+// ChatPanel brings the CREDENTIAL, the WORKTREE, the BRANCH NAME and the RECORD. This module
+// is the pure part: what a connection record holds, how a remote URL maps to one, what a
+// job's branch is called, and the environment that hands a token to git for ONE process
+// without writing it anywhere.
+//
+// THE TOKEN IS NEVER IN THE RECORD. A connection stores a `secretRef` — the name under which
+// the machine's keychain (or the bridge's secret store) holds the token. The record travels
+// with the client-prefs document (`connections` section) so both clients show the same
+// connections; the secret does not travel, and `normalizeConnection` REFUSES a record that
+// carries one, so a settings export, a sync, or a prompt can never carry it either.
+
+export const SCM_KINDS = Object.freeze(['github', 'github-enterprise', 'gitlab', 'bitbucket', 'gitea', 'azure-devops', 'git']);
+export const CONNECTION_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const SECRET_REF_RE = /^[a-zA-Z0-9_.:@/-]{1,200}$/;
+const SECRET_FIELDS = ['token', 'password', 'secret', 'pat', 'apiKey', 'key'];
+const DEFAULT_HOST = { github: 'github.com', gitlab: 'gitlab.com', bitbucket: 'bitbucket.org', 'azure-devops': 'dev.azure.com' };
+
+export class ScmError extends Error {
+  constructor(code, message) { super(message); this.name = 'ScmError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** The host a connection serves: its baseUrl's, or the kind's public host. */
+export function hostOf(conn) {
+  const url = String(conn?.baseUrl || '').trim();
+  if (url) { try { return new URL(/^https?:\/\//i.test(url) ? url : `https://${url}`).host.toLowerCase(); } catch { return url.toLowerCase().replace(/^https?:\/\//, '').split('/')[0]; } }
+  return DEFAULT_HOST[conn?.kind] || '';
+}
+
+export function validateConnection(conn) {
+  const errors = [];
+  if (!isRecord(conn)) return { ok: false, errors: ['connection must be an object'] };
+  if (!CONNECTION_ID_RE.test(String(conn.id || ''))) errors.push('id: a short identifier (letters, digits, _ -)');
+  if (!SCM_KINDS.includes(conn.kind)) errors.push(`kind: one of ${SCM_KINDS.join(', ')}`);
+  const needsHost = ['github-enterprise', 'gitea', 'git'].includes(conn.kind);
+  if (needsHost && !String(conn.baseUrl || '').trim()) errors.push('baseUrl: the hub\'s URL');
+  if (conn.baseUrl && !/^(https?:\/\/)?[a-z0-9.-]+(:\d+)?(\/[^\s]*)?$/i.test(String(conn.baseUrl).trim())) errors.push('baseUrl: a host or URL');
+  const leaked = SECRET_FIELDS.filter((k) => conn[k] !== undefined && conn[k] !== null && conn[k] !== '');
+  if (leaked.length) errors.push(`${leaked.join(', ')}: a connection never stores a secret — store it in the keychain and reference it by secretRef`);
+  if (conn.secretRef !== undefined && conn.secretRef !== null && conn.secretRef !== '' && !SECRET_REF_RE.test(String(conn.secretRef))) errors.push('secretRef: a keychain / secret-store name');
+  if (conn.reach !== undefined && !Array.isArray(conn.reach)) errors.push('reach: a list of remotes or owners this connection may be used for');
+  return { ok: errors.length === 0, errors };
+}
+
+/** The stored form. Throws on a record that carries a secret. */
+export function normalizeConnection(conn) {
+  const v = validateConnection(conn);
+  if (!v.ok) throw new ScmError('INVALID', v.errors.join('; '));
+  const id = String(conn.id);
+  return {
+    id,
+    kind: conn.kind,
+    label: String(conn.label || conn.name || '').trim().slice(0, 80) || `${conn.kind} · ${hostOf(conn) || id}`,
+    ...(conn.baseUrl ? { baseUrl: String(conn.baseUrl).trim().replace(/\/+$/, '') } : {}),
+    // The secret's NAME — `chatpanel:scm:<id>` by default — under which the keychain holds it.
+    secretRef: String(conn.secretRef || '').trim() || `chatpanel:scm:${id}`,
+    ...(conn.username ? { username: String(conn.username).trim().slice(0, 80) } : {}),
+    // Which remotes it may be used for: `owner/*`, `owner/name`, or a host. Empty = any on its host.
+    reach: (Array.isArray(conn.reach) ? conn.reach : []).map((r) => String(r).trim().toLowerCase()).filter(Boolean).slice(0, 64),
+    enabled: conn.enabled !== false,
+    ...(conn.createdAt ? { createdAt: conn.createdAt } : {}),
+  };
+}
+
+/**
+ * A remote URL, read: `{ host, owner, name, protocol }` for https, ssh (`git@host:o/n.git`,
+ * `ssh://git@host/o/n`) and plain `host/o/n`. Credentials in the URL are dropped, never
+ * returned. Null for what cannot be read.
+ */
+export function parseRemote(url) {
+  const s = String(url || '').trim();
+  if (!s) return null;
+  let m = /^(?:ssh:\/\/)?(?:[\w.-]+@)?([a-z0-9.-]+)(?::\d+)?[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(s.replace(/^https?:\/\/(?:[^@/]+@)?/i, ''));
+  if (m && !/^https?:/i.test(s)) return { host: m[1].toLowerCase(), owner: m[2], name: m[3], protocol: /^ssh:|^[\w.-]+@/.test(s) ? 'ssh' : 'plain' };
+  try {
+    const u = new URL(s);
+    const parts = u.pathname.replace(/\.git$/, '').split('/').filter(Boolean);
+    if (parts.length < 2) return null;
+    // Azure DevOps: /org/project/_git/repo; GitLab subgroups: /a/b/c/repo — owner is all but the last.
+    const name = parts.at(-1);
+    const owner = parts.slice(0, -1).filter((p) => p !== '_git').join('/');
+    return { host: u.host.toLowerCase(), owner, name, protocol: u.protocol.replace(':', '') };
+  } catch { return null; }
+}
+
+/**
+ * The connection to use for a remote: enabled, same host, and — when the connection lists
+ * a reach — the remote's `owner/name` or `owner/*` in it. The most specific reach wins.
+ */
+export function connectionFor(remote, connections = []) {
+  const r = typeof remote === 'string' ? parseRemote(remote) : remote;
+  if (!r) return null;
+  const slug = `${r.owner}/${r.name}`.toLowerCase();
+  let best = null; let bestScore = -1;
+  for (const c of connections || []) {
+    if (!c || c.enabled === false) continue;
+    if (hostOf(c) !== r.host) continue;
+    const reach = Array.isArray(c.reach) ? c.reach : [];
+    let score = reach.length ? -1 : 0;
+    for (const x of reach) {
+      if (x === slug) score = Math.max(score, 3);
+      else if (x.endsWith('/*') && slug.startsWith(x.slice(0, -1))) score = Math.max(score, 2);
+      else if (x === r.host) score = Math.max(score, 1);
+    }
+    if (score > bestScore) { best = c; bestScore = score; }
+  }
+  return best;
+}
+
+const slug = (s) => String(s || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 48) || 'x';
+
+/** A job's branch: `cp/<project>/<job>` — one branch per job, always under `cp/`, never a protected name. */
+export function branchFor(projectId, jobId) { return `cp/${slug(projectId)}/${slug(jobId)}`; }
+
+/** A job's worktree directory under the bridge's worktree root: `<project>/<job>`. */
+export function worktreeDirFor(projectId, jobId) { return `${slug(projectId)}/${slug(jobId)}`; }
+
+/**
+ * The environment that hands ONE process the token, scoped to the connection's host:
+ * git's `credential.<url>.helper` set through `GIT_CONFIG_*` (never a file, never the
+ * command line), a helper that reads the token from the environment, terminal prompts
+ * off, and the hub CLIs' own variables (`GH_TOKEN` / `GH_HOST`, `GITLAB_TOKEN`) so `gh` and
+ * `glab` work in the same process. The caller spawns with `{ ...process.env, ...env }` and
+ * the token dies with the process.
+ */
+export function credentialEnv(conn, token, { username = null } = {}) {
+  const c = conn || {};
+  const host = hostOf(c);
+  if (!host || !token) return {};
+  const user = username || c.username || ({ github: 'x-access-token', 'github-enterprise': 'x-access-token', gitlab: 'oauth2', bitbucket: 'x-token-auth', gitea: 'oauth2', 'azure-devops': 'pat' }[c.kind] || 'token');
+  const env = {
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_COUNT: '2',
+    GIT_CONFIG_KEY_0: `credential.https://${host}.helper`,
+    // A shell helper: on `get`, answer from the environment. Nothing is written anywhere.
+    GIT_CONFIG_VALUE_0: '!f() { if [ "$1" = get ]; then printf "username=%s\\npassword=%s\\n" "$CHATPANEL_SCM_USER" "$CHATPANEL_SCM_TOKEN"; fi; }; f',
+    GIT_CONFIG_KEY_1: `credential.https://${host}.useHttpPath`,
+    GIT_CONFIG_VALUE_1: 'false',
+    CHATPANEL_SCM_USER: user,
+    CHATPANEL_SCM_TOKEN: String(token),
+  };
+  if (c.kind === 'github' || c.kind === 'github-enterprise') {
+    env.GH_TOKEN = String(token);
+    if (c.kind === 'github-enterprise') { env.GH_ENTERPRISE_TOKEN = String(token); env.GH_HOST = host; }
+  }
+  if (c.kind === 'gitlab') { env.GITLAB_TOKEN = String(token); env.GITLAB_HOST = host; }
+  return env;
+}
+
+/** One line a person reads: "GitHub · github.com · acme/*". */
+export function describeConnection(conn) {
+  const c = conn || {};
+  const kindLabel = { github: 'GitHub', 'github-enterprise': 'GitHub Enterprise', gitlab: 'GitLab', bitbucket: 'Bitbucket', gitea: 'Gitea', 'azure-devops': 'Azure DevOps', git: 'Git' }[c.kind] || c.kind;
+  return `${kindLabel} · ${hostOf(c)}${c.reach?.length ? ` · ${c.reach.join(', ')}` : ''}${c.enabled === false ? ' (off)' : ''}`;
+}
+
+export function blankConnection() { return { id: '', kind: 'github', label: '', baseUrl: '', reach: [], username: '' }; }
+
+/** The editor's form → a connection, or the errors. The token is NOT part of the form's record: the host stores it separately. */
+export function connectionFromForm(form) {
+  const f = form || {};
+  const id = String(f.id || '').trim() || slug(f.label || `${f.kind}-${hostOf(f)}`);
+  const conn = {
+    id, kind: f.kind || 'github', label: String(f.label || '').trim(),
+    ...(f.baseUrl ? { baseUrl: String(f.baseUrl).trim() } : {}),
+    ...(f.username ? { username: String(f.username).trim() } : {}),
+    ...(f.secretRef ? { secretRef: String(f.secretRef).trim() } : {}),
+    reach: String(Array.isArray(f.reach) ? f.reach.join(',') : f.reach || '').split(/[,\s]+/).map((x) => x.trim()).filter(Boolean),
+    enabled: f.enabled !== false,
+    ...(f.createdAt ? { createdAt: f.createdAt } : {}),
+  };
+  const v = validateConnection(conn);
+  return v.ok ? { ok: true, connection: normalizeConnection(conn) } : { ok: false, errors: v.errors };
+}