@integrity-labs/cloud-broker 0.5.1 → 0.6.0

package/README.md

@@ -1,8 +1,8 @@
 # `@integrity-labs/cloud-broker`
 
-MCP server for the Augmented ephemeral cloud-access broker. Exposes the agent-facing tools (`request_access`, `poll_grant`, `release_access`, `describe_scope`, `preview_request`) that mint, poll, and release scoped, TTL-bounded cloud credentials for a single task.
+MCP server for the Augmented ephemeral cloud-access broker. Exposes the agent-facing tools (`aws_request_access`, `aws_poll_grant`, `aws_release_access`, `aws_describe_scope`, `aws_preview_request`, `aws_get_credentials`) that mint, poll, and release scoped, TTL-bounded cloud credentials for a single task.
 
-**v1 ships AWS support** (STS AssumeRole under the hood; pair with the `aws-cli` toolkit or any AWS SDK as the consumer). GCP, Azure, and Cloudflare land in this same package as the broker grows; the AWS-shaped tools below are the v1 contract and per-cloud namespacing arrives with the second cloud.
+**v1 ships AWS support** (STS AssumeRole under the hood; pair with the `aws-cli` toolkit or any AWS SDK as the consumer). All tools are namespaced `aws_*` so GCP, Azure, and Cloudflare can land in this same package as `gcp_*` / `azure_*` / `cf_*` siblings without colliding (ENG-4782).
 
 See the [PRD](../../docs/prds/aws-ephemeral-access.md) and the [toolkit doc](../../docs/toolkits/aws.md) for the full design.
 
@@ -10,18 +10,18 @@ See the [PRD](../../docs/prds/aws-ephemeral-access.md) and the [toolkit doc](../
 
 | Tool | Purpose |
 |---|---|
-| `describe_scope` | Returns the team's resolved policy ceiling for an account — what the agent is allowed to ask for. Free, idempotent. |
-| `preview_request` | Dry-run a candidate request: `auto_approve` / `route_to_approver` / `hard_deny`. Writes nothing. |
-| `request_access` | Mint or queue a grant. On `auto_approve` you get `secret_ref`; on `route_to_approver` you get `pending` and a grant_id to poll. |
-| `poll_grant` | Single-shot status check. Back-off ~10s between polls. |
-| `release_access` | Voluntarily release a grant before TTL. Idempotent. |
+| `aws_describe_scope` | Returns the team's resolved policy ceiling for an account — what the agent is allowed to ask for. Free, idempotent. |
+| `aws_preview_request` | Dry-run a candidate request: `auto_approve` / `route_to_approver` / `hard_deny`. Writes nothing. |
+| `aws_request_access` | Mint or queue a grant. On `auto_approve` you get `secret_ref`; on `route_to_approver` you get `pending` and a `grant_id`. |
+| `aws_poll_grant` | Single-shot status check. Escape hatch — the broker pushes resolution via direct-chat. |
+| `aws_get_credentials` | Fetch the AWS_* values for an active grant. Call after `aws_request_access` returns active or after the resolution-notification arrives. |
+| `aws_release_access` | Voluntarily release a grant before TTL. Idempotent. |
 
 ## Environment
 
 | Var | Purpose |
 |---|---|
 | `AGT_HOST` | Augmented API base URL (e.g. `https://api.augmented.example`). |
-| `AGT_TEAM_SLUG` | Team slug for the `X-Team-Slug` header. |
 | `AGT_TOKEN` | Pre-provisioned JWT (preferred). If set, used until expiry. |
 | `AGT_API_KEY` | Host API key (`tlk_…`). Used to refresh the JWT via `/host/exchange` when `AGT_TOKEN` is missing or expired. |
 
@@ -33,10 +33,10 @@ An agent that needs to read one S3 object:
 
 ```jsonc
 // 1. Optional: inspect the envelope before guessing.
-describe_scope({ account_id: "123456789012" })
+aws_describe_scope({ account_id: "123456789012" })
 
 // 2. Optional: dry-run.
-preview_request({
+aws_preview_request({
   account_id: "123456789012",
   actions: ["s3:GetObject", "s3:ListBucket"],
   resources: ["arn:aws:s3:::reports/*", "arn:aws:s3:::reports"],
@@ -46,7 +46,7 @@ preview_request({
 // → { "would": "auto_approve", "reason": null }
 
 // 3. Mint.
-request_access({
+aws_request_access({
   agent_id: "11111111-1111-4111-8111-111111111111",
   run_id: "22222222-2222-4222-8222-222222222222",
   account_id: "123456789012",
@@ -58,21 +58,24 @@ request_access({
 })
 // → { "grant_id": "...", "status": "active", "secret_ref": "secret_ref://aws/runs/<run_id>/<grant_id>", "expires_at": "..." }
 
-// 4. Use the AWS CLI / SDK as normal — the runtime resolves the secret_ref to env vars at exec time.
-//    Bash: aws s3 cp s3://reports/today.csv -
+// 4. Fetch the AWS_* values and use them.
+aws_get_credentials({ grant_id: "..." })
+// → { "grant_id": "...", "expires_at": "...", "credentials": { "access_key_id": "...", "secret_access_key": "...", "session_token": "..." } }
+//    Bash: AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN=... aws s3 cp s3://reports/today.csv -
 
 // 5. (Optional) release early.
-release_access({ grant_id: "..." })
+aws_release_access({ grant_id: "..." })
 ```
 
-If `request_access` returns `status: "pending"`, a human approver was paged. Call `poll_grant` every ~10s until status leaves `pending`. On `denied`, the `denial_reason` field explains why.
+If `aws_request_access` returns `status: "pending"`, a human approver was paged. The broker pushes the resolution to you via direct-chat — save the `grant_id`, return control, and resume when the inbound message arrives. On `denied`, the `denial_reason` field explains why. `aws_poll_grant` is an escape hatch for explicit re-checks.
 
 ## Running locally
 
 ```bash
 pnpm --filter @integrity-labs/cloud-broker build
 AGT_HOST=http://api.agt.localhost:1355 \
-AGT_TEAM_SLUG=demo \
+AGT_AGENT_ID=<your-agent-uuid> \
+AGT_RUN_ID=<your-run-uuid> \
 AGT_TOKEN=$YOUR_JWT \
 node packages/cloud-broker/dist/index.js
 ```
@@ -81,5 +84,6 @@ The server speaks MCP over stdio. Wire it into your runtime adapter's `.mcp.json
 
 ## Notes
 
-- The MCP response strips inline credentials from `request_access` — only the `secret_ref` pointer reaches the LLM. The runtime adapter resolves the pointer at AWS-SDK call time so credentials never enter the agent's transcript.
-- Per PRD §6.3 v1 ships TTL-bounded revocation only. `release_access` marks the grant `revoked` in the broker DB and tears down the `secret_ref`, but in-flight STS sessions remain valid in AWS until their TTL. v1.1 closes that gap with the `aws:TokenIssueTime` hard-revoke pattern.
+- The MCP response strips inline credentials from `aws_request_access` — only the `secret_ref` pointer reaches the LLM. The runtime adapter resolves the pointer at AWS-SDK call time (or via `aws_get_credentials`) so credentials never enter the agent's transcript.
+- Per PRD §6.3 v1 ships TTL-bounded revocation only. `aws_release_access` marks the grant `revoked` in the broker DB and tears down the `secret_ref`, but in-flight STS sessions remain valid in AWS until their TTL. v1.1 closes that gap with the `aws:TokenIssueTime` hard-revoke pattern.
+- **0.6.0 hard-renamed the tools to the `aws_*` namespace (ENG-4782).** Agents on cloud-broker ≤ 0.5.0 will see "tool not found" errors from the broker until they're re-provisioned with the new tool names. Re-run `agt agent provision` for any agent that has the cloud-broker MCP wired in.

package/dist/index.js

@@ -21214,8 +21214,8 @@ var getCredentialsShape = getCredentialsSchema.shape;
 // package.json
 var package_default = {
   name: "@integrity-labs/cloud-broker",
-  version: "0.5.1",
-  description: "Cloud Access Broker \u2014 MCP server that mints scoped, TTL-bounded cloud credentials per agent task. v1 ships AWS support (request_access, poll_grant, release_access, describe_scope, preview_request \u2014 STS AssumeRole under the hood); GCP, Azure, and Cloudflare land alongside in the same package as the broker grows.",
+  version: "0.6.0",
+  description: "Cloud Access Broker \u2014 MCP server that mints scoped, TTL-bounded cloud credentials per agent task. v1 ships AWS support (aws_request_access, aws_poll_grant, aws_release_access, aws_describe_scope, aws_preview_request, aws_get_credentials \u2014 STS AssumeRole under the hood); GCP, Azure, and Cloudflare land alongside in the same package as the broker grows.",
   type: "module",
   bin: {
     "cloud-broker": "./dist/index.js"
@@ -21261,17 +21261,12 @@ var AGT_AGENT_ID = process.env.AGT_AGENT_ID;
 var AGT_RUN_ID = process.env.AGT_RUN_ID ?? "";
 var AGT_TOKEN = process.env.AGT_TOKEN ?? "";
 var AGT_API_KEY = process.env.AGT_API_KEY ?? "";
-if (!AGT_HOST || !AGT_AGENT_ID || !AGT_TOKEN && !AGT_API_KEY) {
+if (!AGT_HOST || !AGT_AGENT_ID || !AGT_RUN_ID || !AGT_TOKEN && !AGT_API_KEY) {
   console.error(
-    "cloud-broker: missing env vars. Need AGT_HOST, AGT_AGENT_ID, and one of AGT_TOKEN or AGT_API_KEY."
+    "cloud-broker: missing env vars. Need AGT_HOST, AGT_AGENT_ID, AGT_RUN_ID, and one of AGT_TOKEN or AGT_API_KEY."
   );
   process.exit(1);
 }
-if (!AGT_RUN_ID) {
-  console.error(
-    "cloud-broker: AGT_RUN_ID is not set. request_access will require run_id in the args; describe_scope / get_credentials / release_access still work without it."
-  );
-}
 if (process.env.AGT_TEAM_SLUG) {
   console.error(
     "cloud-broker: AGT_TEAM_SLUG is set but no longer required (the API derives team from agent_id). Safe to remove from .mcp.json env block."
@@ -21280,7 +21275,7 @@ if (process.env.AGT_TEAM_SLUG) {
 var broker = new BrokerClient({
   host: AGT_HOST,
   agentId: AGT_AGENT_ID,
-  // ENG-4746: thread AGT_RUN_ID through so request_access can default it.
+  // ENG-4746: thread AGT_RUN_ID through so aws_request_access can default it.
   // Empty string is treated as absent — the broker client only fills runId
   // on requestAccess if a non-empty value is provided.
   runId: AGT_RUN_ID || void 0,
@@ -21299,8 +21294,8 @@ var server = new McpServer({
   version: package_default.version
 });
 server.tool(
-  "describe_scope",
-  "Return the team's resolved AWS policy ceiling for an account: max_ttl_seconds, allowed_regions, auto_approved_actions, and the action denylist. Call this before request_access if you're not sure what you're allowed to ask for \u2014 it's free, idempotent, and writes nothing.",
+  "aws_describe_scope",
+  "Return the team's resolved AWS policy ceiling for an account: max_ttl_seconds, allowed_regions, auto_approved_actions, and the action denylist. Call this before aws_request_access if you're not sure what you're allowed to ask for \u2014 it's free, idempotent, and writes nothing.",
   describeScopeShape,
   async (args) => {
     try {
@@ -21312,7 +21307,7 @@ server.tool(
   }
 );
 server.tool(
-  "preview_request",
+  "aws_preview_request",
   'Dry-run a candidate request. Returns one of "auto_approve", "route_to_approver", or "hard_deny" without dispatching anything or writing audit_log. Useful for letting the agent self-tighten its scope before triggering a human approval.',
   previewRequestShape,
   async (args) => {
@@ -21325,8 +21320,8 @@ server.tool(
   }
 );
 server.tool(
-  "request_access",
-  'Request scoped, TTL-bounded AWS credentials for the current task. agent_id and run_id are optional \u2014 the broker fills them from the host MCP env (AGT_AGENT_ID / AGT_RUN_ID). source_context is optional but you SHOULD pass it whenever the request was triggered by an inbound channel message: extract { channel_type, channel_id, thread_ts? } from the `<channel>` tag in the conversation that triggered this. Slack: channel_type="slack", channel_id=tag\'s `channel`, thread_ts=tag\'s `thread_ts`. Telegram: channel_type="telegram", channel_id=tag\'s `chat_id`. Direct-chat: channel_type="direct-chat", channel_id=tag\'s `session_id`. Without source_context the resolution notification dead-ends in your direct-chat instead of threading back to the original conversation. Returns { grant_id, status, secret_ref?, expires_at?, denial_reason?, notification_status?, notification_failure_reason? }. status="active" means credentials are ready, use them now. status="denied" means the request was rejected (denial_reason explains). status="pending" means approval is still outstanding \u2014 DO NOT poll. The broker pushes the resolution to you via direct-chat the moment a human approves or denies, so save the grant_id, return control, and resume when the inbound message arrives. The notification body will include an "Original conversation:" line naming the channel/thread to reply in \u2014 complete the user\'s task there, not in direct-chat. Only check notification_status if you need to flag a setup issue to the user: "sent" means a human was paged; "failed" or "not_attempted" means no human was paged (typically channel_not_found because the approval-bot is not a member of the configured channel) \u2014 quote grant_id + notification_failure_reason and recommend manual escalation. poll_grant exists as an escape hatch for explicit re-checks but the autonomous flow does not need it.',
+  "aws_request_access",
+  'Request scoped, TTL-bounded AWS credentials for the current task. agent_id and run_id are optional \u2014 the broker fills them from the host MCP env (AGT_AGENT_ID / AGT_RUN_ID). source_context is optional but you SHOULD pass it whenever the request was triggered by an inbound channel message: extract { channel_type, channel_id, thread_ts? } from the `<channel>` tag in the conversation that triggered this. Slack: channel_type="slack", channel_id=tag\'s `channel`, thread_ts=tag\'s `thread_ts`. Telegram: channel_type="telegram", channel_id=tag\'s `chat_id`. Direct-chat: channel_type="direct-chat", channel_id=tag\'s `session_id`. Without source_context the resolution notification dead-ends in your direct-chat instead of threading back to the original conversation. Returns { grant_id, status, secret_ref?, expires_at?, denial_reason?, notification_status?, notification_failure_reason? }. status="active" means credentials are ready, use them now. status="denied" means the request was rejected (denial_reason explains). status="pending" means approval is still outstanding \u2014 DO NOT poll. The broker pushes the resolution to you via direct-chat the moment a human approves or denies, so save the grant_id, return control, and resume when the inbound message arrives. The notification body will include an "Original conversation:" line naming the channel/thread to reply in \u2014 complete the user\'s task there, not in direct-chat. Only check notification_status if you need to flag a setup issue to the user: "sent" means a human was paged; "failed" or "not_attempted" means no human was paged (typically channel_not_found because the approval-bot is not a member of the configured channel) \u2014 quote grant_id + notification_failure_reason and recommend manual escalation. aws_poll_grant exists as an escape hatch for explicit re-checks but the autonomous flow does not need it.',
   requestAccessShape,
   async (args) => {
     try {
@@ -21339,8 +21334,8 @@ server.tool(
   }
 );
 server.tool(
-  "poll_grant",
-  "Single-shot status check for a grant. The broker pushes resolution updates to you via direct-chat automatically \u2014 you do NOT need to poll in the normal flow. Use this only as an escape hatch: explicit re-check after a notification, or if you suspect a notification was lost (e.g. you got `request_access` returning pending more than ~5 minutes ago and have heard nothing). Returns { grant_id, status, secret_ref?, expires_at?, denial_reason? }.",
+  "aws_poll_grant",
+  "Single-shot status check for a grant. The broker pushes resolution updates to you via direct-chat automatically \u2014 you do NOT need to poll in the normal flow. Use this only as an escape hatch: explicit re-check after a notification, or if you suspect a notification was lost (e.g. you got `aws_request_access` returning pending more than ~5 minutes ago and have heard nothing). Returns { grant_id, status, secret_ref?, expires_at?, denial_reason? }.",
   pollGrantShape,
   async (args) => {
     try {
@@ -21352,7 +21347,7 @@ server.tool(
   }
 );
 server.tool(
-  "release_access",
+  "aws_release_access",
   "Voluntarily release a grant before its TTL expires. Idempotent \u2014 safe to call on already-revoked or already-expired grants. Returns { grant_id, status }.",
   releaseAccessShape,
   async (args) => {
@@ -21365,8 +21360,8 @@ server.tool(
   }
 );
 server.tool(
-  "get_credentials",
-  "Fetch the AWS credentials for an active grant. Call this AFTER request_access returns active (auto-approve) OR after the resolution-notification arrives (route_to_approver). Returns { grant_id, expires_at, credentials: { access_key_id, secret_access_key, session_token } }. Use them by prefixing your bash invocation, e.g. `AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN=... aws ec2 describe-instances`. The grant must still be active and unexpired \u2014 409 if already released, 410 if past expires_at. Safe to call multiple times within the TTL window; the credentials don't change. Call release_access when done.",
+  "aws_get_credentials",
+  "Fetch the AWS credentials for an active grant. Call this AFTER aws_request_access returns active (auto-approve) OR after the resolution-notification arrives (route_to_approver). Returns { grant_id, expires_at, credentials: { access_key_id, secret_access_key, session_token } }. Use them by prefixing your bash invocation, e.g. `AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN=... aws ec2 describe-instances`. The grant must still be active and unexpired \u2014 409 if already released, 410 if past expires_at. Safe to call multiple times within the TTL window; the credentials don't change. Call aws_release_access when done.",
   getCredentialsShape,
   async (args) => {
     try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@integrity-labs/cloud-broker",
-  "version": "0.5.1",
-  "description": "Cloud Access Broker — MCP server that mints scoped, TTL-bounded cloud credentials per agent task. v1 ships AWS support (request_access, poll_grant, release_access, describe_scope, preview_request — STS AssumeRole under the hood); GCP, Azure, and Cloudflare land alongside in the same package as the broker grows.",
+  "version": "0.6.0",
+  "description": "Cloud Access Broker — MCP server that mints scoped, TTL-bounded cloud credentials per agent task. v1 ships AWS support (aws_request_access, aws_poll_grant, aws_release_access, aws_describe_scope, aws_preview_request, aws_get_credentials — STS AssumeRole under the hood); GCP, Azure, and Cloudflare land alongside in the same package as the broker grows.",
   "type": "module",
   "bin": {
     "cloud-broker": "./dist/index.js"