reis-mobile 0.3.6 → 0.4.0

package/skills/android-appfunctions/references/implementation-configuration.md

@@ -0,0 +1,282 @@
+Specialized instructions for generating Kotlin implementations of AppFunctions,
+handling system-wide configuration, and managing build dependencies.
+
+## Instructions
+
+### Step 1: Configure Gradle dependencies and KSP
+
+Add the following to `build.gradle.kts`. App Functions requires the KSP (Kotlin
+Symbol Processing) plugin.
+
+1. **Version check** : Use library version `1.0.0-alpha10` or later from maven.google.com.
+
+
+```kotlin
+implementation(libs.androidx.appfunctions)
+ksp(libs.androidx.appfunctions.compiler)
+```
+
+<br />
+
+<br />
+
+<br />
+
+### Step 2: Set up app metadata XML
+
+Describe the app's capabilities to the LLM by defining
+`res/xml/app_metadata.xml`.
+
+
+```xml
+<AppFunctionAppMetadata xmlns:appfn="http://schemas.android.com/apk/androidx.appfunctions"
+    appfn:description="This app manages user tasks and reminders.
+    Operational Patterns:
+    - Use 'createTask' to add new tasks or reminders with titles and content.
+    Constraints:
+    - Title or content must be non-null when creating a task."
+    appfn:displayDescription="@string/user_visible_description" />
+```
+
+<br />
+
+Register the service and reference the app metadata in `AndroidManifest.xml`
+within the `<application>` tag:
+
+
+```xml
+<service
+    android:name="com.example.snippets.ai.TaskAppFunctionService"
+    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
+    android:exported="true"
+    tools:targetApi="36">
+    <property
+        android:name="android.app.appfunctions.schema"
+        android:value="app_functions_schema.xsd" />
+    <property
+        android:name="android.app.appfunctions.v2"
+        android:value="task_app_function_service.xml" />
+    <intent-filter>
+        <action android:name="android.app.appfunctions.AppFunctionService" />
+    </intent-filter>
+</service>
+<property
+    android:name="android.app.appfunctions.app_metadata"
+    android:resource="@xml/app_metadata" />
+```
+
+<br />
+
+### Step 3: Implement functions
+
+When generating Kotlin code for AppFunctions, you MUST adhere to these rules:
+
+1. **Annotations** :
+   - Annotate the function with `@AppFunction(isDescribedByKDoc = true)`.
+   - Annotate associated data classes with `@AppFunctionSerializable(isDescribedByKDoc = true)`.
+2. **Parameter strategy** :
+   - **Specificity**: Keep parameters specific. State objects must be unambiguous.
+   - **Optionality**: If a parameter isn't essential, make it optional with a default value.
+3. **Execution and threading** :
+   - Use `suspend` functions.
+   - To avoid blocking the Android UI thread, always run AppFunction implementations on a background dispatcher, such as `withContext(Dispatchers.IO)`.
+4. **Supported types** :
+   - **Primitives** : `Int`, `Long`, `Float`, `Double`, `Boolean`
+   - **Arrays** : `IntArray`, `LongArray`, `FloatArray`, `DoubleArray`, `BooleanArray`
+   - **Native types** : `String`, `PendingIntent`, `Uri`, `LocalTime`, `LocalDate`, `LocalDateTime`, `Instant`. Prefer using `LocalDateTime` or `Instant` for date and time fields.
+   - **Custom objects** : Classes annotated with `@AppFunctionSerializable`.
+   - **Collections** : `List` of any supported non-primitive type
+5. **Default values** :
+   - Use defaults that align with the type's empty state, such as `0` for `Int`, `null` for nullable objects, and `emptyList()` for `List`.
+6. **Error handling** :
+   - Throw subclasses of `androidx.appfunctions.AppFunctionException` to report errors to callers.
+7. **Security** :
+   - Don't expose highly sensitive user data, such as passwords or financial details.
+   - Don't expose irreversible destructive actions without confirmation steps.
+
+### Step 4: Set up dependency injection and service entry points
+
+In version 1.0.0-alpha10 and later, App Functions use the compile-time
+`@AppFunctionServiceEntryPoint` architecture. Create an abstract class extending
+`AppFunctionService` annotated with `@AppFunctionServiceEntryPoint`. KSP
+generates the concrete service class and XML schema.
+
+#### Recommended approach with Hilt
+
+Annotate your service with `@AndroidEntryPoint` and inject your data
+repositories or use cases using standard `@Inject internal lateinit var`:
+
+
+```kotlin
+@RequiresApi(36)
+@AndroidEntryPoint
+@AppFunctionServiceEntryPoint(
+    serviceName = "ConfigAppFunctionServiceHeader",
+    appFunctionXmlFileName = "config_app_function_service_header",
+)
+abstract class BaseAppFunctionServiceHeader : AppFunctionService() {
+    @Inject internal lateinit var messageRepository: MessageRepository
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+#### Framework-agnostic approach with alternative dependency injection or service locators
+
+While Hilt is recommended, many Android applications implement AppFunctions with
+alternative dependency injection frameworks (like Koin, Anvil, or manual Service
+Locators). Because `AppFunctionService` inherits from Android
+`android.app.Service` (and therefore `Context`), you are able access your
+application's DI container directly through `applicationContext` in property
+getters or during service lifecycle execution:
+
+
+```kotlin
+@RequiresApi(36)
+@AppFunctionServiceEntryPoint(
+    serviceName = "ServiceLocatorConfigAppFunctionService",
+    appFunctionXmlFileName = "service_locator_config_app_function_service",
+)
+abstract class BaseAppFunctionServiceLocator : AppFunctionService() {
+    // Example using a manual Service Locator / Application container
+    private val messageRepository by lazy {
+        (applicationContext as AppFunctionApplication).appContainer.messageRepository
+    }
+    // Or with Koin / alternative DI locators:
+    // private val messageRepository: MessageRepository by inject()
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+### Step 5: Architectural cleanliness
+
+Don't attempt to make an `AppFunction` class or method OS-agnostic---App Functions are inherently part of the Android platform integration in `androidx.appfunctions`. For architectural cleanliness, use existing
+application functionality (such as existing repositories, use cases, or domain
+orchestrators) to execute the behavior within your `@AppFunction` methods rather
+than creating redundant abstraction layers around the OS service.
+
+<br />
+
+## Critical constraints
+
+### KSP compliance for serializables
+
+**Critical constraints** : For `@AppFunctionSerializable` data classes, KSP
+only extracts documentation if it's written as inline KDoc directly for each
+property definition. Don't use class-level `@param` or `@property` tags.
+
+### Package integrity
+
+Configuration APIs and the `@AppFunction` annotation are located in
+`androidx.appfunctions`.
+
+## Examples
+
+### Example: Serializable with inline KDoc
+
+
+```kotlin
+/** The parameter to create the task. */
+@AppFunctionSerializable(isDescribedByKDoc = true)
+data class CreateTaskParams(
+    /** The title of the task. */
+    val title: String?,
+    /** The content of the task. */
+    val content: String?,
+)
+
+/** The user-created task. */
+@AppFunctionSerializable(isDescribedByKDoc = true)
+data class Task(
+    /** The ID of the task. */
+    val id: String,
+    /** The title of the task. */
+    val title: String,
+    /** The content of the task. */
+    val content: String,
+)
+```
+
+<br />
+
+<br />
+
+### Example: Implementation detail
+
+
+```kotlin
+@RequiresApi(36)
+@AndroidEntryPoint
+@AppFunctionServiceEntryPoint(
+    serviceName = "TaskAppFunctionService",
+    appFunctionXmlFileName = "task_app_function_service",
+)
+abstract class BaseTaskAppFunctionService : AppFunctionService() {
+    @Inject internal lateinit var taskRepository: TaskRepository
+
+    /**
+     * Creates a task based on [createTaskParams].
+     *
+     * @param createTaskParams The parameter to describe how to create the task.
+     */
+    @AppFunction(isDescribedByKDoc = true)
+    suspend fun createTask(
+        createTaskParams: CreateTaskParams,
+    ): Task = withContext(Dispatchers.IO) {
+        // Developers can use predefined exceptions to let the agent know
+        // why it failed.
+        if (createTaskParams.title == null && createTaskParams.content == null) {
+            throw AppFunctionInvalidArgumentException("Title or content should be non-null")
+        }
+
+        val id = taskRepository.createTask(
+            createTaskParams.title,
+            createTaskParams.content
+        )
+
+        return@withContext taskRepository
+            .getTask(id)
+            ?.toTask()
+            ?: throw AppFunctionElementNotFoundException("Task not found for ID = $id")
+    }
+
+    // Maps internal TaskEntity
+    private fun TaskEntity.toTask() = Task(id = id, title = title, content = description)
+}
+```
+
+<br />
+
+<br />
+
+## Troubleshooting
+
+### Error: "AppFunction unavailable" or "Metadata missing"
+
+**Cause**: The AppSearch indexing failed to extract the schema correctly.
+
+**Solution**:
+
+1. Verify `@AppFunctionSerializable` classes use inline KDoc comments, not class-level `@param` tags.
+2. Check that the `assets/<appFunctionXmlFileName>.xml` file exists in the APK.
+3. Confirm the `ksp("androidx.appfunctions:appfunctions-compiler")` dependency is correctly applied.
+4. Ensure the `ksp` argument `appfunctions:aggregateAppFunctions` is set to `"true"`.

package/skills/android-appfunctions/references/kdoc-refinement-optimization.md

@@ -0,0 +1,75 @@
+Optimizes AppFunction KDoc for AI agents and Model Context Protocol.
+
+## Instructions
+
+### Workflow: Agent-centric documentation
+
+1. **Identify the core outcome** : Start the description with a strong imperative verb, for example, "Search", "Create", or "Update". Focus on the *user benefit*, not the code implementation.
+2. **Workflow dependencies** : Explicitly state if another function must be called first using the standard phrase: **Required workflow: Call "Function
+   A" first to "Objective"**.
+3. **Parameter documentation** :
+   - For **functions** : Use specific `@param` tags. Isolate validation rules and default values here.
+   - For **serializables** : Use inline KDoc directly for each property declaration. KSP **won't** extract documentation from class-level tags.
+4. **Error surface mapping** : Rewrite `@throws` descriptions to provide useful recovery steps for the AI agent, for example "If "Error", suggest the user check their internet connection."
+
+### Workflow: Global app description for server instructions
+
+When writing the `appfn:description` for `app_metadata.xml`, follow these
+instructions:
+
+1. **Capture cross-function relationships**: Explain dependencies or sequences between tools, for example, "Always call 'authenticate' before fetching data.".
+2. **Document operational patterns**: Guide the LLM on token-conserving usage, for example, "Use 'batch_update' over multiple 'update' calls."
+3. **Specify constraints**: Define clear boundaries, for example, "File operations limited to workspace" or "Rate limit: 10 requests per minute."
+4. **Anti-patterns** :
+   - Don't repeat individual function descriptions.
+   - Don't include marketing claims or subjective praise.
+   - Don't attempt to prompt model personality or conversation style.
+
+## Critical constraints
+
+### Descriptive, not imperative
+
+Describe what the function *does* , not what the LLM *must* do. Avoid phrases
+like "You must call this..." in favor of "This function provides...".
+
+### No "fluff"
+
+Remove conversational padding like "This method is used to..." or "Helpful
+for...". Be concise and technical.
+
+### Inline KDoc for serializables
+
+**Mandatory** : For `@AppFunctionSerializable` classes, documentation must be
+inline for each property. KSP ignores class-level `@param` or `@property` tags
+for these classes.
+
+## Examples
+
+### Example: MCP refactoring
+
+**Original**:
+
+`/** This function helps you find people. */`
+
+**Refined**:
+
+     /**
+       * Search for message recipients by name or email.
+       * Required workflow: Call this before "sendMessage" to obtain valid recipient IDs.
+       * @param query Search string for name/email. If null, returns 3 most recent contacts.
+       * @return List of "Recipient" objects matching the query.
+       */
+
+### Example: Global app description
+
+**Refined**:
+
+    This app provides functions for task management and team collaboration.
+
+    Operational Patterns:
+    - Always use 'searchUsers' to resolve user handles to internal IDs before calling 'assignTask'.
+    - Prefer 'batchUpdateStatus' when modifying more than three tasks simultaneously to reduce latency.
+
+    Constraints:
+    - Task titles are limited to 100 characters.
+    - Attachment uploads are limited to 5 MB.

package/skills/android-appfunctions/references/migrate-to-service-entry-point.md

@@ -0,0 +1,226 @@
+Follow this systematic procedure to migrate Android applications that use the
+AppFunctions API in version 1.0.0-alpha09 and lower to the compile-time
+`@AppFunctionServiceEntryPoint` architecture introduced in version
+`1.0.0-alpha10`.
+
+*** ** * ** ***
+
+## Architectural shift overview
+
+In lower versions of the AppFunctions API, for example version `1.0.0-alpha09`:
+
+- Applications require separate dependencies for core functionality, specifically `androidx.appfunctions:appfunctions`, and service components, specifically `androidx.appfunctions:appfunctions-service`.
+- The application implements `AppFunctionConfiguration.Provider` on its `Application` class.
+- You manually register enclosing class instantiation using `AppFunctionConfiguration.Builder().addEnclosingClassFactory(...)`.
+- You place metadata property tags directly under `<application>`.
+
+In version `1.0.0-alpha10` featuring `@AppFunctionServiceEntryPoint`:
+
+- The core and service dependencies are consolidated into a single runtime artifact, `androidx.appfunctions:appfunctions`, which eliminates the need for the standalone `appfunctions-service` library.
+- A dedicated wrapper class extending `AppFunctionService` is annotated with `@AppFunctionServiceEntryPoint` and Hilt's `@AndroidEntryPoint` or an alternative dependency injection framework.
+- The KSP compiler generates a concrete service subclass and an XML metadata schema file in `assets/`.
+- The OS discovers and routes executions using a consolidated `<service>` and `app_metadata` declaration in `AndroidManifest.xml`.
+
+### Strict migration requirements from 1.0.0-alpha09 to 1.0.0-alpha10
+
+When focusing solely on the mandatory API changes required by the new
+`@AppFunctionServiceEntryPoint` architecture, the migration consists of four
+strict requirements that you must complete:
+
+1. **Build dependency consolidation** : Remove the merged `appfunctions-service` dependency while retaining core `appfunctions` and the KSP compiler.
+2. **Service wrapper creation** : Replace the legacy `AppFunctionConfiguration.Provider` on the `Application` class with an abstract class extending `AppFunctionService`, annotated with `@AppFunctionServiceEntryPoint`.
+3. **Annotation and context decoupling** : Move `@AppFunction` annotations to the new wrapper methods and drop `AppFunctionContext` parameters because `AppFunctionService` inherits directly from `Context`.
+4. **Manifest registration** : Register the KSP-generated concrete service in `AndroidManifest.xml` with `BIND_APP_FUNCTION_SERVICE`, the `AppFunctionService` intent filter, and metadata property tags.
+
+*** ** * ** ***
+
+## Systematic migration steps
+
+### Consolidate AppFunctions build dependencies
+
+Remove the standalone `appfunctions-service` library from your module build
+files like `build.gradle.kts` and version catalog like `libs.versions.toml`. In
+version `1.0.0-alpha10`, all core service capabilities are consolidated directly
+within the main `appfunctions` artifact.
+
+    // build.gradle.kts
+    dependencies {
+        implementation(libs.androidx.appfunctions)
+    -   implementation(libs.androidx.appfunctions.service)
+        ksp(libs.androidx.appfunctions.compiler)
+    }
+
+    # libs.versions.toml
+    [versions]
+    appfunctions = "1.0.0-alpha10"
+
+    [libraries]
+    androidx-appfunctions = { module = "androidx.appfunctions:appfunctions", version.ref = "appfunctions" }
+    -   androidx-appfunctions-service = { module = "androidx.appfunctions:appfunctions-service", version.ref = "appfunctions" }
+    androidx-appfunctions-compiler = { module = "androidx.appfunctions:appfunctions-compiler", version.ref = "appfunctions" }
+
+> [!NOTE]
+> **Note:** If another dependency in your project uses snapshot builds like `1.0.0-SNAPSHOT` or custom snapshot repositories from `https://androidx.dev/snapshots/...`, preserve your custom snapshot repository configuration in `settings.gradle.kts`. Otherwise, standard Google Maven repositories resolve `1.0.0-alpha10` directly.
+
+*** ** * ** ***
+
+### Create a dedicated wrapper service extending `AppFunctionService`
+
+Instead of annotating standalone business logic classes or implementing manual
+configuration providers, create an abstract service wrapper across your project,
+for example `BaseAppFunctionService`, extending `AppFunctionService` and
+annotated with `@AppFunctionServiceEntryPoint`.
+
+#### Recommended approach using Hilt
+
+Annotate your service with `@AndroidEntryPoint` and inject your data
+repositories or use cases using standard `@Inject internal lateinit var`:
+
+
+```kotlin
+@RequiresApi(36)
+@AndroidEntryPoint
+@AppFunctionServiceEntryPoint(
+    serviceName = "MyAppFunctionService",
+    appFunctionXmlFileName = "my_app_function_service", // Do NOT include .xml extension
+)
+abstract class BaseAppFunctionService : AppFunctionService() {
+    @Inject internal lateinit var messageRepository: MessageRepository
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+#### Framework-agnostic approach using alternative dependency injection or a service locator
+
+While Hilt is recommended, many Android applications implement AppFunctions with
+alternative dependency injection frameworks like Koin, Anvil, or manual Service
+Locators. Because `AppFunctionService` inherits from Android
+`android.app.Service` and therefore `Context`, you are able access your
+application's DI container directly through `applicationContext` in property
+getters or during service lifecycle execution:
+
+
+```kotlin
+@RequiresApi(36)
+@AppFunctionServiceEntryPoint(
+    serviceName = "ServiceLocatorMyAppFunctionService",
+    appFunctionXmlFileName = "service_locator_my_app_function_service",
+)
+abstract class ServiceLocatorBaseAppFunctionService : AppFunctionService() {
+    // Example using a manual Service Locator or Application container
+    private val messageRepository by lazy {
+        (applicationContext as AppFunctionApplication).appContainer.messageRepository
+    }
+    // Or with Koin / alternative DI locators:
+    // private val messageRepository: MessageRepository by inject()
+
+    @AppFunction(isDescribedByKDoc = true)
+    internal suspend fun send(
+        name: String,
+        endpointValue: String,
+        messageBody: String,
+    ): MessageResult {
+        return messageRepository.send(name, endpointValue, messageBody)
+    }
+}
+```
+
+<br />
+
+> [!IMPORTANT]
+> **Important:** The `appFunctionXmlFileName` parameter, for example `"my_app_function_service"`, mustn't include the `.xml` extension, as the KSP compiler automatically appends `.xml`. Passing `"my_app_function_service.xml"` results in the asset being named `"my_app_function_service.xml.xml"`.
+
+*** ** * ** ***
+
+### Simplify method signatures and decouple context
+
+Remove legacy `AppFunctionContext` parameters from your core methods. When a
+method requires an Android `Context`, for example when constructing a
+`PendingIntent`, access `this` directly from your `AppFunctionService` wrapper
+because the wrapper inherently extends `android.content.Context`.
+
+    -   suspend fun makeCall(appFunctionContext: AppFunctionContext, contactName: String?): PendingIntent
+    +   suspend fun makeCall(contactName: String?): PendingIntent
+
+*** ** * ** ***
+
+### Remove legacy configuration provider
+
+Update your `Application` class by removing
+`AppFunctionConfiguration.Provider` and its associated builder entry points:
+
+    -   abstract class BaseChatApplication : Application(), AppFunctionConfiguration.Provider { ... }
+    +   abstract class BaseChatApplication : Application()
+
+*** ** * ** ***
+
+### Avoid redundant abstraction layers
+
+Don't attempt to make an `AppFunction` class or method OS-agnostic---AppFunctions
+are inherently part of the Android platform integration through the
+`androidx.appfunctions` package. For architectural cleanliness, use existing
+application functionality, such as existing repositories, use cases, or domain
+orchestrators, to execute the behavior within your `@AppFunction` methods rather
+than creating redundant abstraction layers around the OS service.
+
+*** ** * ** ***
+
+### Consolidate service and metadata manifest declarations
+
+Register the KSP-generated service declaration and `app_metadata` property
+inside your module manifest, for example in `src/main/AndroidManifest.xml`
+within the `<application>` tag:
+
+
+```xml
+<service
+    android:name="com.example.snippets.ai.MyAppFunctionService"
+    android:permission="android.permission.BIND_APP_FUNCTION_SERVICE"
+    android:exported="true"
+    tools:targetApi="36">
+    <property
+        android:name="android.app.appfunctions.schema"
+        android:value="app_functions_schema.xsd" />
+    <property
+        android:name="android.app.appfunctions.v2"
+        android:value="my_app_function_service.xml" />
+    <intent-filter>
+        <action android:name="android.app.appfunctions.AppFunctionService" />
+    </intent-filter>
+</service>
+<property
+    android:name="android.app.appfunctions.app_metadata"
+    android:resource="@xml/app_metadata" />
+```
+
+<br />
+
+*** ** * ** ***
+
+## Verification and troubleshooting
+
+1. **Clean rebuild and deploy** : `bash
+   ./gradlew clean installDebug`
+2. **Verify AppSearch discovery / indexing** : Run the following ADB command to
+   confirm the OS successfully discovered and indexed your functions:
+   `bash
+   adb shell cmd app_function list-app-functions`
+   *If your package doesn't appear, confirm that `android.app.appfunctions.v2`
+   matches the exact asset name generated in `assets/`.*
+
+3. **Verify execution using ADB** :
+   `bash
+   adb shell "cmd app_function execute-app-function \
+   --package com.example.chatapp \
+   --function 'com.example.chatapp.appfunctions.BaseAppFunctionService#send' \
+   --parameters '{\"name\": \"Alice\", \"endpointValue\": \"1\", \"messageBody\": \"Hello Alice!\"}'"`