@atbash/sdk 0.3.3 → 0.3.5

package/README.md

@@ -1,6 +1,6 @@
 # @atbash/sdk
 
-TypeScript SDK for the Atbash judge and risk-engine APIs. Evaluate agent actions against operator-defined policy before execution — programmatically, from any Node.js backend.
+TypeScript SDK for Atbash — the safety layer that evaluates AI agent actions against operator-defined policies before execution.
 
 ## Installation
 
@@ -8,16 +8,16 @@ TypeScript SDK for the Atbash judge and risk-engine APIs. Evaluate agent actions
 npm install @atbash/sdk
 ```
 
-Requires Node.js 18 or higher. Server-side only — private keys are used for local signing and must never be exposed to browsers.
+Requires Node.js 18+. Server-side only — private keys are used for local signing and must never be exposed to browsers.
 
 ## Quickstart
 
 ```ts
 import { loadAgent, judgeAction } from "@atbash/sdk";
 
-// 1. Load your agent identity — paste the private key from the Atbash
-//    dashboard (https://atbash.ai/risk-engine/agents). loadAgent()
-//    validates the key and derives the matching public key for you.
+// 1. Load your agent identity using the private key you saved during
+//    agent creation. loadAgent() validates the key and derives the
+//    matching public key for you.
 const agent = loadAgent(process.env.ATBASH_AGENT_PRIVKEY!);
 
 // 2. Submit an action for judgment, before executing it.
@@ -57,7 +57,11 @@ If you need finer control, you can call `logToolCall()` and the judge API separa
 
 ### Don't have an agent yet?
 
-Generate one programmatically for local development:
+There are two ways to create an agent:
+
+1. **Dashboard (recommended)** — create an agent at [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents). The dashboard generates the keypair, assigns the agent to your org, and lets you attach a policy pack — all in one step.
+
+2. **Programmatic** — generate a new keypair locally or bring an existing secp256k1 private key from another platform, then onboard it via the dashboard:
 
 ```ts
 import { generateKeyPair, loadAgent } from "@atbash/sdk";
@@ -67,7 +71,7 @@ console.log("Save this private key somewhere safe:", privKey);
 const agent = loadAgent(privKey);
 ```
 
-For production, always create agents in the dashboard so operators can attach policy packs and manage tier / jail state.
+> **Note:** After generating a key programmatically, you must still onboard the agent at [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) — assign it to an org and attach a policy pack before `judgeAction` will work.
 
 ### Secret storage
 
@@ -88,6 +92,8 @@ Every `judgeAction` call returns one of three verdicts:
 | `HOLD` | Requires operator review | Pause — poll `getJudgmentStatus` until resolved |
 | `BLOCK` | Violates a red line | Abort — agent is jailed in Enforcement tier |
 
+> **NB:** If your org is on the **Audit** tier, the judge returns `"No verdict"` — actions are logged on-chain for the audit trail but not evaluated by an AI provider. Upgrade to **Audit+** or **Enforcement** at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) for active verdicts.
+
 ## API
 
 ### Judge
@@ -122,8 +128,8 @@ interface JudgeOptions {
 }
 
 interface ChainOpts {
-  nodeUrls?: string[];        // Chromia node URLs (defaults to testnet)
-  blockchainRid?: string;     // Blockchain RID (defaults to testnet)
+  nodeUrls?: string[];        // Chromia node URLs (uses the default  nodeurls)
+  blockchainRid?: string;     // Blockchain RID (uses the default chromia rid)
 }
 
 interface JudgeResult {
@@ -147,10 +153,10 @@ logToolCall(
   auth: AgentAuth,
   chainOpts?: ChainOpts,
   extra?: { toolName?: string; toolArgsJson?: string },
-): Promise<string>
+): Promise<LogToolCallResult>
 ```
 
-Sign and broadcast `log_tool_call` to the Chromia chain. Returns the `tool_call_id`. Use this if you need to separate the on-chain logging step from the verdict request.
+Sign `log_tool_call` on the Chromia chain. Returns `{ success, toolCallId, error? }`. Use this if you need to separate the on-chain logging step from the verdict request.
 
 ### Poll judgment status
 
@@ -184,39 +190,32 @@ toPubkeyHex(val: unknown): string
 
 `loadAgent(privkey)` is the canonical loader — pass in the private key from the dashboard, get back `{ pubkey, privkey }` ready for `judgeAction`. It accepts `0x`-prefixed, padded, or mixed-case input and throws on malformed keys. Use `generateKeyPair()` only for local development; for production, create agents in the dashboard so operators can attach policies.
 
-### Query APIs
-
-Read from the Atbash audit trail and operator queues:
-
-```ts
-// Tool call history
-getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>
-getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>
-getAgentToolCalls(agentPubkey: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>
-getToolCallCount(opts?: ClientOpts): Promise<number>
-getToolCallFull(toolCallId: string, opts?: ClientOpts): Promise<ToolCallFull | null>
-
-// Org and agent info
-getOrgTierInfo(orgName: string, opts?: ClientOpts): Promise<TierInfo | null>
-getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise<Record<string, unknown>>
-getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>
-
-// Operator review queue
-getPendingHeldActions(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldAction[]>
-getHeldActionReviews(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldActionReview[]>
-
-// Chain-wide stats
-getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>
-```
-
-All query functions accept an optional `ClientOpts` to override the endpoint:
-
-```ts
-interface ClientOpts {
-  endpoint?: string;  // Default: https://atbash.ai
-  timeout?: number;
-}
-```
+### Operations
+
+Functions that sign transactions and write to the Chromia blockchain.
+
+| Function | Use case |
+|----------|----------|
+| `judgeAction(action, context, auth, opts?)` | Sign `log_tool_call` on-chain + request a verdict from the judge API |
+| `logToolCall(action, context, auth, ...)` | Sign and broadcast `log_tool_call` to chain without requesting a verdict |
+
+### Queries
+
+| Function | Use case |
+|----------|----------|
+| `checkAgentExists(pubkey, opts?)` | Check if an agent is onboarded before signing |
+| `getJudgmentStatus(judgmentId, opts?)` | Poll whether a held action has been approved or rejected |
+| `getToolCalls(maxCount)` | List recent tool calls across all agents |
+| `getOrgToolCalls(orgName, maxCount)` | List tool calls for a specific org |
+| `getAgentToolCalls(pubkey, maxCount)` | List tool calls for a specific agent |
+| `getToolCallCount()` | Get total number of tool calls on-chain |
+| `getToolCallFull(toolCallId)` | Get full details of a single tool call (verdict, context, timing) |
+| `getOrgTierInfo(orgName)` | Check an org's tier and whether verdicts are enabled |
+| `getAgentDetail(pubkey)` | Get agent metadata (org, status, creation date) |
+| `getAgentPolicy(pubkey)` | Check agent's policy pack and jail status |
+| `getPendingHeldActions(orgName, maxCount)` | List actions waiting for operator approval |
+| `getHeldActionReviews(orgName, maxCount)` | List completed operator reviews |
+| `getSafetyStats()` | Get chain-wide safety statistics (total judgments, verdicts, etc.) |
 
 ## Configuration
 
@@ -235,14 +234,10 @@ const result = await judgeAction(action, context, auth, {
   model: "gpt-4o",
 });
 
-// Custom Chromia chain (e.g. production RID)
-const result = await judgeAction(action, context, auth, {
-  chainOpts: {
-    blockchainRid: "YOUR_PRODUCTION_BLOCKCHAIN_RID",
-  },
-});
 ```
 
+> **Advanced:** The SDK connects to the default Atbash Chromia chain. To use a different chain, pass `chainOpts` with custom `nodeUrls` and `blockchainRid` in `JudgeOptions`.
+
 ## Integration patterns
 
 ### Pre-execution gate

package/dist/index.cjs

@@ -110,14 +110,29 @@ function generateToolCallId() {
   const rand = (0, import_crypto.randomBytes)(4).toString("hex");
   return `tc-${ts}-${rand}`;
 }
+async function buildSignedTx(opName, args, auth, chainOpts) {
+  const nodeUrls = chainOpts?.nodeUrls ?? DEFAULT_CHROMIA_NODE_URLS;
+  const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
+  const client = await createClient({ nodeUrlPool: nodeUrls, blockchainRid });
+  const privKeyBuf = Buffer.from(auth.privkey, "hex");
+  const keyPair = encryption.makeKeyPair(privKeyBuf);
+  const sigProvider = newSignatureProvider({
+    privKey: keyPair.privKey,
+    pubKey: keyPair.pubKey
+  });
+  const signed = await client.signTransaction(
+    {
+      operations: [{ name: opName, args }],
+      signers: [keyPair.pubKey]
+    },
+    sigProvider
+  );
+  return Buffer.from(signed).toString("hex");
+}
 async function checkAgentExists(pubkey, opts) {
-  try {
-    const url = `${baseUrl(opts)}/api/ai/exists?pubkey=${encodeURIComponent(pubkey)}`;
-    const data = await getJson(url, opts);
-    return Boolean(data.registered);
-  } catch {
-    return false;
-  }
+  const url = `${baseUrl(opts)}/api/ai/exists?pubkey=${encodeURIComponent(pubkey)}`;
+  const data = await getJson(url, opts);
+  return Boolean(data.registered);
 }
 async function logToolCall(action, context, auth, chainOpts, extra, clientOpts) {
   const exists = await checkAgentExists(auth.pubkey, clientOpts);
@@ -129,38 +144,25 @@ async function logToolCall(action, context, auth, chainOpts, extra, clientOpts)
     };
   }
   try {
-    const nodeUrls = chainOpts?.nodeUrls ?? DEFAULT_CHROMIA_NODE_URLS;
-    const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
-    const client = await createClient({
-      nodeUrlPool: nodeUrls,
-      blockchainRid
-    });
-    const privKeyBuf = Buffer.from(auth.privkey, "hex");
-    const keyPair = encryption.makeKeyPair(privKeyBuf);
-    const sigProvider = newSignatureProvider({
-      privKey: keyPair.privKey,
-      pubKey: keyPair.pubKey
-    });
     const toolCallId = generateToolCallId();
-    await client.signAndSendUniqueTransaction(
-      {
-        name: "log_tool_call",
-        args: [
-          toolCallId,
-          action,
-          context || "",
-          extra?.toolName || "",
-          extra?.toolArgsJson || ""
-        ]
-      },
-      sigProvider
+    const signedHex = await buildSignedTx(
+      "log_tool_call",
+      [
+        toolCallId,
+        action,
+        context || "",
+        extra?.toolName || "",
+        extra?.toolArgsJson || ""
+      ],
+      auth,
+      chainOpts
     );
-    return { success: true, toolCallId };
+    return { success: true, toolCallId, signedHex };
   } catch (err) {
     return {
       success: false,
       toolCallId: null,
-      error: err instanceof Error ? err.message : "Failed to log tool call on-chain"
+      error: err instanceof Error ? err.message : "Failed to sign log_tool_call"
     };
   }
 }
@@ -215,6 +217,7 @@ async function postJson(url, body, opts) {
 async function getJson(url, opts) {
   const resp = await fetch(url, {
     method: "GET",
+    headers: { Accept: "application/json" },
     signal: opts?.timeout ? AbortSignal.timeout(opts.timeout) : void 0
   });
   if (!resp.ok) {
@@ -223,7 +226,10 @@ async function getJson(url, opts) {
   }
   return resp.json();
 }
-async function judgeAction(action, context, auth, opts) {
+async function judgeAction(action, context = "", auth, opts) {
+  if (!action || !action.trim()) {
+    throw new Error("action is required and cannot be empty.");
+  }
   const logResult = await logToolCall(
     action,
     context,
@@ -232,25 +238,32 @@ async function judgeAction(action, context, auth, opts) {
     { toolName: opts?.toolName, toolArgsJson: opts?.toolArgsJson },
     opts
   );
-  if (!logResult.success || !logResult.toolCallId) {
-    throw new Error(logResult.error || "Failed to log tool call on-chain");
+  if (!logResult.success || !logResult.toolCallId || !logResult.signedHex) {
+    throw new Error(logResult.error || "Failed to sign log_tool_call");
+  }
+  let signedJudgeActionHex;
+  if (!opts?.provider) {
+    const judgmentId = generateToolCallId();
+    signedJudgeActionHex = await buildSignedTx(
+      "judge_action",
+      [judgmentId, action, context || "", ""],
+      auth,
+      opts?.chainOpts
+    );
   }
   const url = `${baseUrl(opts)}/api/v1/judge`;
-  const data = await postJson(
-    url,
-    {
-      tool_call_id: logResult.toolCallId,
-      agent_pubkey: auth.pubkey,
-      action,
-      ...context && { context },
-      ...opts?.provider && { provider: opts.provider },
-      ...opts?.toolName && { tool_name: opts.toolName },
-      ...opts?.apiKey && { api_key: opts.apiKey },
-      ...opts?.providerEndpoint && { endpoint_url: opts.providerEndpoint },
-      ...opts?.model && { model: opts.model }
-    },
-    opts
-  );
+  const body = {
+    tool_call_id: logResult.toolCallId,
+    agent_pubkey: auth.pubkey,
+    action,
+    signed_log_tool_call: logResult.signedHex,
+    ...signedJudgeActionHex && { signed_judge_action: signedJudgeActionHex },
+    ...context && { context },
+    ...opts?.provider && { provider: opts.provider },
+    ...opts?.toolName && { tool_name: opts.toolName },
+    ...opts?.model && { model: opts.model }
+  };
+  const data = await postJson(url, body, opts);
   return {
     verdict: normalizeVerdict(data.verdict),
     action_type: String(data.action_type || ""),

package/dist/index.d.cts

@@ -1,6 +1,3 @@
-declare const DEFAULT_ENDPOINT = "https://atbash.ai";
-declare const DEFAULT_CHROMIA_NODE_URLS: string[];
-declare const DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
 type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
 type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
 type Tier = "audit" | "audit_plus" | "enforcement" | (string & {});
@@ -9,18 +6,10 @@ type PubkeyValue = string | Buffer | {
     data: number[];
 };
 type JudgmentStatusState = "pending" | "answered" | "error";
-declare function isValidPrivateKey(hex: string): boolean;
-declare function derivePublicKey(privKeyHex: string): string;
-declare function generateKeyPair(): {
-    privKey: string;
-    pubKey: string;
-};
 interface AgentAuth {
     pubkey: string;
     privkey: string;
 }
-declare function loadAgent(privkey: string): AgentAuth;
-declare function toPubkeyHex(val: unknown): string;
 interface ClientOpts {
     endpoint?: string;
     timeout?: number;
@@ -32,23 +21,9 @@ interface ChainOpts {
 interface LogToolCallResult {
     success: boolean;
     toolCallId: string | null;
+    signedHex?: string;
     error?: string;
 }
-/**
- * Check if an agent is onboarded before signing anything.
- * Calls GET /api/ai/exists?pubkey=<66-hex>
- */
-declare function checkAgentExists(pubkey: string, opts?: ClientOpts): Promise<boolean>;
-/**
- * Sign and broadcast `log_tool_call` to the Chromia chain.
- *
- * Checks that the agent is onboarded before signing. The agent's private
- * key is used to sign the transaction locally — never sent over the network.
- */
-declare function logToolCall(action: string, context: string, auth: AgentAuth, chainOpts?: ChainOpts, extra?: {
-    toolName?: string;
-    toolArgsJson?: string;
-}, clientOpts?: ClientOpts): Promise<LogToolCallResult>;
 interface JudgeResult {
     verdict: Verdict;
     action_type: ActionType;
@@ -59,6 +34,22 @@ interface JudgeResult {
     tool_call_id: string;
     on_chain: boolean;
 }
+interface JudgeOptions extends ClientOpts {
+    provider?: Provider;
+    model?: string;
+    toolName?: string;
+    toolArgsJson?: string;
+    chainOpts?: ChainOpts;
+}
+interface JudgmentStatus {
+    status: JudgmentStatusState;
+    verdict: Verdict;
+    reason: string;
+    judgmentId: string;
+    onChain?: boolean;
+    cached?: boolean;
+    responseTimeMs?: number;
+}
 interface TierInfo {
     org_name: string;
     tier: Tier;
@@ -109,31 +100,41 @@ interface HeldActionReview {
     reviewed_at: number;
     created_at: number;
 }
-interface JudgmentStatus {
-    status: JudgmentStatusState;
-    verdict: Verdict;
-    reason: string;
-    judgmentId: string;
-    onChain?: boolean;
-    cached?: boolean;
-    responseTimeMs?: number;
-}
-interface JudgeOptions extends ClientOpts {
-    provider?: Provider;
-    apiKey?: string;
-    providerEndpoint?: string;
-    model?: string;
-    toolName?: string;
-    toolArgsJson?: string;
-    chainOpts?: ChainOpts;
-}
 interface AgentPolicy {
     policy: string;
     is_jailed: boolean;
     is_custom: boolean;
     default_policy: string;
 }
-declare function judgeAction(action: string, context: string, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
+
+declare const DEFAULT_ENDPOINT = "https://atbash.ai";
+declare const DEFAULT_CHROMIA_NODE_URLS: string[];
+declare const DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
+declare function isValidPrivateKey(hex: string): boolean;
+declare function derivePublicKey(privKeyHex: string): string;
+declare function generateKeyPair(): {
+    privKey: string;
+    pubKey: string;
+};
+declare function loadAgent(privkey: string): AgentAuth;
+declare function toPubkeyHex(val: unknown): string;
+/**
+ * Check if an agent is onboarded before signing anything.
+ * Calls GET /api/ai/exists?pubkey=<66-hex>
+ */
+declare function checkAgentExists(pubkey: string, opts?: ClientOpts): Promise<boolean>;
+/**
+ * Sign `log_tool_call` locally and return the signed transaction hex.
+ *
+ * Checks that the agent is onboarded before signing. The private key
+ * is used locally — never sent over the network. The server will
+ * broadcast the signed transaction to the chain.
+ */
+declare function logToolCall(action: string, context: string, auth: AgentAuth, chainOpts?: ChainOpts, extra?: {
+    toolName?: string;
+    toolArgsJson?: string;
+}, clientOpts?: ClientOpts): Promise<LogToolCallResult>;
+declare function judgeAction(action: string, context: string | undefined, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
 declare function getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>;
 declare function getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
 declare function getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
@@ -147,4 +148,4 @@ declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise
 declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
 declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
 
-export { type AgentAuth, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type LogToolCallResult, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, checkAgentExists, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, logToolCall, toPubkeyHex };
+export { type ActionType, type AgentAuth, type AgentPolicy, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type Tier, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, checkAgentExists, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, logToolCall, toPubkeyHex };

package/dist/index.d.ts

@@ -1,6 +1,3 @@
-declare const DEFAULT_ENDPOINT = "https://atbash.ai";
-declare const DEFAULT_CHROMIA_NODE_URLS: string[];
-declare const DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
 type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
 type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
 type Tier = "audit" | "audit_plus" | "enforcement" | (string & {});
@@ -9,18 +6,10 @@ type PubkeyValue = string | Buffer | {
     data: number[];
 };
 type JudgmentStatusState = "pending" | "answered" | "error";
-declare function isValidPrivateKey(hex: string): boolean;
-declare function derivePublicKey(privKeyHex: string): string;
-declare function generateKeyPair(): {
-    privKey: string;
-    pubKey: string;
-};
 interface AgentAuth {
     pubkey: string;
     privkey: string;
 }
-declare function loadAgent(privkey: string): AgentAuth;
-declare function toPubkeyHex(val: unknown): string;
 interface ClientOpts {
     endpoint?: string;
     timeout?: number;
@@ -32,23 +21,9 @@ interface ChainOpts {
 interface LogToolCallResult {
     success: boolean;
     toolCallId: string | null;
+    signedHex?: string;
     error?: string;
 }
-/**
- * Check if an agent is onboarded before signing anything.
- * Calls GET /api/ai/exists?pubkey=<66-hex>
- */
-declare function checkAgentExists(pubkey: string, opts?: ClientOpts): Promise<boolean>;
-/**
- * Sign and broadcast `log_tool_call` to the Chromia chain.
- *
- * Checks that the agent is onboarded before signing. The agent's private
- * key is used to sign the transaction locally — never sent over the network.
- */
-declare function logToolCall(action: string, context: string, auth: AgentAuth, chainOpts?: ChainOpts, extra?: {
-    toolName?: string;
-    toolArgsJson?: string;
-}, clientOpts?: ClientOpts): Promise<LogToolCallResult>;
 interface JudgeResult {
     verdict: Verdict;
     action_type: ActionType;
@@ -59,6 +34,22 @@ interface JudgeResult {
     tool_call_id: string;
     on_chain: boolean;
 }
+interface JudgeOptions extends ClientOpts {
+    provider?: Provider;
+    model?: string;
+    toolName?: string;
+    toolArgsJson?: string;
+    chainOpts?: ChainOpts;
+}
+interface JudgmentStatus {
+    status: JudgmentStatusState;
+    verdict: Verdict;
+    reason: string;
+    judgmentId: string;
+    onChain?: boolean;
+    cached?: boolean;
+    responseTimeMs?: number;
+}
 interface TierInfo {
     org_name: string;
     tier: Tier;
@@ -109,31 +100,41 @@ interface HeldActionReview {
     reviewed_at: number;
     created_at: number;
 }
-interface JudgmentStatus {
-    status: JudgmentStatusState;
-    verdict: Verdict;
-    reason: string;
-    judgmentId: string;
-    onChain?: boolean;
-    cached?: boolean;
-    responseTimeMs?: number;
-}
-interface JudgeOptions extends ClientOpts {
-    provider?: Provider;
-    apiKey?: string;
-    providerEndpoint?: string;
-    model?: string;
-    toolName?: string;
-    toolArgsJson?: string;
-    chainOpts?: ChainOpts;
-}
 interface AgentPolicy {
     policy: string;
     is_jailed: boolean;
     is_custom: boolean;
     default_policy: string;
 }
-declare function judgeAction(action: string, context: string, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
+
+declare const DEFAULT_ENDPOINT = "https://atbash.ai";
+declare const DEFAULT_CHROMIA_NODE_URLS: string[];
+declare const DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
+declare function isValidPrivateKey(hex: string): boolean;
+declare function derivePublicKey(privKeyHex: string): string;
+declare function generateKeyPair(): {
+    privKey: string;
+    pubKey: string;
+};
+declare function loadAgent(privkey: string): AgentAuth;
+declare function toPubkeyHex(val: unknown): string;
+/**
+ * Check if an agent is onboarded before signing anything.
+ * Calls GET /api/ai/exists?pubkey=<66-hex>
+ */
+declare function checkAgentExists(pubkey: string, opts?: ClientOpts): Promise<boolean>;
+/**
+ * Sign `log_tool_call` locally and return the signed transaction hex.
+ *
+ * Checks that the agent is onboarded before signing. The private key
+ * is used locally — never sent over the network. The server will
+ * broadcast the signed transaction to the chain.
+ */
+declare function logToolCall(action: string, context: string, auth: AgentAuth, chainOpts?: ChainOpts, extra?: {
+    toolName?: string;
+    toolArgsJson?: string;
+}, clientOpts?: ClientOpts): Promise<LogToolCallResult>;
+declare function judgeAction(action: string, context: string | undefined, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
 declare function getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>;
 declare function getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
 declare function getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
@@ -147,4 +148,4 @@ declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise
 declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
 declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
 
-export { type AgentAuth, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type LogToolCallResult, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, checkAgentExists, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, logToolCall, toPubkeyHex };
+export { type ActionType, type AgentAuth, type AgentPolicy, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type Tier, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, checkAgentExists, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, logToolCall, toPubkeyHex };

package/dist/index.js

@@ -52,14 +52,29 @@ function generateToolCallId() {
   const rand = randomBytes(4).toString("hex");
   return `tc-${ts}-${rand}`;
 }
+async function buildSignedTx(opName, args, auth, chainOpts) {
+  const nodeUrls = chainOpts?.nodeUrls ?? DEFAULT_CHROMIA_NODE_URLS;
+  const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
+  const client = await createClient({ nodeUrlPool: nodeUrls, blockchainRid });
+  const privKeyBuf = Buffer.from(auth.privkey, "hex");
+  const keyPair = encryption.makeKeyPair(privKeyBuf);
+  const sigProvider = newSignatureProvider({
+    privKey: keyPair.privKey,
+    pubKey: keyPair.pubKey
+  });
+  const signed = await client.signTransaction(
+    {
+      operations: [{ name: opName, args }],
+      signers: [keyPair.pubKey]
+    },
+    sigProvider
+  );
+  return Buffer.from(signed).toString("hex");
+}
 async function checkAgentExists(pubkey, opts) {
-  try {
-    const url = `${baseUrl(opts)}/api/ai/exists?pubkey=${encodeURIComponent(pubkey)}`;
-    const data = await getJson(url, opts);
-    return Boolean(data.registered);
-  } catch {
-    return false;
-  }
+  const url = `${baseUrl(opts)}/api/ai/exists?pubkey=${encodeURIComponent(pubkey)}`;
+  const data = await getJson(url, opts);
+  return Boolean(data.registered);
 }
 async function logToolCall(action, context, auth, chainOpts, extra, clientOpts) {
   const exists = await checkAgentExists(auth.pubkey, clientOpts);
@@ -71,38 +86,25 @@ async function logToolCall(action, context, auth, chainOpts, extra, clientOpts)
     };
   }
   try {
-    const nodeUrls = chainOpts?.nodeUrls ?? DEFAULT_CHROMIA_NODE_URLS;
-    const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
-    const client = await createClient({
-      nodeUrlPool: nodeUrls,
-      blockchainRid
-    });
-    const privKeyBuf = Buffer.from(auth.privkey, "hex");
-    const keyPair = encryption.makeKeyPair(privKeyBuf);
-    const sigProvider = newSignatureProvider({
-      privKey: keyPair.privKey,
-      pubKey: keyPair.pubKey
-    });
     const toolCallId = generateToolCallId();
-    await client.signAndSendUniqueTransaction(
-      {
-        name: "log_tool_call",
-        args: [
-          toolCallId,
-          action,
-          context || "",
-          extra?.toolName || "",
-          extra?.toolArgsJson || ""
-        ]
-      },
-      sigProvider
+    const signedHex = await buildSignedTx(
+      "log_tool_call",
+      [
+        toolCallId,
+        action,
+        context || "",
+        extra?.toolName || "",
+        extra?.toolArgsJson || ""
+      ],
+      auth,
+      chainOpts
     );
-    return { success: true, toolCallId };
+    return { success: true, toolCallId, signedHex };
   } catch (err) {
     return {
       success: false,
       toolCallId: null,
-      error: err instanceof Error ? err.message : "Failed to log tool call on-chain"
+      error: err instanceof Error ? err.message : "Failed to sign log_tool_call"
     };
   }
 }
@@ -157,6 +159,7 @@ async function postJson(url, body, opts) {
 async function getJson(url, opts) {
   const resp = await fetch(url, {
     method: "GET",
+    headers: { Accept: "application/json" },
     signal: opts?.timeout ? AbortSignal.timeout(opts.timeout) : void 0
   });
   if (!resp.ok) {
@@ -165,7 +168,10 @@ async function getJson(url, opts) {
   }
   return resp.json();
 }
-async function judgeAction(action, context, auth, opts) {
+async function judgeAction(action, context = "", auth, opts) {
+  if (!action || !action.trim()) {
+    throw new Error("action is required and cannot be empty.");
+  }
   const logResult = await logToolCall(
     action,
     context,
@@ -174,25 +180,32 @@ async function judgeAction(action, context, auth, opts) {
     { toolName: opts?.toolName, toolArgsJson: opts?.toolArgsJson },
     opts
   );
-  if (!logResult.success || !logResult.toolCallId) {
-    throw new Error(logResult.error || "Failed to log tool call on-chain");
+  if (!logResult.success || !logResult.toolCallId || !logResult.signedHex) {
+    throw new Error(logResult.error || "Failed to sign log_tool_call");
+  }
+  let signedJudgeActionHex;
+  if (!opts?.provider) {
+    const judgmentId = generateToolCallId();
+    signedJudgeActionHex = await buildSignedTx(
+      "judge_action",
+      [judgmentId, action, context || "", ""],
+      auth,
+      opts?.chainOpts
+    );
   }
   const url = `${baseUrl(opts)}/api/v1/judge`;
-  const data = await postJson(
-    url,
-    {
-      tool_call_id: logResult.toolCallId,
-      agent_pubkey: auth.pubkey,
-      action,
-      ...context && { context },
-      ...opts?.provider && { provider: opts.provider },
-      ...opts?.toolName && { tool_name: opts.toolName },
-      ...opts?.apiKey && { api_key: opts.apiKey },
-      ...opts?.providerEndpoint && { endpoint_url: opts.providerEndpoint },
-      ...opts?.model && { model: opts.model }
-    },
-    opts
-  );
+  const body = {
+    tool_call_id: logResult.toolCallId,
+    agent_pubkey: auth.pubkey,
+    action,
+    signed_log_tool_call: logResult.signedHex,
+    ...signedJudgeActionHex && { signed_judge_action: signedJudgeActionHex },
+    ...context && { context },
+    ...opts?.provider && { provider: opts.provider },
+    ...opts?.toolName && { tool_name: opts.toolName },
+    ...opts?.model && { model: opts.model }
+  };
+  const data = await postJson(url, body, opts);
   return {
     verdict: normalizeVerdict(data.verdict),
     action_type: String(data.action_type || ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/sdk",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Atbash SDK — control boundary before the last irreversible step in an agent workflow",
   "homepage": "https://atbash.ai",
   "author": "Atbash",
@@ -26,6 +26,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
     "release": "npm version patch --no-git-tag-version && npm run build && npx npm@10 publish --access public"
   },
   "devDependencies": {