Add vault item WebMCP invoke command (#279)

## Summary

Adds CLI support for the vault `webmcp_invoke` operation, which invokes
a live WebMCP tool with values from a credential item or ready Link card
substituted into null input slots.

- Bumps `github.com/kernel/kernel-go-sdk` from v0.116.0 to v0.117.0,
which adds `WebmcpInvokeVaultItemOperationRequestParam` and the
`webmcp_invoke` result.
- New flag-based command:
  ```sh
  kernel vaults items webmcp invoke <vault> <key> \
--browser-id <session-id> --tool-ref <tool-ref> --page-url
<source.page_url> \
    --input '{"email":null,"password":null}' \
--bind email=/email --bind password=/password [--timeout-sec 1..120] [-o
json]
  ```
`--input-file <path|->` replaces `--input`. Card expiration uses `--bind
expiration:MM/YY=/pointer`.
- `kernel vaults items invoke <vault> <key> webmcp_invoke
--params/--spec-file` accepts the same request as JSON (`browser_id`,
`tool_ref`, `page_url`, `input`, `bindings[{field,input_path,format?}]`,
`timeout_sec`). Both forms go through the same `Invoke` path: the item
is fetched first, and the operation must appear in
`available_operations`. Before this change, an advertised
`webmcp_invoke` fell through to the parameterless-operation branch.
- Local validation runs before any request and never echoes payloads. It
mirrors the API's binding rules: 1-32 bindings; unique fields and paths;
each `input_path` is an RFC 6901 pointer to an existing `null` (no root,
no `-` append, canonical in-range indices, valid `~0`/`~1` escapes). It
also checks: input is a JSON object of at most 64 KiB; `tool_ref` is
non-empty and at most 128 bytes; `page_url` is absolute with no
fragment; `timeout_sec` is 1-120. Top-level input members are sent as
raw JSON so numbers are not re-encoded. The SDK encodes `json.Number` as
a string, which would change them.
- Output: `-o json` prints `type`, `status`, `invocation_id`, `output`
(raw JSON preserved) and `error_text` as returned. Human output labels
`output`/`error_text` as untrusted page data that may contain supplied
values. Both are JSON-encoded so page-supplied terminal control
characters are escaped.
- Outcomes follow existing fill/1pw_fill conventions:
- `completed` and `awaiting_submission` exit 0. `awaiting_submission`
directs the user to submit the populated form instead of re-invoking,
matching `browsers webmcp invoke`.
- `canceled`, `error` and `unknown` exit nonzero with no extra
diagnostic; the JSON result stays on stdout.
  - Requests use `WithMaxRetries(0)`.
- 400/403/404/409 errors keep the recognized code plus guidance, and
state that the tool was not invoked.
- 5xx errors, transport loss, and malformed results report that the tool
may have run, and say not to retry.
- Help text (`vaults`, `items`, `items invoke`, `items webmcp invoke`)
and README updated. Existing fill semantics are unchanged.

## Tests

`make test` (go vet + go test ./...) passes. New
`cmd/vaults_webmcp_test.go` covers:
- synthetic Resy login (`email`/`password` null slots) through both the
flag command and `items invoke ... webmcp_invoke --spec-file`, asserting
the exact request body and the JSON result, including a large integer
preserved in output
- card expiration format, nested/array/escaped pointers, and
large-number preservation in input
- 35 validation cases that make no HTTP request and don't leak payloads
- each result status in JSON and human modes, including exit codes and
escaping of control characters in `error_text`
- 400/403/409/500/502 and malformed responses, each sent exactly once
(no retry), with correct invoked-vs-uncertain guidance
- an unadvertised operation and item lookup failure, neither of which
POSTs

Not run against the live API.

---------

Co-authored-by: rgarcia <72655+rgarcia@users.noreply.github.com>

Author: rgarcia

README.md

@@ -348,6 +348,11 @@ bearer credential: share it only with that user. Readiness means required values
 populated, not that login succeeded. `fill` requires an already-open page and never
 navigates or submits it. Optional `page_url` selects the exact page; cards require it.
 Do not automatically retry failed/unknown fills or fall back to aliases.
+Once ready, use `fill` for ordinary web forms. When the item advertises `webmcp_invoke`, use
+`items webmcp invoke` instead to bind credential fields to existing `null` inputs of a live
+WebMCP tool; the tool may submit or have other side effects, so never retry an uncertain
+outcome (see [Invoke WebMCP tools with vault fields](#invoke-webmcp-tools-with-vault-fields)).
+1Password credentials use their own advertised `1pw_*` operations instead.
 
 Create specs list `fields` as an ordered array. Each entry carries a stable `name`
 (letters, digits, and underscores, starting with a letter) that keys values, updates,
@@ -399,6 +404,7 @@ cannot switch projects.
 | `kernel vaults items list <vault>` | List item keys, types, providers, status, and required actions |
 | `kernel vaults items get <vault> <key>` | Inspect state/actions/returned AgentCard aliases and copyable operation commands; `--wait 0..60`, `--expand payment_methods`, `--open` |
 | `kernel vaults items invoke <vault> <key> <operation>` | GET the item, then POST an advertised operation; `authorize --open` opens a returned HTTPS action; `prepare_checkout --params '<json>'` prepares an unused AgentCard card for Square Pay; `fill --params '<json>'` fills checkout or login fields; `collect --open` opens a credential item's hosted form |
+| `kernel vaults items webmcp invoke <vault> <key>` | Invoke a live WebMCP tool with item fields bound to null input slots; `--browser-id`, `--tool-ref`, `--page-url`, `--input`/`--input-file`, repeatable `--bind <field>=<json-pointer>`, `--timeout-sec 1..120`. Same as `items invoke <vault> <key> webmcp_invoke --params '<json>'` |
 | `kernel vaults items events <vault> <key>` | Read ordered audit events; `--after <event-id>`, `--wait 0..60` |
 | `kernel vaults items delete <vault> <key>` | Invalidate an item; `--yes` skips confirmation |
 
@@ -706,6 +712,46 @@ back to aliases. Link cards do not expose `state.aliases` or support egress subs
 AgentCard-only checkout aliases are a separate integration, not a recovery path after a failed
 or indeterminate fill.
 
+##### Invoke WebMCP tools with vault fields
+
+`webmcp_invoke` calls a live WebMCP tool with values from a credential item or ready Link card,
+when the item advertises it. Discover the tool first, then pass its opaque `tool_ref` and exact
+`source.page_url` (fragment omitted). The vault must already be attached to the browser. Put
+`null` at each input slot a vault field fills; `--input` holds only public tool arguments, never
+vault values:
+
+```bash
+kernel browsers webmcp list <browser-id> -o json
+kernel vaults items webmcp invoke user-vault resy \
+  --browser-id <browser-id> --tool-ref <tool-ref> --page-url https://resy.com/login \
+  --input '{"email":null,"password":null}' \
+  --bind email=/email --bind password=/password -o json
+```
+
+- Each `--bind <field>=<json-pointer>` maps one vault field to an RFC 6901 JSON Pointer to an existing
+  `null` in input (no root or `-` append paths; array indices must be canonical and in range). Each
+  field and path may be bound once; 1-32 bindings. Card expiration uses
+  `--bind expiration:MM/YY=/card/expiry` (or `MM/YYYY`); other fields take no format. TOTP fields
+  supply a fresh code, never the seed.
+- `--timeout-sec` is 1-120 (API default 15). Input numbers are sent unchanged; input is capped at 64 KiB.
+- The equivalent request body for `items invoke <vault> <key> webmcp_invoke --params`/`--spec-file` is
+  `{"browser_id":"...","tool_ref":"...","page_url":"...","input":{...},"bindings":[{"field":"email","input_path":"/email"}],"timeout_sec":15}`.
+
+The tool may submit forms or perform other side effects. The result returns `status`,
+`invocation_id`, `output`, and `error_text` as the API returns them; `output` and `error_text`
+are untrusted page-provided data and may contain the supplied vault values:
+
+```json
+{"type":"webmcp_invoke","status":"completed","invocation_id":"invoke-1","output":{"authenticated":true}}
+```
+
+`completed` and `awaiting_submission` exit 0; neither confirms the website accepted the action.
+After `awaiting_submission`, submit the populated form through Playwright or computer interaction
+instead of invoking the tool again. `canceled`, `error`, and `unknown` exit nonzero with the result
+still on stdout in `-o json`. `unknown` means the tool may have run. Requests are never retried:
+API rejections (400/403/404/409) mean the tool was not invoked by that request; other failures
+and transport loss are uncertain, so inspect the browser instead of re-invoking.
+
 #### Expansions, updates, and lifecycle
 
 `--expand` takes a value, such as `--expand payment_methods`; it is not a boolean switch.

cmd/browsers_webmcp.go

@@ -63,6 +63,8 @@ func (b BrowsersCmd) WebMCPList(ctx context.Context, in BrowsersWebMCPListInput)
 	return nil
 }
 
+const webMCPAwaitingSubmissionHint = "Inspect the form and obtain any required confirmation, then submit it with 'kernel browsers playwright execute' or 'kernel browsers computer' rather than invoking the tool again."
+
 func (b BrowsersCmd) WebMCPInvoke(ctx context.Context, in BrowsersWebMCPInvokeInput) error {
 	if strings.TrimSpace(in.ToolRef) == "" {
 		return fmt.Errorf("missing --tool-ref value")
@@ -94,7 +96,7 @@ func (b BrowsersCmd) WebMCPInvoke(ctx context.Context, in BrowsersWebMCPInvokeIn
 	case kernel.InvocationResultStatusAwaitingSubmission:
 		// A populated form is a result, not a failure. Re-invoking would refill the
 		// same fields, so point the caller at submitting the form they already have.
-		pterm.Warning.Printfln("WebMCP invocation %s: awaiting_submission — populated a form without submitting it. Inspect the form and obtain any required confirmation, then submit it with 'kernel browsers playwright execute' or 'kernel browsers computer' rather than invoking the tool again.", res.InvocationID)
+		pterm.Warning.Printfln("WebMCP invocation %s: awaiting_submission — populated a form without submitting it. %s", res.InvocationID, webMCPAwaitingSubmissionHint)
 	default:
 		return fmt.Errorf("WebMCP invocation %s: %s: %s", res.InvocationID, res.Status, res.ErrorText)
 	}

cmd/vaults.go

@@ -233,6 +233,9 @@ func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, par
 	if operation == "fill" && (params == nil || params.Fill == nil || open) {
 		return fmt.Errorf("fill requires --params and does not support --open")
 	}
+	if operation == "webmcp_invoke" && (params == nil || params.WebMCP == nil || open) {
+		return fmt.Errorf("webmcp_invoke requires --params and does not support --open")
+	}
 	if operation == "prepare_checkout" && (params == nil || params.Checkout == nil) {
 		return fmt.Errorf("prepare_checkout requires checkout parameters")
 	}
@@ -241,7 +244,7 @@ func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, par
 	}
 	item, err := c.vaults.Items.Get(ctx, key, kernel.VaultItemGetParams{IDOrName: vault}, option.WithMaxRetries(0))
 	if err != nil {
-		if operation == "fill" || operation == "1pw_fill" {
+		if operation == "fill" || operation == "1pw_fill" || operation == "webmcp_invoke" {
 			return vaultFillLookupError(err, operation)
 		}
 		return util.CleanedUpSdkError{Err: err}
@@ -278,6 +281,9 @@ func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, par
 	if operation == "1pw_fill" {
 		return c.onePasswordFill(ctx, vault, key, params.OnePassword, output)
 	}
+	if operation == "webmcp_invoke" {
+		return c.webMCPInvoke(ctx, vault, key, params.WebMCP, output)
+	}
 	request := kernel.VaultItemPerformOperationParams{IDOrName: vault}
 	if params != nil && params.OnePassword != nil {
 		request = *params.OnePassword

cmd/vaults_commands.go

@@ -59,14 +59,18 @@ Use wallet and card item types for credit cards and payment checkout instead.
 
 ` + vaultCredentialPathsHelp + `
 
-Kernel-hosted credential flow (fill never submits website forms):
+Kernel-hosted credential flow (fill never submits website forms; WebMCP tools may):
 1. Create a vault per end user and create a browser with --vault <id-or-name>.
 2. Navigate to a sensitive form and define its fields in natural top-to-bottom order with credentials create --spec-file; that array order controls the user-facing collection form.
 3. Present the returned collection URL to the user. Poll items get --wait 60 for ready.
-4. Use items invoke <vault> <key> fill --spec-file with browser_id and field selectors.
+4. Once ready, for ordinary web forms use items invoke <vault> <key> fill --spec-file with
+   browser_id and field selectors (writes fields without submitting). When the item
+   advertises webmcp_invoke, items webmcp invoke instead binds credential fields to existing
+   null inputs of a live WebMCP tool (the tool may submit or have side effects).
+   Never automatically retry either; inspect the browser after an uncertain outcome.
 Use credentials update --version for edits, or items invoke collect to reopen the form.
 Credential values belong in protected files/stdin, never command-line arguments.
-See credentials --help and items invoke --help for examples.
+See credentials --help, items invoke --help, and items webmcp invoke --help for examples.
 
 1Password credential flow: reuse or connect the owner's account with credentials connect,
 create a 1password credential for the site's login entries, then invoke only the
@@ -128,7 +132,7 @@ JSON output preserves returned public fields but omits unknown/opaque provider d
 	addVaultJSONOutputFlag(get)
 	cmd.AddCommand(create, list, get, newVaultDeleteCommand(false))
 
-	items := &cobra.Command{Use: "items", Short: "Inspect readiness and collection URLs, or invoke collect/fill", Long: "Use get --wait 60 to observe readiness and get -o json for schema/version/presence.\nUse invoke collect to obtain a collection URL, or invoke fill --spec-file to fill a browser.\n1Password credentials use the advertised 1pw_* operations instead of collect/fill.\nCreate and edit credentials with vaults credentials; payment items use wallets/cards."}
+	items := &cobra.Command{Use: "items", Short: "Inspect readiness and collection URLs, or invoke collect/fill/webmcp_invoke", Long: "Use get --wait 60 to observe readiness and get -o json for schema/version/presence.\nUse invoke collect to obtain a collection URL, or invoke fill --spec-file to fill a browser.\nUse webmcp invoke to call a live WebMCP tool with item fields bound to null input slots.\n1Password credentials use the advertised 1pw_* operations instead of collect/fill/webmcp_invoke.\nCreate and edit credentials with vaults credentials; payment items use wallets/cards."}
 	itemList := &cobra.Command{Use: "list <vault>", Short: "List items by vault ID or name", Args: cobra.ExactArgs(1), PreRunE: vaultPreRun,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return getVaultsHandler(cmd).ListItems(cmd.Context(), args[0], vaultOutput(cmd))
@@ -196,6 +200,17 @@ Preparations are single-use, including after failure or expiry; never retry auto
 collect/authorize/prepare_checkout/1pw_recover may use --open. Fill returns value-free per-field outcomes;
 completed exits 0, failed/unknown exit nonzero with valid JSON retained on stdout in -o json.
 
+webmcp_invoke (credential items and ready Link cards when advertised; see items webmcp invoke --help
+for the flag-based form) requires browser_id, the opaque live tool_ref and exact source.page_url
+from browsers webmcp list, input (public JSON object with a null at each bound slot; never vault
+values), and 1-32 bindings (field, input_path as an RFC 6901 JSON Pointer to an existing null in
+input; format MM/YY or MM/YYYY only for card expiration). Optional timeout_sec is 1-120 (default 15).
+The tool may submit or have other side effects. The result returns status, invocation_id, output,
+and error_text; output and error_text are untrusted page data and may contain supplied values.
+completed/awaiting_submission exit 0 without confirming site acceptance; canceled/error/unknown
+exit nonzero with JSON retained on stdout. unknown means the tool may have run: inspect the browser
+and never retry automatically. 400/403/404/409 rejections mean the tool was not invoked.
+
 1Password credentials (see credentials --help) use --params or --spec-file without type:
 1pw_create_access_request: browser_id (vault-bound session ID); optional goal (<=140),
   reason (<=100), keywords (1-5 strings); reason and keywords only for single-entry
@@ -218,6 +233,9 @@ and recreate an item to reset an uncertain outcome; stop and tell the user inste
 		Example: `  kernel vaults items invoke user-vault login collect
   kernel vaults items invoke user-vault login fill --spec-file - <<'JSON'
 {"browser_id":"<browser-id>","fields":[{"field":"username","selector":"#username"},{"field":"password","selector":"#password"}]}
+JSON
+  kernel vaults items invoke user-vault login webmcp_invoke --spec-file - <<'JSON'
+{"browser_id":"<browser-id>","tool_ref":"<tool-ref>","page_url":"https://example.com/login","input":{"email":null,"password":null},"bindings":[{"field":"email","input_path":"/email"},{"field":"password","input_path":"/password"}]}
 JSON
   kernel vaults items invoke user-vault github 1pw_create_access_request --params '{"browser_id":"<browser-id>","reason":"Sign in to GitHub"}'
   kernel vaults items invoke user-vault github 1pw_access_request_status --params '{"browser_id":"<browser-id>","timeout_seconds":60}'
@@ -233,9 +251,9 @@ JSON
 			}
 			if cmd.Flags().Changed("spec-file") {
 				if !vaultOperationTakesParams(args[2]) {
-					return fmt.Errorf("--spec-file is only supported for fill, prepare_checkout, and 1Password operations with parameters")
+					return fmt.Errorf("--spec-file is only supported for fill, webmcp_invoke, prepare_checkout, and 1Password operations with parameters")
 				}
-				data, err := readVaultSpecFile(cmd)
+				data, err := readVaultJSONFile(cmd, "spec-file")
 				if err != nil {
 					return err
 				}
@@ -247,12 +265,12 @@ JSON
 			}
 			return getVaultsHandler(cmd).Invoke(cmd.Context(), args[0], args[1], args[2], params, vaultOutput(cmd), open)
 		}}
-	invoke.Flags().String("params", "", "Operation parameters JSON for fill, prepare_checkout, or 1pw_* (maximum 128 KiB); omit type and credential values; 1pw_update_access_token requires --spec-file")
+	invoke.Flags().String("params", "", "Operation parameters JSON for fill, webmcp_invoke, prepare_checkout, or 1pw_* (maximum 128 KiB); omit type and credential values; 1pw_update_access_token requires --spec-file")
 	invoke.Flags().String("spec-file", "", "Operation parameters JSON file (use '-' for stdin; maximum 128 KiB)")
 	invoke.MarkFlagsMutuallyExclusive("params", "spec-file")
 	invoke.Flags().Bool("open", false, "Open a returned HTTPS action URL in your browser")
 	addVaultJSONOutputFlag(invoke)
-	items.AddCommand(itemList, itemGet, itemEvents, invoke, newVaultDeleteCommand(true))
+	items.AddCommand(itemList, itemGet, itemEvents, invoke, newVaultWebMCPCommand(), newVaultDeleteCommand(true))
 
 	wallets := &cobra.Command{Use: "wallets", Short: "Connect provider wallets and inspect funding methods"}
 	walletCreate := &cobra.Command{Use: "create <vault> <key> --provider <link|agentcard> --spec '<json>'", Short: "Create a wallet and display its connection or enrollment action", Args: cobra.ExactArgs(2), PreRunE: vaultPreRun,

cmd/vaults_credential_steering_test.go

@@ -40,3 +40,40 @@ func TestCredentialHelpSteering(t *testing.T) {
 	assert.Contains(t, cmd.Example, `"label":"Username"`)
 	assert.Contains(t, cmd.Example, `"sensitive":false`)
 }
+
+func TestCredentialHelpReadyOperations(t *testing.T) {
+	create, _, err := newVaultsCommand().Find([]string{"credentials", "create"})
+	require.NoError(t, err)
+	group, _, err := newVaultsCommand().Find([]string{"credentials"})
+	require.NoError(t, err)
+	items, _, err := newVaultsCommand().Find([]string{"items"})
+	require.NoError(t, err)
+	flat := func(s string) string { return strings.Join(strings.Fields(s), " ") }
+	for name, long := range map[string]string{"vaults": newVaultsCommand().Long, "credentials": group.Long, "credentials create": create.Long} {
+		t.Run(name, func(t *testing.T) {
+			text := flat(long)
+			paths := flat(vaultCredentialPathsHelp)
+			assert.Contains(t, text, paths)
+			assert.Contains(t, paths, "Once ready, items invoke fill writes them into ordinary web form fields in a vault-bound browser without submitting")
+			assert.Contains(t, paths, "When the item advertises webmcp_invoke, items webmcp invoke instead binds credential fields to existing null inputs of a live WebMCP tool; the tool may submit or have other side effects")
+			assert.Contains(t, paths, "1pw_fill fills and submits through the 1Password extension")
+			assert.Contains(t, text, "Never automatically retry")
+		})
+	}
+	text := flat(create.Long)
+	assert.Contains(t, text, "Ordinary web forms: items invoke fill writes field values without submitting")
+	assert.Contains(t, text, "Live WebMCP tool: when webmcp_invoke is advertised, run browsers webmcp list, then items webmcp invoke")
+	assert.Contains(t, text, "Never automatically retry fill or webmcp_invoke")
+	assert.Contains(t, text, "approves each access request in the 1Password app")
+
+	vaults := flat(newVaultsCommand().Long)
+	assert.Contains(t, vaults, "for ordinary web forms use items invoke <vault> <key> fill --spec-file")
+	assert.Contains(t, vaults, "When the item advertises webmcp_invoke, items webmcp invoke instead binds credential fields to existing null inputs of a live WebMCP tool (the tool may submit or have side effects)")
+	assert.Contains(t, vaults, "items webmcp invoke --help")
+	assert.Contains(t, items.Long, "1Password credentials use the advertised 1pw_* operations instead of collect/fill/webmcp_invoke")
+
+	// The 1Password path keeps its own operations and does not advertise webmcp_invoke.
+	onePassword := flat(vaultOnePasswordCredentialHelp)
+	assert.NotContains(t, onePassword, "webmcp")
+	assert.Contains(t, onePassword, "Never automatically retry an access request, fill, or recovery")
+}