From 7a3e5b46771b44bb8a6a8df192446fe1f8ac53d1 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Thu, 8 Oct 2026 16:37:11 +0000 Subject: [PATCH 1/3] Document vault login example and fix fill inputs in vault docs The vault-payments guide passed fill bindings under a top-level fill key, but manage_vault_items only reads operation inputs from inputs. Add a README example for the Kernel-hosted credential flow. Co-Authored-By: Claude Opus 5.5 --- README.md | 17 +++++++++++++++++ docs/vault-payments.md | 8 ++++---- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f7d5c71..a7e784a 100644 --- a/README.md +++ b/README.md @@ -448,6 +448,23 @@ Example: “Log me into my Hacker News account and update my profile to add a ra The secure App defaults `record_session` and `browser.telemetry.enabled` to `true`, recording replay video plus the operational telemetry categories (`control`, `connection`, `system`, and `captcha`) for managed-auth browser sessions. Callers can explicitly disable either setting. Set `browser.region` in `open_auth_login` or `manage_auth_connections` to choose where a managed-auth browser runs, and `browser.proxy` to choose its proxy by id, name, or mode. Create and update set the connection default; login and reauth overrides apply only to that flow. Omit the field on create to use `us-east`, or omit it on update and login to preserve or inherit the connection default. The programmatic `manage_auth_connections` create, update, and login actions pass the `browser` object through to the API unchanged, preserving defaults and inheritance when it is omitted. +### Fill a login from a vault + +``` +Human: Log in to github.com for user-123 with a password they enter themselves, not in chat. +Assistant: I'll check user-123's vault for a GitHub credential first. +[Uses manage_vaults with action: "create" and name: "user-123", which returns the vault if it already exists] +[Uses manage_vault_items with action: "list" on vault "user-123"; no GitHub credential exists] +Assistant: Is your GitHub login saved in your own 1Password, or would you rather enter it in a secure Kernel form? +Human: The Kernel form. +[Uses manage_vault_credentials with action: "create", provider: "kernel", and username/password field definitions] +Returns: a collection URL to share privately with the user +[Uses manage_vault_items with action: "get" and wait: 60 until the credential is ready] +[Uses manage_browsers with action: "create" and vaults: [{ "name": "user-123" }], then navigates to the login page] +[Uses manage_vault_items with action: "invoke", operation: "fill", and inputs with browser_id, page_url, and field/selector bindings] +Returns: per-field outcomes without the values. The agent submits the form and checks the page. +``` + ### Set up browser profiles for authentication ``` diff --git a/docs/vault-payments.md b/docs/vault-payments.md index 58095a1..2b5158e 100644 --- a/docs/vault-payments.md +++ b/docs/vault-payments.md @@ -97,7 +97,7 @@ failed or uncertain outcome; do not fall back to payment aliases. "vault": "user-123", "key": "login", "operation": "fill", - "fill": { + "inputs": { "browser_id": "browser-session-id", "page_url": "https://example.com/login", "fields": [ @@ -427,7 +427,7 @@ credentials. A reused `user_id` must belong to the same organization and config. The tool fetches the item again and submits only a currently advertised operation. `authorize` has no additional parameters: its API body is `{"type":"authorize"}`. This does not apply to `fill`, which requires the nested - MCP parameters below. Follow any returned provider action and observe state. + `inputs` object below. Follow any returned provider action and observe state. OAuth, enrollment, MFA, and approval actions are for the user, not operation names. 6. When ready, create a new browser with `manage_browsers`: @@ -456,7 +456,7 @@ credentials. A reused `user_id` must belong to the same organization and config. "vault": "checkout", "key": "order-1", "operation": "fill", - "fill": { + "inputs": { "browser_id": "browser-session-id", "page_url": "https://shop.example/checkout", "fields": [ @@ -469,7 +469,7 @@ credentials. A reused `user_id` must belong to the same organization and config. } ``` - `fill` is a nested MCP input object, not a top-level set of API parameters. + Fill parameters go in the nested `inputs` object, not at the top level. `fields` contains bindings, never card values. Each selector must resolve to one unique editable target across all frames. For separate expiration inputs, use `exp_month` (MM) and `exp_year` (YYYY) without `format`. Only combined From b93a2c45d20ca4da363fea53ce00d50c8e38586f Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Thu, 8 Oct 2026 17:08:47 +0000 Subject: [PATCH 2/3] Note that vault fill is safe to retry in README example Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a7e784a..c41c7a5 100644 --- a/README.md +++ b/README.md @@ -462,7 +462,7 @@ Returns: a collection URL to share privately with the user [Uses manage_vault_items with action: "get" and wait: 60 until the credential is ready] [Uses manage_browsers with action: "create" and vaults: [{ "name": "user-123" }], then navigates to the login page] [Uses manage_vault_items with action: "invoke", operation: "fill", and inputs with browser_id, page_url, and field/selector bindings] -Returns: per-field outcomes without the values. The agent submits the form and checks the page. +Returns: per-field outcomes without the values. Fill never submits, so the agent retries it if it fails, then submits the form and checks the page. ``` ### Set up browser profiles for authentication From a1e51295740647885a2acffda1819e4c63133f87 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Thu, 8 Oct 2026 17:10:19 +0000 Subject: [PATCH 3/3] Describe browserless 1Password access requests in vault guide Access request create and status no longer take a browser; only 1pw_fill needs a vault-attached browser. Co-Authored-By: Claude Opus 5.5 --- docs/vault-payments.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/vault-payments.md b/docs/vault-payments.md index 2b5158e..dde1a3c 100644 --- a/docs/vault-payments.md +++ b/docs/vault-payments.md @@ -197,12 +197,10 @@ passkeys; use Kernel-hosted collection for those, or when the user declines the account owner. 1Password credentials store no values or selectors and cannot be updated. -3. Create a browser with the vault attached before asking the owner to approve - anything: the approval link exists only after this request. After explicit user - approval, invoke the advertised `1pw_create_access_request` with - `inputs: {"browser_id": "..."}`. - Kernel loads the 1Password extension into that browser on demand. Request-time - `reason` and `keywords` apply only to a single-login credential. +3. After explicit user approval, invoke the advertised `1pw_create_access_request` + with an optional `goal`. Kernel creates the request with 1Password directly, so it + needs no browser, and the approval link exists only after this request. + Request-time `reason` and `keywords` apply only to a single-login credential. 4. Approval is a human action in the account owner's 1Password app. The pending item returns `action: {"name": "1password_access_approval", "url": "onepassword://grant-brokered-access?access_request_reference=..."}`. Give that link, unmodified, only to the account owner in a private surface outside @@ -210,8 +208,8 @@ passkeys; use Kernel-hosted collection for those, or when the user declines choose, approve, or deny the login there. The link grants nothing until they approve, but it identifies the request, so the agent must never open, decode, or approve it. MCP forwards only links in that exact native form, without the API's - free-text instructions. Invoke the advertised `1pw_access_request_status` with - `browser_id` to observe the decision; it only reads status, so its hint has + free-text instructions. Invoke the advertised `1pw_access_request_status` without + a browser to observe the decision; it only reads status, so its hint has `requires_user_approval: false`. - `declined`: the owner denied the request. Do not request again unless they ask; offer Kernel-hosted collection. @@ -221,8 +219,10 @@ passkeys; use Kernel-hosted collection for those, or when the user declines the `credential_account` named by `spec.account` is connected. If it is, a request may already have reached 1Password. There is no reset: stop, ask the owner to check 1Password, and never delete or recreate the item to retry. -5. When the item is ready, invoke the advertised `1pw_fill` with `browser_id` and the - exact current `page_url`. When several approved logins share the page origin, ask +5. When the item is ready, create a browser with the vault attached and navigate to + the login page. Invoke the advertised `1pw_fill` with that `browser_id` and the + exact current `page_url`; Kernel loads the 1Password extension into the browser + on demand. When several approved logins share the page origin, ask the owner which one to use and pass its `entry_id` from `state.access_request` entries. The extension selects fields and submits the form. `fill_submitted` means the form was submitted, not that login succeeded, so check the page.