@1.0.0
Theorum
A TypeScript kernel for typed agent profiles and deterministic turns.
A unified runtime
for agentic execution.
Theorum turns ad-hoc agent scripts into a typed execution kernel. One contract per agent — predictable at every boundary.
Pillars
Define a profile
A profile is the contract for one agent: identity, models, tools, inputs, outputs, and guardrails.
1 · Install
Add theorum to your project, then import the profile APIs.
npm install theorum import { defineProfile, registerProfile } from "theorum";
2 · Describe agent
Every profile has an id, a handle, and a system instruction the model receives each turn.
defineProfile({ : "mermaid", : { : "mermaid", : true, : "Turn requests into Mermaid diagrams. Ask when the request is too vague.", },
3 · Define models
Select a provider and the models this agent may use. Each model sets thinking levels,
token limits, provider builtins (builtInTools),
and optional compaction.
: { : "geminiInteractions", : "google", : ["fast", "capable"], : { : { : "gemini-3.5-flash-lite", : { on: "medium", off: "minimal" }, : ["minimal", "low", "medium", "high"], : { on: "auto", off: "none" }, : 8192, : 1, : ["googleMaps", "urlContext"], }, : { : "gemini-2.5-flash", : { on: "high", off: "low" }, : ["low", "medium", "high"], : { on: "auto", off: "auto" }, : 8192, : 1, : ["googleSearch"], }, }, : { fast: "fast", smart: "capable" }, : { fast: "low", smart: "high" }, : ["thinking"], : 1, },
4 · Configure tools
tools.allow lists custom function tools only — register them once at startup with registerTool. Provider builtins belong on each
model (builtInTools) and are on whenever that
model is selected. Optional on the profile: tools.t1Policy (T1) and tools.t2Loader (designated loader returning { loaded: string[] } ). T2 promotion is turn-local — the kernel does not remember it on the next turn unless
the host restores visibility via invokeTool (promoted / snapshot) or policy on load. Visibility otherwise follows loadTier on each registered tool.
: { : [], // T1: optional tools.t1Policy(ctx) => ["deferred_lookup"] },
5 · Allow inputs
Declare which text, file, and voice inputs the agent accepts on a turn.
: { : true, : { : ["image/png", "image/jpeg", "image/webp", "application/pdf", "text/plain", "text/markdown"], }, : { : ["audio/webm", "audio/wav", "audio/mpeg"], }, : 5, },
6 · Describe outputs
Configure how the agent responds: plain text, structured JSON, images, or speech.
: { : "mermaidTurn", : { : { : (source) => ({ isValid: typeof source === "string" && source.trim().length > 0, error: "diagram.mermaid must be a non-empty string", }), }, : 3, : "Return valid Mermaid only in diagram.mermaid.", }, : { : true, : true, }, : { : ["length", "stream_incomplete", "provider_error"], : ["length", "stream_incomplete"], }, },
7 · Set guardrails
Canary fencing, input sanitization, sensitive-data redaction, quotas, and opt-in egress (standardEgressEnforce) — the same stack wired in Th30 Live and the playground default.
: { : true, : true, : true, : { : 20, }, },
Package map
──┬── ─────────┬── ──────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └── ──────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ───────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├──
│ ├──
│ ├──
│ └──
│
├── ──────┬── ──────────────────┬──
│ │ ├──
│ │ ├── ┬──
│ │ │ ├──
│ │ │ └──
│ │ └── ────────┬──
│ │ ├──
│ │ └──
│ │
│ ├── ──────────────┬──
│ │ ├──
│ │ └── ──────┬──
│ │ ├──
│ │ └──
│ │
│ ├── ───────────────────┬──
│ │ └──
│ │
│ ├── ──────────────────┬──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├──
│ ├──
│ ├──
│ └──
│
├── ─────┬──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ ├──
│ └──
│
├── ──┬──
│ ├──
│ ├──
│ ├──
│ ├──
│ └──
│
├── ───────────┬──
│ ├──
│ ├──
│ └──
│
├── ────────────┬── ────────────────┬──
│ │ ├──
│ │ ├──
│ │ ├──
│ │ └──
│ │
│ ├── ──────────────────┬──
│ │ └──
│ │
│ └──
│
└── ────────┬──
├── ──────────────────┬──
└──