Skip to content

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

harden-sdk

Justin D'Souza08e20f4dcb87
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0f9cf272..835f2180 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,11 +9,15 @@ on:
jobs:
typescript-sdk:
runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ node-version: [20, 22, 24]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
- node-version: 24
+ node-version: ${{ matrix.node-version }}
cache: npm
cache-dependency-path: packages/asymptote-observe-js/package-lock.json
- name: Install SDK dependencies
@@ -31,6 +35,9 @@ jobs:
- name: Validate SDK package contents
working-directory: packages/asymptote-observe-js
run: npm run pack:dry-run
+ - name: Smoke install SDK package
+ working-directory: packages/asymptote-observe-js
+ run: npm run pack:smoke
go-test:
runs-on: macos-latest
diff --git a/.github/workflows/npm-publish-sdk.yml b/.github/workflows/npm-publish-sdk.yml
new file mode 100644
index 00000000..c4e6f812
--- /dev/null
+++ b/.github/workflows/npm-publish-sdk.yml
@@ -0,0 +1,41 @@
+name: Publish TypeScript SDK
+
+on:
+ workflow_dispatch:
+ push:
+ tags:
+ - observe-js-v*
+
+permissions:
+ contents: read
+ id-token: write
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ registry-url: https://registry.npmjs.org
+ cache: npm
+ cache-dependency-path: packages/asymptote-observe-js/package-lock.json
+ - name: Install SDK dependencies
+ working-directory: packages/asymptote-observe-js
+ run: npm ci
+ - name: Test SDK
+ working-directory: packages/asymptote-observe-js
+ run: npm test
+ - name: Type-check SDK
+ working-directory: packages/asymptote-observe-js
+ run: npm run check
+ - name: Build SDK
+ working-directory: packages/asymptote-observe-js
+ run: npm run build
+ - name: Smoke install SDK package
+ working-directory: packages/asymptote-observe-js
+ run: npm run pack:smoke
+ - name: Publish SDK to npm
+ working-directory: packages/asymptote-observe-js
+ run: npm publish --access public --provenance
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
index be85f92d..29343eba 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go
@@ -1094,6 +1094,8 @@ func NormalizeHarnessName(name string) string {
return ""
case strings.Contains(lower, "cowork") || strings.Contains(lower, "co-work"):
return "claude_cowork"
+ case strings.Contains(lower, "claude_agent_sdk") || strings.Contains(lower, "claude-agent-sdk") || strings.Contains(lower, "claude agent sdk"):
+ return "claude_agent_sdk"
case strings.Contains(lower, "claude_code") || strings.Contains(lower, "claude-code") || strings.Contains(lower, "claude code") || strings.HasPrefix(lower, "claude_code."):
return "claude_code"
case lower == "claude" || strings.Contains(lower, "claude"):
diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
index f10b284d..9dfe697d 100644
--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go
@@ -9,19 +9,7 @@ import (
)
func TestEventsFromTracesNormalizesObserveSDKSpan(t *testing.T) {
- traces := ptrace.NewTraces()
- resourceSpans := traces.ResourceSpans().AppendEmpty()
- resourceAttrs := resourceSpans.Resource().Attributes()
- resourceAttrs.PutStr("beacon.origin", "cloud")
- resourceAttrs.PutStr("beacon.harness.name", "asymptote_observe")
- resourceAttrs.PutStr("service.name", "agent-api")
-
- scopeSpans := resourceSpans.ScopeSpans().AppendEmpty()
- scopeSpans.Scope().SetName("asymptote-observe")
- span := scopeSpans.Spans().AppendEmpty()
- span.SetName("agent.plan")
- span.SetKind(ptrace.SpanKindClient)
- span.SetStartTimestamp(pcommon.NewTimestampFromTime(time.Unix(1700000000, 0).UTC()))
+ span, traces := newObserveSDKTraceSpan("agent.plan")
attrs := span.Attributes()
attrs.PutStr("beacon.event.action", "prompt.submitted")
attrs.PutStr("beacon.event.category", "prompt")
@@ -65,3 +53,81 @@ func TestEventsFromTracesNormalizesObserveSDKSpan(t *testing.T) {
t.Fatalf("gen_ai usage output = %#v, want 34", event.GenAI.Usage)
}
}
+
+func TestEventsFromTracesNormalizesVercelAISDKSpan(t *testing.T) {
+ span, traces := newObserveSDKTraceSpan("ai.generateText")
+ attrs := span.Attributes()
+ attrs.PutStr("beacon.harness.name", "vercel_ai_sdk")
+ attrs.PutStr("beacon.event.action", "prompt.submitted")
+ attrs.PutStr("beacon.event.category", "prompt")
+ attrs.PutStr("gen_ai.provider.name", "anthropic")
+ attrs.PutStr("gen_ai.operation.name", "chat")
+ attrs.PutStr("gen_ai.request.model", "claude-3-5-sonnet")
+ attrs.PutBool("gen_ai.request.stream", true)
+ attrs.PutInt("gen_ai.usage.input_tokens", 42)
+
+ events := NewConverter(Options{}).EventsFromTraces(traces)
+ if len(events) != 1 {
+ t.Fatalf("expected 1 event, got %d", len(events))
+ }
+ event := events[0]
+ if event.Harness.Name != "vercel_ai_sdk" {
+ t.Fatalf("harness = %q, want vercel_ai_sdk", event.Harness.Name)
+ }
+ if event.Event.Action != "prompt.submitted" || event.Event.Category != "prompt" {
+ t.Fatalf("event = %#v, want prompt.submitted prompt", event.Event)
+ }
+ if event.GenAI == nil || event.GenAI.Provider == nil || event.GenAI.Provider.Name != "anthropic" {
+ t.Fatalf("gen_ai provider = %#v, want anthropic", event.GenAI)
+ }
+ if event.GenAI.Request == nil || event.GenAI.Request.Model != "claude-3-5-sonnet" {
+ t.Fatalf("gen_ai request = %#v, want model", event.GenAI.Request)
+ }
+ if event.GenAI.Request.Stream == nil || !*event.GenAI.Request.Stream {
+ t.Fatalf("gen_ai stream = %#v, want true", event.GenAI.Request)
+ }
+ if event.GenAI.Usage == nil || event.GenAI.Usage.InputTokens == nil || *event.GenAI.Usage.InputTokens != 42 {
+ t.Fatalf("gen_ai usage input = %#v, want 42", event.GenAI.Usage)
+ }
+}
+
+func TestEventsFromTracesNormalizesClaudeAgentSDKSpan(t *testing.T) {
+ span, traces := newObserveSDKTraceSpan("claude_agent_sdk.query")
+ attrs := span.Attributes()
+ attrs.PutStr("beacon.harness.name", "claude_agent_sdk")
+ attrs.PutStr("beacon.event.action", "prompt.submitted")
+ attrs.PutStr("beacon.event.category", "prompt")
+ attrs.PutStr("beacon.prompt.text", "review this pull request")
+
+ events := NewConverter(Options{}).EventsFromTraces(traces)
+ if len(events) != 1 {
+ t.Fatalf("expected 1 event, got %d", len(events))
+ }
+ event := events[0]
+ if event.Harness.Name != "claude_agent_sdk" {
+ t.Fatalf("harness = %q, want claude_agent_sdk", event.Harness.Name)
+ }
+ if event.Event.Action != "prompt.submitted" || event.Event.Category != "prompt" {
+ t.Fatalf("event = %#v, want prompt.submitted prompt", event.Event)
+ }
+ if event.Prompt == nil || event.Prompt.Text != "review this pull request" {
+ t.Fatalf("prompt = %#v, want captured prompt text", event.Prompt)
+ }
+}
+
+func newObserveSDKTraceSpan(name string) (ptrace.Span, ptrace.Traces) {
+ traces := ptrace.NewTraces()
+ resourceSpans := traces.ResourceSpans().AppendEmpty()
+ resourceAttrs := resourceSpans.Resource().Attributes()
+ resourceAttrs.PutStr("beacon.origin", "cloud")
+ resourceAttrs.PutStr("beacon.harness.name", "asymptote_observe")
+ resourceAttrs.PutStr("service.name", "agent-api")
+
+ scopeSpans := resourceSpans.ScopeSpans().AppendEmpty()
+ scopeSpans.Scope().SetName("asymptote-observe")
+ span := scopeSpans.Spans().AppendEmpty()
+ span.SetName(name)
+ span.SetKind(ptrace.SpanKindClient)
+ span.SetStartTimestamp(pcommon.NewTimestampFromTime(time.Unix(1700000000, 0).UTC()))
+ return span, traces
+}
diff --git a/packages/asymptote-observe-js/package.json b/packages/asymptote-observe-js/package.json
index 3fc76d0f..5d07fa66 100644
--- a/packages/asymptote-observe-js/package.json
+++ b/packages/asymptote-observe-js/package.json
@@ -41,6 +41,7 @@
"build": "npm run clean && tsc -p tsconfig.build.json",
"check": "tsc -p tsconfig.json --noEmit",
"clean": "rm -rf dist",
+ "pack:smoke": "node scripts/smoke-pack.mjs",
"pack:dry-run": "npm pack --dry-run",
"prepack": "npm run build",
"test": "vitest run",
diff --git a/packages/asymptote-observe-js/scripts/smoke-pack.mjs b/packages/asymptote-observe-js/scripts/smoke-pack.mjs
new file mode 100644
index 00000000..a5026ca1
--- /dev/null
+++ b/packages/asymptote-observe-js/scripts/smoke-pack.mjs
@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+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-"));
+let tarballPath;
+
+try {
+ const packOutput = execFileSync("npm", ["pack", "--json"], {
+ cwd: packageRoot,
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "inherit"],
+ });
+ const [packResult] = JSON.parse(packOutput);
+ if (!packResult?.filename || !Array.isArray(packResult.files)) {
+ throw new Error("npm pack did not return package file metadata");
+ }
+
+ const packedFiles = new Set(packResult.files.map(file => file.path));
+ for (const expectedFile of ["README.md", "dist/index.js", "dist/index.d.ts", "package.json"]) {
+ if (!packedFiles.has(expectedFile)) {
+ throw new Error(`packed tarball is missing ${expectedFile}`);
+ }
+ }
+
+ tarballPath = join(packageRoot, packResult.filename);
+ execFileSync("npm", ["install", "--prefix", tempRoot, tarballPath], {
+ stdio: "inherit",
+ });
+ execFileSync(
+ process.execPath,
+ [
+ "--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');",
+ ],
+ {
+ cwd: tempRoot,
+ stdio: "inherit",
+ },
+ );
+} finally {
+ if (tarballPath) {
+ try {
+ unlinkSync(tarballPath);
+ } catch {
+ // Ignore cleanup errors; the smoke result should reflect package validity.
+ }
+ }
+ rmSync(tempRoot, { force: true, recursive: true });
+}
diff --git a/packages/asymptote-observe-js/src/index.test.ts b/packages/asymptote-observe-js/src/index.test.ts
index bff36449..30611cc3 100644
--- a/packages/asymptote-observe-js/src/index.test.ts
+++ b/packages/asymptote-observe-js/src/index.test.ts
@@ -1,5 +1,6 @@
import { SpanStatusCode } from "@opentelemetry/api";
import { InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";
+import { readFileSync } from "node:fs";
import { createServer, type IncomingMessage } from "node:http";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -64,15 +65,8 @@ describe("resolveExporterConfig", () => {
expect(config.headers.authorization).toBeUndefined();
});
- it("normalizes explicit OTLP traces endpoints to the Observe path", () => {
- const config = resolveExporterConfig({ otlpEndpoint: "http://127.0.0.1:4318/v1/traces" });
-
- expect(config.mode).toBe("otlp");
- expect(config.observeUrl).toBe("http://127.0.0.1:4318/v1/observe");
- });
-
- it("normalizes generic OTLP endpoint env when it includes the traces path", () => {
- process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318/v1/traces/";
+ it("keeps explicit Observe endpoints unchanged after trimming trailing slashes", () => {
+ process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318/v1/observe/";
const config = resolveExporterConfig();
@@ -137,6 +131,7 @@ describe("Asymptote Observe SDK", () => {
expect(spans[0].attributes[ATTR_BEACON_EVENT_ACTION]).toBe("tool.invoked");
expect(spans[0].attributes["asymptote.observe.input.count"]).toBe(1);
expect(spans[0].attributes["asymptote.observe.output.type"]).toBe("string");
+ expect(spans[0].resource.attributes["telemetry.sdk.version"]).toBe(packageVersion());
});
it("respects observe input/output suppression", async () => {
@@ -322,6 +317,11 @@ function clearEnv(): void {
}
}
+function packageVersion(): string {
+ const packageJSON = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string };
+ return packageJSON.version;
+}
+
async function fakeGenerateText(options: { experimental_telemetry?: { isEnabled?: boolean; tracer?: ReturnType<typeof getTracer> } }): Promise<void> {
if (!options.experimental_telemetry?.isEnabled || !options.experimental_telemetry.tracer) {
return;
diff --git a/packages/asymptote-observe-js/src/index.ts b/packages/asymptote-observe-js/src/index.ts
index 2aad39e2..9b4b2388 100644
--- a/packages/asymptote-observe-js/src/index.ts
+++ b/packages/asymptote-observe-js/src/index.ts
@@ -22,6 +22,9 @@ import {
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
import {
AnthropicInstrumentation,
type AnthropicInstrumentationConfig,
@@ -44,10 +47,9 @@ export * from "./constants.js";
const DEFAULT_HOSTED_BASE_URL = "https://api.asymptotelabs.ai";
const DEFAULT_OBSERVE_PATH = "/v1/observe";
-const DEFAULT_OTLP_TRACES_PATH = "/v1/traces";
const DEFAULT_TRACER_NAME = "asymptote-observe";
const DEFAULT_SERVICE_NAME = "asymptote-observe-app";
-const SDK_VERSION = "0.0.0";
+const SDK_VERSION = readSDKVersion();
const CLAUDE_AGENT_QUERY_WRAPPED = Symbol.for("@asymptote-labs/observe.claude-agent-query-wrapped");
export type ExportMode = "hosted" | "otlp" | "custom";
@@ -379,12 +381,22 @@ function observeURL(endpoint: string): string {
if (trimmed.endsWith(DEFAULT_OBSERVE_PATH)) {
return trimmed;
}
- if (trimmed.endsWith(DEFAULT_OTLP_TRACES_PATH)) {
- return `${trimmed.slice(0, -DEFAULT_OTLP_TRACES_PATH.length)}${DEFAULT_OBSERVE_PATH}`;
- }
return `${trimmed}${DEFAULT_OBSERVE_PATH}`;
}
+function readSDKVersion(): string {
+ try {
+ const packageJSONPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+ const packageJSON = JSON.parse(readFileSync(packageJSONPath, "utf8")) as { version?: unknown };
+ if (typeof packageJSON.version === "string" && packageJSON.version.trim() !== "") {
+ return packageJSON.version;
+ }
+ } catch {
+ // Keep tracing usable in unusual bundler/test environments where package.json is unavailable.
+ }
+ return "0.0.0";
+}
+
function patchOpenLLMetryModules(modules: InstrumentModules): void {
if (state?.instrumentationsDisabled) {
return;