OSuite Governed Agent Examples

Reference examples for action-bound governance in AI agent frameworks.

This repository shows how to turn a planned agent action into a reviewable object, bind approval to that exact object, execute only inside a bounded lease, and preserve a replayable proof bundle after execution.

It is not the OSuite product. It is the small, open reference implementation we use when explaining governed agent actions to framework maintainers, security teams, standards groups, and enterprise platform builders.

agent action -> action envelope -> approval lease -> execution -> outcome receipt -> proof bundle

Why

Most agent frameworks already have tools, traces, guardrails, workflow interrupts, or human review. Those layers are useful, but they often leave one operational question underspecified:

What exact action was approved, under which policy, for which runtime, for how long, and what proof remains after it runs?

This repo gives that question an executable shape.

Install

No external services are required for the local examples.

git clone git@github.com:OndCo/OSuite-Governed-Agent-Examples.git
cd OSuite-Governed-Agent-Examples
npm test
npm run examples:smoke

The default examples use a local mock reviewer. Production users can replace the mock reviewer with OSuite Studio, the OSuite SDK, a customer policy service, or a framework-native approval queue.

Quickstart

import {
  createActionEnvelope,
  createApprovalLease,
  createMockReviewer,
  verifyApprovalLease
} from "./packages/governed-action-core/src/index.js";

const envelope = createActionEnvelope({
  actor: { id: "agent:codex", type: "agent" },
  runtime: { id: "runtime:local-shell", family: "shell" },
  action: {
    kind: "source_control.push",
    goal: "Publish reviewed changes",
    command: "git push origin main",
    targets: [{ type: "git.remote", value: "origin/main" }],
    effects: ["code_publication"]
  },
  policy: { profile: "deployment_protected", version: "2026-07-14" }
});

const reviewer = createMockReviewer();
const decision = reviewer.review(envelope);

if (decision.verdict !== "approved") {
  console.log("Approval required for", envelope.action_hash);
}

const lease = createApprovalLease({
  envelope,
  reviewer: { id: "user:operator", type: "human" },
  decision: "approved",
  ttl_seconds: 300
});

console.log(verifyApprovalLease({ lease, envelope }));

Concepts

Primitive	Purpose
Action envelope	Canonical representation of the action the agent wants to take.
CAVA-lite projection	Minimal open example of mapping raw runtime behavior into action semantics.
Approval lease	Scoped, expiring approval bound to one action hash.
Outcome receipt	Record of what happened after execution or blocking.
Proof bundle	Replayable chain tying envelope, lease, outcome, and verifier references together.
External verifier ref	Optional evidence reference from a third-party checkpoint or ledger.

Examples

Example	What it demonstrates
examples/mcp-server	Govern an MCP-style tool call before execution.
examples/openai-agents-sdk	Wrap an agent tool with action-bound governance.
examples/langgraph	Place a governance checkpoint inside a stateful agent graph.
examples/shell-agent	Classify local shell commands before a Codex/Claude Code-style agent runs them.
examples/microsoft-agent-framework	Draft an action-bound tool approval sample for Microsoft Agent Framework.
examples/openhands	Draft a governed-command skill pattern for developer agents.
examples/flowise	Draft a no-code governance checkpoint node contract for Flowise.
examples/mcp-registry	Document the correct registry-first path for MCP publication.

Run the local examples:

npm run examples:smoke

Repository Map

packages/governed-action-core/   Open reference primitives
schemas/                         JSON schemas for portable governance objects
examples/                        Runnable framework examples
docs/                            Design notes and open-core boundaries
pr-packets/                      Draft packets for ecosystem PRs
assets/                          Black-and-white architecture diagrams

PR Targets

The goal is not to push a vendor integration into every project. The goal is to contribute a precise, reusable governance pattern.

Useful first targets:

• LangGraph: approval lease around interruptible workflows.
• MCP ecosystem: registry-first governed tool-call server.
• Microsoft Agent Framework: action-bound tool approval sample.
• OpenHands: governed-command skill or security guidance.
• Flowise: no-code governance checkpoint node or example chatflow.

See docs/pr-targets/first-tier.md, docs/pr-playbook.md, and pr-packets.

Open-Core Boundary

This repository open-sources the shape of the pattern:

• action envelope schema;
• approval lease schema;
• outcome receipt schema;
• proof bundle schema;
• mock reviewer;
• CAVA-lite command projection;
• runnable examples.

It does not open-source OSuite's managed product internals:

• production CAVA parser packs and scoring;
• Decision Score v2.1 weights;
• BAF enforcement internals;
• AREG runtime exposure graph implementation;
• enterprise policy compiler;
• tenant, billing, and external verifier network internals.

See docs/what-this-repo-does-not-open-source.md.

Development

npm test
npm run examples:smoke

The core package is deliberately small and dependency-free. Examples that require optional framework packages document those dependencies in their own README files.

Contributing

Contributions should keep the examples small, portable, and reviewable. Please avoid adding OSuite SaaS internals or examples that require private credentials.

See CONTRIBUTING.md and SECURITY.md.

License

Apache-2.0.