feat: add host llm policy routing

Author: jddunn

docs/PARACOSM.md

@@ -3,7 +3,7 @@ title: "Paracosm — AI Simulation Engine"
 sidebar_position: 1
 ---
 
-Paracosm is an AI agent swarm simulation engine built on AgentOS. Define a scenario as JSON, run it with AI commanders that have different [HEXACO](/features/hexaco-personality) personality profiles, and watch their decisions diverge into measurably different outcomes from the same seed. The reference scenario ships as Mars Genesis: a thirty-colonist Mars colony running from 2035 to 2067 across six turns.
+Paracosm is an AI agent swarm simulation engine built on AgentOS. Define a scenario as JSON, run it with AI commanders that have different [HEXACO](/features/cognitive-memory) personality profiles, and watch their decisions diverge into measurably different outcomes from the same seed. The reference scenario ships as Mars Genesis: a thirty-colonist Mars colony running from 2035 to 2067 across six turns.
 
 **[Live demo](https://paracosm.agentos.sh/sim)** · **[GitHub](https://github.com/framersai/paracosm)** · **[npm](https://www.npmjs.com/package/paracosm)** · **[API reference](/paracosm)** · **[Case study blog post](https://agentos.sh/blog/inside-mars-genesis-ai-colony-simulation)**
 
@@ -61,7 +61,7 @@ Two runs on the same seed produce identical deterministic stages. The LLM stages
 
 ## How HEXACO drives decisions
 
-Paracosm uses the [HEXACO model](/features/hexaco-personality) (Ashton & Lee, 2007) across all six axes, with both poles producing concrete behavioral cues in the commander's decision-style block and the department analysis prompts:
+Paracosm uses the [HEXACO model](/features/cognitive-memory) (Ashton & Lee, 2007) across all six axes, with both poles producing concrete behavioral cues in the commander's decision-style block and the department analysis prompts:
 
 - **Openness** — high: favor novel, untested approaches; low: trust proven protocols.
 - **Conscientiousness** — high: demand evidence and contingency plans; low: move fast, accept ambiguity.
@@ -100,7 +100,7 @@ Any domain works. Mars colonies, submarine habitats, space stations, medieval ki
 }
 ```
 
-`compileScenario()` turns JSON into a runnable `ScenarioPackage` by generating TypeScript hook functions via LLM calls. Compilation costs about $0.10 per scenario and caches to disk. See [`compileScenario`](/paracosm/functions/compileScenario) for the full hook contract.
+`compileScenario()` turns JSON into a runnable `ScenarioPackage` by generating TypeScript hook functions via LLM calls. Compilation costs about $0.10 per scenario and caches to disk. See [`compileScenario`](/paracosm/engine/compiler/functions/compileScenario) for the full hook contract.
 
 ## Cost safety
 
@@ -128,8 +128,8 @@ Full type reference is auto-generated from source at [/paracosm](/paracosm). The
 - [`LeaderConfig`](/paracosm/interfaces/LeaderConfig) — commander identity + HEXACO profile
 - [`HexacoProfile`](/paracosm/interfaces/HexacoProfile) — six-axis personality vector
 - [`SimulationKernel`](/paracosm/classes/SimulationKernel) — deterministic state machine
-- [`runSimulation`](/paracosm/functions/runSimulation) — single-leader turn loop
-- [`runBatch`](/paracosm/functions/runBatch) — parallel multi-scenario runner
+- [`runSimulation`](/paracosm/runtime/functions/runSimulation) — single-leader turn loop
+- [`runBatch`](/paracosm/runtime/functions/runBatch) — parallel multi-scenario runner
 
 ## HTTP + SSE server
 
@@ -151,7 +151,7 @@ The dashboard server exposes a small HTTP API for driving sims from any client:
 ## Related
 
 - [Emergent Capabilities](/features/emergent-capabilities) — the forge + judge machinery underlying `forge_tool`
-- [HEXACO Personality](/features/hexaco-personality) — trait model, mutation system, persona overlays
+- [HEXACO Personality](/features/cognitive-memory) — trait model, mutation system, persona overlays
 - [Cognitive Memory Guide](/features/cognitive-memory-guide) — the memory pipeline colonists use as chat agents
 - [Inside Mars Genesis (blog)](https://agentos.sh/blog/inside-mars-genesis-ai-colony-simulation) — full case study
 - [Emergent Tools and HEXACO Leaders (blog)](https://agentos.sh/blog/emergent-tools-hexaco-leaders) — two-leader-one-seed comparison

docs/architecture/EMERGENT_CAPABILITIES.md

@@ -529,4 +529,4 @@ await exportToolAsSkillPack(forgedTool, './skills/slugify');
 - [Recursive Self-Building](/features/recursive-self-building) -- recursive tool creation and agent spawning
 - [Guardrails](/features/guardrails) -- safety mechanisms that constrain emergent behavior
 - [Agency API](/features/agency-api) -- multi-agent coordination strategies
-- **API Reference:** [`EmergentCapabilityEngine`](/api/classes/EmergentCapabilityEngine) | [`EmergentJudge`](/api/classes/EmergentJudge) | [`EmergentToolRegistry`](/api/classes/EmergentToolRegistry) | [`ForgeToolMetaTool`](/api/classes/ForgeToolMetaTool) | [`ComposableToolBuilder`](/api/classes/ComposableToolBuilder) | [`CodeSandbox`](/api/classes/CodeSandbox) | [`AdaptPersonalityTool`](/api/classes/AdaptPersonalityTool) | [`ManageSkillsTool`](/api/classes/ManageSkillsTool) | [`SelfEvaluateTool`](/api/classes/SelfEvaluateTool) | [`CreateWorkflowTool`](/api/classes/CreateWorkflowTool) | [`SkillExporter`](/api/classes/SkillExporter)
+- **API Reference:** [`EmergentCapabilityEngine`](/api/classes/EmergentCapabilityEngine) | [`EmergentJudge`](/api/classes/EmergentJudge) | [`EmergentToolRegistry`](/api/classes/EmergentToolRegistry) | [`ForgeToolMetaTool`](/api/classes/ForgeToolMetaTool) | [`ComposableToolBuilder`](/api/classes/ComposableToolBuilder) | [`CodeSandbox`](/api/classes/CodeSandbox) | [`AdaptPersonalityTool`](/api/classes/AdaptPersonalityTool) | [`ManageSkillsTool`](/api/classes/ManageSkillsTool) | [`SelfEvaluateTool`](/api/classes/SelfEvaluateTool) | [`CreateWorkflowTool`](/api/classes/CreateWorkflowTool) | [`exportToolAsSkill`](/api/functions/exportToolAsSkill)

docs/publication-manifest.cjs

@@ -215,6 +215,8 @@ const publicationManifest = [
 
   agentosDoc('IMAGE_GENERATION.md', 'features/image-generation.md', 'Image Generation', 'Media Generation', 1),
   agentosDoc('IMAGE_EDITING.md', 'features/image-editing.md', 'Image Editing (Img2Img, Inpainting, Upscaling)', 'Media Generation', 2),
+  agentosDoc('CHARACTER_CONSISTENCY.md', 'features/character-consistency.md', 'Character Consistency', 'Media Generation', 2.5),
+  agentosDoc('STYLE_TRANSFER.md', 'features/style-transfer.md', 'Style Transfer', 'Media Generation', 2.6),
   agentosDoc('VISION_PIPELINE.md', 'features/vision-pipeline.md', 'Vision Pipeline (OCR & Image Understanding)', 'Media Generation', 3),
   staticDoc('features/audio-generation.md', 'features/audio-generation.md', 'Audio Generation', 'Media Generation', 4),
   staticDoc('features/provider-preferences.md', 'features/provider-preferences.md', 'Provider Preferences', 'Media Generation', 5),
@@ -228,6 +230,7 @@ const publicationManifest = [
   siteDoc('features/llm-output-validation.md', 'features/llm-output-validation.md', 'LLM Output Validation', 'AI & LLM', 1.5),
   agentosDoc('EVALUATION.md', 'features/evaluation-guide.md', 'Evaluation Guide', 'AI & LLM', 2),
   agentosDoc('COST_OPTIMIZATION.md', 'features/cost-optimization.md', 'Cost Optimization', 'AI & LLM', 3),
+  agentosDoc('UNCENSORED_CONTENT.md', 'features/uncensored-content.md', 'Uncensored Content & Policy-Tier Routing', 'AI & LLM', 3.5),
   agentosDoc('EVALUATION_FRAMEWORK.md', 'features/evaluation-framework.md', 'Evaluation Framework', 'AI & LLM', 4, {
     sidebar: false,
   }),

src/api/agent.ts

@@ -21,6 +21,7 @@ import {
   type ToolCallHookInfo,
 } from './generateText.js';
 import { streamText, type StreamTextResult } from './streamText.js';
+import type { HostLLMPolicy } from './runtime/hostPolicy.js';
 import type { IModelRouter } from '../core/llm/routing/IModelRouter.js';
 import type { SkillEntry } from '../skills/types.js';
 import type {
@@ -71,6 +72,8 @@ export interface AgentOptions extends BaseAgentConfig {
   onFallback?: (error: Error, fallbackProvider: string) => void;
   /** Model router for intelligent provider selection per-call. */
   router?: IModelRouter;
+  /** Host-level routing hints forwarded to the high-level generation helpers. */
+  hostPolicy?: HostLLMPolicy;
   /**
    * Routing hints passed to the model router's `selectModel()` call.
    *
@@ -391,6 +394,7 @@ export function agent(opts: AgentOptions): Agent {
     fallbackProviders: opts.fallbackProviders,
     onFallback: opts.onFallback,
     router: opts.router,
+    hostPolicy: opts.hostPolicy,
     routerParams: opts.routerParams,
     onBeforeGeneration: opts.onBeforeGeneration,
     onAfterGeneration: opts.onAfterGeneration,

src/api/generateText.ts

@@ -14,6 +14,11 @@
 import { randomUUID } from 'node:crypto';
 import { resolveModelOption, resolveProvider, createProviderManager } from './model.js';
 import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import {
+  hostPolicyToRouteParams,
+  mergeRequiredCapabilities,
+  type HostLLMPolicy,
+} from './runtime/hostPolicy.js';
 import { adaptTools, type AdaptableToolInput } from './runtime/toolAdapter.js';
 import type { AgentOSUsageLedgerOptions } from './runtime/usageLedger.js';
 import { resolveDynamicToolCalls } from './runtime/dynamicToolCalling.js';
@@ -31,6 +36,7 @@ import type {
 
 // Re-export multimodal types for downstream consumers
 export type { MessageContent, MessageContentPart };
+export type { HostLLMPolicy } from './runtime/hostPolicy.js';
 
 async function recordAgentOSUsageLazy(
   input: Parameters<typeof import('./runtime/usageLedger.js')['recordAgentOSUsage']>[0]
@@ -303,6 +309,11 @@ export interface GenerateTextOptions {
    * from system prompt and tool names when not provided.
    */
   routerParams?: Partial<ModelRouteParams>;
+  /**
+   * Host-level routing hints that can be forwarded into the model router
+   * without requiring callers to construct raw router params directly.
+   */
+  hostPolicy?: HostLLMPolicy;
   /**
    * Called before each LLM generation step.  Can inject memory context
    * into messages, sanitize input via guardrails, or modify the prompt.
@@ -726,15 +737,28 @@ export async function generateText(opts: GenerateTextOptions): Promise<GenerateT
                 .map((t: any) => t.name ?? t.function?.name)
                 .filter(Boolean) as string[]
             : [];
+          const hostPolicyRouteParams = hostPolicyToRouteParams(opts.hostPolicy);
+          const requiredCapabilities = mergeRequiredCapabilities(
+            hostPolicyRouteParams.requiredCapabilities,
+            opts.routerParams?.requiredCapabilities,
+            toolNames.length > 0 ? ['function_calling'] : undefined,
+          );
           const routeParams: ModelRouteParams = {
             taskHint:
               opts.routerParams?.taskHint ?? (typeof opts.system === 'string' ? opts.system : undefined) ?? opts.prompt ?? '',
-            requiredCapabilities:
-              opts.routerParams?.requiredCapabilities ??
-              (toolNames.length > 0 ? ['function_calling'] : undefined),
-            optimizationPreference:
-              opts.routerParams?.optimizationPreference ?? 'balanced',
+            ...hostPolicyRouteParams,
             ...opts.routerParams,
+            optimizationPreference:
+              opts.routerParams?.optimizationPreference
+              ?? hostPolicyRouteParams.optimizationPreference
+              ?? 'balanced',
+            requiredCapabilities,
+            preferredProviderIds:
+              opts.routerParams?.preferredProviderIds
+              ?? hostPolicyRouteParams.preferredProviderIds,
+            policyTier:
+              opts.routerParams?.policyTier
+              ?? hostPolicyRouteParams.policyTier,
           };
           const routeResult = await opts.router.selectModel(
             routeParams,

src/api/index.ts

@@ -23,10 +23,12 @@ export {
   type GenerateTextOptions,
   type GenerateTextResult,
   type FallbackProviderEntry,
+  type HostLLMPolicy,
   type Message,
   type ToolCallRecord,
   type TokenUsage,
 } from './generateText.js';
+export { normalizeHostLLMPolicy } from './runtime/hostPolicy.js';
 export { streamText } from './streamText.js';
 export { generateObject } from './generateObject.js';
 export { streamObject } from './streamObject.js';

src/api/runtime/__tests__/hostPolicy.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeHostLLMPolicy } from '../hostPolicy.js';
+
+describe('HostLLMPolicy', () => {
+  it('normalizes optimization, capability, and fallback hints for host apps', () => {
+    const policy = normalizeHostLLMPolicy({
+      optimizationPreference: 'cost',
+      requiredCapabilities: ['json_mode', 'tool_use'],
+      allowedProviders: ['openai', 'anthropic'],
+      fallbackProviders: [{ provider: 'openai', model: 'gpt-4.1-mini' }],
+      cacheDiscipline: 'stable_prefix',
+    });
+
+    expect(policy.optimizationPreference).toBe('cost');
+    expect(policy.requiredCapabilities).toEqual(['json_mode', 'tool_use']);
+    expect(policy.allowedProviders).toEqual(['openai', 'anthropic']);
+    expect(policy.fallbackProviders).toEqual([{ provider: 'openai', model: 'gpt-4.1-mini' }]);
+    expect(policy.policyTier).toBe('standard');
+    expect(policy.cacheDiscipline).toBe('stable_prefix');
+  });
+});

src/api/runtime/__tests__/modelRouter.test.ts

@@ -163,6 +163,31 @@ describe('ModelRouter integration', () => {
     );
   });
 
+  it('threads hostPolicy hints into router selection', async () => {
+    const router = createMockRouter(null);
+
+    await generateText({
+      prompt: 'hello',
+      router,
+      hostPolicy: {
+        optimizationPreference: 'cost',
+        requiredCapabilities: ['json_mode'],
+        allowedProviders: ['anthropic'],
+        policyTier: 'mature',
+      },
+    });
+
+    expect(router.selectModel).toHaveBeenCalledWith(
+      expect.objectContaining({
+        optimizationPreference: 'cost',
+        requiredCapabilities: ['json_mode'],
+        preferredProviderIds: ['anthropic'],
+        policyTier: 'mature',
+      }),
+      undefined,
+    );
+  });
+
   it('auto-extracts taskHint from system prompt when routerParams not provided', async () => {
     const router = createMockRouter(null);
 

src/api/runtime/hostPolicy.ts

@@ -0,0 +1,47 @@
+import type { ModelRouteParams } from '../../core/llm/routing/IModelRouter.js';
+
+export interface HostLLMPolicy {
+  optimizationPreference?: 'cost' | 'speed' | 'quality' | 'balanced';
+  requiredCapabilities?: string[];
+  allowedProviders?: string[];
+  fallbackProviders?: Array<{ provider: string; model?: string }>;
+  policyTier?: 'safe' | 'standard' | 'mature' | 'private-adult';
+  cacheDiscipline?: 'none' | 'stable_prefix' | 'structured_blocks';
+}
+
+export function normalizeHostLLMPolicy(input: HostLLMPolicy = {}): Required<HostLLMPolicy> {
+  return {
+    optimizationPreference: input.optimizationPreference ?? 'balanced',
+    requiredCapabilities: input.requiredCapabilities ?? [],
+    allowedProviders: input.allowedProviders ?? [],
+    fallbackProviders: input.fallbackProviders ?? [],
+    policyTier: input.policyTier ?? 'standard',
+    cacheDiscipline: input.cacheDiscipline ?? 'none',
+  };
+}
+
+export function hostPolicyToRouteParams(hostPolicy?: HostLLMPolicy): Partial<ModelRouteParams> {
+  if (!hostPolicy) return {};
+
+  const normalized = normalizeHostLLMPolicy(hostPolicy);
+  return {
+    optimizationPreference: normalized.optimizationPreference,
+    requiredCapabilities:
+      normalized.requiredCapabilities.length > 0 ? [...normalized.requiredCapabilities] : undefined,
+    preferredProviderIds:
+      normalized.allowedProviders.length > 0 ? [...normalized.allowedProviders] : undefined,
+    policyTier: normalized.policyTier,
+  };
+}
+
+export function mergeRequiredCapabilities(
+  ...capabilitySets: Array<string[] | undefined>
+): string[] | undefined {
+  const merged = capabilitySets
+    .flatMap((capabilities) => capabilities ?? [])
+    .filter((capability, index, allCapabilities) => {
+      return capability.length > 0 && allCapabilities.indexOf(capability) === index;
+    });
+
+  return merged.length > 0 ? merged : undefined;
+}

src/api/streamText.ts

@@ -10,6 +10,7 @@
 import { randomUUID } from 'node:crypto';
 import { resolveModelOption, resolveProvider, createProviderManager } from './model.js';
 import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { hostPolicyToRouteParams, mergeRequiredCapabilities } from './runtime/hostPolicy.js';
 import { adaptTools } from './runtime/toolAdapter.js';
 import {
   buildFallbackChain,
@@ -164,15 +165,28 @@ export function streamText(opts: GenerateTextOptions): StreamTextResult {
                 .map((t: any) => t.name ?? t.function?.name)
                 .filter(Boolean) as string[]
             : [];
+          const hostPolicyRouteParams = hostPolicyToRouteParams(opts.hostPolicy);
+          const requiredCapabilities = mergeRequiredCapabilities(
+            hostPolicyRouteParams.requiredCapabilities,
+            opts.routerParams?.requiredCapabilities,
+            toolNames.length > 0 ? ['function_calling'] : undefined,
+          );
           const routeParams: ModelRouteParams = {
             taskHint:
               opts.routerParams?.taskHint ?? (typeof opts.system === 'string' ? opts.system : undefined) ?? opts.prompt ?? '',
-            requiredCapabilities:
-              opts.routerParams?.requiredCapabilities ??
-              (toolNames.length > 0 ? ['function_calling'] : undefined),
-            optimizationPreference:
-              opts.routerParams?.optimizationPreference ?? 'balanced',
+            ...hostPolicyRouteParams,
             ...opts.routerParams,
+            optimizationPreference:
+              opts.routerParams?.optimizationPreference
+              ?? hostPolicyRouteParams.optimizationPreference
+              ?? 'balanced',
+            requiredCapabilities,
+            preferredProviderIds:
+              opts.routerParams?.preferredProviderIds
+              ?? hostPolicyRouteParams.preferredProviderIds,
+            policyTier:
+              opts.routerParams?.policyTier
+              ?? hostPolicyRouteParams.policyTier,
           };
           const routeResult = await opts.router.selectModel(
             routeParams,