HELM Agent Integrations

HELM Agent Integrations is a public adapter and demo repository for routing agent-framework side effects through HELM AI Kernel.

The positioning is deliberately narrow:

Agent frameworks propose and orchestrate work.
HELM governs execution and produces evidence.

This repository does not define HELM conformance. helm-ai-kernel remains the source of truth for verdicts, receipts, MCP quarantine, OpenAI-compatible proxy behavior, and EvidencePack verification.

RLM Demo Boundary

RLM examples may appear here only as optional demos that route proposed side effects through HELM wrappers. Demo artifacts, generated samples, and RLM handoffs are not official RLM certification, HELM conformance, connector certification, or production trust anchors.

First Slice

This repo currently ships:

• TypeScript withHelmBoundary(...) wrapper around POST /api/v1/evaluate
• Python with_helm_boundary(...) wrapper around POST /api/v1/evaluate
• framework intent normalizers for Hermes, OpenClaw, Mastra, Codex, Claude Code, Browser Use, E2B, Composio, and TinyFish governed web capability
• universal demo docs for MCP boundary, OpenAI-compatible proxy, and generic tool wrappers
• routed-action receipt example showing verdict, receipt ref, and EvidencePack verification handoff
• high-risk MCP and shell demo fixtures for shell, VM, container, mobile, browser-admin, Claude Code hook, and OpenAI Agents tool-call surfaces
• sample-only loop adapter fixtures for Claude Code /goal, Claude Code /loop, Codex cloud task, LangGraph evaluator-optimizer, and GitHub PR bot
• Hermes and OpenClaw example integration bundles
• sample policies and policy-pack templates for common agent-side-effect classes
• generated sample receipts and EvidencePack archives
• a sample-only 99_EXT/helm-formal-proof/ EvidencePack extension fixture
• maintainer issue/PR copy for upstream example submissions
• CI checks that rebuild and verify the generated samples

Quickstart

Start a local HELM boundary from helm-ai-kernel:

cd ../helm-ai-kernel
make build
HELM_ADMIN_API_KEY=local-admin-key \
HELM_RUNTIME_TENANT_ID=local-demo \
HELM_RUNTIME_PRINCIPAL_ID=demo-agent \
  ./bin/helm-ai-kernel serve \
  --policy examples/launch/policies/agent_tool_call_boundary.toml

Use the TypeScript wrapper:

import { withHelmBoundary } from "@mindburn/helm-tool-wrapper";

const sendEmail = withHelmBoundary({
  helmUrl: "http://127.0.0.1:7714",
  apiKey: process.env.HELM_ADMIN_API_KEY ?? "",
  tenantId: "local-demo",
  principal: "demo-agent",
  sessionId: "demo-session-1",
  actionUrn: "tool.gmail.send_email",
  riskClass: "T2",
  effectClass: "E4",
  tool: async (input: { to: string; subject: string; body: string }) => {
    return { provider_id: "msg_123", ...input };
  },
});

const result = await sendEmail({
  to: "investor@example.com",
  subject: "Follow-up",
  body: "Drafted by agent.",
});

if (!result.allowed) {
  console.log(result.verdict, result.decision.reason);
}

Use the Python wrapper:

import os

from helm_tool_wrapper import with_helm_boundary

@with_helm_boundary(
    helm_url="http://127.0.0.1:7714",
    api_key=os.environ["HELM_ADMIN_API_KEY"],
    tenant_id="local-demo",
    principal="demo-agent",
    session_id="demo-session-1",
    action_urn="tool.sql.execute",
    risk_class="T2",
    effect_class="E4",
)
def execute_sql(query: str):
    return {"rows": 1, "query": query}

result = execute_sql("DROP TABLE customers")
if not result.allowed:
    print(result.verdict, result.decision.reason)

The served Kernel evaluate route is tenant-scoped. Both wrappers send the admin API key as a bearer credential and bind tenant_id/principal through the required X-Helm-Tenant-ID and X-Helm-Principal-ID headers. A serviceToken/service_token is rejected on this route because HELM_SERVICE_API_KEY is reserved for Kernel service-internal endpoints.

Repository Layout

packages/js/helm-tool-wrapper/       TypeScript direct preflight wrapper
packages/python/helm_tool_wrapper/   Python direct preflight wrapper
demos/                               universal boundary/proxy/wrapper demos
integrations/                        framework-specific examples
policies/                            sample integration policy profiles
receipts/samples/                    generated sample receipt JSON
evidencepacks/samples/               generated sample EvidencePack archives
docs/campaign/                       maintainer-ready issue and PR copy

TinyFish-style web capability examples live under integrations/tinyfish/. They are HELM-governed external web capability fixtures, not TinyFish certification or partnership claims.

Generate And Verify Samples

Sample receipts and EvidencePack archives are generated from scripts/generate_samples.py.

python3 scripts/generate_samples.py
python3 scripts/generate_samples.py --check
python3 scripts/verify_samples.py

The samples are deterministic local proof fixtures for demos. Formal-proof entries, when present, live under 99_EXT/helm-formal-proof/ and are declared in 00_INDEX.json. They are not customer trust anchors and do not replace native helm-ai-kernel verify; helm-ai-kernel remains source truth for proof contracts and conformance.

Validation

make validate

The validation target runs TypeScript build/tests, Python tests, sample regeneration checks, and sample integrity checks.

Source Truth

• HELM Kernel repo: https://github.com/Mindburn-Labs/helm-ai-kernel
• MCP integration docs: helm-ai-kernel/docs/INTEGRATIONS/mcp.md
• OpenAI-compatible proxy docs: helm-ai-kernel/docs/INTEGRATIONS/openai_baseurl.md
• HTTP API docs: helm-ai-kernel/docs/reference/http-api.md
• Verification docs: helm-ai-kernel/docs/VERIFICATION.md

Maintainer Copy

Use docs/campaign/maintainer-issue.md and docs/campaign/maintainer-pr.md when opening upstream examples. Keep upstream submissions small, optional, and example-only.