Clinical AI agents, where PHI never leaves your cloud.

# core client — pulls in NO cloud SDK
npm install @kartha-health/client

# add exactly one cloud signer SDK (optional peer deps):
npm install @aws-sdk/client-kms                    # AWS   → signer { type: "kms" }
npm install @google-cloud/kms                       # GCP   → signer { type: "gcp-kms" }
npm install @azure/keyvault-keys @azure/identity    # Azure → signer { type: "azure-kv" }
# the local dev signer needs nothing extra

# runtime + server + telemetry
npm install @kartha-health/agent @kartha-health/agent-server
npm install @kartha-health/otel @opentelemetry/api  # optional

import {
  signMcpJwt, JwtAuth, KarthaClient,
  GuardrailExecutor, READ_ONLY_TOOLS,
  DOC_TYPE_CODES, mapDocTypes, observationDigest,
  computeWindow, resolveEncounter, toFhirDate,
  SmartAuthClient, SmartSession,
} from "@kartha-health/client";

// optional: eagerly register a cloud signer (side-effect subpath)
import "@kartha-health/client/aws";   // registers "kms"
import "@kartha-health/client/gcp";   // registers "gcp-kms"
import "@kartha-health/client/azure"; // registers "azure-kv"

import { serve } from "@hono/node-server";
import { Runtime, SkillRegistry, EntitlementGate, AnthropicProvider } from "@kartha-health/agent";
import { JwtAuth } from "@kartha-health/client";
import { KarthaAgentServer } from "@kartha-health/agent-server";

const skills = new SkillRegistry();

// Layer-1 auth: mints a short-lived ES256 MCP-JWT per tenant, KMS-signed.
const mcpAuth = new JwtAuth({
  iss: "cust_bcm",
  signerFor: (tenantId) => ({
    sub: "clinician_42",
    signer: { type: "kms", kmsKeyId: process.env.KMS_KEY_ID!, kid: "bcm-2026" },
  }),
});

const runtime = new Runtime({
  mcpUrl: process.env.KARTHA_MCP_URL!,          // https://<alb-host>/mcp
  auth: mcpAuth,
  tenantId: "t_bcm",
  llm: new AnthropicProvider(),                  // reads ANTHROPIC_API_KEY
  skills,
  entitlement: EntitlementGate.fromGrant(["sepsis-qsofa"]),
  cache: true,                                   // prompt caching on
});

// Layer-2 auth: the caller↔server app bearer.
const server = new KarthaAgentServer({
  runtime, skills,
  auth: { tokens: [process.env.APP_AUTH_TOKEN!] },
});

serve({ fetch: server.fetch, port: 8850 });

# 1 · register an agent (returns { id, version })
curl -sX POST localhost:8850/v1/agents \
  -H "Authorization: Bearer $APP_KEY" -H "Content-Type: application/json" \
  --data @discharge-agent.json

# 2 · open a session bound to a patient
curl -sX POST localhost:8850/v1/sessions \
  -H "Authorization: Bearer $APP_KEY" -H "Content-Type: application/json" \
  -d '{"agentId":"discharge-summary-agent","patientId":"patient-07","skillId":"discharge-summaries"}'

# 3 · send a message and read the turn's SSE inline
curl -N -X POST "localhost:8850/v1/sessions/$SID/events?stream=true" \
  -H "Authorization: Bearer $APP_KEY" -H "Content-Type: application/json" \
  -d '{"type":"user_message","content":"Draft the discharge summary for this admission."}'

import { signMcpJwt } from "@kartha-health/client";

const claims = { iss: "cust_bcm", sub: "clinician_42", aud: "kartha-health", tenantId: "t_bcm", ttlSeconds: 300 };

// AWS KMS — IAM role needs only kms:Sign on an ECC_NIST_P256 key
const jwt = await signMcpJwt(claims, {
  type: "kms", kmsKeyId: "arn:aws:kms:us-east-1:123456789012:key/abc-123", kid: "bcm-2026", region: "us-east-1",
});

// GCP Cloud KMS — full key-version resource name, EC_SIGN_P256_SHA256
await signMcpJwt(claims, {
  type: "gcp-kms",
  keyName: "projects/p/locations/us/keyRings/kartha/cryptoKeys/mcp-jwt/cryptoKeyVersions/1",
  kid: "bcm-2026",
});

// Azure Key Vault — the key identifier URL
await signMcpJwt(claims, {
  type: "azure-kv", keyId: "https://myvault.vault.azure.net/keys/mcp-jwt/<version>", kid: "bcm-2026",
});

// Local PKCS8 P-256 PEM — dev and tests only
await signMcpJwt(claims, { type: "local", pem: devPem, kid: "dev-1" });

import { JwtAuth } from "@kartha-health/client";

const auth = new JwtAuth({
  iss: "cust_bcm",
  aud: "kartha-health",     // default
  ttlSeconds: 300,          // default
  remintSkewSeconds: 60,    // default — re-mint this early
  signerFor: (tenantId) => ({
    sub: "clinician_42",
    signer: { type: "kms", kmsKeyId: "arn:aws:kms:…", kid: "bcm-2026" },
  }),
});

import { SmartAuthClient, SmartSession, KarthaClient } from "@kartha-health/client";

const smart = new SmartAuthClient({ /* issuer, clientId, redirectUri, scopes? */ });
await smart.discover();                                  // /.well-known/smart-configuration
const { url, state, codeVerifier } = smart.authorizationRequest();
// … redirect the user, then on callback:
const tokens = await smart.exchangeCode({ code, codeVerifier });

const session = new SmartSession(tokens, { onTokens: persist }); // auto-refresh, 60s buffer
const client = new KarthaClient({
  url: process.env.KARTHA_MCP_URL!,
  auth: mcpAuth,                                         // Layer-1 MCP-JWT
  tenantId: "t_epic_passthrough",
  emrAccessToken: () => session.getAccessToken(),        // Layer-2 → X-EMR-Access-Token
});

const client = new KarthaClient({ url, auth, tenantId: "t_bcm" });

await client.connect();                    // MCP initialize + notifications/initialized; fails loud on 401
const tools = await client.listTools();    // ToolDef[]  { name, description?, inputSchema }
const aTools = await client.anthropicTools();// AnthropicToolDef[] { name, description?, input_schema }
const res = await client.callTool("fhir_search", {
  resourceType: "Observation", queryParams: "patient=p-123&category=laboratory",
});                                         // ToolResult { text, isError }
await client.close();                       // best-effort DELETE teardown

import { GuardrailExecutor } from "@kartha-health/client";

const guarded = new GuardrailExecutor(client, {
  patientId: "p-123",
  encounterId: "enc-2026-0114",
  docTypeCodes: ["11506-3", "18842-5"],     // progress + discharge notes
  ragQueries: ["oxygen requirement", "discharge barriers"],
  notesMinScore: 0.35,
});

const { result, adjustments } = await guarded.execute("fhir_search", {
  resourceType: "Observation",
  queryParams: "subject=p-999&date=ge2026-01-01",   // subject stripped, patient forced, le injected
});
// adjustments → ["patient-scope: forced patient", "temporal: bounded le injected (…)", "digest: observations summarized"]

Hemoglobin A1c: 4× · latest 7.2 % @ 2026-05-01 · ref 4 %–5.6 % · ⚠ 3 abnormal
Systolic blood pressure: 6× · latest 148 mm[Hg] @ 2026-05-05 · ref 90–130 · ⚠ 4 abnormal
Creatinine: 3× · latest 1.0 mg/dL @ 2026-06-22 · ref 0.6–1.2

import { computeWindow, resolveEncounter, toFhirDate } from "@kartha-health/client";

computeWindow({ lookbackDays: 90 });
// → { ge: "2026-04-16", le: "2026-07-15", days: 90, encounterResolved: true }

resolveEncounter({ encounterPeriod: { start: "2026-07-01" }, encounterMaxDays: 30 });
// caps an open encounter at start + 30d; no period → [now − 14d, now], encounterResolved: false

{ "resourceType": "DocumentReference", "id": "doc-42", "outputFormat": "full" }

type InboundEvent =
  | { type: "user_message"; content: string }
  | { type: "interrupt" }
  | { type: "tool_permission_response"; requestId: string; decision: "allow" | "deny" };

event: session.created
id: b7e4c2a9-…:1
data: {"id":"b7e4c2a9-…:1","seq":1,"sessionId":"b7e4c2a9-…","type":"session.created","agentId":"discharge-summary-agent","agentVersion":2}

event: skill.selected
id: b7e4c2a9-…:2
data: {"…":"…","type":"skill.selected","skillId":"discharge-summaries","via":"explicit"}

event: turn.started
id: b7e4c2a9-…:3
data: {"…":"…","type":"turn.started","turnId":"6c1f9a02-…"}

event: tool.start
id: b7e4c2a9-…:5
data: {"…":"…","type":"tool.start","toolId":"toolu_01XkQ2","tool":"fhir_search","args":{"resourceType":"MedicationRequest","patient":"patient-07"}}

event: tool.result
id: b7e4c2a9-…:6
data: {"…":"…","type":"tool.result","toolId":"toolu_01XkQ2","tool":"fhir_search","tokens":412,"ms":238,"response":"{…Bundle…}","adjustments":["patient-scope: forced patient","temporal: bounded le injected"]}

event: text.delta
id: b7e4c2a9-…:8
data: {"…":"…","type":"text.delta","text":"## Discharge Summary\n\nMs. …"}

event: message.completed
id: b7e4c2a9-…:9
data: {"…":"…","type":"message.completed","content":"## Discharge Summary …"}

event: turn.completed
id: b7e4c2a9-…:10
data: {"…":"…","type":"turn.completed","turnId":"6c1f9a02-…","trace":{ /* TurnTrace */ }}

event: heartbeat
data: 

name: "Care Coordination"
model: { id: claude-sonnet-4-6, speed: standard }
description: >
  Coordinates transitions and follow-up: discharge planning,
  referrals, care-gap closure, transition-of-care summaries.
system: |
  You are a clinical AI agent for care coordination and transitions.

  ## What the runtime enforces (not you)
  The Kartha SDK guardrail layer — not this prompt — guarantees the
  patient-scope floor, both-ended temporal bounds, read-only by default,
  server-side FHIR summarization, and notes_load-before-notes_search.

  ## Grounding
  Cite every clinical claim to a retrieved resource id or a note docId.
  Never fabricate a value; re-read a record with outputFormat="full".
mcp_servers:
  - { name: kartha, type: url, url: "${KARTHA_MCP_URL}" }
skills:
  - { skill_id: discharge-planning, version: latest }
  - { skill_id: referrals, version: latest }
  - { skill_id: care-gaps, version: latest }
kartha:
  retrieval: { encounterMaxDays: 30, defaultMedLookbackDays: 90 }
  guardrails: { readOnly: true, patientScopeFloor: true, dateBounded: true }

{"type":"score","title":"…","value":7,"max":9,"band":"High risk","tone":"critical|warning|good|info","subtitle":"…","source":"…"}
{"type":"factors","title":"…","rows":[{"label":"…","points":2}]}
{"type":"trend","title":"…","unit":"…","points":[{"label":"2026-01","value":150}],"goal":130,"note":"…"}
{"type":"table","title":"…","columns":["…"],"rows":[["…"]]}
{"type":"checklist","title":"…","items":[{"label":"…","status":"done|pending|blocked|na","note":"…"}]}
{"type":"callout","tone":"warning","title":"…","body":"…"}
{"type":"sources","refs":[{"resource":"Condition/<id>","label":"…"}]}

// —— AgentConfig ————————————————————————————————————————————————
type LlmProviderName = "bedrock" | "vertex" | "foundry" | "anthropic";

interface AgentConfig {
  name: string;                 // REQUIRED
  model: { id: string; speed?: "standard" | "fast" };  // REQUIRED (model.id)
  description?: string;
  system: string;               // REQUIRED
  mcp_servers?: { name: string; type: "url"; url: string }[];
  tools?: { type: "mcp_toolset"; mcp_server_name: string; allow: string[] }[];
  skills?: { skill_id: string; version?: "latest" | number }[];
  kartha?: {
    llm?: { provider?: LlmProviderName };
    retrieval?: { encounterMaxDays?: number; defaultMedLookbackDays?: number; notesMinScore?: number };
    guardrails?: { readOnly?: boolean; patientScopeFloor?: boolean; dateBounded?: boolean };
    maxTurns?: number;          // default 8
  };
}

// —— TurnTrace / RunTrace (token meter + cost) ——————————————————————
interface TraceToolCall { tool: string; ms: number; tokens: number; isError: boolean; local?: boolean }

interface TurnTrace {
  turnIndex: number; model: string;
  systemPromptTokens: number;
  inputTokens: number; outputTokens: number;
  cacheReadTokens: number; cacheWriteTokens: number;
  costUsd: number;
  toolCalls: TraceToolCall[];
  iterations: {
    iteration: number; inputTokens: number; outputTokens: number;
    cacheReadTokens: number; cacheWriteTokens: number;
    costUsd: number; modelMs: number; toolCalls: TraceToolCall[];
  }[];
}

interface RunTrace {
  sessionId: string; agentId: string; agentVersion: number;
  skillId?: string; model: string; turns: TurnTrace[];
  fullChartBaselineTokens: number;  // token-meter framing (presentation estimate)
  selectiveTokens: number;          // chart-retrieval tokens only
  actualTokens: number;             // input+output across turns
  totalCostUsd: number;
  graceFlags: string[];             // e.g. "premium (grace): sepsis-qsofa"
}

// —— SkillDef ————————————————————————————————————————————————————
interface SkillDef {
  skill_id: string; name: string; description: string;
  license: "kartha-premium" | "customer"; version: number;
  ragQueries?: string[]; docTypes?: string[];
  body: string;
  references?: { name: string; content: string }[];
}

import { KarthaOtelTelemetry } from "@kartha-health/otel";

const runtime = new Runtime({
  // …
  telemetry: new KarthaOtelTelemetry({
    tracerName: "kartha-health",   // default
    captureContent: false,         // default — no prompt/completion content
  }),
});

# zero-credential demo: fixture MCP + offline provider + Explorer at :8850
pnpm demo

# run one agent headless
pnpm --filter @kartha-health/accelerators run-agent \
  --agent clinical-decision-support --patient patient02-clinical-decision-support-sepsis-qsofa \
  --skill sepsis-qsofa --prompt "Screen this patient for sepsis."

# skill factory + lint
pnpm new:skill --agent lab-diagnostics --id lactate-clearance --name "Lactate Clearance"
pnpm skills:lint

pnpm --filter @kartha-health/accelerators extract-batch \
  --rubric medication-extraction --patient p-ava \
  [--date-range ge2026-01-01] [--doc-type 11506-3] [--encounter enc-9] \
  [--summary] [--out records.json] [--model claude-sonnet-4-6] [--concurrency 4]

{
  patientId, rubric, model,
  records: [{ docId, fields: { [field]: { value, quote, section? } | null } }],
  docs: [{ docId, status: "ok"|"invalid-json"|"llm-error"|"no-content", entities, rejected, reason? }],
  receipt: { docsInScope, docsExtracted, entities, rejectedEntities, failedDocs },
  summary?: string,
  usage: { inputTokens, outputTokens }
}