@zanii/runtime

The deterministic agent rails — the model proposes, tested code disposes. @zanii/sdk records proofs; @zanii/runtime governs the action itself, enforcing the accountability rules that sit above the ledger: scoped authority, "no external receipt → no claim of success", a fixed status vocabulary, tool-manifest validation, and a human confirmation gate for irreversible actions.

npm install @zanii/runtime

Quickstart

import { ZaniiAgent } from '@zanii/sdk';
import { generateKeypair, createCert } from '@zanii/core';
import { Runtime, tool, type ToolResult } from '@zanii/runtime';

const owner = generateKeypair();
const agent = generateKeypair();
const cert = createCert(
  { issuer: owner.did, subject: agent.did, scopes: ['email.*'], exp: '2027-01-01T00:00:00Z' },
  owner.privateKey,
);

const zanii = new ZaniiAgent({
  serverUrl: 'https://ledger.zanii.agency',
  agentDid: agent.did,
  agentPrivateKey: agent.privateKey,
  delegation: [cert],
  apiKey: process.env.ZANII_API_KEY,
});

const sendEmail = tool('email.send', 'email.*', async ({ to, subject }) => {
  const providerId = await mail.send(to as string, subject as string); // your real integration
  return { ok: true, receiptId: providerId } satisfies ToolResult;      // the provider's receipt
}, { irreversible: true });

const rt = new Runtime(zanii, { tools: [sendEmail], delegation: [cert] });

let d = await rt.propose('email.send', { to: '[email protected]', subject: 'Follow up' }, { intent: 'follow up' });
// irreversible ⇒ d.status === 'awaiting_confirmation'; nothing sent yet
d = await rt.confirm(d.confirmationId!);
// owner said yes (bound to this exact action) ⇒ d.status === 'sent', recorded on the ledger

The rules it enforces

• Authority — a proposal whose tool scope isn't covered by the delegation is rejected before anything runs.
• No proof, no claim — status is derived from the tool's result: a missing receiptId ⇒ attempted (never sent); a matched read-back (confirmed: true) ⇒ confirmed; a thrown tool ⇒ failed; partial: true ⇒ partial.
• Proposes / disposes — unknown tools and out-of-scope tools are rejected; a low confidence returns clarify instead of guessing.
• Human gate — irreversible tools pause at a confirmation bound to the exact action, expiring loudly; confirmations arrive only via confirm(), never from content.

Every executed action is recorded through the ZaniiAgent, so the receipt carries the earned status word and the provider's identifier. Mirrors the Python zanii.runtime.

Links

• Docs & concepts — https://ledger.zanii.agency/docs
• Live transparency log — https://ledger.zanii.agency

Changelog

• 0.3.0 — ownerDid (owner-signed confirmations, Article VI); intentReceipts (intent/result); provenance (runtimeHash/modelId/manifestHash, compliance anchoring).
• 0.2.0 — initial release: the deterministic agent rails — Runtime, Tool, ConfirmationGate, and the tool() helper. Propose → validate (manifest + scope) → gate (if irreversible) → execute → record, with evidence-earned status words.

License

Apache-2.0.