@trusty-squire/mcp 1.1.16-rc.3 → 1.1.16-rc.5

package/README.md

@@ -85,9 +85,9 @@ operator does not add a broad secret scanner or claim to defeat that page.
 npx @trusty-squire/mcp connect
 ```
 
-`connect` signs you in with Google or GitHub, detects your coding agent, and merges the `squire` MCP server into its existing configuration. On an enrolled machine, sign-in opens a tab in Trusty Squire's shared browser. Its private Linux display is shown through a single-use noVNC URL printed during the ceremony; open that URL on another device. The URL shows and controls the whole shared browser display, including other sessions' tabs, until the ceremony ends. The shared-browser path has no macOS or Windows local-window exposure today; if the display cannot be shown, connect stops with an explanation instead of waiting indefinitely. On a first connect where no broker can serve, connect launches its own sign-in browser, using a visible desktop when available or a login-scoped Xvfb + noVNC stack on headless Linux (including SSH/TTY sessions with an inherited virtual display).
+`connect` signs you in with Google or GitHub, detects your coding agent, and merges the `squire` MCP server into its existing configuration. On an enrolled machine, sign-in opens a tab in Trusty Squire's shared browser. When that browser is on the machine's own screen and you are running `connect` there, you finish sign-in in the window in front of you — no URL and no virtual display. Otherwise — the shared browser started without a screen and sits on a private Linux display, or you are running `connect` over SSH or a TTY with no screen of your own — the ceremony prints a single-use noVNC URL; open that URL on another device. The URL shows and controls the whole display that browser runs on until the ceremony ends: other sessions' tabs, and on a machine with its own screen, everything else on that screen. macOS and Windows draw their windows natively, so the shared browser's tab is on the screen in front of you there and nothing is exposed over noVNC. If the display cannot be shown, connect stops with an explanation instead of waiting indefinitely. On a first connect where no broker can serve, connect launches its own sign-in browser, using a visible desktop when one still answers or a login-scoped Xvfb + noVNC stack on headless Linux (including SSH/TTY sessions with an inherited virtual display, and a display that has stopped answering since startup).
 
-Ceremony completion, timeout, failure, or interruption tears down its quick tunnel and local exposure helpers. The shared browser and its display remain with the broker; a self-launched ceremony also closes its own browser and display. Operators may set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel, which Trusty Squire never creates or stops. If that fixed local port is busy, login reports it and uses a one-off quick tunnel instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.
+Ceremony completion, timeout, failure, or interruption tears down its quick tunnel and local exposure helpers. Those helpers also hold a bound of their own — the sign-in link's lifetime plus a short grace, counted from the moment they are stood up — so a `connect` that is abandoned, wedged, or never waits still tears the display down and exits non-zero instead of leaving a tunnel published. The shared browser and its display remain with the broker; a self-launched ceremony also closes its own browser and display. Operators may set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel, which Trusty Squire never creates or stops. If that fixed local port is busy, login reports it and uses a one-off quick tunnel instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.
 
 `connect` is also the only way to sign in again: `--force-relogin` switches the bound account and `--force-relogin=google` or `--force-relogin=github` refreshes one provider session. It re-checks provider sessions before reporting success; when the shared browser keeps the profile busy, that check uses committed cookies, which can outlive a server-side session. Use `--force-relogin` to refresh a stale session. The detailed [provider-probe and ceremony contract](docs/browser-broker.md) describes completion and failure handling.
 
@@ -104,6 +104,31 @@ To choose a target explicitly:
 npx @trusty-squire/mcp connect --target=codex
 ```
 
+Callers that must not parse English can pass `--json`. Connect then writes **newline-delimited JSON** to stdout: one complete, self-sufficient report per line, written whenever the run's answer changes, and the last line carries `"terminal": true`. Read lines, not prose — connect blocks for minutes waiting on a human, and the line that names the live sign-in URL goes out *before* that wait begins rather than after it. Human output stays on stderr, and `--json` implies `--no-interactive` so the picker never draws on the machine channel. A first-time install has no MCP session yet, so this flag is the machine contract — not a server tool.
+
+```bash
+npx @trusty-squire/mcp connect --json --target=codex
+```
+
+Every exit path answers, including a run that fails before it resolves a target, so the machine channel is never empty and always ends. Each line is a connect report (it carries `state`) unless connect refused the arguments, in which case the one line is `{"error":"usage","message":"…"}` and the exit code is 64 — a rejected flag is not a connection state.
+
+Each report carries seven fields:
+
+- `terminal` — `false` while the run is still going, `true` on the line that ends it. Exactly one line per run is terminal, and it is the last one.
+
+- `state` — one of four:
+  - `connected` — the bot's Chrome profile carries a Google session bound to your account. `account` is set. `reason: null` means a post-ceremony provider probe said so; `reason: "cached_cookie_evidence"` means the no-ceremony fast path read the profile's cookie store and opened nothing, so the session is present but not proven live.
+  - `needs-sign-in` — a sign-in is outstanding **and Squire holds its live URL**. `sign_in_url` is always a string here; this is the only state that promises one. Non-terminal lines in this state are how a caller gets that URL, and the browser's placement, while both still reach something.
+  - `busy` — Squire could not read or use the bot profile to answer, including a ceremony refused because another session holds the browser (the profile gate's refusal, or a resident broker declining to yield). `holder` says who has it. A broker that died mid-ceremony is not this — that is the run failing, and it reports `no-browser` with `reason: "run_failed"`.
+  - `no-browser` — no browser here is signed in the way this install needs. `reason` names the cause: the sign-in happened outside Squire's browser or the ceremony ended without the session the operator needs (`provider_session_missing`), the scoped provider refresh you asked for did not land (`requested_provider_missing`), the sign-in returned a different account (`account_mismatch`), the link lapsed (`install_expired`), or the run failed before it could settle (`run_failed`). The one cause with `reason: null` — "nothing here could be shown the page" — is named by `browser_location: {kind:"unreachable"}` instead.
+- `sign_in_url` — the one sign-in URL, or `null`. Always a string when `state` is `needs-sign-in`; a `no-browser` run may also carry one when the install is still open but nothing here could show it.
+- `account` — `{ id, providers }` whenever the run proved which account this machine is bound to, which is not only when it ends `connected`: a `no-browser` run whose provider session or scoped refresh missed, and a `busy` run whose stored session names an account, both carry it. `null` when the run never proved a binding. `account.providers` lists only the provider sessions actually observed: `[]` means the profile was read and held none, and `null` means the probe could not read it at all — so treat `null` as "unknown", never as "none".
+- `holder` — who holds the bot profile, as read: `{kind:"none"}`, `{kind:"other",code:"singleton_lock"|"operation_lease",pid}`, or `{kind:"unknown",reason:"cross_host"}`. `singleton_lock` is a live Chrome on the profile that this run did not launch — its own ceremony window is never reported as a holder; `operation_lease` is another Squire run that claimed it for work (a `--force-relogin` wipe holds the lease with no browser running). A lock left behind by a dead process is `none`, not a holder, and `busy` with `holder:{kind:"none"}` means nothing holds the profile — Squire just could not verify it (see `reason`).
+- `browser_location` — where the ceremony browser actually opened, reported by the code that placed it: `{kind:"host_screen",display?}` (the screen you are at), `{kind:"virtual",url}` (a display nobody is sitting at — `url` is the noVNC address that reaches it, reported on a non-terminal line the moment the browser lands there, while the tunnel is up), `{kind:"unreachable",reason}` (nothing here could be shown the page — also the answer when a ceremony ran but no path ever reported a placement, with `reason` naming the failure), `{kind:"none"}` (no browser was opened), or `{kind:"unknown",reason}` (a browser opened that Squire did not place — `--skip-browser` hands the link to the machine's default browser). Squire decides this; callers do not detect screens.
+- `reason` — only what the five fields above cannot say: `provider_session_missing`, `requested_provider_missing`, `account_mismatch`, `profile_unverifiable`, `install_expired`, `cached_cookie_evidence`, `run_failed`. `null` otherwise.
+
+Connect never waits longer than the sign-in link lives — the wait is the link's lifetime counted from the moment connect received it, so a skewed machine clock cannot shorten or overrun it. A `sign_in_url` it hands back is still open; a wait that reached that deadline, or a link the server reported lapsed, is `no-browser` with `reason: "install_expired"` and no URL at all. A ceremony display that outlives its own bound answers the same way, on a terminal line written before connect exits — so a run that wedged before it ever reached that wait still ends the machine channel.
+
 Supported targets: `claude-code`, `cursor`, `codex`, `opencode`, `goose`, `cline`, `continue`, and `hermes`.
 
 The isolated `operate_*` browser runtime currently requires Linux and a local Chrome connection;
@@ -165,6 +190,12 @@ grant; host scoping, auditing, and revocation still apply. When a grant reaches
 an explicit hourly limit, the proxy returns `429 rate_limited` with
 `scope: "grant"`, `Retry-After`, and window/reset metadata.
 
+The proxy passes the provider's response through as it arrives and forwards the
+upstream response headers (cookies, hop-by-hop headers, and the upstream
+content-length removed), so a streaming completion — `stream: true`,
+`text/event-stream` — reaches the app event by event rather than in one block
+once generation has finished. The body is not buffered and carries no size cap.
+
 The result contains a host-scoped egress `base_url` and a `token`, not the Clerk secret key. The token is returned once through the MCP result and remains valid until revoked. That means the scoped grant token can enter agent context; it is not the provider key. Move it directly into backend-only deployment secret storage, never browser code, logs, or source control. If you need zero grant-token exposure to the model, use `use_credential` for agent-initiated requests instead. Trusty Squire removes the grant authorization at the boundary and injects the vaulted provider credential into the upstream request.
 
 ## Security and threat model
@@ -198,15 +229,9 @@ for the system and data flows.
 
 ## MCP tools
 
-The default MCP registry exposes 29 tools (31 when maintainer diagnostics are
-enabled). The 20-tool operator driving surface uses flat, single-purpose verbs:
-`operate_start`, `operate_finish`, `operate_observe`, `operate_screenshot`,
-`operate_network`, `operate_navigate`, `operate_click`, `operate_type`, `operate_select`,
-`operate_press`, `operate_scroll`, `operate_wait`, `operate_read_inbox`, `operate_login`,
-`operate_fill_credential`, `operate_extract`, `inject_card`, `list_credentials`,
-`list_payment_cards`, and `edit_payment_card`.
-Recipe and vault/account tools remain separate surfaces. The complete migration
-table and input contracts are in [operator-tool-surface.md](docs/operator-tool-surface.md).
+Discover the installed tool inventory and schemas with `tools/list`. For the
+operator surface and input contracts, see
+[operator-tool-surface.md](docs/operator-tool-surface.md).
 The evidence required to qualify an operator build is in
 [operator-acceptance-runbook.md](docs/operator-acceptance-runbook.md).
 Continue a pending card release by re-calling `inject_card` with its returned
@@ -220,7 +245,7 @@ For controls visible only in the image, see
 The maintainer-only `list_extract_failures` → `get_extract_failure`
 DOM-diagnostics pair is excluded from that surface; set
 `TRUSTY_SQUIRE_DIAGNOSTICS=1` in the MCP server environment to opt into the
-22-tool diagnostics profile.
+diagnostics profile.
 
 Operate sessions default to `format:"compact"` observations: a bounded,
 paged `browser-use-control-query` control map containing every actionable
@@ -246,7 +271,11 @@ in [browser-use-serializer-port.md](docs/browser-use-serializer-port.md).
   `server_unavailable` includes `retry.max_attempts: 1`: retry once, and never
   kill or restart the shared operator process.
 - `operate_start` opens a scoped website session and `operate_observe` reads its
-  current state. Drive ordinary controls with `operate_click`, `operate_type`,
+  current state. For a signup, checkout, or other goal-shaped task, call
+  `operate_drive` with the goal and facts (or pass `url` to open and drive in
+  one call) instead of planning each click and type yourself; resume that
+  session with `answer` and/or added facts if it hands back. Drive ordinary
+  controls with `operate_click`, `operate_type`,
   `operate_select`, `operate_press`, and `operate_scroll`; use
   `operate_navigate` for scoped navigation. Acting tools target a current `ref`.
   `operate_type` accepts either literal `text` or a protected session `slot`,

package/dist/bot/act/act.d.ts

@@ -5,6 +5,18 @@ import { type ObserveDetail } from "../observe/observe.js";
 import { type CompactV2TargetAuthorization } from "./targets.js";
 import type { Observation, ProvisionAction } from "../provision-session.js";
 import type { Session } from "../session/model.js";
+export type ActExecutorOptions = {
+    drive?: boolean;
+};
+export type DriveActResult = {
+    kind: "ok";
+    combobox: boolean;
+} | {
+    kind: "stale";
+    reason: string;
+} | {
+    kind: "unsupported";
+};
 export declare function runSerializedGoogleIdentityOperation<T>(session: Session, operation: (browser: BrowserController) => Promise<T>, options?: {
     deadline?: OAuthActionDeadline;
 }): Promise<{
@@ -17,9 +29,15 @@ export interface InternalActResult {
     outcome: {
         selectedOption?: string;
     };
+    combobox?: boolean;
 }
-export declare function actInternally(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, compactV2Authorization?: CompactV2TargetAuthorization, operationPage?: Page): Promise<InternalActResult>;
+export declare function actInternally(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, compactV2Authorization?: CompactV2TargetAuthorization, operationPage?: Page, options?: ActExecutorOptions): Promise<InternalActResult>;
 export declare function act(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, outputFormat?: "compact" | "full", compactMapEmitted?: boolean): Promise<Observation>;
+export declare function dispatchDriveAct(sessionId: string, action: ProvisionAction): Promise<DriveActResult>;
 export declare function compactV2SelectionFailureReason(error: unknown): string;
-export declare function settleAfterStateChange(browser: BrowserController, page?: Page): Promise<void>;
+export declare function settleAfterDriveAction(page?: Page, combobox?: boolean): Promise<void>;
+export declare function settleAfterStateChange(browser: BrowserController, page?: Page, options?: {
+    drive?: boolean;
+    combobox?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=act.d.ts.map

package/dist/bot/act/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../../src/bot/act/act.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAWL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAOL,KAAK,aAAa,EAMnB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAiBL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAuDnD,wBAAsB,oCAAoC,CAAC,CAAC,EAC1D,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAO,GAC/C,OAAO,CAAC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAOpD;AA+GD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAqED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,sBAAsB,CAAC,EAAE,4BAA4B,EACrD,aAAa,CAAC,EAAE,IAAI,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAgD5B;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,YAAY,GAAE,SAAS,GAAG,MAAe,EACzC,iBAAiB,UAAO,GACvB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AAiiBD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AA+FD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,IAAI,GACV,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../../src/bot/act/act.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAS,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAWL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAOL,KAAK,aAAa,EAMnB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAiBL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAuBnD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AA4E5B,wBAAsB,oCAAoC,CAAC,CAAC,EAC1D,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAO,GAC/C,OAAO,CAAC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAOpD;AA+GD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAqED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,sBAAsB,CAAC,EAAE,4BAA4B,EACrD,aAAa,CAAC,EAAE,IAAI,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA4D5B;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,YAAY,GAAE,SAAS,GAAG,MAAe,EACzC,iBAAiB,UAAO,GACvB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AA6vBD,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,cAAc,CAAC,CA+DzB;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AA+FD,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzF;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}