@bnbagent/studio-cli 0.0.13-alpha.1 → 0.0.13-alpha.3

package/skills/references/bnbagent-studio-use-azure-foundry.md

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio-use-azure-foundry
-description: When the user wants to deploy or operate a bnbagent-studio project on Azure AI Foundry Hosted Agents - scaffold with `bag init --runtime azure-foundry`, deploy either to the managed platform with `bag deploy --provider bnb --backend azure` or directly with `bag deploy --provider azure`; all cloud lifecycle execution is delegated to pinned `@bnbagent/deploy-cli@0.5.13`. Native MCP is not supported on Azure; use AgentCore for MCP.
+description: When the user wants to deploy or operate a bnbagent-studio project on Azure AI Foundry Hosted Agents - scaffold with `bag init --runtime azure-foundry`, deploy either to the managed platform with `bag deploy --provider bnb --backend azure` or directly with `bag deploy --provider azure`; all cloud lifecycle execution is delegated to pinned `@bnbagent/deploy-cli@0.5.15`. Native MCP is not supported on Azure; use AgentCore for MCP.
 ---
 
 > **Reference file** of the `bnbagent-studio` router skill - installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
@@ -16,14 +16,14 @@ Procedure for deploying and operating the seller Agent on **Azure AI Foundry Hos
 ```
 <workspace>/
 ├── app/agent/             # the deployed code (src/unifiedMain.ts host + Dockerfile here)
-│   ├── studio.toml        # [azure] block: location / subscription_id / account_name / subdomain / project_name / agent_endpoint
+│   ├── studio.toml        # [azure] resources plus named HTTP/A2A/Invocations endpoint records
 │   └── Dockerfile         # the container image bnbagent-deploy builds + pushes
 └── .studio/               # secrets + wallets (workspace root - never in the image)
 ```
 
 > **Deploy model: CONTAINER-ONLY.** The deploy-cli Azure provider rejects Node zip artifacts, so every azure-foundry deploy builds the scaffolded `app/agent/Dockerfile` **locally with Docker** (linux/amd64) and pushes it to the auto-provisioned Azure Container Registry; Foundry Agent Service pulls and runs the image. A running Docker daemon is required.
 
-> **Protocol:** A2A, X402-only, and A2A+X402 projects are supported. The deployed Node host speaks both Foundry container contracts on `:8088`: `GET /readiness`, pass-through `POST /invocations` for user-owned Azure, and OpenAI-compatible `POST /responses` for managed incoming A2A. Neither endpoint is native MCP streamable HTTP; `bag init` and provider selection reject azure-foundry + MCP instead of deploying a container that can never become ready.
+> **Protocol:** A2A, X402-only, and A2A+X402 projects are supported. The deployed Node host speaks both Foundry container contracts on `:8088`: `GET /readiness`, pass-through `POST /invocations`, and OpenAI-compatible `POST /responses`; new direct A2A deploys also enable native incoming A2A. None of these endpoints is native MCP streamable HTTP, so `bag init` and provider selection reject azure-foundry + MCP.
 
 > **Auth is explicit.** User-owned Azure needs a saved delegated browser sign-in, or an ambient Azure credential chain in CI. Deployment itself never shells out to `az` or `azd`, and a non-interactive deploy cannot open a browser.
 
@@ -31,7 +31,7 @@ Procedure for deploying and operating the seller Agent on **Azure AI Foundry Hos
 
 1. **Bun 1.3+ (`bunx`) on PATH** - the pinned `@bnbagent/deploy-cli` runs through it.
 2. **Docker running** - the image is built locally (linux/amd64) before push.
-3. **An Azure subscription** the operator may provision in (Foundry account/project, container registry, hosted agent). Before a local self-deploy, run `bunx --bun @bnbagent/deploy-cli@0.5.13 login --provider azure`; use OIDC/service-principal credentials in CI.
+3. **An Azure subscription** the operator may provision in (Foundry account/project, container registry, hosted agent). Before a local self-deploy, run `bunx --bun @bnbagent/deploy-cli@0.5.15 login --provider azure`; use OIDC/service-principal credentials in CI.
 
 ## ⚠️ Foundry gotchas (read before deploying)
 
@@ -49,7 +49,7 @@ Procedure for deploying and operating the seller Agent on **Azure AI Foundry Hos
 
 > The encrypted keystore (`.studio/wallets/`) stays at the workspace root and rides only that secret channel - never baked into the image.
 
-Provider-native overrides go in the optional `studio.toml [deploy.foundry]` table (verbatim deploy-spec keys; deploy-cli 0.5.13 consumes `account`, `cpu`, `location`, `memory`, `project`, `projectEndpoint`, `protocol`, `registry`, `subscriptionId` and warns about anything else). The `[azure]` block's `subscription_id` / `account_name` / `project_name` / `project_endpoint` / `location` win over conflicting `[deploy.foundry]` keys.
+Provider-native overrides go in the optional `studio.toml [deploy.foundry]` table (verbatim deploy-spec keys; deploy-cli 0.5.14 consumes `account`, `cpu`, `incomingA2a`, `agentCard`, `location`, `memory`, `project`, `projectEndpoint`, `protocol`, `rawInvocations`, `registry`, and `subscriptionId`, and warns about anything else). The `[azure]` block's `subscription_id` / `account_name` / `project_name` / `project_endpoint` / `location` win over conflicting `[deploy.foundry]` keys.
 
 ## Typical workflow
 
@@ -72,7 +72,13 @@ bag deploy prepare --runtime azure-foundry   # local readiness gate (region/subd
 bag deploy --provider azure                  # delegated: onboard → build+push → CustomKeys → deploy [--smoke]
 ```
 
-`bag deploy --provider azure` runs an HTTP contract smoke by default (pass `--skip-smoke` to omit it) and captures the Foundry endpoint into `app/agent/studio.toml [azure].agent_endpoint`. If Foundry creates the resource but that post-create check fails, Studio still records the discovered endpoint so `status`, `logs`, and `destroy` can manage the resource; the deploy command continues to return non-zero.
+`bag deploy --provider azure` runs an HTTP contract smoke by default (pass `--skip-smoke` to omit it), enables incoming A2A, and captures `[azure].http_endpoint`, `a2a_endpoint`, and `agent_card_endpoint`. When X402 is selected it also declares and records `[azure].invocations_endpoint` for the operator's authenticated envelope tunnel. `[azure].agent_endpoint` remains the compatibility primary and points to A2A for new deployments. If Foundry creates the resource but a post-create check fails, Studio still records discovered endpoints so `status`, `logs`, and `destroy` can manage it; the deploy command continues to return non-zero.
+
+For a first deploy in non-interactive automation, pass `--yes`. Studio treats
+that as confirmation of the full deployment plan and delegates explicit
+Foundry project onboarding. Configure `[azure].subscription_id` and
+`account_name` when several candidates are accessible so no prompt or guess is
+required.
 
 For a first deploy in non-interactive automation, pass `--yes`. Studio treats
 that as confirmation of the full deployment plan and delegates explicit
@@ -88,10 +94,7 @@ bag deploy info --provider azure --with-curl # endpoint + Entra token shortcut +
 bag deploy logs --provider azure --limit 50 # delegated Hosted Agent logs
 ```
 
-`bag deploy info --provider azure` reads the recorded Azure endpoint without recreating the
-temporary deploy spec. `--with-curl` adds an optional `az account
-get-access-token --resource https://ai.azure.com` shortcut and a complete
-Invocations request. This does not make the Azure CLI a deploy prerequisite;
+`bag deploy info` reads the recorded named Azure endpoints without recreating the temporary deploy spec. `--with-curl` adds an optional `az account get-access-token --resource https://ai.azure.com` shortcut and complete Responses HTTP, Agent Card, and A2A requests. This does not make the Azure CLI a deploy prerequisite;
 application clients may mint the same `https://ai.azure.com/.default` scope
 with `DefaultAzureCredential` or `ClientSecretCredential`.
 
@@ -102,7 +105,34 @@ session, logs lists the recent sessions visible to the current Azure identity.
 Foundry scopes that list by identity/isolation key, so an external buyer or
 gateway must still preserve the session header from its own response.
 
-The built-in smoke proves the container contract, not the seller signature. For a release E2E, invoke with a complete `negotiate` envelope and require `response.accepted=true`, a non-empty `negotiation_hash`, and `provider_sig`. The Invocations body is `{"input":"<serialized skill JSON>"}`.
+The built-in smoke proves the container contract, not the seller signature. For a release E2E, POST A2A JSON-RPC `message/send` to the recorded A2A endpoint with `A2A-Version: 1.0`, or use the Responses/Invocations contract selected for the deployment. Require `response.accepted=true`, a non-empty `negotiation_hash`, and `provider_sig`.
+
+### X402 external gateway
+
+Foundry does not expose a raw anonymous `/x402` URL. An operator-run HTTPS
+gateway authenticates to the recorded Invocations endpoint with an Entra token
+for `https://ai.azure.com/.default`, wraps the incoming HTTP request as
+`http-envelope-v1`, and unwraps the returned inner status, headers, and base64
+body:
+
+```json
+{
+  "v": 1,
+  "method": "POST",
+  "path": "/x402",
+  "query": {},
+  "headers": { "content-type": "application/json" },
+  "body": "<base64-encoded request body>"
+}
+```
+
+`bag deploy info --provider azure --json` reports the deployed face snapshot,
+seller state, carrier contract, and a request example. In FREE mode that
+example executes seller work without a payment; in PAID mode it returns the
+inner 402 before work until a valid payment is supplied. A PAID seller also
+needs fixed facilitator egress; use an Azure Container Apps workload-profiles
+environment with VNet integration and a NAT Gateway static IP, then allowlist
+that IP with B402. Studio does not deploy or manage the gateway or network.
 
 ### X402 external gateway
 
@@ -148,8 +178,8 @@ a registry proven to be owned by bnbagent-deploy. External registry overrides,
 untagged registries, and registries shared by another Foundry project are kept.
 `--purge` also removes the retained resources the deploy record tracks -
 including the soft-deleted Cognitive Services account, freeing the custom
-subdomain immediately (otherwise held ~48h). A successful teardown clears the
-recorded `[azure].agent_endpoint`.
+subdomain immediately (otherwise held ~48h). A successful teardown clears all
+recorded `[azure]` endpoints.
 
 ## Scope note
 
@@ -158,6 +188,6 @@ Azure Foundry is an alternate runtime for the whole seller agent. There is no se
 ## Reference
 
 - `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
-- `app/agent/studio.toml [azure]` - location / subscription_id / account_name / subdomain / project_name / agent_endpoint
+- `app/agent/studio.toml [azure]` - resource configuration plus `http_endpoint` / `invocations_endpoint` / `a2a_endpoint` / `agent_card_endpoint`
 - `app/agent/studio.toml [deploy.foundry]` - provider-native deploy-spec passthrough
 - `BNBAGENT_DEPLOY_COMMAND` - override the pinned `bunx --bun @bnbagent/deploy-cli@<pin>` invocation (E2E/dev)

package/skills/references/bnbagent-studio-use-bnb-trial.md

@@ -9,7 +9,7 @@ description: Use when deploying or operating a bnbagent-studio seller on the BNB
 
 Treat this provider as a temporary testnet sandbox. Require a throwaway wallet, keep `bsc-testnet`, and explain that the runtime signing material is transmitted to the operator's managed secret store for the trial. Never use a mainnet key. Exception: `wallet.kind='altana'` ships only the bounded, budget-limited, revocable session - the throwaway-wallet advice does not apply; tighten the session instead (`bag wallet session grant --force --budget-u <small> --expiry-days <short>`) and never run `bag wallet new` on an altana project (it breaks the session's `[wallet].address` anchor).
 
-All auth and cloud lifecycle work must cross the pinned `@bnbagent/deploy-cli@0.5.13` boundary. Do not call a cloud CLI or platform REST routes directly. The managed backend is recipe-derived: `agentcore` uses AWS; `azure-foundry` uses Azure. For headless managed Azure, confirm with `bag deploy --provider bnb --backend azure --yes`; never treat `--backend` as a cross-cloud recipe converter.
+All auth and cloud lifecycle work must cross the pinned `@bnbagent/deploy-cli@0.5.15` boundary. Do not call a cloud CLI or platform REST routes directly. The managed backend is recipe-derived: `agentcore` uses AWS; `azure-foundry` uses Azure. For headless managed Azure, confirm with `bag deploy --provider bnb --backend azure --yes`; never treat `--backend` as a cross-cloud recipe converter.
 
 ## Select and authenticate
 
@@ -18,9 +18,16 @@ Run:
 ```bash
 bag platform login
 bag platform credit
+bag deploy prepare --provider bnb --backend aws
 bag deploy --provider bnb
 ```
 
+For an `azure-foundry` recipe, use
+`bag deploy prepare --provider bnb --backend azure` followed by
+`bag deploy --provider bnb --backend azure --yes`. The explicit Platform
+prepare target must accept `[storage].kind='local'`: the API supplies managed
+S3/Blob storage and Studio must not require or forward BYOS credentials.
+
 `bag platform login` must print the GitHub verification URL and device code. It must not open a browser. Give both values to the user and wait for them to complete verification.
 
 Before offering BNB, inspect the trial result:
@@ -46,14 +53,14 @@ bag deploy destroy --provider bnb --execute # destructive confirmation
 
 `status` lists every recorded provider and includes the live trial countdown. Use `--no-probe` only when local records are desired. With multiple deployments, logs/verify/destroy must select a provider interactively or pass `--provider`.
 
-Destroy clears only the BNB lifecycle record after the delegated delete succeeds. It does not delete the local keystore or the on-chain ERC-8004 identity. Destroyed BNB slugs are retired; choose a fresh slug before redeploy.
+Destroy clears the BNB lifecycle record after the delegated delete succeeds. The Agent's managed deliverables share that lifecycle: deletion removes them and their `bnbagent-api` URLs eventually return 404. It does not delete the local keystore or the on-chain ERC-8004 identity. Destroyed BNB slugs are retired; choose a fresh slug before redeploy.
 
 ## Manual staging verification
 
 Use the staging endpoint only for the current shell:
 
 ```bash
-export BNBAGENT_API_URL=https://bnbagent-api.fe.kfkshore.org
+export BNBAGENT_API_URL=https://bnbagent-api-staging.bnbchain.world
 bag platform login
 bag platform credit
 bag deploy --provider bnb

package/skills/references/bnbagent-studio-using-altana-wallet.md

@@ -48,7 +48,7 @@ x402 buying remains separate and exact-bounded:
 bag wallet session x402-setup --allowance-u <U> --yes
 ```
 
-Once armed, `bag x402 buy` pays b402-facilitated merchants (e.g. CoinMarketCap) end to end: B402 verifies the session's ERC-1271 signature on its **permit2 rails** (live since 2026-08). Studio's own b402 sellers advertise `permit2-exact` alongside `eip3009`, so Altana wallets can pay studio-hosted merchants too; eip3009-only merchants still need a 65-byte EOA signature and cannot be paid by a smart account. The buy preflight checks the U→Permit2 allowance against the spend cap, and `bag doctor` reports `[wallet] Altana x402 buying`. Use `@altananetwork/sdk` 0.7.1 in the project.
+Once armed, `bag x402 buy` pays b402-facilitated merchants (e.g. CoinMarketCap) end to end: B402 verifies the session's ERC-1271 signature on its **permit2 rails** (live since 2026-08 in production and, since 2026-08-20, in the QA/testnet environment). Studio's own b402 sellers advertise `permit2-exact` alongside `eip3009`, so Altana wallets can pay studio-hosted merchants too; eip3009-only merchants still need a 65-byte EOA signature and cannot be paid by a smart account. The buy preflight checks the U→Permit2 allowance against the spend cap, and `bag doctor` reports `[wallet] Altana x402 buying`. Use `@altananetwork/sdk` 0.7.1 in the project.
 
 Altana can also be the b402 **seller** payout wallet for a positive price: the payout lands at `[wallet].address`, which for an EIP-7702 altana account is the admin EOA, so the locally-held admin keystore can always move the revenue. Issue the B402 merchant credentials for that exact address. Explicit `price_usd = "0"` stays FREE passthrough (no payout, bypasses B402). The outbound buying authority above remains a separate feature.