@leaflow/sdk 0.202.0 → 0.203.1

package/dist/fleet/v1/generated/functions.d.ts

@@ -87,11 +87,14 @@
  * - `leaflow.fleet.tool.v1`: live session tools. Builtin `computer.*` tools are exposed only while
  *   the virtual desktop capability is actually available; MCP is a separate source.
  *
- * A graphical backend does not require a full desktop environment. Terminal logins, commands
- * and MCP server initialization prepare or reuse the account's lightweight graphical context,
- * in addition to their own session or job. Configuration reads and writes do not initialize a
- * server and do not require this preparation. A request that needs a feature the machine does
- * not report available fails with `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
+ * A graphical backend does not require a full desktop environment. When the machine reports
+ * graphical capability available, terminal logins and commands prepare or reuse the account's
+ * lightweight graphical context, in addition to their own session or job. Without graphical
+ * capability, ordinary commands and terminal sessions run without creating a graphical context
+ * or injecting X environment variables. MCP server initialization prepares or reuses a graphical
+ * context; configuration reads and writes do not initialize a server or require this preparation.
+ * A request that needs a feature the machine does not report available fails with
+ * `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
  *
  * ## Directory
  *
@@ -381,14 +384,16 @@ export declare const getRunMachineCommandUrl: (machineId: string) => string;
  * redirection and `&&` work; there is no terminal and no standard input. The machine admits
  * the account through PAM as for a login. The account is created if the caller has none yet.
  * A command that fails is still a successful request: its exit status is its result.
- * Before starting it, Fleet prepares or reuses the account's ready lightweight graphical
- * session, without starting a full desktop environment. The command has its own job scope;
- * its timeout or exit must not close the account's graphical context.
+ * When the machine reports graphical capability available, Fleet first prepares or reuses
+ * the account's ready lightweight graphical session, without starting a full desktop
+ * environment. Otherwise the command runs without creating a graphical session or injecting
+ * X environment variables. The command has its own job scope; its timeout or exit must not
+ * close an existing account graphical context.
  *
  * Inside the command, `sudo` works without a prompt while the caller has
  * `fleet:machines.admin` on the machine, and refuses otherwise.
  *
- * After graphical context preparation, the request is held until the command ends, at most
+ * After any required context preparation, the request is held until the command ends, at most
  * `timeout_seconds` and a few seconds more. Neither the command nor its output is hidden from the platform: do not put secrets
  * into either.
  *
@@ -396,7 +401,8 @@ export declare const getRunMachineCommandUrl: (machineId: string) => string;
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the command, session or graphical backend is unavailable;
+ * - `FEATURE_UNAVAILABLE` when a required capability is unavailable; an absent graphical
+ *   backend alone does not block a command;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when the account context is not ready or closing;
  * - `USER_NOT_FOUND`, `USER_NOT_ALLOWED`, `ACCOUNT_EXPIRED` or `PAM_PERMISSION_DENIED` when
  *   the machine refuses the account, as for opening a session;
@@ -554,7 +560,9 @@ export type listToolsResponse = listToolsResponseSuccess | listToolsResponseErro
 export declare const getListToolsUrl: (machineId: string, params: ListToolsParams) => string;
 /**
  * Queries Agent's builtin tools and the caller's configured MCP servers live. No directory,
- * result or image is cached. Requires fleet:machines.login; builtin capabilities retain
+ * result or image is cached. Each tool has one callable name: builtin tools are named
+ * computer.*, MCP tools are named `<server>__<tool>`; source only filters the list and is not
+ * part of a tool's identity. Requires fleet:machines.login; builtin capabilities retain
  * their native policies and read-only restrictions. Ensures or reuses the caller's single
  * open graphical session, without launching a desktop environment. The client instance is
  * a UUID generated once per running client, not an authorization credential. Each request
@@ -583,18 +591,19 @@ export type callToolResponse = callToolResponseSuccess | callToolResponseError;
 export declare const getCallToolUrl: (machineId: string) => string;
 /**
  * Uses the same current permissions, directory account and graphical session as list-tools.
- * Listing is not a precondition: callers may use a previously discovered ToolRef, and this
+ * Listing is not a precondition: callers may use a previously discovered tool name, and this
  * operation never sends a discovery request or refreshes schemas before executing it.
  * A removed tool or MCP server returns TOOL_NOT_FOUND, as does a direct builtin computer.*
  * call while virtual desktop capability is unavailable. Actual permission errors remain
  * permission errors; a missing target window is not a missing tool. Use list-tools only when
  * discovery or refresh is needed, and do not cache or reuse execution results.
- * Source is explicit: MCP names never select or impersonate builtin tools. The arguments
- * object is at most 256 KiB. The complete result is at most 8 MiB in the protobuf transport,
- * with each encoded image at most 4 MiB; images are converted to base64 once at this JSON
- * boundary, without recompression or persistence. Cancellation is propagated. A timeout,
- * disconnect or failed response does not prove that side effects did not happen; do not
- * automatically replay. operation_id only correlates live activity, not idempotency.
+ * The name selects exactly one tool: builtin tools are computer.*, MCP tools are
+ * `<server>__<tool>`. The arguments object is at most 256 KiB. The complete result is at most
+ * 8 MiB in the protobuf transport, with each encoded image at most 4 MiB; images are converted
+ * to base64 once at this JSON boundary, without recompression or persistence. Cancellation is
+ * propagated. A timeout, disconnect or failed response does not prove that side effects did
+ * not happen; do not automatically replay. operation_id only correlates live activity, not
+ * idempotency.
  * @summary Call a live builtin or external MCP tool
  */
 export declare const callTool: (machineId: string, callToolRequest: CallToolRequest, options?: RequestInit, fetchFn?: typeof globalThis.fetch) => Promise<callToolResponse>;
@@ -1352,10 +1361,13 @@ export type createSessionResponse = createSessionResponseSuccess | createSession
 export declare const getCreateSessionUrl: () => string;
 /**
  * Opens a session for the caller on a machine, as the caller's account, and returns once it
- * is ready. With `desktop` the session has a desktop. Without, Fleet first prepares or reuses
- * the account's separate ready lightweight graphical session, then creates a terminal session
- * with its own SID and lifetime; closing that terminal does not close the account context. Its
- * one terminal runs the caller's login shell from the start, every participant attaches to
+ * is ready. With `desktop` the session requires graphical capability and has a desktop.
+ * Without `desktop`, Fleet creates a terminal session with its own SID and lifetime. If
+ * graphical capability is available, Fleet first prepares or reuses the account's separate
+ * ready lightweight graphical session; otherwise the terminal runs without creating a
+ * graphical context or injecting X environment variables. Closing a terminal does not close
+ * an existing account graphical context. Its one terminal runs the caller's login shell from
+ * the start, every participant attaches to
  * that terminal, and the session ends when the shell exits; a caller who wants another
  * terminal opens another session. Either kind also offers programs, files, ports, sound,
  * devices, printers and privilege approvals. The account is created if the caller has none
@@ -1372,7 +1384,8 @@ export declare const getCreateSessionUrl: () => string;
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the machine does not offer sessions or the graphical backend;
+ * - `FEATURE_UNAVAILABLE` when the machine does not offer the requested session capability;
+ *   a terminal-only request does not require a graphical backend;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when its shared account context is not ready or closing;
  * - `USER_HAS_DESKTOP_SESSION` with `desktop` when the account already has a session with a
  *   desktop on the machine, which `metadata.sessionId` names; connect to it instead;

package/dist/fleet/v1/generated/functions.js

@@ -127,14 +127,16 @@ export const getRunMachineCommandUrl = (machineId) => {
  * redirection and `&&` work; there is no terminal and no standard input. The machine admits
  * the account through PAM as for a login. The account is created if the caller has none yet.
  * A command that fails is still a successful request: its exit status is its result.
- * Before starting it, Fleet prepares or reuses the account's ready lightweight graphical
- * session, without starting a full desktop environment. The command has its own job scope;
- * its timeout or exit must not close the account's graphical context.
+ * When the machine reports graphical capability available, Fleet first prepares or reuses
+ * the account's ready lightweight graphical session, without starting a full desktop
+ * environment. Otherwise the command runs without creating a graphical session or injecting
+ * X environment variables. The command has its own job scope; its timeout or exit must not
+ * close an existing account graphical context.
  *
  * Inside the command, `sudo` works without a prompt while the caller has
  * `fleet:machines.admin` on the machine, and refuses otherwise.
  *
- * After graphical context preparation, the request is held until the command ends, at most
+ * After any required context preparation, the request is held until the command ends, at most
  * `timeout_seconds` and a few seconds more. Neither the command nor its output is hidden from the platform: do not put secrets
  * into either.
  *
@@ -142,7 +144,8 @@ export const getRunMachineCommandUrl = (machineId) => {
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the command, session or graphical backend is unavailable;
+ * - `FEATURE_UNAVAILABLE` when a required capability is unavailable; an absent graphical
+ *   backend alone does not block a command;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when the account context is not ready or closing;
  * - `USER_NOT_FOUND`, `USER_NOT_ALLOWED`, `ACCOUNT_EXPIRED` or `PAM_PERMISSION_DENIED` when
  *   the machine refuses the account, as for opening a session;
@@ -344,7 +347,9 @@ export const getListToolsUrl = (machineId, params) => {
 };
 /**
  * Queries Agent's builtin tools and the caller's configured MCP servers live. No directory,
- * result or image is cached. Requires fleet:machines.login; builtin capabilities retain
+ * result or image is cached. Each tool has one callable name: builtin tools are named
+ * computer.*, MCP tools are named `<server>__<tool>`; source only filters the list and is not
+ * part of a tool's identity. Requires fleet:machines.login; builtin capabilities retain
  * their native policies and read-only restrictions. Ensures or reuses the caller's single
  * open graphical session, without launching a desktop environment. The client instance is
  * a UUID generated once per running client, not an authorization credential. Each request
@@ -368,18 +373,19 @@ export const getCallToolUrl = (machineId) => {
 };
 /**
  * Uses the same current permissions, directory account and graphical session as list-tools.
- * Listing is not a precondition: callers may use a previously discovered ToolRef, and this
+ * Listing is not a precondition: callers may use a previously discovered tool name, and this
  * operation never sends a discovery request or refreshes schemas before executing it.
  * A removed tool or MCP server returns TOOL_NOT_FOUND, as does a direct builtin computer.*
  * call while virtual desktop capability is unavailable. Actual permission errors remain
  * permission errors; a missing target window is not a missing tool. Use list-tools only when
  * discovery or refresh is needed, and do not cache or reuse execution results.
- * Source is explicit: MCP names never select or impersonate builtin tools. The arguments
- * object is at most 256 KiB. The complete result is at most 8 MiB in the protobuf transport,
- * with each encoded image at most 4 MiB; images are converted to base64 once at this JSON
- * boundary, without recompression or persistence. Cancellation is propagated. A timeout,
- * disconnect or failed response does not prove that side effects did not happen; do not
- * automatically replay. operation_id only correlates live activity, not idempotency.
+ * The name selects exactly one tool: builtin tools are computer.*, MCP tools are
+ * `<server>__<tool>`. The arguments object is at most 256 KiB. The complete result is at most
+ * 8 MiB in the protobuf transport, with each encoded image at most 4 MiB; images are converted
+ * to base64 once at this JSON boundary, without recompression or persistence. Cancellation is
+ * propagated. A timeout, disconnect or failed response does not prove that side effects did
+ * not happen; do not automatically replay. operation_id only correlates live activity, not
+ * idempotency.
  * @summary Call a live builtin or external MCP tool
  */
 export const callTool = async (machineId, callToolRequest, options, fetchFn) => {
@@ -1241,10 +1247,13 @@ export const getCreateSessionUrl = () => {
 };
 /**
  * Opens a session for the caller on a machine, as the caller's account, and returns once it
- * is ready. With `desktop` the session has a desktop. Without, Fleet first prepares or reuses
- * the account's separate ready lightweight graphical session, then creates a terminal session
- * with its own SID and lifetime; closing that terminal does not close the account context. Its
- * one terminal runs the caller's login shell from the start, every participant attaches to
+ * is ready. With `desktop` the session requires graphical capability and has a desktop.
+ * Without `desktop`, Fleet creates a terminal session with its own SID and lifetime. If
+ * graphical capability is available, Fleet first prepares or reuses the account's separate
+ * ready lightweight graphical session; otherwise the terminal runs without creating a
+ * graphical context or injecting X environment variables. Closing a terminal does not close
+ * an existing account graphical context. Its one terminal runs the caller's login shell from
+ * the start, every participant attaches to
  * that terminal, and the session ends when the shell exits; a caller who wants another
  * terminal opens another session. Either kind also offers programs, files, ports, sound,
  * devices, printers and privilege approvals. The account is created if the caller has none
@@ -1261,7 +1270,8 @@ export const getCreateSessionUrl = () => {
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the machine does not offer sessions or the graphical backend;
+ * - `FEATURE_UNAVAILABLE` when the machine does not offer the requested session capability;
+ *   a terminal-only request does not require a graphical backend;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when its shared account context is not ready or closing;
  * - `USER_HAS_DESKTOP_SESSION` with `desktop` when the account already has a session with a
  *   desktop on the machine, which `metadata.sessionId` names; connect to it instead;

package/dist/fleet/v1/generated/models.d.ts

@@ -87,11 +87,14 @@
  * - `leaflow.fleet.tool.v1`: live session tools. Builtin `computer.*` tools are exposed only while
  *   the virtual desktop capability is actually available; MCP is a separate source.
  *
- * A graphical backend does not require a full desktop environment. Terminal logins, commands
- * and MCP server initialization prepare or reuse the account's lightweight graphical context,
- * in addition to their own session or job. Configuration reads and writes do not initialize a
- * server and do not require this preparation. A request that needs a feature the machine does
- * not report available fails with `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
+ * A graphical backend does not require a full desktop environment. When the machine reports
+ * graphical capability available, terminal logins and commands prepare or reuse the account's
+ * lightweight graphical context, in addition to their own session or job. Without graphical
+ * capability, ordinary commands and terminal sessions run without creating a graphical context
+ * or injecting X environment variables. MCP server initialization prepares or reuses a graphical
+ * context; configuration reads and writes do not initialize a server or require this preparation.
+ * A request that needs a feature the machine does not report available fails with
+ * `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
  *
  * ## Directory
  *
@@ -979,25 +982,14 @@ export interface SendMcpRequestResponse {
     /** The server's JSON-RPC 2.0 response, with the id of the request */
     response: SendMcpRequestResponseResponse;
 }
-export type ToolRefSource = (typeof ToolRefSource)[keyof typeof ToolRefSource];
-export declare const ToolRefSource: {
+/**
+ * Whether the tool is builtin or comes from an MCP server. For filtering only.
+ */
+export type ToolDescriptorSource = (typeof ToolDescriptorSource)[keyof typeof ToolDescriptorSource];
+export declare const ToolDescriptorSource: {
     readonly builtin: "builtin";
     readonly mcp: "mcp";
 };
-export interface ToolRef {
-    source: ToolRefSource;
-    /**
-     * @minLength 1
-     * @maxLength 128
-     */
-    name: string;
-    /**
-     * Required only for mcp; forbidden for builtin
-     * @minLength 1
-     * @maxLength 64
-     */
-    server?: string;
-}
 export type ToolDescriptorInputSchema = {
     [key: string]: unknown;
 };
@@ -1011,8 +1003,15 @@ export type ToolDescriptorMetadata = {
     [key: string]: unknown;
 };
 export interface ToolDescriptor {
-    tool: ToolRef;
+    /**
+     * The name to call it by. Builtin tools are named computer.*; MCP tools are named
+     * `<server>__<tool>`, so a name selects exactly one tool.
+     * @minLength 1
+     * @maxLength 194
+     */
     name: string;
+    /** Whether the tool is builtin or comes from an MCP server. For filtering only. */
+    source: ToolDescriptorSource;
     title: string;
     description: string;
     input_schema: ToolDescriptorInputSchema;
@@ -1045,7 +1044,13 @@ export type CallToolRequestArguments = {
 };
 export interface CallToolRequest {
     client_instance_id: string;
-    tool: ToolRef;
+    /**
+     * The name from list-tools. Builtin tools are computer.*; MCP tools are
+     * `<server>__<tool>`. The name selects the tool; source is not part of the call.
+     * @minLength 1
+     * @maxLength 194
+     */
+    tool: string;
     /** A JSON object, at most 256 KiB when encoded */
     arguments: CallToolRequestArguments;
     read_only?: boolean;
@@ -1539,16 +1544,28 @@ export type DeleteMcpServerParams = {
     expected_revision?: string;
 };
 export type ListToolsParams = {
+    /**
+     * A UUID generated once per running client and reused for its lifetime. It separates
+     * concurrent callers of the same user and is not an authorization credential.
+     */
     client_instance_id: string;
+    /**
+     * Return only tools of this source. A filter, not part of a tool's identity.
+     */
     source?: ListToolsSource;
     /**
+     * Return only this MCP server's tools.
      * @maxLength 64
      */
     mcp_server?: string;
     /**
+     * Words that each must occur in a tool's name, title or description, ignoring case.
      * @maxLength 256
      */
     query?: string;
+    /**
+     * Sign the control authorization as read-only, so mutating tools are refused.
+     */
     read_only?: boolean;
     /**
      * @minimum 1

package/dist/fleet/v1/generated/models.js

@@ -68,7 +68,7 @@ export const McpServerFailure = {
     protocol_error: "protocol_error",
     timeout: "timeout",
 };
-export const ToolRefSource = {
+export const ToolDescriptorSource = {
     builtin: "builtin",
     mcp: "mcp",
 };

package/dist/fleet/v1/generated/schemas.zod.d.ts

@@ -87,11 +87,14 @@
  * - `leaflow.fleet.tool.v1`: live session tools. Builtin `computer.*` tools are exposed only while
  *   the virtual desktop capability is actually available; MCP is a separate source.
  *
- * A graphical backend does not require a full desktop environment. Terminal logins, commands
- * and MCP server initialization prepare or reuse the account's lightweight graphical context,
- * in addition to their own session or job. Configuration reads and writes do not initialize a
- * server and do not require this preparation. A request that needs a feature the machine does
- * not report available fails with `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
+ * A graphical backend does not require a full desktop environment. When the machine reports
+ * graphical capability available, terminal logins and commands prepare or reuse the account's
+ * lightweight graphical context, in addition to their own session or job. Without graphical
+ * capability, ordinary commands and terminal sessions run without creating a graphical context
+ * or injecting X environment variables. MCP server initialization prepares or reuses a graphical
+ * context; configuration reads and writes do not initialize a server or require this preparation.
+ * A request that needs a feature the machine does not report available fails with
+ * `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
  *
  * ## Directory
  *
@@ -311,14 +314,16 @@ export declare const ListMachineEventsQueryParams: zod.ZodObject<{
  * redirection and `&&` work; there is no terminal and no standard input. The machine admits
  * the account through PAM as for a login. The account is created if the caller has none yet.
  * A command that fails is still a successful request: its exit status is its result.
- * Before starting it, Fleet prepares or reuses the account's ready lightweight graphical
- * session, without starting a full desktop environment. The command has its own job scope;
- * its timeout or exit must not close the account's graphical context.
+ * When the machine reports graphical capability available, Fleet first prepares or reuses
+ * the account's ready lightweight graphical session, without starting a full desktop
+ * environment. Otherwise the command runs without creating a graphical session or injecting
+ * X environment variables. The command has its own job scope; its timeout or exit must not
+ * close an existing account graphical context.
  *
  * Inside the command, `sudo` works without a prompt while the caller has
  * `fleet:machines.admin` on the machine, and refuses otherwise.
  *
- * After graphical context preparation, the request is held until the command ends, at most
+ * After any required context preparation, the request is held until the command ends, at most
  * `timeout_seconds` and a few seconds more. Neither the command nor its output is hidden from the platform: do not put secrets
  * into either.
  *
@@ -326,7 +331,8 @@ export declare const ListMachineEventsQueryParams: zod.ZodObject<{
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the command, session or graphical backend is unavailable;
+ * - `FEATURE_UNAVAILABLE` when a required capability is unavailable; an absent graphical
+ *   backend alone does not block a command;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when the account context is not ready or closing;
  * - `USER_NOT_FOUND`, `USER_NOT_ALLOWED`, `ACCOUNT_EXPIRED` or `PAM_PERMISSION_DENIED` when
  *   the machine refuses the account, as for opening a session;
@@ -445,7 +451,9 @@ export declare const DeleteMcpServerQueryParams: zod.ZodObject<{
 }, zod.z.core.$strict>;
 /**
  * Queries Agent's builtin tools and the caller's configured MCP servers live. No directory,
- * result or image is cached. Requires fleet:machines.login; builtin capabilities retain
+ * result or image is cached. Each tool has one callable name: builtin tools are named
+ * computer.*, MCP tools are named `<server>__<tool>`; source only filters the list and is not
+ * part of a tool's identity. Requires fleet:machines.login; builtin capabilities retain
  * their native policies and read-only restrictions. Ensures or reuses the caller's single
  * open graphical session, without launching a desktop environment. The client instance is
  * a UUID generated once per running client, not an authorization credential. Each request
@@ -480,18 +488,19 @@ export declare const ListToolsQueryParams: zod.ZodObject<{
 }, zod.z.core.$strict>;
 /**
  * Uses the same current permissions, directory account and graphical session as list-tools.
- * Listing is not a precondition: callers may use a previously discovered ToolRef, and this
+ * Listing is not a precondition: callers may use a previously discovered tool name, and this
  * operation never sends a discovery request or refreshes schemas before executing it.
  * A removed tool or MCP server returns TOOL_NOT_FOUND, as does a direct builtin computer.*
  * call while virtual desktop capability is unavailable. Actual permission errors remain
  * permission errors; a missing target window is not a missing tool. Use list-tools only when
  * discovery or refresh is needed, and do not cache or reuse execution results.
- * Source is explicit: MCP names never select or impersonate builtin tools. The arguments
- * object is at most 256 KiB. The complete result is at most 8 MiB in the protobuf transport,
- * with each encoded image at most 4 MiB; images are converted to base64 once at this JSON
- * boundary, without recompression or persistence. Cancellation is propagated. A timeout,
- * disconnect or failed response does not prove that side effects did not happen; do not
- * automatically replay. operation_id only correlates live activity, not idempotency.
+ * The name selects exactly one tool: builtin tools are computer.*, MCP tools are
+ * `<server>__<tool>`. The arguments object is at most 256 KiB. The complete result is at most
+ * 8 MiB in the protobuf transport, with each encoded image at most 4 MiB; images are converted
+ * to base64 once at this JSON boundary, without recompression or persistence. Cancellation is
+ * propagated. A timeout, disconnect or failed response does not prove that side effects did
+ * not happen; do not automatically replay. operation_id only correlates live activity, not
+ * idempotency.
  * @summary Call a live builtin or external MCP tool
  */
 export declare const CallToolParams: zod.ZodObject<{
@@ -499,14 +508,7 @@ export declare const CallToolParams: zod.ZodObject<{
 }, zod.z.core.$strict>;
 export declare const CallToolBody: zod.ZodObject<{
     client_instance_id: zod.ZodUUID;
-    tool: zod.ZodObject<{
-        source: zod.ZodEnum<{
-            builtin: "builtin";
-            mcp: "mcp";
-        }>;
-        name: zod.ZodString;
-        server: zod.ZodOptional<zod.ZodString>;
-    }, zod.z.core.$strict>;
+    tool: zod.ZodString;
     arguments: zod.ZodRecord<zod.ZodString, zod.ZodUnknown>;
     read_only: zod.ZodDefault<zod.ZodBoolean>;
     timeout_seconds: zod.ZodDefault<zod.ZodInt>;
@@ -924,10 +926,13 @@ export declare const ListSessionsQueryParams: zod.ZodObject<{
 }, zod.z.core.$strict>;
 /**
  * Opens a session for the caller on a machine, as the caller's account, and returns once it
- * is ready. With `desktop` the session has a desktop. Without, Fleet first prepares or reuses
- * the account's separate ready lightweight graphical session, then creates a terminal session
- * with its own SID and lifetime; closing that terminal does not close the account context. Its
- * one terminal runs the caller's login shell from the start, every participant attaches to
+ * is ready. With `desktop` the session requires graphical capability and has a desktop.
+ * Without `desktop`, Fleet creates a terminal session with its own SID and lifetime. If
+ * graphical capability is available, Fleet first prepares or reuses the account's separate
+ * ready lightweight graphical session; otherwise the terminal runs without creating a
+ * graphical context or injecting X environment variables. Closing a terminal does not close
+ * an existing account graphical context. Its one terminal runs the caller's login shell from
+ * the start, every participant attaches to
  * that terminal, and the session ends when the shell exits; a caller who wants another
  * terminal opens another session. Either kind also offers programs, files, ports, sound,
  * devices, printers and privilege approvals. The account is created if the caller has none
@@ -944,7 +949,8 @@ export declare const ListSessionsQueryParams: zod.ZodObject<{
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the machine does not offer sessions or the graphical backend;
+ * - `FEATURE_UNAVAILABLE` when the machine does not offer the requested session capability;
+ *   a terminal-only request does not require a graphical backend;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when its shared account context is not ready or closing;
  * - `USER_HAS_DESKTOP_SESSION` with `desktop` when the account already has a session with a
  *   desktop on the machine, which `metadata.sessionId` names; connect to it instead;

package/dist/fleet/v1/generated/schemas.zod.js

@@ -87,11 +87,14 @@
  * - `leaflow.fleet.tool.v1`: live session tools. Builtin `computer.*` tools are exposed only while
  *   the virtual desktop capability is actually available; MCP is a separate source.
  *
- * A graphical backend does not require a full desktop environment. Terminal logins, commands
- * and MCP server initialization prepare or reuse the account's lightweight graphical context,
- * in addition to their own session or job. Configuration reads and writes do not initialize a
- * server and do not require this preparation. A request that needs a feature the machine does
- * not report available fails with `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
+ * A graphical backend does not require a full desktop environment. When the machine reports
+ * graphical capability available, terminal logins and commands prepare or reuse the account's
+ * lightweight graphical context, in addition to their own session or job. Without graphical
+ * capability, ordinary commands and terminal sessions run without creating a graphical context
+ * or injecting X environment variables. MCP server initialization prepares or reuses a graphical
+ * context; configuration reads and writes do not initialize a server or require this preparation.
+ * A request that needs a feature the machine does not report available fails with
+ * `FEATURE_UNAVAILABLE`, whose `metadata.feature` names it.
  *
  * ## Directory
  *
@@ -354,14 +357,16 @@ export const ListMachineEventsQueryParams = zod.strictObject({
  * redirection and `&&` work; there is no terminal and no standard input. The machine admits
  * the account through PAM as for a login. The account is created if the caller has none yet.
  * A command that fails is still a successful request: its exit status is its result.
- * Before starting it, Fleet prepares or reuses the account's ready lightweight graphical
- * session, without starting a full desktop environment. The command has its own job scope;
- * its timeout or exit must not close the account's graphical context.
+ * When the machine reports graphical capability available, Fleet first prepares or reuses
+ * the account's ready lightweight graphical session, without starting a full desktop
+ * environment. Otherwise the command runs without creating a graphical session or injecting
+ * X environment variables. The command has its own job scope; its timeout or exit must not
+ * close an existing account graphical context.
  *
  * Inside the command, `sudo` works without a prompt while the caller has
  * `fleet:machines.admin` on the machine, and refuses otherwise.
  *
- * After graphical context preparation, the request is held until the command ends, at most
+ * After any required context preparation, the request is held until the command ends, at most
  * `timeout_seconds` and a few seconds more. Neither the command nor its output is hidden from the platform: do not put secrets
  * into either.
  *
@@ -369,7 +374,8 @@ export const ListMachineEventsQueryParams = zod.strictObject({
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the command, session or graphical backend is unavailable;
+ * - `FEATURE_UNAVAILABLE` when a required capability is unavailable; an absent graphical
+ *   backend alone does not block a command;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when the account context is not ready or closing;
  * - `USER_NOT_FOUND`, `USER_NOT_ALLOWED`, `ACCOUNT_EXPIRED` or `PAM_PERMISSION_DENIED` when
  *   the machine refuses the account, as for opening a session;
@@ -478,7 +484,9 @@ export const DeleteMcpServerQueryParams = zod.strictObject({
 });
 /**
  * Queries Agent's builtin tools and the caller's configured MCP servers live. No directory,
- * result or image is cached. Requires fleet:machines.login; builtin capabilities retain
+ * result or image is cached. Each tool has one callable name: builtin tools are named
+ * computer.*, MCP tools are named `<server>__<tool>`; source only filters the list and is not
+ * part of a tool's identity. Requires fleet:machines.login; builtin capabilities retain
  * their native policies and read-only restrictions. Ensures or reuses the caller's single
  * open graphical session, without launching a desktop environment. The client instance is
  * a UUID generated once per running client, not an authorization credential. Each request
@@ -499,28 +507,45 @@ export const listToolsQueryPageSizeDefault = 100;
 export const listToolsQueryPageSizeMax = 100;
 export const listToolsQueryPageTokenMax = 4096;
 export const ListToolsQueryParams = zod.strictObject({
-    client_instance_id: zod.uuid(),
-    source: zod.enum(["all", "builtin", "mcp"]).default(listToolsQuerySourceDefault),
-    mcp_server: zod.string().max(listToolsQueryMcpServerMax).optional(),
-    query: zod.string().max(listToolsQueryQueryMax).optional(),
-    read_only: zod.boolean().default(listToolsQueryReadOnlyDefault),
+    client_instance_id: zod
+        .uuid()
+        .describe("A UUID generated once per running client and reused for its lifetime. It separates\nconcurrent callers of the same user and is not an authorization credential."),
+    source: zod
+        .enum(["all", "builtin", "mcp"])
+        .default(listToolsQuerySourceDefault)
+        .describe("Return only tools of this source. A filter, not part of a tool's identity."),
+    mcp_server: zod
+        .string()
+        .max(listToolsQueryMcpServerMax)
+        .optional()
+        .describe("Return only this MCP server's tools."),
+    query: zod
+        .string()
+        .max(listToolsQueryQueryMax)
+        .optional()
+        .describe("Words that each must occur in a tool's name, title or description, ignoring case."),
+    read_only: zod
+        .boolean()
+        .default(listToolsQueryReadOnlyDefault)
+        .describe("Sign the control authorization as read-only, so mutating tools are refused."),
     page_size: zod.int().min(1).max(listToolsQueryPageSizeMax).default(listToolsQueryPageSizeDefault),
     page_token: zod.string().max(listToolsQueryPageTokenMax).optional(),
 });
 /**
  * Uses the same current permissions, directory account and graphical session as list-tools.
- * Listing is not a precondition: callers may use a previously discovered ToolRef, and this
+ * Listing is not a precondition: callers may use a previously discovered tool name, and this
  * operation never sends a discovery request or refreshes schemas before executing it.
  * A removed tool or MCP server returns TOOL_NOT_FOUND, as does a direct builtin computer.*
  * call while virtual desktop capability is unavailable. Actual permission errors remain
  * permission errors; a missing target window is not a missing tool. Use list-tools only when
  * discovery or refresh is needed, and do not cache or reuse execution results.
- * Source is explicit: MCP names never select or impersonate builtin tools. The arguments
- * object is at most 256 KiB. The complete result is at most 8 MiB in the protobuf transport,
- * with each encoded image at most 4 MiB; images are converted to base64 once at this JSON
- * boundary, without recompression or persistence. Cancellation is propagated. A timeout,
- * disconnect or failed response does not prove that side effects did not happen; do not
- * automatically replay. operation_id only correlates live activity, not idempotency.
+ * The name selects exactly one tool: builtin tools are computer.*, MCP tools are
+ * `<server>__<tool>`. The arguments object is at most 256 KiB. The complete result is at most
+ * 8 MiB in the protobuf transport, with each encoded image at most 4 MiB; images are converted
+ * to base64 once at this JSON boundary, without recompression or persistence. Cancellation is
+ * propagated. A timeout, disconnect or failed response does not prove that side effects did
+ * not happen; do not automatically replay. operation_id only correlates live activity, not
+ * idempotency.
  * @summary Call a live builtin or external MCP tool
  */
 export const CallToolParams = zod.strictObject({
@@ -1000,10 +1025,13 @@ export const ListSessionsQueryParams = zod.strictObject({
 });
 /**
  * Opens a session for the caller on a machine, as the caller's account, and returns once it
- * is ready. With `desktop` the session has a desktop. Without, Fleet first prepares or reuses
- * the account's separate ready lightweight graphical session, then creates a terminal session
- * with its own SID and lifetime; closing that terminal does not close the account context. Its
- * one terminal runs the caller's login shell from the start, every participant attaches to
+ * is ready. With `desktop` the session requires graphical capability and has a desktop.
+ * Without `desktop`, Fleet creates a terminal session with its own SID and lifetime. If
+ * graphical capability is available, Fleet first prepares or reuses the account's separate
+ * ready lightweight graphical session; otherwise the terminal runs without creating a
+ * graphical context or injecting X environment variables. Closing a terminal does not close
+ * an existing account graphical context. Its one terminal runs the caller's login shell from
+ * the start, every participant attaches to
  * that terminal, and the session ends when the shell exits; a caller who wants another
  * terminal opens another session. Either kind also offers programs, files, ports, sound,
  * devices, printers and privilege approvals. The account is created if the caller has none
@@ -1020,7 +1048,8 @@ export const ListSessionsQueryParams = zod.strictObject({
  *
  * Fails with:
  * - `MACHINE_OFFLINE` when the machine is not connected and does not connect again in time;
- * - `FEATURE_UNAVAILABLE` when the machine does not offer sessions or the graphical backend;
+ * - `FEATURE_UNAVAILABLE` when the machine does not offer the requested session capability;
+ *   a terminal-only request does not require a graphical backend;
  * - `SESSION_UNAVAILABLE` or `SESSION_CLOSED` when its shared account context is not ready or closing;
  * - `USER_HAS_DESKTOP_SESSION` with `desktop` when the account already has a session with a
  *   desktop on the machine, which `metadata.sessionId` names; connect to it instead;