aiegis-harness (Node) API Reference

Note

About this page

This API reference is hand-rendered directly from the index.d.ts in the source tree. Typedoc was not installed on the build host and Node was not available to invoke it; this page mirrors the .d.ts declarations and their JSDoc comments verbatim rather than running typedoc and inventing additional surface.

If you want a typedoc-generated page in your local checkout, install Node + run npx typedoc --out docs-node index.d.ts from crates/harness-node/. The site of truth is index.d.ts regardless.

01 / Install

Install

npm install aiegis-harness
# or
yarn add aiegis-harness
# or
pnpm add aiegis-harness

Package: aiegis-harness. Native modules are published per platform via NAPI-RS (aiegis-harness.darwin-arm64.node, aiegis-harness.linux-x64.node, etc).

02 / Interfaces

Type declarations

interface EvaluationResult

interface EvaluationResult {
  decision: string
  reason?: string
  layer?: string
  receiptId?: string
  decisionMs: number
  agentDid?: string
  /** Raw upstream JSON as a string. Use JSON.parse() to consume. */
  raw: string
}

Normalized result returned from HarnessClient.evaluate / evaluateOrThrow. Same shape as the Python EvaluationResult; field names are camelCased per Node convention. The raw field carries the full upstream JSON for clients that want layer-by-layer detail.

interface ClientOptions

interface ClientOptions {
  apiToken?: string
  timeoutMs?: number
}

Optional constructor options. apiToken is passed as the X-AEGIS-Tag header on every request (required for the production cloud endpoint, ignored by the local reference daemon). timeoutMs is a per-request timeout in milliseconds.

03 / Class

class HarnessClient

constructor(baseUrl, options?)

constructor(
  baseUrl: string,
  options?: ClientOptions | undefined | null
)

baseUrl: root URL, e.g. "http://127.0.0.1:18100" (local daemon) or "https://aiegis.ie" (cloud prod). The client appends "/api/protect".

options.apiToken: passed as X-AEGIS-Tag header (required for cloud prod, ignored by the local reference daemon).

options.timeoutMs: per-request timeout in milliseconds.

evaluate(action, target?, input?, contextJson?)

evaluate(
  action: string,
  target?: string | undefined | null,
  input?: string | undefined | null,
  contextJson?: string | undefined | null,
): Promise<EvaluationResult>

Sends {action, target, input, context} to <baseUrl>/api/protect. contextJson is a JSON-encoded string of any extra context fields to attach (the wrapper in index.js handles JSON.stringify so callers can pass a plain object).

Resolves with an EvaluationResult. Does not reject on DENY — caller inspects result.decision.

evaluateOrThrow(action, target?, input?, contextJson?)

evaluateOrThrow(
  action: string,
  target?: string | undefined | null,
  input?: string | undefined | null,
  contextJson?: string | undefined | null,
): Promise<EvaluationResult>

Like evaluate, but rejects the promise with HarnessDenied: ... if the decision is not "ALLOW". Convenience for guard-style agent integrations.

health()

health(): Promise<string>

GET /health on the base URL. Returns the JSON body as a string (caller JSON.parses it).

04 / Example

Worked example

import { HarnessClient } from 'aiegis-harness';

const client = new HarnessClient('https://aiegis.ie', {
  apiToken: process.env.AEGIS_KEY,
  timeoutMs: 10_000,
});

// Inspect mode — never throws on DENY.
const result = await client.evaluate(
  'tool.read_file',
  '/etc/hosts',
  '',
  JSON.stringify({ agent_did: 'did:key:z6Mk...' })
);
console.log(result.decision, result.reason, result.layer, result.decisionMs);

// Guard mode — throws on non-ALLOW.
try {
  await client.evaluateOrThrow('tool.shell_exec', 'rm -rf /');
} catch (e) {
  console.error('blocked by harness:', e.message);
}