sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/router/route-projection.ts

@@ -0,0 +1,357 @@
+import type { AgentCapabilityCatalog, AgentCapabilityCatalogEntry, AgentCapabilityDomain, AgentCapabilityMaterialPack, AgentCapabilityStage } from '../registries/agent-capability-catalog.js';
+import { TOOL_PERMISSION_SPEC_VERSION } from '../contracts.js';
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type { SddTask, SddTaskGap } from '../sdd-docs/task-parser.js';
+import type {
+  AgentCapabilityRouteDecision,
+  AgentProfileId,
+  AgentRouterCategory,
+  AgentRouterRejectedProfile,
+  AgentRuntimeAdapterMapping,
+  AgentRuntimeRoutingRule,
+  CapabilitySourceCatalogEntry,
+  ModelPolicyContract,
+  RuntimeRegistryEntrySource,
+  ToolPermissionSpec
+} from './agent-runtime.js';
+import { BUILT_IN_MODEL_POLICIES, registrySourceFor, type AgentSkillRuntimeRegistry } from './runtime-registry.js';
+import { findBuiltInProfile, findRegisteredProfile, resolveAgentProfileToken } from './profile-resolution.js';
+import { hasExternalUnknownRisk, hasSecurityRisk, isHighRiskValues } from './risk-policy.js';
+
+export function routeCategory(task: SddTask, blockingGap: SddTaskGap | undefined, allowedProfiles: AgentProfileId[] = [], matchedRules: AgentRuntimeRoutingRule[] = []): AgentRouterCategory {
+  if (blockingGap) {
+    return 'blocked';
+  }
+  if (hasSecurityRisk(task.risk)) {
+    return 'security_research';
+  }
+  if (hasExternalUnknownRisk(task.risk)) {
+    return 'external_research';
+  }
+  if (task.status === 'completed') {
+    return 'validation';
+  }
+  const ruleCategory = matchedRules.find((rule) => rule.category)?.category;
+  if (ruleCategory) {
+    return ruleCategory;
+  }
+  if (allowedProfiles.every((profile) => profile === 'planner' || profile === 'architect' || profile === 'researcher')) {
+    return 'planning';
+  }
+  if (allowedProfiles.includes('reviewer') && !allowedProfiles.includes('implementer')) {
+    return 'implementation_review';
+  }
+  return 'implementation';
+}
+
+export function selectRequiredSkillCapabilities(task: SddTask, profile: AgentProfileId, registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): string[] {
+  const capabilities = new Set<string>(['host.search.grep_glob']);
+  const profileContract = findRegisteredProfile(profile, registry);
+  for (const capabilityId of profileContract?.hostCapabilityRequirements ?? []) {
+    capabilities.add(capabilityId);
+  }
+  for (const rule of matchedRules) {
+    for (const capabilityId of rule.requireCapabilities) {
+      capabilities.add(capabilityId);
+    }
+  }
+  if (profile === 'researcher' || profile === 'planner' || profile === 'architect' || hasExternalUnknownRisk(task.risk)) {
+    capabilities.add('claude.subagent.researcher');
+    capabilities.add('context7.docs');
+  }
+  if (profile === 'implementer') {
+    capabilities.add('claude.subagent.implementer');
+    capabilities.add('host.edit.hashline');
+    capabilities.add('host.cli.shell');
+  }
+  if (profile === 'reviewer') {
+    capabilities.add('host.cli.shell');
+  }
+  if (profile === 'validator') {
+    capabilities.add('host.cli.shell');
+    if (task.validation.some((item) => /browser|ui|frontend|playwright|页面|前端/i.test(item))) {
+      capabilities.add('playwright.browser_validation');
+    }
+  }
+  if (profile === 'security' || hasSecurityRisk(task.risk)) {
+    capabilities.add('pattern.ohmy.security_research');
+  }
+  if (profile === 'domain_expert') {
+    capabilities.add('external.agency_agents.material');
+  }
+  return [...capabilities];
+}
+
+export function buildAgentCapabilityRouteDecision(task: SddTask | null, category: AgentRouterCategory, autonomyCeiling: LifecycleAutonomyCeiling, registry: AgentSkillRuntimeRegistry, catalog: AgentCapabilityCatalog): AgentCapabilityRouteDecision {
+  if (!task) {
+    return {
+      authority: 'advisory_only',
+      selectedDomains: [],
+      selectedPacks: [],
+      rejectedExternalSources: rejectedCapabilitySources(registry.capabilitySources),
+      consideredExternalSources: consideredCapabilitySources(registry.capabilitySources),
+      evidenceRequirements: ['task metadata must exist before capability routing can select evidence requirements'],
+      permissionCeiling: autonomyCeiling
+    };
+  }
+  const stage = routeCapabilityStage(task, category);
+  const text = taskSignalText(task);
+  const selectedCapabilities = catalog.capabilities.filter((capability) => capability.domainGroup === 'professional' && capabilityStageFits(capability, stage, task, text) && capabilityMatchesTask(capability, task, text));
+  const effectiveCapabilities = selectedCapabilities.length > 0 ? selectedCapabilities : fallbackCapabilitiesForTask(catalog.capabilities, task, stage);
+  const packById = new Map(catalog.materialPacks.map((pack) => [pack.id, pack]));
+  const selectedPackIds = new Set<string>();
+  for (const capability of effectiveCapabilities) {
+    for (const packId of capability.routing.materialPackIds) {
+      const pack = packById.get(packId);
+      if (pack && pack.loadPolicy !== 'never_inline' && packFitsRoute(pack, stage, text)) {
+        selectedPackIds.add(packId);
+      }
+    }
+  }
+  return {
+    authority: 'advisory_only',
+    selectedDomains: effectiveCapabilities.map((capability) => ({
+      domain: capability.domain,
+      capabilityId: capability.id,
+      authority: capability.authority,
+      reason: capabilityReason(capability, task)
+    })),
+    selectedPacks: [...selectedPackIds].map((packId) => packById.get(packId)).filter((pack): pack is AgentCapabilityMaterialPack => Boolean(pack)).map((pack) => ({
+      id: pack.id,
+      domains: [...pack.domains],
+      loadPolicy: pack.loadPolicy,
+      contextBudget: pack.contextBudget,
+      sourceKind: pack.sourceKind,
+      expectedOutputs: [...pack.expectedOutputs],
+      reason: packReason(pack, stage)
+    })),
+    rejectedExternalSources: rejectedCapabilitySources(registry.capabilitySources),
+    consideredExternalSources: consideredCapabilitySources(registry.capabilitySources),
+    evidenceRequirements: evidenceRequirementsForCapabilities(effectiveCapabilities),
+    permissionCeiling: autonomyCeiling
+  };
+}
+
+export function routeRegistrySources(registry: AgentSkillRuntimeRegistry, profile: AgentProfileId | null, capabilityIds: string[]): RuntimeRegistryEntrySource[] {
+  const selected: RuntimeRegistryEntrySource[] = [];
+  const seen = new Set<string>();
+  const pushSource = (source: RuntimeRegistryEntrySource | null): void => {
+    if (!source) {
+      return;
+    }
+    const key = `${source.kind}:${source.id}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      selected.push(source);
+    }
+  };
+  if (profile) {
+    pushSource(registrySourceFor(registry, 'profile', profile));
+  }
+  for (const capabilityId of capabilityIds) {
+    const capabilitySource = registrySourceFor(registry, 'skill_capability', capabilityId);
+    pushSource(capabilitySource);
+    if (capabilitySource?.sourceId) {
+      pushSource(registrySourceFor(registry, 'capability_source', capabilitySource.sourceId));
+    }
+  }
+  return selected;
+}
+
+export function quarantineWarningsForSources(sources: RuntimeRegistryEntrySource[]): string[] {
+  return sources.filter((source) => source.quarantineRequired).map((source) => `${source.kind}:${source.id} originates from quarantined material and remains declarative metadata only.`);
+}
+
+export function adapterMappingForProfile(registry: AgentSkillRuntimeRegistry, profile: AgentProfileId): AgentRuntimeAdapterMapping | null {
+  return registry.adapterMappings.find((mapping) => resolveAgentProfileToken(mapping.profile, registry).profile === profile) ?? null;
+}
+
+export function buildToolPermissionSpec(task: SddTask, profile: AgentProfileId, autonomyCeiling: LifecycleAutonomyCeiling, registry?: AgentSkillRuntimeRegistry): ToolPermissionSpec {
+  const highRisk = isHighRiskValues(task.risk);
+  const readonlyProfiles: AgentProfileId[] = ['planner', 'architect', 'researcher', 'reviewer', 'security', 'domain_expert'];
+  const profileContract = registry ? findRegisteredProfile(profile, registry) : null;
+  const toolGroups = profileContract && !findBuiltInProfile(profile) ? [...profileContract.toolScope] : readonlyProfiles.includes(profile) ? ['read', 'search', 'docs'] : profile === 'validator' ? ['read', 'test', 'browser'] : ['read', 'edit', 'test'];
+  return {
+    version: TOOL_PERMISSION_SPEC_VERSION,
+    profile,
+    risk: [...task.risk],
+    toolGroups,
+    fileScope: task.affectedFiles.length > 0 ? [...task.affectedFiles] : ['declared task boundary', 'artifacts/<task>.md'],
+    policy: highRisk || autonomyCeiling === 'full_sdd_with_checkpoint' || autonomyCeiling === 'research_before_implementation' ? 'ask' : 'allow',
+    approvalPolicy: highRisk ? 'human checkpoint required before write or external side effect' : 'host approval policy applies',
+    runtimeValidationRequired: highRisk || profile === 'implementer' || profile === 'validator',
+    deniedTools: profile === 'security' ? ['destructive_exploit', 'dos', 'credential_exfiltration', 'detection_evasion'] : ['destructive_git', 'unscoped_external_write'],
+    hostPermissionProjection: `profile=${profile}; autonomy=${autonomyCeiling}; policy=${highRisk ? 'ask' : 'host-default'}`
+  };
+}
+
+export function modelPolicyForProfile(profile: AgentProfileId | null, registry?: AgentSkillRuntimeRegistry): ModelPolicyContract {
+  const profileContract = profile && registry ? findRegisteredProfile(profile, registry) : null;
+  const policyId = profileContract?.modelPolicyId ?? (profile === 'security' ? 'security_review' : profile === 'planner' || profile === 'architect' || profile === 'reviewer' || profile === 'researcher' || profile === 'orchestrator' ? 'reasoning' : 'balanced');
+  return BUILT_IN_MODEL_POLICIES.find((policy) => policy.id === policyId) ?? BUILT_IN_MODEL_POLICIES[0];
+}
+
+export function buildRejectedProfiles(allowedProfiles: AgentProfileId[], blockedReason: string | null, registry: AgentSkillRuntimeRegistry): AgentRouterRejectedProfile[] {
+  const allowed = new Set(allowedProfiles);
+  return registry.profiles
+    .filter((profile) => !allowed.has(profile.id))
+    .map((profile) => ({ profile: profile.id, reason: blockedReason ?? 'Profile is outside task metadata allowed_agents/agent_fit, routing rules, or router risk category.' }));
+}
+
+function routeCapabilityStage(task: SddTask, category: AgentRouterCategory): AgentCapabilityStage {
+  if (category === 'planning') {
+    return 'plan';
+  }
+  if (category === 'validation' || task.status === 'completed') {
+    return 'test';
+  }
+  return 'do';
+}
+
+function taskSignalText(task: SddTask): string {
+  return [
+    task.id,
+    task.title ?? '',
+    task.boundary ?? '',
+    task.implementationNotes ?? '',
+    ...task.risk,
+    ...task.affectedFiles,
+    ...task.validation,
+    ...task.acceptance,
+    ...task.allowedAgents,
+    ...task.agentFit
+  ].join('\n').toLowerCase();
+}
+
+function capabilityMatchesTask(capability: AgentCapabilityCatalogEntry, task: SddTask, text: string): boolean {
+  return capability.routing.riskTags.some((tag) => text.includes(tag.toLowerCase())) || capability.routing.projectStackTags.some((tag) => projectStackMatches(tag, task, text)) || capability.routing.materialPackIds.some((packId) => text.includes(packId.replace(/^baseline-/, '').replace(/-/g, ' '))) || domainFileSignal(capability.domain, task.affectedFiles);
+}
+
+function fallbackCapabilitiesForTask(capabilities: AgentCapabilityCatalogEntry[], task: SddTask, stage: AgentCapabilityStage): AgentCapabilityCatalogEntry[] {
+  const codeFile = task.affectedFiles.some((file) => /\.(ts|js|java|go|py|rs|cs|php|rb)$/i.test(file));
+  const fallbackDomain: AgentCapabilityDomain = codeFile ? 'backend-engineering' : 'solution-design';
+  const fallback = capabilities.find((capability) => capability.domain === fallbackDomain && capabilityStageFits(capability, stage, task, taskSignalText(task)));
+  return fallback ? [fallback] : [];
+}
+
+function packFitsRoute(pack: AgentCapabilityMaterialPack, stage: AgentCapabilityStage, text: string): boolean {
+  const keywordTriggered = pack.triggerKeywords.some((keyword) => text.includes(keyword.toLowerCase()));
+  if (pack.sourceKind === 'sdd_native_baseline') {
+    return pack.triggerStages.includes(stage) || keywordTriggered;
+  }
+  return pack.triggerStages.includes(stage) && keywordTriggered;
+}
+
+function domainFileSignal(domain: AgentCapabilityDomain, affectedFiles: string[]): boolean {
+  const files = affectedFiles.map((file) => file.toLowerCase());
+  if (domain === 'frontend-engineering') {
+    return files.some((file) => /\.(tsx|jsx|vue|svelte|css|scss|less)$/.test(file) || file.includes('/components/') || file.includes('/pages/'));
+  }
+  if (domain === 'db-data-engineering') {
+    return files.some((file) => /\.(sql|prisma)$/.test(file) || file.includes('migration') || file.includes('schema') || file.includes('database'));
+  }
+  if (domain === 'backend-engineering') {
+    return files.some((file) => /\.(ts|js|java|go|py|rs|cs|php|rb)$/.test(file)) && !domainFileSignal('frontend-engineering', affectedFiles);
+  }
+  return false;
+}
+
+function capabilityStageFits(capability: AgentCapabilityCatalogEntry, stage: AgentCapabilityStage, task: SddTask, text: string): boolean {
+  if (capability.stages.includes(stage)) {
+    return true;
+  }
+  if (capability.domain === 'testing-quality-engineering' && stage === 'do') {
+    return testingQualityTaskSignal(task);
+  }
+  return capability.domain === 'release-engineering' && /release|ship|deploy|rollback|ci|发布/.test(text);
+}
+
+function testingQualityTaskSignal(task: SddTask): boolean {
+  const taskText = [task.id, task.title ?? '', task.boundary ?? '', task.implementationNotes ?? '', ...task.risk, ...task.affectedFiles, ...task.acceptance].join('\n').toLowerCase();
+  return /quality|coverage|acceptance|验证|测试/.test(taskText) || task.affectedFiles.some((file) => /\.(test|spec)\.[tj]sx?$/i.test(file));
+}
+
+function capabilityReason(capability: AgentCapabilityCatalogEntry, task: SddTask): string {
+  const fileSignal = domainFileSignal(capability.domain, task.affectedFiles) ? 'affected file evidence' : 'task risk, validation, or text evidence';
+  return `${capability.domain} selected from ${fileSignal}; authority remains ${capability.authority}.`;
+}
+
+function packReason(pack: AgentCapabilityMaterialPack, stage: AgentCapabilityStage): string {
+  return `${pack.id} is route_when_triggered for ${stage} and stays ${pack.contextBudget} context.`;
+}
+
+function evidenceRequirementsForCapabilities(capabilities: AgentCapabilityCatalogEntry[]): string[] {
+  const requirements = new Set<string>();
+  for (const capability of capabilities) {
+    for (const output of capability.outputs) {
+      requirements.add(`${capability.domain}: ${output}`);
+    }
+  }
+  return [...requirements];
+}
+
+function consideredCapabilitySources(sources: CapabilitySourceCatalogEntry[]): AgentCapabilityRouteDecision['consideredExternalSources'] {
+  return sources
+    .filter((source) => source.kind !== 'native_host')
+    .map((source) => ({
+      sourceId: source.id,
+      kind: source.kind,
+      quarantineStatus: source.quarantineStatus,
+      reuseDecision: source.reuseDecision,
+      allowedEvidenceTypes: [...source.allowedEvidenceTypes],
+      consideredUse: source.allowedUse,
+      reason: rejectedSourceReason(source)
+    }));
+}
+
+
+function rejectedCapabilitySources(sources: CapabilitySourceCatalogEntry[]): AgentCapabilityRouteDecision['rejectedExternalSources'] {
+  return sources
+    .filter((source) => source.kind !== 'native_host' && (source.quarantineRequired || source.reuseDecision !== 'reuse_direct' || source.kind === 'future_adapter'))
+    .map((source) => ({
+      sourceId: source.id,
+      quarantineStatus: source.quarantineStatus,
+      reuseDecision: source.reuseDecision,
+      allowedEvidenceTypes: [...source.allowedEvidenceTypes],
+      reason: rejectedSourceReason(source)
+    }));
+}
+
+function projectStackMatches(tag: string, task: SddTask, text: string): boolean {
+  if (tag === 'generic') {
+    return false;
+  }
+  if (text.includes(tag.toLowerCase())) {
+    return true;
+  }
+  const files = task.affectedFiles.map((file) => file.toLowerCase());
+  if (tag === 'typescript') {
+    return files.some((file) => /\.(ts|tsx)$/.test(file));
+  }
+  if (tag === 'javascript') {
+    return files.some((file) => /\.(js|jsx)$/.test(file));
+  }
+  if (tag === 'java') {
+    return files.some((file) => file.endsWith('.java'));
+  }
+  if (tag === 'sql') {
+    return files.some((file) => /\.(sql|prisma)$/.test(file));
+  }
+  return files.some((file) => file.includes(tag.toLowerCase()));
+}
+
+function rejectedSourceReason(source: CapabilitySourceCatalogEntry): string {
+  if (source.quarantineStatus === 'denied') {
+    return 'Source is denied or unsupported and cannot participate in routing.';
+  }
+  if (source.kind === 'future_adapter') {
+    return 'Future adapter is recorded as metadata only until host behavior is validated.';
+  }
+  if (source.quarantineStatus === 'quarantined' || source.quarantineStatus === 'required') {
+    return 'Source requires quarantine/provenance review and is not invoked by capability routing.';
+  }
+  if (source.reuseDecision === 'avoid') {
+    return 'Reuse policy avoids this source.';
+  }
+  return 'External source is considered but not loaded during progressive disclosure.';
+}