@scitrera/aether-client 0.1.60 → 0.2.1

package/README.md

@@ -282,7 +282,7 @@ await kv.putSync({
 
 ## Progress Reporting
 
-Agents and tasks report progress through the `pg.{workspace}` stream. Users subscribed to the workspace receive filtered updates:
+Agents and tasks report progress through the `pg::{workspace}` stream. Users subscribed to the workspace receive filtered updates:
 
 ```typescript
 agent.reportProgress({
@@ -458,7 +458,7 @@ uniqueTaskTopic("prod", "report", "daily");         // "tu.prod.report.daily"
 taskBroadcastTopic("prod", "worker");               // "tb.prod.worker"
 globalAgentsTopic("prod");                          // "ga.prod"
 eventTopic("task.completed");                       // "event.task.completed"
-bridgeTopic("aether-msgbridge", "discord-1");       // "br.aether-msgbridge.discord-1"
+bridgeTopic("example-bridge", "instance-1");        // "br.example-bridge.instance-1"
 ```
 
 ## Principal Types
@@ -467,15 +467,15 @@ Aether supports 8 principal types. The TypeScript SDK provides dedicated client
 
 | Type | Client Class | Description | Topic Format |
 |------|-------------|-------------|-------------|
-| Agent | `AgentClient` | Persistent entity | `ag.{workspace}.{impl}.{spec}` |
-| UniqueTask | `TaskClient` (with specifier) | Named task | `tu.{workspace}.{impl}.{spec}` |
-| NonUniqueTask | `TaskClient` (no specifier) | Ephemeral task | `ta.{workspace}.{impl}.{id}` |
-| User | `UserClient` | Browser session | `us.{userId}.{windowId}` |
+| Agent | `AgentClient` | Persistent entity | `ag::{workspace}::{impl}::{spec}` |
+| UniqueTask | `TaskClient` (with specifier) | Named task | `tu::{workspace}::{impl}::{spec}` |
+| NonUniqueTask | `TaskClient` (no specifier) | Ephemeral task | `ta::{workspace}::{impl}::{id}` |
+| User | `UserClient` | Browser session | `us::{userId}::{windowId}` |
 | Orchestrator | `OrchestratorClient` | Compute provisioner | receives `TaskAssignment` |
 | WorkflowEngine | `WorkflowEngineClient` | Event processor (singleton) | subscribes to `event.*` |
 | MetricsBridge | `MetricsBridgeClient` | Telemetry collector (singleton) | subscribes to `metric.*` |
-| Bridge | `BridgeClient` | Cross-workspace relay | `br.{impl}.{spec}` |
-| Service | _(no dedicated client)_ | Sidecar service proxy | `sv.{impl}.{spec}` |
+| Bridge | `BridgeClient` | Cross-workspace relay | `br::{impl}::{spec}` |
+| Service | _(no dedicated client)_ | Sidecar service proxy | `sv::{impl}::{spec}` |
 
 > **Known gap:** The TypeScript SDK does not currently have a dedicated `ServiceClient`. The `Service` principal type represents sidecar services addressable via the HTTP proxy feature. If you need to connect as a service principal, use `BridgeClient` (cross-workspace) or `AgentClient` (workspace-scoped) as a workaround and set your identity fields to match the service's `impl`/`spec`. A dedicated `ServiceClient` is planned for a future release.
 
@@ -574,8 +574,8 @@ import { BridgeClient, MessageType } from "@scitrera/aether-client";
 
 const bridge = new BridgeClient({
   address: "localhost:50051",
-  implementation: "aether-msgbridge",
-  specifier: "discord-1",
+  implementation: "example-bridge",
+  specifier: "instance-1",
 });
 
 bridge.onMessage((msg) => {
@@ -642,7 +642,7 @@ agent.switchWorkspace("staging");
 // agent.workspace === "staging"
 
 // UserClient — declares the user's active app workspace to the gateway.
-// Users do not encode a workspace in their identity (topic: us.{userId}.{windowId}),
+// Users do not encode a workspace in their identity (topic: us::{userId}::{windowId}),
 // so calling switchWorkspace right after connect() is recommended to ensure
 // server-side session state has the correct workspace for task-authority scoping.
 await user.connect();
@@ -674,6 +674,14 @@ The connection itself IS the distributed lock AND the heartbeat. When the gRPC s
 
 See the [Go SDK documentation](../go/aether/doc.go) and [Python SDK](../python-client/) for additional API patterns. This TypeScript SDK follows the same conventions.
 
+
 ## License
 
-Apache License, Version 2.0
+Copyright 2025+ scitrera.ai. Licensed under the Apache License, Version 2.0.
+
+## Links
+
+- [GitHub Repository](https://github.com/scitrera/aether)
+- [Documentation](https://github.com/scitrera/aether#readme)
+- [Issue Tracker](https://github.com/scitrera/aether/issues)
+

package/dist/index.cjs

@@ -1448,6 +1448,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 import_meta = {};
 var DEFAULT_CONNECTION = {
@@ -1831,7 +1919,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
@@ -2069,7 +2157,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) {
@@ -2734,7 +2822,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
@@ -3926,7 +4014,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);
@@ -3988,8 +4076,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
@@ -4180,8 +4268,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() {
@@ -4343,7 +4431,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);
@@ -4351,7 +4439,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.
    */
@@ -4425,8 +4513,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
@@ -4909,7 +4997,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);
@@ -4946,8 +5034,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