@coralai/claude-code-agent 0.1.0

package/dist/telemetry/otel-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-adapter.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,MAAM,GACN,OAAO,GACP,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC;CAC/B;AAED,yCAAyC;AACzC,MAAM,WAAW,IAAI;IACnB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;IAC1D,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAC1C,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;IAC/D,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IACvC,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED,2CAA2C;AAC3C,MAAM,WAAW,MAAM;IACrB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAC;CACtE;AAMD;;;oCAGoC;AACpC,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB,CAgBA;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,cAAc,GACpB,IAAI,CAQN;AAID,2DAA2D;AAC3D,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,UAAU,CAAqB;gBAE3B,MAAM,EAAE,MAAM;IAI1B;2EACuE;IACvE,YAAY,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAW3E,sCAAsC;IACtC,UAAU,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAezD,6CAA6C;IAC7C,WAAW,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAYnE,wDAAwD;IACxD,SAAS,CAAC,IAAI,EAAE;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE;YACN,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,YAAY,CAAC,EAAE,MAAM,CAAC;YACtB,eAAe,CAAC,EAAE,MAAM,CAAC;YACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;YAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;SAC3B,CAAC;QACF,KAAK,CAAC,EAAE,KAAK,CAAC;KACf,GAAG,IAAI;CAoBT"}

package/dist/telemetry/otel-adapter.js

@@ -0,0 +1,153 @@
+/**
+ * OpenTelemetry adapter — wraps session/prompt/tool lifecycle in OTel spans.
+ *
+ * Per Eng D4 (2026-05-14):
+ * - Span hierarchy: agent.session (root) → agent.prompt → agent.tool.call /
+ *   agent.permission.request / agent.elicitation.request
+ * - Attributes follow OTel GenAI semantic conventions:
+ *     gen_ai.system: 'claude'
+ *     gen_ai.usage.input_tokens / output_tokens / cache_read_tokens / cache_write_tokens
+ *     gen_ai.response.finish_reason
+ * - Attribute payloads > 8 KB are truncated and marked `truncated: true`
+ *
+ * Peer dependency: `@opentelemetry/api` ≥1.7 <2 (OPTIONAL — only loaded when
+ * caller passes a tracer). The adapter never imports `@opentelemetry/api`;
+ * it uses a minimal structural `Tracer` interface that matches the real type.
+ * This keeps zero-dep cost for callers who don't use telemetry.
+ *
+ * Caller pattern:
+ *
+ *   import { trace } from '@opentelemetry/api';
+ *   const agent = new ClaudeCodeAgent({ cwd, tracer: trace.getTracer('myapp') });
+ *
+ * Step 1.4.7 ships the adapter + 8 KB truncation. Span hierarchy is wired
+ * for session.start, prompt, and turn-end. Tool/permission/elicitation
+ * spans land in Step 1.4.8 alongside their respective wirings.
+ */
+// ─── Attribute truncation ───────────────────────────────
+const MAX_ATTRIBUTE_BYTES = 8 * 1024; // 8 KB per D4
+/** Truncate a string-valued attribute if it exceeds 8 KB. Returns the
+ *  possibly-truncated value paired with a `_truncated` flag attribute name.
+ *  Callers should write both: setAttribute(key, value) + setAttribute(key+'.truncated', true)
+ *  when the result is truncated. */
+export function truncateAttributeValue(value) {
+    const bytes = Buffer.byteLength(value, 'utf-8');
+    if (bytes <= MAX_ATTRIBUTE_BYTES) {
+        return { value, truncated: false };
+    }
+    // Truncate to fit within 8 KB. Byte-safe truncation by scanning back from
+    // the end of the byte budget to a complete UTF-8 boundary.
+    let end = MAX_ATTRIBUTE_BYTES;
+    // Walk back while we're mid-codepoint
+    const buf = Buffer.from(value, 'utf-8');
+    while (end > 0) {
+        const byte = buf[end];
+        if (byte === undefined || (byte & 0xc0) !== 0x80)
+            break;
+        end--;
+    }
+    return { value: buf.slice(0, end).toString('utf-8'), truncated: true };
+}
+/** Helper: set an attribute with auto-truncation when the value is a string. */
+export function setAttributeSafe(span, key, value) {
+    if (typeof value === 'string') {
+        const { value: v, truncated } = truncateAttributeValue(value);
+        span.setAttribute(key, v);
+        if (truncated)
+            span.setAttribute(`${key}.truncated`, true);
+        return;
+    }
+    span.setAttribute(key, value);
+}
+// ─── Span manager ───────────────────────────────────────
+/** SpanStatusCode mirrors OTel: UNSET=0, OK=1, ERROR=2. */
+export const SpanStatusCode = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+/**
+ * Coordinates the span hierarchy for one ClaudeCodeAgent instance.
+ * The agent owns a single SpanManager that opens session-scoped spans on
+ * start, prompt-scoped spans during each turn, and closes them on settle/fail.
+ */
+export class SpanManager {
+    tracer;
+    sessionSpan = null;
+    promptSpan = null;
+    constructor(tracer) {
+        this.tracer = tracer;
+    }
+    /** Open the root span for the agent's session. Returns the span so the
+     *  caller can stash it (typically just rely on `this.sessionSpan`). */
+    startSession(attrs) {
+        const attributes = {
+            'gen_ai.system': 'claude',
+            'gen_ai.session.id': attrs.sessionId,
+            'agent.cwd': attrs.cwd,
+        };
+        if (attrs.pid !== undefined)
+            attributes['agent.pid'] = attrs.pid;
+        this.sessionSpan = this.tracer.startSpan('agent.session', { attributes });
+        return this.sessionSpan;
+    }
+    /** Mark session ended. Idempotent. */
+    endSession(opts) {
+        if (!this.sessionSpan)
+            return;
+        if (opts?.error) {
+            this.sessionSpan.recordException(opts.error);
+            this.sessionSpan.setStatus({ code: SpanStatusCode.ERROR, message: opts.error.message });
+        }
+        else {
+            this.sessionSpan.setStatus({ code: SpanStatusCode.OK });
+        }
+        if (opts?.code !== undefined) {
+            this.sessionSpan.setAttribute('agent.exit_code', opts.code);
+        }
+        this.sessionSpan.end();
+        this.sessionSpan = null;
+    }
+    /** Open a child span for one prompt turn. */
+    startPrompt(attrs) {
+        const { value: preview, truncated } = truncateAttributeValue(attrs.promptPreview);
+        const attributes = {
+            'gen_ai.system': 'claude',
+            'gen_ai.turn.id': attrs.turnId,
+            'gen_ai.prompt': preview,
+        };
+        if (truncated)
+            attributes['gen_ai.prompt.truncated'] = true;
+        this.promptSpan = this.tracer.startSpan('agent.prompt', { attributes });
+        return this.promptSpan;
+    }
+    /** Close the prompt span with finish reason + usage. */
+    endPrompt(opts) {
+        if (!this.promptSpan)
+            return;
+        this.promptSpan.setAttribute('gen_ai.response.finish_reason', opts.stopReason);
+        if (opts.usage) {
+            const u = opts.usage;
+            if (u.inputTokens !== undefined)
+                this.promptSpan.setAttribute('gen_ai.usage.input_tokens', u.inputTokens);
+            if (u.outputTokens !== undefined)
+                this.promptSpan.setAttribute('gen_ai.usage.output_tokens', u.outputTokens);
+            if (u.cacheReadTokens !== undefined)
+                this.promptSpan.setAttribute('gen_ai.usage.cache_read_tokens', u.cacheReadTokens);
+            if (u.cacheWriteTokens !== undefined)
+                this.promptSpan.setAttribute('gen_ai.usage.cache_write_tokens', u.cacheWriteTokens);
+            if (u.estimatedCostUsd !== undefined)
+                this.promptSpan.setAttribute('gen_ai.cost.usd', u.estimatedCostUsd);
+        }
+        if (opts.error) {
+            this.promptSpan.recordException(opts.error);
+            this.promptSpan.setStatus({ code: SpanStatusCode.ERROR, message: opts.error.message });
+        }
+        else {
+            this.promptSpan.setStatus({ code: SpanStatusCode.OK });
+        }
+        this.promptSpan.end();
+        this.promptSpan = null;
+    }
+}
+//# sourceMappingURL=otel-adapter.js.map

package/dist/telemetry/otel-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-adapter.js","sourceRoot":"","sources":["../../src/telemetry/otel-adapter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@coralai/claude-code-agent",
+  "version": "0.1.0",
+  "description": "Lean runtime primitive for embedding ACP-compatible agents (Claude Code) in Node.js apps",
+  "type": "module",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "acp",
+    "claude",
+    "agent",
+    "anthropic",
+    "runtime"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.21.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  }
+}