Move core java code from Wanaku to the Capabilities SDK

This supports fixing issue wanaku-ai/wanaku#673

Author: orpiske

.github/workflows/early-access.yml

@@ -0,0 +1,37 @@
+name: early-access
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  publish-snapshot:
+    name: Publish Snapshot
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: 'zulu'
+          server-id: central
+          server-username: MAVEN_USERNAME
+          server-password: MAVEN_CENTRAL_TOKEN
+          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
+          gpg-passphrase: MAVEN_GPG_PASSPHRASE
+          cache: maven
+
+      - name: Publish snapshot to Maven Central
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_CENTRAL_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
+        run: |
+          export GPG_TTY=$(tty)
+          mvn -Pdist -B --file pom.xml deploy

.github/workflows/main-build.yml

@@ -19,26 +19,16 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout Wanaku Main project
-      uses: actions/checkout@v4
+    - uses: actions/checkout@v4
       with:
-        repository: wanaku-ai/wanaku
+        ref: ${{ github.ref_name }}
         persist-credentials: false
-        ref: main
-        path: wanaku
+        fetch-depth: 0
     - name: Set up JDK 21
       uses: actions/setup-java@v4
       with:
         java-version: '21'
         distribution: 'temurin'
         cache: maven
-    - name: Build Wanaku Main Project
-      run: mvn -DskipTests clean install
-      working-directory: ${{ github.workspace }}/wanaku
-    - uses: actions/checkout@v4
-      with:
-        ref: main
-        persist-credentials: false
-        fetch-depth: 0
     - name: Build with Maven
       run: mvn -B package --file pom.xml

.github/workflows/pr-builds.yml

@@ -41,26 +41,15 @@ jobs:
       fail-fast: true
 
     steps:
-      - name: Checkout Wanaku Main project
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
-          repository: wanaku-ai/wanaku
           persist-credentials: false
-          ref: main
-          path: wanaku
+          fetch-depth: 0
       - name: Set up JDK 21
         uses: actions/setup-java@v4
         with:
           java-version: '21'
           distribution: 'temurin'
           cache: maven
-      - name: Build Wanaku Main Project
-        run: mvn -DskipTests clean install
-        working-directory: ${{ github.workspace }}/wanaku
-      - uses: actions/checkout@v4
-        with:
-          ref: main
-          persist-credentials: false
-          fetch-depth: 0
       - name: Build with Maven
         run: mvn -B package --file pom.xml

.github/workflows/trigger-early-access.yml

@@ -0,0 +1,22 @@
+name: Trigger Early Access
+
+on:
+  schedule:
+    # Run every 2 days at 00:00 UTC
+    - cron: '0 0 */2 * *'
+
+jobs:
+  trigger:
+    name: Trigger Early Access Workflow
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger early-access workflow
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'early-access.yml',
+              ref: 'main'
+            })

capabilities-api/pom.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>ai.wanaku.sdk</groupId>
+        <artifactId>capabilities-parent</artifactId>
+        <version>0.0.9-SNAPSHOT</version>
+        <relativePath>../capabilities-parent/pom.xml</relativePath>
+    </parent>
+
+    <artifactId>capabilities-api</artifactId>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-annotations</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>

capabilities-api/src/main/java/ai/wanaku/capabilities/sdk/api/discovery/DiscoveryCallback.java

@@ -0,0 +1,73 @@
+package ai.wanaku.capabilities.sdk.api.discovery;
+
+import ai.wanaku.capabilities.sdk.api.types.providers.ServiceTarget;
+
+/**
+ * Callback interface for receiving notifications about service registration lifecycle events.
+ *
+ * <p>Implementations of this interface can be registered with a {@link RegistrationManager}
+ * to receive notifications when registration-related operations occur, such as successful
+ * registration, deregistration attempts, or periodic health check pings.</p>
+ *
+ * <p>Callbacks are invoked synchronously after the corresponding operation completes.
+ * If a callback throws an exception, it will be logged but will not prevent other
+ * registered callbacks from executing.</p>
+ *
+ * <p>Usage example:</p>
+ * <pre>{@code
+ * RegistrationManager manager = ...;
+ * manager.addCallBack(new RegistrationCallback() {
+ *     @Override
+ *     public void onRegistration(RegistrationManager manager) {
+ *         // Handle successful registration
+ *     }
+ *
+ *     @Override
+ *     public void onPing(RegistrationManager manager, int status) {
+ *         // Handle ping result
+ *     }
+ *
+ *     @Override
+ *     public void onDeregistration(RegistrationManager manager, int status) {
+ *         // Handle deregistration result
+ *     }
+ * });
+ * }</pre>
+ *
+ * @see RegistrationManager#addCallBack(DiscoveryCallback)
+ */
+public interface DiscoveryCallback {
+
+    /**
+     * Invoked after a ping operation is sent to the discovery service.
+     * This callback is triggered when the service sends a heartbeat to indicate
+     * it is still active and operational.
+     *
+     * @param manager the {@link RegistrationManager} that performed the ping operation
+     * @param target the {@link ServiceTarget} that was pinged
+     * @param status the HTTP status code returned by the ping operation
+     *               (200 indicates success, other values indicate various failure conditions)
+     */
+    void onPing(RegistrationManager manager, ServiceTarget target, int status);
+
+    /**
+     * Invoked after the service has been successfully registered with the discovery service.
+     * This callback is only called when registration completes successfully.
+     *
+     * @param manager the {@link RegistrationManager} that performed the registration
+     * @param target the {@link ServiceTarget} that was registered
+     */
+    void onRegistration(RegistrationManager manager, ServiceTarget target);
+
+    /**
+     * Invoked after a deregistration attempt is made with the discovery service.
+     * This callback is triggered when the service is being shut down or explicitly
+     * removed from the registry.
+     *
+     * @param manager the {@link RegistrationManager} that performed the deregistration operation
+     * @param target the {@link ServiceTarget} that was deregistered
+     * @param status the HTTP status code returned by the deregistration operation
+     *               (200 indicates success, other values indicate various failure conditions)
+     */
+    void onDeregistration(RegistrationManager manager, ServiceTarget target, int status);
+}

capabilities-api/src/main/java/ai/wanaku/capabilities/sdk/api/discovery/RegistrationManager.java

@@ -0,0 +1,55 @@
+package ai.wanaku.capabilities.sdk.api.discovery;
+
+/**
+ * The `RegistrationManager` interface defines the contract for a class responsible for managing the lifecycle
+ * registration of a capability service within the Wanaku ecosystem.
+ *
+ * <p>Implementations of this interface handle the processes of registering, deregistering,
+ * and monitoring the status of a service's registration. It acts as the primary interface
+ * for a capability service to interact with the Wanaku registration mechanism.</p>
+ */
+public interface RegistrationManager {
+
+    /**
+     * Registers the capability service with Wanaku
+     */
+    void register();
+
+    /**
+     * Deregisters the capability service from the Wanaku registration system.
+     * This method notifies the registry that the service is no longer available
+     * or is shutting down, allowing for proper cleanup and resource release.
+     */
+    void deregister();
+
+    /**
+     * Sends a "ping" or heartbeat signal to the Wanaku registration system.
+     * This method is used to periodically inform the registry that the service is still active
+     * and operational, preventing its registration from expiring due to inactivity.
+     */
+    void ping();
+
+    /**
+     * Notifies the Wanaku registration system that the last attempted operation (tool call
+     * or resource acquisition) from this service failed.
+     *
+     * @param reason A descriptive string explaining the reason for the failure.
+     * This information can be used for logging, debugging, or alerting purposes
+     * by the registration system.
+     */
+    void lastAsFail(String reason);
+
+    /**
+     * Notifies the Wanaku registration system that the last attempted operation (tool call
+     * or resource acquisition) from this service was successful.
+     * This method can be used to update the service's status within the registry,
+     * indicating its continued health and availability.
+     */
+    void lastAsSuccessful();
+
+    /**
+     * Adds a callback to be run after some operations have executed
+     * @param callback the callback to add
+     */
+    void addCallBack(DiscoveryCallback callback);
+}

capabilities-api/src/main/java/ai/wanaku/capabilities/sdk/api/exceptions/ConfigurationNotFoundException.java

@@ -0,0 +1,64 @@
+package ai.wanaku.capabilities.sdk.api.exceptions;
+
+/**
+ * This exception can be thrown if a configuration is expected in some way, but it is not found.
+ */
+public class ConfigurationNotFoundException extends WanakuException {
+
+    /**
+     * Constructs a new instance of this exception without a message or cause.
+     */
+    public ConfigurationNotFoundException() {}
+
+    /**
+     * Constructs a new instance of this exception with the specified detail message.
+     *
+     * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method)
+     */
+    public ConfigurationNotFoundException(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new instance of this exception with the specified detail message and cause.
+     *
+     * @param message the detail message (which is saved for later retrieval by the {@link #getMessage()} method)
+     * @param cause   the cause (which is saved for later retrieval by the {@link #getCause()} method)
+     */
+    public ConfigurationNotFoundException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Constructs a new instance of this exception with the specified cause.
+     *
+     * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method)
+     */
+    public ConfigurationNotFoundException(Throwable cause) {
+        super(cause);
+    }
+
+    /**
+     * Constructs a new instance of this exception with the specified detail message, cause,
+     * enable suppression and writable stack trace.
+     *
+     * @param message            the detail message (which is saved for later retrieval by the {@link #getMessage()} method)
+     * @param cause              the cause (which is saved for later retrieval by the {@link #getCause()} method)
+     * @param enableSuppression  whether suppression is enabled
+     * @param writableStackTrace whether stack traces should be writtable
+     */
+    public ConfigurationNotFoundException(
+            String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
+        super(message, cause, enableSuppression, writableStackTrace);
+    }
+
+    /**
+     * Creates a new instance of this exception for the given tool name.
+     *
+     * @param toolName the name of the tool that was not found
+     * @return a new instance of this exception with a message indicating that the tool was not found
+     */
+    public static ConfigurationNotFoundException forName(String toolName) {
+        return new ConfigurationNotFoundException(String.format("Tool %s not found", toolName));
+    }
+}