@aiwuk/team 0.0.0-stage → 5.0.3

package/plan-gate.js

@@ -0,0 +1,92 @@
+import { m as modelText } from './i18n.js';
+// Plan-first teammates: a capability with `planFirst` submits a plan to the Lead and waits for approval before it may
+// run execution tools. A new dispatch plan that assigns the role asks for a fresh plan, so one approval covers one task.
+import { params } from './tool-schema.js';
+import { ownsCapabilityTeam } from './preset-guard.js';
+import { resolveRole } from './config.js';
+import { toolClass } from './workflow.js';
+export const SUBMIT_TOOL = 'capability_submit_plan';
+export const REVIEW_TOOL = 'capability_review_plan';
+const output = { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] };
+const STATUS = { pending: modelText('plan-gate.324'), approved: modelText('plan-gate.325'), rejected: modelText('plan-gate.326') };
+function text(value, max, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error(modelText('plan-gate.327', { 0: label, 1: max }));
+  return value.trim();
+}
+/** Pure decision for one teammate call under plan-first; returns a denial reason or undefined. */
+export function planDenial(exec, role, plan, workflow) {
+  if (!role.planFirst || exec.name === SUBMIT_TOOL || plan?.status === 'approved') return undefined;
+  const kind = toolClass(exec.name, workflow);
+  if (kind === 'analysis' || kind === 'coordination') return undefined;
+  const state = plan ? modelText('plan-gate.328', { 0: STATUS[plan.status], 1: plan.feedback ? modelText('plan-gate.329', { 0: plan.feedback }) : '' }) : modelText('plan-gate.330');
+  return modelText('plan-gate.331', { 0: role.displayName, 1: role.capability, 2: SUBMIT_TOOL, 3: exec.name, 4: state });
+}
+export function createPlanGate(ctx, team) {
+  const plans = new Map(); // `${teamId}:${role}` → { status, plan, feedback?, at }
+  const keyOf = (membership, role = membership.name) => `${membership.id}:${role}`;
+  const roleOf = (agent, membership) => {
+    const project = team.pinned(agent);
+    const effective = project ? team.loadSync(project, agent).effective : team.base;
+    return { role: resolveRole(membership, effective), effective };
+  };
+  return {
+    plans,
+    /** Model-facing plan state for a teammate's own context, or undefined when its capability is not plan-first. */
+    status(agent, membership, role) {
+      if (!role?.planFirst || membership?.role !== 'teammate') return undefined;
+      const plan = plans.get(keyOf(membership));
+      return plan ? `${STATUS[plan.status]}${plan.feedback ? modelText('plan-gate.332', { 0: plan.feedback }) : ''}` : modelText('plan-gate.333', { 0: SUBMIT_TOOL });
+    },
+    /** The Lead assigned these roles in a new dispatch plan: earlier approvals do not cover the new task. */
+    reset(leadMembership, roles) {
+      for (const role of roles) plans.delete(keyOf(leadMembership, role));
+    },
+    guard(exec) {
+      const membership = ctx.agentTeams.tryMembership(exec.agent);
+      if (!ownsCapabilityTeam(ctx, exec.agent) || membership?.role !== 'teammate') return undefined;
+      let resolved;
+      try { resolved = roleOf(exec.agent, membership); } catch { return undefined; } // Routing and the access guard report config errors.
+      return planDenial(exec, resolved.role, plans.get(keyOf(membership)), resolved.effective.workflow);
+    },
+    register() {
+      ctx.effect(() => ctx.tools.guard(exec => this.guard(exec)));
+      ctx.effect(() => ctx.tools.register({ name: SUBMIT_TOOL, output,
+        description: modelText('plan-gate.334'),
+        parameters: params({ plan: { type: 'string', description: modelText('plan-gate.335') } }, ['plan']),
+        async execute(args, exec) {
+          const membership = ctx.agentTeams.membership(exec.agent);
+          if (membership.role !== 'teammate') throw new Error(modelText('plan-gate.336'));
+          const { role } = roleOf(exec.agent, membership);
+          if (!role.planFirst) throw new Error(modelText('plan-gate.337', { 0: role.displayName }));
+          const plan = text(args.plan, 8000, modelText('plan-gate.338'));
+          plans.set(keyOf(membership), { status: 'pending', plan, at: Date.now() });
+          await ctx.agentTeams.sendMessage(exec.agent, { target: 'lead', signal: exec.signal, content: [{ type: 'text',
+            text: modelText('plan-gate.339', { 0: role.displayName, 1: membership.name, 2: REVIEW_TOOL, 3: membership.name, 4: plan }) }] });
+          return modelText('plan-gate.340', { 0: STATUS.pending });
+        },
+      }));
+      ctx.effect(() => ctx.tools.register({ name: REVIEW_TOOL, output,
+        description: modelText('plan-gate.341'),
+        parameters: params({
+          role: { type: 'string', description: modelText('plan-gate.342') },
+          approve: { type: 'boolean', description: modelText('plan-gate.343') },
+          feedback: { type: 'string', description: modelText('plan-gate.344') },
+        }, ['role', 'approve']),
+        async execute(args, exec) {
+          const membership = ctx.agentTeams.membership(exec.agent);
+          if (membership.role !== 'lead') throw new Error(modelText('plan-gate.345'));
+          const role = text(args.role, 64, modelText('plan-gate.346'));
+          const plan = plans.get(keyOf(membership, role));
+          if (!plan || plan.status !== 'pending') throw new Error(modelText('plan-gate.347', { 0: role }));
+          if (args.approve !== true && args.approve !== false) throw new Error(modelText('plan-gate.348'));
+          const feedback = args.feedback === undefined || args.feedback === '' ? undefined : text(args.feedback, 2000, modelText('plan-gate.349'));
+          if (!args.approve && !feedback) throw new Error(modelText('plan-gate.350'));
+          plans.set(keyOf(membership, role), { ...plan, status: args.approve ? 'approved' : 'rejected', feedback, at: Date.now() });
+          await ctx.agentTeams.sendMessage(exec.agent, { target: role, signal: exec.signal, content: [{ type: 'text',
+            text: args.approve ? modelText('plan-gate.351', { 0: feedback ? modelText('plan-gate.352', { 0: feedback }) : '' }) : modelText('plan-gate.353', { 0: SUBMIT_TOOL, 1: feedback }) }] });
+          return modelText('plan-gate.354', { 0: args.approve ? modelText('plan-gate.355') : modelText('plan-gate.356'), 1: role });
+        },
+      }));
+    },
+  };
+}

package/preset-guard.js

@@ -0,0 +1,47 @@
+// Fail closed: native team membership alone does not identify this preset.
+export const CAPABILITY_PRESET = 'capability-team';
+// A service missing from the caller's `inject` throws on direct property access in cordis; ctx.get() does not.
+const service = (ctx, name) => { try { const direct = ctx[name]; if (direct) return direct; } catch { /* not injected */ } try { return ctx.get?.(name); } catch { return undefined; } };
+export function ownsCapabilityTeam(ctx, agent) {
+  if (!agent) return false;
+  try {
+    const membership = service(ctx, 'agentTeams')?.tryMembership(agent);
+    const owner = membership?.root ?? agent;
+    const presets = service(ctx, 'agentPresets');
+    return presets?.composedPreset(owner.ctx) === CAPABILITY_PRESET;
+  } catch { return false; }
+}
+export function capabilitySession(ctx, session) {
+  try { return ownsCapabilityTeam(ctx, ctx.agents?.get(session?.id)); }
+  catch { return false; }
+}
+export function isolatedProjection(ctx, definition) {
+  const owns = header => {
+    // DSH's own SessionHeader.agentPreset decides first. The live Agent is only a fallback for headers without it:
+    // a projection can initialise before the Agent's preset is composed, and that early "not ours" used to stick
+    // for the whole session, leaving usage, activity and report empty for real capability-team sessions.
+    const recorded = header?.agentPreset ?? header?.preset;
+    if (recorded !== undefined) return recorded === CAPABILITY_PRESET;
+    try {
+      const agent = ctx.agents?.get(header?.id ?? header?.sessionId);
+      return agent ? ownsCapabilityTeam(ctx, agent) : false;
+    } catch { return false; }
+  };
+  // +2: checkpoints written by the earlier decision are discarded and refolded from the session log.
+  return { ...definition, stateVersion: definition.stateVersion + 2,
+    init(header, inherited) {
+      const state = definition.init(header, inherited);
+      return { ...state, capabilityPreset: owns(header) };
+    },
+    apply(state, event) {
+      // A blank session may switch preset before its first turn: re-decide from the committed selection.
+      if (event?.type === 'agent-preset/selected') {
+        const owned = event.data?.agentPreset === CAPABILITY_PRESET;
+        if (owned !== state.capabilityPreset) return { ...state, capabilityPreset: owned };
+      }
+      if (!state.capabilityPreset) return state;
+      return { ...definition.apply(state, event), capabilityPreset: true };
+    },
+    wire: { ...definition.wire, view: state => definition.wire.view(state.capabilityPreset ? state : definition.init()) },
+  };
+}

package/request-evidence.js

@@ -0,0 +1,41 @@
+import { m as modelText } from './i18n.js';
+// Extract only recorded model identities, never prompt/content/replayState.
+// Request headers prove configuration admission, not successful provider completion.
+import { foldUsage } from './usage.js';
+export function requestEvidence(snapshot, limit = 30) {
+  const inherited = snapshot.inheritedEventCount ?? 0;
+  const result = [];
+  for (let i = snapshot.events.length - 1; i >= inherited && result.length < limit; i--) {
+    const event = snapshot.events[i];
+    let source, evidence;
+    if (event.type === 'request/header') { source = event.data?.header?.config; evidence = 'request-header'; }
+    else if (event.type === 'assistant/message') { source = event.data?.message?.source; evidence = 'assistant-message'; }
+    if (typeof source?.provider !== 'string' || typeof source?.model !== 'string') continue;
+    result.push({ seq: event.seq, time: event.time, provider: source.provider, model: source.model, evidence,
+      ...(event.data?.interrupted ? { interrupted: true } : {}) });
+  }
+  return result;
+}
+export async function readTeamEvidence(query, teams, agent) {
+  let members;
+  try { members = teams ? teams.listMembers(agent) : [{ id: agent.id, name: 'lead' }]; }
+  catch (error) {
+    return [{ sessionId: agent.id, name: 'lead', ...await readRequestEvidence(query, agent.id),
+      unavailable: modelText('request-evidence.357', { 0: error.message ?? error }) }];
+  }
+  const result = [];
+  // Deliberately sequential: bound peak log memory to one member at a time.
+  for (const member of members) {
+    result.push({ sessionId: member.id, name: member.name, inheritedModel: member.model ?? null,
+      ...await readRequestEvidence(query, member.id) });
+  }
+  return result;
+}
+export async function readRequestEvidence(query, sessionId) {
+  if (!query) return { records: [], unavailable: modelText('request-evidence.358') };
+  try {
+    const snapshot = await query.readSession(sessionId);
+    return { records: requestEvidence(snapshot), usage: foldUsage(snapshot) };
+  }
+  catch (error) { return { records: [], unavailable: String(error.message ?? error) }; }
+}

package/roles.js

@@ -0,0 +1,69 @@
+import { m as modelText, roleText } from './i18n.js';
+import { allocatedRequest } from './allocation.js';
+import { followUserChoice, leadRequest } from './lead-route.js';
+import { budgetDenial, sessionUsage } from './usage.js';
+import { createLongContext, promptTokens } from './long-context.js';
+import { ensurePreset } from './access.js';
+import { bindRuntime } from './runtime-observability.js';
+import { FILE_LIMITS, fileLimitRules } from './file-limits.js';
+import { TOKEN_RULES, tokenRuleText } from './token-discipline.js';
+// `allowed` is the free list resolved from OpenCode's catalog (opencode.js); nothing is fixed here.
+export function freeArgs(prompt, model, allowed = []) {
+  if (typeof model !== 'string' || !allowed.includes(model)) throw new Error(modelText('roles.359'));
+  if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 16000) throw new Error(modelText('roles.360'));
+  return ['run', '--format', 'json', '--model', model, '--', prompt];
+}
+// Static rules hold no role names, models or tiers: those come from the per-Agent team context.
+export const policy = roleText('roles.361', { 0: fileLimitRules(FILE_LIMITS), 1: tokenRuleText(TOKEN_RULES) });
+/**
+ * Route every model request by the native Team identity.
+ * The loop re-runs agent/request for each retry, so the failover state picks the attempt's route.
+ */
+export function apply(ctx, team, failover, observability, taskControl) {
+  const installed = new WeakSet();
+  const installPolicy = agent => {
+    if (!team.owns(agent) || installed.has(agent)) return;
+    installed.add(agent);
+    agent.ctx.systemPrompt.context({ name: 'capability-team:policy', order: 95, text: () => team.owns(agent) ? policy : '' });
+  };
+  ctx.on('agent/created', ({ agent }) => installPolicy(agent));
+  for (const agent of ctx.agents?.list?.() ?? []) installPolicy(agent);
+  const longContext = createLongContext();
+  const hadOverride = new WeakSet();
+  ctx.on('agent/request', async ({ agent, turn, step }, next) => {
+    const previous = await next();
+    if (!team.owns(agent)) return previous;
+    const resolved = await team.resolve(agent);
+    const lead = ctx.agentTeams?.tryMembership?.(agent)?.role === 'lead';
+    const { leadContext, ...configuredRole } = resolved;
+    // The Lead uses the model the user picked in the conversation; teammates are routed strictly by role.
+    const role = lead ? followUserChoice(configuredRole, previous, leadContext) : configuredRole;
+    if (role.userChoiceRejected) ctx.logger?.warn?.(modelText('roles.362', { 0: role.userChoiceRejected }));
+    // Fail closed: silently inheriting the Lead model defeats capability tiers and hides misconfiguration.
+    if (role.unassigned) throw new Error(modelText('roles.363', { 0: role.displayName ?? role.id, 1: role.capability }));
+    // DSH's own sandbox preset for read-only roles; re-checked every request so config edits take effect.
+    ensurePreset(ctx.get?.('permissionPresets'), agent.session, role.access, message => ctx.logger?.warn?.(`capability-team: ${message}`));
+    const projections = ctx.get?.('sessionProjections');
+    const overBudget = budgetDenial(role, sessionUsage(projections, agent.session));
+    if (overBudget) throw new Error(overBudget);
+    const controlled = taskControl ? await taskControl.route(agent, role) : role;
+    if (hadOverride.has(agent) && !controlled.taskLeaseSignature) { longContext.reset(agent.session); hadOverride.delete(agent); }
+    if (controlled.taskLeaseSignature) hadOverride.add(agent);
+    const routed = controlled.taskLeaseSignature ? controlled : longContext.apply(agent.session, controlled, promptTokens(projections, agent.session));
+    // Always explicit: the loop pins the last logged header, so the primary must be restored by name.
+    const selected = failover.route(agent, turn, step, routed);
+    if (observability) {
+      try {
+        bindRuntime(agent, observability, ctx.agentTeams);
+        observability.request(agent, { turn, step, role, routed, selected });
+      } catch { /* telemetry must never change model selection */ }
+    }
+    return (lead && leadRequest(previous, selected)) || allocatedRequest(previous, selected);
+  });
+  ctx.on('agent/request-error', async ({ agent, failure, signal }, next) => {
+    const downstream = await next(); // DSH provider retry policy keeps priority.
+    if (team.owns(agent)) { try { observability?.failure(agent, failure); } catch { /* read-only telemetry */ } }
+    if (downstream?.kind === 'retry' || !team.owns(agent)) return downstream;
+    return (await failover.recover(agent, failure, signal)) ? { kind: 'retry' } : undefined;
+  });
+}

package/roster-defaults.js

@@ -0,0 +1,70 @@
+import { roleText, m as modelText } from './i18n.js';
+// Built-in role rosters. The neutral roster is the default; "three-kingdoms" is an optional skin applied
+// per project through capability_team_import { theme }. Projects saved before 4.0 keep their hero roster.
+const isMap = v => !!v && typeof v === 'object' && !Array.isArray(v);
+const frozen = roles => Object.freeze(Object.fromEntries(Object.entries(roles).map(([id, r]) => [id, Object.freeze(r)])));
+/** Neutral default roster (English display names; the Web client localizes untouched defaults). */
+export const DEFAULT_ROLES = frozen({
+  lead: { displayName: 'Lead', capability: 'orchestrator' },
+  architect: { displayName: 'Architect', capability: 'technical-director' },
+  backend: { displayName: 'Backend', capability: 'backend' },
+  frontend: { displayName: 'Frontend', capability: 'frontend' },
+  researcher: { displayName: 'Researcher', capability: 'research' },
+  writer: { displayName: 'Writer', capability: 'writer' },
+  qa: { displayName: 'QA', capability: 'qa' },
+});
+/** The pre-4.0 default roster, kept as the optional "three-kingdoms" theme. */
+export const THREE_KINGDOMS_ROLES = frozen({
+  lead: { displayName: roleText('roster-defaults.364'), capability: 'orchestrator' },
+  'zhuge-liang': { displayName: roleText('roster-defaults.365'), capability: 'technical-director' },
+  'lv-bu': { displayName: roleText('roster-defaults.366'), capability: 'backend' },
+  'diao-chan': { displayName: roleText('roster-defaults.367'), capability: 'frontend' },
+  'zhao-yun': { displayName: roleText('roster-defaults.368'), capability: 'research' },
+  'chen-lin': { displayName: roleText('roster-defaults.369'), capability: 'writer' },
+  'zhou-yu': { displayName: roleText('roster-defaults.370'), capability: 'qa' },
+});
+export const ROLE_THEMES = Object.freeze({ default: DEFAULT_ROLES, 'three-kingdoms': THREE_KINGDOMS_ROLES });
+/** Hero id → neutral id with the same capability; lets members spawned under the old roster keep routing. */
+export const LEGACY_ROLE_ALIASES = Object.freeze({ 'zhuge-liang': 'architect', 'lv-bu': 'backend', 'diao-chan': 'frontend', 'zhao-yun': 'researcher', 'chen-lin': 'writer', 'zhou-yu': 'qa' });
+const sameRole = (a, b) => isMap(a) && isMap(b) && a.displayName === b.displayName && a.capability === b.capability && a.description === b.description;
+/** Stored-override marker written by 4.0+: such files are never read against the old hero default. */
+export const ROSTER_MARK = 2;
+/**
+ * True for overrides saved before 4.0 against the hero default: no marker (every 4.0+ save writes one), and a hero id
+ * the base lacks is stored, whether as a partial rename, a deletion (null) or a complete role from a 3.x template.
+ * Such a file was written on top of the hero roster, so mixing it into the neutral default would duplicate roles.
+ */
+export function isLegacyRoster(baseRoles = {}, overrides = {}) {
+  if (overrides.roster === ROSTER_MARK) return false;
+  return Object.keys(overrides.roles ?? {}).some(id => Object.hasOwn(LEGACY_ROLE_ALIASES, id) && !Object.hasOwn(baseRoles, id));
+}
+/** Base roles for one project's stored overrides: a pre-4.0 save keeps the hero roster (neutral defaults it never saw are dropped). */
+export function rosterBase(baseRoles = {}, overrides = {}) {
+  if (!isLegacyRoster(baseRoles, overrides)) return baseRoles;
+  const kept = Object.entries(baseRoles).filter(([id, r]) => !(Object.hasOwn(DEFAULT_ROLES, id) && sameRole(r, DEFAULT_ROLES[id])));
+  return { ...Object.fromEntries(kept), ...THREE_KINGDOMS_ROLES };
+}
+/**
+ * Overrides to store after a save: marked as 4.0+. A legacy project's roster is written out explicitly on its first
+ * save (base-only roles stored as null), so later loads no longer depend on guessing.
+ */
+export function pinRoster(next, previous, baseRoles = {}) {
+  if (!isLegacyRoster(baseRoles, previous)) return { ...next, roster: ROSTER_MARK };
+  const roles = Object.fromEntries(Object.keys(baseRoles).map(id => [id, null]));
+  for (const [id, r] of Object.entries(rosterBase(baseRoles, previous))) roles[id] = { ...r };
+  for (const [id, r] of Object.entries(next.roles ?? {})) roles[id] = r === null ? null : isMap(r) && isMap(roles[id]) ? { ...roles[id], ...r } : r;
+  return { ...next, roles, roster: ROSTER_MARK };
+}
+/** Role id a member name resolves to when the roster lacks it: a legacy hero name maps to its neutral role. */
+export function legacyRoleId(name, roles) {
+  const alias = LEGACY_ROLE_ALIASES[name];
+  return alias && !Object.hasOwn(roles, name) && Object.hasOwn(roles, alias) ? alias : undefined;
+}
+/** Save patch that replaces the project's roster with a built-in theme; other roles are removed, per-role descriptions kept. */
+export function themePatch(theme, current) {
+  const roles = Object.hasOwn(ROLE_THEMES, theme) ? ROLE_THEMES[theme] : undefined;
+  if (!roles) throw new Error(modelText('roster-defaults.371', { 0: theme, 1: Object.keys(ROLE_THEMES).join(' / ') }));
+  const patch = Object.fromEntries(Object.entries(roles).map(([id, r]) => [id, { ...r }]));
+  for (const id of Object.keys(current.roles ?? {})) if (!Object.hasOwn(patch, id)) patch[id] = false;
+  return { roles: patch };
+}

package/route-health.js

@@ -0,0 +1,39 @@
+// Route failures that outlive a DSH restart. The failover layer keeps cooldowns in memory, so after a restart
+// a route with a dead key looked healthy again and could even be preselected as a habit. Failures are kept
+// here: credential errors (the key is wrong until someone fixes it) for a day, other failures for an hour.
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+export const CREDENTIAL_CODES = new Set(['AUTH', 'INVALID_CREDENTIAL', 'MISSING_CREDENTIAL']);
+export const KEEP_MS = { credential: 24 * 3600_000, other: 3600_000 };
+/** Whether a failure means the route's key is wrong or missing (it stays bad until someone fixes it). */
+export const isCredential = (code, status) => CREDENTIAL_CODES.has(code) || status === 401 || status === 403;
+export function createRouteHealth(root, { now = Date.now } = {}) {
+  const path = join(root, 'route-health.json');
+  let data;
+  const load = () => {
+    if (data) return data;
+    try { data = JSON.parse(readFileSync(path, 'utf8')); } catch { data = {}; }
+    return data;
+  };
+  const save = () => {
+    try { mkdirSync(root, { recursive: true }); const temp = `${path}.${process.pid}.tmp`; writeFileSync(temp, JSON.stringify(data)); renameSync(temp, path); } catch { /* best effort */ }
+  };
+  const alive = (entry, at) => at - entry.lastFailureAt < (entry.credential ? KEEP_MS.credential : KEEP_MS.other);
+  return {
+    /** Failover telemetry: remember each cooldown with its error class. */
+    record(event) {
+      if (event?.kind !== 'cooldown' || !event.route) return;
+      const key = `${event.route.provider}/${event.route.model}`;
+      load()[key] = { strikes: event.strikes ?? 1, lastFailureAt: now(), code: event.code ?? null, credential: isCredential(event.code, event.status) };
+      for (const [k, v] of Object.entries(data)) if (!alive(v, now())) delete data[k];
+      save();
+    },
+    /** Recent failures, in the same shape as failover.health(). */
+    recent() {
+      const at = now();
+      return Object.fromEntries(Object.entries(load()).filter(([, v]) => alive(v, at)).map(([k, v]) => [k, { strikes: v.strikes, lastFailureAt: v.lastFailureAt, cooling: false, credential: v.credential }]));
+    },
+  };
+}
+/** Persisted failures merged with the live failover state (live state wins). */
+export const mergeHealth = (persisted, live) => ({ ...persisted, ...live });

package/runtime-observability.js

@@ -0,0 +1,78 @@
+// Ephemeral routing telemetry: no prompt/error text and no persisted session events.
+import { randomUUID } from 'node:crypto';
+import { safeId, safeTime } from './activity-summary.js';
+import { taskControlSnapshot } from './member-task-control.js';
+const routeOf = r => r && typeof r.provider === 'string' && r.provider.length <= 128 && typeof r.model === 'string' && r.model.length <= 512 ? { provider: r.provider, model: r.model } : null;
+const same = (a, b) => a && b && a.provider === b.provider && a.model === b.model;
+const codeOf = c => safeId(c, 80);
+const statusOf = s => Number.isInteger(s) && s >= 100 && s <= 599 ? s : null;
+export function createRuntimeObservability({ now = Date.now, epoch = randomUUID() } = {}) {
+  const since = safeTime(now()) ?? 0;
+  const members = new Map(), listeners = new Set(), sharedCooling = new Map(); let revision = 0;
+  const changed = () => { revision += 1; for (const listener of listeners) { try { listener(); } catch { /* observation must not affect routing */ } } };
+  const get = agent => {
+    const id = safeId(agent?.id); if (!id) return null;
+    if (!members.has(id)) {
+      if (members.size >= 256) members.delete(members.keys().next().value);
+      members.set(id, { sessionId: id, candidates: [], cooling: [], switches: [], counters: { requestFailures: 0, pluginRetries: 0, failoverSwitches: 0, longContextSwitches: 0 }, attempt: 0, turn: null, step: null, active: null, lc: false, truncated: false });
+    }
+    return members.get(id);
+  };
+  const record = (m, from, to, reason, detail = {}) => {
+    if (!from || !to || same(from, to)) return;
+    const at = safeTime(now()) ?? 0;
+    m.switches.unshift({ id: `${epoch}:${revision + 1}:${m.sessionId}`, at, turn: m.turn, step: m.step, attempt: m.attempt, from, to, reason, code: codeOf(detail.code), status: statusOf(detail.status) });
+    if (m.switches.length > 16) { m.switches.length = 16; m.truncated = true; }
+    if (reason === 'failover' || reason === 'long-context') m.counters[reason === 'failover' ? 'failoverSwitches' : 'longContextSwitches'] += 1;
+  };
+  return {
+    epoch,
+    notifyTaskControl() { changed(); },
+    onChanged(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    request(agent, { turn, step, role, routed, selected }) {
+      const m = get(agent); if (!m) return;
+      const newStep = m.turn !== turn || m.step !== step;
+      m.attempt = !newStep ? m.attempt + 1 : 1;
+      m.turn = Number.isSafeInteger(turn) ? turn : null; m.step = Number.isSafeInteger(step) ? step : null;
+      m.candidates = [role, ...(role?.fallbacks ?? []), ...(role?.longContext ? [role.longContext] : [])].map(routeOf).filter(Boolean).slice(0, 32);
+      const active = routeOf(selected), lc = !!routed.longContextActive;
+      if (m.active && m.override !== (routed.taskLeaseSignature ?? null)) record(m, m.active, active, routed.taskLeaseSignature ? 'override' : 'override-expired');
+      m.override = routed.taskLeaseSignature ?? null;
+      if (m.active && !routed.taskLeaseSignature && lc !== m.lc) record(m, m.active, routeOf(routed), 'long-context');
+      const primary = routeOf(routed);
+      if (primary && active && !same(primary, active)) {
+        // recover already recorded a switch in this attempt; a new step skipping a cooled route has not.
+        if (m.active && newStep && (!m.pendingSwitch || !same(m.pendingSwitch, active))) record(m, primary, active, 'failover', [...sharedCooling.values()].find(c => same(c.route, primary)));
+      }
+      m.pendingSwitch = null; m.active = active; m.lc = lc; changed();
+    },
+    failure(agent, failure) { const m = get(agent); if (!m) return; m.counters.requestFailures += 1; changed(); },
+    telemetry(event) {
+      const m = get(event.agent); if (!m) return;
+      if (event.kind === 'retry') m.counters.pluginRetries += 1;
+      if (event.kind === 'cooldown') {
+        const route = routeOf(event.route); if (!route) return;
+        const cooldown = { route, code: codeOf(event.code), status: statusOf(event.status), until: safeTime(event.until), attempt: m.attempt };
+        // Shared cooldown is filtered by each member's confirmed candidates at snapshot time.
+        sharedCooling.set(JSON.stringify(route), cooldown);
+        if (sharedCooling.size > 256) sharedCooling.delete(sharedCooling.keys().next().value);
+      }
+      if (event.kind === 'switch') { const to = routeOf(event.to); record(m, routeOf(event.from), to, 'failover', event); m.pendingSwitch = to; }
+      changed();
+    },
+    snapshot(leadSessionId, roster) {
+      const result = [];
+      for (const member of roster.slice(0, 64)) {
+        const m = members.get(member.id);
+        const candidates = m?.candidates ?? [];
+        const cooling = [...sharedCooling.values()].filter(c => c.until > now() && candidates.some(r => same(c.route, r)));
+        result.push({ sessionId: member.id, cooling: cooling.slice(0, 16).map(c => ({ ...c, route: { ...c.route } })), switches: (m?.switches ?? []).map(s => ({ ...s, from: { ...s.from }, to: { ...s.to } })), counters: { ...(m?.counters ?? { requestFailures: 0, pluginRetries: 0, failoverSwitches: 0, longContextSwitches: 0 }) }, truncated: !!m?.truncated || cooling.length > 16 });
+      }
+      return { schemaVersion: 1, leadSessionId, epoch, revision, generatedAt: safeTime(now()) ?? 0, coverage: { mode: 'runtime', since }, members: result, taskControl: taskControlSnapshot(leadSessionId) };
+    },
+  };
+}
+// Kept outside session checkpoints. Bound to the exact live Agent identity.
+const runtimeBindings = new WeakMap();
+export function bindRuntime(agent, runtime, teams) { runtimeBindings.set(agent, { runtime, teams }); }
+export function runtimeBinding(agent) { return runtimeBindings.get(agent); }

package/runtime-view.js

@@ -0,0 +1,21 @@
+import { m as modelText } from './i18n.js';
+// Shared read-only bridge. Keys are Agent objects, never guessed from a project or display name.
+const readers = new WeakMap();
+const writers = new WeakMap();
+export function registerPolicyWriter(agent, save) {
+  writers.set(agent, save);
+  return () => { if (writers.get(agent) === save) writers.delete(agent); };
+}
+export async function saveTeamPolicy(agent, routes, revision) {
+  const save = writers.get(agent);
+  if (!save) throw new Error(modelText('runtime-view.372'));
+  return save(routes, revision);
+}
+export function registerTeamReader(agent, read) {
+  readers.set(agent, read);
+  return () => { if (readers.get(agent) === read) readers.delete(agent); };
+}
+export async function readTeamSnapshot(agent) {
+  const read = readers.get(agent);
+  return read ? await read() : null;
+}

package/scripts/memory-cli.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// Bridge from the team memory hub to outside coding agents (e.g. a Claude Code UserPromptSubmit hook).
+// Recall sees only project and global pitfalls/decisions: teammates' role-private reports and session memories
+// never leave the hub, nothing is embedded or sent over the network, and recall never updates hit counters.
+// Writes are explicit, local, redacted, and limited to project/global scope so every team role can recall them.
+import { resolve } from 'node:path';
+import { m } from '../i18n.js';
+import { pathToFileURL } from 'node:url';
+import { createMemoryStore, tokenize } from '../memory-store.js';
+import { redactSecrets } from '../memory-redact.js';
+import { defaultRoot, projectRoot } from '../theme.js';
+
+export const RECALL_KINDS = ['pitfall', 'decision'];
+export const RECALL_ROLE = 'external-agent'; // never a team role id, so role-scoped memories stay hidden
+export const RECALL_HEADER = m('memory.recallHeader');
+export const RECALL_DEFAULTS = { k: 6, maxChars: 2400, maxQuery: 2000, minShared: 2 };
+
+export const WRITE_KINDS = ['pitfall', 'decision', 'note'];
+export const WRITE_SCOPES = ['project', 'global'];
+export const WRITE_LIMITS = { minText: 4, maxText: 2000, maxKey: 120, maxTags: 10, maxTag: 64 };
+
+const meaningful = text => new Set(tokenize(text).filter(t => t.length >= 2));
+
+/** Store one memory written on purpose by an outside agent; returns what was saved, never the raw input. */
+export async function writeMemory({ kind, text, scope = 'project', key, tags = [], cwd, root = defaultRoot(), now = Date.now }) {
+  if (!WRITE_KINDS.includes(kind)) throw new Error(`kind must be one of ${WRITE_KINDS.join(', ')}`);
+  if (!WRITE_SCOPES.includes(scope)) throw new Error(`scope must be one of ${WRITE_SCOPES.join(', ')}`);
+  const body = redactSecrets(String(text ?? '').replace(/\s+/g, ' ').trim());
+  if (body.length < WRITE_LIMITS.minText) throw new Error('text is too short');
+  if (body.length > WRITE_LIMITS.maxText) throw new Error(`text exceeds ${WRITE_LIMITS.maxText} characters`);
+  const topic = key == null || key === '' ? null : redactSecrets(String(key).trim());
+  if (topic !== null && (!topic || topic.length > WRITE_LIMITS.maxKey)) throw new Error(`key must be 1-${WRITE_LIMITS.maxKey} characters`);
+  const labels = [...new Set(tags.map(t => redactSecrets(String(t).trim())).filter(Boolean))];
+  if (labels.length > WRITE_LIMITS.maxTags || labels.some(t => t.length > WRITE_LIMITS.maxTag)) throw new Error(`at most ${WRITE_LIMITS.maxTags} tags of ${WRITE_LIMITS.maxTag} characters`);
+  let target = { kind: 'global' };
+  if (scope === 'project') {
+    if (!cwd) throw new Error('project scope needs a working directory');
+    target = { kind: 'project', project: projectRoot(cwd, root) };
+  }
+  const store = createMemoryStore(root, { now });
+  const saved = await store.write({ scope: target, kind, text: body, tags: labels, key: topic, source: { member: RECALL_ROLE, at: now() } });
+  return { saved: true, id: saved.memory.id, kind, scope, merged: saved.merged, superseded: saved.superseded.length, sync: 'local-only' };
+}
+
+/** Ranked memories for `query`, keeping only those sharing at least `minShared` multi-char tokens with it. */
+export async function recall({ query, cwd, root = defaultRoot(), k = RECALL_DEFAULTS.k, minShared = RECALL_DEFAULTS.minShared }) {
+  const text = redactSecrets(String(query ?? '').replace(/\s+/g, ' ').trim().slice(0, RECALL_DEFAULTS.maxQuery));
+  if (!text) return [];
+  const project = cwd ? projectRoot(cwd, root) : null;
+  const store = createMemoryStore(root);
+  const ranked = await store.search({ project, role: RECALL_ROLE, query: text, k: k * 3, kinds: RECALL_KINDS });
+  const wanted = meaningful(text);
+  return ranked.filter(({ memory }) => {
+    if (memory.scope.kind !== 'project' && memory.scope.kind !== 'global') return false;
+    if (minShared <= 0) return true;
+    let shared = 0;
+    for (const t of meaningful(memory.text)) if (wanted.has(t) && ++shared >= minShared) return true;
+    return false;
+  }).slice(0, k);
+}
+
+/** Injection block within `maxChars`, header included; empty when nothing fits. */
+export function formatRecall(results, maxChars = RECALL_DEFAULTS.maxChars) {
+  const lines = []; let used = RECALL_HEADER.length;
+  for (const { memory: m } of results) {
+    const line = `- [${m.kind}${m.scope.kind === 'global' ? '·global' : ''}] ${redactSecrets(m.text)}`;
+    if (used + 1 + line.length > maxChars) continue;
+    used += 1 + line.length; lines.push(line);
+  }
+  return lines.length ? [RECALL_HEADER, ...lines].join('\n') : '';
+}
+
+/** Hook payload (Claude Code UserPromptSubmit JSON on stdin) → hook output JSON string, or '' to add nothing. */
+export async function hookOutput(payload, options = {}) {
+  const prompt = payload?.prompt;
+  if (typeof prompt !== 'string' || !prompt.trim()) return '';
+  const block = formatRecall(await recall({ query: prompt, cwd: payload.cwd || process.cwd(), ...options }), options.maxChars);
+  if (!block) return '';
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block } });
+}
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (['--cwd', '--k', '--kind', '--scope', '--key', '--tags'].includes(a)) out[a.slice(2)] = argv[++i];
+    else out._.push(a);
+  }
+  return out;
+}
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === 'hook') {
+    // A recall failure must never block the user's prompt: swallow everything and add no context.
+    try { const out = await hookOutput(JSON.parse(await readStdin() || '{}')); if (out) process.stdout.write(out); }
+    catch { /* degrade silently */ }
+    return 0;
+  }
+  if (command === 'search') {
+    const args = parseArgs(rest);
+    const k = Math.min(20, Math.max(1, Number.parseInt(args.k ?? RECALL_DEFAULTS.k, 10) || RECALL_DEFAULTS.k));
+    const results = await recall({ query: args._.join(' '), cwd: args.cwd ?? process.cwd(), k });
+    process.stdout.write(JSON.stringify(results.map(({ memory: m, score }) => ({
+      id: m.id, kind: m.kind, scope: m.scope.kind, tags: m.tags, score: Number(score.toFixed(5)), text: redactSecrets(m.text),
+    })), null, 2) + '\n');
+    return 0;
+  }
+  if (command === 'write') {
+    // Text comes from the arguments, or from stdin when none are given (safer for long or quoted text).
+    const args = parseArgs(rest);
+    const text = args._.length ? args._.join(' ') : await readStdin();
+    try {
+      const result = await writeMemory({ kind: args.kind, scope: args.scope ?? 'project', key: args.key, tags: args.tags ? args.tags.split(',') : [], text, cwd: args.cwd ?? process.cwd() });
+      process.stdout.write(JSON.stringify(result) + '\n');
+      return 0;
+    } catch (error) {
+      process.stderr.write(JSON.stringify({ saved: false, error: error.message }) + '\n');
+      return 1;
+    }
+  }
+  process.stderr.write([
+    'usage: memory-cli.mjs hook < payload.json',
+    '       memory-cli.mjs search <query> [--cwd dir] [--k n]',
+    '       memory-cli.mjs write --kind pitfall|decision|note [--scope project|global] [--key topic] [--tags a,b] [--cwd dir] [text | < text]',
+  ].join('\n') + '\n');
+  return 2;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  process.exitCode = await main(process.argv.slice(2));
+}