witnora

Witnora Controlled Action Runtime

The controlled action runtime is the production action-boundary layer in Witnora. packages/onegent-runtime remains an internal source module name; customers use the single public witnora package and the generated customer-owned Gateway.

Unlike MCPBench and Tripwire CI, it does not ask whether an agent should ship. It asks whether one live action should be allowed right now.

Implemented MVP

• receives proposed actions from an agent or tool gateway;
• supports SUBMIT, PAY, SEND, and UPDATE action intents;
• classifies action risk;
• records the acting principal and requested permissions;
• supports a deterministic authorization policy that denies missing scopes;
• evaluates deterministic local policy;
• supports policy-as-code with onegent.policy.json;
• requires human approval when needed;
• mock-executes only after approval;
• verifies expected state against observed local mock state;
• records audit events;
• exports an audit packet.

Customer integration surface

npx witnora@latest onboard --project <project-id>

The generated local Gateway client proposes high-risk actions, waits for the Hosted human decision, consumes a short-lived single-use execution grant, and routes the approved operation through the configured sandbox adapter. A separate read-only probe observes the outcome, after which Witnora issues the signed receipt automatically. Customers do not install or import the internal runtime module directly.

The internal reference implementation keeps these boundaries explicit:

• assessRisk(action);
• evaluatePolicy(action);
• requestApproval(action);
• executeAfterApproval(action, adapter?);
• verifyOutcome(action, observed);
• writeAuditPacket(action).

The checked-in adapter path is local and deterministic:

• createLocalEchoAdapter() returns the proposed after-state as observed local state.
• createInMemoryAuditStore() captures audit packets for tests and demos.
• approvalAdapter.requestApproval() lets callers plug in their own ticket, Slack, email, or human review system later without changing the core runtime API.
• authorizationPolicy.authorize() binds the action to a principal and grants explicit permissions. If any requested permission is absent, the action is cancelled before approval or execution.

Real systems should only be added behind explicit credential, approval, rollback, verification, and audit boundaries.

Sandbox Conformance Harness

Onegent now includes a tenant-scoped, local-only conformance harness between the mock demo and any future vendor sandbox. It enforces synthetic seed data, deny-by-default network access, target allowlists, explicit idempotency keys, identified approval, per-action and per-run limits, global and tenant kill switches, observed-state verification, rollback, and deterministic reset.

npx witnora@latest sandbox init
npx witnora@latest sandbox certify --adapter ./witnora.sandbox.mjs

The active suite emits a versioned report covering ten controls. See Sandbox Conformance Harness v0.1 for the CLI flow, control table, schema, and customer-sandbox progression.

Procurement Walkthrough

The demo scenario is a ProcurementAgent submitting a $4,850 purchase order to Acme Industrial Supply. The purchase order starts in local mock ERP state DRAFT. Because purchase orders over $1,000 require human approval, the action is classified as HIGH risk and waits for approval before execution.

After approval, the runtime updates only the local mock ERP purchase order from DRAFT to SUBMITTED, verifies that the observed mock state matches the expected state, and generates an audit packet.

Run the static demo export:

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

Run with an explicit policy file:

npm --prefix packages/onegent-runtime run demo:procurement -- --policy onegent.policy.json

Run the local server:

npm --prefix packages/onegent-runtime run serve

Open:

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

Local API Routes

The current project has no web framework, so the MVP exposes framework-free local route equivalents through Node’s built-in HTTP server:

• GET /api/action-gateway/actions
• POST /api/action-gateway/actions
• GET /api/action-gateway/actions/:id
• POST /api/action-gateway/actions/:id/approve
• POST /api/action-gateway/actions/:id/reject
• POST /api/action-gateway/actions/:id/verify
• GET /api/action-gateway/actions/:id/audit-packet
• GET /api/action-gateway/demo/procurement
• POST /api/action-gateway/demo/procurement/reset
• POST /api/action-gateway/demo/procurement/approve
• GET /mock-systems/procurement/purchase-orders/:id

Policy-As-Code

Policy files use a small deterministic JSON format:

{
  "schemaVersion": "1",
  "rules": [
    {
      "id": "po-over-1000-requires-approval",
      "name": "Purchase orders over $1,000 require approval",
      "description": "High-value purchase order submissions must be reviewed before mock execution.",
      "actionTypes": ["SUBMIT"],
      "effect": "REQUIRE_APPROVAL",
      "enabled": true,
      "conditions": [
        {
          "field": "amount",
          "operator": "greaterThan",
          "value": 1000
        }
      ]
    }
  ]
}

Supported effects:

• ALLOW
• REQUIRE_APPROVAL
• BLOCK

Supported operators:

• equals
• notEquals
• greaterThan
• greaterThanOrEqual
• lessThan
• lessThanOrEqual
• includes

Non-Goals

• no real payment systems;
• no real email sending;
• no vendor portal scraping;
• no real credentials;
• no production integrations;
• no persistent database or auth system.

Production integrations should only be added behind explicit adapters, credential boundaries, approval controls, and rollback/compensation design.

This site is open source. Improve this page.