feat(computer-use): ask for missing macOS permissions in the conversation

packages/plugin-sdk/src/contracts.ts

@@ -10209,6 +10209,36 @@ export const contracts = {
                       'authorityRevision',
                     ],
                   },
+                  {
+                    description:
+                      'Missing operating-system grants the waiting tool call needs. The producer\npolls the real grant state and commits `SystemPermissionGranted` itself;\nthe user can only cancel.',
+                    type: 'object',
+                    properties: {
+                      kind: {
+                        type: 'string',
+                        const: 'system_permission',
+                      },
+                      toolUseId: {
+                        type: 'string',
+                      },
+                      grants: {
+                        description: 'Distinct missing grants.',
+                        type: 'array',
+                        items: {
+                          $ref: '#/$defs/SystemPermissionGrant',
+                        },
+                        minItems: 1,
+                      },
+                      application: {
+                        description:
+                          'The application name the operating system lists in its settings.',
+                        type: 'string',
+                        minLength: 1,
+                      },
+                    },
+                    additionalProperties: false,
+                    required: ['kind', 'toolUseId', 'grants', 'application'],
+                  },
                 ],
               },
               PermissionBasis: {
@@ -10773,6 +10803,23 @@ export const contracts = {
                 type: 'string',
                 enum: ['low', 'high'],
               },
+              SystemPermissionGrant: {
+                description:
+                  'A macOS privacy grant (TCC) that the Host process itself needs before native\nComputer Use can run. This is operating-system state the user changes in\nSystem Settings, not a Maka grant; the Host observes it and commits the outcome.',
+                oneOf: [
+                  {
+                    description: 'System Settings > Privacy & Security > Accessibility.',
+                    type: 'string',
+                    const: 'accessibility',
+                  },
+                  {
+                    description:
+                      'System Settings > Privacy & Security > Screen & System Audio Recording.',
+                    type: 'string',
+                    const: 'screen_recording',
+                  },
+                ],
+              },
               InteractionOutcome: {
                 oneOf: [
                   {
@@ -10927,6 +10974,24 @@ export const contracts = {
                     additionalProperties: false,
                     required: ['kind', 'decision', 'committedAt'],
                   },
+                  {
+                    description:
+                      'Producer-committed once every requested system grant is present; no answer maps here.',
+                    type: 'object',
+                    properties: {
+                      kind: {
+                        type: 'string',
+                        const: 'system_permission_granted',
+                      },
+                      committedAt: {
+                        type: 'integer',
+                        format: 'uint64',
+                        minimum: 0,
+                      },
+                    },
+                    additionalProperties: false,
+                    required: ['kind', 'committedAt'],
+                  },
                   {
                     type: 'object',
                     properties: {
@@ -14062,6 +14127,7 @@ export const contracts = {
                   'form',
                   'client_capability',
                   'computer_app',
+                  'system_permission',
                 ],
               },
             },
@@ -16565,6 +16631,17 @@ export const contracts = {
                     additionalProperties: false,
                     required: ['kind'],
                   },
+                  {
+                    type: 'object',
+                    properties: {
+                      kind: {
+                        type: 'string',
+                        const: 'system_permission_cancel',
+                      },
+                    },
+                    additionalProperties: false,
+                    required: ['kind'],
+                  },
                 ],
               },
               Decision: {
@@ -16988,6 +17065,36 @@ export const contracts = {
                       'authorityRevision',
                     ],
                   },
+                  {
+                    description:
+                      'Missing operating-system grants the waiting tool call needs. The producer\npolls the real grant state and commits `SystemPermissionGranted` itself;\nthe user can only cancel.',
+                    type: 'object',
+                    properties: {
+                      kind: {
+                        type: 'string',
+                        const: 'system_permission',
+                      },
+                      toolUseId: {
+                        type: 'string',
+                      },
+                      grants: {
+                        description: 'Distinct missing grants.',
+                        type: 'array',
+                        items: {
+                          $ref: '#/$defs/SystemPermissionGrant',
+                        },
+                        minItems: 1,
+                      },
+                      application: {
+                        description:
+                          'The application name the operating system lists in its settings.',
+                        type: 'string',
+                        minLength: 1,
+                      },
+                    },
+                    additionalProperties: false,
+                    required: ['kind', 'toolUseId', 'grants', 'application'],
+                  },
                 ],
               },
               PermissionBasis: {
@@ -17552,6 +17659,23 @@ export const contracts = {
                 type: 'string',
                 enum: ['low', 'high'],
               },
+              SystemPermissionGrant: {
+                description:
+                  'A macOS privacy grant (TCC) that the Host process itself needs before native\nComputer Use can run. This is operating-system state the user changes in\nSystem Settings, not a Maka grant; the Host observes it and commits the outcome.',
+                oneOf: [
+                  {
+                    description: 'System Settings > Privacy & Security > Accessibility.',
+                    type: 'string',
+                    const: 'accessibility',
+                  },
+                  {
+                    description:
+                      'System Settings > Privacy & Security > Screen & System Audio Recording.',
+                    type: 'string',
+                    const: 'screen_recording',
+                  },
+                ],
+              },
               InteractionOutcome: {
                 oneOf: [
                   {
@@ -17706,6 +17830,24 @@ export const contracts = {
                     additionalProperties: false,
                     required: ['kind', 'decision', 'committedAt'],
                   },
+                  {
+                    description:
+                      'Producer-committed once every requested system grant is present; no answer maps here.',
+                    type: 'object',
+                    properties: {
+                      kind: {
+                        type: 'string',
+                        const: 'system_permission_granted',
+                      },
+                      committedAt: {
+                        type: 'integer',
+                        format: 'uint64',
+                        minimum: 0,
+                      },
+                    },
+                    additionalProperties: false,
+                    required: ['kind', 'committedAt'],
+                  },
                   {
                     type: 'object',
                     properties: {
@@ -23525,6 +23667,7 @@ export const contracts = {
                   'form',
                   'client_capability',
                   'computer_app',
+                  'system_permission',
                 ],
               },
               AgentComputerApps: {

packages/plugin-sdk/src/generated/runtime.ts

@@ -3273,7 +3273,8 @@ export type AgentInteractionKind =
   | 'permissions'
   | 'form'
   | 'client_capability'
-  | 'computer_app';
+  | 'computer_app'
+  | 'system_permission';
 export type InteractionAnswer =
   | {
       kind: 'service_approval';
@@ -3317,6 +3318,9 @@ export type InteractionAnswer =
     }
   | {
       kind: 'computer_app_cancel';
+    }
+  | {
+      kind: 'system_permission_cancel';
     };
 export type Decision = 'allow' | 'deny';
 export type Decision2 =
@@ -3387,6 +3391,20 @@ export type InteractionRequest =
       display: ComputerAppDisplay;
       allowAlways: boolean;
       authorityRevision: number;
+    }
+  | {
+      kind: 'system_permission';
+      toolUseId: string;
+      /**
+       * Distinct missing grants.
+       *
+       * @minItems 1
+       */
+      grants: [SystemPermissionGrant, ...SystemPermissionGrant[]];
+      /**
+       * The application name the operating system lists in its settings.
+       */
+      application: string;
     };
 export type FormField = {
   name: string;
@@ -3468,6 +3486,12 @@ export type GrantScope =
     };
 export type ComputerAppPlatform = 'macos' | 'windows';
 export type ComputerAppRisk = 'low' | 'high';
+/**
+ * A macOS privacy grant (TCC) that the Host process itself needs before native
+ * Computer Use can run. This is operating-system state the user changes in
+ * System Settings, not a Maka grant; the Host observes it and commits the outcome.
+ */
+export type SystemPermissionGrant = 'accessibility' | 'screen_recording';
 export type InteractionOutcome =
   | {
       kind: 'service_approval_decision';
@@ -3515,6 +3539,10 @@ export type InteractionOutcome =
       decision: ComputerAppDecision;
       committedAt: number;
     }
+  | {
+      kind: 'system_permission_granted';
+      committedAt: number;
+    }
   | {
       kind: 'closure';
       reason: ClosureReason;

platform/computer-use/src/lib.rs

@@ -63,6 +63,7 @@ mod permission_subject;
 pub mod protocol;
 #[cfg(feature = "native-desktop")]
 mod session;
+pub mod system_permission;
 #[cfg(all(feature = "native-desktop", target_os = "windows"))]
 mod windows_permission_subject;
 

platform/computer-use/src/macos/tcc.rs

@@ -205,18 +205,44 @@ fn path_of(pid: libc::pid_t) -> Option<String> {
     String::from_utf8(buffer).ok()
 }
 
-pub(crate) fn require(grant: Grant) -> Result<(), ToolError> {
+impl From<maka_agent_facts::interaction::SystemPermissionGrant> for Grant {
+    fn from(grant: maka_agent_facts::interaction::SystemPermissionGrant) -> Self {
+        use maka_agent_facts::interaction::SystemPermissionGrant;
+        match grant {
+            SystemPermissionGrant::Accessibility => Self::Accessibility,
+            SystemPermissionGrant::ScreenRecording => Self::ScreenRecording,
+        }
+    }
+}
+
+/// Whether the grant is in effect, confirming it with a real call when it
+/// has not been confirmed yet. It blocks for the call.
+pub(crate) fn present(grant: Grant) -> bool {
     if grant.confirmed().load(Ordering::Relaxed) {
-        return Ok(());
+        return true;
     }
-    if grant.observed() {
+    let observed = grant.observed();
+    if observed {
         grant.confirmed().store(true, Ordering::Relaxed);
-        return Ok(());
     }
+    observed
+}
+
+/// Asks macOS to show its request for the grant, once per Host. Returns
+/// whether this call asked.
+pub(crate) fn ask(grant: Grant) -> bool {
     let asked = !grant.asked().swap(true, Ordering::Relaxed);
     if asked {
         grant.request();
     }
+    asked
+}
+
+pub(crate) fn require(grant: Grant) -> Result<(), ToolError> {
+    if present(grant) {
+        return Ok(());
+    }
+    let asked = ask(grant);
     Err(ToolError::Failed(message(
         grant,
         &responsible_application(),
@@ -253,6 +279,11 @@ fn suspect(error: &ToolError) -> Option<Grant> {
     }
 }
 
+/// The failure for a grant still missing after the user was asked.
+pub(crate) fn still_missing(grant: Grant, application: &str) -> String {
+    message(grant, application, false)
+}
+
 /// The tool error for a missing grant. `permission_required:` is the stable
 /// prefix; the rest tells the user which switch to turn on.
 fn message(grant: Grant, application: &str, asked: bool) -> String {
@@ -271,7 +302,7 @@ fn message(grant: Grant, application: &str, asked: bool) -> String {
 }
 
 /// The name macOS shows for the process that holds this Host's grants.
-fn responsible_application() -> String {
+pub(crate) fn responsible_application() -> String {
     responsible_path()
         .map(|path| application_name(&path))
         .unwrap_or_else(|| "the application that started Maka".into())