@aiwuk/team 0.0.0-stage → 5.0.3

package/theme-plugin.js

@@ -0,0 +1,172 @@
+import { m as modelText, t } from './i18n.js';
+import { readFileSync } from 'node:fs';
+import { roleView, describeChanges, resolveRole, seed } from './config.js';
+import { modelCatalog, changedRoutes, verifyRoutes } from './allocation.js';
+import { saveProject } from './theme.js';
+import { params } from './tool-schema.js';
+import { registerTeamReader, registerPolicyWriter } from './runtime-view.js';
+import { modelPolicyRows, applyModelPolicy, policyRoleView } from './model-policy.js';
+import { accessSummary } from './access.js';
+import { toTemplate, templatePatch, TEMPLATE_FORMAT } from './template.js';
+import { ROLE_THEMES, themePatch } from './roster-defaults.js';
+import { singleModelFrom } from './single-model.js';
+const output = { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] };
+const ENTRY_RULE = modelText('theme-plugin.506');
+/** Model-facing team context for one Agent, rebuilt from the pinned project on every step. */
+export function teamContext(team, agent, membership, failover, workflow, planGate) {
+  const project = team.pinned(agent);
+  if (!project) return modelText('theme-plugin.507');
+  let loaded;
+  try { loaded = team.loadSync(project, agent); }
+  catch (error) { return modelText('theme-plugin.508', { 0: error.message }); }
+  let self;
+  try {
+    const { failover: _policy, access, ...role } = applyModelPolicy(resolveRole(membership, loaded.effective), loaded.policy?.disabledRoutes);
+    self = role;
+    const limits = accessSummary(access);
+    if (limits) self.access = modelText('theme-plugin.509', { 0: limits });
+    const planState = planGate?.status(agent, membership, role);
+    if (planState) self.plan = planState;
+    const live = failover?.status(agent);
+    const allowed = [role, ...(role.fallbacks ?? [])].map(r => `${r.provider}/${r.model}`);
+    const wide = role.longContext ? `${role.longContext.provider}/${role.longContext.model}` : undefined;
+    if (live?.active && live.active === wide) self.currentRoute = modelText('theme-plugin.510', { 0: wide });
+    else if (live && !live.primary && allowed.includes(live.active)) self.currentRoute = modelText('theme-plugin.511', { 0: live.active });
+  } catch (error) { self = { error: error.message }; }
+  const roster = roleView(loaded.effective).map(entry => {
+    try {
+      const { id, displayName, capability, whenToUse, provider, model, access, singleModel } = applyModelPolicy(entry, loaded.policy?.disabledRoutes);
+      const limits = accessSummary(access);
+      return { id, displayName, capability, ...(whenToUse ? { whenToUse } : {}), model: provider ? `${provider}/${model}${singleModel ? modelText('theme-plugin.512') : ''}` : modelText('theme-plugin.513'), ...(limits ? { access: limits } : {}) };
+    } catch (error) { return { id: entry.id, displayName: entry.displayName, model: modelText('theme-plugin.514'), error: error.message }; }
+  });
+  const status = membership?.role === 'lead' ? workflow?.status(agent, loaded.effective.workflow) : undefined;
+  return modelText('theme-plugin.515', { 0: loaded.effective.name, 1: loaded.revision, 2: project, 3: JSON.stringify(self), 4: JSON.stringify(roster), 5: status ? `\n${status}` : '' });
+}
+async function confirm(ctx, exec, lines, revision) {
+  const answer = await ctx.userQuestions.ask({ agent: exec.agent, signal: exec.signal, questions: [{
+    id: 'confirm', header: t('theme-plugin.516'),
+    question: t('theme-plugin.517', { 0: lines.length }),
+    detail: t('theme-plugin.518', { 0: lines.join('\n'), 1: revision }),
+    options: [{ label: t('theme-plugin.519'), description: t('theme-plugin.520') }, { label: t('theme-plugin.521'), description: t('theme-plugin.522') }],
+  }] });
+  const item = answer.answers.find(a => a.id === 'confirm');
+  if (!item?.selected.includes(t('theme-plugin.523'))) throw new Error(modelText('theme-plugin.524', { 0: item?.custom ? modelText('theme-plugin.525', { 0: item.custom }) : '' }));
+}
+export function apply(ctx, team, failover, workflow, planGate, taskControl) {
+  const content = readFileSync(new URL('./skills/project-role-theme/SKILL.md', import.meta.url), 'utf8');
+  ctx.effect(() => ctx.skills.register({ name: 'project-role-theme', source: 'runtime', content,
+    description: modelText('theme-plugin.526') }));
+  ctx.effect(() => ctx.tools.register({ name: 'capability_team_read', parameters: params(), output,
+    description: modelText('theme-plugin.527'),
+    async execute(_args, exec) {
+      await team.refresh();
+      const { project, revision, overrides, effective, policy } = await team.load(exec.agent);
+      const { report, unknown, errors, detectedAt } = team.detection();
+      return JSON.stringify({ project, revision, defaults: team.base, overrides, effective, roles: policyRoleView(roleView(effective), policy.disabledRoutes), coolingRoutes: failover?.cooling() ?? [],
+        autoMatch: { detectedAt, report, unrecognized: unknown.slice(0, 50), unrecognizedCount: unknown.length, errors } });
+    },
+  }));
+  ctx.effect(() => ctx.tools.register({ name: 'capability_model_catalog', parameters: params(), output,
+    description: modelText('theme-plugin.528'),
+    async execute(_args, exec) {
+      const { effective } = await team.load(exec.agent);
+      return JSON.stringify(await modelCatalog(ctx.llm, effective.tiers));
+    },
+  }));
+  ctx.effect(() => ctx.tools.register({ name: 'capability_team_save', output,
+    description: modelText('theme-plugin.529'),
+    parameters: params({
+      expected_revision: { type: 'integer', description: modelText('theme-plugin.530') },
+      name: { type: 'string', description: modelText('theme-plugin.531') },
+      tiers: { type: 'object', additionalProperties: true, description: modelText('theme-plugin.532', { 0: ENTRY_RULE }) },
+      capabilities: { type: 'object', additionalProperties: true, description: modelText('theme-plugin.533', { 0: ENTRY_RULE }) },
+      failover: { oneOf: [{ type: 'object', additionalProperties: true }, { type: 'null' }], description: modelText('theme-plugin.534') },
+      workflow: { oneOf: [{ type: 'object', additionalProperties: true }, { type: 'null' }], description: modelText('theme-plugin.535') },
+      roles: { type: 'object', additionalProperties: true, description: modelText('theme-plugin.536', { 0: ENTRY_RULE }) },
+      single_model: { type: 'string', enum: ['use-default', 'off'], description: modelText('theme-plugin.537') },
+    }, ['expected_revision']),
+    async execute(args, exec) {
+      const singleModel = args.single_model === 'off' ? null : args.single_model === 'use-default' ? singleModelFrom(ctx.get?.('agentDefaultModel')?.currentSelection?.()) : undefined;
+      const patch = { name: args.name, failover: args.failover, workflow: args.workflow, tiers: args.tiers, capabilities: args.capabilities, roles: args.roles, singleModel };
+      return JSON.stringify(await saveConfirmed(exec, patch, args.expected_revision));
+    },
+  }));
+  /** Validate, check new routes against the catalog, and save only after the user approves the full diff. */
+  async function saveConfirmed(exec, patch, expectedRevision) {
+    if (ctx.agentTeams.membership(exec.agent).role !== 'lead') throw new Error(modelText('theme-plugin.538'));
+    const project = await team.pin(exec.agent);
+    const result = await saveProject(project, patch, expectedRevision, { base: team.base, root: team.root,
+      async check(before, after) {
+        const lines = describeChanges(before, after);
+        if (!lines.length) throw new Error(modelText('theme-plugin.539'));
+        const routes = changedRoutes(before, after);
+        const single = after.singleModel && `${after.singleModel.provider}/${after.singleModel.model}` !== `${before.singleModel?.provider}/${before.singleModel?.model}`
+          ? [{ capability: modelText('theme-plugin.540'), ...after.singleModel }] : [];
+        if (routes.length || single.length) verifyRoutes([...routes, ...single], await modelCatalog(ctx.llm, after.tiers));
+        await confirm(ctx, exec, lines, expectedRevision);
+      } });
+    return { saved: true, project: result.project, revision: result.revision, roles: roleView(result.effective) };
+  }
+  ctx.effect(() => ctx.tools.register({ name: 'capability_team_export', parameters: params(), output,
+    description: modelText('theme-plugin.541', { 0: TEMPLATE_FORMAT }),
+    async execute(_args, exec) {
+      const { effective } = await team.load(exec.agent);
+      return JSON.stringify(toTemplate(effective), null, 2);
+    },
+  }));
+  ctx.effect(() => ctx.tools.register({ name: 'capability_team_import', output,
+    description: modelText('theme-plugin.542', { 0: Object.keys(ROLE_THEMES).join(' / ') }),
+    parameters: params({
+      expected_revision: { type: 'integer', description: modelText('theme-plugin.543') },
+      template: { type: 'object', additionalProperties: true, description: modelText('theme-plugin.544', { 0: TEMPLATE_FORMAT }) },
+      theme: { type: 'string', enum: Object.keys(ROLE_THEMES), description: modelText('theme-plugin.545') },
+    }, ['expected_revision']),
+    async execute(args, exec) {
+      const { effective } = await team.load(exec.agent);
+      if ((args.template === undefined) === (args.theme === undefined)) throw new Error(modelText('theme-plugin.546'));
+      const patch = args.theme === undefined ? templatePatch(args.template, effective) : themePatch(args.theme, effective);
+      const result = await saveConfirmed(exec, patch, args.expected_revision);
+      const unassigned = result.roles.filter(r => r.provider === undefined).map(r => r.id);
+      return JSON.stringify({ ...result, ...(unassigned.length ? { unassigned, next: modelText('theme-plugin.547') } : {}) });
+    },
+  }));
+  // Install the team context in each Team member's own scope, like the native Team identity.
+  const installed = new Map();
+  const install = async agent => {
+    if (installed.has(agent) || !ownsCapabilityTeam(ctx, agent) || ctx.agentTeams.tryMembership(agent) === undefined) return;
+    installed.set(agent, undefined);
+    // Pin before the first step; a failure must not block creation and resurfaces on the next request.
+    await team.pin(agent).catch(() => {});
+    if (!installed.has(agent)) return; // disposed meanwhile
+    const removeReader = registerTeamReader(agent, async () => {
+      await team.refresh();
+      const { project, revision, effective, policy } = await team.load(agent);
+      return { project, revision, name: effective.name, ...(effective.singleModel ? { singleModel: effective.singleModel } : {}), roles: policyRoleView(roleView(effective), policy.disabledRoutes), workflow: effective.workflow,
+        modelPolicy: { ...modelPolicyRows(effective.tiers, roleView(effective), policy.disabledRoutes, [...(team.detection().pools ?? []), ...(team.detection().unknown ?? [])]), revision: policy.revision },
+        autoMatch: team.detection().report, catalogErrors: team.detection().errors ?? [], actualRequest: null,
+        ...(effective.tierDrift ? { tierDrift: effective.tierDrift } : {}),
+        modelNotice: t('theme-plugin.548') };
+    });
+    const removeContext = agent.ctx.systemPrompt.context({ name: 'capability-team:roster', order: 98, required: true,
+      text: () => (ownsCapabilityTeam(ctx, agent) ? teamContext(team, agent, ctx.agentTeams.tryMembership(agent), failover, workflow, planGate) : '') });
+    const removeBudgetContext = taskControl && ctx.agentTeams.tryMembership(agent)?.role === 'lead'
+      ? agent.ctx.systemPrompt.context({ name: 'capability-team:task-budget', order: 99, required: true,
+        text: () => (ownsCapabilityTeam(ctx, agent) ? taskControl.summary(agent) : '') }) : () => {};
+    const removeWriter = registerPolicyWriter(agent, (routes, revision) => team.savePolicy(agent, routes, revision));
+    installed.set(agent, () => { removeReader(); removeWriter(); removeContext(); removeBudgetContext(); });
+  };
+  for (const agent of ctx.agents.list()) void install(agent);
+  ctx.on('agent/created', ({ agent }) => install(agent));
+  ctx.on('agent/disposed', ({ agent }) => { installed.get(agent)?.(); installed.delete(agent); });
+  // A blank session reused for another preset is recomposed without agent/created or agent/disposed.
+  ctx.on('agent-preset/selected', sessionId => {
+    let agent; try { agent = ctx.agents?.get?.(sessionId); } catch { return; }
+    if (!agent) return;
+    if (ownsCapabilityTeam(ctx, agent)) { void install(agent); return; }
+    installed.get(agent)?.(); installed.delete(agent);
+  });
+  ctx.effect(() => () => { for (const dispose of installed.values()) dispose?.(); installed.clear(); });
+}
+export { seed };
+import { ownsCapabilityTeam } from './preset-guard.js';

package/theme.js

@@ -0,0 +1,115 @@
+import { m as modelText } from './i18n.js';
+// Per-project team configuration store: overrides on top of the preset base.
+import { mkdir, readFile, writeFile, rename, unlink, open, stat } from 'node:fs/promises';
+import { readFileSync, statSync, existsSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { resolve, join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { effectiveConfig, migrateProject, applyPatch, seed } from './config.js';
+import { pinRoster } from './roster-defaults.js';
+export const STALE_LOCK_MS = 30000;
+export function defaultRoot() {
+  return process.env.CAPABILITY_TEAM_HOME || join(homedir(), '.dsh', 'capability-team-themes');
+}
+function identity(dir) {
+  const project = resolve(dir);
+  return process.platform === 'win32' ? project.toLowerCase() : project;
+}
+export function themePath(cwd, root = defaultRoot()) {
+  return join(root, createHash('sha256').update(identity(cwd)).digest('hex') + '.json');
+}
+/** Nearest ancestor (inclusive) that already owns a configuration, else the directory itself. */
+export function projectRoot(cwd, root = defaultRoot()) {
+  let dir = resolve(cwd);
+  for (;;) {
+    if (existsSync(themePath(dir, root))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(cwd);
+    dir = parent;
+  }
+}
+const cache = new Map();
+function parse(raw, path) {
+  try { return migrateProject(JSON.parse(raw)); }
+  catch (error) { throw new Error(modelText('theme.549', { 0: path, 1: error.message })); }
+}
+const EMPTY = Object.freeze({ revision: 0, tiers: {}, capabilities: {}, roles: {} });
+function remember(path, info, raw) {
+  const value = parse(raw, path);
+  cache.set(path, { mtimeMs: info.mtimeMs, size: info.size, value });
+  return value;
+}
+function cached(path, info) {
+  const hit = cache.get(path);
+  return hit && hit.mtimeMs === info.mtimeMs && hit.size === info.size ? hit.value : undefined;
+}
+/** Read stored overrides; cached by mtime and size so a request costs one stat. */
+export async function readOverrides(project, root = defaultRoot()) {
+  const path = themePath(project, root);
+  let info;
+  try { info = await stat(path); } catch (error) { if (error.code === 'ENOENT') { cache.delete(path); return EMPTY; } throw error; }
+  return cached(path, info) ?? remember(path, info, await readFile(path, 'utf8'));
+}
+/** Synchronous variant for prompt assembly, which cannot await. */
+export function readOverridesSync(project, root = defaultRoot()) {
+  const path = themePath(project, root);
+  let info;
+  try { info = statSync(path); } catch (error) { if (error.code === 'ENOENT') { cache.delete(path); return EMPTY; } throw error; }
+  return cached(path, info) ?? remember(path, info, readFileSync(path, 'utf8'));
+}
+export async function loadProject(project, base = seed, root) {
+  const overrides = await readOverrides(project, root);
+  return { project, revision: overrides.revision, overrides, effective: effectiveConfig(overrides, base, { trustedFrom: overrides }) };
+}
+export function loadProjectSync(project, base = seed, root) {
+  const overrides = readOverridesSync(project, root);
+  return { project, revision: overrides.revision, overrides, effective: effectiveConfig(overrides, base, { trustedFrom: overrides }) };
+}
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+export async function acquireLock(lockPath) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const handle = await open(lockPath, 'wx');
+      try { await handle.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() })); }
+      catch (error) { await handle.close(); await unlink(lockPath); throw error; }
+      return handle;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let owner = {};
+      try { owner = JSON.parse(await readFile(lockPath, 'utf8')); } catch { /* empty or partial lock: judged by file age */ }
+      const since = Number(owner.at) || (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+      const knownOwner = Number.isSafeInteger(owner.pid) && owner.pid > 0;
+      // A confirmation dialog can stay open for minutes. Age never invalidates a live owner's lock.
+      const stale = knownOwner ? !alive(owner.pid) : Date.now() - since > STALE_LOCK_MS;
+      if (attempt || !stale) throw new Error(modelText('theme.550'));
+      await unlink(lockPath).catch(e => { if (e.code !== 'ENOENT') throw e; });
+    }
+  }
+}
+/**
+ * Apply one patch under a lock with revision CAS; the merged result must validate.
+ * `check(before, after)` may reject, for example on a catalog or confirmation failure.
+ */
+export async function saveProject(project, patch, expectedRevision, { base = seed, root = defaultRoot(), check } = {}) {
+  const path = themePath(project, root);
+  await mkdir(dirname(path), { recursive: true });
+  const lock = await acquireLock(path + '.lock');
+  const tmp = path + '.' + randomUUID() + '.tmp';
+  try {
+    const previous = await loadProject(project, base, root);
+    if (!Number.isSafeInteger(expectedRevision) || previous.revision !== expectedRevision) throw new Error(modelText('theme.551', { 0: previous.revision }));
+    const nextOverrides = pinRoster(applyPatch(previous.overrides, patch), previous.overrides, base.roles);
+    const effective = effectiveConfig(nextOverrides, base, { trustedFrom: previous.overrides });
+    if (check) await check(previous.effective, effective);
+    const stored = { ...nextOverrides, revision: previous.revision + 1, project: resolve(project) };
+    await writeFile(tmp, JSON.stringify(stored, null, 2), { encoding: 'utf8', flag: 'wx' });
+    await rename(tmp, path);
+    cache.delete(path);
+    return { project: resolve(project), revision: stored.revision, effective };
+  } finally {
+    try { await unlink(tmp).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+    finally { try { await lock.close(); } finally { await unlink(path + '.lock').catch(e => { if (e.code !== 'ENOENT') throw e; }); } }
+  }
+}

package/token-discipline.js

@@ -0,0 +1,116 @@
+import { m as modelText } from './i18n.js';
+// Token rules for the team (part of the iron rules). Measured on this project: prompt caching already works
+// (93–98% of prompt tokens are cache reads), so cost is driven by how much context every step resends —
+// sessions ran at ~150k tokens per step because DSH compacts only at 80% of the window. The levers are a small,
+// stable prefix and a small working context, without breaking the cache:
+// 1. Idle compaction: when a team member goes idle above `idleCompactRatio` of its window, compact it then.
+//    The provider cache expires after a few idle minutes anyway, so this costs almost no cache.
+// 2. Oversized command/search output is cut to head + tail at once (the full text is spilled to a file),
+//    instead of riding along in every later step until DSH's own pruner runs at compaction time.
+// 3. The prefix stays stable: plugin context only changes on events, and routes do not flip per step.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promptTokens } from './long-context.js';
+import { ownsCapabilityTeam } from './preset-guard.js';
+import { createTokenMetrics, usageSample } from './token-metrics.js';
+import { restrictiveToolName } from './tool-names.js';
+export const TOKEN_RULES = { idleCompactRatio: 0.35, trimToolOutputChars: 6000, keepHeadChars: 3000, keepTailChars: 1500 };
+const KEYS = Object.keys(TOKEN_RULES);
+/** Tools whose output is a log or listing rather than content the model must read whole. */
+export const TRIMMED_TOOLS = new Set(['bash', 'pwsh', 'grep', 'glob', 'job_output', 'web_fetch', 'web_search', 'omni_fetch', 'omni_search', 'session_search', 'session_event_search']);
+export function validateTokenRules(value) {
+  if (value === undefined || value === null) return { ...TOKEN_RULES };
+  if (value === false) return false;
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(modelText('token-discipline.552'));
+  const extra = Object.keys(value).filter(k => !KEYS.includes(k));
+  if (extra.length) throw new Error(modelText('token-discipline.553', { 0: extra.join(', ') }));
+  const out = { ...TOKEN_RULES, ...value };
+  if (typeof out.idleCompactRatio !== 'number' || out.idleCompactRatio < 0.1 || out.idleCompactRatio > 0.9) throw new Error(modelText('token-discipline.554'));
+  for (const k of ['trimToolOutputChars', 'keepHeadChars', 'keepTailChars']) if (!Number.isSafeInteger(out[k]) || out[k] < 200 || out[k] > 200000) throw new Error(modelText('token-discipline.555', { 0: k }));
+  if (out.keepHeadChars + out.keepTailChars >= out.trimToolOutputChars) throw new Error(modelText('token-discipline.556'));
+  return out;
+}
+/** Model-facing token rules, appended to the file rules in the team policy. */
+export function tokenRuleText(rules) {
+  if (!rules) return '';
+  return modelText('token-discipline.557', { 0: rules.trimToolOutputChars, 1: Math.round(rules.idleCompactRatio * 100) });
+}
+/** Head + tail of a long text with a pointer to the full copy. Pure. */
+export function trimText(text, rules, spillPath) {
+  const head = text.slice(0, rules.keepHeadChars);
+  const tail = text.slice(-rules.keepTailChars);
+  return modelText('token-discipline.558', { 0: head, 1: text.length - head.length - tail.length, 2: text.length, 3: spillPath, 4: tail });
+}
+export function createTokenDiscipline(ctx, team, { spillDir = join(tmpdir(), 'capability-team-spill'), rulesOf, trimmedTools = TRIMMED_TOOLS, ratesOf } = {}) {
+  const compacting = new WeakSet();
+  const metrics = createTokenMetrics({ ratesOf });
+  // `compaction` is not in the plugin's inject list, and cordis throws on a direct read of an un-injected
+  // service (that once stopped the DSH host). It arrives through ctx.inject when the host provides it.
+  let compactionService;
+  const compaction = () => compactionService;
+  const rules = agent => {
+    if (rulesOf) return rulesOf(agent);
+    const project = team.pinned(agent);
+    if (!project) return TOKEN_RULES;
+    try { return team.loadSync(project, agent).effective.workflow.tokens; } catch { return TOKEN_RULES; }
+  };
+  const isMember = agent => ownsCapabilityTeam(ctx, agent) && !!ctx.agentTeams.tryMembership(agent);
+  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; }
+  };
+  async function compactIdleUnsafe(agent) {
+    const r = rules(agent);
+    const service = compaction();
+    if (!r || compacting.has(agent) || !isMember(agent) || typeof service?.compactNow !== 'function') return false;
+    const ratio = ratioOf(agent);
+    if (ratio === undefined || ratio < r.idleCompactRatio) return false;
+    compacting.add(agent);
+    const started = Date.now();
+    try { const done = (await service.compactNow(agent, AbortSignal.timeout(180000))) !== null; if (done) metrics.compact(agent, Date.now() - started); return done; }
+    finally { compacting.delete(agent); }
+  }
+  const api = {
+    metrics,
+    /** Compact an idle member whose context is above the idle threshold. Never throws; returns true when it ran. */
+    async compactIdle(agent) {
+      // busy (new work arrived), nothing compactable or any host error: skip, and try again on the next idle
+      try { return await compactIdleUnsafe(agent); } catch { return false; }
+    },
+    /** Post-execute decision: trim an oversized log/listing result for a team member. */
+    async trim(exec, result) {
+      const r = rules(exec.agent);
+      if (!r || !new Set(trimmedTools).has(restrictiveToolName(exec.name, new Set(trimmedTools))) || !isMember(exec.agent) || !Array.isArray(result?.content)) return undefined;
+      const text = result.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+      if (text.length <= r.trimToolOutputChars || result.content.some(b => b.type !== 'text')) return undefined;
+      await mkdir(spillDir, { recursive: true });
+      const path = join(spillDir, `${String(exec.callId ?? Date.now()).replace(/[^\w.-]/g, '_')}.txt`);
+      await writeFile(path, text);
+      const trimmed = trimText(text, r, path);
+      metrics.trim(exec.agent, text.length, trimmed.length);
+      return [{ type: 'text', text: trimmed }];
+    },
+    register() {
+      ctx.on('agent/request', async (payload, next) => {
+        const result = await next();
+        if (isMember(payload.agent)) metrics.sample(payload.agent, payload.turn, payload.step, usageSample(ctx.get?.('sessionProjections'), payload.agent.session));
+        return result;
+      });
+      try { ctx.inject?.(['compaction'], scoped => { compactionService = scoped.compaction; scoped.effect?.(() => () => { compactionService = undefined; }); }); } catch { /* host without compaction */ }
+      // Listeners must never reject: an unhandled rejection inside a host event stops the DSH host.
+      ctx.on('agent/status', ({ agent, status }) => { if (status === 'idle') api.compactIdle(agent).catch(() => {}); });
+      ctx.on('tools/post-execute', async (exec, result, next) => {
+        const decision = await next();
+        if (decision?.kind !== 'accept' || decision.content !== undefined || result?.isError) return decision;
+        try { const content = await api.trim(exec, result); return content ? { ...decision, content } : decision; }
+        catch { return decision; }
+      });
+    },
+  };
+  return api;
+}

package/token-metrics.js

@@ -0,0 +1,37 @@
+// Numeric telemetry only; never injected into prompts. Provider billing rates are optional.
+export function usageSample(projections, session) {
+  try {
+    const state = projections?.stateOf(session, 'tokenUsage');
+    const value = state?.totals ?? state;
+    return value ? { ...value, inputTokens: value.inputTokens ?? value.uncachedInputTokens } : null;
+  } catch { return null; }
+}
+const n = x => Number.isFinite(x) && x >= 0 ? x : 0;
+export function estimateCost(usage, rates) {
+  if (!rates) return null;
+  return (n(usage.inputTokens) * n(rates.input) + n(usage.cacheReadTokens) * n(rates.cacheRead)
+    + n(usage.cacheWriteTokens) * n(rates.cacheWrite) + n(usage.outputTokens) * n(rates.output)) / 1e6;
+}
+export function createTokenMetrics({ now = Date.now, ratesOf = () => null } = {}) {
+  const sessions = new WeakMap();
+  const state = agent => { if (!sessions.has(agent)) sessions.set(agent, { steps: [], trimmedChars: 0, estimatedSavedTokens: 0, compactions: 0, compactionMs: 0 }); return sessions.get(agent); };
+  return {
+    sample(agent, turn, step, usage, route) {
+      if (!usage) return;
+      const row = { turn, step, at: now(), prompt: n(usage.inputTokens) + n(usage.cacheReadTokens) + n(usage.cacheWriteTokens),
+        cacheRead: n(usage.cacheReadTokens), cacheWrite: n(usage.cacheWriteTokens), output: n(usage.outputTokens),
+        estimatedCost: estimateCost(usage, ratesOf(route)), source: 'sessionProjections.tokenUsage' };
+      const s = state(agent), old = s.steps.findIndex(x => x.turn === turn && x.step === step);
+      const totals = { prompt: row.prompt, cacheRead: row.cacheRead, cacheWrite: row.cacheWrite, output: row.output };
+      const baseline = old >= 0 ? s.steps[old].baseline : (s.lastTotals ?? { prompt: 0, cacheRead: 0, cacheWrite: 0, output: 0 });
+      for (const key of Object.keys(totals)) row[key] = Math.max(0, totals[key] - baseline[key]);
+      row.baseline = baseline; s.lastTotals = totals;
+      row.estimatedCost = estimateCost({ inputTokens: Math.max(0, row.prompt - row.cacheRead - row.cacheWrite), cacheReadTokens: row.cacheRead, cacheWriteTokens: row.cacheWrite, outputTokens: row.output }, ratesOf(route));
+      if (old >= 0) s.steps[old] = row; else s.steps.push(row);
+      s.steps = s.steps.slice(-1000);
+    },
+    trim(agent, before, after) { const s = state(agent), saved = Math.max(0, before - after); s.trimmedChars += saved; s.estimatedSavedTokens += Math.ceil(saved / 4); },
+    compact(agent, duration) { const s = state(agent); s.compactions++; s.compactionMs += n(duration); },
+    snapshot(agent) { return structuredClone(state(agent)); },
+  };
+}

package/tool-names.js

@@ -0,0 +1,10 @@
+// Host aliases supported by the existing workflow: optional MCP envelope and one word prefix.
+// A suffix is NOT proof of native tool identity. Use these candidates only to ADD restrictions,
+// never to grant permissions, mark a tool read-only, or establish sandbox/confirmation trust.
+export function restrictiveToolName(name, known) {
+  const raw = String(name ?? '').replace(/^mcp__.+?__/, '');
+  const has = value => typeof known === 'function' ? known(value) : known instanceof Set ? known.has(value) : Object.hasOwn(known, value);
+  if (has(raw)) return raw;
+  const tail = raw.slice(raw.indexOf('_') + 1);
+  return raw.includes('_') && has(tail) ? tail : raw;
+}

package/tool-schema.js

@@ -0,0 +1,23 @@
+// ctx.tools.register sends `parameters` to the model verbatim as JSON Schema (draft 2020-12),
+// so tool parameters must be a raw object-rooted schema, not the defineTool shorthand
+// (`{name: {type, required: true}}`). DSH accepts only this keyword subset.
+const ALLOWED = new Set(['type', 'oneOf', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const', 'description', 'title', 'default', 'examples']);
+
+/** Object-rooted parameter schema; `required` lists property names. */
+export function params(properties = {}, required = []) {
+  for (const name of required) if (!Object.hasOwn(properties, name)) throw new Error(`required parameter ${name} is not declared`);
+  return { type: 'object', properties, ...(required.length ? { required } : {}) };
+}
+
+/** Throws when a schema uses keywords outside the DSH subset or the shorthand `required: true`. */
+export function assertToolSchema(schema, path = 'parameters') {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) throw new Error(`${path} must be a schema object`);
+  for (const [key, value] of Object.entries(schema)) {
+    if (!ALLOWED.has(key)) throw new Error(`${path}.${key} is not a supported keyword`);
+    if (key === 'required' && !(Array.isArray(value) && value.every(v => typeof v === 'string'))) throw new Error(`${path}.required must be an array of property names`);
+  }
+  if (path === 'parameters' && schema.type !== 'object') throw new Error('parameters must have type "object" at the root');
+  for (const [name, sub] of Object.entries(schema.properties ?? {})) assertToolSchema(sub, `${path}.properties.${name}`);
+  if (schema.items) assertToolSchema(schema.items, `${path}.items`);
+  for (const [i, sub] of (schema.oneOf ?? []).entries()) assertToolSchema(sub, `${path}.oneOf[${i}]`);
+}

package/transcribe.js

@@ -0,0 +1,104 @@
+// Speech to text through the configured gateway (integrations.audio). The file is read locally only after the
+// user approves that exact path in DSH's native question box, then uploaded as multipart with its real bytes;
+// fetch's FormData sets the boundary. The key goes into the Authorization header only, never into prompts,
+// tool arguments or logs. A 200 still has to carry text to count as a result.
+import { m, t } from './i18n.js';
+import { open, realpath } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { keyOf, refreshCredentials, resolveIntegrations } from './integrations-config.js';
+import { gatewayBase, httpError } from './search.js';
+import { readCapped } from './search-engines.js';
+import { params } from './tool-schema.js';
+export const AUDIO_TYPES = { '.mp3': 'audio/mpeg', '.mp4': 'audio/mp4', '.m4a': 'audio/mp4', '.mpeg': 'audio/mpeg', '.mpga': 'audio/mpeg', '.wav': 'audio/wav', '.webm': 'audio/webm', '.ogg': 'audio/ogg', '.oga': 'audio/ogg', '.flac': 'audio/flac' };
+const AUDIO_BASE = { what: m('transcribe.559'), field: 'audio.baseUrl', envName: 'OMNI_AUDIO_BASE_URL' };
+const extOf = path => (/\.[^.\\/]+$/.exec(path)?.[0] ?? '').toLowerCase();
+export function audioSettings(resolved = resolveIntegrations()) {
+  return { config: resolved.effective.audio, key: keyOf('audio', resolved), keyEnv: resolved.keys.audio.env };
+}
+/**
+ * Check type and size on an open handle, call `approve(size)`, and only then read the bytes. Nothing is read
+ * before approval, and the size checked is the size of the file actually read (no stat/read race).
+ */
+export async function readAudio(path, maxBytes, approve = async () => {}) {
+  // A symlink named meeting.mp3 could point anywhere (e.g. a private key): check and show the real target.
+  const unsupported = name => new Error(m('transcribe.560', { 0: extOf(name) || m('transcribe.561'), 1: Object.keys(AUDIO_TYPES).join(' ') }));
+  if (!AUDIO_TYPES[extOf(path)]) throw unsupported(path);
+  const real = await realpath(path);
+  if (!AUDIO_TYPES[extOf(real)]) throw unsupported(real);
+  const handle = await open(real, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error(m('transcribe.562'));
+    if (stat.size > maxBytes) throw new Error(m('transcribe.563', { 0: (stat.size / 1048576).toFixed(1), 1: (maxBytes / 1048576).toFixed(1) }));
+    if (!stat.size) throw new Error(m('transcribe.564'));
+    await approve(stat.size, real);
+    const bytes = await handle.readFile();
+    if (bytes.byteLength > maxBytes) throw new Error(m('transcribe.565'));
+    return bytes;
+  } finally { await handle.close(); }
+}
+export async function transcribe({ bytes, name, language, prompt }, { settings, fetcher = fetch, signal } = {}) {
+  if (!settings) await refreshCredentials();
+  const { config, key, keyEnv } = settings ?? audioSettings();
+  if (!key) throw new Error(m('transcribe.566', { 0: keyEnv }));
+  const origin = gatewayBase(config.baseUrl, AUDIO_BASE);
+  const form = new FormData();
+  form.append('file', new Blob([bytes], { type: AUDIO_TYPES[extOf(name)] ?? 'application/octet-stream' }), name);
+  if (config.model) form.append('model', config.model);
+  if (language) form.append('language', language);
+  if (prompt) form.append('prompt', prompt);
+  const timeout = AbortSignal.timeout(config.timeoutMs);
+  const response = await fetcher(`${origin}${config.path}`, { method: 'POST', redirect: 'error', body: form,
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout, headers: { ...config.headers, Authorization: `Bearer ${key}` } });
+  if (!response.ok) throw httpError(m('transcribe.559'), response.status);
+  const text = await readCapped(response, m('transcribe.559'));
+  if (text.includes(key)) throw new Error(m('transcribe.569'));
+  let data; try { data = JSON.parse(text); } catch { data = { text }; }
+  if (typeof data?.text !== 'string' || !data.text.trim()) throw new Error(m('transcribe.570'));
+  return data;
+}
+export async function audioStatus({ settings, fetcher = fetch, signal } = {}) {
+  if (!settings) await refreshCredentials();
+  const { config, key, keyEnv } = settings ?? audioSettings();
+  if (!config.statusPath) throw new Error(m('transcribe.571'));
+  if (!key) throw new Error(m('transcribe.572', { 0: keyEnv }));
+  const timeout = AbortSignal.timeout(30000);
+  const response = await fetcher(`${gatewayBase(config.baseUrl, AUDIO_BASE)}${config.statusPath}`, { method: 'GET', redirect: 'error',
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout, headers: { ...config.headers, Authorization: `Bearer ${key}` } });
+  if (!response.ok) throw httpError(m('transcribe.573'), response.status);
+  const text = await readCapped(response, m('transcribe.573'));
+  if (text.includes(key)) throw new Error(m('transcribe.569'));
+  let status; try { status = JSON.parse(text); } catch { throw new Error(m('transcribe.576')); }
+  return { note: t('transcribe.577'), status };
+}
+/** Ask the user, in DSH's native question box, to allow uploading this one file. */
+async function approve(ctx, exec, path, size, cwd) {
+  const allowLabel = t('transcribe.582');
+  const outside = cwd && relative(cwd, path).startsWith('..') ? t('transcribe.578') : '';
+  const answer = await ctx.userQuestions.ask({ agent: exec.agent, signal: exec.signal, questions: [{
+    id: 'upload', header: t('transcribe.579'),
+    question: t('transcribe.580'),
+    detail: t('transcribe.581', { 0: path, 1: (size / 1048576).toFixed(2), 2: outside }),
+    options: [{ label: allowLabel, description: t('transcribe.583') }, { label: t('transcribe.584'), description: t('transcribe.585') }],
+  }] });
+  if (!answer.answers.find(a => a.id === 'upload')?.selected.includes(allowLabel)) throw new Error(m('transcribe.587'));
+}
+const output = { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] };
+export function applyTranscribe(ctx) {
+  ctx.effect(() => ctx.tools.register({ name: 'omni_transcribe', output,
+    description: m('transcribe.588'),
+    parameters: params({ file_path: { type: 'string', description: m('transcribe.589') }, language: { type: 'string', description: m('transcribe.590') }, prompt: { type: 'string', description: m('transcribe.591') } }, ['file_path']),
+    async execute(args, exec) {
+      const cwd = await ctx.workingDirectory.ensure(exec.agent, exec.signal);
+      const path = isAbsolute(String(args.file_path)) ? String(args.file_path) : resolve(cwd, String(args.file_path));
+      const max = audioSettings().config.maxBytes;
+      const bytes = await readAudio(path, max, (size, real) => approve(ctx, exec, real, size, cwd)); // read only after approval
+      const result = await transcribe({ bytes, name: basename(path), language: args.language, prompt: args.prompt }, { signal: exec.signal });
+      return JSON.stringify(result);
+    },
+  }));
+  ctx.effect(() => ctx.tools.register({ name: 'omni_transcribe_status', output, parameters: params({}, []),
+    description: m('transcribe.592'),
+    async execute(_args, exec) { return JSON.stringify(await audioStatus({ signal: exec.signal })); },
+  }));
+}