fuli-context 0.20.0-beta.2 → 0.20.0-beta.3

package/src/external-knowledge/connectors/feishu.js

@@ -1,3 +1,8 @@
+import { nonEmptyText, requiredString, uniqueTextArray } from '../../validation/values.js';
+import { onlineUrl, timeoutMilliseconds } from './response-values.js';
+
+const HTTPS_ONLY = Object.freeze(['https:']);
+
 const API_ROOTS = Object.freeze({
   cn: 'https://open.feishu.cn',
   global: 'https://open.larksuite.com'
@@ -217,7 +222,7 @@ function feishuRequester(fetchImpl, tokenCache) {
         'Content-Type': 'application/json; charset=utf-8'
       },
       ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs))
+      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs, 'Feishu timeoutMs'))
     });
     const payload = await response.json().catch(() => ({}));
     if (!response.ok || payload.code !== 0) {
@@ -243,7 +248,7 @@ async function accessToken(context, fetchImpl, tokenCache) {
       method: 'POST',
       headers: { 'Content-Type': 'application/json; charset=utf-8' },
       body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
-      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs))
+      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs, 'Feishu timeoutMs'))
     }
   );
   const payload = await response.json().catch(() => ({}));
@@ -298,9 +303,9 @@ async function searchWiki(context, request, source, query, pageToken, limit = 50
 }
 
 function feishuSource(source, { allowEmpty = false } = {}) {
-  const nodeTokens = idArray(source?.nodeTokens, 'Feishu nodeTokens');
-  const spaceId = optionalString(source?.spaceId);
-  const rootNodeToken = optionalString(source?.rootNodeToken);
+  const nodeTokens = uniqueTextArray(source?.nodeTokens, 'Feishu nodeTokens');
+  const spaceId = nonEmptyText(source?.spaceId);
+  const rootNodeToken = nonEmptyText(source?.rootNodeToken);
   if (!allowEmpty && !nodeTokens.length && !spaceId) {
     throw new TypeError('Feishu source requires nodeTokens or spaceId');
   }
@@ -315,7 +320,7 @@ function nodeSummary(node) {
     id: node.node_token ?? node.node_id,
     title: node.title ?? node.node_token ?? node.node_id,
     type: normalizedObjectType(node.obj_type),
-    url: onlineUrl(node.url),
+    url: onlineUrl(node.url, HTTPS_ONLY),
     updatedAt: epochDateTime(node.obj_edit_time),
     metadata: {
       spaceId: node.space_id ?? null,
@@ -326,9 +331,9 @@ function nodeSummary(node) {
 }
 
 function nodeUrl(node, source) {
-  const direct = onlineUrl(node.url);
+  const direct = onlineUrl(node.url, HTTPS_ONLY);
   if (direct) return direct;
-  const base = onlineUrl(source?.webBaseUrl);
+  const base = onlineUrl(source?.webBaseUrl, HTTPS_ONLY);
   const token = node.node_token ?? node.node_id;
   return base && token ? new URL(`/wiki/${encodeURIComponent(token)}`, base).toString() : null;
 }
@@ -403,14 +408,6 @@ function environmentValue(env, name, label) {
   return value;
 }
 
-function idArray(value, label) {
-  if (value === undefined || value === null) return [];
-  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) {
-    throw new TypeError(`${label} must be an array of nonempty strings`);
-  }
-  return [...new Set(value.map((item) => item.trim()))];
-}
-
 function rawContentInterval(value) {
   if (value === undefined || value === null) return 210;
   if (!Number.isInteger(value) || value < 0 || value > 10_000) {
@@ -419,14 +416,6 @@ function rawContentInterval(value) {
   return value;
 }
 
-function timeoutMilliseconds(value) {
-  if (value === undefined || value === null) return 30_000;
-  if (!Number.isInteger(value) || value < 1_000 || value > 120_000) {
-    throw new TypeError('Feishu timeoutMs must be between 1000 and 120000');
-  }
-  return value;
-}
-
 function pageSize(value) {
   if (value === undefined || value === null) return 50;
   if (!Number.isInteger(value) || value <= 0) throw new TypeError('Feishu page size is invalid');
@@ -439,23 +428,3 @@ function epochDateTime(value) {
     ? new Date(seconds * 1_000).toISOString()
     : null;
 }
-
-function onlineUrl(value) {
-  if (typeof value !== 'string') return null;
-  try {
-    const url = new URL(value);
-    return url.protocol === 'https:' && !url.username && !url.password ? url.toString() : null;
-  } catch {
-    return null;
-  }
-}
-
-function optionalString(value) {
-  return typeof value === 'string' && value.trim() ? value.trim() : null;
-}
-
-function requiredString(value, label) {
-  const normalized = optionalString(value);
-  if (!normalized) throw new TypeError(`${label} is required`);
-  return normalized;
-}

package/src/external-knowledge/connectors/mcp.js

@@ -4,6 +4,8 @@ import {
   getDefaultEnvironment
 } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { requiredString } from '../../validation/values.js';
+import { dateTimeOrNull, onlineUrl } from './response-values.js';
 
 const LOCAL_CURSOR_PREFIX = 'fuli-mcp-v1:';
 
@@ -389,23 +391,6 @@ function mcpHttpUrl(value) {
   return url;
 }
 
-function onlineUrl(value) {
-  if (typeof value !== 'string') return null;
-  try {
-    const url = new URL(value);
-    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
-      ? url.toString()
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function dateTimeOrNull(value) {
-  if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) return null;
-  return new Date(value).toISOString();
-}
-
 function plainObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
 }
@@ -418,11 +403,6 @@ function stringArray(value) {
   return value;
 }
 
-function requiredString(value, label) {
-  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
-  return value.trim();
-}
-
 function assertEnvironmentName(value) {
   if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value)) {
     throw new TypeError('Environment variable name is invalid');

package/src/external-knowledge/connectors/notion.js

@@ -1,3 +1,6 @@
+import { requiredString, uniqueTextArray } from '../../validation/values.js';
+import { dateTimeOrNull, jsonObject, onlineUrl, timeoutMilliseconds } from './response-values.js';
+
 const NOTION_API_ROOT = 'https://api.notion.com';
 const NOTION_API_VERSION = '2026-03-11';
 
@@ -123,7 +126,7 @@ function notionRequester(fetchImpl) {
         ...(body === undefined ? {} : { 'Content-Type': 'application/json' })
       },
       ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs))
+      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs, 'Notion timeoutMs'))
     });
     const payload = await response.json().catch(() => ({}));
     if (!response.ok) {
@@ -178,8 +181,8 @@ async function notionPageDocument(context, request, page) {
 }
 
 function notionSources(source, { allowEmpty = false } = {}) {
-  const pageIds = idArray(source?.pageIds, 'Notion pageIds');
-  const dataSourceIds = idArray(source?.dataSourceIds, 'Notion dataSourceIds');
+  const pageIds = uniqueTextArray(source?.pageIds, 'Notion pageIds');
+  const dataSourceIds = uniqueTextArray(source?.dataSourceIds, 'Notion dataSourceIds');
   const sources = [
     ...pageIds.map((id) => ({ kind: 'page', id })),
     ...dataSourceIds.map((id) => ({ kind: 'data_source', id }))
@@ -256,52 +259,8 @@ function credentialFromEnvironment(context, key, label) {
   return value;
 }
 
-function idArray(value, label) {
-  if (value === undefined || value === null) return [];
-  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) {
-    throw new TypeError(`${label} must be an array of nonempty strings`);
-  }
-  return [...new Set(value.map((item) => item.trim()))];
-}
-
 function pageSize(value) {
   if (value === undefined || value === null) return 100;
   if (!Number.isInteger(value) || value <= 0) throw new TypeError('Notion page size is invalid');
   return Math.min(value, 100);
 }
-
-function timeoutMilliseconds(value) {
-  if (value === undefined || value === null) return 30_000;
-  if (!Number.isInteger(value) || value < 1_000 || value > 120_000) {
-    throw new TypeError('Notion timeoutMs must be between 1000 and 120000');
-  }
-  return value;
-}
-
-function requiredString(value, label) {
-  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
-  return value.trim();
-}
-
-function onlineUrl(value) {
-  if (typeof value !== 'string') return null;
-  try {
-    const url = new URL(value);
-    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
-      ? url.toString()
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function dateTimeOrNull(value) {
-  if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) return null;
-  return new Date(value).toISOString();
-}
-
-function jsonObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value)
-    ? structuredClone(value)
-    : {};
-}

package/src/external-knowledge/connectors/response-values.js

@@ -0,0 +1,34 @@
+// Shared readers for values that external knowledge sources return or accept.
+
+const WEB_PROTOCOLS = Object.freeze(['http:', 'https:']);
+
+// A browsable source link without embedded credentials, otherwise null.
+export function onlineUrl(value, protocols = WEB_PROTOCOLS) {
+  if (typeof value !== 'string' || !value) return null;
+  try {
+    const url = new URL(value);
+    return protocols.includes(url.protocol) && !url.username && !url.password ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function dateTimeOrNull(value) {
+  if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) return null;
+  return new Date(value).toISOString();
+}
+
+// A detached copy of a JSON object, or an empty object for anything else.
+export function jsonObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? structuredClone(value)
+    : {};
+}
+
+export function timeoutMilliseconds(value, label, fallback = 30_000) {
+  if (value === undefined || value === null) return fallback;
+  if (!Number.isInteger(value) || value < 1_000 || value > 120_000) {
+    throw new TypeError(`${label} must be between 1000 and 120000`);
+  }
+  return value;
+}

package/src/external-knowledge/connectors/retrieval-api.js

@@ -1,4 +1,6 @@
 import { createHash } from 'node:crypto';
+import { positiveInteger, requiredString } from '../../validation/values.js';
+import { jsonObject, onlineUrl } from './response-values.js';
 
 const DEFAULT_SCORE_THRESHOLD = 0.5;
 const MAX_KNOWLEDGE_BASES = 32;
@@ -172,24 +174,6 @@ function optionalEnvironmentName(value, label) {
   return value;
 }
 
-function jsonObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value)
-    ? structuredClone(value)
-    : {};
-}
-
-function onlineUrl(value) {
-  if (!value) return null;
-  try {
-    const url = new URL(value);
-    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
-      ? url.toString()
-      : null;
-  } catch {
-    return null;
-  }
-}
-
 function dateTime(value) {
   return value && !Number.isNaN(Date.parse(value))
     ? new Date(value).toISOString()
@@ -206,17 +190,3 @@ function firstString(...values) {
   }
   return null;
 }
-
-function requiredString(value, label, maximum) {
-  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
-  const normalized = value.trim();
-  if (normalized.length > maximum) throw new TypeError(`${label} is too long`);
-  return normalized;
-}
-
-function positiveInteger(value, label, maximum) {
-  if (!Number.isInteger(value) || value <= 0 || value > maximum) {
-    throw new TypeError(`${label} must be a positive integer no greater than ${maximum}`);
-  }
-  return value;
-}

package/src/external-knowledge/document-mapping.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 
 import { detectSensitiveContent } from '../security/sensitive-content.js';
+import { requiredString } from '../validation/values.js';
 
 const MAX_CHUNK_LENGTH = 6_000;
 const MAX_EXCERPT_LENGTH = 2_048;
@@ -115,13 +116,6 @@ function shortHash(value) {
   return createHash('sha256').update(value).digest('hex').slice(0, 24);
 }
 
-function requiredString(value, label, maximum) {
-  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
-  const normalized = value.trim();
-  if (normalized.length > maximum) throw new TypeError(`${label} is too long`);
-  return normalized;
-}
-
 function optionalOnlineUrl(value) {
   if (value === undefined || value === null || value === '') return null;
   const url = new URL(value);

package/src/external-knowledge/service.js

@@ -10,6 +10,7 @@ import {
 } from './document-mapping.js';
 import { safeExternalSourceDiagnostic } from './safe-diagnostic.js';
 import { ApplicationError } from '../app/application-error.js';
+import { positiveInteger, requiredString } from '../validation/values.js';
 
 const MODES = new Set(['hybrid', 'live', 'mirror']);
 const MAX_TARGETS = 32;
@@ -780,25 +781,11 @@ function normalizedConfigurationKey(key) {
   return key.toLocaleLowerCase().replace(/[^a-z0-9]/gu, '');
 }
 
-function requiredString(value, label, maximum) {
-  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
-  const normalized = value.trim();
-  if (normalized.length > maximum) throw new TypeError(`${label} is too long`);
-  return normalized;
-}
-
 function optionalString(value, label, maximum) {
   if (value === undefined || value === null || value === '') return null;
   return requiredString(value, label, maximum);
 }
 
-function positiveInteger(value, label, maximum) {
-  if (!Number.isInteger(value) || value <= 0 || value > maximum) {
-    throw new TypeError(`${label} must be a positive integer no greater than ${maximum}`);
-  }
-  return value;
-}
-
 function isCredentialDocumentError(error) {
   return error instanceof TypeError &&
     error.message === 'Connector item contains credentials and cannot be retrieved or stored';

package/src/graphiti/agent-attention.js

@@ -1,3 +1,6 @@
+import { nativeChoiceInteraction } from '../conversations/human-interaction.js';
+import { nonEmptyText } from '../validation/values.js';
+
 const fields = {
   personalSpaceId: 'personal_space_id', personalProjectId: 'personal_project_id',
   agentId: 'agent_id', taskId: 'task_id', requestId: 'request_id',
@@ -18,9 +21,39 @@ export function attentionRecord(value) {
 
 export async function listAgentAttention(application, input) {
   const value = await application.personal.listAgentAttention(attentionInput(input));
-  return { ...value, items: value.items.map(attentionRecord) };
+  const items = value.items.map(attentionRecord);
+  return { ...attentionInteraction(items.find(item => item.status === 'open')), ...value, items };
 }
 
 export async function changeAgentAttention(application, operation, input) {
-  return attentionRecord(await application.personal.changeAgentAttention(operation, attentionInput(input)));
+  const record = attentionRecord(await application.personal.changeAgentAttention(operation, attentionInput(input)));
+  return { ...attentionInteraction(record), ...record };
+}
+
+// The console sends the chosen option and an optional note; the Provider keeps
+// them as one response text, and the requesting Agent receives both.
+export async function respondToAgentAttention(application, { choice, note, ...input }) {
+  const answer = { choice: nonEmptyText(choice), note: nonEmptyText(note) };
+  if (!answer.choice && !answer.note) throw new TypeError('An attention reply needs a choice or a note');
+  const record = await changeAgentAttention(application, 'respond', { ...input,
+    response: [answer.choice, answer.note].filter(Boolean).join('\n\n') });
+  return { ...record, delivery: await deliverAnswer(application, record, answer) };
+}
+
+// The reply is already recorded; a failed delivery leaves it readable through
+// list_agent_attention and is reported, never hidden.
+async function deliverAnswer(application, record, answer) {
+  const unavailable = { status: 'unavailable', agentId: record.agentId };
+  if (!application.roundtable) return unavailable;
+  try { return await application.roundtable.deliverAttentionReply(record, answer); }
+  catch { return unavailable; }
+}
+
+function attentionInteraction(record) {
+  if (record?.status !== 'open') return {};
+  return { human_interaction: nativeChoiceInteraction({
+    source: { kind: 'agent_attention', id: record.requestId, revision: record.revision,
+      personalSpaceId: record.personalSpaceId, personalProjectId: record.personalProjectId },
+    title: record.title, question: record.requestedAction, options: record.options
+  }) };
 }

package/src/graphiti/agent-collaboration.js

@@ -1,4 +1,6 @@
 import { verificationPreference } from './verification-preference.js';
+import { executionPlan } from './execution-mode.js';
+import { dispatchTarget, subLeadIds, reportingParent } from './project-team-hierarchy.js';
 const lower = values => (values ?? []).map(value => String(value).toLowerCase());
 // Matches Provider staffing: a nonempty assignment list overrides the profile list.
 const effective = (assignment, profile, field) => lower(assignment[field]?.length ? assignment[field] : profile?.[field]);
@@ -7,6 +9,7 @@ const verificationKinds = new Set(['test_validation', 'verification', 'code_revi
 function matchCandidates(agents, task, input) {
   const required = lower(input.requiredCapabilities);
   const workKind = String(input.workKind).toLowerCase();
+  const occupation = input.occupation ? String(input.occupation).toLowerCase() : null;
   const candidates = [];
   for (const agent of Array.isArray(agents) ? agents : []) {
     for (const assignment of agent.assignments ?? []) {
@@ -14,21 +17,27 @@ function matchCandidates(agents, task, input) {
       const capabilities = effective(assignment, agent.profile, 'capabilities');
       if (!required.every(value => capabilities.includes(value))) continue;
       const workMatch = effective(assignment, agent.profile, 'work_kinds').includes(workKind);
-      if (!workMatch && !required.length) continue;
+      // The lead assigns by occupation first; a matching occupation qualifies on its own.
+      const role = agent.occupation?.role ? String(agent.occupation.role).toLowerCase() : null;
+      const occupationMatch = Boolean(occupation) && role === occupation;
+      if (!workMatch && !occupationMatch && !required.length) continue;
       candidates.push({ agentId: agent.agent_id, name: agent.profile?.display_name || agent.profile?.name,
         projectId: assignment.personal_project_id, capabilities,
         allowedClients: agent.profile?.allowed_clients ?? [],
         clientAvailable: Boolean(agent.profile?.allowed_clients?.includes(input.sourceApplication)),
         ...(assignment.responsibility ? { responsibility: assignment.responsibility } : {}),
         requiresLoan: assignment.personal_project_id !== task.personalProjectId,
+        ...(role ? { occupation: role } : {}), occupationMatch,
         workMatch, activeTasks: agent.open_task_count ?? 0 });
     }
   }
   return candidates;
 }
 
-function nextSteps(candidate, taskContextToken, sourceLeadId, personalProjectId) {
-  const steps = { ask: { tool: 'message_agent', arguments: { to: candidate.agentId }, advisoryOnly: true,
+function nextSteps(candidate, taskContextToken, sourceLeadId, personalProjectId, hierarchy = null) {
+  const target = hierarchy && !candidate.requiresLoan
+    ? dispatchTarget(hierarchy.policy, hierarchy.coordinatorAgentId, candidate.agentId) : candidate.agentId;
+  const steps = { ask: { tool: 'message_agent', arguments: { to: target }, advisoryOnly: true,
     guidance: 'A roundtable answer is advice from a read-only session, not executed work.' } };
   if (candidate.requiresLoan) {
     steps.borrow = { tool: 'request_agent_loan', arguments: { sourceProjectId: candidate.projectId, specialistId: candidate.agentId },
@@ -36,7 +45,10 @@ function nextSteps(candidate, taskContextToken, sourceLeadId, personalProjectId)
       guidance: 'Only the destination project lead may request. The source lead approves with decide_agent_loan in its own task context before any assignment or execution.' };
   }
   steps.execute = { tool: 'coordinate_project_agent_task',
-    arguments: { taskContextToken, personalProjectId, collaboratorAgentIds: [candidate.agentId] },
+    arguments: { taskContextToken, personalProjectId, ...(hierarchy ? {
+      coordinatorAgentId: hierarchy.coordinatorAgentId, leadAgentId: target,
+      ...(target !== candidate.agentId ? { workKind: 'delegation', requiredCapabilities: [] } : {})
+    } : { collaboratorAgentIds: [candidate.agentId] }) },
     guidance: `${candidate.requiresLoan ? 'After the loan is approved, ' : ''}coordinate under the project lead with an authorized runtime; record the actual worker and result back to the lead.` };
   return steps;
 }
@@ -59,26 +71,49 @@ export async function planAgentCollaboration(application, input) {
   const separated = input.taskSize !== 'small' && !verificationOnly;
   const independent = separated && input.taskSize === 'complex' ? input.independentWork : null;
   const verification = { workKind: input.verificationWorkKind ?? 'test_validation',
+    occupation: input.verificationOccupation ?? 'testing',
     requiredCapabilities: input.verificationCapabilities ?? [] };
   const pools = { main: matchCandidates(agents, task, input),
     independent: independent ? matchCandidates(agents, task, { ...input, ...independent,
-      requiredCapabilities: independent.requiredCapabilities ?? [] }) : [],
+      requiredCapabilities: independent.requiredCapabilities ?? [], occupation: independent.occupation ?? null }) : [],
     verification: separated ? matchCandidates(agents, task, { ...input, ...verification }) : [] };
   // A loan needs the source project's lead, who itself cannot be borrowed.
   const sourceProjects = [...new Set(Object.values(pools).flat().filter(item => item.requiresLoan).map(item => item.projectId))];
   const sourceLeads = Object.fromEntries(await Promise.all(sourceProjects.map(async projectId => [projectId,
     (await application.personal.getProjectAgentCoordinationPolicy(spaceId, projectId))?.team_lead_agent_id ?? null])));
   const token = input.taskContextToken;
-  const eligible = (pool, excluded = [], available = true) => pool.filter(item => item.clientAvailable === available && !excluded.includes(item.agentId)
+  const subLeads = subLeadIds(policy);
+  const coordinatorAgentId = subLeads.has(task.projectAgentId) ? task.projectAgentId
+    : policy.team_lead_agent_id ?? task.projectAgentId;
+  const memberOwner = Boolean(policy.sub_teams?.length && task.projectAgentId !== policy.team_lead_agent_id
+    && !subLeads.has(task.projectAgentId));
+  const hierarchy = policy.sub_teams?.length ? { policy, coordinatorAgentId } : null;
+  const candidateSteps = candidate => nextSteps(candidate, token, sourceLeads[candidate.projectId], task.personalProjectId, hierarchy);
+  const dispatchable = candidate => !policy.sub_teams?.length || (memberOwner ? candidate.agentId === task.projectAgentId : candidate.requiresLoan
+    ? coordinatorAgentId === policy.team_lead_agent_id
+    : dispatchTarget(policy, coordinatorAgentId, candidate.agentId) !== null);
+  const throughLead = item => {
+    const target = hierarchy && !item.requiresLoan ? dispatchTarget(policy, coordinatorAgentId, item.agentId) : item.agentId;
+    if (target === item.agentId || !target) return item;
+    const lead = agents.find(agent => agent.agent_id === target && agent.profile?.status !== 'archived'
+      && agent.assignments?.some(assignment => assignment.status === 'active' && assignment.personal_project_id === task.personalProjectId));
+    return { ...item, clientAvailable: item.clientAvailable && Boolean(lead?.profile?.allowed_clients?.includes(input.sourceApplication)),
+      dispatchAgentId: target };
+  };
+  const eligible = (pool, excluded = [], available = true) => pool.map(throughLead).filter(item => item.clientAvailable === available && !excluded.includes(item.agentId)
+    && dispatchable(item)
+    && !(subLeads.has(item.agentId) && item.agentId === coordinatorAgentId
+      && !['planning', 'delegation', 'integration', 'reporting'].includes(input.workKind))
     && (!item.requiresLoan || (sourceLeads[item.projectId] && sourceLeads[item.projectId] !== item.agentId)))
-    .sort((a, b) => Number(a.requiresLoan) - Number(b.requiresLoan) || Number(b.workMatch) - Number(a.workMatch)
+    .sort((a, b) => Number(b.occupationMatch) - Number(a.occupationMatch)
+      || Number(a.requiresLoan) - Number(b.requiresLoan) || Number(b.workMatch) - Number(a.workMatch)
       || a.activeTasks - b.activeTasks || a.agentId.localeCompare(b.agentId));
   const authors = [...new Set([task.projectAgentId, ...(input.implementationAgentIds ?? [])])];
   const mainCandidates = eligible(pools.main, independentAcceptance ? authors : []);
   const unavailableCandidates = eligible(pools.main, independentAcceptance ? authors : [], false);
   const shown = mainCandidates.slice(0, 8).map(item => ({ ...item,
     ...(item.requiresLoan ? { sourceLeadId: sourceLeads[item.projectId] } : {}),
-    nextSteps: nextSteps(item, token, sourceLeads[item.projectId], task.personalProjectId) }));
+    nextSteps: candidateSteps(item) }));
   const preferencePrompt = verificationPreference({ executors, rules, projectId: task.personalProjectId,
     lockedExecutorIds: currentAgent.profile?.executorPolicy?.mode === 'locked' ? currentAgent.profile.executorPolicy.lockedExecutorIds : null });
   const judgmentPolicy = await application.judgment?.policy({ personalSpaceId: spaceId, personalProjectId: task.personalProjectId });
@@ -91,46 +126,59 @@ export async function planAgentCollaboration(application, input) {
   const recruit = stream => ({ tool: 'coordinate_project_agent_task',
     arguments: { taskContextToken: token, personalProjectId: task.personalProjectId,
       workKind: stream.workKind, requiredCapabilities: stream.requiredCapabilities ?? [],
-      staffingIntent: 'new_durable' },
+      staffingIntent: 'new_durable',
+      // Bole hires by the occupation the workstream asked for, not by guessing from its work kind.
+      ...(stream.occupation ? { recruitmentOccupation: { role: stream.occupation, tags: [] } } : {}) },
     requires: ['idempotencyKey', 'title', 'objective', 'routingReason', 'contextQueries'],
     coordinatorAgentId: policy.team_lead_agent_id ?? null, askBeforeRecruitment: policy.ask_before_recruitment !== false,
     guidance: 'Reuse one stable idempotencyKey for this staffing need so a retry reuses the same recruitment. When askBeforeRecruitment is true, AR only proposes a hire; confirm with the user before it is staffed. Recruiting executes nothing.' });
-  const recruitment = shown.length || unavailableCandidates.length ? null : recruit(input);
-  const coordinatorAgentId = policy.team_lead_agent_id ?? task.projectAgentId;
+  const subTeamCoordinator = subLeads.has(coordinatorAgentId) || memberOwner;
+  const recruitment = shown.length || unavailableCandidates.length || subTeamCoordinator ? null : recruit(input);
   function workstream(id, spec, candidate, dependsOn = [], unavailable = []) {
-    const continuing = id === 'main' && !independentAcceptance && candidate?.agentId === task.projectAgentId;
-    const blocked = !candidate && unavailable.length > 0;
+    const target = candidate && !candidate.requiresLoan ? dispatchTarget(policy, coordinatorAgentId, candidate.agentId) : candidate?.agentId;
+    const viaSubLead = Boolean(candidate && target !== coordinatorAgentId && subLeads.has(target));
+    const continuing = id === 'main' && !independentAcceptance && target === task.projectAgentId;
+    const scopeGap = !candidate && !unavailable.length && subTeamCoordinator;
+    const blocked = !candidate && (unavailable.length > 0 || scopeGap);
     const dispatch = continuing || blocked ? null : candidate ? { tool: 'coordinate_project_agent_task',
       arguments: { taskContextToken: token, workKind: spec.workKind, requiredCapabilities: spec.requiredCapabilities ?? [],
-        leadAgentId: candidate.agentId },
+        leadAgentId: target, ...(viaSubLead ? { workKind: 'delegation', requiredCapabilities: [] } : {}) },
       requires: ['idempotencyKey', 'title', 'objective', 'contextQueries'] } : recruit(spec);
     if (dispatch) Object.assign(dispatch.arguments, { personalProjectId: task.personalProjectId, coordinatorAgentId, contextLimitPerQuery: 3,
       routingReason: `Bounded ${id} workstream; ${dependsOn.length ? 'independent acceptance after stable artifacts' : 'explicit scope'}; report evidence to the project lead.`,
       ...(spec.contextQueries ? { contextQueries: spec.contextQueries } : {}) });
-    return { id, workKind: spec.workKind, agentId: candidate?.agentId ?? null,
+    return { id, workKind: spec.workKind, agentId: target ?? null,
+      ...(viaSubLead ? { executionCandidateAgentId: candidate.agentId,
+        reportingGuidance: 'Send a bounded coordination brief to the sub-lead; it delegates within its group and reports to the project lead.' } : {}),
       boundary: spec.boundary ?? (verificationOnly || id === 'verification'
         ? '独立检查约定产物与验收条件，返回问题、命令和结果；不改动主线实现。'
         : '负责主线实施与集成；独立工作包之外的修改由此处统一处理。'),
       action: continuing ? 'continue_current' : blocked ? 'blocked' : candidate?.requiresLoan ? 'request_loan' : candidate ? 'delegate' : 'recruit',
       dependsOn, startWhen: dependsOn.length ? 'artifacts_ready' : 'now', dispatch,
-      ...(blocked ? { blockedReason: 'qualified_agent_client_unavailable', unavailableCandidates: unavailable,
+      ...(scopeGap ? { blockedReason: 'sub_team_scope_gap', reportToAgentId: reportingParent(policy, task.projectAgentId),
+        guidance: 'Report this staffing gap to the project lead; do not bypass your group or recruit a replacement.' }
+        : blocked ? { blockedReason: 'qualified_agent_client_unavailable', unavailableCandidates: unavailable,
         guidance: 'A qualified FLA exists but cannot use this client. Select an already authorized eligible client with assess_agent_action or report the constraint; do not recruit a replacement or relax its allowed clients.' } : {}),
       ...(candidate?.requiresLoan ? { borrow: nextSteps(candidate, token, sourceLeads[candidate.projectId], task.personalProjectId).borrow } : {}) };
   }
-  const main = !independentAcceptance && mainCandidates.find(candidate => candidate.agentId === task.projectAgentId)
-    || mainCandidates[0];
+  // The lead keeps the main work only when no other occupation was asked for.
+  // An explicitly requested occupation is a requirement: without such a member, Bole recruits one.
+  const pick = (list, occupation) => occupation ? list.find(candidate => candidate.occupationMatch) : list[0];
+  const main = !independentAcceptance && mainCandidates.find(candidate => candidate.agentId === task.projectAgentId
+    && (!input.occupation || candidate.occupationMatch)) || pick(mainCandidates, input.occupation);
   const workstreams = [workstream('main', input, main, [], unavailableCandidates)];
   if (independent) {
     const excluded = [...authors, main?.agentId];
-    workstreams.push(workstream('independent', independent, eligible(pools.independent, excluded)[0], [],
+    workstreams.push(workstream('independent', independent, pick(eligible(pools.independent, excluded), independent.occupation), [],
       eligible(pools.independent, excluded, false)));
   }
   if (separated) {
     const excluded = [...authors, ...workstreams.map(stream => stream.agentId)];
-    workstreams.push(workstream('verification', verification, eligible(pools.verification, excluded)[0],
+    workstreams.push(workstream('verification', verification, pick(eligible(pools.verification, excluded), input.verificationOccupation),
       workstreams.map(stream => stream.id), eligible(pools.verification, excluded, false)));
   }
   const divisionPlan = { mode: separated ? 'separated' : 'single', coordinatorAgentId, workstreams,
+    execution: executionPlan(workstreams, input.hostExecutionModes, token),
     reason: separated ? (independent ? '复杂任务有明确独立边界，拆为两个执行工作包和一份独立验收。'
       : '主线延续当前上下文，另一个 FLA 在产物稳定后独立验收，减少重复阅读。')
       : independentAcceptance ? '这是独立验收工作包，排除已知实现者，不再递归拆分。'
@@ -144,7 +192,7 @@ export async function planAgentCollaboration(application, input) {
     candidates: shown, unavailableCandidates, recruitment, pendingLoans: loans.loans?.filter(loan => loan.status === 'requested') ?? [],
     executionStarted: false,
     preferencePrompt, divisionPlan,
-    guidance: 'Keep the project lead as owner. Choose a qualified specialist. Discovery and roundtable answers are advisory and are not executed work. For another project, the destination lead calls request_agent_loan; the source lead approves with decide_agent_loan in its own scoped task. Then coordinate_project_agent_task with the borrowed Agent. Share only the bounded task brief and authorized artifacts. Workers report results to the project lead; record actual workers. Verify each artifact; use record_agent_verification. Two failed attempts at one capability tier require escalation, not another identical retry. A selected model is not proof of execution or success.' };
+    guidance: 'Keep the project lead as user-facing owner. Choose a qualified specialist through its immediate reporting lead; each lead integrates reports upward. Discovery and roundtable answers are advisory and are not executed work. For another project, the destination lead calls request_agent_loan; the source lead approves with decide_agent_loan in its own scoped task. Then coordinate_project_agent_task with the borrowed Agent. Share only the bounded task brief and authorized artifacts; record actual workers. Verify each artifact; use record_agent_verification. Two failed attempts at one capability tier require escalation, not another identical retry. A selected model is not proof of execution or success.' };
 }
 
 export async function agentLoan(application, operation, input) {