@trustloopguard/sdk 0.0.1

package/src/client.ts

@@ -0,0 +1,453 @@
+// Thin HTTP client. Mirrors the `Guard.check(draft, ctx)` plugin contract.
+//
+// Retry policy mirrors tl-sdk-rust and the Python SDK — same defaults,
+// same `nextDelay` semantics. Voice callers should pass
+// `{ ...DEFAULT_RETRY, maxAttempts: 1 }` to opt out.
+
+import type { CheckRequest } from './generated/CheckRequest';
+import type { Decision } from './generated/Decision';
+import type { AgentListResponse } from './generated/AgentListResponse';
+import type { AgentProfile } from './generated/AgentProfile';
+import type { ApiKeyBatchRevokeResponse } from './generated/ApiKeyBatchRevokeResponse';
+import type { GuardrailGenerateResponse } from './generated/GuardrailGenerateResponse';
+import type { GuardrailListResponse } from './generated/GuardrailListResponse';
+import type { PolicyDocument } from './generated/PolicyDocument';
+import type { PolicyBatchSetEnabledResponse } from './generated/PolicyBatchSetEnabledResponse';
+import type { PolicyDraftResponse } from './generated/PolicyDraftResponse';
+import type { PolicyListResponse } from './generated/PolicyListResponse';
+import type { PolicyValidateResponse } from './generated/PolicyValidateResponse';
+import type { CreateRunEventRequest } from './generated/CreateRunEventRequest';
+import type { CreateRunRequest } from './generated/CreateRunRequest';
+import type { RunDetail } from './generated/RunDetail';
+import type { RunEventListResponse } from './generated/RunEventListResponse';
+import type { RunEventSummary } from './generated/RunEventSummary';
+import type { RunListResponse } from './generated/RunListResponse';
+import type { RunStatus } from './generated/RunStatus';
+import type { RunSummary } from './generated/RunSummary';
+import type { TraceListResponse } from './generated/TraceListResponse';
+import type { UpdateRunRequest } from './generated/UpdateRunRequest';
+import { Decode, SdkError, Transport, fromResponse, parseRetryAfter } from './errors';
+import { DEFAULT_RETRY, type RetryConfig, nextDelay } from './retry';
+
+export interface ClientOptions {
+  baseUrl: string;
+  apiKey?: string;
+  fetchImpl?: typeof fetch;
+  retry?: RetryConfig;
+  /**
+   * Hook invoked once per retry decision. Useful for surfacing retry
+   * activity in logs / OpenTelemetry without forcing a logger
+   * dependency on the SDK.
+   */
+  onRetry?: (info: { attempt: number; delayS: number; error: SdkError }) => void;
+}
+
+export class Client {
+  private readonly baseUrl: string;
+  private readonly apiKey: string | undefined;
+  private readonly fetchImpl: typeof fetch;
+  private readonly retry: RetryConfig;
+  private readonly onRetry: ClientOptions['onRetry'];
+
+  constructor(opts: ClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+    this.apiKey = opts.apiKey;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.retry = opts.retry ?? DEFAULT_RETRY;
+    this.onRetry = opts.onRetry;
+  }
+
+  async check(req: CheckRequest, signal?: AbortSignal): Promise<Decision> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<Decision>(
+          '/v1/check',
+          {
+            method: 'POST',
+            body: JSON.stringify(req),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async startRun(
+    req: Omit<CreateRunRequest, 'metadata'> & { metadata?: Record<string, unknown> },
+    signal?: AbortSignal,
+  ): Promise<RunSummary> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<RunSummary>(
+          '/v1/runs',
+          {
+            method: 'POST',
+            body: JSON.stringify({ metadata: {}, ...req }),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async listRuns(signal?: AbortSignal): Promise<RunListResponse> {
+    return this.withRetry(
+      (signal) => this.sendJson<RunListResponse>('/v1/runs', { method: 'GET' }, signal),
+      signal,
+    );
+  }
+
+  async getRun(runId: string, signal?: AbortSignal): Promise<RunDetail> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<RunDetail>(
+          `/v1/runs/${encodeURIComponent(runId)}`,
+          { method: 'GET' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async updateRun(
+    runId: string,
+    req: UpdateRunRequest,
+    signal?: AbortSignal,
+  ): Promise<RunSummary> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<RunSummary>(
+          `/v1/runs/${encodeURIComponent(runId)}`,
+          {
+            method: 'PATCH',
+            body: JSON.stringify(req),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async finishRun(
+    runId: string,
+    status: Extract<RunStatus, 'completed' | 'failed' | 'canceled'> = 'completed',
+    signal?: AbortSignal,
+  ): Promise<RunSummary> {
+    return this.updateRun(runId, { status }, signal);
+  }
+
+  async createRunEvent(
+    runId: string,
+    req: Omit<CreateRunEventRequest, 'metadata'> & { metadata?: Record<string, unknown> },
+    signal?: AbortSignal,
+  ): Promise<RunEventSummary> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<RunEventSummary>(
+          `/v1/runs/${encodeURIComponent(runId)}/events`,
+          {
+            method: 'POST',
+            body: JSON.stringify({ metadata: {}, ...req }),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async listRunEvents(runId: string, signal?: AbortSignal): Promise<RunEventListResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<RunEventListResponse>(
+          `/v1/runs/${encodeURIComponent(runId)}/events`,
+          { method: 'GET' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async listRunTraces(runId: string, signal?: AbortSignal): Promise<TraceListResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<TraceListResponse>(
+          `/v1/runs/${encodeURIComponent(runId)}/traces`,
+          { method: 'GET' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async validatePolicy(source: string, signal?: AbortSignal): Promise<PolicyValidateResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendText<PolicyValidateResponse>(
+          '/v1/policies/validate',
+          'POST',
+          source,
+          'application/yaml',
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async listPolicies(signal?: AbortSignal): Promise<PolicyListResponse> {
+    return this.withRetry(
+      (signal) => this.sendJson<PolicyListResponse>('/v1/policies', { method: 'GET' }, signal),
+      signal,
+    );
+  }
+
+  async listAgents(signal?: AbortSignal): Promise<AgentListResponse> {
+    return this.withRetry(
+      (signal) => this.sendJson<AgentListResponse>('/v1/agents', { method: 'GET' }, signal),
+      signal,
+    );
+  }
+
+  async upsertAgent(profile: AgentProfile, signal?: AbortSignal): Promise<AgentProfile> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<AgentProfile>(
+          '/v1/agents',
+          {
+            method: 'POST',
+            body: JSON.stringify(profile),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async getPolicy(policyId: string, signal?: AbortSignal): Promise<PolicyDocument> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<PolicyDocument>(
+          `/v1/policies/${encodeURIComponent(policyId)}`,
+          { method: 'GET' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async upsertPolicy(source: string, signal?: AbortSignal): Promise<PolicyDocument> {
+    return this.withRetry(
+      (signal) =>
+        this.sendText<PolicyDocument>('/v1/policies', 'POST', source, 'application/yaml', signal),
+      signal,
+    );
+  }
+
+  async setPolicyEnabled(
+    policyId: string,
+    enabled: boolean,
+    signal?: AbortSignal,
+  ): Promise<PolicyDocument> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<PolicyDocument>(
+          `/v1/policies/${encodeURIComponent(policyId)}/enabled`,
+          {
+            method: 'PATCH',
+            body: JSON.stringify({ enabled }),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async batchSetPolicyEnabled(
+    policyIds: string[],
+    enabled: boolean,
+    signal?: AbortSignal,
+  ): Promise<PolicyBatchSetEnabledResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<PolicyBatchSetEnabledResponse>(
+          '/v1/policies/batch/enabled',
+          {
+            method: 'PATCH',
+            body: JSON.stringify({ ids: policyIds, enabled }),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  /**
+   * LLM-draft a policy skeleton from a natural-language prompt. The
+   * server holds the provider key; the response is a strict, typed
+   * `PolicyDraftResponse`. Returns a 503-mapped `Unavailable` error when
+   * the deployment has no LLM configured.
+   */
+  async draftPolicy(prompt: string, signal?: AbortSignal): Promise<PolicyDraftResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<PolicyDraftResponse>(
+          '/v1/policies/draft',
+          {
+            method: 'POST',
+            body: JSON.stringify({ prompt }),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  /**
+   * Derive a guardrail policy set from the agent's stored `system_prompt`,
+   * auto-persist each draft with `enabled=false`, and return what was
+   * saved. The caller must have previously registered the agent (with a
+   * non-empty `system_prompt`) via `POST /v1/agents`.
+   *
+   * Errors:
+   * - `NotFound` (404) — agent is not registered.
+   * - `Unprocessable` (422) — agent has no `system_prompt`.
+   * - `Unavailable` (503) — the deployment has no LLM configured.
+   */
+  async generateGuardrails(
+    agentId: string,
+    signal?: AbortSignal,
+  ): Promise<GuardrailGenerateResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<GuardrailGenerateResponse>(
+          `/v1/agents/${encodeURIComponent(agentId)}/guardrails/generate`,
+          { method: 'POST' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  /**
+   * List policies owned by an agent. Empty when the agent has none or
+   * doesn't exist — existence is the caller's concern.
+   */
+  async listGuardrails(agentId: string, signal?: AbortSignal): Promise<GuardrailListResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<GuardrailListResponse>(
+          `/v1/agents/${encodeURIComponent(agentId)}/guardrails`,
+          { method: 'GET' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async deletePolicy(policyId: string, signal?: AbortSignal): Promise<void> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<void>(
+          `/v1/policies/${encodeURIComponent(policyId)}`,
+          { method: 'DELETE' },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  async batchRevokeApiKeys(
+    apiKeyIds: string[],
+    signal?: AbortSignal,
+  ): Promise<ApiKeyBatchRevokeResponse> {
+    return this.withRetry(
+      (signal) =>
+        this.sendJson<ApiKeyBatchRevokeResponse>(
+          '/v1/api-keys/batch/revoke',
+          {
+            method: 'PATCH',
+            body: JSON.stringify({ ids: apiKeyIds }),
+          },
+          signal,
+        ),
+      signal,
+    );
+  }
+
+  private async withRetry<T>(
+    send: (signal?: AbortSignal) => Promise<T>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const start = performance.now();
+    let attempt = 0;
+    while (true) {
+      attempt += 1;
+      try {
+        return await send(signal);
+      } catch (e) {
+        if (!(e instanceof SdkError)) throw e;
+        const elapsedS = (performance.now() - start) / 1000;
+        const delay = nextDelay(this.retry, attempt, elapsedS, e, Math.random());
+        if (delay === undefined) throw e;
+        this.onRetry?.({ attempt, delayS: delay, error: e });
+        await new Promise((resolve) => setTimeout(resolve, delay * 1000));
+      }
+    }
+  }
+
+  private async sendText<T>(
+    path: string,
+    method: string,
+    body: string,
+    contentType: string,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    return this.sendJson<T>(
+      path,
+      {
+        method,
+        headers: { 'content-type': contentType },
+        body,
+      },
+      signal,
+    );
+  }
+
+  private async sendJson<T>(path: string, init: RequestInit, signal?: AbortSignal): Promise<T> {
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      ...((init.headers as Record<string, string> | undefined) ?? {}),
+    };
+    if (this.apiKey !== undefined) {
+      headers['authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    const requestInit: RequestInit = {
+      ...init,
+      headers,
+    };
+    if (signal !== undefined) {
+      requestInit.signal = signal;
+    }
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, requestInit);
+    } catch (e) {
+      throw new Transport(e instanceof Error ? e.message : String(e));
+    }
+
+    if (res.status === 204) return undefined as T;
+
+    if (res.ok) {
+      try {
+        return (await res.json()) as T;
+      } catch (e) {
+        throw new Decode(`failed to parse response: ${String(e)}`);
+      }
+    }
+
+    const retryAfter = parseRetryAfter(res.headers.get('retry-after'));
+    const body = await res.text().catch(() => '');
+    throw fromResponse(res.status, body, retryAfter);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,202 @@
+// Typed errors for the TrustLoopGuard TypeScript SDK.
+//
+// Mirrors `tl-sdk-rust`'s `SdkError` and the Python SDK's exception
+// hierarchy. Callers branch on `instanceof` (or on `error.code`) instead
+// of inspecting status codes:
+//
+//   try {
+//     await client.check(req);
+//   } catch (e) {
+//     if (e instanceof RateLimited) {
+//       await sleep((e.retryAfter ?? 1) * 1000);
+//     } else if (e instanceof Unauthorized) {
+//       refreshToken();
+//     }
+//   }
+//
+// The status -> code fallback table and retriable-by-default set are kept
+// in lockstep with `tl-core::ApiErrorCode::from_http_status` and the
+// Python `_STATUS_TO_CODE` dict — the parity is asserted by tests in
+// every SDK so they cannot drift silently.
+
+import type { ApiError } from './generated/ApiError';
+import type { ApiErrorCode } from './generated/ApiErrorCode';
+
+const STATUS_TO_CODE: Record<number, ApiErrorCode> = {
+  400: 'invalid',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'not_found',
+  410: 'gone',
+  422: 'unprocessable',
+  429: 'rate_limited',
+  500: 'internal',
+  501: 'internal',
+  502: 'unavailable',
+  503: 'unavailable',
+  504: 'unavailable',
+};
+
+const DEFAULT_RETRIABLE: ReadonlySet<ApiErrorCode> = new Set<ApiErrorCode>([
+  'rate_limited',
+  'unavailable',
+]);
+
+export function codeFromHttpStatus(status: number): ApiErrorCode {
+  if (status in STATUS_TO_CODE) {
+    return STATUS_TO_CODE[status]!;
+  }
+  if (status >= 500 && status < 600) return 'internal';
+  return 'invalid';
+}
+
+export function synthesizeApiError(status: number, body: string): ApiError {
+  const code = codeFromHttpStatus(status);
+  return {
+    code,
+    message: body || `server returned status ${status}`,
+    retriable: DEFAULT_RETRIABLE.has(code),
+    details: null,
+  };
+}
+
+export class SdkError extends Error {
+  readonly error: ApiError;
+  constructor(error: ApiError) {
+    super(`${error.code}: ${error.message}`);
+    this.name = 'SdkError';
+    this.error = error;
+    // Preserve prototype chain for `instanceof` to work after transpile.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  get code(): ApiErrorCode {
+    return this.error.code;
+  }
+  isRetriable(): boolean {
+    return this.error.retriable;
+  }
+}
+
+// One subclass per ApiErrorCode. The classes carry no extra behavior
+// beyond their name — they exist so callers can use `instanceof` and
+// stack traces are labeled. RateLimited is the one exception: it carries
+// the parsed Retry-After value.
+
+export class Invalid extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Invalid';
+  }
+}
+export class Unauthorized extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Unauthorized';
+  }
+}
+export class Forbidden extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Forbidden';
+  }
+}
+export class NotFound extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'NotFound';
+  }
+}
+export class Gone extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Gone';
+  }
+}
+export class Unprocessable extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Unprocessable';
+  }
+}
+export class RateLimited extends SdkError {
+  readonly retryAfter: number | undefined;
+  constructor(error: ApiError, retryAfter?: number) {
+    super(error);
+    this.name = 'RateLimited';
+    this.retryAfter = retryAfter;
+  }
+}
+export class Internal extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Internal';
+  }
+}
+export class Unavailable extends SdkError {
+  constructor(error: ApiError) {
+    super(error);
+    this.name = 'Unavailable';
+  }
+}
+export class Transport extends SdkError {
+  constructor(message: string) {
+    super({ code: 'unavailable', message, retriable: true, details: null });
+    this.name = 'Transport';
+  }
+}
+export class Decode extends SdkError {
+  constructor(message: string) {
+    super({ code: 'internal', message, retriable: false, details: null });
+    this.name = 'Decode';
+  }
+}
+
+const CODE_TO_CLASS: Record<ApiErrorCode, new (e: ApiError) => SdkError> = {
+  invalid: Invalid,
+  unauthorized: Unauthorized,
+  forbidden: Forbidden,
+  not_found: NotFound,
+  gone: Gone,
+  unprocessable: Unprocessable,
+  rate_limited: RateLimited,
+  internal: Internal,
+  unavailable: Unavailable,
+};
+
+function isApiError(value: unknown): value is ApiError {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Partial<ApiError>;
+  return (
+    typeof v.code === 'string' &&
+    typeof v.message === 'string' &&
+    typeof v.retriable === 'boolean' &&
+    v.code in CODE_TO_CLASS
+  );
+}
+
+export function fromResponse(
+  status: number,
+  body: string,
+  retryAfter?: number,
+): SdkError {
+  let apiErr: ApiError;
+  try {
+    const parsed: unknown = JSON.parse(body);
+    apiErr = isApiError(parsed) ? parsed : synthesizeApiError(status, body);
+  } catch {
+    apiErr = synthesizeApiError(status, body);
+  }
+  if (apiErr.code === 'rate_limited') {
+    return new RateLimited(apiErr, retryAfter);
+  }
+  const Cls = CODE_TO_CLASS[apiErr.code];
+  return new Cls(apiErr);
+}
+
+export function parseRetryAfter(header: string | null | undefined): number | undefined {
+  if (header === null || header === undefined) return undefined;
+  const trimmed = header.trim();
+  const n = Number(trimmed);
+  if (!Number.isFinite(n)) return undefined;
+  return n;
+}

package/src/generated/AgentAuthority.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type AgentAuthority = { can_promise: Array<string>, cannot_promise: Array<string>, };

package/src/generated/AgentListResponse.ts

@@ -0,0 +1,4 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AgentProfile } from "./AgentProfile";
+
+export type AgentListResponse = { agents: Array<AgentProfile>, };

package/src/generated/AgentProfile.ts

@@ -0,0 +1,23 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AgentAuthority } from "./AgentAuthority";
+import type { AgentScope } from "./AgentScope";
+import type { AgentTone } from "./AgentTone";
+import type { KnowledgeSource } from "./KnowledgeSource";
+
+/**
+ * What an agent is, what it may claim, and how it should sound.
+ *
+ * Authored as YAML by the customer (see `policies/agents/*.yaml`), parsed
+ * by `tl-policy::load_agent_str`, persisted in Postgres, cached in process,
+ * and consulted by Tier 2 (out-of-scope embedding lookup) and Tier 3
+ * (LLM judge ground truth).
+ */
+export type AgentProfile = { agent_id: string, display_name: string, scope: AgentScope, authority: AgentAuthority, tone: AgentTone, knowledge_sources: Array<KnowledgeSource>, escalation_triggers: Array<string>,
+/**
+ * Raw system prompt the customer ships to their LLM. Source of truth
+ * for auto-generating guardrails: `POST /v1/agents/{id}/guardrails:generate`
+ * reads this and asks an LLM to derive a policy set tailored to it.
+ * Optional at the type level so existing profiles keep deserializing;
+ * the generate endpoint enforces presence at call time.
+ */
+system_prompt?: string, };

package/src/generated/AgentScope.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type AgentScope = { in_scope: Array<string>, out_of_scope: Array<string>, };

package/src/generated/AgentTone.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type AgentTone = { target: string, forbidden: Array<string>, };