@ciphyrshq/sdk 2.6.0 → 3.0.0

package/types.d.ts

@@ -83,9 +83,22 @@ export interface WaitForJobOptions {
 export interface ProtectOptions extends MaskOptions {
   /** Default true — purge vault after restore (data minimisation). */
   purge?: boolean;
+  /**
+   * What to do when the masker is unreachable. DEFAULT FALSE (fail closed):
+   * the call throws and your LLM never sees the raw text. `true` sends the
+   * RAW, UNMASKED input to your LLM and returns it unrestored with
+   * `failedOpen: true`. Falls back to the client-wide `failOpen`.
+   *
+   * `null` means unset, not "fail open". The legacy `failClosed` key is NOT
+   * read here — it has never done anything on scan.protect and still does
+   * not, because on this surface turning fail-closed off means sending
+   * unmasked PII to your model.
+   */
+  failOpen?: boolean | null;
 }
 export interface ProtectContext {
-  sessionId: string;
+  /** null only on the failOpen path, where no vault session was ever created. */
+  sessionId: string | null;
   entitiesFound: any[];
 }
 export interface ProtectResult {
@@ -95,9 +108,15 @@ export interface ProtectResult {
   maskedInput: string;
   /** What the LLM returned, before unmask (audit). */
   maskedOutput: string;
-  sessionId: string;
+  sessionId: string | null;
   entitiesFound: any[];
   tokensRestored: number;
+  /**
+   * Present only when `failOpen: true` and the masker was unreachable — the
+   * text was NOT masked. Absent on every normal round-trip, so auditing
+   * "was this really masked?" is a property check, not a guess.
+   */
+  failedOpen?: true;
 }
 export type ProtectLLMCall = (masked: string, ctx: ProtectContext) => Promise<string>;
 
@@ -260,6 +279,22 @@ export interface CiphyrsClientOptions {
   dashUrl?: string;
   /** Request timeout in milliseconds (default: 10000) */
   timeout?: number;
+  /**
+   * Fleet-wide failure posture for protectTool, guard.wrap and scan.protect
+   * when Ciphyrs cannot be reached.
+   *
+   * DEFAULT FALSE — FAIL CLOSED: the tool is not executed, the LLM is not
+   * called, and the error surfaces. This is a BEHAVIOUR CHANGE for
+   * protectTool, which previously failed OPEN and ran the tool unauthorised
+   * during an outage while the other two refused to proceed. Set `true` to
+   * restore the old behaviour across the client; `{ failOpen: true }` on an
+   * individual call overrides this either way. An existing protectTool caller
+   * who passed `failClosed: false` still fails open, unchanged — but that
+   * legacy key is read on protectTool ONLY, never here.
+   *
+   * `null` means unset (fail closed), not fail open.
+   */
+  failOpen?: boolean | null;
 }
 
 // ── V58 Guard ────────────────────────────────────────────────────────────
@@ -301,13 +336,32 @@ export interface GuardWrapResult {
   reason?: string;
   decision: GuardDecision;
   detections?: GuardCheckResult['detections'];
-  decision_id: string;
+  decision_id: string | null;
+  /** Present only when a check was skipped because the guard was unreachable
+   *  and `failOpen` was set — i.e. this "allow" was never actually decided. */
+  failedOpen?: true;
+}
+
+/** The one failure-posture switch, shared by guard.wrap, scan.protect and protectTool. */
+export interface FailPostureOptions {
+  /**
+   * Run anyway when Ciphyrs is unreachable. DEFAULT FALSE — fail closed:
+   * the LLM is not called / the tool is not executed and the error surfaces.
+   * Falls back to the client-wide `failOpen` when omitted.
+   *
+   * `null` is accepted and means UNSET, exactly like omitting the key, so a
+   * posture read out of JSON config, a database column or a `{ ...defaults }`
+   * spread falls through to the client posture instead of choosing one.
+   * Anything the SDK cannot read as an unmistakable yes or no is unset too —
+   * the fail-open direction is only ever reached by a value that says so.
+   */
+  failOpen?: boolean | null;
 }
 export type GuardLLMCall = (input: string) => Promise<string>;
 
 export declare class GuardResource {
   check(params: GuardCheckParams): Promise<GuardCheckResult>;
-  wrap(userInput: string, llmCall: GuardLLMCall, opts?: GuardCheckParams): Promise<GuardWrapResult>;
+  wrap(userInput: string, llmCall: GuardLLMCall, opts?: GuardCheckParams & FailPostureOptions): Promise<GuardWrapResult>;
   getPolicy(): Promise<{ policy_mode: GuardPolicyMode; modes: any[] }>;
   setPolicy(mode: GuardPolicyMode): Promise<{ policy_mode: GuardPolicyMode }>;
   decisions(opts?: { limit?: number; decision?: GuardDecision }): Promise<{ decisions: any[]; total: number }>;
@@ -379,4 +433,210 @@ export declare class CiphyrsClient {
   maskAsync(text: string, opts?: MaskAsyncOptions): Promise<MaskAsyncResult>;
   waitForJob(jobId: string, opts?: WaitForJobOptions): Promise<JobResult>;
   createKey(opts?: { name?: string; scopes?: string[] }): Promise<{ apiKey: string; key: ApiKey }>;
-}
+
+  // ── Agent health (V39 heartbeat, V143 windows + metrics) ────────────────
+  reportHeartbeat(args: {
+    agentName?: string; agentId?: string;
+    status?: AgentHealthStatus; projectName?: string;
+    latencyMs?: number | null; errorMessage?: string | null;
+    environment?: string; heartbeatIntervalS?: number;
+    metrics?: AgentProcessMetrics; metadata?: Record<string, unknown>;
+  }): Promise<{ ok: boolean; agent_id?: string; prev_status?: string; new_status?: string; error?: string }>;
+  startHealthMonitor(args: {
+    agentName?: string; agentId?: string; projectName?: string;
+    intervalMs?: number; environment?: string;
+    probe?: () => Promise<{ status?: AgentHealthStatus; latencyMs?: number } | void>;
+  }): ReturnType<typeof setInterval>;
+  stopHealthMonitor(): void;
+  setAgentMonitoring(agentId: string, opts: {
+    heartbeatTimeoutS?: number | null; probeUrl?: string | null;
+  }): Promise<{ monitoring: { id: string; name: string; heartbeat_interval_s: number | null; heartbeat_timeout_s: number | null; probe_url: string | null; probe_status: string | null } }>;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+//  Tracing (2.7) — spans, and the cross-process propagation the topology
+//  graph is derived from. See src/propagation.js.
+// ═════════════════════════════════════════════════════════════════════════
+
+export type AgentHealthStatus = 'up' | 'degraded' | 'failing' | 'down' | 'unknown';
+
+/** Process metrics shipped with a heartbeat; the server turns a struggling
+ *  process into `degraded` rather than waiting for it to go silent. */
+export interface AgentProcessMetrics {
+  rss_mb?: number; heap_mb?: number; cpu_pct?: number;
+  event_loop_lag_ms?: number; thread_lag_ms?: number;
+  error_rate?: number; uptime_s?: number;
+  spans_since_last?: number; errors_since_last?: number; active_traces?: number;
+  runtime?: string; sdk_version?: string; hostname?: string;
+}
+
+export type SpanKind = 'agent' | 'tool' | 'llm_call' | 'chain' | 'retrieval' | 'communication' | 'handoff';
+
+export interface SpanOptions {
+  /** Explicit parent. Omit and the enclosing span is used automatically. */
+  parentSpanId?: string | null;
+  agentName?: string;
+  kind?: SpanKind;
+  /** Opt out of auto-entering ambient context; manage it with span.run(). */
+  scoped?: boolean;
+}
+
+export declare class Span {
+  readonly spanId: string;
+  readonly agentName?: string;
+  setInput(text: string): this;
+  setOutput(text: string): this;
+  setStatus(status: 'ok' | 'error'): this;
+  setError(message: string): this;
+  setCost(usd: number): this;
+  setModel(name: string): this;
+  setTokens(prompt: number, completion: number): this;
+  setMetadata(meta: Record<string, unknown>): this;
+  /** Run `fn` with this span active, then end it (even if `fn` throws). */
+  run<T>(fn: (span: Span) => Promise<T> | T): Promise<T>;
+  /** Make this span ambient for the rest of the async context; end() unwinds. */
+  enter(): this;
+  end(): this;
+}
+
+export declare class Trace {
+  readonly traceId: string;
+  readonly name: string;
+  /** True when this trace continues one started by another agent/process. */
+  readonly isContinuation: boolean;
+  /** The agent that called us, when the inbound request named one. */
+  readonly callerAgent: string | null;
+  span(name: string, opts?: SpanOptions): Span;
+  run<T>(fn: (trace: Trace) => Promise<T> | T): Promise<T>;
+}
+
+export interface TracerOptions {
+  projectName: string;
+  flushIntervalMs?: number;
+  batchSize?: number;
+  /** The agent this process runs — visible in the fleet before any traffic. */
+  agentName?: string;
+  /** Liveness beat for every agent seen. 0 disables. Default 60000. */
+  heartbeatIntervalMs?: number;
+  heartbeatMetrics?: boolean;
+  /** Inject traceparent/baggage into outbound calls. Default true. */
+  propagate?: boolean;
+}
+
+export declare class CiphyrsTracer {
+  constructor(client: CiphyrsClient, opts: TracerOptions);
+  readonly knownAgents: string[];
+  /** Start a trace — or continue the caller's, when serving an instrumented request. */
+  trace(name: string, opts?: { traceId?: string; headers?: unknown }): Trace;
+  withTrace<T>(name: string, fn: (trace: Trace) => Promise<T> | T, opts?: { traceId?: string; headers?: unknown }): Promise<T>;
+  emitMetric(name: string, value: number, opts?: { unit?: string; tags?: Record<string, string>; agentName?: string }): void;
+  collectMetrics(): AgentProcessMetrics;
+  flush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+/** What an inbound request told us about the trace it belongs to. */
+export interface RemoteTraceContext {
+  trace_id: string;
+  span_id?: string;
+  agent_name?: string;
+  project?: string;
+  sampled: boolean;
+}
+
+export declare const TRACEPARENT: 'traceparent';
+export declare const BAGGAGE: 'baggage';
+
+/** Add traceparent/baggage for the active span. No-op outside a trace. */
+export declare function inject<H extends object>(headers?: H): H;
+/** Read the caller's context from inbound headers (object, Headers, entry array or CGI env). */
+export declare function extract(headers: unknown): RemoteTraceContext | undefined;
+/** Run `fn` as a continuation of the caller's trace. */
+export declare function withRemoteContext<T>(headersOrCtx: unknown, fn: () => T): T;
+export declare function currentContext(): RemoteTraceContext | undefined;
+export declare function instrumentFetch(): boolean;
+export declare function instrumentHttp(): boolean;
+export declare function autoInstrument(): { fetch: boolean; http: boolean };
+export declare function expressMiddleware(): (req: any, res: any, next: () => void) => unknown;
+export declare function fastifyPlugin(app: any): Promise<void>;
+export declare function withPropagation<H extends (req: any, res: any) => any>(handler: H): H;
+export declare function w3cTraceId(traceId: string): string;
+export declare function w3cSpanId(spanId: string): string;
+/** The active trace/span ids — what a guard call attributes itself to. */
+export declare function activeIds(): { trace_id?: string; span_id?: string };
+/**
+ * The kind of the innermost LOCAL span, or undefined when none is open.
+ * A remote parent has no kind (it does not travel in baggage) and a trace is
+ * not a span, so both answer undefined. protectTool uses this to tell whether
+ * the span it is inside is the tool span it may name to the gateway.
+ */
+export declare function activeSpanKind(): 'agent' | 'tool' | 'llm' | 'retriever' | string | undefined;
+export declare function activeAgent(): string | undefined;
+export declare function remoteParent(): RemoteTraceContext | undefined;
+
+// ── V60 Tool-call authorization ──────────────────────────────────────────
+
+export declare class ToolBlocked extends Error {
+  action: string;
+  reason: string;
+  ruleId?: string;
+  ruleName?: string;
+  decisionId?: string;
+  constructor(action: string, reason: string, opts?: { ruleId?: string; ruleName?: string; decisionId?: string });
+}
+export declare class ToolApprovalTimeout extends ToolBlocked {}
+
+export interface ProtectToolOptions extends FailPostureOptions {
+  /** Agent name rules are scoped to. Required. */
+  agent: string;
+  /** Tool name reported to Ciphyrs (default: the function's name). */
+  name?: string;
+  /** Shown in the tool inventory / allowlist UI. */
+  description?: string;
+  /** Approval poll interval in ms (default 1000). */
+  pollIntervalMs?: number;
+  /** Hard cap on approval polling; defaults to whatever the rule says. */
+  maxPollSeconds?: number;
+  /**
+   * Legacy spelling of `failOpen`, inverted, honoured in BOTH directions:
+   * `failClosed: false` still means fail open. Prefer `failOpen`.
+   *
+   * protectTool is the ONLY surface that reads this key — it is the only one
+   * it ever shipped on. On `guard.wrap`, `scan.protect` and the client
+   * constructor it is inert, as it has always been; use `failOpen` there.
+   *
+   * `null` means unset, i.e. the same as omitting it. It used to mean fail
+   * OPEN, because `!null` is true — so a posture nobody had set ran the tool
+   * during an outage.
+   * @deprecated
+   */
+  failClosed?: boolean | null;
+}
+
+/**
+ * Gate an async tool behind Ciphyrs tool-call authorization.
+ *
+ * FAILS CLOSED by default: if Ciphyrs cannot be reached the tool is NOT run
+ * and ToolBlocked is thrown. This changed — protectTool used to fail open —
+ * because this is the path that authorises tool execution. Opt back out with
+ * `{ failOpen: true }` here or `new CiphyrsClient({ failOpen: true })`.
+ *
+ * Sends the active `trace_id` on every gate call. The `span_id` is sent ONLY
+ * when the enclosing span is a TOOL span (`span(name, { kind: 'tool' })`) —
+ * i.e. when the id names the span this tool call will actually export.
+ * protectTool emits no span of its own, so inside an agent span, an llm span,
+ * a propagated remote context, or no span at all, the span id is omitted.
+ *
+ * That is deliberate and it is not merely caution: the gateway matches a tool
+ * span to its gate call by span id, and reads ANY producer-supplied id as
+ * proof that this agent's spans CAN be matched exactly. Sending the id of a
+ * span that is not the tool span leaves the exact match impossible while
+ * moving the agent from "not correlated, do not judge" into judgement on an
+ * unvalidated name/time fallback. Open a tool-kind span around the call if you
+ * want exact correlation.
+ */
+export declare function protectTool<F extends (...args: any[]) => Promise<any>>(
+  client: CiphyrsClient,
+  opts: ProtectToolOptions,
+  fn: F,
+): F;