@ciphyrshq/sdk 2.6.0 → 3.0.1

package/README.md

@@ -189,6 +189,137 @@ Full type definitions included via `types.d.ts`. Import types directly:
 import type { MaskResult, RestoreResult, CiphyrsClientOptions } from '@ciphyrshq/sdk'
 ```
 
+## Monitoring agents you already deployed (2.7)
+
+An agent running on your own infrastructure — Oracle, AWS, Azure, GCP, on-prem
+— needs nothing from us but outbound HTTPS and an API key. Two things used to
+require code you had to remember to write; both are now automatic.
+
+### Agents in separate processes appear as one connected system
+
+The topology graph is *derived*: an edge A → B exists because a span of agent B
+names a span of agent A as its parent. Inside one process the SDK tracks that
+for you. Across processes it used to need hand-threaded headers, and without
+them two agents that talked constantly rendered as two disconnected dots.
+
+Outbound calls made inside a span now carry W3C `traceparent` and `baggage`
+automatically (`fetch`, and `node:http`/`node:https`, which covers axios,
+node-fetch, got and superagent):
+
+```js
+import { CiphyrsClient, CiphyrsTracer } from '@ciphyrshq/sdk';
+
+const client = new CiphyrsClient({ apiKey: process.env.CIPHYRS_API_KEY });
+const tracer = new CiphyrsTracer(client, { projectName: 'orders', agentName: 'RouterAgent' });
+
+const t = tracer.trace('handle order');
+await t.span('RouterAgent', { agentName: 'RouterAgent' }).run(async () => {
+  // headers are added for you — no options to pass
+  await fetch('https://billing.internal/charge', { method: 'POST', body });
+});
+```
+
+On the receiving side, one line activates the caller's trace for the request:
+
+```js
+import express from 'express';
+import { expressMiddleware } from '@ciphyrshq/sdk';
+
+const app = express();
+app.use(expressMiddleware());          // Fastify: await app.register(fastifyPlugin)
+
+app.post('/charge', async (req, res) => {
+  const t = tracer.trace('charge');    // continues the caller's trace
+  await t.span('BillingAgent', { agentName: 'BillingAgent' }).run(async () => { /* ... */ });
+  res.json({ ok: true });
+});
+```
+
+That is all the edge needs. `t.isContinuation` is true, `t.callerAgent` names
+who called, and the first span is parented to the caller's span.
+
+Queues, gRPC, or a framework not listed — two functions:
+
+```js
+import { inject, withRemoteContext } from '@ciphyrshq/sdk';
+
+await queue.send({ body, headers: inject({}) });                   // producer
+await withRemoteContext(msg.headers, async () => { /* ... */ });   // consumer
+```
+
+Peers instrumented with plain OpenTelemetry interoperate: ids are generated in
+W3C shape (32/16 hex), so a non-Ciphyrs service joins the same trace.
+
+Set `propagate: false` on the tracer to opt out. Calls to the Ciphyrs API
+itself are never decorated.
+
+### Spans nest without bookkeeping
+
+A span created while another is open is its child, so the graph has edges even
+inside one process:
+
+```js
+const t = tracer.trace('run');
+const outer = t.span('Router', { agentName: 'Router' });
+const inner = t.span('Billing', { agentName: 'Billing' });   // child of Router
+inner.end();
+outer.end();
+```
+
+`span.run(fn)` is the scoped form and is what to prefer — it ends the span even
+if `fn` throws, and records the error on it. Pass an explicit `parentSpanId` to
+override, or `{ scoped: true }` to opt out of ambient context entirely.
+
+### Health is reported, and can be observed
+
+Heartbeats are on by default and carry the interval they beat at, so the
+platform sizes each agent's "down" window to that agent rather than applying
+one global threshold to a fleet whose agents beat at very different rates. They
+also ship process metrics (RSS, heap, event-loop lag, CPU, error rate), so the
+fleet can show **degraded** before **down**:
+
+```js
+const tracer = new CiphyrsTracer(client, {
+  projectName: 'orders',
+  agentName: 'RouterAgent',      // visible in the fleet before any traffic
+  heartbeatIntervalMs: 60_000,   // 0 disables
+  heartbeatMetrics: true,
+});
+```
+
+For a real readiness signal, run a probe each tick:
+
+```js
+client.startHealthMonitor({
+  agentName: 'RouterAgent',
+  probe: async () => {
+    const t0 = Date.now();
+    await db.ping();
+    return { status: 'up', latencyMs: Date.now() - t0 };
+  },
+});
+```
+
+And to make `down` something Ciphyrs *observed* rather than inferred from
+silence, register a URL the platform polls:
+
+```js
+await client.setAgentMonitoring(agentId, {
+  probeUrl: 'https://agent.example.com/healthz',
+  heartbeatTimeoutS: 120,
+});
+```
+
+Private, loopback and cloud-metadata addresses are refused by the prober and
+surface as `probe_status: 'blocked'` — a misconfiguration, never an outage.
+
+### If you cannot propagate headers
+
+The platform also infers edges from shared traces, correlation ids and shared
+sessions. Those render dashed with a confidence score, and an operator can
+confirm or dismiss them. A real propagated edge always wins over an inferred
+one, so wiring up the middleware above upgrades them automatically.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciphyrshq/sdk",
-  "version": "2.6.0",
+  "version": "3.0.1",
   "description": "Official JavaScript / TypeScript SDK for the Ciphyrs PII Shield API",
   "type": "module",
   "main": "./src/index.js",
@@ -11,20 +11,38 @@
       "types": "./types.d.ts"
     },
     "./tracer": "./src/tracer.js",
+    "./propagation": "./src/propagation.js",
+    "./context": "./src/context.js",
     "./secret-detector": "./src/secret-detector.js",
     "./eval-runner": "./src/eval-runner.js"
   },
-  "files": ["src", "types.d.ts"],
-  "keywords": ["pii", "privacy", "masking", "llm", "ciphyrs", "gdpr", "dpdp", "sdk"],
+  "files": [
+    "src",
+    "!src/*.test.js",
+    "!src/*.test-helper.js",
+    "types.d.ts"
+  ],
+  "keywords": [
+    "pii",
+    "privacy",
+    "masking",
+    "llm",
+    "ciphyrs",
+    "gdpr",
+    "dpdp",
+    "sdk"
+  ],
   "license": "MIT",
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/praveen190/Ciphyrs.git",
+    "url": "git+https://github.com/praveen190/Ciphyrs.git",
     "directory": "packages/sdk"
   },
   "homepage": "https://ciphyrs.com",
   "scripts": {
-    "test": "node --test src/**/*.test.js"
+    "test": "node --test src/*.test.js"
   }
 }

package/src/client.js

@@ -1,3 +1,5 @@
+import { registerInternalOrigin } from './propagation.js';
+import { resolveFailOpen } from './fail-posture.js';
 import {
   CiphyrsError,
   CiphyrsAuthError,
@@ -14,10 +16,50 @@ const DASH_BASE_URL    = 'https://www.ciphyrs.com';
 const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
 const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 500;
+// A server-supplied Retry-After bounds one sleep; without a cap a
+// "Retry-After: 3600" from a plan-limit response parked the agent's thread
+// for an hour. Same cap as the Python SDK.
+const MAX_RETRY_AFTER_MS = 60_000;
+
+// GUARD CALLS ARE DIFFERENT. /v1/guard/check and /v1/guard/tool-check are
+// synchronous decisions inside the agent's turn: the model is waiting, the
+// customer is waiting, and a tool the policy meant to refuse is not running
+// until the verdict lands. The general ladder — four attempts on the
+// caller's full timeout — was written for calls that may safely be slow;
+// applied to a verdict it turned a slow gateway into a request that hung
+// for minutes and died with no reply (BFSI demo, 25 Sep 2026, Python SDK —
+// this client had the same ladder). Guard paths get one quick retry, a
+// short per-attempt timeout and a wall-clock budget; the fail posture then
+// decides at once, as documented. Same numbers as ciphyrs 4.1.1 (Python).
+const GUARD_PATH = '/v1/guard/';
+const GUARD_MAX_RETRIES = 1;
+const GUARD_ATTEMPT_TIMEOUT_MS = 6_000;
+const GUARD_TOTAL_BUDGET_MS = 10_000;
+
+function isGuardUrl(url) {
+  try { return new URL(String(url)).pathname.startsWith(GUARD_PATH); }
+  catch { return String(url).includes(GUARD_PATH); }
+}
+
+// A 5xx whose body already carries the gateway's final verdict (fail_open or
+// fail_closed) is an answer, not an outage: retrying it asks the same
+// question again and gets the same deliberate answer, three times, with
+// backoff. The Python SDK stopped doing that on 13 Sep 2026; this one had
+// not.
+function carriesFinalVerdict(data) {
+  return !!data && typeof data === 'object' && (data.fail_open === true || data.fail_closed === true);
+}
 
 // ── Internal HTTP helper with auto-retry ────────────────────────────────────────
 async function request(url, { method = 'GET', headers = {}, body, timeout = 10_000, maxRetries = MAX_RETRIES } = {}) {
   let lastErr;
+  const guard = isGuardUrl(url);
+  if (guard) {
+    maxRetries = Math.min(maxRetries, GUARD_MAX_RETRIES);
+    timeout = Math.min(timeout, GUARD_ATTEMPT_TIMEOUT_MS);
+  }
+  const started = Date.now();
+  const budgetLeft = () => !guard || (Date.now() - started) < GUARD_TOTAL_BUDGET_MS;
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     let res;
@@ -27,15 +69,18 @@ async function request(url, { method = 'GET', headers = {}, body, timeout = 10_0
         signal:  AbortSignal.timeout(timeout),
         headers: { 'Content-Type': 'application/json', ...headers },
         body:    body !== undefined ? JSON.stringify(body) : undefined,
+        // Telemetry the SDK sends is not the agent doing work: the
+        // propagation patch must not decorate it with trace headers.
+        ciphyrsInternal: true,
       });
     } catch (err) {
       if (err.name === 'TimeoutError' || err.name === 'AbortError') {
         lastErr = new CiphyrsTimeoutError();
-        if (attempt < maxRetries) { await sleep(backoff(attempt)); continue; }
+        if (attempt < maxRetries && budgetLeft()) { await sleep(backoff(attempt)); continue; }
         throw lastErr;
       }
       lastErr = new CiphyrsError(err.message);
-      if (attempt < maxRetries) { await sleep(backoff(attempt)); continue; }
+      if (attempt < maxRetries && budgetLeft()) { await sleep(backoff(attempt)); continue; }
       throw lastErr;
     }
 
@@ -44,13 +89,18 @@ async function request(url, { method = 'GET', headers = {}, body, timeout = 10_0
     if (!res.ok) {
       const msg = data?.error || `Request failed (${res.status})`;
 
-      // Retry on transient errors
-      if (RETRYABLE_STATUSES.has(res.status) && attempt < maxRetries) {
+      // Retry on transient errors — unless the body is already the verdict.
+      if (RETRYABLE_STATUSES.has(res.status) && attempt < maxRetries && !carriesFinalVerdict(data) && budgetLeft()) {
         const retryAfter = res.headers.get('retry-after');
-        const delay = retryAfter ? parseInt(retryAfter) * 1000 : backoff(attempt);
+        const parsed = retryAfter ? parseInt(retryAfter, 10) * 1000 : NaN;
+        const delay = Number.isFinite(parsed) && parsed >= 0 ? Math.min(parsed, MAX_RETRY_AFTER_MS) : backoff(attempt);
         await sleep(delay);
         continue;
       }
+      // A 5xx that carries the gateway's fail-posture decision is returned
+      // as data, the way a 200 verdict is: the caller's guard/protectTool
+      // code reads fail_open / fail_closed and acts on it.
+      if (carriesFinalVerdict(data)) return data;
 
       if (res.status === 401) throw new CiphyrsAuthError(msg);
       if (res.status === 403) throw new CiphyrsPermissionError(msg);
@@ -78,12 +128,13 @@ function sleep(ms) {
 // Used by: developers integrating Ciphyrs into their LLM pipelines
 // ─────────────────────────────────────────────────────────────────────────────
 class ScanResource {
-  #headers; #base; #timeout;
+  #headers; #base; #timeout; #failOpen;
 
-  constructor(headers, base, timeout) {
+  constructor(headers, base, timeout, failOpen = false) {
     this.#headers = headers;
     this.#base    = base;
     this.#timeout = timeout;
+    this.#failOpen = failOpen;
   }
 
   /**
@@ -192,6 +243,18 @@ class ScanResource {
    *                                       Defaults to true (data minimisation);
    *                                       set false to keep the session alive
    *                                       for follow-up turns in a conversation.
+   * @param {boolean} [opts.failOpen]    — What to do when the masker is
+   *                                       unreachable. DEFAULT FALSE: the call
+   *                                       throws and your LLM is never given
+   *                                       the raw text. `true` sends the RAW,
+   *                                       UNMASKED input to your LLM and
+   *                                       returns it unrestored with
+   *                                       `failedOpen: true` — real PII
+   *                                       egress, so only opt in knowingly.
+   *                                       Falls back to the client-wide
+   *                                       `failOpen`. Same switch, same
+   *                                       precedence, as guard.wrap and
+   *                                       protectTool.
    * @returns {Promise<{
    *   output: string,            // Unmasked LLM response (return THIS to the user)
    *   maskedInput: string,       // What the LLM actually saw (audit)
@@ -221,10 +284,41 @@ class ScanResource {
     if (typeof llmCall !== 'function') {
       throw new TypeError('protect: llmCall must be an async function (masked, ctx) => Promise<string>');
     }
-    const { purge = true, ...maskOpts } = opts;
-
-    // 1. Mask
-    const m = await this.mask(userInput, maskOpts);
+    // `failClosed` is destructured out but NOT resolved. It has never done
+    // anything on this surface: before the shared posture it landed in
+    // maskOpts and mask() whitelists its fields, so it went nowhere. Feeding
+    // it to the resolver here would turn a key copy-pasted from a protectTool
+    // call site into a live switch, and on THIS surface `{ failClosed: false }`
+    // means sending the customer's unmasked text to their model. It stays
+    // inert, and it stays out of maskOpts so it never reaches the wire either.
+    const { purge = true, failOpen, failClosed: _legacyIgnoredHere, ...maskOpts } = opts;
+    const runOnOutage = resolveFailOpen({ failOpen }, this.#failOpen);
+
+    // 1. Mask. An outage here is the same fork protectTool and guard.wrap
+    //    face, and it is answered with the same option: fail closed (the
+    //    default) means the LLM is never handed the raw text.
+    let m;
+    try {
+      m = await this.mask(userInput, maskOpts);
+    } catch (err) {
+      if (!runOnOutage) throw err;
+      // Explicitly asked for. Loud, because this is the one fail-open path in
+      // the SDK whose cost is data leaving the customer's boundary unmasked,
+      // and a silent return here reads identically to a successful mask.
+      console.warn(
+        `[ciphyrs] scan.protect failed OPEN (failOpen: true): ${err.message}. ` +
+        'Sending UNMASKED input to your LLM.'
+      );
+      const output = await llmCall(userInput, { sessionId: null, entitiesFound: [] });
+      if (typeof output !== 'string') {
+        throw new TypeError('protect: llmCall must return a string (the LLM response). Got ' + typeof output + '.');
+      }
+      return {
+        output, maskedInput: userInput, maskedOutput: output,
+        sessionId: null, entitiesFound: [], tokensRestored: 0,
+        failedOpen: true,
+      };
+    }
 
     // 2. Call the customer's LLM with the masked text
     let llmResponse;
@@ -267,9 +361,10 @@ class ScanResource {
 // their LLM calls with check() and it returns allow / block / review in
 // <50ms. The whole V58 pitch lives here.
 class GuardResource {
-  #headers; #base; #timeout;
-  constructor(headers, base, timeout) {
+  #headers; #base; #timeout; #failOpen;
+  constructor(headers, base, timeout, failOpen = false) {
     this.#headers = headers; this.#base = base; this.#timeout = timeout;
+    this.#failOpen = failOpen;
   }
 
   /**
@@ -318,6 +413,12 @@ class GuardResource {
    * One-shot wrapper: check input, if allowed call your LLM, then check
    * output, then return. Matches the protect() pattern but for blocking.
    *
+   * Failure posture: fail CLOSED by default — if the guard cannot be reached
+   * the error propagates and your LLM is not called. `{ failOpen: true }`, or
+   * a client built with `failOpen: true`, proceeds instead and marks the
+   * result `failedOpen: true`. Same switch and same precedence as
+   * scan.protect and protectTool.
+   *
    * @example
    *   const result = await client.guard.wrap(userMessage, async (input) => {
    *     return await openai.chat.completions.create({...}).choices[0].message.content;
@@ -329,8 +430,29 @@ class GuardResource {
     if (typeof llmCall !== 'function') {
       throw new TypeError('guard.wrap: llmCall must be a function');
     }
+    // `opts` is the caller's whole GuardCheckParams bag, and only `failOpen` is
+    // read out of it as a posture. guard.wrap has never honoured the legacy
+    // `failClosed` — check() whitelists its fields, so the key was inert here —
+    // and starting to honour it would let `{ failClosed: false }`, copy-pasted
+    // from a protectTool call site, quietly disable fail-closed on a surface
+    // where it never did before.
+    const runOnOutage = resolveFailOpen({ failOpen: opts?.failOpen }, this.#failOpen);
+    // An unreachable guard is not a verdict. Fail-closed rethrows what the
+    // transport said, which is what this path has always done; fail-open
+    // substitutes a synthetic allow so the caller's flow continues, and says
+    // so in the result rather than dressing it up as a real decision.
+    const checkOrFailOpen = async (params) => {
+      try {
+        return await this.check(params);
+      } catch (err) {
+        if (!runOnOutage) throw err;
+        return { decision: 'allow', reason: `guard unreachable, failed open: ${err.message}`,
+          detections: [], decision_id: null, failedOpen: true };
+      }
+    };
+
     // 1. Pre-check input
-    const inGuard = await this.check({ ...opts, input: userInput });
+    const inGuard = await checkOrFailOpen({ ...opts, input: userInput });
     if (inGuard.decision === 'block') {
       return { blocked: true, reason: inGuard.reason, decision: inGuard.decision,
         detections: inGuard.detections, decision_id: inGuard.decision_id };
@@ -341,14 +463,17 @@ class GuardResource {
       throw new TypeError('guard.wrap: llmCall must return a string');
     }
     // 3. Post-check output
-    const outGuard = await this.check({ ...opts, input: userInput, output: llmResponse });
+    const outGuard = await checkOrFailOpen({ ...opts, input: userInput, output: llmResponse });
     if (outGuard.decision === 'block') {
       return { blocked: true, reason: outGuard.reason, decision: outGuard.decision,
         detections: outGuard.detections, decision_id: outGuard.decision_id,
         output: null };   // never leak the blocked output
     }
     return { blocked: false, output: llmResponse, decision: outGuard.decision,
-      detections: outGuard.detections, decision_id: outGuard.decision_id };
+      detections: outGuard.detections, decision_id: outGuard.decision_id,
+      // Only present when a check was skipped rather than answered, so a
+      // caller auditing "was this really checked?" can tell the two apart.
+      ...(inGuard.failedOpen || outGuard.failedOpen ? { failedOpen: true } : {}) };
   }
 
   async getPolicy() {
@@ -912,8 +1037,23 @@ export class CiphyrsClient {
    * @param {string}  [opts.baseUrl] — Override gateway URL (VPC / on-prem deployments)
    * @param {string}  [opts.dashUrl] — Override dashboard API URL
    * @param {number}  [opts.timeout] — Request timeout in ms (default: 10000)
+   * @param {boolean} [opts.failOpen=false]
+   *        Fleet-wide failure posture: what protectTool, guard.wrap and
+   *        scan.protect do when Ciphyrs cannot be reached.
+   *
+   *        DEFAULT FALSE — FAIL CLOSED. The work does not proceed: the tool is
+   *        not executed, the LLM is not called, and the error surfaces. This is
+   *        a CHANGE for protectTool, which used to fail open and run the tool
+   *        during an outage of ours while the other two refused to proceed; the
+   *        tool path is the one that moves money, so it now gets the safe
+   *        default too. Set `true` here (or `{ failOpen: true }` on any single
+   *        call) to restore the old behaviour everywhere. A protectTool caller
+   *        who already wrote `failClosed: false` keeps failing open unchanged —
+   *        but that legacy key is read on protectTool ONLY. It has never done
+   *        anything on this constructor, on guard.wrap or on scan.protect, and
+   *        it still does not: use `failOpen` on those.
    */
-  constructor({ apiKey, token, baseUrl = DEFAULT_BASE_URL, dashUrl = DASH_BASE_URL, timeout = 10_000 } = {}) {
+  constructor({ apiKey, token, baseUrl = DEFAULT_BASE_URL, dashUrl = DASH_BASE_URL, timeout = 10_000, failOpen } = {}) {
     if (!apiKey && !token) throw new Error('CiphyrsClient: provide apiKey (server-side) or token (dashboard)');
 
     const headers = {
@@ -927,16 +1067,147 @@ export class CiphyrsClient {
     this._headers = headers;
     /** @internal Default timeout */
     this._timeout = timeout;
-
-    this.scan     = new ScanResource(headers, this._baseUrl, timeout);
+    /** @internal Fleet-wide failure posture; protectTool reads this off the client.
+     *  `failOpen` only: the legacy `failClosed` never existed on the client, so
+     *  reading it here would not preserve anybody's behaviour — it would invent
+     *  a new way to turn fail-closed off for the whole fleet at once. It is
+     *  honoured on protectTool, the surface it shipped on, and nowhere else. */
+    this._failOpen = resolveFailOpen({ failOpen }, false);
+
+    this.scan     = new ScanResource(headers, this._baseUrl, timeout, this._failOpen);
     this.auth     = new AuthResource(headers, this._baseUrl, timeout);
     this.metrics  = new MetricsResource(headers, dashUrl.replace(/\/$/, ''), timeout);
     this.tenant   = new TenantResource(headers, dashUrl.replace(/\/$/, ''), timeout);
     this.trace    = new TraceResource(headers, this._baseUrl, timeout);
     // V54-V59 — security platform resources
-    this.guard    = new GuardResource(headers, this._baseUrl, timeout);
+    this.guard    = new GuardResource(headers, this._baseUrl, timeout, this._failOpen);
     this.security = new SecurityResource(headers, this._baseUrl, timeout);
     this.reports  = new ReportsResource(headers, this._baseUrl, timeout);
+
+    // So propagation never writes trace headers onto calls to our own API,
+    // including a customer's VPC/on-prem gateway URL.
+    registerInternalOrigin(this._baseUrl);
+    registerInternalOrigin(dashUrl);
+
+    /** @internal recurring health monitor state (startHealthMonitor) */
+    this._healthTimer = null;
+  }
+
+  // ── Agent health (V39 heartbeat, V143 windows + metrics) ─────────────────
+
+  /**
+   * Report one health check. Fire-and-forget by design: a flaky network must
+   * never take down the agent being monitored, so failures resolve to
+   * `{ ok: false }` and warn once rather than throwing.
+   *
+   * Reporting `heartbeatIntervalS` matters — the server sizes THIS agent's
+   * "down" window from it (2x + grace) instead of applying one global
+   * threshold to a fleet whose agents beat at very different rates. Shipping
+   * `metrics` lets the fleet show `degraded` before `down`.
+   *
+   * @param {object} args
+   * @param {string} [args.agentName]  — Resolve the agent by name (preferred)
+   * @param {string} [args.agentId]    — Or pass an explicit UUID
+   * @param {'up'|'degraded'|'failing'|'down'|'unknown'} [args.status='up']
+   * @param {string} [args.projectName] — Which project the agent belongs to
+   * @param {number} [args.latencyMs]
+   * @param {string} [args.errorMessage] — Expected when status !== 'up'
+   * @param {string} [args.environment]
+   * @param {number} [args.heartbeatIntervalS]
+   * @param {object} [args.metrics]
+   * @param {object} [args.metadata]
+   */
+  async reportHeartbeat({
+    agentName, agentId, status = 'up', projectName, latencyMs = null,
+    errorMessage = null, environment, heartbeatIntervalS, metrics, metadata = {},
+  } = {}) {
+    if (!agentName && !agentId) throw new Error('reportHeartbeat requires agentName or agentId');
+    try {
+      const res = await this._request(`${this._baseUrl}/v1/trace/agents/heartbeat`, {
+        method: 'POST',
+        body: {
+          agent_id: agentId || undefined,
+          agent_name: agentName || undefined,
+          project_name: projectName || undefined,
+          status,
+          latency_ms: latencyMs,
+          error_message: errorMessage,
+          environment: environment || undefined,
+          heartbeat_interval_s: heartbeatIntervalS,
+          metrics,
+          metadata,
+          source: 'sdk',
+        },
+      });
+      return { ok: true, ...res };
+    } catch (err) {
+      console.warn(`[ciphyrs] heartbeat failed for ${agentName || agentId}: ${err.message}`);
+      return { ok: false, error: err.message };
+    }
+  }
+
+  /**
+   * Start a recurring heartbeat. Runs `probe()` each tick when given: if it
+   * throws, the beat is sent as `down` with the message; if it returns
+   * `{ status, latencyMs }`, those win. Safe to call repeatedly — the previous
+   * monitor is cleared first. The timer is unref'd so it never holds the
+   * process open.
+   *
+   * @example
+   *   client.startHealthMonitor({
+   *     agentName: 'billing-agent',
+   *     probe: async () => { const t = Date.now(); await dbPing(); return { status: 'up', latencyMs: Date.now() - t }; },
+   *   });
+   */
+  startHealthMonitor({ agentName, agentId, projectName, intervalMs = 60_000, probe = null, environment } = {}) {
+    if (!agentName && !agentId) throw new Error('startHealthMonitor requires agentName or agentId');
+    this.stopHealthMonitor();
+    const intervalS = Math.round(intervalMs / 1000);
+    const tick = async () => {
+      let status = 'up', latencyMs = null, errorMessage = null;
+      if (probe) {
+        const t0 = Date.now();
+        try {
+          const r = await probe();
+          status = r?.status || 'up';
+          latencyMs = r?.latencyMs ?? (Date.now() - t0);
+        } catch (err) {
+          status = 'down';
+          latencyMs = Date.now() - t0;
+          errorMessage = err?.message || String(err);
+        }
+      }
+      await this.reportHeartbeat({
+        agentName, agentId, projectName, status, latencyMs, errorMessage,
+        environment, heartbeatIntervalS: intervalS,
+      });
+    };
+    tick().catch(() => {});
+    this._healthTimer = setInterval(() => { tick().catch(() => {}); }, intervalMs);
+    if (this._healthTimer.unref) this._healthTimer.unref();
+    return this._healthTimer;
+  }
+
+  /** Stop the recurring heartbeat started by startHealthMonitor(). */
+  stopHealthMonitor() {
+    if (this._healthTimer) { clearInterval(this._healthTimer); this._healthTimer = null; }
+  }
+
+  /**
+   * Set an agent's down window and/or a synthetic probe URL the platform
+   * polls, so `down` becomes something Ciphyrs observed rather than inferred
+   * from silence. Requires a dashboard token (owner/admin/developer).
+   *
+   * @param {string} agentId
+   * @param {{ heartbeatTimeoutS?: number|null, probeUrl?: string|null }} opts
+   */
+  async setAgentMonitoring(agentId, { heartbeatTimeoutS, probeUrl } = {}) {
+    const body = {};
+    if (heartbeatTimeoutS !== undefined) body.heartbeat_timeout_s = heartbeatTimeoutS;
+    if (probeUrl !== undefined) body.probe_url = probeUrl;
+    return this._request(`${this._baseUrl}/v1/trace/agents/${encodeURIComponent(agentId)}/monitoring`, {
+      method: 'PATCH', body,
+    });
   }
 
   /**
@@ -970,4 +1241,39 @@ export class CiphyrsClient {
 
   /** Shortcut for client.auth.createApiKey() */
   createKey(opts)               { return this.auth.createApiKey(opts); }
+
+  // ── V60: tool-call authorization (used by protectTool wrapper) ──────────
+  /** @internal Used by protectTool() — POST /v1/guard/tool-check
+   *
+   *  `span_id` is the field the gateway route destructures alongside
+   *  `trace_id`; it stores it on agent_tool_calls.span_id, which is the only
+   *  key trust.001 can use to match a gate call to the tool span it
+   *  authorised. Omitted when the wrapper has no span to name — see
+   *  protect-tool.js producerIds(). Never substituted with anything: the
+   *  gateway mints its own `gs_…` when this is absent, and the rule reads a
+   *  minted id as "this producer cannot be correlated". */
+  async _toolCheck({ agent_name, tool_name, args, trace_id, span_id, user_id }) {
+    return this._request(`${this._baseUrl}/v1/guard/tool-check`, {
+      method: 'POST',
+      body: { agent_name, tool_name, args, trace_id, span_id, user_id },
+    });
+  }
+
+  /** @internal Used by protectTool() — GET /v1/guard/approval/:id (poll) */
+  async _approvalStatus(approvalId) {
+    return this._request(`${this._baseUrl}/v1/guard/approval/${encodeURIComponent(approvalId)}`);
+  }
+
+  /** @internal Used by protectTool() — announce decorated tools at startup
+   *  so the inventory (and any default-deny allowlist) covers the full tool
+   *  surface before the first call ever happens. Best-effort. */
+  async _announceTools(agentName, tools) {
+    return this._request(`${this._baseUrl}/v1/agent-inventory/announce`, {
+      method: 'POST',
+      body: { agent_name: agentName, tools },
+    });
+  }
 }
+
+/** @internal exported for tests */
+export const _retryInternals = { isGuardUrl, carriesFinalVerdict, GUARD_MAX_RETRIES, GUARD_ATTEMPT_TIMEOUT_MS, GUARD_TOTAL_BUDGET_MS, MAX_RETRY_AFTER_MS, MAX_RETRIES, request };