witnora

Witnora Runtime

Witnora Runtime is Witnora’s runtime action boundary package. It lets a caller capture a proposed high-risk agent action, assess risk, evaluate policy, request approval, execute only after approval, verify the observed outcome, and write an audit packet.

The checked-in implementation is local and mock-only. It does not connect to real payment systems, email providers, vendor portals, production ERPs, or real credentials.

Production Evaluator Kit

The exported evaluator factories cover CRM record state, ticket status, email delivery, prepared database reads, webhook delivery, queue/job completion, payment refund results, and browser workflow outcomes. They run inside the customer boundary with locally resolved read-only credentials. Remote HTTP reads are fixed-origin HTTPS GET requests with redirects disabled, a 10-second maximum timeout, and a 64 KiB response limit; database checks accept only a customer-registered statement ID, never SQL supplied by Nora or Hosted.

Each factory returns the same witnora.production_evaluator_observation.v0.1 shape. Only allowlisted scalar fields and SHA-256 bindings leave the evaluator; credentials, raw provider responses, page text, and business payloads remain local. A satisfied result proves only that bounded observation and never authorizes a write or establishes independent review.

Trusted Action Recorder and Mandate v0.1

The trusted runtime adds a stronger evidence path for consequential actions:

Run the complete local browser-agent SUBMIT example:

npm run build
npm run demo:trusted-browser

It reads a local purchase-order page, proposes a $4,850 SUBMIT, obtains human approval, writes through a gateway-only credential, verifies DRAFT -> SUBMITTED through an independent GET endpoint, and emits a signed receipt. The fixture is a deterministic infrastructure demonstration, not a model benchmark. See Action Assurance Protocol v0.1.

SDK

This is currently a repository-local preview package, not a published npm package. Build and test it from the Witnora checkout:

npm --prefix packages/onegent-runtime ci
npm --prefix packages/onegent-runtime run build
npm --prefix packages/onegent-runtime test

import {
  createInMemoryAuditStore,
  createLocalEchoAdapter,
  createWitnoraRuntime,
} from "@agentcert/onegent-runtime";

const auditStore = createInMemoryAuditStore();
const runtime = createWitnoraRuntime({
  authorizationPolicy: {
    name: "procurement-permissions",
    authorize: (action) => ({
      allowed: action.principal.id === "procurement-agent",
      grantedPermissions: ["MockERP:SUBMIT"],
      reason: "Allowed by the local demo policy.",
    }),
  },
  approvalAdapter: {
    name: "manager-approval",
    requestApproval: async () => ({
      approved: true,
      reviewerId: "manager@example.local",
      reviewerComment: "Approved for demo execution.",
    }),
  },
  auditStore,
});
const review = runtime.captureAction({
  sourceAgentName: "ProcurementAgent",
  principal: { id: "procurement-agent", type: "agent" },
  requestedPermissions: ["MockERP:SUBMIT"],
  actionType: "SUBMIT",
  targetSystem: "MockERP",
  title: "Submit purchase order",
  description: "Submit a high-value purchase order for approval.",
  businessObjectType: "purchase_order",
  businessObjectId: "PO-1001",
  amount: 4850,
  currency: "USD",
  vendorName: "Acme Industrial Supply",
  beforeState: { status: "DRAFT" },
  proposedAfterState: { status: "SUBMITTED" },
});

if (review.authorizationDecision?.decision !== "ALLOW") {
  throw new Error("Action was not authorized.");
}

const risk = runtime.assessRisk(review.action);
const policy = runtime.evaluatePolicy(review.action, risk);
const approval = await runtime.requestApproval(review.action);

if (approval.status !== "APPROVED") throw new Error("Action was not approved.");

const observed = await runtime.executeAfterApproval(review.action, createLocalEchoAdapter());
const verification = runtime.verifyOutcome(review.action, observed);
if (!verification.success) throw new Error("Observed state did not match expected state.");
const auditPacket = await runtime.writeAuditPacket(review.action);

The SDK is intentionally adapter-shaped: you bring the authorization policy, approval workflow, execution adapter, and audit store. Execution is keyed by ActionIntent.idempotencyKey; concurrent retries share one result, and a key cannot be rebound to a different action. Rollback is an explicit compensating action implemented by the adapter, never an assumed reversal of a real-world side effect. Requested permissions must be included in the policy’s granted permissions or the action is blocked. The checked-in examples are local-only and deterministic so they are safe for tests and demos.

createStateSandboxAdapter() is the reference safety boundary. It refuses production actions, allows only named synthetic target systems, performs no network access, snapshots previous state, and implements deterministic rollback. createJsonlAuditStore() provides an append-only local audit sink; hosted or customer-managed stores can implement the same AuditStore contract.

Sandbox Certification Harness

Run the active local certification suite:

npm run build
node dist/cli.js sandbox-certify --out .onegent/sandbox-certification

It tests tenant isolation, synthetic-data enforcement, network denial, target allowlisting, production denial, approval, execution limits, kill switches, idempotency, verification, rollback, and reset. The versioned JSON report is validated by sandbox-certification.schema.json.

Programmatic entry points:

Business Task Replay and Shadow

runReplayEvaluation() and runShadowEvaluation() consume the same customer-approved Business Task Contract:

createBusinessTaskEvaluatorServer() turns those deterministic evaluators into the contract-pinned, literal-loopback service consumed by the Managed Workflow Harness. The customer supplies the local scenario loader and candidate callbacks; Witnora supplies authentication, binding checks, body and concurrency bounds, timeouts, Replay sandbox enforcement, and Shadow’s zero-write boundary. Raw scenario inputs stay inside the customer process and never appear in the returned report.

Neither mode establishes production enforcement, a production outcome, or whole-Agent reliability. Raw scenario inputs stay inside the customer runtime and are never included in the report or Hosted Run metadata.

runBusinessTaskWorkflow() executes an approved Business Workflow Contract as dependency-ready waves. A Workflow may coordinate several Business Tasks and several Agents, but every callback still receives one exact task version and one Replay or Shadow mode. The runner bounds concurrency, blocks downstream tasks after an upstream decision, rejects production writes, and returns separate per-task results rather than an aggregate assurance claim.

When an approved Business Task version changes, the Control Plane requires a new Workflow Contract version. Historical Runs remain evidence for their original task version and are not reused as proof for the changed Workflow.

See the full harness guide.

Sandbox Adapter Kit v0.2

npm run build
node dist/cli.js sandbox-conformance --out .onegent/sandbox-conformance

createSandboxSystemAdapter() provides the guarded callback template for third-party systems. runSandboxAdapterConformanceSuite() verifies the adapter, the ten v0.1 controls, tenant lifecycle, and tenant TTL cleanup. Harness tenants expire after one hour by default and are deleted on expiry or close().

Use createStripeTestModeReadOnlyAdapter() for the vendor reference boundary. It accepts only a restricted rk_test_ key and exposes bounded PaymentIntent GET operations; it cannot execute a payment mutation. The boundary checks the exact HTTPS origin, method, and resource route before network access, then applies a 5-second timeout and process-local request cap. Use the public npx --package agentcert witnora sandbox stripe-readonly --payment-intent pi_... command to produce and optionally upload the redacted v0.4 report.

Add --push to either sandbox command to create a Hosted Control Plane run and upload the report as complete evidence. Configure WITNORA_PROJECT_ID, WITNORA_API_KEY, and optionally WITNORA_BASE_URL; the API key needs runs:write and evidence:write.

See the Adapter Kit guide and the runnable third-party template.

Demo

npm --prefix packages/onegent-runtime ci
npm --prefix packages/onegent-runtime run build
npm --prefix packages/onegent-runtime run demo:procurement
npm --prefix packages/onegent-runtime run demo:trusted-browser

Outputs:

Local Server

npm --prefix packages/onegent-runtime run serve

Open:

http://localhost:3310/action-gateway/walkthrough/procurement

Brand migration compatibility

The internal package name, createAgentCert* API names, agentcert.* schema IDs, and legacy AGENTCERT_* variables remain supported. New integrations should use the Witnora product name, witnora-runtime command, and WITNORA_* variables.

This site is open source. Improve this page.