@atbash/sdk 0.3.11-dev.1 → 0.3.11-dev.11

package/README.md

@@ -23,10 +23,12 @@ const agent = loadAgent(process.env.ATBASH_AGENT_PRIVKEY!);
 // 2. Submit an action for judgment, before executing it.
 //    The SDK signs the transaction locally and sends it to the judge API.
 //    Private key stays on your machine — never sent over HTTP.
+//    Pass orgName so the SDK auto-resolves the correct chain (public or private).
 const result = await judgeAction(
   "Transfer $50,000 to external wallet 0xabc",
   "Outbound AML check — new recipient, over threshold",
   agent,
+  { orgName: "my_org" },
 );
 
 // 3. Enforce the verdict
@@ -39,19 +41,19 @@ switch (result.verdict) {
     console.log("Held for review:", result.tool_call_id);
     break;
   case "BLOCK":
-    // Refused — agent is jailed in Enforcement tier
+    // Refused — agent is auto-jailed
     throw new Error(`Blocked: ${result.reason}`);
 }
 ```
 
-Before this works, the agent must be onboarded at [atbash.ai](https://atbash.ai/) — assigned to an org, with a policy pack attached, and the org tier set to Audit+ or Enforcement.
+Before this works, the agent must be onboarded at [atbash.ai](https://atbash.ai/) — assigned to an org with an active subscription and a policy pack attached.
 
 ### How it works
 
 `judgeAction()` performs a two-step flow:
 
 1. **Sign locally** — signs the transaction using the agent's private key. The key never leaves your machine.
-2. **Request verdict** — sends the signed transaction, `tool_call_id`, and `agent_pubkey` to the Atbash judge API. The server broadcasts it to the Chromia blockchain and returns a verdict.
+2. **Request verdict** — sends the signed payload to the Atbash judge API, which records it on the Chromia blockchain and returns a verdict.
 
 
 ### Don't have an agent yet?
@@ -86,9 +88,9 @@ Every `judgeAction` call returns one of three verdicts:
 |---------|---------|-------------------------|
 | `ALLOW` | Action is within policy | Proceed with execution |
 | `HOLD` | Requires operator review | Pause — poll `getJudgmentStatus` until resolved |
-| `BLOCK` | Violates a red line | Abort — agent is jailed in Enforcement tier |
+| `BLOCK` | Violates a red line | Abort — agent is auto-jailed |
 
-> **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.
+> **NB:** If your org has **no active subscription**, the judge returns `"No verdict"` — actions are logged on-chain for the audit trail but not evaluated. Assign a subscription plan at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) for active verdicts. All subscription plans (including Free) get full enforcement.
 
 ## API
 
@@ -118,17 +120,11 @@ interface JudgeOptions {
   model?: string;             // Model override (e.g. "gpt-4o-mini")
   toolName?: string;          // Tool name for audit trail
   toolArgsJson?: string;      // Tool arguments JSON for audit trail
-  chainOpts?: ChainOpts;      // Override Chromia chain connection
-}
-
-interface ChainOpts {
-  nodeUrls?: string[];        // Chromia node URLs (uses the default  nodeurls)
-  blockchainRid?: string;     // Blockchain RID (uses the default chromia rid)
+  orgName?: string;           // Org name — SDK auto-resolves the correct chain
 }
 
 interface JudgeResult {
   verdict: string;       // "ALLOW", "HOLD", or "BLOCK"
-  action_type: string;   // "allow", "hold_for_user_confirm", or "block"
   reason: string;        // Human-readable explanation
   confidence: number;    // 0–1
   provider: string;      // Which provider evaluated the action
@@ -138,20 +134,6 @@ interface JudgeResult {
 }
 ```
 
-### Log tool call (low-level)
-
-```ts
-logToolCall(
-  action: string,
-  context: string,
-  auth: AgentAuth,
-  chainOpts?: ChainOpts,
-  extra?: { toolName?: string; toolArgsJson?: string },
-): Promise<LogToolCallResult>
-```
-
-Sign the transaction locally. Returns `{ success, toolCallId, signedHex?, error? }`. Use this if you need to separate the signing step from the verdict request.
-
 ### Poll judgment status
 
 ```ts
@@ -191,7 +173,6 @@ Functions that sign transactions and write to the Chromia blockchain.
 | Function | Use case |
 |----------|----------|
 | `judgeAction(action, context, auth, opts?)` | Sign locally + request a verdict from the judge API |
-| `logToolCall(action, context, auth, ...)` | Sign the transaction locally without requesting a verdict |
 
 ### Queries
 
@@ -204,7 +185,7 @@ Functions that sign transactions and write to the Chromia blockchain.
 | `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 |
+| `getOrgSubscription(orgName)` | Check an org's subscription plan, network, and active status |
 | `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 |
@@ -242,6 +223,7 @@ saveUserConfig({
 // Then use resolve() anywhere
 const agent = loadAgent(resolve("agentKey"));
 const result = await judgeAction("Transfer $500", "finance", agent, {
+  orgName: resolve("orgName"),
   provider: resolve("provider"), // omit to use the on-chain ATBASH judge
 });
 ```
@@ -264,7 +246,7 @@ Config file location: `~/.config/atbash/config.json`
 | `provider` | `ATBASH_PROVIDER` |
 | `providerModel` | `ATBASH_PROVIDER_MODEL` |
 
-> **Advanced:** The SDK connects to the default Atbash Chromia chain. To use a different chain, pass `chainOpts` with custom `nodeUrls` and `blockchainRid` in `JudgeOptions`.
+> **Chain routing:** When you pass `orgName`, the SDK automatically connects to the correct chain for your org's subscription plan. You don't need to configure chain details manually.
 
 ## Secret redaction
 
@@ -285,6 +267,32 @@ Common `kinds`:
 
 Redaction is silent at the consumer level — the SDK's caller still has the original arguments. Only what's sent to the judge (and persisted on chain via the verdict log) is scrubbed.
 
+## High-level client
+
+For framework integrations, `createAtbashClient` wraps key loading, secret redaction, and verdict handling into a single `auditToolCall` method:
+
+```ts
+import { createAtbashClient } from "@atbash/sdk";
+
+const atbash = createAtbashClient({
+  orgName: "my_org",
+  keyPair: { privKey: process.env.ATBASH_AGENT_KEY!, pubKey: "" },
+  failClosed: true,  // block on errors (default: true)
+});
+
+const decision = await atbash.auditToolCall({
+  toolName: "send_email",
+  args: { to: "user@example.com", subject: "Reset" },
+  context: "Password reset flow",
+});
+
+if (!decision.allow) {
+  console.log(`${decision.verdict}: ${decision.reason}`);
+}
+```
+
+The client auto-resolves the correct chain from the org's subscription on the first call and caches the result. Secret redaction runs automatically before signing.
+
 ## Integration patterns
 
 ### Pre-execution gate
@@ -334,8 +342,8 @@ API error 404: {"error":"Agent not registered..."}
 |---|---|---|
 | `API error 404: Agent not registered` | Agent not onboarded | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
 | `API error 400: Agent has no policy` | No policy attached to agent | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
-| `Agent is jailed` | BLOCK verdict triggered auto-jail (Enforcement tier) | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
-| `Org tier does not support verdicts` | Org is on Audit tier | [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |
+| `Agent is jailed` | BLOCK verdict triggered auto-jail | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
+| `Verdicts are disabled` | Org has no active subscription | [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |
 | `API error 400: action is required` | Empty action string | Fix caller |
 | `API error 502: Incorrect API key` | Invalid provider API key | Check saved key at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |