Advanced Topics

Advanced TypeScript Shield topics including debugging, optimization, streaming, context objects, sessions, logging, and telemetry.

This page collects the deeper operational and debugging features of the TypeScript SDK.

Advanced Request Options

Use explain, debug, optimize, dryrun, early_exit, and contexts for debugging, profiling, and context-aware detection:

const explainResp = await client.guard.evaluate({
  content: userInput,
  content_type: "prompt",
  action: "process_prompt",
  explain: true,
});
console.log(explainResp.explanation);
console.log(explainResp.root_causes);
console.log(explainResp.tiers_evaluated);
console.log(explainResp.projected_context);

const debugResp = await client.guard.evaluate({
  content: userInput,
  content_type: "prompt",
  action: "process_prompt",
  debug: true,
});
for (const d of debugResp.detectors ?? []) {
  console.log(`${d.name}:`, d.context);
}

const optimizedResp = await client.guard.evaluate({
  content: userInput,
  content_type: "prompt",
  action: "process_prompt",
  optimize: true,
});
console.log(optimizedResp.optimization?.required_detectors.length, "detectors ran");

const dryrunResp = await client.guard.evaluate({
  content: userInput,
  content_type: "prompt",
  action: "process_prompt",
  optimize: true,
  dryrun: true,
});

const earlyExitResp = await client.guard.evaluate({
  content: userInput,
  content_type: "prompt",
  action: "process_prompt",
  early_exit: true,
});

const contextualResp = await client.guard.evaluate({
  content: modelResponse,
  content_type: "response",
  action: "process_prompt",
  contexts: [originalPrompt, ...ragChunks],
});

Streaming

client.guard.stream() returns an AsyncIterable of StreamEvent.

for await (const event of client.guard.stream({
  content: "tell me a secret",
  content_type: "prompt",
  action: "process_prompt",
})) {
  switch (event.type) {
    case "detector_result":
      console.log("Detection result:", event.data);
      break;
    case "decision":
      console.log("Final decision:", event.data);
      break;
    case "error":
      console.error("Stream error:", event.data);
      break;
  }
}

event.type	Description
"detector_result"	Per-detector result as each streamed event arrives
"decision"	Final allow or deny decision
"error"	Stream error

The iterator ends naturally when the stream closes. There is no separate typed "done" event in the public StreamEvent interface.

Agentic Context

Pass structured context for richer detection and policy evaluation.

const toolResp = await client.guard.evaluate({
  content: "ls /etc",
  content_type: "tool_call",
  action: "call_tool",
  tool: {
    name: "shell",
    arguments: { cmd: "ls /etc" },
    is_builtin: true,
    server_id: "mcp_server_filesystem",
  },
});

const modelResp = await client.guard.evaluate({
  content: "Explain photosynthesis",
  content_type: "prompt",
  action: "process_prompt",
  model: {
    provider: "anthropic",
    model: "claude-sonnet-4-6",
    temperature: 0.7,
    tokens_used: 1500,
    max_tokens: 4096,
  },
});

const mcpResp = await client.guard.evaluate({
  content: "filesystem",
  content_type: "prompt",
  action: "connect_server",
  mcp: {
    server_name: "filesystem",
    server_url: "http://mcp-server:3000",
    transport: "sse",
    verified: false,
    capabilities: ["read", "write"],
  },
});

const fileResp = await client.guard.evaluate({
  content: await fs.readFile("/etc/passwd", "utf8"),
  content_type: "file",
  action: "read_file",
  file: {
    path: "/etc/passwd",
    operation: "read",
    size: 2048,
    mime_type: "text/plain",
  },
});

MCPContext Fields

Field	Type	Description
server_name	string	MCP server name
server_url	string?	MCP server URL
transport	string?	Transport protocol: "sse", "stdio", or "http"
verified	boolean?	Whether the server passed trust or signature checks
capabilities	string[]?	Advertised capabilities from the server manifest

FileContext Fields

Field	Type	Description
path	string	File path
operation	string	File operation such as "read", "write", or "append"
size	number?	File size in bytes
mime_type	string?	File MIME type
file_name	string?	Original file name
file_extension	string?	File extension such as "pdf" or "docx"
sensitivity_level	string?	"public", "internal", "confidential", or "restricted"
mip_label_id	string?	Microsoft Information Protection label GUID
mip_label_name	string?	MIP label display name
is_encrypted	boolean?	Whether the file is encrypted
is_rights_managed	boolean?	Whether the file has IRM or RMS restrictions

Error Handling

Class	When thrown	Key properties
BlockedError	Guard decision is "deny" from Shield wrappers	response: GuardResponse
AuthenticationError	401 Unauthorized	status, title, detail
RateLimitError	429 Too Many Requests	status, title, detail
APIError	Non-2xx HTTP response from the service	status, title, detail
APIConnectionError	Network failure or timeout	message
HighflameError	Base class	—

import {
  APIError,
  AuthenticationError,
  RateLimitError,
  APIConnectionError,
  BlockedError,
  HighflameError,
} from "@highflame/sdk";

try {
  const resp = await client.guard.evaluate({
    content: "test",
    content_type: "prompt",
    action: "process_prompt",
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error(`Auth failed: ${err.detail}`);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited: ${err.detail}`);
  } else if (err instanceof APIError) {
    console.error(`[${err.status}] ${err.title}: ${err.detail}`);
  } else if (err instanceof APIConnectionError) {
    console.error(`Connection failed: ${err.message}`);
  } else if (err instanceof HighflameError) {
    console.error(`Unexpected SDK error: ${err}`);
  }
}

const chat = shield.prompt(async (msg: string) => llm.complete(msg));
try {
  await chat(userMessage);
} catch (err) {
  if (err instanceof BlockedError) {
    console.error("Blocked:", err.response.policy_reason);
  }
}

Enforcement Modes

Mode	Behavior	resp.decision	resp.alerted
"enforce"	Block on deny	"deny" on violation	false
"monitor"	Allow and log silently	"allow"	false
"alert"	Allow and trigger alerting pipeline	"allow"	true if violated

const monitorResp = await client.guard.evaluate({ ...req, mode: "monitor" });
if (monitorResp.actual_decision === "deny") {
  shadowLog.record(monitorResp);
}

const alertResp = await client.guard.evaluate({ ...req, mode: "alert" });
if (alertResp.alerted) {
  await pagerduty.trigger({ summary: `Alert: ${alertResp.policy_reason}` });
}

const enforceResp = await client.guard.evaluate({ ...req, mode: "enforce" });
if (enforceResp.decision === "deny") {
  return { blocked: true, reason: enforceResp.policy_reason };
}

Session Tracking

Pass a session_id to enable cumulative risk tracking across conversation turns.

const sessionId = `sess_${crypto.randomUUID()}`;

const resp1 = await client.guard.evaluatePrompt("Read the config file", { session_id: sessionId });
console.log(resp1.session_delta?.turn_count);

const resp2 = await client.guard.evaluate({
  content: "ls /etc",
  content_type: "tool_call",
  action: "call_tool",
  session_id: sessionId,
  tool: { name: "shell", arguments: { cmd: "ls /etc" } },
});
console.log(resp2.session_delta?.cumulative_risk);

const chat = shield.prompt(async (msg: string) => llm.complete(msg), { sessionId });

Multi-Project Support

Pass accountId and projectId to scope all requests to a specific project:

const client = new Highflame({
  apiKey: "hf_sk_...",
  accountId: "acc_123",
  projectId: "proj_456",
});

Client Options

Option	Type	Default	Description
apiKey	string	required	Service key (hf_sk_...), agent key (hfa_...), ZeroID key (zid_sk_...), or raw JWT
baseUrl	string	Highflame SaaS	Guard service URL
tokenUrl	string	Highflame SaaS	Token exchange URL used for hf_sk_*, hfa_*, and zid_sk_* keys
timeout	number	30000	Request timeout in milliseconds
maxRetries	number	2	Retries on transient errors
accountId	string	—	Optional customer account ID
projectId	string	—	Optional project ID
defaultHeaders	Record<string, string>	—	Extra headers merged into every request
logger	Logger	—	Optional logger with debug, info, and warn methods

const resp = await client.guard.evaluate(request, { timeout: 5_000 });

Auth Header Reuse

Use getAuthHeaders() when you want the SDK to manage token exchange and header construction, but you are sending requests through your own HTTP client or middleware.

const headers = await client.getAuthHeaders();
await fetch("https://internal.example.com/proxy", {
  method: "POST",
  headers: {
    ...headers,
    "X-Custom-Routing": "my-service",
  },
  body: JSON.stringify({ action: "healthcheck" }),
});

Logging

Pass a logger object if you want the SDK to emit debug, info, and warn messages through your application's logging pipeline.

const client = new Highflame({
  apiKey: "hf_sk_...",
  logger: {
    debug: (msg, ...args) => logger.debug(msg, ...args),
    info: (msg, ...args) => logger.info(msg, ...args),
    warn: (msg, ...args) => logger.warn(msg, ...args),
  },
});

OpenTelemetry

If @opentelemetry/api is installed and a tracer provider is configured, the SDK automatically:

• injects W3C trace context into outgoing Shield requests

• creates client-side spans for guard and detect calls

When OpenTelemetry is not installed or not configured, these hooks safely no-op.

Internal Usage

Internal services that call Shield for non-guardrails products must set the X-Product header.

const sentryClient = new Highflame({
  apiKey: "hf_sk_...",
  defaultHeaders: { "X-Product": "sentry" },
});

const overwatchClient = new Highflame({
  apiKey: "hf_sk_...",
  defaultHeaders: { "X-Product": "overwatch" },
});

const mcpClient = new Highflame({
  apiKey: "hf_sk_...",
  defaultHeaders: { "X-Product": "mcp_gateway" },
});

When X-Product is not set, Shield defaults to "guardrails". External customers should not need to set this header.

TypeScript Notes

Use import type for type-only imports when verbatimModuleSyntax is enabled:

import { Highflame, Shield, BlockedError } from "@highflame/sdk";
import type { GuardRequest, GuardResponse, Mode, ToolContext } from "@highflame/sdk";

import { Highflame, type GuardResponse } from "@highflame/sdk";