@trustloopguard/sdk 0.0.1

package/dist/guard.js

@@ -0,0 +1,211 @@
+// `guard()` — output-boundary helper.
+//
+// Most integrations should create one guardrail at startup and call it before
+// delivering an agent draft:
+//
+//   const guardrail = guard({ agentId: 'acme-support-v3' });
+//   const reply = await guardrail({ input: userMessage, draft: agentDraft });
+//   await sendToCustomer(reply);
+//
+// The lower-level form remains available for custom client ownership:
+//
+//   const reply = await guard({
+//     client,
+//     input,
+//     draft,
+//     context,
+//     agentId: 'acme-support-v3',
+//     onBlock:    () => cannedSafeReply,
+//     onEscalate: () => { humanQueue.push(...); return holdMessage; },
+//   });
+//   await sendToCustomer(reply);
+//
+// The handler stays the source of truth on what to do per-verdict.
+// `guard` just makes the dispatch ergonomic and applies a fail-open
+// default for transport errors so an outage on our side doesn't take
+// down the agent.
+//
+// Factory guards support three presets:
+//   strict                -> treat rewrite verdicts as blocked output
+//   rewrite               -> use safeOutput, block when no safeOutput exists
+//   rewrite_or_regenerate -> use safeOutput, otherwise regenerate and check again
+import { Client } from './client';
+import { SdkError } from './errors';
+const DEFAULT_BLOCK_MESSAGE = "I can't help with that request.";
+const DEFAULT_ESCALATE_MESSAGE = 'A human teammate should review this before we continue.';
+export const GuardMode = {
+    Strict: 'strict',
+    Rewrite: 'rewrite',
+    RewriteOrRegenerate: 'rewrite_or_regenerate',
+};
+export function guard(opts) {
+    if ('input' in opts && 'draft' in opts) {
+        return guardOnce(opts);
+    }
+    return createOutputGuard(opts);
+}
+async function guardOnce(opts) {
+    const start = performance.now();
+    const req = {
+        agent_id: opts.agentId,
+        channel: opts.channel ?? 'chat',
+        input: opts.input,
+        proposed_output: opts.draft,
+        domain: opts.domain ?? null,
+        policies: [],
+        // Server's `context` is `Record<string, unknown> | null`; null
+        // matches the wire shape when no context is supplied.
+        context: (opts.context ?? null),
+        trace_id: opts.traceId ?? null,
+    };
+    addDefined(req, 'run_id', opts.runId);
+    addDefined(req, 'run_event_id', opts.runEventId);
+    addDefined(req, 'run_event', opts.runEvent);
+    let decision;
+    try {
+        decision = await opts.client.check(req, opts.signal);
+    }
+    catch (e) {
+        if (!(e instanceof SdkError))
+            throw e;
+        const fallback = opts.onError ? await opts.onError(e, opts.draft) : opts.draft; // fail-open default
+        opts.log?.({
+            trace_id: opts.traceId ?? '',
+            // Wire shape doesn't have an "error" verdict; we synthesise the
+            // log line for observability without lying about the wire.
+            verdict: 'allow',
+            branch: 'error',
+            latency_ms: Math.round(performance.now() - start),
+        });
+        return fallback;
+    }
+    const result = await dispatch(opts, decision);
+    opts.log?.({
+        trace_id: decision.trace_id,
+        verdict: decision.verdict,
+        branch: branchFor(decision.verdict),
+        latency_ms: Math.round(performance.now() - start),
+    });
+    return result;
+}
+function createOutputGuard(opts) {
+    const client = opts.client ?? new Client(clientOptions(opts));
+    return async (call) => {
+        const mode = call.mode ?? opts.mode ?? 'rewrite';
+        const regenerate = call.regenerate ?? opts.regenerate;
+        const maxRegenerations = call.maxRegenerations ?? opts.maxRegenerations ?? 1;
+        const onBlock = decisionHandler(call.onBlock ?? opts.onBlock, DEFAULT_BLOCK_MESSAGE);
+        const onEscalate = decisionHandler(call.onEscalate ?? opts.onEscalate, DEFAULT_ESCALATE_MESSAGE);
+        const onError = errorHandler(call.onError ?? opts.onError, opts.failClosed === true ? DEFAULT_BLOCK_MESSAGE : undefined);
+        const runAttempt = async (currentDraft, completedRegenerations) => {
+            const onRevise = async (revised, checkedDraft, decision) => {
+                if (mode === 'strict')
+                    return await onBlock(decision);
+                if (revised !== null)
+                    return revised;
+                if (mode !== 'rewrite_or_regenerate' ||
+                    regenerate === undefined ||
+                    completedRegenerations >= maxRegenerations) {
+                    return await onBlock(decision);
+                }
+                const nextAttempt = completedRegenerations + 1;
+                const nextDraft = await regenerate({
+                    input: call.input,
+                    draft: checkedDraft,
+                    decision,
+                    reason: decision.reason,
+                    safeOutput: decision.safe_output ?? null,
+                    attempt: nextAttempt,
+                    maxAttempts: maxRegenerations,
+                });
+                return await runAttempt(nextDraft, nextAttempt);
+            };
+            const guardOpts = {
+                client,
+                agentId: opts.agentId,
+                input: call.input,
+                draft: currentDraft,
+                context: { ...(opts.context ?? {}), ...(call.context ?? {}) },
+                onBlock,
+                onEscalate,
+                onRevise,
+            };
+            addDefined(guardOpts, 'channel', call.channel ?? opts.channel);
+            addDefined(guardOpts, 'domain', call.domain ?? opts.domain);
+            addDefined(guardOpts, 'traceId', call.traceId);
+            addDefined(guardOpts, 'runId', call.runId);
+            addDefined(guardOpts, 'runEventId', call.runEventId);
+            addDefined(guardOpts, 'runEvent', call.runEvent);
+            addDefined(guardOpts, 'onError', onError);
+            addDefined(guardOpts, 'log', call.log ?? opts.log);
+            addDefined(guardOpts, 'signal', call.signal);
+            return await guardOnce(guardOpts);
+        };
+        return await runAttempt(call.draft, 0);
+    };
+}
+async function dispatch(opts, decision) {
+    switch (decision.verdict) {
+        case 'allow':
+            return opts.onAllow ? await opts.onAllow(opts.draft, decision) : opts.draft;
+        case 'rewrite':
+            return opts.onRevise
+                ? await opts.onRevise(decision.safe_output ?? null, opts.draft, decision)
+                : (decision.safe_output ?? opts.draft);
+        case 'block':
+            return await opts.onBlock(decision);
+        case 'escalate':
+            return await opts.onEscalate(decision);
+    }
+}
+function branchFor(v) {
+    if (v === 'rewrite')
+        return 'revise';
+    return v;
+}
+function decisionHandler(handler, defaultMessage) {
+    return async (decision) => {
+        if (handler === undefined)
+            return defaultMessage;
+        if (typeof handler === 'string')
+            return handler;
+        return await handler(decision);
+    };
+}
+function errorHandler(handler, defaultMessage) {
+    if (handler === undefined && defaultMessage === undefined)
+        return undefined;
+    return async (err, draft) => {
+        if (handler === undefined)
+            return defaultMessage ?? draft;
+        if (typeof handler === 'string')
+            return handler;
+        return await handler(err, draft);
+    };
+}
+function env(...names) {
+    const proc = globalThis;
+    for (const name of names) {
+        const value = proc.process?.env?.[name];
+        if (value !== undefined && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function clientOptions(opts) {
+    const clientOpts = {
+        baseUrl: opts.baseUrl ??
+            env('TL_SERVER_URL', 'TRUSTLOOPGUARD_URL', 'TRUSTLOOP_URL') ??
+            'http://127.0.0.1:8080',
+    };
+    addDefined(clientOpts, 'apiKey', opts.apiKey ?? env('TL_API_KEY', 'TRUSTLOOPGUARD_API_KEY', 'TRUSTLOOP_API_KEY'));
+    addDefined(clientOpts, 'retry', opts.retry);
+    addDefined(clientOpts, 'fetchImpl', opts.fetchImpl);
+    addDefined(clientOpts, 'onRetry', opts.onRetry);
+    return clientOpts;
+}
+function addDefined(target, key, value) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+export * from './generated/CheckRequest';
+export * from './generated/Decision';
+export * from './generated/Verdict';
+export * from './generated/Channel';
+export * from './generated/Severity';
+export * from './generated/TriggeredPolicy';
+export * from './generated/AgentAuthority';
+export * from './generated/AgentListResponse';
+export * from './generated/AgentProfile';
+export * from './generated/AgentScope';
+export * from './generated/AgentTone';
+export * from './generated/KnowledgeSource';
+export * from './generated/CreateKnowledgeSourceRequest';
+export * from './generated/DashboardKnowledgeSourceKind';
+export * from './generated/KnowledgeFileInput';
+export * from './generated/KnowledgeFileMetadata';
+export * from './generated/KnowledgeSourceDocument';
+export * from './generated/KnowledgeSourceFileResponse';
+export * from './generated/KnowledgeSourceListResponse';
+export * from './generated/KnowledgeSourceStatus';
+export * from './generated/ApiError';
+export * from './generated/ApiErrorCode';
+export * from './generated/PolicyDocument';
+export * from './generated/PolicyBatchSetEnabledRequest';
+export * from './generated/PolicyBatchSetEnabledResponse';
+export * from './generated/PolicyListResponse';
+export * from './generated/PolicySetEnabledRequest';
+export * from './generated/PolicySummary';
+export * from './generated/PolicyValidateResponse';
+export * from './generated/PolicyValidationIssue';
+export * from './generated/PolicyAction';
+export * from './generated/PolicyMatchType';
+export * from './generated/PolicyDraft';
+export * from './generated/PolicyDraftRequest';
+export * from './generated/PolicyDraftResponse';
+export * from './generated/GuardrailGenerateResponse';
+export * from './generated/GuardrailListResponse';
+export * from './generated/ApiKeyBatchRevokeRequest';
+export * from './generated/ApiKeyBatchRevokeResponse';
+export * from './generated/ApiKeyListResponse';
+export * from './generated/CreateApiKeyRequest';
+export * from './generated/CreateApiKeyResponse';
+export * from './generated/DashboardApiKey';
+export * from './generated/WorkspaceSettings';
+export * from './generated/TraceListResponse';
+export * from './generated/TraceSummary';
+export * from './generated/CreateRunEventRequest';
+export * from './generated/CreateRunRequest';
+export * from './generated/UpdateRunRequest';
+export * from './generated/RunDetail';
+export * from './generated/RunEventKind';
+export * from './generated/RunEventListResponse';
+export * from './generated/RunEventSummary';
+export * from './generated/RunKind';
+export * from './generated/RunListResponse';
+export * from './generated/RunStatus';
+export * from './generated/RunSummary';
+export { Client } from './client';
+export type { ClientOptions } from './client';
+export { GuardMode, guard } from './guard';
+export type { GuardCallbacks, GuardOptions, GuardFactoryOptions, GuardCallOptions, GuardLogEvent, OutputGuard, RegenerateFeedback, } from './guard';
+export { DEFAULT_RETRY, nextDelay } from './retry';
+export type { RetryConfig } from './retry';
+export { SdkError, Invalid, Unauthorized, Forbidden, NotFound, Gone, Unprocessable, RateLimited, Internal, Unavailable, Transport, Decode, codeFromHttpStatus, synthesizeApiError, fromResponse, parseRetryAfter, } from './errors';

package/dist/index.js

@@ -0,0 +1,64 @@
+// Public surface of the TrustLoopGuard TypeScript SDK.
+// Type definitions are generated from Rust by `cargo run -p tl-codegen`.
+// See README.md in src/generated for regen instructions.
+export * from './generated/CheckRequest';
+export * from './generated/Decision';
+export * from './generated/Verdict';
+export * from './generated/Channel';
+export * from './generated/Severity';
+export * from './generated/TriggeredPolicy';
+export * from './generated/AgentAuthority';
+export * from './generated/AgentListResponse';
+export * from './generated/AgentProfile';
+export * from './generated/AgentScope';
+export * from './generated/AgentTone';
+export * from './generated/KnowledgeSource';
+export * from './generated/CreateKnowledgeSourceRequest';
+export * from './generated/DashboardKnowledgeSourceKind';
+export * from './generated/KnowledgeFileInput';
+export * from './generated/KnowledgeFileMetadata';
+export * from './generated/KnowledgeSourceDocument';
+export * from './generated/KnowledgeSourceFileResponse';
+export * from './generated/KnowledgeSourceListResponse';
+export * from './generated/KnowledgeSourceStatus';
+export * from './generated/ApiError';
+export * from './generated/ApiErrorCode';
+export * from './generated/PolicyDocument';
+export * from './generated/PolicyBatchSetEnabledRequest';
+export * from './generated/PolicyBatchSetEnabledResponse';
+export * from './generated/PolicyListResponse';
+export * from './generated/PolicySetEnabledRequest';
+export * from './generated/PolicySummary';
+export * from './generated/PolicyValidateResponse';
+export * from './generated/PolicyValidationIssue';
+export * from './generated/PolicyAction';
+export * from './generated/PolicyMatchType';
+export * from './generated/PolicyDraft';
+export * from './generated/PolicyDraftRequest';
+export * from './generated/PolicyDraftResponse';
+export * from './generated/GuardrailGenerateResponse';
+export * from './generated/GuardrailListResponse';
+export * from './generated/ApiKeyBatchRevokeRequest';
+export * from './generated/ApiKeyBatchRevokeResponse';
+export * from './generated/ApiKeyListResponse';
+export * from './generated/CreateApiKeyRequest';
+export * from './generated/CreateApiKeyResponse';
+export * from './generated/DashboardApiKey';
+export * from './generated/WorkspaceSettings';
+export * from './generated/TraceListResponse';
+export * from './generated/TraceSummary';
+export * from './generated/CreateRunEventRequest';
+export * from './generated/CreateRunRequest';
+export * from './generated/UpdateRunRequest';
+export * from './generated/RunDetail';
+export * from './generated/RunEventKind';
+export * from './generated/RunEventListResponse';
+export * from './generated/RunEventSummary';
+export * from './generated/RunKind';
+export * from './generated/RunListResponse';
+export * from './generated/RunStatus';
+export * from './generated/RunSummary';
+export { Client } from './client';
+export { GuardMode, guard } from './guard';
+export { DEFAULT_RETRY, nextDelay } from './retry';
+export { SdkError, Invalid, Unauthorized, Forbidden, NotFound, Gone, Unprocessable, RateLimited, Internal, Unavailable, Transport, Decode, codeFromHttpStatus, synthesizeApiError, fromResponse, parseRetryAfter, } from './errors';

package/dist/retry.d.ts

@@ -0,0 +1,18 @@
+import { SdkError } from './errors';
+export interface RetryConfig {
+    /** Total attempts including the initial one. `1` = no retry. */
+    maxAttempts: number;
+    /** Hard cap on total wall time including sleeps, in seconds. */
+    totalBudgetS: number;
+    /** Base for exponential backoff: delay = base * 2^(attempt-1). */
+    baseDelayS: number;
+    /** Cap on a single retry delay; prevents runaway exponential. */
+    maxDelayS: number;
+}
+export declare const DEFAULT_RETRY: Readonly<RetryConfig>;
+/**
+ * Compute the delay before the next attempt, or `undefined` to stop.
+ * Pure mirror of `tl_sdk_rust::RetryConfig::next_delay` and
+ * `trustloopguard.retry.RetryConfig.next_delay`.
+ */
+export declare function nextDelay(cfg: RetryConfig, attempt: number, elapsedS: number, err: SdkError, jitterFraction: number): number | undefined;

package/dist/retry.js

@@ -0,0 +1,48 @@
+// Retry policy for the TrustLoopGuard TypeScript SDK.
+//
+// Mirrors `tl-sdk-rust`'s `RetryConfig` exactly. Same defaults
+// (4 attempts, 30s budget, 200ms base, 8s cap), same `nextDelay`
+// contract: given the attempt number, elapsed time, the error that just
+// occurred, and a jitter fraction, return the delay before the next
+// attempt (in seconds) or `undefined` to stop.
+//
+// The function is pure so it can be unit-tested without spinning up an
+// HTTP server. Production callers feed `Math.random()`; tests pin the
+// value for determinism.
+import { RateLimited, SdkError } from './errors';
+export const DEFAULT_RETRY = Object.freeze({
+    maxAttempts: 4,
+    totalBudgetS: 30.0,
+    baseDelayS: 0.2,
+    maxDelayS: 8.0,
+});
+/**
+ * Compute the delay before the next attempt, or `undefined` to stop.
+ * Pure mirror of `tl_sdk_rust::RetryConfig::next_delay` and
+ * `trustloopguard.retry.RetryConfig.next_delay`.
+ */
+export function nextDelay(cfg, attempt, elapsedS, err, jitterFraction) {
+    if (!err.isRetriable())
+        return undefined;
+    if (attempt >= cfg.maxAttempts)
+        return undefined;
+    if (elapsedS >= cfg.totalBudgetS)
+        return undefined;
+    const exp = cfg.baseDelayS * 2 ** (attempt - 1);
+    const capped = Math.min(exp, cfg.maxDelayS);
+    // ±25% jitter: jitterFraction in [0,1] maps to multiplier [0.75, 1.25].
+    const frac = Math.max(0, Math.min(1, jitterFraction));
+    const multiplier = 0.75 + frac * 0.5;
+    const jittered = capped * multiplier;
+    let delay;
+    if (err instanceof RateLimited && err.retryAfter !== undefined) {
+        delay = Math.max(err.retryAfter, jittered);
+    }
+    else {
+        delay = jittered;
+    }
+    const remaining = cfg.totalBudgetS - elapsedS;
+    if (remaining <= 0)
+        return undefined;
+    return Math.min(delay, remaining);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@trustloopguard/sdk",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for TrustLoopGuard. Types are generated from Rust via tl-codegen; do not hand-edit src/generated.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.0"
+  }
+}