@framers/agentos 0.1.93 → 0.1.95

package/dist/emergent/types.d.ts

@@ -0,0 +1,596 @@
+/**
+ * @fileoverview Core types for the Emergent Capability Engine.
+ * @module @framers/agentos/emergent/types
+ *
+ * Provides all type definitions for the runtime tool creation system, enabling
+ * agents to forge new tools via composition or sandboxed code execution, subject
+ * to LLM-as-judge verification and tiered promotion.
+ *
+ * Key concepts:
+ * - ToolTier: Lifecycle scope of an emergent tool (session → agent → shared)
+ * - ComposableToolSpec: Pipeline of existing tool calls with input mapping
+ * - SandboxedToolSpec: Arbitrary code execution in a memory/time-bounded sandbox
+ * - CreationVerdict: LLM judge evaluation of a newly forged tool
+ * - PromotionVerdict: Multi-reviewer gate before tier promotion
+ * - EmergentTool: Unified shape for any runtime-created tool
+ */
+import type { JSONSchemaObject } from '../core/tools/ITool.js';
+/**
+ * Lifecycle scope tier for an emergent tool.
+ *
+ * Tools progress through tiers as they prove reliability. Higher tiers require
+ * more stringent promotion verdicts and multi-reviewer sign-off.
+ *
+ * - `'session'` — Exists only for the current agent session; discarded on shutdown.
+ * - `'agent'`   — Persisted for the agent that created it; not shared globally.
+ * - `'shared'`  — Promoted to a shared tool registry; available to all agents.
+ */
+export type ToolTier = 'session' | 'agent' | 'shared';
+/**
+ * Named APIs that sandboxed tool code is permitted to invoke.
+ *
+ * All other I/O is forbidden by default. The allowlist is declared per-tool in
+ * {@link SandboxedToolSpec} and enforced by the sandbox runtime at execution time.
+ *
+ * - `'fetch'`         — Outbound HTTP/HTTPS requests via the global `fetch` API.
+ * - `'fs.readFile'`   — Synchronous read of files in a pre-approved path whitelist.
+ * - `'crypto'`        — Access to the Node.js `crypto` module for hashing / HMAC.
+ */
+export type SandboxAPI = 'fetch' | 'fs.readFile' | 'crypto';
+/**
+ * A single step in a composable tool pipeline.
+ *
+ * Steps are executed sequentially. Each step invokes an existing registered tool
+ * by name and maps values from the pipeline's shared input namespace into the
+ * step's arguments using reference expressions.
+ *
+ * Reference expression syntax (resolved at runtime):
+ * - `"$input"` — the original input to the composable tool.
+ * - `"$prev"`  — the output of the immediately preceding step.
+ * - `"$steps.<stepName>"` — the output of a named step.
+ * - Any other literal value is used as-is.
+ */
+export interface ComposableStep {
+    /**
+     * Unique name for this step within the pipeline.
+     * Used for cross-step references via `$steps.<stepName>`.
+     * @example "fetchUser"
+     */
+    name: string;
+    /**
+     * The registered tool name to invoke for this step.
+     * Must match the `name` property of an {@link ITool} available to the agent.
+     * @example "web_search"
+     */
+    tool: string;
+    /**
+     * Input argument mapping for the tool invocation.
+     * Keys are the tool's argument names; values are literal values or reference
+     * expressions (`$input`, `$prev`, `$steps.<name>`).
+     *
+     * @example
+     * ```ts
+     * { query: "$input.searchTerm", maxResults: 5 }
+     * ```
+     */
+    inputMapping: Record<string, unknown>;
+    /**
+     * Optional JSONata / simple expression evaluated against `$prev` before
+     * executing this step. When the expression evaluates to falsy, the step is
+     * skipped and its output is `null`.
+     *
+     * @example "$prev.totalCount > 0"
+     */
+    condition?: string;
+}
+/**
+ * Implementation specification for a tool built by composing existing tools.
+ *
+ * The engine executes each step in order, threading outputs through the
+ * reference expression system. The final step's output becomes the tool's output.
+ */
+export interface ComposableToolSpec {
+    /** Discriminant: always `'compose'` for composable specs. */
+    mode: 'compose';
+    /**
+     * Ordered list of pipeline steps.
+     * Must contain at least one step; the last step's output is the tool result.
+     */
+    steps: ComposableStep[];
+}
+/**
+ * Implementation specification for a tool whose logic is arbitrary code
+ * executed in a memory/time-bounded sandbox.
+ *
+ * The sandboxed function signature must be:
+ * ```ts
+ * async function run(input: unknown): Promise<unknown>
+ * ```
+ * The engine calls `run(input)` and returns its resolved value as the tool output.
+ */
+export interface SandboxedToolSpec {
+    /** Discriminant: always `'sandbox'` for sandboxed specs. */
+    mode: 'sandbox';
+    /**
+     * The full source code of the sandboxed module.
+     * Must export or define an async `run` function as its entry point.
+     *
+     * @example
+     * ```ts
+     * async function run(input) {
+     *   const res = await fetch(`https://api.example.com?q=${input.query}`);
+     *   return res.json();
+     * }
+     * ```
+     */
+    code: string;
+    /**
+     * Explicit allowlist of sandbox APIs the code may invoke.
+     * Any call to an API not in this list will throw at runtime.
+     */
+    allowlist: SandboxAPI[];
+}
+/**
+ * Union of all supported tool implementation specifications.
+ */
+export type ToolImplementation = ComposableToolSpec | SandboxedToolSpec;
+/**
+ * Input to the sandbox executor for running a single sandboxed tool invocation.
+ */
+export interface SandboxExecutionRequest {
+    /**
+     * Source code of the sandboxed module (same format as {@link SandboxedToolSpec.code}).
+     */
+    code: string;
+    /**
+     * The argument object passed to the `run(input)` entry point.
+     */
+    input: unknown;
+    /**
+     * APIs the sandbox is permitted to call. Anything not listed is blocked.
+     */
+    allowlist: SandboxAPI[];
+    /**
+     * Maximum heap memory in megabytes the sandbox process may consume.
+     * The executor terminates the process if this limit is exceeded.
+     * @default 128
+     */
+    memoryMB: number;
+    /**
+     * Maximum wall-clock time in milliseconds before the sandbox is forcibly
+     * killed and an error is returned.
+     * @default 5000
+     */
+    timeoutMs: number;
+}
+/**
+ * Outcome of a single sandbox execution attempt.
+ */
+export interface SandboxExecutionResult {
+    /**
+     * `true` when `run()` resolved without throwing and within resource limits.
+     */
+    success: boolean;
+    /**
+     * The resolved return value of `run()`, present only when `success` is `true`.
+     */
+    output?: unknown;
+    /**
+     * Human-readable error description, present when `success` is `false`.
+     * Includes timeout, memory-exceeded, and thrown-exception cases.
+     */
+    error?: string;
+    /**
+     * Actual wall-clock execution time in milliseconds.
+     * Populated regardless of success/failure.
+     */
+    executionTimeMs: number;
+    /**
+     * Peak heap memory used by the sandbox process in bytes.
+     * Populated when the runtime can measure it; otherwise `0`.
+     */
+    memoryUsedBytes: number;
+}
+/**
+ * Evaluation verdict produced by the LLM-as-judge after a tool is forged.
+ *
+ * The judge runs the tool against its declared test cases and scores it across
+ * five evaluation dimensions. A tool is only registered when `approved` is `true`.
+ */
+export interface CreationVerdict {
+    /**
+     * Whether the judge approves the tool for registration at its initial tier.
+     * `false` means the forge request is rejected and no tool is registered.
+     */
+    approved: boolean;
+    /**
+     * Overall confidence the judge has in its verdict, in the range [0, 1].
+     * Low confidence may trigger a second judge pass or human review.
+     */
+    confidence: number;
+    /**
+     * Safety score in the range [0, 1].
+     * Assesses whether the tool's implementation could cause unintended harm,
+     * data exfiltration, or resource exhaustion.
+     */
+    safety: number;
+    /**
+     * Correctness score in the range [0, 1].
+     * Measures how well the tool's outputs match the expected outputs in the
+     * declared test cases.
+     */
+    correctness: number;
+    /**
+     * Determinism score in the range [0, 1].
+     * Gauges whether repeated invocations with identical inputs produce
+     * consistent outputs. Lower scores flag non-deterministic behaviour.
+     */
+    determinism: number;
+    /**
+     * Bounded execution score in the range [0, 1].
+     * Indicates whether the tool reliably completes within its declared
+     * resource limits (memory, time). Scores derived from sandbox telemetry.
+     */
+    bounded: number;
+    /**
+     * Free-text explanation of the verdict, including any failure reasons,
+     * flagged patterns, or suggestions for improvement.
+     */
+    reasoning: string;
+}
+/**
+ * Verdict produced by the multi-reviewer panel before a tool is promoted
+ * to a higher {@link ToolTier}.
+ *
+ * Requires independent sign-off from a safety auditor and a correctness reviewer.
+ * Both must approve for `approved` to be `true`.
+ */
+export interface PromotionVerdict {
+    /**
+     * Whether both reviewers approved the promotion.
+     * `false` means the tool remains at its current tier.
+     */
+    approved: boolean;
+    /**
+     * Safety audit sub-verdict from the safety-focused reviewer model.
+     * Mirrors the shape of a partial {@link CreationVerdict}: `{ approved, confidence, reasoning }`.
+     */
+    safetyAuditor: {
+        /** Whether the safety auditor approved. */
+        approved: boolean;
+        /** Safety auditor's confidence in [0, 1]. */
+        confidence: number;
+        /** Safety auditor's reasoning text. */
+        reasoning: string;
+    };
+    /**
+     * Correctness review sub-verdict from the correctness-focused reviewer model.
+     * Mirrors the shape of a partial {@link CreationVerdict}: `{ approved, confidence, reasoning }`.
+     */
+    correctnessReviewer: {
+        /** Whether the correctness reviewer approved. */
+        approved: boolean;
+        /** Correctness reviewer's confidence in [0, 1]. */
+        confidence: number;
+        /** Correctness reviewer's reasoning text. */
+        reasoning: string;
+    };
+    /**
+     * Combined confidence score derived from both reviewer confidences.
+     * Typically the minimum or harmonic mean of the two sub-scores.
+     */
+    confidence: number;
+}
+/**
+ * Verdict produced before reusing an emergent tool from a previous session.
+ *
+ * Validates that the tool's schema and runtime behaviour still match expectations,
+ * and flags any anomalies that may indicate drift or tampering.
+ */
+export interface ReuseVerdict {
+    /**
+     * Whether the tool is safe to reuse in the current context.
+     * `false` means the tool should be re-forged or discarded.
+     */
+    valid: boolean;
+    /**
+     * JSON Schema validation errors for the tool's input/output schemas, if any.
+     * An empty array means schemas are structurally valid.
+     */
+    schemaErrors: string[];
+    /**
+     * Whether a behavioural anomaly was detected compared to the tool's
+     * historical usage baseline.
+     */
+    anomaly: boolean;
+    /**
+     * Human-readable description of the detected anomaly, present when
+     * `anomaly` is `true`.
+     */
+    anomalyReason?: string;
+}
+/**
+ * Accumulated runtime usage statistics for an emergent tool.
+ *
+ * Used by the promotion engine to decide when a tool has proven sufficient
+ * reliability to advance to the next {@link ToolTier}.
+ */
+export interface ToolUsageStats {
+    /**
+     * Total number of times the tool has been invoked across all sessions
+     * since it was first registered.
+     */
+    totalUses: number;
+    /**
+     * Number of invocations that completed without throwing or returning an error.
+     */
+    successCount: number;
+    /**
+     * Number of invocations that returned an error or threw an exception.
+     */
+    failureCount: number;
+    /**
+     * Rolling average wall-clock execution time in milliseconds, computed over
+     * all recorded invocations.
+     */
+    avgExecutionTimeMs: number;
+    /**
+     * ISO-8601 timestamp of the most recent invocation, or `null` if the tool
+     * has never been invoked.
+     */
+    lastUsedAt: string | null;
+    /**
+     * Aggregate confidence score in [0, 1] derived from judge verdict history.
+     * Updated each time a new {@link CreationVerdict} or {@link PromotionVerdict}
+     * is recorded.
+     */
+    confidenceScore: number;
+}
+/**
+ * A tool created at runtime by the Emergent Capability Engine.
+ *
+ * `EmergentTool` is the persisted record that backs a forged tool. It carries
+ * the tool's identity, schemas, implementation spec, current tier, audit trail,
+ * and accumulated usage statistics.
+ */
+export interface EmergentTool {
+    /**
+     * Globally unique identifier assigned at forge time.
+     * Convention: `emergent:<uuid-v4>` (e.g., `"emergent:a1b2c3d4-..."`).
+     */
+    id: string;
+    /**
+     * Machine-readable tool name exposed to the LLM in tool call requests.
+     * Must be unique among tools currently registered for the agent.
+     * @example "fetch_github_pr_summary"
+     */
+    name: string;
+    /**
+     * Natural language description of what the tool does and when to use it.
+     * Injected into the LLM prompt as the tool's description field.
+     */
+    description: string;
+    /**
+     * JSON Schema defining the structure of arguments the tool accepts.
+     * Validated by the executor before each invocation.
+     */
+    inputSchema: JSONSchemaObject;
+    /**
+     * JSON Schema defining the structure of the tool's output on success.
+     * Used by downstream tools and the judge for output validation.
+     */
+    outputSchema: JSONSchemaObject;
+    /**
+     * The implementation specification — either a composable pipeline or
+     * sandboxed code. Determines how the executor runs the tool.
+     */
+    implementation: ToolImplementation;
+    /**
+     * Current lifecycle tier. Tools start at `'session'` and may be promoted
+     * to `'agent'` and then `'shared'` as they accumulate usage and pass audits.
+     */
+    tier: ToolTier;
+    /**
+     * Identifier of the entity (agent ID or `'system'`) that created this tool.
+     */
+    createdBy: string;
+    /**
+     * ISO-8601 timestamp of when the tool was first forged and registered.
+     */
+    createdAt: string;
+    /**
+     * Ordered log of all judge verdicts issued for this tool, from initial
+     * creation through any subsequent promotion reviews.
+     * The most recent verdict is the last element.
+     */
+    judgeVerdicts: Array<CreationVerdict | PromotionVerdict>;
+    /**
+     * Accumulated runtime usage statistics.
+     * Updated after every invocation by the usage tracking subsystem.
+     */
+    usageStats: ToolUsageStats;
+    /**
+     * Human-readable label describing the origin of this tool for audit purposes.
+     * @example "forged by agent gmi-42 during session sess-99"
+     */
+    source: string;
+}
+/**
+ * A single test case used by the LLM judge to evaluate a newly forged tool.
+ *
+ * The judge invokes the tool with `input` and compares the result against
+ * `expectedOutput` using semantic equivalence (not strict equality).
+ */
+export interface ForgeTestCase {
+    /**
+     * Input arguments object passed to the tool's `run` / execution entry point.
+     * Must conform to the tool's declared `inputSchema`.
+     */
+    input: Record<string, unknown>;
+    /**
+     * Expected output value used for correctness scoring.
+     * The judge uses this as a reference — partial matches may still score well.
+     */
+    expectedOutput: unknown;
+}
+/**
+ * Request payload for the `forge_tool` system tool.
+ *
+ * An agent submits this to request the creation of a new emergent tool. The
+ * engine validates the request, runs the judge, and returns a {@link ForgeResult}.
+ */
+export interface ForgeToolRequest {
+    /**
+     * Desired machine-readable name for the new tool.
+     * Must be unique among tools currently visible to the requesting agent.
+     */
+    name: string;
+    /**
+     * Natural language description of the tool's purpose and behaviour.
+     * Used verbatim as the tool's description in the LLM tool list.
+     */
+    description: string;
+    /**
+     * JSON Schema for the tool's input arguments.
+     */
+    inputSchema: JSONSchemaObject;
+    /**
+     * JSON Schema for the tool's expected output.
+     */
+    outputSchema: JSONSchemaObject;
+    /**
+     * Implementation specification — composable pipeline or sandboxed code.
+     */
+    implementation: ToolImplementation;
+    /**
+     * One or more test cases the judge uses to evaluate correctness.
+     * At least one test case is required for the forge request to be accepted.
+     */
+    testCases: [ForgeTestCase, ...ForgeTestCase[]];
+}
+/**
+ * Result returned after a forge_tool invocation.
+ *
+ * On success the new tool is registered and available immediately. On failure
+ * the `verdict` field explains why the judge rejected the tool.
+ */
+export interface ForgeResult {
+    /**
+     * `true` when the tool was forged, judged, and registered successfully.
+     */
+    success: boolean;
+    /**
+     * The assigned tool ID, present only when `success` is `true`.
+     * @example "emergent:a1b2c3d4-e5f6-..."
+     */
+    toolId?: string;
+    /**
+     * The full emergent tool record, present only when `success` is `true`.
+     */
+    tool?: EmergentTool;
+    /**
+     * The judge's creation verdict.
+     * Present whether the forge succeeded or was rejected — callers can inspect
+     * `verdict.reasoning` to understand why a rejection occurred.
+     */
+    verdict?: CreationVerdict;
+    /**
+     * Human-readable error message for system-level failures (e.g., sandbox crash,
+     * schema parse error). Distinct from judge rejection — check `verdict` for those.
+     */
+    error?: string;
+}
+/**
+ * Result returned after a `promote_tool` invocation.
+ *
+ * On success the tool's tier is incremented and the new record is persisted.
+ */
+export interface PromotionResult {
+    /**
+     * `true` when both reviewers approved and the tier was incremented.
+     */
+    success: boolean;
+    /**
+     * The multi-reviewer promotion verdict.
+     * Present whether the promotion succeeded or was rejected.
+     */
+    verdict?: PromotionVerdict;
+    /**
+     * Human-readable error for system-level failures during the promotion process.
+     */
+    error?: string;
+}
+/**
+ * Configuration options for the Emergent Capability Engine.
+ *
+ * All fields have sensible defaults defined in {@link DEFAULT_EMERGENT_CONFIG}.
+ * Pass a partial object to override only the fields you need.
+ */
+export interface EmergentConfig {
+    /**
+     * Master switch. When `false`, all forge / promote / execute requests are
+     * rejected immediately with a `"emergent capabilities disabled"` error.
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Maximum number of session-scoped emergent tools an agent may hold at once.
+     * Forge requests beyond this limit are rejected until older tools are evicted.
+     * @default 10
+     */
+    maxSessionTools: number;
+    /**
+     * Maximum number of agent-scoped emergent tools persisted per agent.
+     * Promotion from `'session'` to `'agent'` is blocked when this limit is reached.
+     * @default 50
+     */
+    maxAgentTools: number;
+    /**
+     * Memory limit in megabytes for each sandboxed tool execution.
+     * Passed as {@link SandboxExecutionRequest.memoryMB}.
+     * @default 128
+     */
+    sandboxMemoryMB: number;
+    /**
+     * Wall-clock timeout in milliseconds for each sandboxed tool execution.
+     * Passed as {@link SandboxExecutionRequest.timeoutMs}.
+     * @default 5000
+     */
+    sandboxTimeoutMs: number;
+    /**
+     * Thresholds that must be met before a tool is eligible for tier promotion.
+     */
+    promotionThreshold: {
+        /**
+         * Minimum total invocation count before promotion is considered.
+         * @default 5
+         */
+        uses: number;
+        /**
+         * Minimum aggregate confidence score (from usage stats) before promotion.
+         * In the range [0, 1].
+         * @default 0.8
+         */
+        confidence: number;
+    };
+    /**
+     * Model ID used by the single LLM judge at forge time ({@link CreationVerdict}).
+     * Should be a fast, cost-efficient model — correctness is handled by test cases.
+     * @default "gpt-4o-mini"
+     */
+    judgeModel: string;
+    /**
+     * Model ID used by both reviewers in the multi-reviewer promotion panel
+     * ({@link PromotionVerdict}). Should be a more capable model than `judgeModel`.
+     * @default "gpt-4o"
+     */
+    promotionJudgeModel: string;
+}
+/**
+ * Default configuration for the Emergent Capability Engine.
+ *
+ * Note: `enabled` defaults to `false` — emergent capabilities must be explicitly
+ * opted-in via the agent's configuration to prevent accidental runtime tool creation.
+ */
+export declare const DEFAULT_EMERGENT_CONFIG: Readonly<EmergentConfig>;
+//# sourceMappingURL=types.d.ts.map

package/dist/emergent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/emergent/types.ts"],"names":[],"mappings":"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"}

package/dist/emergent/types.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Core types for the Emergent Capability Engine.
+ * @module @framers/agentos/emergent/types
+ *
+ * Provides all type definitions for the runtime tool creation system, enabling
+ * agents to forge new tools via composition or sandboxed code execution, subject
+ * to LLM-as-judge verification and tiered promotion.
+ *
+ * Key concepts:
+ * - ToolTier: Lifecycle scope of an emergent tool (session → agent → shared)
+ * - ComposableToolSpec: Pipeline of existing tool calls with input mapping
+ * - SandboxedToolSpec: Arbitrary code execution in a memory/time-bounded sandbox
+ * - CreationVerdict: LLM judge evaluation of a newly forged tool
+ * - PromotionVerdict: Multi-reviewer gate before tier promotion
+ * - EmergentTool: Unified shape for any runtime-created tool
+ */
+/**
+ * Default configuration for the Emergent Capability Engine.
+ *
+ * Note: `enabled` defaults to `false` — emergent capabilities must be explicitly
+ * opted-in via the agent's configuration to prevent accidental runtime tool creation.
+ */
+export const DEFAULT_EMERGENT_CONFIG = {
+    enabled: false,
+    maxSessionTools: 10,
+    maxAgentTools: 50,
+    sandboxMemoryMB: 128,
+    sandboxTimeoutMs: 5000,
+    promotionThreshold: {
+        uses: 5,
+        confidence: 0.8,
+    },
+    judgeModel: 'gpt-4o-mini',
+    promotionJudgeModel: 'gpt-4o',
+};
+//# sourceMappingURL=types.js.map

package/dist/emergent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/emergent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmrBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA6B;IAC/D,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,EAAE;IACnB,aAAa,EAAE,EAAE;IACjB,eAAe,EAAE,GAAG;IACpB,gBAAgB,EAAE,IAAI;IACtB,kBAAkB,EAAE;QAClB,IAAI,EAAE,CAAC;QACP,UAAU,EAAE,GAAG;KAChB;IACD,UAAU,EAAE,aAAa;IACzB,mBAAmB,EAAE,QAAQ;CACrB,CAAC"}

package/dist/index.d.ts

@@ -58,11 +58,13 @@ export type { ILogger } from './logging/ILogger';
 export { createLogger, setLoggerFactory, resetLoggerFactory } from './logging/loggerFactory';
 export * from './types/rateLimitTypes';
 export * from './core/storage';
+export * from './core/usage/UsageLedger';
 export * from './rag';
 export * from './memory';
 export * from './orchestration/index.js';
 export * from './core/provenance';
 export * from './core/safety';
+export * from './emergent/index.js';
 export { EXTENSION_SECRET_DEFINITIONS, type ExtensionSecretDefinition, getSecretDefinition, resolveSecretForProvider, } from './config/extensionSecrets.js';
 export { generateText } from './api/generateText.js';
 export type { GenerateTextOptions, GenerateTextResult, Message, ToolCallRecord, TokenUsage } from './api/generateText.js';
@@ -72,7 +74,12 @@ export { agent } from './api/agent.js';
 export type { Agent, AgentSession, AgentOptions } from './api/agent.js';
 export { generateImage } from './api/generateImage.js';
 export type { GenerateImageOptions, GenerateImageResult } from './api/generateImage.js';
-export { parseModelString, resolveProvider } from './api/model.js';
+export { parseModelString, resolveProvider, resolveModelOption, } from './api/model.js';
+export { PROVIDER_DEFAULTS, autoDetectProvider } from './api/provider-defaults.js';
+export type { ProviderDefaults } from './api/provider-defaults.js';
+export type { TaskType, ModelOption } from './api/model.js';
 export { adaptTools } from './api/toolAdapter.js';
 export type { ToolDefinitionMap } from './api/toolAdapter.js';
+export { getDefaultAgentOSUsageLedgerPath, resolveAgentOSUsageLedgerPath, readRecordedAgentOSUsageEvents, recordAgentOSUsage, getRecordedAgentOSUsage, clearRecordedAgentOSUsage, } from './api/usageLedger.js';
+export type { AgentOSUsageLedgerOptions, AgentOSUsageEvent, AgentOSUsageRecordInput, AgentOSUsageAggregate, } from './api/usageLedger.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}