@agentvalet/client 0.1.1 → 0.1.2

package/README.md

@@ -46,6 +46,20 @@ const result = await av.call({
 });
 ```
 
+`call()` resolves to the broker's envelope — the upstream SaaS body under
+`data`, with `_meta` describing the call itself:
+
+```typescript
+{
+  data: { ok: true, ts: "1723800000.000100" },   // exactly what Slack returned
+  _meta: { capability: "agent.action", timestamp: "…", next_actions: […], docs: "…" }
+}
+```
+
+So it's `result.data.ok`, not `result.ok`. The split is deliberate: `data` is the
+upstream payload byte-for-byte, so anything the broker adds about the call stays
+outside it.
+
 `fromEnv()` reads `AGENTVALET_AGENT_ID` / `AGENTVALET_OWNER_ID` (or the bare
 `AGENT_ID` / `OWNER_ID` the CLI writes) and finds the key via
 `AGENT_PRIVATE_KEY_B64`, `AGENT_PRIVATE_KEY_PATH`, `AGENT_PRIVATE_KEY`, or
@@ -135,6 +149,41 @@ await av.evaluate("stripe", "charge");     // dry-run the decision, no side effe
 `evaluate()` is worth a call before anything destructive — it tells you whether
 the action would be allowed without performing it.
 
+## Which connection served the call
+
+When a platform has several connections and you don't pin one, the broker uses
+the default. That's the quiet failure behind a lot of confused agents: you ask
+for a repo, the default GitHub account doesn't have it, you get a 404, and you
+conclude the repo doesn't exist rather than that you're on the wrong account.
+
+When there was more than one connection you could have used, the response says
+so. On success it rides `_meta`, leaving `data` untouched:
+
+```typescript
+res._meta.connection;
+// {
+//   used: "o-github", label: "Acme", defaulted: true,
+//   others: [{ connection_id: "o-github-9f1c", label: "Personal" }],
+//   hint: "…the target may live on another connection — retry with connection_id…"
+// }
+```
+
+On an upstream error there's no envelope — the body is exactly what the platform
+sent — so the same information arrives as one namespaced key, carried on
+`ProxyError.body`:
+
+```json
+{
+  "message": "Not Found",
+  "_agentvalet": { "connection": { "used": "o-github", "defaulted": true, "others": [], "hint": "…" } }
+}
+```
+
+The upstream keys stay where they were, so existing error handling is unaffected.
+It's absent when there's nothing to act on — a connection you pinned, a platform
+with one connection, or a lookup that failed — so treat its absence as "no
+alternatives", never as "this is definitely the right account".
+
 ## Self-hosting
 
 Point `proxyUrl` at your own deployment. Everything else is identical.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentvalet/client",
-  "version": "0.1.1",
-  "description": "AgentValet client SDK — call approved SaaS platforms from any Node agent. Signs the agent JWT, brokers through the AgentValet proxy, and waits out owner approvals.",
+  "version": "0.1.2",
+  "description": "AgentValet client SDK \u2014 call approved SaaS platforms from any Node agent. Signs the agent JWT, brokers through the AgentValet proxy, and waits out owner approvals.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,13 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "node ../../scripts/no-secrets.mjs && pnpm run build && node ../../scripts/no-workspace-protocol.mjs"
+  },
   "dependencies": {
     "jose": "^5.10.0"
   },
@@ -37,11 +44,5 @@
     "sdk"
   ],
   "license": "MIT",
-  "homepage": "https://github.com/AgentValet/AgentValet#readme",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  }
-}
+  "homepage": "https://github.com/AgentValet/AgentValet#readme"
+}