fix(agentos): remove eager usage-ledger imports from lightweight API paths

Deferred UsageLedger imports in agent.ts, generateText.ts, and
streamText.ts to avoid pulling heavy dependency chains when only
the lightweight generation API is used.

Author: jddunn

README.md

@@ -179,6 +179,44 @@ console.log(followUp.text);
 const config = tutor.exportJSON();
 ```
 
+The lightweight API also supports per-call model routing and lifecycle middleware without booting the full `AgentOS` runtime:
+
+```typescript
+import type { IModelRouter } from '@framers/agentos';
+
+const router: IModelRouter = {
+  routerId: 'fast-vs-quality',
+  async initialize() {},
+  async selectModel(params) {
+    if (params.optimizationPreference === 'speed') {
+      return null; // fall back to the caller's provider/model
+    }
+    return null;
+  },
+};
+
+const reviewer = agent({
+  instructions: 'Review drafts for policy and tone.',
+  router,
+  skills: [{
+    skill: {
+      name: 'policy-review',
+      description: 'Review output before it is shown to users.',
+      content: 'Flag unsafe content and keep the tone concise.',
+    },
+    frontmatter: {} as any,
+  }],
+  onBeforeGeneration: async (ctx) => ({
+    ...ctx,
+    messages: [{ role: 'system', content: 'User is on the free plan.' }, ...ctx.messages],
+  }),
+  onAfterGeneration: async (result) => ({
+    ...result,
+    text: result.text.trim(),
+  }),
+});
+```
+
 ### 5. Multimodal (Image, Video, Audio, OCR, Embeddings)
 
 ```typescript

package.json

@@ -12,6 +12,26 @@
       "default": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./api": {
+      "import": "./dist/api/index.js",
+      "default": "./dist/api/index.js",
+      "types": "./dist/api/index.d.ts"
+    },
+    "./api/agent": {
+      "import": "./dist/api/agent.js",
+      "default": "./dist/api/agent.js",
+      "types": "./dist/api/agent.d.ts"
+    },
+    "./api/generateText": {
+      "import": "./dist/api/generateText.js",
+      "default": "./dist/api/generateText.js",
+      "types": "./dist/api/generateText.d.ts"
+    },
+    "./api/streamText": {
+      "import": "./dist/api/streamText.js",
+      "default": "./dist/api/streamText.js",
+      "types": "./dist/api/streamText.d.ts"
+    },
     "./config/extension-secrets.json": "./dist/config/extension-secrets.json",
     "./skills": {
       "import": "./dist/skills.js",

src/api/agent.ts

@@ -21,13 +21,12 @@ import {
 import { streamText, type StreamTextResult } from './streamText.js';
 import type { IModelRouter } from '../core/llm/routing/IModelRouter.js';
 import type { SkillEntry } from '../skills/types.js';
-import {
-  getRecordedAgentOSUsage,
-  type AgentOSUsageAggregate,
-  type AgentOSUsageLedgerOptions,
+import type {
+  AgentOSUsageAggregate,
+  AgentOSUsageLedgerOptions,
 } from './runtime/usageLedger.js';
 import type { BaseAgentConfig } from './types.js';
-import { exportAgentConfig, exportAgentConfigJSON, type AgentExportConfig } from './agentExport.js';
+import { exportAgentConfig, exportAgentConfigJSON, type AgentExportConfig } from './agentExportCore.js';
 
 /**
  * Configuration options for the {@link agent} factory function.
@@ -173,6 +172,13 @@ function mergeUsageLedgerOptions(
   return Object.keys(merged).length > 0 ? merged : undefined;
 }
 
+async function loadRecordedAgentOSUsage(
+  options?: Pick<AgentOSUsageLedgerOptions, 'enabled' | 'path' | 'sessionId' | 'personaId'>
+): Promise<AgentOSUsageAggregate> {
+  const { getRecordedAgentOSUsage } = await import('./runtime/usageLedger.js');
+  return getRecordedAgentOSUsage(options);
+}
+
 /** Timeout for memory operations to prevent blocking generation. */
 const MEMORY_TIMEOUT_MS = 5000;
 
@@ -423,7 +429,7 @@ export function agent(opts: AgentOptions): Agent {
         },
 
         async usage(): Promise<AgentOSUsageAggregate> {
-          return getRecordedAgentOSUsage({
+          return loadRecordedAgentOSUsage({
             enabled: baseOpts.usageLedger?.enabled,
             path: baseOpts.usageLedger?.path,
             sessionId,
@@ -437,7 +443,7 @@ export function agent(opts: AgentOptions): Agent {
     },
 
     async usage(sessionId?: string): Promise<AgentOSUsageAggregate> {
-      return getRecordedAgentOSUsage({
+      return loadRecordedAgentOSUsage({
         enabled: baseOpts.usageLedger?.enabled,
         path: baseOpts.usageLedger?.path,
         sessionId,

src/api/agentExport.ts

@@ -34,186 +34,10 @@ import YAML from 'yaml';
 import { agent as createAgent } from './agent.js';
 import { agency as createAgency } from './agency.js';
 import type { BaseAgentConfig, AgencyOptions, AgencyStrategy, Agent } from './types.js';
-
-// ============================================================================
-// EXPORT CONFIG TYPE
-// ============================================================================
-
-/**
- * Portable agent configuration envelope.
- *
- * Wraps a `BaseAgentConfig` with version metadata, export timestamp,
- * and type discriminator so import logic can reconstruct the correct agent
- * variant (single agent vs. multi-agent agency).
- */
-export interface AgentExportConfig {
-  /** Schema version for forward-compatible deserialization. */
-  version: '1.0.0';
-
-  /** ISO 8601 timestamp of when the export was created. */
-  exportedAt: string;
-
-  /**
-   * Discriminator: `'agent'` for a single-agent export, `'agency'` for
-   * a multi-agent export that includes a sub-agent roster.
-   */
-  type: 'agent' | 'agency';
-
-  /** The full agent configuration. */
-  config: BaseAgentConfig;
-
-  // -- Agency-specific fields (present when `type === 'agency'`) --
-
-  /** Sub-agent roster keyed by agent name. Present for agency exports. */
-  agents?: Record<string, BaseAgentConfig>;
-
-  /** Orchestration strategy. Present for agency exports. */
-  strategy?: AgencyStrategy;
-
-  /** Whether runtime strategy adaptation is enabled. */
-  adaptive?: boolean;
-
-  /** Maximum orchestration rounds for iterative strategies. */
-  maxRounds?: number;
-
-  // -- Optional metadata --
-
-  /** Human-readable metadata about the export (name, author, tags, etc.). */
-  metadata?: {
-    /** Display name for the exported agent. */
-    name?: string;
-    /** Free-text description of what this agent does. */
-    description?: string;
-    /** Author identifier (person or system). */
-    author?: string;
-    /** Searchable tags for categorization. */
-    tags?: string[];
-  };
-}
-
-// ============================================================================
-// EXPORT FUNCTIONS
-// ============================================================================
-
-/**
- * Extracts the stored configuration from an Agent instance.
- *
- * The agent's config is captured at creation time by the `agent()` and
- * `agency()` factories and attached as a non-enumerable `__config` property.
- * If the property is absent (e.g. the agent was created by external code),
- * we return an empty config.
- *
- * @param agentInstance - The agent to extract config from.
- * @returns The stored BaseAgentConfig or an empty object.
- */
-function extractConfig(agentInstance: Agent): BaseAgentConfig {
-  // The __config property is set by our patched agent/agency factories
-  const config = (agentInstance as unknown as Record<string, unknown>).__config;
-  if (config && typeof config === 'object') {
-    return config as BaseAgentConfig;
-  }
-  // Fallback: no stored config — return empty
-  return {};
-}
-
-/**
- * Extracts agency-specific fields from an Agent instance that was created
- * by the `agency()` factory.
- *
- * @param agentInstance - The agent/agency to extract from.
- * @returns Agency fields if present, or undefined for plain agents.
- */
-function extractAgencyFields(agentInstance: Agent):
-  | {
-      agents?: Record<string, BaseAgentConfig>;
-      strategy?: AgencyStrategy;
-      adaptive?: boolean;
-      maxRounds?: number;
-    }
-  | undefined {
-  const raw = (agentInstance as unknown as Record<string, unknown>).__agencyConfig;
-  if (raw && typeof raw === 'object') {
-    return raw as {
-      agents?: Record<string, BaseAgentConfig>;
-      strategy?: AgencyStrategy;
-      adaptive?: boolean;
-      maxRounds?: number;
-    };
-  }
-  return undefined;
-}
-
-/**
- * Exports an agent's configuration as a portable {@link AgentExportConfig} object.
- *
- * Captures the full `BaseAgentConfig` including model, instructions,
- * personality, tools, guardrails, memory, RAG, voice, channels, and all
- * other configuration surfaces. For agency instances, the sub-agent roster,
- * strategy, and round limits are also included.
- *
- * @param agentInstance - The agent (or agency) instance to export.
- * @param metadata - Optional human-readable metadata to attach to the export.
- * @returns A portable config object that can be serialized to JSON or YAML.
- *
- * @example
- * ```ts
- * const config = exportAgentConfig(myAgent, {
- *   name: 'Research Assistant',
- *   author: 'team-alpha',
- *   tags: ['research', 'summarization'],
- * });
- * ```
- */
-export function exportAgentConfig(
-  agentInstance: Agent,
-  metadata?: AgentExportConfig['metadata']
-): AgentExportConfig {
-  const config = extractConfig(agentInstance);
-  const agencyFields = extractAgencyFields(agentInstance);
-
-  const isAgency = !!agencyFields?.agents;
-
-  const exportConfig: AgentExportConfig = {
-    version: '1.0.0',
-    exportedAt: new Date().toISOString(),
-    type: isAgency ? 'agency' : 'agent',
-    config,
-  };
-
-  // Attach agency-specific fields when present
-  if (isAgency && agencyFields) {
-    exportConfig.agents = agencyFields.agents;
-    exportConfig.strategy = agencyFields.strategy;
-    exportConfig.adaptive = agencyFields.adaptive;
-    exportConfig.maxRounds = agencyFields.maxRounds;
-  }
-
-  if (metadata) {
-    exportConfig.metadata = metadata;
-  }
-
-  return exportConfig;
-}
-
-/**
- * Exports an agent's configuration as a pretty-printed JSON string.
- *
- * @param agentInstance - The agent (or agency) instance to export.
- * @param metadata - Optional human-readable metadata to attach.
- * @returns JSON string with 2-space indentation.
- *
- * @example
- * ```ts
- * const json = exportAgentConfigJSON(myAgent);
- * fs.writeFileSync('agent.json', json);
- * ```
- */
-export function exportAgentConfigJSON(
-  agentInstance: Agent,
-  metadata?: AgentExportConfig['metadata']
-): string {
-  return JSON.stringify(exportAgentConfig(agentInstance, metadata), null, 2);
-}
+import { exportAgentConfig, exportAgentConfigJSON } from './agentExportCore.js';
+export { exportAgentConfig, exportAgentConfigJSON };
+export type { AgentExportConfig } from './agentExportCore.js';
+import type { AgentExportConfig } from './agentExportCore.js';
 
 /**
  * Exports an agent's configuration as a YAML string.