@tangle-network/sandbox-cli 0.8.3-develop.20260623085144.b80a88e → 0.8.3-develop.20260623145823.af08643

package/hub-reference.md

@@ -40,7 +40,7 @@ tangle hub connections --json
 {
   "connections": [
     {
-      "id": "conn_abc123",
+      "id": "hubconn_github_a1",
       "providerId": "github",
       "displayName": "GitHub",
       "accountDisplay": "octocat",
@@ -59,6 +59,25 @@ Connection `status`: `active`, `revoked`, `unhealthy`, `reconnect_required`.
 
 Connection `health`: `unknown`, `healthy`, `unhealthy`, `rate_limited`.
 
+#### Connection references
+
+Anywhere a command takes a connection (`--connection`, `connections revoke`,
+`agent --connection`), you may pass a raw connection id (`hubconn_...`) or a
+human reference instead:
+
+- `<provider>` — e.g. `github`, resolves when you hold exactly one connection
+  for that provider.
+- `<provider>:<account>` — e.g. `gmail:alice@example.com`, disambiguates when
+  you hold several connections for one provider (matches `accountDisplay` or
+  `displayName`).
+
+A reference resolves against `tangle hub connections`; revoked connections are
+skipped. If it matches no connection, or more than one, the CLI fails loud and
+lists the candidates so you can pass an id or `provider:account`. Raw ids never
+contact the hub for resolution. The `agent --connection` head is followed by
+`:capabilities`, so it accepts a provider or an id but not `provider:account` —
+use an id when a provider is ambiguous there.
+
 ### OAuth Connect
 
 ```bash
@@ -196,7 +215,7 @@ tangle hub approvals list --json
   "approvals": [
     {
       "id": "app_xxx",
-      "connectionId": "conn_abc123",
+      "connectionId": "hubconn_github_a1",
       "providerId": "github",
       "actionPath": "github.issues.create",
       "inputHash": "sha256:...",
@@ -224,7 +243,7 @@ tangle hub approvals deny app_xxx --json
   "approval": {
     "id": "app_xxx",
     "status": "approved",
-    "connectionId": "conn_abc123",
+    "connectionId": "hubconn_github_a1",
     "actionPath": "github.issues.create"
   },
   "capabilityToken": {
@@ -239,7 +258,7 @@ tangle hub approvals deny app_xxx --json
 ### Permissions
 
 ```bash
-tangle hub permissions list --connection conn_xxx --json
+tangle hub permissions list --connection hubconn_github_a1 --json
 ```
 
 ```json
@@ -247,7 +266,7 @@ tangle hub permissions list --connection conn_xxx --json
   "policies": [
     {
       "id": "pol_xxx",
-      "connectionId": "conn_xxx",
+      "connectionId": "hubconn_github_a1",
       "providerId": "github",
       "actionPath": "github.issues.create",
       "decision": "ask",
@@ -263,14 +282,14 @@ tangle hub permissions list --connection conn_xxx --json
 ### Permission Set
 
 ```bash
-tangle hub permissions set --connection conn_xxx --action github.issues.create --decision allow --json
+tangle hub permissions set --connection hubconn_github_a1 --action github.issues.create --decision allow --json
 ```
 
 ```json
 {
   "policy": {
     "id": "pol_xxx",
-    "connectionId": "conn_xxx",
+    "connectionId": "hubconn_github_a1",
     "providerId": "github",
     "actionPath": "github.issues.create",
     "decision": "allow",
@@ -280,6 +299,55 @@ tangle hub permissions set --connection conn_xxx --action github.issues.create -
 }
 ```
 
+### Granting connections to an agent
+
+`tangle agent prompt`/`tangle agent task` expose granted hub connections to the
+agent as MCP tools with `--connection <spec>` (repeatable). Three modes, from
+least to most privilege:
+
+The spec head is a connection id or a provider name (see
+[Connection references](#connection-references)).
+
+```bash
+# Least privilege (recommended): the agent sees exactly these tool paths.
+tangle agent task sbx_123 "triage issues" \
+  --connection github:github.issues.listIssues,github.issues.create
+
+# All capabilities of one connection (by id when a provider is ambiguous).
+tangle agent task sbx_123 "triage issues" --connection hubconn_github_a1:*
+
+# All capabilities of every connected provider (broadest).
+tangle agent task sbx_123 "do the thing" --connection '*:*'
+```
+
+A grant controls what the agent can **see**. Each call is still policy-gated
+(`allow`/`ask`/`deny`); by default reads are allowed and writes/destructive
+actions prompt for approval.
+
+### `--allow-writes`
+
+Pre-approve every **write** action of each granted connection so an autonomous
+run can write without per-action prompts. Reads are already allowed; destructive
+actions still prompt. The grant is persistent and scoped to the named
+connections only.
+
+```bash
+tangle agent task sbx_123 "file the weekly report" \
+  --connection github:* --allow-writes
+```
+
+Revert the bulk grant at any time — it deletes only the rows `--allow-writes`
+created, leaving manual `permissions set` decisions intact:
+
+```bash
+tangle hub permissions revert-writes --connection github
+```
+
+> `--allow-writes` needs a named connection (id or provider); the `*:*`
+> wildcard can't be bulk-granted. Pass `--no-hub-key` (or set
+> `TANGLE_SKIP_HUB_KEY=1`) to skip auto-minting a platform Hub key and use your
+> stored credential as-is.
+
 ## Error Format
 
 ```bash
@@ -345,7 +413,7 @@ tangle hub tools describe github.issues.listIssues --json
 tangle hub exec github.issues.listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}' --approve
 
 # 5. Set permanent policy
-tangle hub permissions set --connection conn_xxx --action github.issues.listIssues --decision allow
+tangle hub permissions set --connection hubconn_github_a1 --action github.issues.listIssues --decision allow
 ```
 
 ### Batch Approvals
@@ -364,11 +432,11 @@ done
 
 ```bash
 # Show all policies for one connection
-tangle hub permissions list --connection conn_xxx --json
+tangle hub permissions list --connection hubconn_github_a1 --json
 
 # Set all read actions to allow, write actions to ask
-tangle hub permissions set --connection conn_xxx --action github.issues.listIssues --decision allow
-tangle hub permissions set --connection conn_xxx --action github.issues.create --decision ask
+tangle hub permissions set --connection hubconn_github_a1 --action github.issues.listIssues --decision allow
+tangle hub permissions set --connection hubconn_github_a1 --action github.issues.create --decision ask
 ```
 
 ## GitHub App Primitives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox-cli",
-  "version": "0.8.3-develop.20260623085144.b80a88e",
+  "version": "0.8.3-develop.20260623145823.af08643",
   "description": "CLI for Tangle Sandbox operations",
   "type": "module",
   "bin": {
@@ -15,15 +15,15 @@
     "hub-reference.md"
   ],
   "dependencies": {
-    "@tangle-network/agent-eval": "^0.95.1",
-    "@tangle-network/agent-runtime": "^0.70.1",
+    "@tangle-network/agent-eval": "^0.99.0",
+    "@tangle-network/agent-runtime": "^0.76.0",
     "chalk": "^5.4.1",
     "commander": "12.1.0",
     "dotenv": "17.2.3",
     "ora": "^9.4.0",
     "ws": "^8.20.0",
     "@tangle-network/hub-sdk": "0.2.2",
-    "@tangle-network/sandbox": "0.8.3-develop.20260623085144.b80a88e"
+    "@tangle-network/sandbox": "0.8.3-develop.20260623145823.af08643"
   },
   "devDependencies": {
     "@types/node": "25.6.0",