@worca/app 1.2.0-rc.2 → 1.2.0

package/src/core/plugin-manifest.mjs

@@ -5,6 +5,7 @@
 
 import { readFileSync, readdirSync, readlinkSync, existsSync } from 'node:fs';
 import { join, resolve, dirname, sep, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { WORCA_PLUGIN_API, WORCA_PLUGIN_APIS } from './plugin-api.mjs';
 import { EFFORTS, isReservedModelEnvKey, assertModelCost } from './model-env.mjs';
 import { validateMetaV2, normalizeAgentMeta, indexByKey } from '../shared/graph/agent-meta.mjs';
@@ -19,7 +20,37 @@ const KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const SOURCE_ID_RE = /^[a-z][a-z0-9-]{0,63}$/;
 const FIELD_TYPES = new Set(['text', 'select']);
 const INPUT_TYPES = new Set(['text', 'select', 'remote-select', 'task-browser']);
-const KNOWN_TOP = new Set(['name', 'version', 'description', 'author', 'homepage', 'license', 'engines', 'taskSources', 'chatChannels', 'setup', 'models', 'modelSecrets']);
+// `worca` is a free-form tool-metadata block (the workflow exporter records
+// `worca.exports` there — issue #421); the loader never reads it.
+const KNOWN_TOP = new Set(['name', 'version', 'description', 'author', 'homepage', 'license', 'engines', 'taskSources', 'chatChannels', 'setup', 'models', 'modelSecrets', 'worca']);
+
+/** The built-in agent layer (repo agents/). Same URL math as agent-registry's
+ *  DEFAULT_AGENTS_DIR, duplicated because agent-registry imports THIS module
+ *  (declaredApi) and a back-import would be a cycle. */
+const BUILTIN_AGENTS_DIR = fileURLToPath(new URL('../../agents/', import.meta.url));
+
+/**
+ * Normalized meta v2 sidecars of the built-in layer, for the plugin-template
+ * isolation rule (#421): a template may reference built-ins (immutable, always
+ * present on every host) plus the plugin's own agents — never the user layer
+ * or another plugin. A sidecar that fails the v2 gate is skipped: it ships no
+ * ports, so a template naming it gets the same V4 the runtime would raise.
+ * @param {string} [dir]
+ * @returns {object[]}
+ */
+export function builtinAgentMetas(dir = BUILTIN_AGENTS_DIR) {
+  const out = [];
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => f.endsWith('.meta.json')); } catch { return out; }
+  for (const f of files.sort()) {
+    let meta = null;
+    try { meta = JSON.parse(readFileSync(join(dir, f), 'utf8')); } catch { continue; }
+    if (Number(meta?.metaVersion) !== 2 || !KEY_RE.test(String(meta.key || ''))) continue;
+    if (validateMetaV2(meta).errors.length) continue;
+    out.push(normalizeAgentMeta(meta).meta);
+  }
+  return out;
+}
 const KNOWN_SOURCE = new Set(['id', 'displayName', 'module', 'configSchema', 'inputs', 'multiProfile']);
 const KNOWN_CHANNEL = new Set(['id', 'displayName', 'platform', 'module', 'ingress', 'capabilities', 'configSchema']);
 const CHANNEL_INGRESS = new Set(['connect', 'webhook']);
@@ -497,7 +528,7 @@ export function findEscapingSymlinks(root) {
  * strict: unknown-field warnings become errors.
  * @returns {{ok:boolean, manifest:object|null, problems:Array<{level:'error'|'warn', message:string}>}}
  */
-export function validatePluginDir(absDir, { strict = false } = {}) {
+export function validatePluginDir(absDir, { strict = false, builtinMetas } = {}) {
   const problems = [];
   const push = (level, message) => problems.push({ level, message });
 
@@ -592,12 +623,18 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
 
   // workflows/*.json are v2 GRAPHS (API 3), validated by the SAME shared
   // validator the composer and POST /api/workflows use, over a ports function
-  // built from this plugin's OWN sidecars plus the engine's flow-card ports.
-  // The isolation rule stays: a template may reference only keys this plugin
-  // ships, so a host rename or a deleted user agent can never break it.
+  // built from the BUILT-IN sidecars plus this plugin's OWN, plus the engine's
+  // flow-card ports. The isolation rule (#421): a template may reference
+  // built-ins (immutable, present on every host) and keys this plugin ships —
+  // never the user layer or another plugin — so a host rename or a deleted
+  // user agent can never break it. The plugin's own sidecar wins the index on
+  // a key it shares with a built-in (the registry drops such a plugin agent at
+  // load; the template still validates against the ports it will run with).
   const wfDir = join(absDir, 'workflows');
   if (existsSync(wfDir)) {
-    const portsFn = portsFnFor(indexByKey(ownMetas));
+    const hostMetas = Array.isArray(builtinMetas) ? builtinMetas : builtinAgentMetas();
+    const hostKeys = new Set(hostMetas.map((m) => m.key));
+    const portsFn = portsFnFor(indexByKey([...hostMetas, ...ownMetas]));
     for (const f of readdirSync(wfDir).filter((x) => x.endsWith('.json'))) {
       let tpl = null;
       try { tpl = JSON.parse(readFileSync(join(wfDir, f), 'utf8')); }
@@ -607,14 +644,14 @@ export function validatePluginDir(absDir, { strict = false } = {}) {
       const keys = nodes.filter((n) => n && n.kind === 'agent').map((n) => n.key).filter(Boolean);
       let unresolved = false;
       for (const k of new Set(keys)) {
-        if (agentKeys.has(k)) continue;
+        if (agentKeys.has(k) || hostKeys.has(k)) continue;
         if (ungatedKeys.has(k)) {
           // The sidecar is this plugin's, it just did not pass. Report at the
           // DATA level so an API-1 plugin keeps installing (spec §9) instead of
           // being refused for a template that is fine.
           push(dataLevel, `workflows/${f}: references agent key "${k}" whose sidecar is not a valid meta v2 sidecar`);
         } else {
-          push('error', `workflows/${f}: references agent key "${k}" which this plugin does not ship`);
+          push('error', `workflows/${f}: references agent key "${k}" which is neither a built-in nor shipped by this plugin`);
         }
         unresolved = true;
       }

package/src/core/run-harness.mjs

@@ -3641,6 +3641,13 @@ export class RunHarness extends EventEmitter {
       signal: this.abort.signal,
       bin: this.claude.bin,
       mock: this.claude.mock,
+      // The run's own model is the title default (#422, title.mjs#resolveTitleModel):
+      // an install with no first-party model titles its runs with no setup.
+      runModel: this.claude.model,
+      // A failed title used to vanish into a kept provisional title. Say so in
+      // the run log — once per run, there is only ever one title call.
+      onError: ({ model, error }) => this._log('orchestrator', 'warn',
+        `title generation failed (model ${model}): ${clipMiddle(error?.message || error, 300)} — keeping the provisional title`),
       // Same env policy as the pipeline nodes. Both undefined on an unconfigured
       // project ⇒ byte-identical spawn env (legacy parity).
       envScrub: this.guardrails?.envScrub || undefined,

package/src/core/settings.mjs

@@ -543,8 +543,69 @@ export const SETTINGS_POST_KEYS = Object.freeze([
   'pipelineCostLimitUsd', 'totalCostLimitUsd', 'costLimitResetPeriod',
   'askMaxTurns', 'askMaxBudgetUsd',
   'debugSpawnEnabled',
+  'titleModel', 'hideBuiltinModels',
 ]);
 
+// ── Title-generation model + hidden built-ins (#422) ─────────────────────────
+// `titleModel` is the catalog id every run/chat title is written with; absent
+// means "the model of the run or chat that asked for the title" (title.mjs owns
+// that precedence, and the catalog check — settings.mjs cannot import config.mjs).
+// `hideBuiltinModels` drops the first-party built-ins from every model picker
+// for an install with no first-party account; it is cosmetic + defaults only,
+// a hidden id still resolves (config.mjs#composeCatalog). Both are read at use
+// time like every other stored setting — a UI save reaches the next title call.
+export const DEFAULT_HIDE_BUILTIN_MODELS = false;
+const TITLE_MODEL_MAX_LEN = 200;
+
+const isTitleModelId = (v) => typeof v === 'string' && v.trim().length > 0 && v.length <= TITLE_MODEL_MAX_LEN;
+
+/** The STORED title model id (trimmed), or null when unset/invalid (loudly). */
+export function titleModel() {
+  const v = readSettings().titleModel;
+  if (v === undefined) return null;
+  if (isTitleModelId(v)) return v.trim();
+  console.warn(`[worca] invalid titleModel ${JSON.stringify(v)} — titles use the run's model`);
+  return null;
+}
+
+/** @throws {Error} unless `input` is a non-empty model id (or empty, which clears). */
+export function assertTitleModelInput(input) {
+  if (isClearInput(input)) return;
+  if (!isTitleModelId(input)) throw new Error(`titleModel must be a model id of at most ${TITLE_MODEL_MAX_LEN} characters, or empty to use the run's model`);
+}
+
+export async function setTitleModel(input) {
+  assertTitleModelInput(input);
+  const settings = readSettings();
+  if (isClearInput(input)) delete settings.titleModel;
+  else settings.titleModel = input.trim();
+  await persistSettings(settings);
+  return { titleModel: titleModel() };
+}
+
+/** Whether built-in (first-party) models are hidden from every picker. */
+export function hideBuiltinModels() {
+  const v = readSettings().hideBuiltinModels;
+  if (v === undefined) return DEFAULT_HIDE_BUILTIN_MODELS;
+  if (typeof v === 'boolean') return v;
+  console.warn(`[worca] invalid hideBuiltinModels ${JSON.stringify(v)} — using the default (${DEFAULT_HIDE_BUILTIN_MODELS})`);
+  return DEFAULT_HIDE_BUILTIN_MODELS;
+}
+
+/** @throws {Error} unless `input` is a boolean. */
+export function assertHideBuiltinModelsInput(input) {
+  if (typeof input !== 'boolean') throw new Error('hideBuiltinModels must be true or false');
+}
+
+export async function setHideBuiltinModels(input) {
+  assertHideBuiltinModelsInput(input);
+  const settings = readSettings();
+  if (input === DEFAULT_HIDE_BUILTIN_MODELS) delete settings.hideBuiltinModels;
+  else settings.hideBuiltinModels = input;
+  await persistSettings(settings);
+  return { hideBuiltinModels: hideBuiltinModels() };
+}
+
 // ── Spawn-debug diagnostics toggle (the stored side of WORCA_DEBUG_SPAWN) ────
 // Like every other stored setting (skillMount, the cost caps, the ask caps) this
 // is READ AT USE TIME: claude-runner.mjs#debugSpawnEnabled calls

package/src/core/title.mjs

@@ -1,12 +1,62 @@
 // src/core/title.mjs
 import { runClaude } from './claude-runner.mjs';
-import { resolveModelEnv } from './config.mjs';
+import { resolveModelEnv, catalogHasModel } from './config.mjs';
+import { titleModel as storedTitleModel } from './settings.mjs';
+import { AUX_EFFORT } from './model-env.mjs';
 
-// A fast, cheap model is enough for a one-line summary. Overridable for tests/cost tuning.
-const DEFAULT_TITLE_MODEL =
-  process.env.WORCA_TITLE_MODEL || 'claude-haiku-4-5-20251001';
+// The last-resort title model: the BUILT-IN Haiku id (config.mjs PREDEFINED_MODELS),
+// not the dated API id it used to be — a global entry that shadows the built-in
+// (to route it) must match, or its routing env would never reach a title call.
+export const DEFAULT_TITLE_MODEL = 'claude-haiku-4-5';
 const MAX_LEN = 70;
 
+/**
+ * Which model writes a title, decided PER CALL (#422) — nothing is captured at
+ * import, so a Settings save or an env change reaches the very next title:
+ *   1. `opts.model`            — an explicit caller choice
+ *   2. WORCA_TITLE_MODEL       — a non-empty env override (tests, cost tuning);
+ *                                verbatim, no catalog check: an operator escape hatch
+ *   3. the stored `titleModel` — only while it is still a catalog member; a stale
+ *                                id (plugin removed, entry deleted) is reported and skipped
+ *   4. `opts.runModel`         — the model of the run / chat that asked for the title,
+ *                                which is what makes an install with NO first-party
+ *                                model produce titles with zero configuration
+ *   5. DEFAULT_TITLE_MODEL     — the built-in Haiku
+ * Pure apart from the injectable readers. Exported for tests and for the
+ * settings API (describeTitleModel below).
+ * @param {{model?:string, runModel?:string}} [opts]
+ * @param {{env?:NodeJS.ProcessEnv, stored?:()=>string|null, inCatalog?:(id:string)=>boolean}} [deps]
+ * @returns {{model:string, source:'explicit'|'env'|'settings'|'run'|'builtin', stale:string|null}}
+ */
+export function resolveTitleModel(opts = {}, { env = process.env, stored = storedTitleModel, inCatalog = catalogHasModel } = {}) {
+  const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : '');
+  const explicit = str(opts.model);
+  if (explicit) return { model: explicit, source: 'explicit', stale: null };
+  const fromEnv = str(env.WORCA_TITLE_MODEL);
+  if (fromEnv) return { model: fromEnv, source: 'env', stale: null };
+  let stale = null;
+  const configured = str(stored());
+  if (configured) {
+    if (inCatalog(configured)) return { model: configured, source: 'settings', stale: null };
+    stale = configured;
+  }
+  const runModel = str(opts.runModel);
+  if (runModel) return { model: runModel, source: 'run', stale };
+  return { model: DEFAULT_TITLE_MODEL, source: 'builtin', stale };
+}
+
+/**
+ * What the Settings card shows: the stored id, whether the environment
+ * overrides it, and a stale stored id that no longer resolves. `model` is
+ * null when titles follow the run's model (the default).
+ * @returns {{model:string|null, source:'env'|'settings'|'run', stale:string|null}}
+ */
+export function describeTitleModel(deps) {
+  const r = resolveTitleModel({}, deps);
+  if (r.source === 'env' || r.source === 'settings') return { model: r.model, source: r.source, stale: null };
+  return { model: null, source: 'run', stale: r.stale };
+}
+
 const SYSTEM = [
   'You write a SHORT, human-readable title for a software task.',
   'Rules: 3–8 words, Title Case-ish, no trailing period, no quotes, no markdown,',
@@ -60,24 +110,34 @@ export function isRefusalTitle(t) {
  * failure/abort/empty input so the caller keeps the provisional title.
  * `permissionMode` (default 'acceptEdits') exists for Ask Worca: its title call
  * passes 'dontAsk' so the mock dispatcher can never reach a file-writing role.
+ * `runModel` is the model of the run/chat asking (resolveTitleModel step 4).
+ * `onError` fires ONCE when the call yields no usable title for any reason but
+ * an abort (a spawn failure, a refusal, an empty reply) — the caller logs it on
+ * its own channel; the return value stays '' so every existing caller is unchanged.
  * @param {string} prompt
- * @param {{cwd:string, signal?:AbortSignal, model?:string, bin?:string, mock?:boolean, envScrub?:boolean, envAllowlist?:string[], tools?:string[], strictMcpConfig?:boolean, settingSources?:string[], disableSlashCommands?:boolean, mcpConfigPath?:string, permissionMode?:string}} opts
+ * @param {{cwd:string, signal?:AbortSignal, model?:string, runModel?:string, onError?:(info:{model:string, error:Error})=>void, bin?:string, mock?:boolean, envScrub?:boolean, envAllowlist?:string[], tools?:string[], strictMcpConfig?:boolean, settingSources?:string[], disableSlashCommands?:boolean, mcpConfigPath?:string, permissionMode?:string}} opts
  * @returns {Promise<string>}
  */
 export async function generateTitle(prompt, opts = {}) {
   const text = String(prompt || '').trim();
   if (!text) return '';
+  const { model, stale } = resolveTitleModel(opts);
+  if (stale) console.warn(`[worca] titleModel ${JSON.stringify(stale)} is no longer in the catalog — titles use ${model}`);
+  const report = (error) => {
+    if (typeof opts.onError !== 'function') return;
+    try { opts.onError({ model, error }); } catch { /* a logging sink must never fail the caller */ }
+  };
   try {
     const { text: out } = await runClaude({
       cwd: opts.cwd || process.cwd(),
       systemPrompt: SYSTEM,
       prompt: `Write the title for this task:\n\n${text.slice(0, 4000)}`,
-      model: opts.model || DEFAULT_TITLE_MODEL,
+      model,
       // Aux calls keep their model choice but still route through the catalog's
       // env (design §4.8) — a global entry matching this id carries its routing
       // env everywhere the id is used.
-      modelEnv: resolveModelEnv(opts.model || DEFAULT_TITLE_MODEL),
-      effort: 'low',
+      modelEnv: resolveModelEnv(model),
+      effort: AUX_EFFORT,
       permissionMode: opts.permissionMode || 'acceptEdits',
       allowedTools: [],            // empty → no --allowedTools flag → claude defaults; pure text gen
       signal: opts.signal,
@@ -103,9 +163,12 @@ export async function generateTitle(prompt, opts = {}) {
       onEvent: () => {},
     });
     const title = sanitizeTitle(out);
-    return isRefusalTitle(title) ? '' : title;
+    if (!title) { report(new Error('the model returned an empty reply')); return ''; }
+    if (isRefusalTitle(title)) { report(new Error(`the model did not write a title: ${title.slice(0, 120)}`)); return ''; }
+    return title;
   } catch (err) {
     if (err && err.name === 'AbortError') return ''; // run was stopped — caller keeps provisional
+    report(err instanceof Error ? err : new Error(String(err)));
     return '';
   }
 }

package/src/core/ui-instance.mjs

@@ -20,6 +20,7 @@
 // when the token is unavailable (file missing, or a server too old to have one).
 
 import fs from 'node:fs';
+import http from 'node:http';
 import fsp from 'node:fs/promises';
 import process from 'node:process';
 import { join } from 'node:path';
@@ -106,7 +107,7 @@ function dialHost(host) {
   return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
 }
 
-/** Every error code nested in a fetch failure (Node wraps them in `cause`, sometimes an AggregateError). */
+/** Every error code nested in a request failure (Node wraps them in `cause`, sometimes an AggregateError). */
 function errorCodes(err) {
   const out = new Set();
   const walk = (e, depth) => {
@@ -119,12 +120,38 @@ function errorCodes(err) {
   return out;
 }
 
+/**
+ * One-shot HTTP call on a throwaway connection. NOT fetch(): the lifecycle verbs
+ * call process.exit() right after a probe, and undici's pooled keep-alive socket is
+ * still closing at that moment — on Windows libuv asserts on it
+ * (`!(handle->flags & UV_HANDLE_CLOSING)`, src/win/async.c) and the CLI dies with
+ * 0xC0000409 instead of its exit code, after printing the right message. A bare
+ * `agent: false` + `Connection: close` request leaves nothing behind to tear down.
+ * Rejects with the socket error (its `code` intact, e.g. ECONNREFUSED) or the
+ * signal's AbortError.
+ */
+function request(url, { method = 'GET', headers = {}, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(url, { method, agent: false, signal, headers: { ...headers, connection: 'close' } }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('error', reject);
+      res.on('end', () => resolve({
+        status: res.statusCode, ok: res.statusCode >= 200 && res.statusCode < 300,
+        text: Buffer.concat(chunks).toString('utf8'),
+      }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
 /** GET a JSON object from the UI, or null (non-2xx, non-JSON, non-object). Network errors propagate. */
 async function getJson(url, signal) {
-  const res = await fetch(url, { signal, headers: { accept: 'application/json' } });
+  const res = await request(url, { signal, headers: { accept: 'application/json' } });
   if (!res.ok) return null;
   try {
-    const data = await res.json();
+    const data = JSON.parse(res.text);
     return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
   } catch {
     return null;
@@ -212,7 +239,7 @@ export async function stopUi({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT, t
 
   if (bearer) {
     try {
-      const res = await fetch(`http://${dialHost(host)}:${port}/api/shutdown`, {
+      const res = await request(`http://${dialHost(host)}:${port}/api/shutdown`, {
         method: 'POST',
         headers: { authorization: `Bearer ${bearer}`, accept: 'application/json' },
         signal: AbortSignal.timeout(3000),