Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/f12-connection-grants.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@fluentui-react-native/desktop-driver': patch
'@fluentui-react-native/desktop-driver-mcp': patch
---

Separate driver, declared-workload, and recovery grant scopes. Add bounded,
attenuated connection principals and awaitable descendant revocation with
retryable terminal-only cleanup proof. Isolate MCP sessions per connection and
keep descriptor credentials out of diagnostics.
8 changes: 6 additions & 2 deletions packages/agentic/desktop-driver-mcp/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,16 @@ only maps them onto MCP.
cleanup responsibility after transport loss; reverify discovery and never
replay a failed mutation. A verified replacement invalidates old references.
Fence a lost acquisition response; disposal also cleans up late acquisitions.
- Delegate a distinct driver-only child after verified discovery. Retain it on
same-incarnation/descriptor-principal rediscovery; never share or resume another
connection's session. Disposal awaits child revocation, keeping terminal-only
cleanup proof for lost responses and failed drains; unauthorized is not cleanup.
- Tie every artifact link to its session. Artifact ids restart in each session.
- Progress ticks come from the adapter and never reach the service, so a waiting
model does not keep an idle session alive. Cancellation aborts the HTTP call,
which the service treats as the caller leaving.
- Messages the model reads are fixed or bounded. Connection failures name no
paths; the details go to stderr.
- Messages the model reads are fixed or bounded. Connection failures use fixed
diagnostics on stderr too; never echo discovery exceptions or descriptor contents.

## Validation

Expand Down
5 changes: 4 additions & 1 deletion packages/agentic/desktop-driver-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,10 @@ The adapter does not start anything. A trusted supervisor runs the Desktop
Driver service with an authority, issues the agent a grant, and publishes a
private connection descriptor. The adapter reads that descriptor, has the
installed native helper verify the listening service's process identity, and
only then sends the grant. See
only then sends the grant to obtain its own driver-only child principal. Two
connections reading the same descriptor cannot share sessions. Disposal revokes
and drains the child, including ambiguous acquisitions; old services without
delegation fail closed. See
[Connection and setup](references/connection.md).

## Use it
Expand Down
47 changes: 34 additions & 13 deletions packages/agentic/desktop-driver-mcp/references/connection.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,13 @@ four things before an agent connects:
connection descriptor holding the service URL, the grant, and that identity.
4. Removes the descriptor after the service drains.

The descriptor grant defaults to `driver-control`. After verification, each MCP
controller uses `delegateConnection()` to obtain a distinct driver-only child
client. The child credential never enters tool results or diagnostics. Older or
unprotected services without the delegation route are explicitly unsupported by
this adapter, not a fallback to shared session authority. The generic driver's
unprotected mode is unchanged.

The descriptor format, storage, and verifier contracts belong to
`@fluentui-react-native/desktop-driver`
(its service reference, "Private connection descriptors").
Expand Down Expand Up @@ -86,7 +93,8 @@ desktop-driver-mcp [--descriptor <name>] [--root <path>]
| `--root <path>` | The private storage root, when the supervisor published somewhere other than the platform default. It must be absolute and canonical. |

The adapter speaks MCP over stdio until the client closes stdin, then stops
admissions and attempts to delete its session, including late acquisition.
admissions and attempts to revoke and drain its child, including late or
ambiguous acquisitions.
Cleanup waits at most ten seconds; an unresolved attempt continues while the
process lives and reports to stderr. Service drain/expiry is still needed when
the adapter cannot confirm deletion. `--help` and `--version` write to stderr so stdout
Expand All @@ -106,29 +114,42 @@ grant leaves the adapter. The service then confirms its incarnation.

The adapter connects on the first tool call, not at startup, so it can start
before the service. When the service cannot be reached, a tool returns the
fixed reason `service-unavailable`; the cause, which may name local paths, goes
to stderr. Transport failure invalidates the cached connection, **not** known
fixed reason `service-unavailable`; stderr reports a fixed diagnostic without
echoing discovery errors, which may contain paths or credentials.
Transport failure invalidates the cached connection, **not** known
session cleanup responsibility. The next call re-verifies discovery. The same
verified service incarnation and non-secret grant principal can rebind the
known session. A replacement service or an authoritative invalid/revoked
verified service incarnation and descriptor principal reuse the controller's
existing private child client, never another connection's child. This retains
known-session cleanup responsibility rather than resuming across connections.
A replacement service or an authoritative invalid/revoked
session invalidates old references; open a new session and observe again.
Nothing automatically replays the failed operation.

Operations, acquisition, close, and complete resource reads are serialized per
MCP connection. Disposal stops admission immediately and cleans up a session
whose acquisition completes late. A failed DELETE retains responsibility until
confirmed deletion or authoritative invalidation. A lost create response has
MCP connection. Disposal stops admission immediately and drains the child,
including sessions whose acquisition completes late. A failed session DELETE
retains responsibility until confirmed deletion or authoritative invalidation.
A lost create response has
no safely known session id: `session-uncertain` fences further acquisition and
mutation. Revoke the old grant (and drain it) or replace the service through the
trusted supervisor; do not guess an id or acquire again under the same authority.
mutation. Close the MCP connection to revoke and drain its child, or have the
supervisor revoke and drain the parent. Do not guess an id or acquire again
under the same child.

A new principal on the same live service does not prove that the old session
ended. The adapter first attempts cleanup with the old authority, or verifies
its revocation. Current descriptors share one supervisor-issued agent grant,
not isolated per-MCP-connection grants. Grant labels are not principals.
ended. The adapter first awaits terminal cleanup with the old child before
delegating from a replacement descriptor principal. Grant labels are not
principals. A revoked child credential is retained solely to retry its own
`DELETE /furn/grants/current` cleanup after a lost response or failed drain;
unauthorized is never treated as successful cleanup. Repeated disposal can
retry an incomplete cleanup while the process remains alive.
There is no resume across different MCP connections and no crash-safe native
recovery promise; see [current status](current-status.md).

The authority limits delegation to eight edges and 4096 grants per service
incarnation, including revoked roots/children. Exhaustion is explicit and
requires an operator-controlled drain and service replacement. Cleanup proof
is never silently evicted or reused.

## Embedding

`createDesktopDriverMcpServer({ connect, version })` returns an SDK `McpServer`
Expand Down
31 changes: 16 additions & 15 deletions packages/agentic/desktop-driver-mcp/references/current-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,21 +19,22 @@ and the generalized management facet is

## Capability matrix

| Capability | State | Boundary/remaining work |
| ------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Six tools over shared driver schemas | Done | Session, observe, act, check, capture, story. No separate execution path. |
| Private descriptor and native identity verification | Done | Verifies before sending a grant. Uses the driver's `/native`, `/authority`, and `/client` subpaths, not its WebdriverIO-heavy root; boundary tests guard this dependency. No model URL/token/config/executable input. |
| Single-flight connection/session lifetime | Done | Serial acquisition, close, operations and resource reads; late acquisition after dispose is cleaned up. |
| Same-port protected restart/revocation | Done in deterministic contracts | Invalid authority is forgotten; next call re-verifies discovery. No mutation replay. Live endpoint reruns remain required. |
| Same-authority transport retry | Done, bounded semantics | Retain known session cleanup responsibility and rebind only after verification of the same incarnation/principal. This is not cross-MCP-connection resume. |
| Lost create response | Fenced; recovery in progress | `session-uncertain`; no repeated acquisition. Operator must revoke the old grant or replace the service. No session-enumeration shortcut. |
| Failed delete/disconnect | Done with limits | Keep known-session responsibility; bounded dispose wait leaves late cleanup attached. Unreachable-service cleanup cannot be guaranteed; service drain/expiry remains necessary. |
| Launch-mode discovery | Done | Status lists effective launch/attach modes; no predictable attach-first failure against launch-only targets. |
| Progress, cancellation, paged image resources | Done | Progress does not renew idle sessions; artifacts are session-bound and hash-checked. |
| Storybook control | Experimental | Driver selection/marker path exists; channel ingress/reconnect and full exclusive context authority remain incomplete. |
| Per-connection attenuated grants and resumable sessions | Work in progress | Current supervisor publishes one shared agent grant. Labels are not client isolation. |
| Workload/test orchestration tools | Work in progress | Belong to a future harness control/client surface; adapter never becomes the resource owner. |
| General MCP-client qualification | Work in progress | SDK stdio evidence exists; client-specific resource/image/cancellation behavior needs independent runs. |
| Capability | State | Boundary/remaining work |
| --------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Six tools over shared driver schemas | Done | Session, observe, act, check, capture, story. No separate execution path. |
| Private descriptor and native identity verification | Done | Verifies before sending a grant. Uses the driver's `/native`, `/authority`, and `/client` subpaths, not its WebdriverIO-heavy root; boundary tests guard this dependency. No model URL/token/config/executable input. |
| Single-flight connection/session lifetime | Done | Serial acquisition, close, operations and resource reads; late acquisition after dispose is cleaned up. |
| Same-port protected restart/revocation | Done in deterministic contracts | Invalid authority is forgotten; next call re-verifies discovery. No mutation replay. Live endpoint reruns remain required. |
| Same-authority transport retry | Done, bounded semantics | Retain known session cleanup responsibility and rebind only after verification of the same incarnation/principal. This is not cross-MCP-connection resume. |
| Lost create response | Fenced; child drain implemented | `session-uncertain`; no repeated acquisition. Connection disposal revokes and drains the child, including unknown session ids. Live descriptor-path reruns not run for this change. |
| Failed delete/disconnect | Done with limits | Keep known-session responsibility; bounded dispose wait leaves late cleanup attached. Unreachable-service cleanup cannot be guaranteed; service drain/expiry remains necessary. |
| Launch-mode discovery | Done | Status lists effective launch/attach modes; no predictable attach-first failure against launch-only targets. |
| Progress, cancellation, paged image resources | Done | Progress does not renew idle sessions; artifacts are session-bound and hash-checked. |
| Storybook control | Experimental | Driver selection/marker path exists; channel ingress/reconnect and full exclusive context authority remain incomplete. |
| Per-connection attenuated grants | Done in deterministic contracts | Each controller delegates a distinct driver-only child after verification; target/scope subsets and terminal-only cleanup retry. Native descriptor-path qualification not run for this change. |
| Cross-connection session resume | Intentionally unsupported | No lease/grace or ownership-transfer protocol. Same-controller rediscovery retains its existing child; no automatic replay or cross-connection resume. |
| Workload/test orchestration tools | Work in progress | Belong to a future harness control/client surface; adapter never becomes the resource owner. |
| General MCP-client qualification | Work in progress | SDK stdio evidence exists; client-specific resource/image/cancellation behavior needs independent runs. |

See [connection](connection.md) and [tools](tools.md) for exact behavior.
Native and Storybook limitations are tracked in
Expand Down
Loading
Loading