wawesome 0.14.0 → 0.14.2

package/README.md

@@ -316,8 +316,8 @@ A credential carries `deploy`, reaches every App in the workspace, and expires i
 you say otherwise:
 
 ```bash
-# reads logs and cannot deploy, restricted to one App, never expires
-npx wawesome credentials mint agent -c logs:read -a prod --expires never
+# reads and runs what somebody else shipped, restricted to one App, never expires
+npx wawesome credentials mint agent -c read,logs:read,invoke -a prod --expires never
 
 # ships code and attaches the domain the project declares
 npx wawesome credentials mint ci -c deploy,domains:attach -a prod
@@ -325,14 +325,18 @@ npx wawesome credentials mint ci -c deploy,domains:attach -a prod
 
 | Flag                 | Meaning                                                                       |
 |:---------------------|:------------------------------------------------------------------------------|
-| `-c, --capability`   | `deploy`, `logs:read`, `domains:attach`, or any mix. Repeatable or comma-separated. Default `deploy` |
+| `-c, --capability`   | `deploy`, `read`, `logs:read`, `invoke`, `domains:attach`, or any mix. Repeatable or comma-separated. Default `deploy` |
 | `-a, --app`          | Restrict to these Apps, by slug. Repeatable. Default: every App in the workspace |
 | `--expires`          | Days, or `never`. Default: 90                                                   |
 
+`deploy` reaches the reads of what it writes, so a credential minted with it carries `read` as well:
+it lists the workspace, the Apps in it, the Functions in an App and their versions. The command
+prints the words the credential ended up with.
+
 An App named in a restriction does not have to exist yet. A pipeline whose first deploy creates the
-App it was minted for is the ordinary case. A restriction bounds what a credential can disturb, not
-what it can read. A Function deployed into one App still reads the whole workspace's environment at
-runtime.
+App it was minted for is the ordinary case. A restriction bounds what a credential reads as well as
+what it disturbs, and `deploy` is the hole in it: a Function deployed into an App the credential does
+reach still reads the whole workspace's environment at runtime.
 
 ### List them
 
@@ -395,6 +399,159 @@ looking in their CI settings instead of your dashboard.
 
 ---
 
+## Your agent, over MCP
+
+The same deploy credential connects a coding agent to your workspace, over MCP. Nothing to install and
+no local process to keep running: it is an endpoint on the gateway, `https://api.wawesome.io/v1/mcp`,
+and the credential is the whole of the authentication.
+
+### Install it
+
+In Claude Code, one command:
+
+```bash
+claude mcp add --transport http wawesome https://api.wawesome.io/v1/mcp \
+  --header "Authorization: Bearer wawe_..."
+```
+
+In Cursor, `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
+
+```json
+{
+  "mcpServers": {
+    "wawesome": {
+      "url": "https://api.wawesome.io/v1/mcp",
+      "headers": { "Authorization": "Bearer wawe_..." }
+    }
+  }
+}
+```
+
+In VS Code, `.vscode/mcp.json` in the workspace, or the file **MCP: Open User Configuration** opens.
+The shape is the same address and header map, under the key `servers` rather than `mcpServers`:
+
+```json
+{
+  "servers": {
+    "wawesome": {
+      "type": "http",
+      "url": "https://api.wawesome.io/v1/mcp",
+      "headers": { "Authorization": "Bearer wawe_..." }
+    }
+  }
+}
+```
+
+A file inside the project is a file your repository carries, and the secret with it. VS Code takes an
+`inputs` entry and a `${input:...}` placeholder in the header, so it asks once and holds the value
+itself. In Cursor, put the credential in `~/.cursor/mcp.json`, which is outside every repository.
+
+### Where a bearer credential reaches
+
+It works in Claude Code, the Claude Agent SDK, Cursor, VS Code, Windsurf, Zed and the Gemini CLI. It
+works in every agent framework that takes a URL and a header map, among them the OpenAI Agents SDK,
+LangChain, the Vercel AI SDK and Pydantic AI. Anything that speaks streamable HTTP MCP and lets you
+set a header can connect.
+
+Whichever protocol revision your client speaks, the endpoint answers it. It holds both eras at one
+address: the current revision, `2026-07-28`, and the three handshake-based ones the installed base is
+still on. A client ahead of your editor's next release connects, and so does one behind it.
+
+It does **not** work in the connector dialog in claude.ai or Claude Desktop, or in ChatGPT
+connectors. Those three accept "no authentication" or OAuth and have no field for a token, so there
+is nowhere to put `wawe_...`. Reaching them needs an OAuth authorization server, which the platform
+does not run today, and nothing you can configure works around that.
+
+### What your agent gets
+
+Every tool is listed for every credential, and each one names the capability it needs. A credential
+that does not carry that word is refused by name, so your agent tells you what to mint rather than
+concluding the platform cannot do it.
+
+| Tool                       | What it does                                                            | Needs         |
+|:---------------------------|:------------------------------------------------------------------------|:--------------|
+| `list_templates`           | The template catalogue, with what each one is for                       | nothing       |
+| `get_template`             | One template's files, environment contract and outbound providers        | nothing       |
+| `list_apps`                | The Apps the credential reaches, with the slug each is addressed by      | `read`        |
+| `list_functions`           | The Functions in one App, and what their live version carries            | `read`        |
+| `list_versions`            | A Function's Versions, and which one is live                             | `read`        |
+| `get_usage`                | The Tenant's usage and headroom                                          | `read`        |
+| `list_invocations`         | Recent Invocations of a Function, failures included                      | `logs:read`   |
+| `get_invocation`           | One Invocation by id                                                     | `logs:read`   |
+| `read_invocation_logs`     | An Invocation's log body, a page at a time                               | `logs:read`   |
+| `diagnose_latest_failure`  | The latest failure, its logs and the Version that ran it, in one call    | `logs:read`, `read` |
+| `deploy_function`          | Deploys code and the static files it carries                             | `deploy`      |
+| `deploy_status`            | How a deploy went, by the handle it answered with                        | `deploy`      |
+| `rollback_function`        | Puts a Version the Function already has back on its public address       | `deploy`      |
+| `set_env_var`              | Sets an App's environment variable, read at the next invocation          | `deploy`      |
+| `invoke_function`          | Runs a deployed Function once and answers with the Invocation id         | `invoke`      |
+
+A deploy is two calls. The first says which of your files the platform does not already hold, by
+content hash; your agent uploads those bytes to `PUT /v1/assets/{content_hash}` with the same
+credential and asks again, so a redeploy that changed only its code uploads nothing. The second
+answers with a handle rather than waiting for the build, because a dropped connection would otherwise
+cancel a deploy that was going fine. `deploy_status` reads the handle whenever your agent asks.
+
+When the deploy is out and something is wrong, `diagnose_latest_failure` answers the latest failed
+run of a Function, that run's log output, and the version that ran it, in one call. Mirroring the
+routes there costs four round trips and four chances to carry the wrong identifier between them.
+
+Log output comes back a page at a time, with a cursor for the next one, and nothing is held open.
+Your own `wawesome logs --follow` keeps running while your agent reads. One live tail per credential
+is all the platform permits, and an agent taking it would end yours.
+
+### Which credential for which job
+
+A credential carries the words its job needs and stops there. They are the same words
+[Deploy credentials](#mint-one) mints with.
+
+**Read and investigate, without the ability to ship.** The agent enumerates your Apps, reads
+Functions, Versions, Invocations and log bodies, diagnoses a failure, checks usage, and browses
+templates. Every tool that ships code or runs it refuses:
+
+```bash
+npx wawesome credentials mint investigator -c read,logs:read -a prod
+```
+
+**Read, investigate and run.** The same, plus `invoke_function`, so the agent can exercise a Function
+and read what it did. It still cannot deploy, roll back, or set a variable:
+
+```bash
+npx wawesome credentials mint runner -c read,logs:read,invoke -a prod
+```
+
+**The whole loop.** Deploy, run, diagnose, roll back, set a key. Every tool in the table:
+
+```bash
+npx wawesome credentials mint agent -c deploy,read,logs:read,invoke -a prod
+```
+
+Add `domains:attach` where the project declares a custom domain the deploy should claim. Nothing
+gives an agent billing, plan changes, credential management or your workspace's slug: those are
+closed to every credential, whatever it carries.
+
+Keep `-a` on all three. A credential restricted to one App is refused on every tool that names
+another, which is what stops an agent working on one client's project from touching another's.
+`get_invocation` and `read_invocation_logs` take an Invocation id rather than an App, and an id
+belonging to an App the credential cannot reach is answered as an id naming nothing. `list_apps`
+answers a set rather than one App, so it is narrowed instead of refused: the credential is listed the
+Apps it reaches and told nothing about the rest.
+
+### When a tool refuses
+
+A refusal is the tool's answer, not a protocol error, and it carries the same `reason` code the CLI
+prints:
+
+- `credential-missing-capability`. The credential does not carry a word this tool needs. The refusal
+  names it in `missing_capability`, which is the word to mint a credential with.
+- `app-outside-credential-scope`. The credential is restricted to named Apps and this is not one of
+  them. A wider capability changes nothing here.
+
+A quota refusal carries its numbers under `allowance` beside the prose, so your agent reports
+"3 of 3 App slots" rather than handing you a sentence to read.
+
+---
+
 ## Configuration and a custom gateway
 
 ### `wawesome-function.json`

package/dist/index.mjs

@@ -883,7 +883,7 @@ async function buildJs(entryInput, options) {
 * that has to name this version — `--version`, the dependency a scaffolded
 * project pins — reads it here, so a release bumps one file.
 */
-const CLI_VERSION = "0.14.0";
+const CLI_VERSION = "0.14.2";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -5519,7 +5519,7 @@ cli.command("credentials [action] [target]", "Mint, list, regenerate, revoke and
   Examples:
     wawesome credentials
     wawesome credentials mint ci-pipeline
-    wawesome credentials mint agent -c logs:read --expires never
+    wawesome credentials mint agent -c read,logs:read,invoke --expires never
     wawesome credentials mint prod-deploy -c deploy -a prod --expires 30
     wawesome credentials mint ci -c deploy,domains:attach -a prod
     wawesome credentials mint ci-pipeline > /tmp/secret
@@ -5527,8 +5527,8 @@ cli.command("credentials [action] [target]", "Mint, list, regenerate, revoke and
     wawesome credentials regenerate ci --expires never --yes
     wawesome credentials revoke ci-pipeline
     wawesome credentials revoke wawe_ab3k9x --yes
-    wawesome credentials delete ci-pipeline`).option("-c, --capability <capability>", "Capability to grant: deploy, logs:read, domains:attach (repeatable or comma-separated, default: deploy)").option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated, default: every App)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-y, --yes", "Skip the confirmation a regenerate, revoke or delete asks for").option("-v, --verbose", "Enable verbose debug output").action((action, target, options) => credentialsCommand(action, target, options));
-cli.command("credentials mint <name>", "Mint a deploy credential, printing its secret exactly once").option("-c, --capability <capability>", "Capability to grant: deploy, logs:read, domains:attach (repeatable or comma-separated)").option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-v, --verbose", "Enable verbose debug output").action((name, options) => mintCredentialCommand(name, options));
+    wawesome credentials delete ci-pipeline`).option("-c, --capability <capability>", "Capability to grant: deploy, read, logs:read, invoke, domains:attach (repeatable or comma-separated, default: deploy, which carries read)").option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated, default: every App)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-y, --yes", "Skip the confirmation a regenerate, revoke or delete asks for").option("-v, --verbose", "Enable verbose debug output").action((action, target, options) => credentialsCommand(action, target, options));
+cli.command("credentials mint <name>", "Mint a deploy credential, printing its secret exactly once").option("-c, --capability <capability>", "Capability to grant: deploy, read, logs:read, invoke, domains:attach (repeatable or comma-separated; deploy carries read)").option("-a, --app <app>", "Restrict the credential to this App (repeatable or comma-separated)").option("--expires <days|never>", "Days until the credential expires, or 'never' (default: 90)").option("-v, --verbose", "Enable verbose debug output").action((name, options) => mintCredentialCommand(name, options));
 cli.command("credentials list", "List deploy credentials, never their secrets").alias("credentials ls").option("-v, --verbose", "Enable verbose debug output").action((options) => listCredentialsCommand(options));
 cli.command("credentials regenerate <name-or-prefix>", "Replace a deploy credential's secret, keeping its name, capabilities and Apps").option("--expires <days|never>", "Days until the regenerated credential expires, or 'never' (default: 90)").option("-y, --yes", "Regenerate without being asked to confirm").option("-v, --verbose", "Enable verbose debug output").action((target, options) => regenerateCredentialCommand(target, options));
 cli.command("credentials revoke <name-or-prefix>", "Revoke a deploy credential, immediately and for good").option("-y, --yes", "Revoke without being asked to confirm").option("-v, --verbose", "Enable verbose debug output").action((target, options) => revokeCredentialCommand(target, options));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {