@aiwuk/team 0.0.0-stage → 5.0.3

package/search-engines.js

@@ -0,0 +1,119 @@
+// Direct search/fetch engine drivers (Tavily, Brave, SearXNG, Jina) plus the HTTP plumbing they share with the
+// custom gateway driver in search.js. Every driver returns normalized data:
+//   search -> [{ title, url, snippet, published? }]     fetch -> { url, title?, content }
+// Errors carry `retryable`: availability failures (timeout, network, 401/403, 404, 429, 5xx, malformed 200)
+// let the dispatcher fall over to the next engine; invalid input (400, 413, 422) does not.
+// Upstream bodies are never echoed and a response that contains the key is blocked.
+/** What an upstream status means for the caller; error bodies are never echoed (they may carry secrets). */
+import { m } from './i18n.js';
+export const STATUS_HINT = Object.fromEntries([400, 401, 403, 404, 413, 422, 429, 502, 504].map((status, index) => [status, m(`search-engines.${373 + index}`)]));
+const NOT_RETRYABLE = new Set([400, 413, 422]);
+export const RESPONSE_CAP = 1024 * 1024;
+export function httpError(label, status) {
+  const error = new Error(`${label} HTTP ${status}${STATUS_HINT[status] ? ` (${STATUS_HINT[status]})` : ''}`);
+  error.status = status; error.retryable = !NOT_RETRYABLE.has(status) && (status >= 401);
+  return error;
+}
+/** An error from an engine; `retryable` decides whether the dispatcher tries the next engine. */
+export function engineError(message, retryable = true) { const error = new Error(message); error.retryable = retryable; return error; }
+/** Read a response body as text with the 1MB cap. */
+export async function readCapped(response, label) {
+  if (!response.body) throw engineError(m('search-engines.382', { 0: label }));
+  const reader = response.body.getReader(); const parts = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read(); if (done) break;
+      size += value.byteLength;
+      if (size > RESPONSE_CAP) { await reader.cancel(); throw engineError(m('search-engines.383', { 0: label })); }
+      parts.push(value);
+    }
+  } finally { reader.releaseLock(); }
+  return Buffer.concat(parts).toString('utf8');
+}
+/** Combine the caller's abort signal with a per-request timeout. */
+export const withTimeout = (signal, ms) => { const timeout = AbortSignal.timeout(ms); return signal ? AbortSignal.any([signal, timeout]) : timeout; };
+/**
+ * One JSON request: redirects are errors, the body is capped, a body echoing the key is blocked and an error
+ * body is never read. A network failure or timeout is retryable unless the caller itself aborted.
+ */
+export async function requestJson(label, url, init, { fetcher = fetch, key, timeoutMs, signal } = {}) {
+  let response;
+  try { response = await fetcher(url, { ...init, redirect: 'error', signal: withTimeout(signal, timeoutMs) }); }
+  catch (error) {
+    if (signal?.aborted) throw error;
+    throw engineError(`${label}: ${m(error?.name === 'TimeoutError' ? 'search-engines.384' : 'search-engines.385')}`);
+  }
+  if (!response.ok) throw httpError(label, response.status);
+  const text = await readCapped(response, label);
+  if (key && text.includes(key)) throw engineError(m('search-engines.386'), false);
+  try { return JSON.parse(text); } catch { throw engineError(m('search-engines.387', { 0: label })); }
+}
+const clean = value => (typeof value === 'string' ? value.replace(/<[^>]{0,200}>/g, '').replace(/\s+/g, ' ').trim() : '');
+/** Normalize one result row; rows without a URL are dropped. */
+export function resultRow(row, { title = 'title', url = 'url', snippet = ['snippet', 'content', 'description'], published = [] } = {}) {
+  if (!row || typeof row !== 'object' || typeof row[url] !== 'string' || !row[url]) return undefined;
+  const out = { title: clean(row[title]) || row[url], url: row[url], snippet: clean(snippet.map(k => row[k]).find(v => typeof v === 'string' && v)) };
+  const date = published.map(k => row[k]).find(v => typeof v === 'string' && v);
+  if (date) out.published = date;
+  return out;
+}
+const rows = (list, limit, shape) => {
+  if (!Array.isArray(list)) return undefined;
+  return list.map(row => resultRow(row, shape)).filter(Boolean).slice(0, limit);
+};
+const noResults = label => engineError(m('search-engines.388', { 0: label }));
+const json = { 'Content-Type': 'application/json', Accept: 'application/json' };
+export const TAVILY_ORIGIN = 'https://api.tavily.com';
+export const BRAVE_ORIGIN = 'https://api.search.brave.com';
+export const JINA_READER = 'https://r.jina.ai/';
+
+/** Tavily search: POST /search with a Bearer key; news maps to topic "news". */
+export async function tavilySearch(body, { key, config, fetcher, signal }) {
+  if (!key) throw engineError(m('search-engines.389', { 0: config.tavilyKeyEnv }));
+  const payload = { query: body.query, max_results: body.max_results, topic: body.search_type === 'news' ? 'news' : 'general', search_depth: 'basic' };
+  const data = await requestJson('Tavily', `${TAVILY_ORIGIN}/search`, { method: 'POST', headers: { ...json, Authorization: `Bearer ${key}` }, body: JSON.stringify(payload) }, { fetcher, key, timeoutMs: config.engineTimeoutMs, signal });
+  return rows(data?.results, body.max_results, { snippet: ['content'], published: ['published_date'] }) ?? Promise.reject(noResults('Tavily'));
+}
+/** Brave Search API: GET web search (news uses the news endpoint) with X-Subscription-Token. */
+export async function braveSearch(body, { key, config, fetcher, signal }) {
+  if (!key) throw engineError(m('search-engines.390', { 0: config.braveKeyEnv }));
+  const news = body.search_type === 'news';
+  const url = new URL(`${BRAVE_ORIGIN}/res/v1/${news ? 'news' : 'web'}/search`);
+  url.searchParams.set('q', body.query); url.searchParams.set('count', String(Math.min(body.max_results, 20)));
+  const data = await requestJson('Brave', url.href, { method: 'GET', headers: { Accept: 'application/json', 'X-Subscription-Token': key } }, { fetcher, key, timeoutMs: config.engineTimeoutMs, signal });
+  // Brave omits the `web` block when a query has no hits; a reply of type "search" is still a valid answer.
+  const list = news ? data?.results : data?.web?.results ?? (data?.type === 'search' ? [] : undefined);
+  return rows(list, body.max_results, { snippet: ['description'], published: ['page_age', 'age'] }) ?? Promise.reject(noResults('Brave'));
+}
+/** SearXNG instance: GET {searxngUrl}/search?format=json; news and code map to the news / it categories. */
+export async function searxngSearch(body, { key, config, fetcher, signal }) {
+  if (!config.searxngUrl) throw engineError(m('search-engines.391'));
+  const url = new URL(`${config.searxngUrl}/search`);
+  url.searchParams.set('q', body.query); url.searchParams.set('format', 'json');
+  const category = { news: 'news', code: 'it' }[body.search_type];
+  if (category) url.searchParams.set('categories', category);
+  const headers = { Accept: 'application/json', ...(key ? { Authorization: `Bearer ${key}` } : {}) };
+  const data = await requestJson('SearXNG', url.href, { method: 'GET', headers }, { fetcher, key, timeoutMs: config.engineTimeoutMs, signal });
+  return rows(data?.results, body.max_results, { snippet: ['content'], published: ['publishedDate'] }) ?? Promise.reject(noResults('SearXNG'));
+}
+const pageContent = (label, url, title, content) => {
+  if (typeof content !== 'string' || !content.trim()) throw engineError(m('search-engines.392', { 0: label }));
+  return { url, ...(typeof title === 'string' && title.trim() ? { title: title.trim() } : {}), content };
+};
+/** Jina Reader: GET r.jina.ai/{url}; works without a key, an optional key raises the rate limit. */
+export async function jinaFetch(body, { key, config, fetcher, signal }) {
+  const headers = { Accept: 'application/json', 'X-Return-Format': body.format === 'html' ? 'html' : 'markdown', ...(key ? { Authorization: `Bearer ${key}` } : {}) };
+  const data = await requestJson('Jina', `${JINA_READER}${body.url}`, { method: 'GET', headers }, { fetcher, key, timeoutMs: config.engineTimeoutMs, signal });
+  const page = data?.data ?? data;
+  return pageContent('Jina', page?.url || body.url, page?.title, page?.content ?? page?.html);
+}
+/** Tavily Extract: POST /extract for one URL. */
+export async function tavilyFetch(body, { key, config, fetcher, signal }) {
+  if (!key) throw engineError(m('search-engines.389', { 0: config.tavilyKeyEnv }));
+  const payload = { urls: [body.url], format: body.format === 'html' ? 'text' : 'markdown' };
+  const data = await requestJson('Tavily', `${TAVILY_ORIGIN}/extract`, { method: 'POST', headers: { ...json, Authorization: `Bearer ${key}` }, body: JSON.stringify(payload) }, { fetcher, key, timeoutMs: config.engineTimeoutMs, signal });
+  const page = Array.isArray(data?.results) ? data.results[0] : undefined;
+  return pageContent('Tavily', page?.url || body.url, page?.title, page?.raw_content);
+}
+export const SEARCH_DRIVERS = Object.freeze({ tavily: tavilySearch, brave: braveSearch, searxng: searxngSearch });
+export const FETCH_DRIVERS = Object.freeze({ jina: jinaFetch, tavily: tavilyFetch });

package/search.js

@@ -0,0 +1,164 @@
+import { m as modelText } from './i18n.js';
+// Search/fetch dispatcher: picks engines from integrations.search, falls over on availability failures and
+// returns normalized results. Direct engine drivers live in search-engines.js; the `custom` engine is any
+// gateway speaking the generic search/fetch/providers protocol, implemented here by `gateway`.
+import { params } from './tool-schema.js';
+import { INTEGRATION_DEFAULTS, SEARCH_ENGINES, SEARCH_KEY_FIELDS, engineKeyOf, keyOf, refreshCredentials, resolveIntegrations } from './integrations-config.js';
+import { FETCH_DRIVERS, SEARCH_DRIVERS, engineError, httpError, readCapped, resultRow, withTimeout } from './search-engines.js';
+export { STATUS_HINT, httpError } from './search-engines.js';
+// Engine order, paths, headers and the provider lists are configuration (integrations.search), never code.
+export function requestBody(kind, args, config = INTEGRATION_DEFAULTS.search) {
+  const allowed = kind === 'search' ? ['query','max_results','search_type','provider'] : ['url','format','provider'];
+  if (!args || Object.keys(args).some(key => !allowed.includes(key))) throw new Error(modelText('search.394'));
+  const body = {};
+  if (kind === 'search') {
+    if (typeof args.query !== 'string' || !args.query.trim() || args.query.length > 4000) throw new Error(modelText('search.395'));
+    body.query = args.query; body.max_results = args.max_results ?? 5; body.search_type = args.search_type ?? 'web';
+    if (!Number.isInteger(body.max_results) || body.max_results < 1 || body.max_results > 20) throw new Error(modelText('search.396'));
+    if (!['web','news','code'].includes(body.search_type)) throw new Error(modelText('search.397'));
+  } else {
+    const url = new URL(args.url);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || /^(localhost|127\.|0\.|10\.|192\.168\.|169\.254\.|\[|.*\.local$)/i.test(url.hostname) || /^172\.(1[6-9]|2\d|3[01])\./.test(url.hostname)) throw new Error(modelText('search.398'));
+    body.url = url.href; body.format = args.format ?? 'markdown';
+    if (!['markdown','html'].includes(body.format)) throw new Error(modelText('search.399'));
+  }
+  if (args.provider !== undefined) {
+    const allowed = kind === 'search' ? config.providers : config.fetchProviders;
+    // With a configured list only those providers pass; without one, any provider token goes to the gateway.
+    if (typeof args.provider !== 'string' || !/^[\w.:-]{1,64}$/.test(args.provider) || (allowed.length && !allowed.includes(args.provider))) throw new Error(modelText('search.400'));
+    body.provider = args.provider;
+  }
+  return body;
+}
+/**
+ * Gateway base from configuration; only a credential-free https origin (optional path prefix) is accepted.
+ * `field`/`envName` name where the address comes from, for the error message.
+ */
+export function gatewayBase(raw, { what = modelText('search.401'), field = 'search.baseUrl', envName = 'OMNI_SEARCH_BASE_URL' } = {}) {
+  if (!raw) throw new Error(modelText('search.402', { 0: what, 1: field, 2: envName }));
+  let url;
+  try { url = new URL(raw); } catch { throw new Error(modelText('search.403', { 0: envName })); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error(modelText('search.404', { 0: envName }));
+  return url.href.replace(/\/+$/, '');
+}
+/** Search/fetch config and every engine key as resolved now; tests and callers may pass them explicitly. */
+export function searchSettings(resolved = resolveIntegrations()) {
+  const keys = Object.fromEntries(Object.keys(SEARCH_KEY_FIELDS).map(engine => [engine, engineKeyOf(engine, resolved)]));
+  return { config: resolved.effective.search, key: keyOf('search', resolved), keyEnv: resolved.keys.search.env, keys };
+}
+const engineKey = (settings, engine) => (engine === 'custom' ? settings.keys?.custom ?? settings.key : settings.keys?.[engine]);
+/** Whether an engine has what it needs to be tried in auto mode (a key, or a URL for SearXNG / custom). */
+export function engineConfigured(engine, settings) {
+  const { config } = settings;
+  if (engine === 'searxng') return !!config.searxngUrl;
+  if (engine === 'custom') return !!config.baseUrl;
+  return !!engineKey(settings, engine);
+}
+/** Ordered search engines: the configured list, or auto = every configured engine in default order. */
+export function activeEngines(settings) {
+  return settings.config.engines ?? SEARCH_ENGINES.filter(engine => engineConfigured(engine, settings));
+}
+/** Whether `custom` takes part in search (explicit list, or auto with a gateway address). */
+export const customActive = config => (config.engines ? config.engines.includes('custom') : !!config.baseUrl);
+const fetchEnginesOf = config => config.fetchEngines ?? INTEGRATION_DEFAULTS.search.fetchEngines;
+/** A 200 still has to carry a real result: search needs a results list, fetch needs page content. */
+export function checkResult(kind, data) {
+  if (kind === 'search' && !Array.isArray(data?.results)) throw engineError(modelText('search.405'));
+  if (kind === 'fetch' && !(typeof data?.content === 'string' && data.content.trim())) throw engineError(modelText('search.406'));
+  if (kind === 'providers' && !Array.isArray(data?.data)) throw engineError(modelText('search.407'));
+  return data;
+}
+/** The `custom` engine: one request to the configured gateway (search, fetch or providers), raw checked data. */
+export async function gateway(kind, args, { fetcher = fetch, settings, key, base, signal } = {}) {
+  if (!settings && key === undefined) await refreshCredentials();
+  const current = settings ?? searchSettings();
+  const config = { ...current.config, ...(base !== undefined ? { baseUrl: base } : {}) };
+  const secret = key !== undefined ? key : engineKey(current, 'custom');
+  const body = kind === 'providers' ? undefined : requestBody(kind, args, config);
+  if (!secret) throw engineError(modelText('search.408', { 0: current.keyEnv ?? config.apiKeyEnv }));
+  const origin = gatewayBase(config.baseUrl);
+  if (kind === 'providers' && !config.providersPath) throw new Error(modelText('search.409'));
+  const path = { search: config.searchPath, fetch: config.fetchPath, providers: config.providersPath }[kind];
+  let response;
+  try {
+    response = await fetcher(`${origin}${path}`, {
+      method: body ? 'POST' : 'GET', redirect: 'error', signal: withTimeout(signal, kind === 'fetch' ? config.fetchTimeoutMs : config.timeoutMs),
+      headers: { ...config.headers, Authorization: `Bearer ${secret}`, ...(body ? { 'Content-Type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (error) { if (signal?.aborted) throw error; throw engineError(modelText('search.410', { 0: error?.name === 'TimeoutError' ? modelText('search.411') : modelText('search.412') })); }
+  // Never echo error bodies: gateways may include secrets or upstream headers.
+  if (!response.ok) throw httpError(modelText('search.413'), response.status);
+  const text = await readCapped(response, modelText('search.414'));
+  if (text.includes(secret)) throw engineError(modelText('search.415'), false);
+  let data;
+  try { data = JSON.parse(text); } catch { throw engineError(modelText('search.416')); }
+  return checkResult(kind, data);
+}
+const RESULT_SHAPE = { snippet: ['snippet', 'content', 'description'], published: ['published', 'published_date', 'publishedDate'] };
+async function customSearch(body, { args, ...opts }) {
+  const data = await gateway('search', args, opts);
+  return data.results.map(row => resultRow(row, RESULT_SHAPE)).filter(Boolean).slice(0, body.max_results);
+}
+async function customFetch(body, { args, ...opts }) {
+  const data = await gateway('fetch', args, opts);
+  return { url: typeof data.url === 'string' && data.url ? data.url : body.url, ...(typeof data.title === 'string' && data.title.trim() ? { title: data.title.trim() } : {}), content: data.content };
+}
+// Run engines in order; only a retryable failure moves on. The final error lists each engine's (safe) reason.
+async function failover(label, engines, attempt) {
+  const reasons = [];
+  for (const engine of engines) {
+    try { return await attempt(engine); }
+    catch (error) {
+      if (error?.retryable !== true) throw error;
+      reasons.push(`${engine}: ${error.message}`);
+    }
+  }
+  throw new Error(modelText('search.417', { 0: label, 1: reasons.join('；') }));
+}
+const NO_ENGINE = modelText('search.418');
+/**
+ * Search, fetch or list custom providers. Search -> { engine, results }, fetch -> { engine, url, title?, content },
+ * providers -> the custom gateway's raw list.
+ */
+export async function omni(kind, args, { fetcher = fetch, settings, signal } = {}) {
+  if (!settings) await refreshCredentials();
+  const current = settings ?? searchSettings();
+  const { config } = current;
+  if (kind === 'providers') {
+    if (!customActive(config)) throw new Error(modelText('search.419'));
+    return gateway('providers', args, { fetcher, settings: current, signal });
+  }
+  const body = requestBody(kind, args, config);
+  const opts = key => ({ key, config, fetcher, signal, args, settings: current });
+  if (kind === 'search') {
+    const engines = activeEngines(current);
+    if (args.provider !== undefined && !engines.includes('custom')) throw new Error(modelText('search.420'));
+    if (!engines.length) throw new Error(NO_ENGINE);
+    return failover(modelText('search.421'), engines, async engine => {
+      const driver = engine === 'custom' ? customSearch : SEARCH_DRIVERS[engine];
+      return { engine, results: await driver(body, opts(engineKey(current, engine))) };
+    });
+  }
+  const engines = fetchEnginesOf(config);
+  if (args.provider !== undefined && !engines.includes('custom')) throw new Error(modelText('search.422'));
+  return failover(modelText('search.423'), engines, async engine => {
+    const driver = engine === 'custom' ? customFetch : FETCH_DRIVERS[engine];
+    return { engine, ...(await driver(body, opts(engineKey(current, engine)))) };
+  });
+}
+/**
+ * Tool schemas. `provider` exists only when the custom engine takes part; a configured provider list becomes
+ * its enum. The providers tool needs the custom engine and a providersPath.
+ */
+export function searchSchemas(config = INTEGRATION_DEFAULTS.search) {
+  const provider = list => (list.length ? { type: 'string', enum: list } : { type: 'string', description: modelText('search.424') });
+  const custom = customActive(config);
+  return {
+    omni_search: params({ query: { type: 'string', description: modelText('search.425') }, max_results: { type: 'integer', description: modelText('search.426') }, search_type: { type: 'string', enum: ['web','news','code'] },
+      ...(custom ? { provider: provider(config.providers) } : {}) }, ['query']),
+    omni_fetch: params({ url: { type: 'string', description: modelText('search.427') }, format: { type: 'string', enum: ['markdown','html'] },
+      ...(fetchEnginesOf(config).includes('custom') ? { provider: provider(config.fetchProviders) } : {}) }, ['url']),
+    ...(custom && config.providersPath ? { omni_search_providers: params({}, []) } : {}),
+  };
+}
+export const schemas = searchSchemas();

package/session-policy.js

@@ -0,0 +1,59 @@
+import { m as modelText } from './i18n.js';
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { defaultRoot, acquireLock } from './theme.js';
+import { validateDisabledRoutes } from './model-policy.js';
+const profileNamespace = () => process.env.DSH_PROFILE_DIR ?? process.env.DSH_PROFILE ?? 'default';
+export function sessionPolicyPath(sessionId, root = defaultRoot()) {
+  if (typeof sessionId !== 'string' || !sessionId) throw new Error(modelText('session-policy.428'));
+  return join(root, 'sessions', createHash('sha256').update(JSON.stringify([profileNamespace(), sessionId])).digest('hex') + '.json');
+}
+/** One model policy per DSH profile, shared by every capability-team session. */
+export function globalPolicyPath(root = defaultRoot()) {
+  return join(root, 'model-policy', createHash('sha256').update(JSON.stringify([profileNamespace(), 'global'])).digest('hex') + '.json');
+}
+function parsePolicy(raw) {
+  try {
+    const data = JSON.parse(raw);
+    if (!Number.isSafeInteger(data.revision) || data.revision < 1) throw new Error(modelText('session-policy.429'));
+    return { revision: data.revision, disabledRoutes: validateDisabledRoutes(data.disabledRoutes) };
+  } catch (error) { throw new Error(modelText('session-policy.430', { 0: error.message })); }
+}
+async function readPolicyAt(path) {
+  let raw;
+  try { raw = await readFile(path, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return { revision: 0, disabledRoutes: [] }; throw error; }
+  return parsePolicy(raw);
+}
+function readPolicyAtSync(path) {
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return { revision: 0, disabledRoutes: [] }; throw error; }
+  return parsePolicy(raw);
+}
+export const readSessionPolicy = (sessionId, root) => readPolicyAt(sessionPolicyPath(sessionId, root));
+export const readSessionPolicySync = (sessionId, root) => readPolicyAtSync(sessionPolicyPath(sessionId, root));
+export const saveSessionPolicy = (sessionId, disabledRoutes, expectedRevision, root) => savePolicyAt(sessionPolicyPath(sessionId, root), disabledRoutes, expectedRevision);
+export const readGlobalPolicy = root => readPolicyAt(globalPolicyPath(root));
+export const readGlobalPolicySync = root => readPolicyAtSync(globalPolicyPath(root));
+export const saveGlobalPolicy = (disabledRoutes, expectedRevision, root) => savePolicyAt(globalPolicyPath(root), disabledRoutes, expectedRevision);
+async function savePolicyAt(path, disabledRoutes, expectedRevision) {
+  const disabled = validateDisabledRoutes(disabledRoutes);
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) throw new Error(modelText('session-policy.431'));
+  await mkdir(join(path, '..'), { recursive: true });
+  const lock = await acquireLock(path + '.lock');
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    const current = await readPolicyAt(path);
+    if (current.revision !== expectedRevision) throw new Error(modelText('session-policy.432'));
+    const next = { revision: current.revision + 1, disabledRoutes: disabled };
+    await writeFile(temporary, JSON.stringify(next, null, 2) + '\n', { flag: 'wx' });
+    await rename(temporary, path);
+    return next;
+  } finally {
+    try { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+    finally { try { await lock.close(); } finally { await unlink(path + '.lock').catch(error => { if (error.code !== 'ENOENT') throw error; }); } }
+  }
+}

package/session-rotation.js

@@ -0,0 +1,206 @@
+import { m as modelText } from './i18n.js';
+// Session rotation: a teammate session that has been compacted several times, is close to its context window,
+// or keeps re-reading the same file is handed over to a fresh successor instead of piling up. The member
+// writes a structured handoff (capability_handoff); the plugin adds facts it collects itself (git diff stat,
+// owned board tasks, last test command). The Lead then calls capability_rotate_member, which names the
+// successor `<role>-r<N>` (team rosters never reuse a name) and returns the exact calls to make.
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { params } from './tool-schema.js';
+import { ownsCapabilityTeam } from './preset-guard.js';
+import { promptTokens } from './long-context.js';
+import { restrictiveToolName } from './tool-names.js';
+const TRACKED_TOOLS = new Set(['read', 'write', 'edit', 'str_replace_editor', 'apply_patch', 'bash', 'pwsh', 'send_message']);
+export const ROTATION = { softCompactions: 2, hardCompactions: 3, softRatio: 0.75, hardRatio: 0.9, softRepeatReads: 15, hardTurns: 8, maxMembers: 8 };
+const KEYS = Object.keys(ROTATION);
+const SUFFIX = /-r(\d+)$/;
+export const baseName = name => String(name ?? '').replace(SUFFIX, '');
+export const generation = name => Number(SUFFIX.exec(String(name ?? ''))?.[1] ?? 1);
+export const successorName = name => `${baseName(name)}-r${generation(name) + 1}`;
+const output = { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] };
+export function validateRotation(value) {
+  if (value === undefined || value === null) return { ...ROTATION };
+  if (value === false) return false;
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(modelText('session-rotation.433'));
+  const extra = Object.keys(value).filter(k => !KEYS.includes(k));
+  if (extra.length) throw new Error(modelText('session-rotation.434', { 0: extra.join(', ') }));
+  const out = { ...ROTATION, ...value };
+  for (const k of ['softRatio', 'hardRatio']) if (typeof out[k] !== 'number' || out[k] <= 0 || out[k] > 1) throw new Error(modelText('session-rotation.435', { 0: k }));
+  for (const k of KEYS.filter(k => !k.endsWith('Ratio'))) if (!Number.isSafeInteger(out[k]) || out[k] < 1 || out[k] > 1000) throw new Error(modelText('session-rotation.436', { 0: k }));
+  if (out.softCompactions > out.hardCompactions || out.softRatio > out.hardRatio) throw new Error(modelText('session-rotation.437'));
+  return out;
+}
+/** 'ok' | 'soft' | 'hard' with the reasons, from one session's counters and its context ratio. */
+export function rotationLevel(m, ratio, limits) {
+  if (!limits || !m) return { level: 'ok', reasons: [] };
+  const hard = [], soft = [];
+  if (m.compactions >= limits.hardCompactions) hard.push(modelText('session-rotation.438', { 0: m.compactions }));
+  else if (m.compactions >= limits.softCompactions) soft.push(modelText('session-rotation.439', { 0: m.compactions }));
+  if (ratio !== undefined && ratio >= limits.hardRatio) hard.push(modelText('session-rotation.440', { 0: Math.round(ratio * 100) }));
+  else if (ratio !== undefined && ratio >= limits.softRatio) soft.push(modelText('session-rotation.441', { 0: Math.round(ratio * 100) }));
+  if (m.turns >= limits.hardTurns) hard.push(modelText('session-rotation.442', { 0: m.turns }));
+  if (m.maxRepeat >= limits.softRepeatReads) soft.push(modelText('session-rotation.443', { 0: m.maxRepeat }));
+  // Rotating a session that has produced nothing only makes the successor read everything again, so a
+  // stalled session stays at the reminder level until it edits a file or the host compacts it.
+  const progressed = (m.edits ?? 0) > 0 || m.compactions > 0;
+  if (hard.length && !progressed) return { level: 'soft', reasons: [...hard, ...soft], stalled: true };
+  return hard.length ? { level: 'hard', reasons: [...hard, ...soft] } : soft.length ? { level: 'soft', reasons: soft } : { level: 'ok', reasons: [] };
+}
+const TEST_CMD = /\b(npm (run )?test|node --test|pnpm test|yarn test|pytest|go test|cargo test|vitest|jest)\b/;
+/** Fold one session event into the counters. Pure, so tests can replay a log. */
+export function foldEvent(m, event) {
+  const data = event?.data ?? {};
+  const d = { ...data, name: restrictiveToolName(data.name, TRACKED_TOOLS) };
+  if (event?.type === 'compaction/end') m.compactions++;
+  else if (event?.type === 'turn/start') m.turns++;
+  else if (event?.type === 'tool/call') {
+    let args = {}; try { args = typeof d.arguments === 'string' ? JSON.parse(d.arguments) : d.arguments ?? {}; } catch { /* partial */ }
+    if (d.name === 'read' && typeof args.file_path === 'string') {
+      const n = (m.reads.get(args.file_path) ?? 0) + 1; m.reads.set(args.file_path, n); m.maxRepeat = Math.max(m.maxRepeat, n);
+    }
+    if (['write', 'edit', 'str_replace_editor', 'apply_patch'].includes(d.name) && !(d.name === 'str_replace_editor' && args.command === 'view')) m.edits++;
+    if (['bash', 'pwsh'].includes(d.name) && TEST_CMD.test(String(args.command ?? ''))) m.pendingTest = { callId: d.callId, command: String(args.command).slice(0, 300) };
+  } else if (event?.type === 'tool/result' && m.pendingTest && d.message?.toolCallId === m.pendingTest.callId) {
+    const text = (d.message.content ?? []).map(c => c.text ?? '').join('\n');
+    const summary = text.split('\n').filter(l => /\b(pass|fail|tests?|ok|error)\b/i.test(l)).slice(-6).join('\n');
+    m.lastTest = { command: m.pendingTest.command, isError: !!d.message.isError, summary: summary.slice(0, 600), at: event.time ?? null };
+    m.pendingTest = null;
+  }
+  return m;
+}
+export const emptyMetrics = () => ({ compactions: 0, turns: 0, edits: 0, reads: new Map(), maxRepeat: 0, lastTest: null, pendingTest: null });
+const gitStat = cwd => new Promise(resolve => execFile('git', ['diff', '--stat'], { cwd, timeout: 5000, maxBuffer: 1 << 20 }, (error, stdout) =>
+  resolve(error ? null : stdout.trim().split('\n').slice(-40).join('\n'))));
+export function createRotation(ctx, team, { root = team.root, diffStat = gitStat, now = Date.now, onHandoff } = {}) {
+  const metrics = new Map(); // session id → counters
+  const handoffs = new Map(); // `${leadId}:${memberName}` → latest handoff
+  const retired = new Map(); // `${leadId}:${memberName}` → successor name
+  const planned = new Map(); // `${leadId}:${successor}` → { from, prompt }
+  const counters = id => { if (!metrics.has(id)) metrics.set(id, emptyMetrics()); return metrics.get(id); };
+  const limitsOf = agent => { try { const project = team.pinned(agent); return project ? team.loadSync(project, agent).effective.workflow.rotation : false; } catch { return false; } };
+  const ratioOf = agent => {
+    try {
+      const projections = ctx.get?.('sessionProjections');
+      const tokens = promptTokens(projections, agent.session);
+      const window = projections?.stateOf(agent.session, 'contextPressure')?.contextWindow;
+      return tokens !== undefined && window ? tokens / window : undefined;
+    } catch { return undefined; }
+  };
+  const dir = leadId => join(root, 'handoffs', createHash('sha256').update(leadId).digest('hex').slice(0, 32));
+  const api = {
+    metrics: id => metrics.get(id),
+    status(agent) { return rotationLevel(metrics.get(agent.id), ratioOf(agent), limitsOf(agent)); },
+    retiredTo: (leadId, name) => retired.get(`${leadId}:${name}`),
+    /** Lead guard: no new work for a retired member or one past the hard line; successors may be spawned. */
+    guard(exec) {
+      const membership = ctx.agentTeams.tryMembership(exec.agent);
+      if (!ownsCapabilityTeam(ctx, exec.agent) || membership?.role !== 'lead') return undefined;
+      const lead = exec.agent;
+      if (restrictiveToolName(exec.name, TRACKED_TOOLS) === 'send_message') {
+        const target = exec.arguments?.target;
+        const next = retired.get(`${lead.id}:${target}`);
+        if (next) return modelText('session-rotation.444', { 0: target, 1: next, 2: next });
+        const member = ctx.agentTeams.listMembers(lead).find(m => m.name === target && m.role !== 'lead');
+        const agent = member && ctx.agents.get(member.id);
+        const status = agent && api.status(agent);
+        if (status?.level === 'hard') return modelText('session-rotation.445', { 0: target, 1: status.reasons.join('、') });
+      }
+      return undefined;
+    },
+    /** Whether `name` is a successor this Lead asked for via capability_rotate_member. */
+    plannedSuccessor: (leadId, name) => planned.has(`${leadId}:${name}`),
+    /** The member a planned successor replaces, if any. */
+    predecessorOf: (leadId, name) => planned.get(`${leadId}:${name}`)?.from,
+    async writeHandoff(agent, args) {
+      const membership = ctx.agentTeams.tryMembership(agent);
+      if (membership?.role !== 'teammate') throw new Error(modelText('session-rotation.446'));
+      const lead = membership.root;
+      const project = team.pinned(agent) ?? ctx.workingDirectory?.get?.(agent.session);
+      const m = metrics.get(agent.id) ?? emptyMetrics();
+      let tasks = [];
+      try { tasks = (ctx.agentTeams.listTasks?.(lead) ?? []).filter(t => t.status !== 'deleted' && t.status !== 'completed' && (t.ownerId === agent.id || t.ownerName === membership.name)).map(t => ({ id: t.id, subject: t.subject, status: t.status })); } catch { /* optional */ }
+      const text = (v, max = 4000) => (typeof v === 'string' ? v.trim().slice(0, max) : '');
+      const handoff = { schemaVersion: 1, at: now(), lead: lead.id, member: membership.name, role: baseName(membership.name), session: agent.id,
+        written: { goal: text(args.goal), done: text(args.done), remaining: text(args.remaining), pitfalls: text(args.pitfalls), open: text(args.open), verify: text(args.verify) },
+        facts: { diffStat: project ? await diffStat(project) : null, openTasks: tasks, lastTest: m.lastTest, compactions: m.compactions, turns: m.turns } };
+      if (!handoff.written.remaining && !handoff.written.done) throw new Error(modelText('session-rotation.447'));
+      handoffs.set(`${lead.id}:${membership.name}`, handoff);
+      await mkdir(dir(lead.id), { recursive: true });
+      await writeFile(join(dir(lead.id), `${membership.name}.json`), JSON.stringify(handoff, null, 2) + '\n');
+      try { await onHandoff?.(handoff); } catch { /* the handoff is saved even if the memory hub is unavailable */ }
+      return handoff;
+    },
+    async readHandoff(leadId, name) {
+      const key = `${leadId}:${name}`;
+      if (handoffs.has(key)) return handoffs.get(key);
+      try { const h = JSON.parse(await readFile(join(dir(leadId), `${name}.json`), 'utf8')); handoffs.set(key, h); return h; } catch { return undefined; }
+    },
+    /** Plan the successor for a member: name, fresh-context prompt, and the calls the Lead makes. */
+    async rotate(lead, args) {
+      const name = String(args.role ?? '');
+      const members = ctx.agentTeams.listMembers(lead).filter(m => m.role !== 'lead');
+      const current = members.find(m => m.name === name) ?? members.filter(m => baseName(m.name) === baseName(name)).sort((a, b) => generation(b.name) - generation(a.name))[0];
+      if (!current) throw new Error(modelText('session-rotation.448', { 0: name }));
+      const limits = limitsOf(lead) || ROTATION;
+      const used = ctx.agentTeams.listMembers(lead).length;
+      if (used >= limits.maxMembers) {
+        return { rotated: false, reason: modelText('session-rotation.449', { 0: used, 1: limits.maxMembers }),
+          next: modelText('session-rotation.450', { 0: current.name }) };
+      }
+      const handoff = await api.readHandoff(lead.id, current.name);
+      if (!handoff && !args.without_handoff) {
+        return { rotated: false, reason: modelText('session-rotation.451', { 0: current.name }),
+          next: modelText('session-rotation.452', { 0: current.name }) };
+      }
+      const successor = successorName(current.name);
+      const facts = handoff?.facts ?? { diffStat: await diffStat(team.pinned(lead) ?? '.'), openTasks: [], lastTest: metrics.get(current.id)?.lastTest ?? null };
+      const w = handoff?.written ?? {};
+      const prompt = [modelText('session-rotation.453', { 0: current.name, 1: baseName(current.name) }),
+        args.task ? modelText('session-rotation.454', { 0: String(args.task).slice(0, 4000) }) : null,
+        w.goal ? modelText('session-rotation.455', { 0: w.goal }) : null, w.done ? modelText('session-rotation.456', { 0: w.done }) : null, w.remaining ? modelText('session-rotation.457', { 0: w.remaining }) : null,
+        w.pitfalls ? modelText('session-rotation.458', { 0: w.pitfalls }) : null, w.open ? modelText('session-rotation.459', { 0: w.open }) : null, w.verify ? modelText('session-rotation.460', { 0: w.verify }) : null,
+        facts.diffStat ? modelText('session-rotation.461', { 0: facts.diffStat }) : null,
+        facts.openTasks?.length ? modelText('session-rotation.462', { 0: facts.openTasks.map(t => `${t.id} ${t.subject}`).join('；') }) : null,
+        facts.lastTest ? modelText('session-rotation.463', { 0: facts.lastTest.command, 1: facts.lastTest.isError ? modelText('session-rotation.464') : modelText('session-rotation.465'), 2: facts.lastTest.summary }) : null,
+        modelText('session-rotation.466')].filter(Boolean).join('\n\n');
+      planned.set(`${lead.id}:${successor}`, { from: current.name, prompt });
+      retired.set(`${lead.id}:${current.name}`, successor);
+      return { rotated: true, from: current.name, to: successor, handoff: handoff ? 'member' : 'facts-only',
+        next: [`1. interrupt_agent target=${current.name}`, modelText('session-rotation.467', { 0: successor }),
+          facts.openTasks?.length ? modelText('session-rotation.468', { 0: facts.openTasks.map(t => t.id).join('、'), 1: successor }) : null].filter(Boolean).join('\n'), prompt };
+    },
+    register() {
+      try { ctx.on('session/event', (session, event) => { if (session?.id && ownsCapabilityTeam(ctx, ctx.agents.get(session.id)) && ctx.agentTeams.tryMembership?.(ctx.agents.get(session.id))?.role === 'teammate') foldEvent(counters(session.id), event); }); } catch { /* host without session observers */ }
+      ctx.on('agent/created', ({ agent }) => {
+        const identity = ctx.agentTeams.tryMembership(agent);
+        if (!ownsCapabilityTeam(ctx, agent) || identity?.role !== 'teammate') return;
+        counters(agent.id);
+        // Runtime context only says something once a threshold is crossed, so it does not churn the cache.
+        agent.ctx.systemPrompt.context({ name: 'capability-team:rotation', order: 98, text: () => {
+          const s = api.status(agent);
+          if (s.level === 'ok') return '';
+          return s.level === 'hard'
+            ? modelText('session-rotation.469', { 0: s.reasons.join('、') })
+            : modelText('session-rotation.470', { 0: s.reasons.join('、'), 1: s.stalled ? modelText('session-rotation.471') : '' });
+        } });
+      });
+      ctx.effect(() => ctx.tools.guard(exec => api.guard(exec)));
+      ctx.effect(() => ctx.tools.register({ name: 'capability_handoff', output,
+        description: modelText('session-rotation.472'),
+        parameters: params({ goal: { type: 'string' }, done: { type: 'string' }, remaining: { type: 'string' }, pitfalls: { type: 'string' }, open: { type: 'string' }, verify: { type: 'string' } }, ['done', 'remaining']),
+        async execute(args, exec) { const h = await api.writeHandoff(exec.agent, args); return JSON.stringify({ saved: true, member: h.member, facts: { diffStat: !!h.facts.diffStat, openTasks: h.facts.openTasks.length, lastTest: h.facts.lastTest?.command ?? null } }); },
+      }));
+      ctx.effect(() => ctx.tools.register({ name: 'capability_rotate_member', output,
+        description: modelText('session-rotation.473'),
+        parameters: params({ role: { type: 'string', description: modelText('session-rotation.474') }, task: { type: 'string', description: modelText('session-rotation.475') }, without_handoff: { type: 'boolean', description: modelText('session-rotation.476') } }, ['role']),
+        async execute(args, exec) {
+          if (ctx.agentTeams.tryMembership(exec.agent)?.role !== 'lead') throw new Error(modelText('session-rotation.477'));
+          return JSON.stringify(await api.rotate(exec.agent, args));
+        },
+      }));
+    },
+  };
+  return api;
+}

package/settings-schema.js

@@ -0,0 +1,40 @@
+// Settings-form support for the standalone omni-search and memory bundles (copied into packages/*/shared/).
+// cordis validates an exported `Config` through Standard Schema (`Config['~standard'].validate`) and DSH's settings
+// page projects only `.volatile()` fields, which need @deepseek-ai/schemastery >= 3.18.4 (resolved from the DSH
+// installation through the optional peer dependency). Outside DSH (plain `node --test`, no node_modules) the
+// library is absent: the bundles then export no Config and keep validating their own plain options.
+let lib = null;
+try { lib = (await import('@deepseek-ai/schemastery')).default; }
+catch (error) { if (error?.code !== 'ERR_MODULE_NOT_FOUND' && error?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw error; }
+/** Refuse a stale copy without `.volatile()` (an old nested node_modules shadowing DSH's) with an actionable error. */
+export function assertVolatile(z, owner) {
+  let ok = false;
+  try { ok = typeof z.string().default('x').volatile === 'function'; } catch { ok = false; }
+  if (!ok) throw new Error(`[${owner}] the resolved @deepseek-ai/schemastery has no .volatile() (needs >= 3.18.4). A stale nested copy (node_modules/${owner}/node_modules/@deepseek-ai/schemastery) probably shadows the one DSH ships; delete it or reinstall the plugin, then restart DSH.`);
+  return z;
+}
+/** The schemastery default export, or null when unavailable. `owner` names the bundle in the load error. */
+export const schemastery = owner => (lib ? assertVolatile(lib, owner) : null);
+/** Current value of a volatile reference or plain value; empty strings and empty lists count as unset. */
+export function liveValue(ref) {
+  const value = typeof ref?.get === 'function' ? ref.get() : ref;
+  if (value === undefined || value === null || (typeof value === 'string' && !value.trim()) || (Array.isArray(value) && !value.length)) return undefined;
+  return Array.isArray(value) ? [...value] : typeof value === 'string' ? value.trim() : value;
+}
+/**
+ * Split a bundle config into its plain options and a settings layer reader.
+ * `fields` maps each settings key to its integrations target `[section, key]`; the reader returns only set values.
+ */
+export function splitSettings(input, fields) {
+  const plain = {}; const refs = {};
+  for (const [key, value] of Object.entries(input ?? {})) (Object.hasOwn(fields, key) ? refs : plain)[key] = value;
+  const read = () => {
+    const layer = {};
+    for (const [key, [section, target]] of Object.entries(fields)) {
+      const value = liveValue(refs[key]);
+      if (value !== undefined) (layer[section] ??= {})[target] = value;
+    }
+    return layer;
+  };
+  return { plain, read };
+}