@hazeljs/decision
v2.1.0
Published
Native HazelJS Agent OS decision runtime — bounded choices, confidence, policy, then Gatekeeper
Maintainers
Readme
@hazeljs/decision
Bounded, typed decisions for Agent OS — choose from a closed set, then govern.
Models propose. Agents evaluate. Critics challenge. Confidence informs. Policies govern. Skillgate classifies. Gatekeeper authorizes. Durable Kernel executes.
This is not a wrapper around Jev, OpenAI, Gemini, or another external decision model. The default provider is hazel-agent: a native evidence → candidates → judge → critic → confidence pipeline. External providers are optional adapters; every result still passes policy and Gatekeeper.
Reasoning ≠ Decision ≠ Policy ≠ Authorization ≠ ExecutionFeatures
- Closed-set choices —
choices: [...] as const; invalid model output is rejected - Native
hazel-agentprovider — evidence / candidates / judge / critic / confidence (optional LLM viagenerateObject) - Risk → strategy routing —
fast|standard|deliberate|human-required|rules - Deterministic policy — allow / critique / review / deny from confidence bands (never authorization)
- Gatekeeper + Skillgate — execute only after policy allow and Gatekeeper allow; skill class may raise risk floor
- Durable HITL — review creates
HumanTask; resume with receipts (no double-invoke) - Decision Lab — run / shadow compare / flow projection; Agent Office UI in hazeljs-agent-office at
/office/decisions(not Inspector) - Opt-in extensions — ensemble, cache, history/trends, calibration, cost-aware router
- CLI —
hazel decision run | compare | flow | lab
Installation
npm install @hazeljs/decision @hazeljs/agent
# production execute:
npm install @hazeljs/agent-gatekeeper
# optional:
npm install @hazeljs/skillgate @hazeljs/ai @hazeljs/auditOr:
hazel add decisionQuick Start
import { createDecisionRuntime } from '@hazeljs/decision';
const decisions = createDecisionRuntime();
const result = await decisions.decide({
objective: 'Choose the safest production remediation',
state: {
errorRate: 0.38,
previousErrorRate: 0.01,
deploymentAgeMinutes: 4,
failedHealthChecks: 8,
},
choices: ['retry', 'rollback', 'escalate', 'ignore'] as const,
risk: 'high',
provider: 'hazel-agent',
});
// result.decision: 'retry' | 'rollback' | 'escalate' | 'ignore'Governed runtime (LLM stages + Gatekeeper + audit):
import { createGovernedDecisionRuntime } from '@hazeljs/decision';
const decisions = createGovernedDecisionRuntime({
generateObject: aiService,
agentRuntime,
gatekeeper,
auditService,
});Architecture
decide() → complexity router → provider → confidence → policy
→ Gatekeeper (if execute) → durable checkpoint → capability handler| Concern | Primitive |
| ------------------------ | ----------------------------------------------------------- |
| DNA / HITL / checkpoints | @hazeljs/agent |
| Call-time authorization | @hazeljs/agent-gatekeeper |
| Skill risk floor | @hazeljs/skillgate |
| Effect isolation | Host effectGate / @hazeljs/agent-vm (not reimplemented) |
Skillgate curates skills. Gatekeeper authorizes invocations. Confidence never collapses those layers.
Providers
| Provider | Role |
| ------------------------------------- | -------------------------------------------------------------------- |
| hazel-agent | Default. Native pipeline; optional generateObject judge/critic |
| mock | MockDecisionProvider for tests |
| auto | Cost-aware router hook |
| ensemble | Majority / weighted / unanimous / risk-sensitive |
| openai / gemini / jev / local | Thin adapters — still pass policy + Gatekeeper |
import {
createOpenAiDecisionProvider,
createJevDecisionProvider,
createEnsembleDecisionProvider,
} from '@hazeljs/decision';
runtime.providers.register(createOpenAiDecisionProvider(aiService));
runtime.providers.register(createJevDecisionProvider({ decide: jevDecide }));On LLM failure, hazel-agent falls back to heuristics (never to “allow”).
Policy → Gatekeeper
Default confidence bands (overridable via DNA / request policy):
| Band | Policy |
| -------------- | ------------------ |
| ≥ high (0.95) | allow (eligible) |
| ≥ medium (0.7) | critique |
| < medium | review (HITL) |
Even with confidence 0.999 and policy allow, Gatekeeper can deny. Missing Gatekeeper + execute: true ⇒ denied.
await decisions.resumeFromHuman({
decisionId,
runId,
action: 'override', // approve | reject | override
decision: 'escalate',
actor: 'ops-lead',
reason: 'Rollback currently prohibited',
execute: true,
});Resume hydrates from durable checkpoints when in-memory results are gone (process restart). Receipts prevent double-invoke.
Decision DNA
Optional on Agent DNA (format: 'hazeljs.agent.dna'):
decisions: {
'incident-remediation': {
version: '3',
objective: 'Choose the safest remediation',
choices: ['retry', 'rollback', 'escalate', 'ignore'],
risk: { level: 'high' },
confidence: { high: 0.95, medium: 0.7 },
execution: { rollback: { capability: 'deployment.rollback' } },
},
}Risk is trusted configuration. Models cannot lower it. Skillgate may raise the floor only.
Decision Lab
import { createDecisionRuntime, createDecisionLab } from '@hazeljs/decision';
const lab = createDecisionLab(createDecisionRuntime());
const run = await lab.run({ objective, state, choices: [...] as const, risk: 'high' });
const cmp = await lab.compare(request, ['hazel-agent', 'mock']);
// cmp.executionForbidden === trueAgent Office (Run · Compare · Flow · History · Calibration) lives in the sibling app
hazeljs-agent-office at /office/decisions — not in @hazeljs/inspector.
Meridian teaches the API path: POST /api/decision/refund → resume.
Opt-in extensions
import {
DecisionCache,
DecisionHistory,
createCostAwareRouter,
projectDecisionFlow,
fitCalibrationFromHistory,
} from '@hazeljs/decision';
const runtime = createDecisionRuntime({
cache: new DecisionCache({ ttlMs: 30_000 }),
history: new DecisionHistory(),
});
await runtime.decide({ ..., cache: true }); // opt-in cache
history.trends(); // Lab only — never auto-prompted
runtime.setCalibration(fitCalibrationFromHistory(history));
await runtime.decide({ ..., calibrate: true }); // reporting only
projectDecisionFlow({ risk: 'high' }); // Flow-shaped UI graphCLI
hazel decision run --risk high
hazel decision compare --providers hazel-agent,mock
hazel decision flow --risk critical
hazel decision labExamples
npx tsx examples/incident-remediation.ts
npx tsx examples/refund-hitl.ts
npx tsx examples/high-confidence-denied.ts
npx tsx examples/prompt-injection.ts
npx tsx examples/decision-lab.ts
npx tsx examples/flow-and-calibration.ts
npx tsx examples/ensemble.tsProgressive complexity
decide()- provider
- risk + confidence
- critic + policy
- Gatekeeper + durable HITL
- DNA + Lab + evaluation
Security
- State is data (prompt-injection resistant)
- Closed choices — no invented verbs
- Risk / policy / capabilities are not model-writable
- Replay never re-executes side effects
- History / calibration never auto-inject into prompts
- Confidence never authorizes
Related
- Docs: Decision package
- Docs: Decision Runtime guide
- @hazeljs/agent
- @hazeljs/skillgate
- @hazeljs/agent-gatekeeper
- @hazeljs/flow
- hazeljs-agent-office — Decision Lab UI
- hazeljs-meridian-ops — Decision teaching API
License
Apache-2.0
