Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

update sdk naming

Justin D'Souza7140afba7c5e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 835f2180..cfd94ac4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,24 +19,24 @@ jobs:
with:
node-version: ${{ matrix.node-version }}
cache: npm
- cache-dependency-path: packages/asymptote-observe-js/package-lock.json
+ cache-dependency-path: packages/asymptote-sdk-js/package-lock.json
- name: Install SDK dependencies
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm ci
- name: Test SDK
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm test
- name: Type-check SDK
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run check
- name: Build SDK
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run build
- name: Validate SDK package contents
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run pack:dry-run
- name: Smoke install SDK package
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run pack:smoke
go-test:
diff --git a/.github/workflows/npm-publish-sdk.yml b/.github/workflows/npm-publish-sdk.yml
index c4e6f812..0a544563 100644
--- a/.github/workflows/npm-publish-sdk.yml
+++ b/.github/workflows/npm-publish-sdk.yml
@@ -4,7 +4,7 @@ on:
workflow_dispatch:
push:
tags:
- - observe-js-v*
+ - sdk-js-v*
permissions:
contents: read
@@ -20,22 +20,22 @@ jobs:
node-version: 24
registry-url: https://registry.npmjs.org
cache: npm
- cache-dependency-path: packages/asymptote-observe-js/package-lock.json
+ cache-dependency-path: packages/asymptote-sdk-js/package-lock.json
- name: Install SDK dependencies
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm ci
- name: Test SDK
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm test
- name: Type-check SDK
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run check
- name: Build SDK
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run build
- name: Smoke install SDK package
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm run pack:smoke
- name: Publish SDK to npm
- working-directory: packages/asymptote-observe-js
+ working-directory: packages/asymptote-sdk-js
run: npm publish --access public --provenance
diff --git a/CLAUDE.md b/CLAUDE.md
index 438aa2c7..d34afe7f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,7 +9,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.
- `cli/beacon`: public `beacon` CLI and endpoint runtime.
- `cli/beacon-hooks`: hook adapter invoked by Cursor and other supported runtimes.
- `collector-builder`: OpenTelemetry Collector distribution and Beacon JSONL exporter.
-- `packages/asymptote-observe-js`: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.
+- `packages/asymptote-sdk-js`: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.
- `packaging`: macOS packaging and deployment assets.
Do not recreate or depend on removed `asymptote` mirror trees. Keep new work focused on the Beacon paths above.
@@ -88,7 +88,7 @@ go test ./...
Run TypeScript SDK checks:
```bash
-cd packages/asymptote-observe-js
+cd packages/asymptote-sdk-js
npm test
npm run check
npm run build
@@ -129,7 +129,7 @@ Run the release gates before publishing:
cd cli/beacon && go test ./...
cd ../beacon-hooks && go test ./...
cd ../../collector-builder/exporter/beaconjsonexporter && go test ./...
-cd ../../../packages/asymptote-observe-js && npm test && npm run check && npm run build && npm run pack:dry-run
+cd ../../../packages/asymptote-sdk-js && npm test && npm run check && npm run build && npm run pack:dry-run
cd ../..
sh packaging/macos/test-endpoint-scripts.sh
```
diff --git a/packages/asymptote-observe-js/README.md b/packages/asymptote-sdk-js/README.md
similarity index 60%
rename from packages/asymptote-observe-js/README.md
rename to packages/asymptote-sdk-js/README.md
index d4c658a2..3270d49c 100644
--- a/packages/asymptote-observe-js/README.md
+++ b/packages/asymptote-sdk-js/README.md
@@ -1,20 +1,21 @@
-# Asymptote Observe TypeScript SDK
+# Asymptote TypeScript SDK
-Asymptote Observe instruments cloud-hosted agent apps and exports OpenTelemetry
-spans that remain compatible with Beacon's normalized JSONL event schema.
+The Asymptote SDK instruments cloud-hosted agent apps through the `Observe`
+module and exports OpenTelemetry spans that remain compatible with Beacon's
+normalized JSONL event schema.
## Hosted Asymptote Observe
```bash
-npm install @asymptote-labs/observe
-export ASYMPTOTE_OBSERVE_API_KEY=...
+npm install @asymptote/sdk
+export ASYMPTOTE_API_KEY=...
```
```typescript
-import { AsymptoteObserve } from "@asymptote-labs/observe";
+import { Observe } from "@asymptote/sdk";
-AsymptoteObserve.initialize({
- apiKey: process.env.ASYMPTOTE_OBSERVE_API_KEY,
+Observe.initialize({
+ apiKey: process.env.ASYMPTOTE_API_KEY,
});
```
@@ -23,8 +24,8 @@ Hosted Observe contract:
- Transport: OpenTelemetry over HTTP.
- Default base URL: `https://api.asymptotelabs.ai`.
- Observe path: `/v1/observe` is appended when the endpoint does not already include it.
-- Auth: `authorization: Bearer <ASYMPTOTE_OBSERVE_API_KEY>`.
-- Override base URL with `ASYMPTOTE_OBSERVE_BASE_URL` or `initialize({ baseUrl })`.
+- Auth: `authorization: Bearer <ASYMPTOTE_API_KEY>`.
+- Override base URL with `ASYMPTOTE_BASE_URL` or `initialize({ baseUrl })`.
The TypeScript SDK preserves this hosted contract, but this repository does not
implement the managed ingest service. Use `baseUrl` with a local stub in tests.
@@ -32,10 +33,10 @@ implement the managed ingest service. Use `baseUrl` with a local stub in tests.
## Local Or Customer-Managed Observe Export
```typescript
-import { AsymptoteObserve } from "@asymptote-labs/observe";
+import { Observe } from "@asymptote/sdk";
-AsymptoteObserve.initialize({
- otlpEndpoint: process.env.ASYMPTOTE_OBSERVE_ENDPOINT,
+Observe.initialize({
+ otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
});
```
@@ -46,9 +47,8 @@ attributes documented in `docs/asymptote-observe-sdk.md`.
Endpoint precedence:
1. `initialize({ otlpEndpoint })`
-2. `ASYMPTOTE_OBSERVE_ENDPOINT`
-3. `OTEL_EXPORTER_OTLP_ENDPOINT`
-4. hosted `baseUrl` when an API key is present
+2. `OTEL_EXPORTER_OTLP_ENDPOINT`
+3. hosted `baseUrl` when an API key is present
Beacon endpoint installs remain local-first and never require hosted credentials.
@@ -59,10 +59,10 @@ as early as possible, then use existing OpenLLMetry instrumentations for common
provider SDKs.
```typescript
-import { AsymptoteObserve } from "@asymptote-labs/observe";
+import { Observe } from "@asymptote/sdk";
-AsymptoteObserve.initialize({
- apiKey: process.env.ASYMPTOTE_OBSERVE_API_KEY,
+Observe.initialize({
+ apiKey: process.env.ASYMPTOTE_API_KEY,
});
```
@@ -70,8 +70,8 @@ By default the SDK enables OpenAI and Anthropic OpenLLMetry instrumentations.
Disable or configure them if needed:
```typescript
-AsymptoteObserve.initialize({
- apiKey: process.env.ASYMPTOTE_OBSERVE_API_KEY,
+Observe.initialize({
+ apiKey: process.env.ASYMPTOTE_API_KEY,
instrumentationOptions: {
openAI: { traceContent: true },
anthropic: false,
@@ -80,7 +80,7 @@ AsymptoteObserve.initialize({
```
If your app already owns OpenTelemetry setup, use
-`AsymptoteObserve.instrumentations()` with that provider instead of calling
+`Observe.instrumentations()` with that provider instead of calling
`initialize()` twice.
## Vercel AI SDK
@@ -88,12 +88,12 @@ If your app already owns OpenTelemetry setup, use
```typescript
import { registerTelemetry } from "ai";
import { OpenTelemetry } from "@ai-sdk/otel";
-import { AsymptoteObserve } from "@asymptote-labs/observe";
+import { Observe } from "@asymptote/sdk";
-AsymptoteObserve.initialize();
+Observe.initialize();
registerTelemetry(new OpenTelemetry({
- tracer: AsymptoteObserve.getTracer(),
+ tracer: Observe.getTracer(),
}));
```
@@ -101,11 +101,11 @@ registerTelemetry(new OpenTelemetry({
```typescript
import { query as originalQuery } from "@anthropic-ai/claude-agent-sdk";
-import { AsymptoteObserve } from "@asymptote-labs/observe";
+import { Observe } from "@asymptote/sdk";
-AsymptoteObserve.initialize();
+Observe.initialize();
-const query = AsymptoteObserve.wrapClaudeAgentQuery(originalQuery);
+const query = Observe.wrapClaudeAgentQuery(originalQuery);
```
For the first SDK release, prefer provider-level Anthropic/OpenLLMetry
@@ -115,7 +115,7 @@ SDK hooks are deferred until those paths leave important telemetry gaps.
## Custom Agent Steps
```typescript
-const plan = AsymptoteObserve.observe(
+const plan = Observe.observe(
{
name: "agent.plan",
attributes: {
@@ -129,14 +129,14 @@ const plan = AsymptoteObserve.observe(
);
```
-Call `AsymptoteObserve.flush()` before short-lived scripts exit, or
-`AsymptoteObserve.shutdown()` when the process owns the provider lifecycle.
+Call `Observe.flush()` before short-lived scripts exit, or
+`Observe.shutdown()` when the process owns the provider lifecycle.
## Beta Support Matrix
- OpenAI SDK: OpenLLMetry instrumentation enabled by default.
- Anthropic SDK: OpenLLMetry instrumentation enabled by default.
-- Vercel AI SDK: register `@ai-sdk/otel` with `AsymptoteObserve.getTracer()`.
+- Vercel AI SDK: register `@ai-sdk/otel` with `Observe.getTracer()`.
- Claude Agent SDK: wrap query functions with `wrapClaudeAgentQuery()` or use `observe()`.
- Custom orchestration: wrap functions with `observe()`.
- Custom Claude hook and OpenAI Agents tracing adapters are intentionally deferred.
diff --git a/packages/asymptote-observe-js/package-lock.json b/packages/asymptote-sdk-js/package-lock.json
similarity index 99%
rename from packages/asymptote-observe-js/package-lock.json
rename to packages/asymptote-sdk-js/package-lock.json
index bd41407d..14871bd8 100644
--- a/packages/asymptote-observe-js/package-lock.json
+++ b/packages/asymptote-sdk-js/package-lock.json
@@ -1,11 +1,11 @@
{
- "name": "@asymptote-labs/observe",
+ "name": "@asymptote/sdk",
"version": "0.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
- "name": "@asymptote-labs/observe",
+ "name": "@asymptote/sdk",
"version": "0.0.0",
"license": "MIT",
"dependencies": {
diff --git a/packages/asymptote-observe-js/package.json b/packages/asymptote-sdk-js/package.json
similarity index 90%
rename from packages/asymptote-observe-js/package.json
rename to packages/asymptote-sdk-js/package.json
index 5d07fa66..b09d6cc0 100644
--- a/packages/asymptote-observe-js/package.json
+++ b/packages/asymptote-sdk-js/package.json
@@ -1,13 +1,13 @@
{
- "name": "@asymptote-labs/observe",
+ "name": "@asymptote/sdk",
"version": "0.0.0",
- "description": "Asymptote Observe TypeScript SDK for Beacon-compatible agent telemetry",
+ "description": "Asymptote TypeScript SDK for Observe agent telemetry",
"type": "module",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/asymptote-labs/agent-beacon.git",
- "directory": "packages/asymptote-observe-js"
+ "directory": "packages/asymptote-sdk-js"
},
"keywords": [
"asymptote",
diff --git a/packages/asymptote-observe-js/scripts/smoke-pack.mjs b/packages/asymptote-sdk-js/scripts/smoke-pack.mjs
similarity index 84%
rename from packages/asymptote-observe-js/scripts/smoke-pack.mjs
rename to packages/asymptote-sdk-js/scripts/smoke-pack.mjs
index a5026ca1..2c5afa22 100644
--- a/packages/asymptote-observe-js/scripts/smoke-pack.mjs
+++ b/packages/asymptote-sdk-js/scripts/smoke-pack.mjs
@@ -5,7 +5,7 @@ import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const tempRoot = mkdtempSync(join(tmpdir(), "asymptote-observe-pack-"));
+const tempRoot = mkdtempSync(join(tmpdir(), "asymptote-sdk-pack-"));
let tarballPath;
try {
@@ -35,7 +35,7 @@ try {
[
"--input-type=module",
"--eval",
- "import { AsymptoteObserve, observe } from '@asymptote-labs/observe'; if (typeof AsymptoteObserve.initialize !== 'function' || typeof observe !== 'function') throw new Error('missing SDK exports');",
+ "import { Observe, observe } from '@asymptote/sdk'; if (typeof Observe.initialize !== 'function' || typeof observe !== 'function') throw new Error('missing SDK exports');",
],
{
cwd: tempRoot,
diff --git a/packages/asymptote-observe-js/src/constants.ts b/packages/asymptote-sdk-js/src/constants.ts
similarity index 100%
rename from packages/asymptote-observe-js/src/constants.ts
rename to packages/asymptote-sdk-js/src/constants.ts
diff --git a/packages/asymptote-observe-js/src/index.test.ts b/packages/asymptote-sdk-js/src/index.test.ts
similarity index 92%
rename from packages/asymptote-observe-js/src/index.test.ts
rename to packages/asymptote-sdk-js/src/index.test.ts
index 30611cc3..bb7f42e4 100644
--- a/packages/asymptote-observe-js/src/index.test.ts
+++ b/packages/asymptote-sdk-js/src/index.test.ts
@@ -10,7 +10,7 @@ import {
ATTR_BEACON_HARNESS_NAME,
ATTR_BEACON_ORIGIN,
ATTR_BEACON_PROMPT_TEXT,
- AsymptoteObserve,
+ Observe,
flush,
getTracer,
initialize,
@@ -23,9 +23,8 @@ import {
} from "./index.js";
const envKeys = [
- "ASYMPTOTE_OBSERVE_API_KEY",
- "ASYMPTOTE_OBSERVE_BASE_URL",
- "ASYMPTOTE_OBSERVE_ENDPOINT",
+ "ASYMPTOTE_API_KEY",
+ "ASYMPTOTE_BASE_URL",
"OTEL_EXPORTER_OTLP_ENDPOINT",
];
@@ -47,8 +46,8 @@ describe("resolveExporterConfig", () => {
});
it("resolves hosted config from env", () => {
- process.env.ASYMPTOTE_OBSERVE_API_KEY = "env-key";
- process.env.ASYMPTOTE_OBSERVE_BASE_URL = "https://observe.example";
+ process.env.ASYMPTOTE_API_KEY = "env-key";
+ process.env.ASYMPTOTE_BASE_URL = "https://observe.example";
const config = resolveExporterConfig();
@@ -57,6 +56,17 @@ describe("resolveExporterConfig", () => {
expect(config.headers.authorization).toBe("Bearer env-key");
});
+ it("prefers explicit api key and base URL over env", () => {
+ process.env.ASYMPTOTE_API_KEY = "env-key";
+ process.env.ASYMPTOTE_BASE_URL = "https://observe.example";
+
+ const config = resolveExporterConfig({ apiKey: "option-key", baseUrl: "https://option.example" });
+
+ expect(config.mode).toBe("hosted");
+ expect(config.observeUrl).toBe("https://option.example/v1/observe");
+ expect(config.headers.authorization).toBe("Bearer option-key");
+ });
+
it("resolves explicit Observe endpoint config without api key", () => {
const config = resolveExporterConfig({ otlpEndpoint: "http://127.0.0.1:4318" });
@@ -74,18 +84,17 @@ describe("resolveExporterConfig", () => {
expect(config.observeUrl).toBe("http://127.0.0.1:4318/v1/observe");
});
- it("prefers Observe endpoint env over generic OTLP endpoint env", () => {
+ it("prefers explicit OTLP endpoint option over generic OTLP endpoint env", () => {
process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318";
- process.env.ASYMPTOTE_OBSERVE_ENDPOINT = "http://127.0.0.1:9999/v1/observe";
- const config = resolveExporterConfig();
+ const config = resolveExporterConfig({ otlpEndpoint: "http://127.0.0.1:9999/v1/observe" });
expect(config.mode).toBe("otlp");
expect(config.observeUrl).toBe("http://127.0.0.1:9999/v1/observe");
});
it("throws when neither hosted credentials nor explicit OTLP are configured", () => {
- expect(() => resolveExporterConfig()).toThrow(/ASYMPTOTE_OBSERVE_API_KEY/);
+ expect(() => resolveExporterConfig()).toThrow(/ASYMPTOTE_API_KEY/);
});
it("allows custom mode when default exporter is disabled", () => {
@@ -254,7 +263,7 @@ describe("Asymptote Observe SDK", () => {
await fakeGenerateText({
experimental_telemetry: {
isEnabled: true,
- tracer: AsymptoteObserve.getTracer(),
+ tracer: Observe.getTracer(),
},
});
await flush();
diff --git a/packages/asymptote-observe-js/src/index.ts b/packages/asymptote-sdk-js/src/index.ts
similarity index 95%
rename from packages/asymptote-observe-js/src/index.ts
rename to packages/asymptote-sdk-js/src/index.ts
index 9b4b2388..773b56b0 100644
--- a/packages/asymptote-observe-js/src/index.ts
+++ b/packages/asymptote-sdk-js/src/index.ts
@@ -47,10 +47,10 @@ export * from "./constants.js";
const DEFAULT_HOSTED_BASE_URL = "https://api.asymptotelabs.ai";
const DEFAULT_OBSERVE_PATH = "/v1/observe";
-const DEFAULT_TRACER_NAME = "asymptote-observe";
-const DEFAULT_SERVICE_NAME = "asymptote-observe-app";
+const DEFAULT_TRACER_NAME = "asymptote-sdk";
+const DEFAULT_SERVICE_NAME = "asymptote-app";
const SDK_VERSION = readSDKVersion();
-const CLAUDE_AGENT_QUERY_WRAPPED = Symbol.for("@asymptote-labs/observe.claude-agent-query-wrapped");
+const CLAUDE_AGENT_QUERY_WRAPPED = Symbol.for("@asymptote/sdk.claude-agent-query-wrapped");
export type ExportMode = "hosted" | "otlp" | "custom";
@@ -119,7 +119,7 @@ type ClaudeAgentQueryFunction<T extends (...args: any[]) => any = (...args: any[
let state: SDKState | undefined;
-export class AsymptoteObserve {
+export class Observe {
static initialize(options: InitializeOptions = {}): void {
initialize(options);
}
@@ -191,7 +191,7 @@ export function initialize(options: InitializeOptions = {}): void {
const provider = new NodeTracerProvider({
resource: resourceFromAttributes({
[ATTR_SERVICE_NAME]: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? DEFAULT_SERVICE_NAME,
- "telemetry.sdk.name": "asymptote-observe-js",
+ "telemetry.sdk.name": "asymptote-sdk-js",
"telemetry.sdk.version": SDK_VERSION,
[ATTR_BEACON_ORIGIN]: "cloud",
[ATTR_BEACON_HARNESS_NAME]: "asymptote_observe",
@@ -252,7 +252,7 @@ export function observe<T extends (...args: any[]) => any>(options: ObserveOptio
export function patch(modules: InstrumentModules): void {
if (!modules || Object.keys(modules).length === 0) {
- throw new Error("AsymptoteObserve.patch requires at least one module");
+ throw new Error("Observe.patch requires at least one module");
}
patchOpenLLMetryModules(modules);
patchClaudeAgentSDK(modules.claudeAgentSDK ?? modules.claudeAgentSdk);
@@ -345,14 +345,14 @@ export function isInitialized(): boolean {
}
export function resolveExporterConfig(options: InitializeOptions = {}): ResolvedExporterConfig {
- const explicitEndpoint = options.otlpEndpoint ?? process.env.ASYMPTOTE_OBSERVE_ENDPOINT ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
- const apiKey = options.apiKey ?? process.env.ASYMPTOTE_OBSERVE_API_KEY;
- const baseUrl = options.baseUrl ?? process.env.ASYMPTOTE_OBSERVE_BASE_URL ?? DEFAULT_HOSTED_BASE_URL;
+ const explicitEndpoint = options.otlpEndpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+ const apiKey = options.apiKey ?? process.env.ASYMPTOTE_API_KEY;
+ const baseUrl = options.baseUrl ?? process.env.ASYMPTOTE_BASE_URL ?? DEFAULT_HOSTED_BASE_URL;
const skipDefault = !!(options.disableDefaultExporter || options.spanExporter);
const mode: ExportMode = skipDefault ? "custom" : explicitEndpoint ? "otlp" : apiKey ? "hosted" : "custom";
if (mode === "custom" && !skipDefault && !explicitEndpoint) {
- throw new Error("Asymptote Observe requires ASYMPTOTE_OBSERVE_API_KEY for hosted ingest or OTEL_EXPORTER_OTLP_ENDPOINT for explicit OTLP export");
+ throw new Error("Asymptote SDK requires ASYMPTOTE_API_KEY for hosted ingest or OTEL_EXPORTER_OTLP_ENDPOINT for explicit OTLP export");
}
const observeUrl = skipDefault ? undefined : explicitEndpoint ? observeURL(explicitEndpoint) : observeURL(baseUrl);
diff --git a/packages/asymptote-observe-js/tsconfig.build.json b/packages/asymptote-sdk-js/tsconfig.build.json
similarity index 100%
rename from packages/asymptote-observe-js/tsconfig.build.json
rename to packages/asymptote-sdk-js/tsconfig.build.json
diff --git a/packages/asymptote-observe-js/tsconfig.json b/packages/asymptote-sdk-js/tsconfig.json
similarity index 100%
rename from packages/asymptote-observe-js/tsconfig.json
rename to packages/asymptote-sdk-js/tsconfig.json