@trigguard/agent-sdk

Canonical TrigGuard agent integration layer.

Wraps @trigguard/execution-sdk — all authority decisions come from production POST /execute. No duplicate policy logic. No parallel authority systems.

Quick start

import { createTrigGuardAgent } from "@trigguard/agent-sdk";

const trigguard = createTrigGuardAgent({
  gatewayUrl: process.env.TRIGGUARD_GATEWAY_URL ?? "https://api.trigguardai.com",
  apiKey: process.env.TRIGGUARD_API_KEY,
  defaultActorId: "my-agent",
});

const decision = await trigguard.authorize({
  surface: "deploy.release",
  context: { repository: "TrigGuard-AI/example", environment: "staging" },
});

if (decision.permit()) {
  await runProtectedAction();
} else if (decision.deny()) {
  stop("Authority denied");
} else if (decision.silence()) {
  await requestHumanReview();
}

const verified = await decision.verifyOffline();
console.log(decision.executionId, decision.label(), verified.ok);

Authority flow

Agent intent
    ↓
trigguard.authorize({ surface, context })
    ↓
POST /execute  (via @trigguard/execution-sdk)
    ↓
PERMIT | DENY | SILENCE + signed receipt
    ↓
AgentDecision.permit() | deny() | silence()
    ↓
Optional: verifyOffline() or verifyRemote()

When to use this vs execution-sdk

| Package | Use when | |---|---| | @trigguard/agent-sdk | Building agents (Cursor, Claude Code, MCP hosts, custom bots) | | @trigguard/execution-sdk | CI pipelines, low-level HTTP control, withExecute fail-closed |

Agent SDK adds typed AgentDecision, receipt-first decision extraction, and verify helpers.

Examples

• examples/cursor-governed-agent — Cursor-style tool governance (mock actions)
• examples/claude-code-governed-agent — Claude Code-style repo mutations (mock actions)

Design partner guide

See docs/integrations/FIRST_DESIGN_PARTNER_GUIDE.md.

MCP integration

Production MCP server: @trigguard/mcp-server — stdio transport, tools authorize_action, verify_receipt, get_surface, get_policy.

• Quickstart: docs/adoption/MCP_CURSOR_QUICKSTART.md
• Tool reference: docs/adoption/MCP_TOOL_REFERENCE.md
• Architecture: docs/architecture/TRIGGUARD_MCP_ARCHITECTURE.md

MCP calls this SDK internally — do not duplicate authority logic in MCP handlers.

Non-goals

• No client-side policy evaluation
• No /decide rail (receipt-less)
• No console UI changes