feat(agents-sdk): add govern() fail-closed governance interceptor hel…

[Adityakk9031]

Summary

Resolves #3463 by introducing govern(), an interceptor-based governance helper in @inkeep/agents-sdk designed to mitigate CWE-636 (fail-open observer pattern flaw).

Context

Standard observer-pattern event hooks in LLM agent frameworks fail-open if a governance hook or policy check crashes, allowing tool execution to proceed without policy approval. This PR introduces a fail-closed interceptor execution boundary following the CCS (Correctover Conformance Standard) specification.

Key Changes

1. Governance Interceptor Helper (govern())

   • Added govern(handler, options) in packages/agents-sdk/src/governance.ts.
   • Guarantees that if a policy check throws an exception, times out, or evaluates to false, the underlying tool execution handler is never called (fail-closed contract).
   • Supports custom onDeny hooks and custom error messages.

2. Public SDK Exports

   • Exported govern and GovernanceOptions in packages/agents-sdk/src/index.ts.

3. Unit Tests & Changeset

   • Added Vitest test suite in packages/agents-sdk/src/__tests__/governance.test.ts.
   • Added patch changeset in .changeset/add-govern-interceptor.md.

Usage Example

import { govern } from "@inkeep/agents-sdk";

const myGovernedTool = govern(
  async (args: { query: string }) => {
    return await executeQuery(args.query);
  },
  {
    policy: async (args) => {
      // Return true if policy check passes; any throw/rejection blocks execution
      return args.query !== "forbidden";
    },
  }
);

Verification

• Verified unit test suite covering policy success, policy denial, policy exception fail-closed execution, and custom onDeny handlers.
• Verified export resolution in @inkeep/agents-sdk.

[changeset-bot]

🦋 Changeset detected

Latest commit: f5f5c3f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@inkeep/agents-sdk	Patch
@inkeep/agents-api	Patch
@inkeep/agents-manage-ui	Patch
@inkeep/agents-cli	Patch
@inkeep/agents-core	Patch
@inkeep/agents-email	Patch
@inkeep/agents-mcp	Patch
@inkeep/agents-work-apps	Patch
@inkeep/ai-sdk-provider	Patch
@inkeep/create-agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Thanks for the contribution!

What happens next:

• A maintainer will review your PR.
• If you don't hear back within a few business days, please comment here to nudge our team.
• This repository is maintained through an internal mirror. When your change is accepted, this PR will close automatically. Don't be alarmed when it closes — that's how it merges, and your authorship is preserved.

[Adityakk9031]

@robert-inkeep and @tim-inkeep have a look