kalguard-sdk is the lightweight HTTP client agents use to talk to the KalGuard sidecar. It exposes a typed client (KalGuardClient) plus two convenience wrappers (withPromptCheck, withToolCheck) that turn security mediation into a single line of code.

Most users should install the umbrella kalguard package, which re-exports everything in this SDK. Install kalguard-sdk directly if you want to pin only the client surface.

Install

npm install kalguard-sdk
# or
pnpm add kalguard-sdk

You also need:

• A running kalguard-sidecar reachable over HTTP.
• An agent bearer token signed with the sidecar's KALGUARD_TOKEN_SECRET. Issue one with createAgentToken(...) from kalguard-core.

Quick Start

import { KalGuardClient, withPromptCheck, withToolCheck } from 'kalguard-sdk';

const guard = new KalGuardClient({
  baseUrl: 'http://localhost:9292',
  token: process.env.KALGUARD_AGENT_TOKEN!,
});

const messages = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user',   content: userInput },
];

const reply = await withPromptCheck(guard, messages, async (safe) => {
  return await llm.chat(safe);          // only runs if policy allows
});

const weather = await withToolCheck(guard, 'get_weather', { location: 'NYC' }, async () => {
  return await tools.getWeather('NYC'); // only runs if policy allows
});

If the sidecar denies the request the wrapper throws; your agent never invokes the LLM or the tool. If the prompt firewall sanitizes the input, the wrapper hands you the cleaned safe messages.

API

class KalGuardClient

new KalGuardClient(options: KalGuardClientOptions)

| Option | Type | Required | Description | |--------------|----------|----------|-------------| | baseUrl | string | yes | Sidecar URL, e.g. http://localhost:9292. Trailing slash is stripped. | | token | string | yes | Agent bearer token (HMAC-signed; verified by the sidecar). | | requestId? | string | no | Default correlation id. Per-call ids override this. |

client.checkPrompt(messages, requestId?)

Calls POST /v1/prompt/check. Returns:

SecurityResponse<{
  allowed: boolean;
  riskScore?: number;
  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
  sanitizedMessages?: ReadonlyArray<PromptMessage>;
}>

client.checkTool(toolName, args, requestId?)

Calls POST /v1/tool/check. Returns SecurityResponse<{ allowed: boolean }>.

withPromptCheck(client, messages, run)

Convenience wrapper:

1. Calls client.checkPrompt(messages).
2. If allowed, invokes run(sanitizedMessages ?? messages) and returns the result.
3. If denied, throws an error carrying the policy reason — your agent must surface this to the caller, not retry.

withToolCheck(client, toolName, args, run)

Same shape for tool invocations.

Error model

All wrapper rejections include:

• name: 'KalGuardDenied'
• reason: human-readable string from policy
• requestId: correlation id (also returned in the x-kalguard-request-id response header)

Treat denials as terminal — never silently fall through to an unguarded path.

Compatibility

• Node.js: 20+ (relies on global fetch).
• Module format: ESM only.
• Browser / edge runtimes: not supported. Tokens are sensitive and must stay server-side.

Related packages

• kalguard — umbrella package; re-exports this SDK.
• kalguard-core — types, policy engine, prompt firewall, token utilities.
• kalguard-sidecar — the HTTP server this client talks to.

License

Apache-2.0 © KalGuard Contributors

Part of the Infrarix AI Infrastructure ecosystem