@atbash/autogen 0.2.0

package/README.md

@@ -0,0 +1,127 @@
+# `@atbash/autogen`
+
+Atbash safety judge for AutoGen-style multi-agent orchestration loops.
+
+This package is intentionally small. It gives you one focused helper to ask Atbash for a verdict at the point where your app decides whether to proceed with an action. It does not own your orchestration model.
+
+## Installation
+
+```bash
+npm install @atbash/autogen
+```
+
+## When To Use It
+
+Use this package when:
+
+- you already control your own orchestration steps
+- you want one explicit Atbash check before a side effect
+- you do not need a heavier plugin lifecycle
+
+Good fits:
+
+- AutoGen-style multi-agent loops
+- custom planners
+- supervisor-worker systems
+- approval chains where your app already owns the review UI
+
+## Quick Start
+
+```ts
+import { createAtbashClient, loadAgent } from "@atbash/sdk";
+import { judgeForAutoGen } from "@atbash/autogen";
+
+const agent = loadAgent(process.env.ATBASH_AGENT_PRIVKEY);
+const client = createAtbashClient({ keyPair: { privKey: agent.privkey, pubKey: agent.pubkey } });
+
+const result = await judgeForAutoGen(
+  {
+    action: "Bank transfer $25 to a new external vendor account",
+    context: "AutoGen agent checking transfer before execution",
+    toolName: "send_bank_transfer",
+    toolArgs: { amount: 25, recipient: "new vendor" },
+  },
+  client,
+);
+
+if (result.allow) {
+  // proceed
+} else {
+  // stop — surface result.reason to the operator
+}
+```
+
+## API
+
+### `judgeForAutoGen(input, client)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `input` | `AutoGenJudgeInput` | The action to evaluate |
+| `client` | `AtbashClient` | SDK client created with `createAtbashClient()` |
+
+Returns `Promise<Decision>`.
+
+### `AutoGenJudgeInput`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | Yes | Human-readable description of the action |
+| `context` | `string` | Yes | Why the agent is taking this action |
+| `toolName` | `string` | No | Name of the tool being called (defaults to `"autogen_action"`) |
+| `toolArgs` | `unknown` | No | Structured payload the judge evaluates (defaults to `{ action }`) |
+
+### `Decision`
+
+| Field | Type | Description |
+|---|---|---|
+| `allow` | `boolean` | Whether to proceed |
+| `verdict` | `"ALLOW" \| "HOLD" \| "BLOCK" \| "ERROR"` | Judge verdict |
+| `reason` | `string?` | Policy reason (present on HOLD/BLOCK) |
+| `toolCallId` | `string?` | ID to pass back on HOLD resolution |
+
+## Verdict Handling
+
+| Verdict | Meaning | Action |
+|---|---|---|
+| `ALLOW` | Safe to proceed | Continue orchestration |
+| `HOLD` | Needs human review | Stop and hand off; keep `toolCallId` |
+| `BLOCK` | Policy violation | Stop and surface `reason` |
+| `ERROR` | Judge unreachable | Fail closed by default |
+
+## Creating the Client
+
+Create the `AtbashClient` once at startup, then pass it to every `judgeForAutoGen` call.
+
+```ts
+import { createAtbashClient, loadAgent } from "@atbash/sdk";
+
+const agent = loadAgent(process.env.ATBASH_AGENT_PRIVKEY);
+const client = createAtbashClient({ keyPair: { privKey: agent.privkey, pubKey: agent.pubkey } });
+```
+
+To use a custom endpoint:
+
+```ts
+const client = createAtbashClient({
+  keyPair: { privKey: agent.privkey, pubKey: agent.pubkey },
+  judge: { endpoint: process.env.ATBASH_ENDPOINT },
+});
+```
+
+## What This Package Does Not Do
+
+- It does not wrap your framework for you.
+- It does not create a review queue.
+- It does not log or execute the real action automatically.
+
+That is intentional. The host loop stays in control.
+
+## Example
+
+A runnable example is in [`examples/autogen-runtime-agent/`](./examples/autogen-runtime-agent/).
+
+```bash
+cd examples/autogen-runtime-agent
+ATBASH_AGENT_PRIVKEY=your_key_here node run.mjs
+```

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { AtbashClient, Decision } from '@atbash/sdk';
+
+type AutoGenJudgeInput = {
+    action: string;
+    context: string;
+    toolName?: string;
+    toolArgs?: unknown;
+};
+/**
+ * Submit an AutoGen-style action to the Atbash judge for evaluation.
+ *
+ * Uses the high-level `AtbashClient.auditToolCall` so the call inherits
+ * secret redaction, endpoint validation, fail-closed defaults, and the
+ * normalised `Decision` shape from the SDK.
+ *
+ * The user-supplied human-readable `action` description is forwarded to
+ * the judge alongside the caller's own `context` string, while the
+ * structured `toolArgs` become the action payload the redactor scans
+ * and the judge evaluates.
+ */
+declare function judgeForAutoGen(input: AutoGenJudgeInput, client: AtbashClient): Promise<Decision>;
+
+export { type AutoGenJudgeInput, judgeForAutoGen };

package/dist/index.js

@@ -0,0 +1,16 @@
+// src/index.ts
+async function judgeForAutoGen(input, client) {
+  const action = input.action?.trim();
+  const context = input.context?.trim();
+  if (!action || !context) {
+    throw new Error("Both action and context are required");
+  }
+  return client.auditToolCall({
+    toolName: input.toolName ?? "autogen_action",
+    args: input.toolArgs ?? { action },
+    context: `${action} \u2014 ${context}`
+  });
+}
+export {
+  judgeForAutoGen
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@atbash/autogen",
+  "version": "0.2.0",
+  "description": "Atbash safety judge plugin for AutoGen-style multi-agent orchestration",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "atbash",
+    "autogen",
+    "ai-safety",
+    "agent-safety",
+    "multi-agent",
+    "judge",
+    "policy"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "node examples/autogen-runtime-agent/run.mjs"
+  },
+  "dependencies": {
+    "@atbash/sdk": "^0.3.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.6"
+  }
+}