Support credential collection and browser fill through MCP

README.md

@@ -317,12 +317,13 @@ Call `get_connection_context` before deciding whether to create or select a proj
 - `manage_credentials` - Create, list, get, update, and delete stored credentials; fetch a current TOTP code for credentials with a configured totp_secret.
 - `manage_credential_providers` - Create, list, get, update, and delete external credential providers (e.g. 1Password); list available items and test the provider connection.
 - `manage_vault_provider_configs` - Create, list, get, rename, rotate secrets, and delete organization-owned Link and AgentCard configurations. Writes require organization scope.
-- `manage_vaults` - Create, list, get, and delete project-owned payment vaults.
+- `manage_vaults` - Create, list, get, and delete project-owned vaults; use one per end user.
 - `manage_vault_wallets` - Connect Kernel-managed or configured Link/AgentCard wallets, import Link grants from a trusted backend, and inspect live payment methods.
 - `manage_vault_cards` - Create or update card requests according to the API's lifecycle rules; does not implicitly authorize Link cards.
-- `manage_vault_items` - List, get, invoke advertised operations, observe events, and delete vault items. Provider approvals remain user actions; ready does not mean paid.
+- `manage_vault_credentials` - Create credential definitions for private human collection; update values or description with version and optional immutable item identity preconditions.
+- `manage_vault_items` - List, get, invoke advertised operations (including fill with value-free bindings), observe events, and delete vault items. Read credential definitions, presence, version, collection links, and explicitly non-sensitive values; sensitive values remain hidden. `collect` reopens the full form; provider approvals remain user actions. Ready is not login or payment success.
 
-See [Vault payments](docs/vault-payments.md) for both provider flows, safety rules, and response shapes. `manage_browsers` accepts creation-only `vaults` references (max 20); existing sessions and pools cannot gain vault bindings. The five vault tools share the `vaults` toolset and prepare/observe credentials rather than submitting merchant payments. They are exposed only when `GET /org/entitlements` reports `features.vaults.enabled: true` for the current credential; missing or unavailable entitlements hide them. Toolset configuration cannot override this access check. Provider configuration support uses the released `@onkernel/sdk` 0.101.0.
+See [Vault payments](docs/vault-payments.md) for both provider flows, safety rules, and response shapes. `manage_browsers` accepts creation-only `vaults` references (max 20); existing sessions and pools cannot gain vault bindings. The six vault tools share the `vaults` toolset and prepare/observe credentials rather than submitting merchant payments. They are exposed only when `GET /org/entitlements` reports `features.vaults.enabled: true` for the current credential; missing or unavailable entitlements hide them. Toolset configuration cannot override this access check. Credential create → collect → readiness → fill is supported entirely through MCP tools. `prepare_checkout` remains API/CLI-only. The SDK dependency is pinned in `bun.lock`.
 
 ### Standalone tools
 

docs/vault-payments.md

@@ -1,19 +1,111 @@
 # Vault payments
 
-The vault tools prepare and observe payment credentials. They do **not** submit
+The vault tools prepare and observe payment credentials and manage non-payment credential items. They do **not** submit
 merchant payments, expose real card values, or complete provider approval actions.
-They use the same vault API as the Kernel CLI.
+They use the same vault API as the Kernel CLI. When advertised, fill is the
+preferred browser-checkout path. The alias recipes below are for explicitly chosen
+egress-substitution integrations, not fallback after a failed or uncertain fill.
 
 **Assume real payment effects.** Mode comes from the selected provider credentials;
 there is no per-item test flag. AgentCard configuration responses report the
 introspected `test_mode`. A development or staging MCP endpoint does not make a
 card request a test transaction.
 
-Provider configuration support uses the released Node SDK 0.101.0.
+The released Node SDK dependency is pinned in `bun.lock`.
+
+## Credential collection and observation
+
+Use one vault per end user, such as `user-123`. Create credential definitions with
+`manage_vault_credentials`: use only the recognizable site name for `description`, and
+set `sensitive: false` explicitly for ordinary usernames/emails. Passwords and TOTP
+seeds must be sensitive. Payment-card data belongs in wallet/card items, not credentials.
+
+`manage_vault_items` can read existing credential items and invoke advertised `collect`.
+It returns field definitions, `has_value`, version, collection-link expiry, and
+explicitly non-sensitive text/email values. Sensitive values and TOTP seeds are
+omitted. Share the bearer collection link
+only with the intended user, outside the agent-controlled browser. Never request a
+password or TOTP seed in chat; hosted collection cannot accept TOTP seeds.
+
+Listing does not renew links; use single-item `get` or advertised `collect`.
+Collection reopens the full form without clearing values or changing version.
+`wait` observes readiness, not edits to ready items. Compare versions using `get`
+without `wait`; API updates can also change the version.
+
+For `manage_vault_credentials` updates, use the current `version`
+and `expected_item_id` when bound to an earlier read. Clearing supported required
+values returns pending collection; hosted forms still require populated inputs.
+Fill writes real values into the browser without submitting the form. It does not
+isolate them from an agent with browser access. Never retry an uncertain fill or
+fall back to payment aliases.
+
+### MCP credential flow
+
+1. Create the user's vault with `manage_vaults` (`action: "create"`, `name: "user-123"`).
+   Create a browser with `manage_browsers` and `vaults: [{"name":"user-123"}]`.
+   Vault bindings cannot be changed later. Navigate to the intended login page and inspect its inputs.
+2. Call `manage_vault_credentials` with:
+
+   ```json
+   {
+     "action": "create",
+     "vault": "user-123",
+     "key": "login",
+     "spec": {
+       "description": "Example",
+       "fields": {
+         "username": { "type": "text", "required": true, "sensitive": false },
+         "password": { "type": "password", "required": true, "sensitive": true }
+       }
+     }
+   }
+   ```
+
+   Give `item.action.url` only to the intended user. To reopen the full form later,
+   use `manage_vault_items` with `action: "invoke"` and `operation: "collect"`.
+
+3. Observe readiness with `manage_vault_items` using `action: "get"`, the same vault/key,
+   and `wait: 60`. A pending response is not permission to fill; stop until ready.
+4. Invoke `manage_vault_items` with the actual browser session ID and selectors
+   verified on that page:
+
+   ```json
+   {
+     "action": "invoke",
+     "vault": "user-123",
+     "key": "login",
+     "operation": "fill",
+     "fill": {
+       "browser_id": "browser-session-id",
+       "page_url": "https://example.com/login",
+       "fields": [
+         { "field": "username", "selector": "#username" },
+         { "field": "password", "selector": "#password" }
+       ]
+     }
+   }
+   ```
+
+   The response has a value-free `result` with ordered field outcomes. `failed` and
+   `unknown` are tool errors, not invitations to retry; fields may already be written.
+   API validation errors (400/403/404/409) retain HTTP status and recognized error codes,
+   with actionable explanations and confirmation that this request wrote no fields.
+   Inspect and correct the cause before deciding on a new fill. Transport loss and
+   other uncertain failures retain the no-retry warning. Raw upstream error bodies
+   are never returned.
+   Fill does not navigate or submit. Submit separately only after confirming the fill
+   completed and submission is authorized. TOTP bindings send only the field name;
+   the API generates each current code immediately before writing, never exposing seeds.
+
+Updates use `action: "update"`, `version`, optional `expected_item_id`, and a `spec`
+containing `description` and/or `fields: {"username":{"value":"new-name"}}`.
+Definitions cannot be changed. Never solicit secret replacement values in chat;
+prefer `collect` for human edits. Requests are not automatically retried.
+`prepare_checkout` remains API/CLI-only.
 
 ## Tools and scope
 
-The five vault tools are exposed only when the current credential's
+The six vault tools are exposed only when the current credential's
 `GET /org/entitlements` response reports `features.vaults.enabled: true`.
 Access is rechecked on every authenticated MCP request, including tool calls,
 without caching grants across requests or connections. A missing field, malformed
@@ -27,13 +119,14 @@ The `vaults` toolset configuration can further restrict access, never grant it.
 | `manage_vaults`                 | `create`, `list`, `get`, `delete`           |
 | `manage_vault_wallets`          | `create`, `payment_methods`                 |
 | `manage_vault_cards`            | `create`, `update`                          |
+| `manage_vault_credentials`      | `create`, `update`                          |
 | `manage_vault_items`            | `list`, `get`, `invoke`, `events`, `delete` |
 
 Provider configurations are organization-owned and do not accept a project
 selector. Reads are available to project-scoped credentials; writes require an
 organization-scoped connection. The API remains the authorization authority.
 
-The other four tools accept an optional `project` name or ID. Vaults are project-owned;
+The other five tools accept an optional `project` name or ID. Vaults are project-owned;
 omitting `project` uses the API's effective default project, **not** all projects.
 Project-scoped connections cannot switch projects. Use `get_connection_context`
 to inspect the connection's scope.
@@ -251,8 +344,16 @@ with `manage_vault_cards`:
 AgentCard uses `merchant`, not Link's `merchant_name`. Optionally inspect wallet
 payment methods and provide a returned `card_id`; otherwise the cardholder selects
 one at approval. AgentCard currently does not advertise `authorize`: authorization
-happens at checkout. Attach the vault to a new browser and use returned aliases.
-Observe the card for its checkout authorization and any approval URL for the user.
+happens at checkout. Eligible unused cards may instead advertise `prepare_checkout`;
+invoke it through the API or CLI with the advertised checkout context. Keep the approval
+page open, poll until `ready_to_submit`, and submit native Pay before
+`state.preparation.expires_at` (at most 30 seconds after readiness). Polling does not
+extend the deadline. Each preparation is single-use even after failure or expiry.
+MCP preserves preparation metadata but does not expose an invocation hint for it.
+
+For an explicitly chosen alias-based integration, attach the vault to a new browser
+and use returned aliases. Observe checkout authorization and approval URLs. Never
+switch to aliases after an uncertain fill or preparation.
 A reusable card remaining `ready` does not establish that the last payment succeeded.
 
 ## Observation, updates, and safety

src/lib/mcp/register.test.ts

@@ -127,6 +127,7 @@ describe("MCP toolset allowlist", () => {
           "manage_vault_provider_configs",
           "manage_vault_wallets",
           "manage_vault_cards",
+          "manage_vault_credentials",
           "manage_vault_items",
           "manage_vaults",
         ]);
@@ -193,6 +194,7 @@ describe("project selection registration", () => {
     "manage_vaults",
     "manage_vault_wallets",
     "manage_vault_cards",
+    "manage_vault_credentials",
     "manage_vault_items",
     "open_auth_login",
     "begin_auth_login",

src/lib/mcp/tool-names.ts

@@ -19,6 +19,7 @@ export const KERNEL_MCP_TOOL_NAMES = [
   "manage_proxies",
   "manage_replays",
   "manage_vault_cards",
+  "manage_vault_credentials",
   "manage_vault_items",
   "manage_vault_provider_configs",
   "manage_vault_wallets",

src/lib/mcp/tools/vault-cards.ts

@@ -18,7 +18,7 @@ export function registerVaultCardTools(
 ) {
   server.tool(
     "manage_vault_cards",
-    'Configure payment card requests, not merchant payments. Mode is determined by the wallet credentials, not a per-item test flag; never assume a test transaction. "create" creates or retrieves an identical card request by immutable key. "update" replaces requested-card specs. Pending issuance updates preserve omitted optional fields and clear explicit empty lists, only for provider-supported edits allowed by the API. Wallet/provider binding cannot change after authorization starts. Uncertain updates enter recovery_required; do not retry. Neither implicitly authorizes Link: inspect available_operations with manage_vault_items and obtain explicit user approval before invoking. AgentCard authorizes at checkout. Amounts are integer minor currency units. No card data, OAuth tokens, provider secrets, or domain configuration. Never reconfigure a card to retry a failed, timed-out, rejected, or indeterminate payment. Requests are not automatically retried.',
+    'Configure payment card requests in a per-end-user vault, not merchant payments. Use wallet/card items for credit card numbers, security codes, and expiration dates; never store that data in credential items. Mode is determined by the wallet credentials, not a per-item test flag; never assume a test transaction. "create" creates or retrieves an identical card request by immutable key. "update" replaces requested-card specs. Pending issuance updates preserve omitted optional fields and clear explicit empty lists, only for provider-supported edits allowed by the API. Wallet/provider binding cannot change after authorization starts. Uncertain updates enter recovery_required; do not retry. Neither implicitly authorizes Link: inspect available_operations with manage_vault_items and obtain explicit user approval before invoking. Eligible unused AgentCard cards advertise prepare_checkout for supported tokenization checkout; this operation requires the Kernel API, not this MCP tool. Keep the returned approval page open, poll until ready_to_submit, and submit native Pay before preparation.expires_at. Preparations are single-use, even after failure or expiry. Amounts are integer minor currency units. No card data, OAuth tokens, provider secrets, or domain configuration. Never reconfigure a card to retry a failed, timed-out, rejected, or indeterminate payment. Requests are not automatically retried.',
     vaultToolInput({
       ...vaultItemSchema,
       key: vaultKeySchema(),