@integrity-labs/cloud-broker 0.6.1 → 0.6.3

package/dist/index.js

@@ -21126,12 +21126,45 @@ var BrokerClient = class {
   pollGrant(args) {
     return this.request("GET", `/aws/grants/${encodeURIComponent(args.grant_id)}`);
   }
+  /**
+   * ENG-4824: pre-flight check that the agent's Slack bot can actually
+   * post to the AWS-approval channel configured for an enrolment. Mirror
+   * of describeScope's GET-with-agent_id pattern — the API derives the
+   * enrolment row and the agent's bot token server-side, calls Slack,
+   * and returns the same shape as slack.channel_info.
+   */
+  checkApprovalChannel(args) {
+    if (!this.agentId) {
+      throw makeBrokerError(400, "BrokerClient.checkApprovalChannel requires agentId \u2014 pass it in BrokerClientConfig");
+    }
+    return this.request(
+      "GET",
+      "/aws/approval-channel-status",
+      { query: { account_id: args.account_id, agent_id: this.agentId } }
+    );
+  }
   releaseAccess(args) {
     return this.request(
       "POST",
       `/aws/grants/${encodeURIComponent(args.grant_id)}/release`
     );
   }
+  /**
+   * ENG-5013: agent-scoped inventory of enrolled AWS accounts. Called by
+   * the MCP server once at startup so the tool descriptions can name the
+   * available accounts inline — agents no longer have to ask the user
+   * for a 12-digit account_id when an alias is configured.
+   */
+  listInventory() {
+    if (!this.agentId) {
+      throw makeBrokerError(400, "BrokerClient.listInventory requires agentId \u2014 pass it in BrokerClientConfig");
+    }
+    return this.request(
+      "GET",
+      "/aws/inventory",
+      { query: { agent_id: this.agentId } }
+    );
+  }
   // ENG-4779: fetch the AWS_* credentials persisted on the grant. Pre-4779
   // there was no path back to credentials for a route_to_approver grant —
   // they were minted inside mintAndActivateGrant and never returned. Now
@@ -21144,6 +21177,24 @@ var BrokerClient = class {
   }
 };
 
+// src/inventory.ts
+var INVENTORY_RENDER_LIMIT = 20;
+function renderInventoryBlock(accounts) {
+  if (accounts.length === 0) return "";
+  const shown = accounts.slice(0, INVENTORY_RENDER_LIMIT);
+  const lines = shown.map((a) => {
+    const region = a.default_region ? ` (default region: ${a.default_region})` : "";
+    return `  - \`${a.account_id}\` \u2014 ${a.display_name}${region}`;
+  });
+  const truncated = accounts.length > INVENTORY_RENDER_LIMIT ? `
+
+  \u2026and ${accounts.length - INVENTORY_RENDER_LIMIT} more \u2014 call \`aws_describe_scope\` for any unlisted account.` : "";
+  return `
+
+Available accounts for this team (use the 12-digit account_id, NEVER invent one):
+${lines.join("\n")}${truncated}`;
+}
+
 // src/tool-schemas.ts
 var accountIdSchema = external_exports.string().regex(/^\d{12}$/, "AWS account_id must be a 12-digit string");
 var ttlSecondsSchema = external_exports.number().int().min(300, "ttl_seconds minimum is 300 (5 min)").max(3600, "ttl_seconds maximum is 3600 (60 min)").optional().describe("Requested TTL in seconds. Defaults to 900 (15 min) on the broker if omitted.");
@@ -21204,17 +21255,21 @@ var releaseAccessSchema = external_exports.object({
 var getCredentialsSchema = external_exports.object({
   grant_id: external_exports.string().uuid("grant_id must be a UUID")
 });
+var checkApprovalChannelSchema = external_exports.object({
+  account_id: accountIdSchema
+});
 var describeScopeShape = describeScopeSchema.shape;
 var previewRequestShape = previewRequestSchema.shape;
 var requestAccessShape = requestAccessSchema.shape;
 var pollGrantShape = pollGrantSchema.shape;
 var releaseAccessShape = releaseAccessSchema.shape;
 var getCredentialsShape = getCredentialsSchema.shape;
+var checkApprovalChannelShape = checkApprovalChannelSchema.shape;
 
 // package.json
 var package_default = {
   name: "@integrity-labs/cloud-broker",
-  version: "0.6.1",
+  version: "0.6.3",
   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: {
@@ -21293,9 +21348,34 @@ var server = new McpServer({
   name: "cloud-broker",
   version: package_default.version
 });
+var INVENTORY_FETCH_TIMEOUT_MS = 3e3;
+async function loadInventoryBlock() {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), INVENTORY_FETCH_TIMEOUT_MS);
+  try {
+    const result = await Promise.race([
+      broker.listInventory(),
+      new Promise((_, reject) => {
+        ctl.signal.addEventListener(
+          "abort",
+          () => reject(new Error(`aws_inventory_lookup timed out after ${INVENTORY_FETCH_TIMEOUT_MS}ms`))
+        );
+      })
+    ]);
+    return renderInventoryBlock(result.accounts);
+  } catch (err) {
+    console.error(
+      `cloud-broker: aws_inventory_lookup_failed (non-fatal \u2014 tool descriptions render account-agnostic): ${formatBrokerError(err)}`
+    );
+    return "";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var inventoryBlock = await loadInventoryBlock();
 server.tool(
   "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.",
+  "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." + inventoryBlock,
   describeScopeShape,
   async (args) => {
     try {
@@ -21319,9 +21399,26 @@ server.tool(
     }
   }
 );
+server.tool(
+  "aws_check_approval_channel",
+  `Verify the agent's Slack bot can post to the AWS-approval channel for an account BEFORE calling aws_request_access. Returns { ok, channel?, bot_user_handle?, reason? }. When ok=false, branch on reason: "channel_not_found" or "not_in_channel" \u2192 tell the user "I need to be invited to the approvals channel before I can request access \u2014 please run \`/invite @<bot_user_handle>\` in your AWS-approvals channel and let me know when done"; "archived" \u2192 tell the user the configured channel is archived and an admin needs to repoint it in Team Settings; "no_approval_channel_configured" \u2192 tell the user no approval channel is set up for this AWS account and ask them to configure one in Team Settings; "agent_slack_not_configured" \u2192 escalate to operator (you have no Slack bot at all, so /invite won't help); "auth_failed" or "unknown" \u2192 escalate to operator with raw_error. ALWAYS call this on the FIRST aws_request_access for a given account_id in a session \u2014 once you've gotten ok=true once, you can skip subsequent pre-checks. If ok=false, DO NOT call aws_request_access \u2014 surface the user-facing message above and wait. Same jargon-free, no-mechanics rules as aws_request_access: never expose "broker", "grant", "MCP", "Slack channel ID", etc to the user \u2014 talk about the AWS account and the invite action.` + inventoryBlock,
+  checkApprovalChannelShape,
+  async (args) => {
+    try {
+      const result = await broker.checkApprovalChannel(args);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatBrokerError(err) }], isError: true };
+    }
+  }
+);
 server.tool(
   "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. Post a brief, jargon-free acknowledgement to the user first (e.g. "Requesting access to the <aws_account_name> account so I can <do the task> \u2014 pinged an admin to approve, will resume the moment it lands"), then save the grant_id and return control. NEVER expose broker mechanics to the user \u2014 phrases like "firing a broker grant", "requesting a grant", "broker grant", "grant_id", "secret_ref", "STS", "AssumeRole", or any aws_* tool name must not appear in user-facing messages. Also NEVER paste the grant UUID into user-facing prose (e.g. "request c7a0b7be-5e09-\u2026 is queued") \u2014 it is operator-only metadata and reads as noise to the user. Talk about the task and the AWS account, not the plumbing. The broker pushes the resolution to you via direct-chat the moment a human approves or denies. The notification body will include an "Original conversation:" line naming the channel/thread to reply in \u2014 when it arrives, post a one-line acknowledgement there in the same jargon-free style ("Approval came through \u2014 kicking off <X> now" on active; "Request was denied: <paraphrased reason>" on denied) BEFORE calling aws_get_credentials or doing the work, then complete the user\'s task in that same channel/thread (not direct-chat). Going silent between the request and the work loses the human-in-the-loop signal. 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.',
+  // ENG-5013: append inventoryBlock so the model sees the available
+  // accounts inline with the tool that consumes account_id. This is the
+  // call site where a wrong/invented account_id would actually do harm
+  // (route to a nonexistent enrolment → 404 → confusing failure mode).
+  'Request scoped, TTL-bounded AWS credentials for the current task. CALL aws_check_approval_channel FIRST on the FIRST request for a given account_id in a session \u2014 if it returns ok=false, DO NOT call this tool, surface the invite-the-bot message instead. 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?, notification_channel_name?, notification_channel_id?, notification_permalink?, notification_bot_user_handle? }. 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. Post a brief, jargon-free acknowledgement to the user first. When notification_channel_name is populated, QUOTE IT VERBATIM in the acknowledgement (e.g. "Requesting access to the <aws_account_name> account so I can <do the task> \u2014 pinged an admin in #<notification_channel_name> to approve, will resume the moment it lands"); NEVER invent or guess a channel name from training (e.g. "#aws-approvals" is wrong if the configured channel is "#agt-approvals"). When notification_permalink is populated, you MAY append it as a markdown link (e.g. "[approval card](<notification_permalink>)") so the user can jump straight to it; otherwise omit. When notification_channel_name is absent, fall back to the channel-agnostic phrasing ("pinged an admin to approve"). Then save the grant_id and return control. NEVER expose broker mechanics to the user \u2014 phrases like "firing a broker grant", "requesting a grant", "broker grant", "grant_id", "secret_ref", "STS", "AssumeRole", or any aws_* tool name must not appear in user-facing messages. Also NEVER paste the grant UUID into user-facing prose (e.g. "request c7a0b7be-5e09-\u2026 is queued") \u2014 it is operator-only metadata and reads as noise to the user. Talk about the task and the AWS account, not the plumbing. The broker pushes the resolution to you via direct-chat the moment a human approves or denies. The notification body will include an "Original conversation:" line naming the channel/thread to reply in \u2014 when it arrives, post a one-line acknowledgement there in the same jargon-free style ("Approval came through for <aws_account_name> \u2014 kicking off <the task> now" on active; "Couldn\'t get access to <aws_account_name> for <the task>: <paraphrased reason> \u2014 let me know how you\'d like to proceed" on denied) BEFORE calling aws_get_credentials or doing the work, then complete the user\'s task in that same channel/thread (not direct-chat). Going silent between the request and the work loses the human-in-the-loop signal. 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). When notification_status is "failed" and notification_bot_user_handle + notification_channel_name are populated, name them specifically in the user message: "I queued the access request for <aws_account_name> but couldn\'t notify the approver \u2014 please run `/invite @<notification_bot_user_handle>` in #<notification_channel_name> and let me know when done so I can re-fire". When the handle/channel-name aren\'t populated, fall back to the generic version: "I couldn\'t reach an approver for the <aws_account_name> account (the approval bot isn\'t in the configured channel) \u2014 please ping an admin manually, or fix the AWS approval channel in Team Settings". Keep the user-facing text jargon-free and paraphrased. grant_id and notification_failure_reason are operator/escalation-only metadata; if and only if you are escalating to an operator, append "(reference: <grant_id>, failure: <notification_failure_reason>)" to the operator-facing escalation note. aws_poll_grant exists as an escape hatch for explicit re-checks but the autonomous flow does not need it.' + inventoryBlock,
   requestAccessShape,
   async (args) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integrity-labs/cloud-broker",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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": {