@helixar_ai/hdp-autogen

HDP (Human Delegation Provenance) middleware for AutoGen (TypeScript) — attach a cryptographic audit trail to any multi-agent conversation.

npm install @helixar_ai/hdp-autogen

Quick start

import { HdpAgentWrapper, hdpMiddleware } from "@helixar_ai/hdp-autogen";
import { generateKeyPair } from "@helixar_ai/hdp";

const { privateKey, publicKey } = generateKeyPair();

// Class-based: wrap an AutoGen agent
const wrapper = new HdpAgentWrapper({
  signingKey: privateKey,
  sessionId: "research-2026-q1",
  principal: { id: "[email protected]", idType: "email" },
  scope: { intent: "Summarise papers", authorizedTools: ["web_search"] },
});

await wrapper.init();
wrapper.onSpeakerTurn("researcher", "Summarising recent LLM papers...");
wrapper.onSpeakerTurn("reviewer", "The summary looks good.");

const token = wrapper.exportToken();

Functional middleware

const mw = hdpMiddleware({
  signingKey: privateKey,
  sessionId: "s1",
  principal: { id: "alice", idType: "handle" },
  scope: { intent: "research" },
});

await mw.observe({ agent: "researcher", content: "Hello" });
// mw.required() returns the current token or null

Error handling

onSpeakerTurn() and observe() are non-blocking — signing failures are caught internally and logged, so agent execution is never interrupted.

For tool-call scope enforcement, use onToolCall():

// Non-blocking (default): returns { allowed: false, violation: "..." }
const result = wrapper.onToolCall("execute_code", { code: "rm -rf /" });
if (!result.allowed) {
  console.warn("Scope violation:", result.violation);
}

OpenAI-compatible tool schemas

import { getHdpTools, HDP_TOOLS } from "@helixar_ai/hdp-autogen";

// HDP_TOOLS is a static array of 3 tool schemas:
// hdp_issue_token, hdp_extend_chain, hdp_verify_token
// Compatible with AutoGen's OpenAI tool_calls format

Cross-language compatibility

Tokens are wire-compatible with the Python hdp-autogen package. A token created in TypeScript can be verified in Python and vice versa — both use RFC 8785 canonical JSON + Ed25519.

Releasing

Published to npm via GitHub Actions. Two ways to release:

Standalone (publishes only this package):

git tag node/hdp-autogen/v0.1.2 && git push origin node/hdp-autogen/v0.1.2

Pipeline: test-hdp-autogen-ts → vet-hdp-autogen-ts (ReleaseGuard) → publish-hdp-autogen-ts-standalone

With all Node packages (publishes core + mcp + cli + autogen):

git tag v0.1.2 && git push origin v0.1.2

| Detail | Value | |---|---| | npm package | @helixar_ai/hdp-autogen | | Standalone tag | node/hdp-autogen/v* | | Bundle tag | v* (with all Node packages) | | Workflow | .github/workflows/release.yml | | Auth | NPM_TOKEN secret |

Spec

Human Delegation Provenance (HDP) is an IETF draft: draft-helixar-hdp-agentic-delegation

License

CC BY 4.0 — Helixar Limited