@scitrera/aether-client 0.1.60 → 0.2.1

package/dist/index.d.cts

@@ -321,7 +321,7 @@ interface KVDecrementIfOptions {
 }
 /**
  * A progress update received from an agent or task.
- * Delivered via the pg.{workspace} RabbitMQ stream with server-side filtering.
+ * Delivered via the pg::{workspace} RabbitMQ stream with server-side filtering.
  */
 interface ProgressUpdate {
     /** The identity of the reporting agent/task (topic format). */
@@ -1812,7 +1812,7 @@ declare class AetherClient {
     /**
      * Registers a handler for progress updates from agents/tasks.
      *
-     * Progress updates are delivered via the pg.{workspace} stream with
+     * Progress updates are delivered via the pg::{workspace} stream with
      * server-side recipient filtering.
      *
      * @param handler - Function called when a progress update is received
@@ -1978,7 +1978,7 @@ declare class AetherClient {
     /**
      * Reports progress for a task through the Aether gateway.
      *
-     * Progress updates are routed through RabbitMQ Streams via the pg.{workspace}
+     * Progress updates are routed through RabbitMQ Streams via the pg::{workspace}
      * topic with server-side recipient filtering.
      *
      * @param opts - Progress report options
@@ -2840,7 +2840,7 @@ declare class AgentClient extends AetherClient {
     /**
      * Returns this agent's topic address.
      *
-     * Format: ag.{workspace}.{implementation}.{specifier}
+     * Format: ag::{workspace}::{implementation}::{specifier}
      */
     get topic(): string;
     /** @internal */
@@ -2868,8 +2868,8 @@ declare class AgentClient extends AetherClient {
     /**
      * Sends a message to a specific task.
      *
-     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
      *
      * @param workspace - Target task's workspace
      * @param implementation - Target task's implementation type
@@ -2979,10 +2979,10 @@ interface TaskClientOptions extends AetherClientOptions {
  *
  * Tasks come in two flavors:
  * - **Unique tasks** (with specifier): Persistent identity like agents,
- *   only one connection at a time. Topic: tu.{workspace}.{impl}.{spec}
+ *   only one connection at a time. Topic: tu::{workspace}::{impl}::{spec}
  * - **Non-unique tasks** (empty specifier): Server-assigned ID, multiple
- *   instances allowed. Subscribe to both ta.{workspace}.{impl}.{id} and
- *   the shared tb.{workspace}.{impl} broadcast for work claiming.
+ *   instances allowed. Subscribe to both ta::{workspace}::{impl}::{id} and
+ *   the shared tb::{workspace}::{impl} broadcast for work claiming.
  *
  * @example
  * ```typescript
@@ -3014,8 +3014,8 @@ declare class TaskClient extends AetherClient {
     get isUnique(): boolean;
     /**
      * Returns this task's topic address.
-     * For unique tasks: tu.{workspace}.{impl}.{spec}
-     * For non-unique tasks: returns the broadcast topic tb.{workspace}.{impl}
+     * For unique tasks: tu::{workspace}::{impl}::{spec}
+     * For non-unique tasks: returns the broadcast topic tb::{workspace}::{impl}
      * (the actual instance topic is assigned by the server).
      */
     get topic(): string;
@@ -3143,13 +3143,13 @@ declare class UserClient extends AetherClient {
     /**
      * Returns this user's topic address.
      *
-     * Format: us.{userId}.{windowId}
+     * Format: us::{userId}::{windowId}
      */
     get topic(): string;
     /**
      * Returns this user's workspace-scoped topic address.
      *
-     * Format: uw.{userId}.{workspace}
+     * Format: uw::{userId}::{workspace}
      *
      * Returns empty string if no workspace is set.
      */
@@ -3187,8 +3187,8 @@ declare class UserClient extends AetherClient {
     /**
      * Sends a message to a specific task.
      *
-     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
      *
      * @param workspace - Target task's workspace
      * @param implementation - Target task's implementation type
@@ -3609,7 +3609,7 @@ interface BridgeClientOptions extends AetherClientOptions {
  * - Identity management (implementation, specifier)
  * - Messaging helpers to any workspace (sendToAgent, sendToUser, sendToTask, broadcast)
  *
- * Topic format: br.{implementation}.{specifier}
+ * Topic format: br::{implementation}::{specifier}
  *
  * @example
  * ```typescript
@@ -3650,7 +3650,7 @@ declare class BridgeClient extends AetherClient {
     /**
      * Returns this bridge's topic address.
      *
-     * Format: br.{implementation}.{specifier}
+     * Format: br::{implementation}::{specifier}
      */
     get topic(): string;
     /** @internal */
@@ -3668,8 +3668,8 @@ declare class BridgeClient extends AetherClient {
     /**
      * Sends a message to a specific task in any workspace.
      *
-     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
      *
      * @param workspace - Target task's workspace
      * @param implementation - Target task's implementation type

package/dist/index.d.ts

@@ -321,7 +321,7 @@ interface KVDecrementIfOptions {
 }
 /**
  * A progress update received from an agent or task.
- * Delivered via the pg.{workspace} RabbitMQ stream with server-side filtering.
+ * Delivered via the pg::{workspace} RabbitMQ stream with server-side filtering.
  */
 interface ProgressUpdate {
     /** The identity of the reporting agent/task (topic format). */
@@ -1812,7 +1812,7 @@ declare class AetherClient {
     /**
      * Registers a handler for progress updates from agents/tasks.
      *
-     * Progress updates are delivered via the pg.{workspace} stream with
+     * Progress updates are delivered via the pg::{workspace} stream with
      * server-side recipient filtering.
      *
      * @param handler - Function called when a progress update is received
@@ -1978,7 +1978,7 @@ declare class AetherClient {
     /**
      * Reports progress for a task through the Aether gateway.
      *
-     * Progress updates are routed through RabbitMQ Streams via the pg.{workspace}
+     * Progress updates are routed through RabbitMQ Streams via the pg::{workspace}
      * topic with server-side recipient filtering.
      *
      * @param opts - Progress report options
@@ -2840,7 +2840,7 @@ declare class AgentClient extends AetherClient {
     /**
      * Returns this agent's topic address.
      *
-     * Format: ag.{workspace}.{implementation}.{specifier}
+     * Format: ag::{workspace}::{implementation}::{specifier}
      */
     get topic(): string;
     /** @internal */
@@ -2868,8 +2868,8 @@ declare class AgentClient extends AetherClient {
     /**
      * Sends a message to a specific task.
      *
-     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
      *
      * @param workspace - Target task's workspace
      * @param implementation - Target task's implementation type
@@ -2979,10 +2979,10 @@ interface TaskClientOptions extends AetherClientOptions {
  *
  * Tasks come in two flavors:
  * - **Unique tasks** (with specifier): Persistent identity like agents,
- *   only one connection at a time. Topic: tu.{workspace}.{impl}.{spec}
+ *   only one connection at a time. Topic: tu::{workspace}::{impl}::{spec}
  * - **Non-unique tasks** (empty specifier): Server-assigned ID, multiple
- *   instances allowed. Subscribe to both ta.{workspace}.{impl}.{id} and
- *   the shared tb.{workspace}.{impl} broadcast for work claiming.
+ *   instances allowed. Subscribe to both ta::{workspace}::{impl}::{id} and
+ *   the shared tb::{workspace}::{impl} broadcast for work claiming.
  *
  * @example
  * ```typescript
@@ -3014,8 +3014,8 @@ declare class TaskClient extends AetherClient {
     get isUnique(): boolean;
     /**
      * Returns this task's topic address.
-     * For unique tasks: tu.{workspace}.{impl}.{spec}
-     * For non-unique tasks: returns the broadcast topic tb.{workspace}.{impl}
+     * For unique tasks: tu::{workspace}::{impl}::{spec}
+     * For non-unique tasks: returns the broadcast topic tb::{workspace}::{impl}
      * (the actual instance topic is assigned by the server).
      */
     get topic(): string;
@@ -3143,13 +3143,13 @@ declare class UserClient extends AetherClient {
     /**
      * Returns this user's topic address.
      *
-     * Format: us.{userId}.{windowId}
+     * Format: us::{userId}::{windowId}
      */
     get topic(): string;
     /**
      * Returns this user's workspace-scoped topic address.
      *
-     * Format: uw.{userId}.{workspace}
+     * Format: uw::{userId}::{workspace}
      *
      * Returns empty string if no workspace is set.
      */
@@ -3187,8 +3187,8 @@ declare class UserClient extends AetherClient {
     /**
      * Sends a message to a specific task.
      *
-     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
      *
      * @param workspace - Target task's workspace
      * @param implementation - Target task's implementation type
@@ -3609,7 +3609,7 @@ interface BridgeClientOptions extends AetherClientOptions {
  * - Identity management (implementation, specifier)
  * - Messaging helpers to any workspace (sendToAgent, sendToUser, sendToTask, broadcast)
  *
- * Topic format: br.{implementation}.{specifier}
+ * Topic format: br::{implementation}::{specifier}
  *
  * @example
  * ```typescript
@@ -3650,7 +3650,7 @@ declare class BridgeClient extends AetherClient {
     /**
      * Returns this bridge's topic address.
      *
-     * Format: br.{implementation}.{specifier}
+     * Format: br::{implementation}::{specifier}
      */
     get topic(): string;
     /** @internal */
@@ -3668,8 +3668,8 @@ declare class BridgeClient extends AetherClient {
     /**
      * Sends a message to a specific task in any workspace.
      *
-     * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-     * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+     * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+     * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
      *
      * @param workspace - Target task's workspace
      * @param implementation - Target task's implementation type

package/dist/index.js

@@ -1340,6 +1340,94 @@ function extractGrant(response) {
   return grant;
 }
 
+// package.json
+var package_default = {
+  name: "@scitrera/aether-client",
+  version: "0.2.1",
+  description: "TypeScript/JavaScript SDK for the Aether distributed control plane",
+  license: "Apache-2.0",
+  author: "scitrera.ai",
+  homepage: "https://memorylayer.ai",
+  repository: {
+    type: "git",
+    url: "https://github.com/scitrera/aether",
+    directory: "sdk/typescript"
+  },
+  type: "module",
+  main: "./dist/index.cjs",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      import: {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      },
+      require: {
+        types: "./dist/index.d.cts",
+        default: "./dist/index.cjs"
+      }
+    }
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    lint: "tsc --noEmit",
+    clean: "rm -rf dist"
+  },
+  dependencies: {
+    "@grpc/grpc-js": "1.14.3",
+    "@grpc/proto-loader": "0.8.1"
+  },
+  devDependencies: {
+    typescript: "^5.4.0",
+    tsup: "^8.0.0",
+    vitest: "^1.4.0"
+  },
+  engines: {
+    node: ">=18.0.0"
+  },
+  keywords: [
+    "aether",
+    "scitrera",
+    "grpc",
+    "distributed",
+    "control-plane",
+    "messaging"
+  ]
+};
+
+// src/version-meta.ts
+var CLIENT_SDK_NAME = "ts";
+var cachedMeta;
+function clientVersionMeta() {
+  if (cachedMeta !== void 0) {
+    return cachedMeta;
+  }
+  const version = package_default.version ?? "unknown";
+  let runtime = "unknown";
+  let os = "unknown";
+  if (typeof process !== "undefined" && process.versions && process.versions.node) {
+    runtime = `node${process.versions.node}`;
+    os = `${process.platform}/${process.arch}`;
+  } else if (typeof navigator !== "undefined") {
+    runtime = "browser";
+    os = navigator.userAgent ?? "browser";
+  }
+  cachedMeta = {
+    clientVersion: version,
+    clientSdk: CLIENT_SDK_NAME,
+    clientBuildInfo: { runtime, os }
+  };
+  return cachedMeta;
+}
+
 // src/client.ts
 var DEFAULT_CONNECTION = {
   maxRetries: 5,
@@ -1722,7 +1810,7 @@ var AetherClient = class {
   /**
    * Registers a handler for progress updates from agents/tasks.
    *
-   * Progress updates are delivered via the pg.{workspace} stream with
+   * Progress updates are delivered via the pg::{workspace} stream with
    * server-side recipient filtering.
    *
    * @param handler - Function called when a progress update is received
@@ -1960,7 +2048,7 @@ var AetherClient = class {
       stream.on("end", () => {
         this._handleStreamEnd();
       });
-      const initMsg = this._buildInitMessage();
+      const initMsg = { ...clientVersionMeta(), ...this._buildInitMessage() };
       stream.write({ init: initMsg });
     } catch (err) {
       if (err instanceof ConnectionError) {
@@ -2625,7 +2713,7 @@ var AetherClient = class {
   /**
    * Reports progress for a task through the Aether gateway.
    *
-   * Progress updates are routed through RabbitMQ Streams via the pg.{workspace}
+   * Progress updates are routed through RabbitMQ Streams via the pg::{workspace}
    * topic with server-side recipient filtering.
    *
    * @param opts - Progress report options
@@ -3817,7 +3905,7 @@ var AgentClient = class extends AetherClient {
   /**
    * Returns this agent's topic address.
    *
-   * Format: ag.{workspace}.{implementation}.{specifier}
+   * Format: ag::{workspace}::{implementation}::{specifier}
    */
   get topic() {
     return agentTopic(this._workspace, this._implementation, this._specifier);
@@ -3879,8 +3967,8 @@ var AgentClient = class extends AetherClient {
   /**
    * Sends a message to a specific task.
    *
-   * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-   * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+   * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+   * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
    *
    * @param workspace - Target task's workspace
    * @param implementation - Target task's implementation type
@@ -4071,8 +4159,8 @@ var TaskClient = class extends AetherClient {
   }
   /**
    * Returns this task's topic address.
-   * For unique tasks: tu.{workspace}.{impl}.{spec}
-   * For non-unique tasks: returns the broadcast topic tb.{workspace}.{impl}
+   * For unique tasks: tu::{workspace}::{impl}::{spec}
+   * For non-unique tasks: returns the broadcast topic tb::{workspace}::{impl}
    * (the actual instance topic is assigned by the server).
    */
   get topic() {
@@ -4234,7 +4322,7 @@ var UserClient = class extends AetherClient {
   /**
    * Returns this user's topic address.
    *
-   * Format: us.{userId}.{windowId}
+   * Format: us::{userId}::{windowId}
    */
   get topic() {
     return userTopic(this._userId, this._windowId);
@@ -4242,7 +4330,7 @@ var UserClient = class extends AetherClient {
   /**
    * Returns this user's workspace-scoped topic address.
    *
-   * Format: uw.{userId}.{workspace}
+   * Format: uw::{userId}::{workspace}
    *
    * Returns empty string if no workspace is set.
    */
@@ -4316,8 +4404,8 @@ var UserClient = class extends AetherClient {
   /**
    * Sends a message to a specific task.
    *
-   * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-   * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+   * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+   * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
    *
    * @param workspace - Target task's workspace
    * @param implementation - Target task's implementation type
@@ -4800,7 +4888,7 @@ var BridgeClient = class extends AetherClient {
   /**
    * Returns this bridge's topic address.
    *
-   * Format: br.{implementation}.{specifier}
+   * Format: br::{implementation}::{specifier}
    */
   get topic() {
     return bridgeTopic(this._implementation, this._specifier);
@@ -4837,8 +4925,8 @@ var BridgeClient = class extends AetherClient {
   /**
    * Sends a message to a specific task in any workspace.
    *
-   * For unique tasks (with specifier), uses tu.{workspace}.{impl}.{spec} topic.
-   * For non-unique tasks (empty specifier), uses tb.{workspace}.{impl} broadcast topic.
+   * For unique tasks (with specifier), uses tu::{workspace}::{impl}::{spec} topic.
+   * For non-unique tasks (empty specifier), uses tb::{workspace}::{impl} broadcast topic.
    *
    * @param workspace - Target task's workspace
    * @param implementation - Target task's implementation type