Runtime Manual/Reference & Specs/Comprehensive API Reference
Comprehensive API Reference
Complete API directory for Amber native modules (amber:*), Node.js compatibility, and Web standards
Amber delivers a unified runtime environment exposing three foundational API tiers:
- Amber Native Modules (
amber:*): Purpose-built subsystems for AI Agent execution, persistent state, streaming grammars, and sandboxing. - Node.js Core Modules (
node:*): 51/51 conformance suites passing for drop-in npm package compatibility. - W3C / WHATWG Web Standards: Universal browser-compatible primitives (
fetch,WebCrypto,WebStreams,Worker).
1. Amber Native API Reference (amber:*)
All native Amber modules can be imported using the canonical amber:<module> specifier or its unqualified short identifier (e.g. import { open } from 'amber:kv' or const { open } = require('kv')).
code
[ Amber Native Fabric ]
+------------------------------------+------------------------------------+
| Autonomous Agent Subsystems | Runtime & Infrastructure |
| --------------------------- | ------------------------ |
| • amber:ai (Tensors & LLM) | • amber:kv (ACID State) |
| • amber:bus (PubSub Fabric) | • amber:sandbox (Micro-Enclaves) |
| • amber:grammar (Stream Repair) | • amber:security (Permissions) |
| • amber:checkpoint(Time-Travel) | • amber:db (SQLite Engine) |
| • amber:tools (OpenAPI Synth) | • amber:vector (Vector Search) |
| • amber:replay (Trace Replay) | • amber:wasm (Zero-Copy JIT) |
| • amber:weights (GGUF Slicing) | • amber:ffi (Native C ABI) |
| • amber:mcp (MCP 2.0 Client) | • amber:std (Std Library) |
+------------------------------------+------------------------------------+
1.1 amber:ai — Edge Tensor Computing & Agent Pipelines
code
import { Tensor, LLM, AgentPipeline, embed, embedBatch, generate, generateStream, cosineSimilarity } from 'amber:ai';
| Function / Class | Signature | Description |
|---|---|---|
Tensor | new Tensor(shape: number[], data?: number[] | Float32Array, dtype?: string) | N-dimensional tensor supporting matmul(), add(), slice(), norm(), and fromBuffer(). |
LLM | new LLM(config?: { model?: string, maxTokens?: number }) | Local or remote inference engine with generate() and generateStream(). |
AgentPipeline | new AgentPipeline() | Multi-step reasoning pipeline supporting registerTool(), registerTools(), and step(). |
embed(text: string) | Promise<number[]> | Generates high-density vector embeddings (384/768 dim). |
embedBatch(texts: string[]) | Promise<number[][]> | Batch generates embeddings with parallel SIMD optimization. |
cosineSimilarity(a, b) | number | Calculates cosine similarity between two float vectors. |
1.2 amber:bus — Multi-Agent Message Bus & PubSub Channel Fabric
code
import { createBus, getDefaultBus, subscribe, once, unsubscribe, publish, broadcast, request, reply, use, topicMatches } from 'amber:bus';
| Method | Signature | Description |
|---|---|---|
subscribe(pattern, handler, opts?) | (pattern: string, handler: (msg: Message) => void, opts?: { priority?: number }) => Subscription | Subscribes to hierarchical topics with * and # wildcards. |
once(pattern, handler, opts?) | (pattern: string, handler: (msg) => void, opts?) => Subscription | Single-shot event subscriber automatically unregistering after first delivery. |
publish(topic, payload, opts?) | (topic: string, payload: any, opts?: PublishOptions) => Message | Dispatches message to subscribers sorted by descending priority. |
request(topic, payload, opts?) | (topic: string, payload: any, opts?: { timeoutMs?: number }) => Promise<any> | Bidirectional RPC request awaiting reply on correlation topic. |
reply(originalMsg, responsePayload) | (msg: Message, response: any) => Message | Replies directly to message's replyTo return address. |
use(middleware) | (middleware: (msg, next) => void) => this | Registers interceptor for tracing, authentication, or payload validation. |
getMetrics() | () => BusMetrics | Returns { published_count, delivered_count, dead_letter_count, active_subscriptions }. |
getDeadLetters() | () => Message[] | Inspects unhandled messages routed to the Dead-Letter Queue. |
1.3 amber:grammar — Streaming Structured Output & Token Grammar Engine
code
import { parsePartialJSON, createStreamDecoder, parseSSEChunk, createGrammar, createChoiceGrammar, createRegexGrammar, createJSONGrammar } from 'amber:grammar';
| Method | Signature | Description |
|---|---|---|
parsePartialJSON(text) | (input: string) => any | Microsecond-speed auto-repair for unclosed strings, open brackets ], and open braces }. |
createStreamDecoder(opts?) | (opts?: { onChunk?: (parsed, isComplete) => void }) => StreamDecoder | Statefully accumulates text chunks and emits incrementally updated JSON snapshots. |
parseSSEChunk(chunk) | (chunk: string) => SSEMessage[] | Parses raw Server-Sent Events stream chunks with built-in .json() accessor. |
createChoiceGrammar(choices) | (choices: string[]) => Grammar | Token grammar restricting LLM generation to fixed string alternatives. |
createRegexGrammar(pattern) | (pattern: string | RegExp) => Grammar | Token grammar enforcing regular expression conformance. |
createJSONGrammar(schema?) | (schema?: any) => Grammar | Token grammar verifying progressive valid JSON syntax. |
1.4 amber:checkpoint — Agent State Checkpoint & Time-Travel Snapshotting
code
import { createCheckpointManager, getDefaultManager, save, restore, get, list, diff, fork, clear } from 'amber:checkpoint';
| Method | Signature | Description |
|---|---|---|
save(idOrOptions, state?, metadata?) | (id?: string, state?: any, meta?: object) => Checkpoint | Captures an immutable deep clone of current agent state linked to lineage tree. |
restore(id) | (id: string) => any | Restores agent state to a historical checkpoint for clean fault rollback. |
diff(fromId, toId) | (fromId: string, toId: string) => StateDiff | Structural delta identifying { added, modified: { from, to }, deleted }. |
fork(fromId, branchName) | (fromId: string, branchName: string) => CheckpointManager | Creates speculative execution branch (Tree-of-Thought) without mutating main branch. |
persist(kvStore, prefix?) | (kvStore: KVStore, prefix?: string) => number | Flushes all checkpoints to a durable amber:kv Write-Ahead Log. |
restoreFromKV(kvStore, prefix?) | (kvStore: KVStore, prefix?: string) => number | Restores complete checkpoint lineage from a amber:kv store instance. |
1.5 amber:kv — Persistent Key-Value & Durable State Engine
code
import { open, openInMemory, KVStore } from 'amber:kv';
| Method | Signature | Description |
|---|---|---|
open(pathOrOptions) | (options: string | { path: string }) => KVStore | Opens durable disk-backed key-value store with append-only Write-Ahead Log (WAL). |
openInMemory() | () => KVStore | Opens ultra-low latency in-memory transient key-value store. |
get(key) | (key: string) => any | Reads key; returns undefined if key does not exist or has expired. |
set(key, value, ttlMs?) | (key: string, value: any, ttlMs?: number) => this | Writes key-value pair with optional automatic millisecond TTL expiration. |
delete(key) | (key: string) => boolean | Deletes key from memory and appends tombstone to WAL. |
incr(key, delta?) | (key: string, delta?: number) => number | Atomic integer increment operation. |
scan(options?) | (options?: { prefix?: string, limit?: number }) => Array<{ key, value }> | High-performance prefix range scanning. |
batch(operations) | (ops: Array<{ type: 'set' | 'delete', key, value?, ttlMs? }>) => this | Executes multiple write operations in a single atomic transaction. |
compact() | () => boolean | Prunes expired entries and compacts WAL log file to minimize disk footprint. |
1.6 amber:tools — Agent Tool Auto-Synthesis & OpenAPI Schema Compiler
code
import { compileSchemaTool, fromOpenAPI, parseToolCalls, registerTools, AgentTool } from 'amber:tools';
| Method | Signature | Description |
|---|---|---|
compileSchemaTool(spec) | (spec: ToolDefinition) => AgentTool | Compiles JSON Schema into validated callable AgentTool. |
fromOpenAPI(spec, options?) | (spec: object | string, opts?: OpenAPIOptions) => AgentTool[] | Automatically synthesizes executable tools from OpenAPI 3.x specifications. |
parseToolCalls(llmOutput) | (llmOutput: string | object) => ToolCall[] | Robustly extracts tool calls from JSON, arrays, markdown code blocks, and tags. |
registerTools(pipeline, tools) | (pipeline: AgentPipeline, tools: AgentTool[]) => AgentPipeline | Binds synthesized tools directly into an AgentPipeline. |
1.7 amber:sandbox — Hardened Micro-Enclaves & Real-time Audit Logging
code
import { createEnclave, startAuditLog, stopAuditLog, getAuditLogPath, isEnabled, enable, disable } from 'amber:sandbox';
| Method | Signature | Description |
|---|---|---|
createEnclave(policyOrCode, opts?) | (policy?: EnclavePolicy) => SandboxEnclave | Creates a zero-privilege micro-enclave with memory, timeout, and whitelist limits. |
startAuditLog(path) | (path: string) => boolean | Streams real-time compliance JSONL audit logs for all security decisions. |
stopAuditLog() | () => boolean | Flushes and finalizes active compliance audit log. |
getAuditLogPath() | () => string | null | Queries the currently active audit log file path. |
1.8 amber:replay — Deterministic Agent Replay Engine
code
import { startRecording, stopRecording, loadTrace, step, isRecording, isReplaying, getTraceStats } from 'amber:replay';
| Method | Signature | Description |
|---|---|---|
startRecording(opts) | (opts: { script?: string, outputPath?: string }) => void | Arms engine to record non-deterministic inputs into .amber-trace.json. |
stopRecording(path?) | (path?: string) => AgentTrace | Finalizes recording and exports trace file. |
loadTrace(traceOrPath) | (trace: string | object) => void | Loads trace and arms offline deterministic replay mode. |
step(name, input, fn) | (name: string, input: any, fn: (input) => any) => any | Records during live run; intercepts and replays cached outputs during replay. |
1.9 amber:weights — Native GGUF & SafeTensors Model Weights Loader
code
import { readGGUFMetadata, readSafeTensorsMetadata, loadTensor } from 'amber:weights';
| Method | Signature | Description |
|---|---|---|
readGGUFMetadata(filePath) | (path: string) => GGUFMetadata | Sub-millisecond inspection of GGUF v2/v3 tensor headers and KV pairs. |
readSafeTensorsMetadata(filePath) | (path: string) => SafeTensorsMetadata | Inspects HuggingFace SafeTensors file headers. |
loadTensor(filePath, tensorName) | (path: string, name: string) => LoadedTensor | Memory-maps tensor weights zero-copy into typed ArrayBuffer. |
1.10 amber:security & amber:permissions — Enterprise Capability Security
code
import { permissions, createSandboxPolicy, attenuate } from 'amber:security';
| Method | Signature | Description |
|---|---|---|
permissions.query(descriptor) | (desc: PermissionDescriptor) => Promise<PermissionStatus> | Queries whether specific I/O permission is currently granted. |
permissions.has(descriptor) | (desc: PermissionDescriptor) => boolean | Synchronous boolean capability inspection. |
permissions.revoke(descriptor) | (desc: PermissionDescriptor) => boolean | Drops privileged access dynamically at runtime. |
permissions.list() | () => PermissionRules | Dumps currently active allow/deny rule sets. |
attenuate(base, restricted) | (base: Policy, restricted: Policy) => Policy | Computes mathematical least-privilege intersection of permissions. |
1.11 amber:db & amber:vector — Embedded SQLite & Vector Search
code
import { Database } from 'amber:db';
import { VectorDB } from 'amber:vector';
// SQLite
const db = Database.open('./data.db');
db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
const stmt = db.prepare('INSERT INTO users (name) VALUES (?)');
stmt.run('Alice');
// Vector Engine
const vecDb = VectorDB.create({ dimension: 384, metric: 'cosine' });
vecDb.insert('doc-1', embeddingArray, { title: 'Introduction' });
const results = vecDb.search(queryEmbedding, { limit: 5 });
1.12 amber:std — Modern Standard Library
code
import { config } from 'amber:std/dotenv';
import { colors, table } from 'amber:std/cli';
import { walkDir, ensureDir } from 'amber:std/fs';
import { uuid, signJwt, verifyJwt } from 'amber:std/crypto';
import { assert, assertEquals } from 'amber:std/assert';
config({ path: '.env' });
console.log(colors.green('Environment loaded successfully'));
1.13 amber:wasm, amber:ffi & amber:pool — Native Interop & Concurrency
code
// WebAssembly 2.0 Shared Memory Bridge (amber:wasm)
import { compile, instantiate, MemoryView } from 'amber:wasm';
// Native C ABI FFI (amber:ffi)
import { dlopen, CString, types } from 'amber:ffi';
const libm = dlopen('libm.dylib', { cos: { args: [types.f64], returns: types.f64 } });
// Multi-Tenant IsolatePool (amber:pool)
import { IsolatePool } from 'amber:pool';
const pool = new IsolatePool({ size: 4, memoryLimitMb: 128 });
const result = await pool.execute('2 + 3');
2. Node.js Core Modules Reference (node:*)
Amber passes 51/51 official Node.js conformance test suites with hardware SIMD acceleration:
| Module | Specifier | Primary APIs | Status |
|---|---|---|---|
node:fs | fs, node:fs, node:fs/promises | readFile, writeFile, stat, readdir, mkdir, rm, createReadStream, createWriteStream | ✅ 100% |
node:path | path, node:path | join, resolve, dirname, basename, extname, normalize, isAbsolute | ✅ 100% |
node:crypto | crypto, node:crypto | createHash, createHmac, randomBytes, randomUUID, pbkdf2, AES-GCM/CBC | ✅ 100% |
node:buffer | buffer, node:buffer | Buffer.from, Buffer.alloc, Buffer.concat, isBuffer, toString (SIMD accelerated) | ✅ 100% |
node:events | events, node:events | EventEmitter, on, once, emit, removeListener, listenerCount | ✅ 100% |
node:stream | stream, node:stream | Readable, Writable, Transform, pipeline, finished | ✅ 100% |
node:http | http, node:http | createServer, IncomingMessage, ServerResponse, request, get, Keep-Alive | ✅ 100% |
node:process | process, node:process | argv, env, cwd(), exit(), uptime(), memoryUsage(), nextTick() | ✅ 100% |
node:timers | timers, node:timers | setTimeout, clearTimeout, setInterval, clearInterval, setImmediate | ✅ 100% |
node:url | url, node:url | URL, URLSearchParams, fileURLToPath, pathToFileURL | ✅ 100% |
node:dns | dns, node:dns | lookup, resolve, resolve4, resolve6 asynchronous DNS queries | ✅ 100% |
node:perf_hooks | perf_hooks, node:perf_hooks | performance.now(), PerformanceObserver | ✅ 100% |
3. Web Standards API Surface
Universally accessible on globalThis without import:
| Web API | Description | Global Access |
|---|---|---|
fetch() | Universal network request interface with streaming bodies | ✅ globalThis.fetch |
Headers, Request, Response | Fetch API primitives | ✅ globalThis.* |
URL, URLSearchParams | WHATWG URL specification parser | ✅ globalThis.* |
WebSocket | Standard real-time full-duplex client socket | ✅ globalThis.WebSocket |
crypto.subtle (Web Crypto) | Cryptography: digest, encrypt, decrypt, sign, verify | ✅ globalThis.crypto.subtle |
ReadableStream, WritableStream | WHATWG Streams standard for data pipelines | ✅ globalThis.* |
CompressionStream | Native streaming gzip and deflate compression | ✅ globalThis.CompressionStream |
Blob, File, FormData | Binary and multipart containers | ✅ globalThis.* |
structuredClone() | Native deep-cloning for complex object graphs | ✅ globalThis.structuredClone |
TextEncoder, TextDecoder | High-performance UTF-8 conversion | ✅ globalThis.* |
Worker | Multi-threaded Web Worker execution | ✅ globalThis.Worker |