sdd-agent-platform 0.2.0 → 0.4.0

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

@@ -0,0 +1,323 @@
+import {
+  AGENT_EXECUTION_RECORD_CONTRACT_VERSION,
+  AGENT_ROUTER_CONTRACT_VERSION,
+  AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+  CAPABILITY_SOURCE_CATALOG_VERSION,
+  EVIDENCE_INGESTION_CONTRACT_VERSION,
+  EXTERNAL_AGENT_PACK_IMPORT_POLICY_VERSION,
+  HOST_ADAPTER_CONTRACT_VERSION,
+  TEAM_MODE_POLICY_VERSION,
+  TEAM_SESSION_RECORD_CONTRACT_VERSION,
+  TOOL_PERMISSION_SPEC_VERSION
+} from '../contracts.js';
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type { ArtifactResultIngestionStatus } from '../artifacts/ingestion.js';
+import type { SddResultStatus } from '../artifacts/sdd-result.js';
+import type { RouteCacheMetadata, RuntimeProfileSpan, TeamModeActivation } from './route-cache.js';
+import type { ApprovalPolicy, LifecycleRiskProfile, LifecycleWorkflowGate } from '../risk.js';
+
+export type BuiltInAgentProfileId = 'planner' | 'architect' | 'implementer' | 'reviewer' | 'validator' | 'researcher' | 'orchestrator' | 'security' | 'domain_expert';
+export type AgentProfileId = BuiltInAgentProfileId | string;
+export type CapabilityReuseDecision = 'reuse_direct' | 'adapt_via_host_adapter' | 'borrow_mechanism' | 'avoid';
+export type SkillCapabilityKind = 'skill' | 'mcp' | 'cli_tool' | 'host_tool' | 'project_agent' | 'external_pattern';
+export type SkillCapabilitySource = 'project' | 'user_global' | 'claude_code' | 'mcp' | 'open_source' | 'host';
+export type SkillCapabilityEvidenceType = 'none' | 'command_output' | 'test_result' | 'browser_snapshot' | 'artifact' | 'external_source' | 'execution_record';
+export type CapabilitySourceKind = 'native_host' | 'mcp_tool' | 'open_source_material' | 'mechanism_reference' | 'future_adapter' | 'project_material';
+export type ExternalPackImportStatus = 'approved' | 'quarantined' | 'denied';
+export type ExternalPackCheckStatus = 'pass' | 'warn' | 'fail' | 'not_run';
+export type ToolPermissionPolicy = 'allow' | 'ask' | 'deny';
+export type AgentRouterCategory = 'planning' | 'implementation' | 'implementation_review' | 'validation' | 'security_research' | 'external_research' | 'blocked';
+export type TeamModeDecisionStatus = 'disabled' | 'enabled' | 'blocked';
+export type TeamModeSelection = 'off' | 'inspect' | 'review-lite' | 'hyperplan' | 'security-research';
+export type TeamModeCostClass = 'none' | 'low' | 'medium' | 'high';
+export type TeamModeCostRoute = 'not_applicable' | 'downgraded' | 'no_downgrade' | 'blocked';
+export type AgentExecutionRecordStatus = 'claimed' | 'completed' | 'failed' | 'blocked' | 'skipped';
+export type TeamSessionRecordStatus = 'created' | 'completed' | 'blocked' | 'disabled';
+
+export interface AgentProfileContract {
+  version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
+  id: AgentProfileId;
+  stageScope: string[];
+  riskCeiling: LifecycleAutonomyCeiling;
+  defaultAutonomy: LifecycleAutonomyCeiling;
+  requiredArtifacts: string[];
+  toolScope: string[];
+  modelPolicyId: string;
+  hostCapabilityRequirements: string[];
+  boundaries: string[];
+}
+
+export interface SkillCapabilityContract {
+  version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
+  id: string;
+  name: string;
+  kind: SkillCapabilityKind;
+  source: SkillCapabilitySource;
+  sourceRef: string;
+  capabilityDomain: string[];
+  allowedStages: string[];
+  requiredRiskCeiling: LifecycleAutonomyCeiling;
+  evidenceType: SkillCapabilityEvidenceType;
+  reuseDecision: CapabilityReuseDecision;
+  buildExceptionReason: string | null;
+}
+
+export interface CapabilitySourceCatalogEntry {
+  version: typeof CAPABILITY_SOURCE_CATALOG_VERSION;
+  id: string;
+  name: string;
+  kind: CapabilitySourceKind;
+  sourceRef: string;
+  reuseDecision: CapabilityReuseDecision;
+  quarantineRequired: boolean;
+  allowedUse: string;
+  attribution: string;
+  rationale: string;
+}
+
+export type RuntimeRegistryOrigin = 'built_in' | 'project_config' | 'external_manifest';
+
+export interface RuntimeRegistryEntrySource {
+  id: string;
+  kind: 'profile' | 'skill_capability' | 'capability_source';
+  origin: RuntimeRegistryOrigin;
+  sourceId: string | null;
+  quarantineRequired: boolean;
+}
+
+export interface AgentRuntimeRoutingRuleWhen {
+  keywords: string[];
+  affectedFileGlobs: string[];
+}
+
+export interface AgentRuntimeRoutingRule {
+  id: string;
+  when: AgentRuntimeRoutingRuleWhen;
+  preferProfile: AgentProfileId;
+  requireCapabilities: string[];
+  category: AgentRouterCategory | null;
+}
+
+export interface AgentRuntimeAdapterMapping {
+  profile: AgentProfileId;
+  hostAdapter: string;
+  projection: string;
+  permissionPolicy: string;
+}
+
+export interface AgentRuntimeAliasResolution {
+  input: string;
+  resolved: AgentProfileId;
+  source: 'built_in' | 'project_config';
+}
+
+export interface ProjectAgentRuntimeConfig {
+  profiles: AgentProfileContract[];
+  skillCapabilities: SkillCapabilityContract[];
+  capabilitySources: CapabilitySourceCatalogEntry[];
+  aliases: Record<string, string>;
+  routingRules: AgentRuntimeRoutingRule[];
+  adapterMappings: AgentRuntimeAdapterMapping[];
+}
+
+export interface ExternalAgentPackImportCheck {
+  check: string;
+  status: ExternalPackCheckStatus;
+  evidence: string;
+}
+
+export interface ExternalAgentPackImportInspection {
+  version: typeof EXTERNAL_AGENT_PACK_IMPORT_POLICY_VERSION;
+  sourceId: string;
+  status: ExternalPackImportStatus;
+  checks: ExternalAgentPackImportCheck[];
+  mappingResult: string;
+  allowedProfiles: AgentProfileId[];
+  riskCeiling: LifecycleAutonomyCeiling;
+  reason: string;
+}
+
+export interface ModelPolicyContract {
+  id: string;
+  category: string;
+  fallbackPolicy: string;
+  hostProjection: string;
+}
+
+export interface ToolPermissionSpec {
+  version: typeof TOOL_PERMISSION_SPEC_VERSION;
+  profile: AgentProfileId;
+  risk: string[];
+  toolGroups: string[];
+  fileScope: string[];
+  policy: ToolPermissionPolicy;
+  approvalPolicy: string;
+  runtimeValidationRequired: boolean;
+  deniedTools: string[];
+  hostPermissionProjection: string;
+}
+
+export interface HostAdapterContract {
+  version: typeof HOST_ADAPTER_CONTRACT_VERSION;
+  id: string;
+  host: string;
+  responsibilities: string[];
+  forbiddenAuthority: string[];
+  projections: string[];
+}
+
+export interface DelegationWavePolicy {
+  id: string;
+  waveKind: 'hyperplan' | 'security_research' | 'implementation_review' | 'validation';
+  memberProfiles: AgentProfileId[];
+  requiredArtifacts: string[];
+  fileOwnershipRequired: boolean;
+  mergeGate: string;
+}
+
+export interface TeamModePolicy {
+  version: typeof TEAM_MODE_POLICY_VERSION;
+  enabled: boolean;
+  decision: TeamModeDecisionStatus;
+  mode: TeamModeSelection;
+  activation: TeamModeActivation;
+  costClass: TeamModeCostClass;
+  reason: string;
+  costRoute: TeamModeCostRoute;
+  downgradeReason: string | null;
+  trustPolicyEnforced: boolean;
+  chiefProfile: AgentProfileId;
+  memberProfiles: AgentProfileId[];
+  allowedWaves: DelegationWavePolicy[];
+  maxMembers: number;
+  requireArtifacts: boolean;
+  blockedReason: string | null;
+  waveRecommendation: string[];
+}
+
+export interface EvidenceIngestionContract {
+  version: typeof EVIDENCE_INGESTION_CONTRACT_VERSION;
+  sourceOutputs: string[];
+  evidenceTargets: string[];
+  canonicalTruth: string;
+  forbiddenTruthSources: string[];
+}
+
+export interface AgentExecutionRecord {
+  version: typeof AGENT_EXECUTION_RECORD_CONTRACT_VERSION;
+  executionId: string;
+  runId: string;
+  taskId: string;
+  profile: AgentProfileId;
+  category: AgentRouterCategory;
+  host: string;
+  hostSessionId: string | null;
+  hostTaskId: string | null;
+  modelPolicy: ModelPolicyContract;
+  toolPermission: ToolPermissionSpec | null;
+  capabilitiesUsed: string[];
+  sourceAttribution: string[];
+  artifacts: string[];
+  status: AgentExecutionRecordStatus;
+  delegationId: string | null;
+  queueItemId: string | null;
+  ingestionStatus: ArtifactResultIngestionStatus | null;
+  resultStatus: SddResultStatus | null;
+  routeId: string;
+  routeDecision: Pick<AgentRouterDecision, 'version' | 'category' | 'recommendedProfile' | 'autonomyCeiling' | 'requiredCapabilities' | 'blockedReason'>;
+  evidenceSummary: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TeamMessageRecord {
+  sender: AgentProfileId | 'runtime';
+  receiver: AgentProfileId | 'team' | 'runtime';
+  taskRef: string | null;
+  artifactRefs: string[];
+  blocker: string | null;
+  evidenceSummary: string;
+  createdAt: string;
+}
+
+export interface TeamSessionRecord {
+  version: typeof TEAM_SESSION_RECORD_CONTRACT_VERSION;
+  teamId: string;
+  runId: string;
+  taskId: string | null;
+  status: TeamSessionRecordStatus;
+  chiefProfile: AgentProfileId;
+  memberProfiles: AgentProfileId[];
+  hostLayout: string | null;
+  teamMode: TeamModePolicy;
+  waves: DelegationWavePolicy[];
+  messages: TeamMessageRecord[];
+  artifacts: string[];
+  evidenceSummary: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AgentRouterRejectedProfile {
+  profile: AgentProfileId;
+  reason: string;
+}
+
+export interface AgentRouterDecision {
+  version: typeof AGENT_ROUTER_CONTRACT_VERSION;
+  taskId: string;
+  branch: string;
+  category: AgentRouterCategory;
+  recommendedProfile: AgentProfileId | null;
+  allowedProfiles: AgentProfileId[];
+  rejectedProfiles: AgentRouterRejectedProfile[];
+  requiredCapabilities: string[];
+  sourceCapability: string | null;
+  reuseDecision: CapabilityReuseDecision | null;
+  toolPermission: ToolPermissionSpec | null;
+  modelPolicy: ModelPolicyContract;
+  teamMode: TeamModePolicy;
+  autonomyCeiling: LifecycleAutonomyCeiling;
+  lifecycleGate: LifecycleWorkflowGate | null;
+  lifecycleProfile: LifecycleRiskProfile | null;
+  approvalPolicy: ApprovalPolicy | null;
+  requiredStages: string[];
+  primaryReason: string;
+  requiredArtifacts: string[];
+  blockedReason: string | null;
+  nextAction: string;
+  registrySources?: RuntimeRegistryEntrySource[];
+  resolvedAliases?: AgentRuntimeAliasResolution[];
+  routingRuleHits?: string[];
+  quarantineWarnings?: string[];
+  adapterMapping?: AgentRuntimeAdapterMapping | null;
+  cache?: RouteCacheMetadata;
+  profile?: RuntimeProfileSpan[];
+}
+
+export interface AgentSkillTeamRuntimeInspection {
+  version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
+  profiles: AgentProfileContract[];
+  skillCapabilities: SkillCapabilityContract[];
+  capabilitySources: CapabilitySourceCatalogEntry[];
+  hostAdapter: HostAdapterContract;
+  evidenceIngestion: EvidenceIngestionContract;
+  teamMode: TeamModePolicy;
+  reusePolicy: string;
+  registrySources?: RuntimeRegistryEntrySource[];
+  aliases?: Record<string, string>;
+  routingRules?: AgentRuntimeRoutingRule[];
+  adapterMappings?: AgentRuntimeAdapterMapping[];
+}
+
+export interface SkillCapabilityRegistry {
+  version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
+  capabilities: SkillCapabilityContract[];
+  registrySources?: RuntimeRegistryEntrySource[];
+}
+
+export interface CapabilitySourceCatalog {
+  version: typeof CAPABILITY_SOURCE_CATALOG_VERSION;
+  sources: CapabilitySourceCatalogEntry[];
+  registrySources?: RuntimeRegistryEntrySource[];
+}

package/node_modules/@sdd-agent-platform/core/src/router/profile-resolution.ts

@@ -0,0 +1,154 @@
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import type {
+  AgentProfileContract,
+  AgentProfileId,
+  AgentRuntimeAliasResolution,
+  AgentRuntimeRoutingRule
+} from './agent-runtime.js';
+import { BUILT_IN_AGENT_PROFILES, type AgentSkillRuntimeRegistry } from './runtime-registry.js';
+import { hasExternalUnknownRisk, hasSecurityRisk } from './risk-policy.js';
+
+export interface AgentRouteProfileSelection {
+  profiles: AgentProfileId[];
+  resolvedAliases: AgentRuntimeAliasResolution[];
+}
+
+interface AgentProfileTokenResolution {
+  profile: AgentProfileId | null;
+  alias: AgentRuntimeAliasResolution | null;
+}
+
+export function deriveAllowedProfiles(task: SddTask, registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): AgentRouteProfileSelection {
+  const profiles = new Set<AgentProfileId>();
+  const resolvedAliases: AgentRuntimeAliasResolution[] = [];
+  for (const value of [...task.allowedAgents, ...task.agentFit]) {
+    for (const token of value.split(/[\s,\/]+/).filter(Boolean)) {
+      const resolution = resolveAgentProfileToken(token, registry);
+      if (resolution.profile) {
+        profiles.add(resolution.profile);
+      }
+      appendAliasResolution(resolvedAliases, resolution.alias);
+    }
+  }
+  for (const rule of matchedRules) {
+    const resolution = resolveAgentProfileToken(rule.preferProfile, registry);
+    if (resolution.profile) {
+      profiles.add(resolution.profile);
+    }
+    appendAliasResolution(resolvedAliases, resolution.alias);
+  }
+  if (profiles.size === 0) {
+    for (const profile of fallbackProfilesForTask(task)) {
+      addRegisteredProfile(profiles, profile, registry);
+    }
+  }
+  return { profiles: [...profiles], resolvedAliases };
+}
+
+export function toAgentProfileId(value: string, registry?: AgentSkillRuntimeRegistry): AgentProfileId | null {
+  return resolveAgentProfileToken(value, registry).profile;
+}
+
+export function resolveAgentProfileToken(value: string, registry?: AgentSkillRuntimeRegistry): AgentProfileTokenResolution {
+  const directProfile = registry ? findRegisteredProfile(value, registry) : findBuiltInProfile(value);
+  if (directProfile) {
+    return { profile: directProfile.id, alias: null };
+  }
+  const builtInAlias = builtInProfileAliasTarget(value);
+  const builtInProfile = builtInAlias ? registry ? findRegisteredProfile(builtInAlias, registry) : findBuiltInProfile(builtInAlias) : null;
+  if (builtInProfile) {
+    return { profile: builtInProfile.id, alias: { input: value, resolved: builtInProfile.id, source: 'built_in' } };
+  }
+  if (registry) {
+    for (const [alias, target] of Object.entries(registry.aliases)) {
+      if (normalizeAgentToken(alias) !== normalizeAgentToken(value)) {
+        continue;
+      }
+      const aliasTarget = findRegisteredProfile(target, registry) ?? (builtInProfileAliasTarget(target) ? findRegisteredProfile(builtInProfileAliasTarget(target)!, registry) : null);
+      if (aliasTarget) {
+        return { profile: aliasTarget.id, alias: { input: value, resolved: aliasTarget.id, source: 'project_config' } };
+      }
+    }
+  }
+  return { profile: null, alias: null };
+}
+
+export function findRegisteredProfile(value: string, registry: AgentSkillRuntimeRegistry): AgentProfileContract | null {
+  const normalized = normalizeAgentToken(value);
+  return registry.profiles.find((profile) => normalizeAgentToken(profile.id) === normalized) ?? null;
+}
+
+export function findBuiltInProfile(value: string): AgentProfileContract | null {
+  const normalized = normalizeAgentToken(value);
+  return BUILT_IN_AGENT_PROFILES.find((profile) => normalizeAgentToken(profile.id) === normalized) ?? null;
+}
+
+export function chooseRecommendedProfile(task: SddTask, allowedProfiles: AgentProfileId[], registry: AgentSkillRuntimeRegistry, matchedRules: AgentRuntimeRoutingRule[]): AgentProfileId {
+  if (hasSecurityRisk(task.risk)) {
+    return allowedProfiles.includes('security') ? 'security' : allowedProfiles[0] ?? 'security';
+  }
+  if (hasExternalUnknownRisk(task.risk)) {
+    return allowedProfiles.includes('researcher') ? 'researcher' : allowedProfiles[0] ?? 'researcher';
+  }
+  if (task.status === 'completed') {
+    return allowedProfiles.includes('validator') ? 'validator' : allowedProfiles[0] ?? 'validator';
+  }
+  const preferredByRule = matchedRules.map((rule) => resolveAgentProfileToken(rule.preferProfile, registry).profile).find((profile): profile is AgentProfileId => Boolean(profile));
+  if (preferredByRule && allowedProfiles.includes(preferredByRule)) {
+    return preferredByRule;
+  }
+  if (allowedProfiles.includes('implementer')) {
+    return 'implementer';
+  }
+  return allowedProfiles[0] ?? 'implementer';
+}
+
+function appendAliasResolution(resolvedAliases: AgentRuntimeAliasResolution[], alias: AgentRuntimeAliasResolution | null): void {
+  if (!alias) {
+    return;
+  }
+  if (!resolvedAliases.some((candidate) => candidate.input === alias.input && candidate.resolved === alias.resolved && candidate.source === alias.source)) {
+    resolvedAliases.push(alias);
+  }
+}
+
+function builtInProfileAliasTarget(value: string): AgentProfileId | null {
+  const normalized = normalizeAgentToken(value);
+  if (normalized === 'scout') {
+    return 'researcher';
+  }
+  if (normalized === 'debugger') {
+    return 'implementer';
+  }
+  if (normalized === 'spec_reviewer') {
+    return 'reviewer';
+  }
+  if (normalized === 'domain') {
+    return 'domain_expert';
+  }
+  return null;
+}
+
+function addRegisteredProfile(profiles: Set<AgentProfileId>, profileId: AgentProfileId, registry: AgentSkillRuntimeRegistry): void {
+  const profile = findRegisteredProfile(profileId, registry);
+  if (profile) {
+    profiles.add(profile.id);
+  }
+}
+
+function fallbackProfilesForTask(task: SddTask): AgentProfileId[] {
+  if (hasSecurityRisk(task.risk)) {
+    return ['security', 'reviewer'];
+  }
+  if (hasExternalUnknownRisk(task.risk)) {
+    return ['researcher', 'architect'];
+  }
+  if (task.status === 'completed') {
+    return ['validator', 'reviewer'];
+  }
+  return ['implementer', 'reviewer', 'validator'];
+}
+
+function normalizeAgentToken(value: string): string {
+  return value.trim().toLowerCase().replace(/-/g, '_');
+}

package/node_modules/@sdd-agent-platform/core/src/router/risk-policy.ts

@@ -0,0 +1,33 @@
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile } from '../task-risk-profile.js';
+
+export function taskAutonomyCeiling(task: SddTask): LifecycleAutonomyCeiling {
+  const declared = task.autonomy?.trim();
+  if (declared === 'direct_execution_allowed' || declared === 'compact_boundary_only' || declared === 'full_sdd_with_checkpoint' || declared === 'research_before_implementation') {
+    return declared;
+  }
+  const profile = buildTaskRiskProfile(task);
+  if (profile.externalUnknown) {
+    return 'research_before_implementation';
+  }
+  if (profile.riskLevel === 'high') {
+    return 'full_sdd_with_checkpoint';
+  }
+  if (profile.riskLevel === 'medium') {
+    return 'compact_boundary_only';
+  }
+  return 'direct_execution_allowed';
+}
+
+export function hasSecurityRisk(risk: string[]): boolean {
+  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).securitySensitive;
+}
+
+export function hasExternalUnknownRisk(risk: string[]): boolean {
+  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).externalUnknown;
+}
+
+export function isHighRiskValues(risk: string[]): boolean {
+  return buildTaskRiskProfile({ id: null, risk, affectedFiles: [], validation: [], requiredArtifacts: [] }).riskLevel === 'high';
+}

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

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  ACCEPTANCE_POLICY_RULESET_VERSION,
+  AGENT_ROUTER_CONTRACT_VERSION,
+  AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+  ROUTE_CACHE_CONTRACT_VERSION,
+  RUNTIME_PROFILE_CONTRACT_VERSION,
+  TEAM_MODE_POLICY_VERSION
+} from '../contracts.js';
+import { getRouteCachePath } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { TOOL_CAPABILITY_REGISTRY_VERSION } from '../registries/tool-capabilities.js';
+import { TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION } from '../registries/tool-plugins.js';
+import { WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION } from '../registries/worker-adapters.js';
+export type TeamModeActivation = 'auto' | 'force' | 'off';
+
+export interface RouteCacheMetadata {
+  contract: typeof ROUTE_CACHE_CONTRACT_VERSION;
+  key: string;
+  status: 'hit' | 'miss' | 'stored';
+  source: 'content_addressed_derived_route';
+  authoritative: false;
+}
+
+export interface RuntimeProfileSpan {
+  contract: typeof RUNTIME_PROFILE_CONTRACT_VERSION;
+  name: string;
+  startedAt: string;
+  endedAt: string;
+  durationMs: number;
+}
+
+export interface RouteCacheDocuments {
+  specHash?: string | null;
+  planHash?: string | null;
+  tasksHash?: string | null;
+  planBasedOnSpecHash?: string | null;
+  tasksBasedOnPlanHash?: string | null;
+}
+
+export interface CacheableRouteDecision {
+  version: typeof AGENT_ROUTER_CONTRACT_VERSION;
+  cache?: RouteCacheMetadata;
+  profile?: RuntimeProfileSpan[];
+}
+
+export function runtimeProfileSpan(name: string, startedAtMs: number, startedAt = new Date(startedAtMs).toISOString()): RuntimeProfileSpan {
+  const endedAtMs = Date.now();
+  return {
+    contract: RUNTIME_PROFILE_CONTRACT_VERSION,
+    name,
+    startedAt,
+    endedAt: new Date(endedAtMs).toISOString(),
+    durationMs: Math.max(0, endedAtMs - startedAtMs)
+  };
+}
+
+export function routeCacheKey(input: { taskId: string; branch: string; agent: string | null; teamModeActivation: TeamModeActivation; approved?: boolean; documents: RouteCacheDocuments }): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      contract: ROUTE_CACHE_CONTRACT_VERSION,
+      router: AGENT_ROUTER_CONTRACT_VERSION,
+      teamMode: TEAM_MODE_POLICY_VERSION,
+      policy: ACCEPTANCE_POLICY_RULESET_VERSION,
+      runtime: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+      capabilities: TOOL_CAPABILITY_REGISTRY_VERSION,
+      plugins: TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION,
+      workers: WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION,
+      taskId: input.taskId,
+      branch: input.branch,
+      agent: input.agent,
+      teamModeActivation: input.teamModeActivation,
+      approved: input.approved === true,
+      specHash: input.documents.specHash ?? null,
+      planHash: input.documents.planHash ?? null,
+      tasksHash: input.documents.tasksHash ?? null,
+      planBasedOnSpecHash: input.documents.planBasedOnSpecHash ?? null,
+      tasksBasedOnPlanHash: input.documents.tasksBasedOnPlanHash ?? null
+    }))
+    .digest('hex')
+    .slice(0, 32);
+}
+
+export async function readRouteCache<TDecision extends CacheableRouteDecision>(projectRoot: string, key: string): Promise<TDecision | null> {
+  const cachePath = getRouteCachePath(projectRoot, key);
+  if (!await exists(cachePath)) {
+    return null;
+  }
+  const parsed = JSON.parse(await readFile(cachePath, 'utf8')) as TDecision;
+  return parsed.version === AGENT_ROUTER_CONTRACT_VERSION ? parsed : null;
+}
+
+export async function writeRouteCache<TDecision extends CacheableRouteDecision>(projectRoot: string, key: string, decision: TDecision): Promise<void> {
+  const cachePath = getRouteCachePath(projectRoot, key);
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  const { cache: _cache, profile: _profile, ...cacheable } = decision;
+  await writeFile(cachePath, `${JSON.stringify(cacheable, null, 2)}\n`, 'utf8');
+}