@ancha-labs/record 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @ancha-labs/record
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Puts the request and response bodies of your agent's API calls into your OpenTelemetry traces. Ancha rebuilds the
+world your agent saw from those bodies; OpenTelemetry's HTTP instrumentation leaves them out.
+
+```sh
+npm install @ancha-labs/record @opentelemetry/api
+node --import ./otel.js --import @ancha-labs/record your-agent.js   # otel.js starts your OpenTelemetry SDK
+```
+
+- **What becomes a span:** each `fetch` or `node:http(s)` call to a tool Ancha replicates (Slack, GitHub, Datadog, PagerDuty, Stripe, and the hosts in `VENDOR_API_BASES`). It is a client span on your own tracer, so it goes out through your own exporter, with `url.full`, the method, the status, `ancha.service`, and the bodies (`ancha.http.request.body`, `ancha.http.response.body`, 64 KB each at most). Other calls are left alone.
+- **Headers are never recorded,** so tokens never leave the process. Ancha removes credentials found in bodies before it stores anything.
+- **Webhooks:** call `recordInbound('slack', rawBody)` in the handler, while the request's server span is active.
+- **A proxy or private host** in front of a tool: `ANCHA_RECORD_HOSTS=api.internal.example=stripe`.
+- **Streams:** server-sent event responses are passed through and not buffered.
+
+Docs: [OTLP](https://docs.ancha.io/reference/otlp). MIT licensed.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@ancha-labs/record",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Adds the request and response bodies of your agent's API calls to your OpenTelemetry traces, so Ancha can rebuild the world your agent saw.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "homepage": "https://docs.ancha.io",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,96 @@
+// @ancha-labs/record: puts the request and response bodies of your agent's API calls into your OpenTelemetry traces
+// (TRACE_PLAN §1.5.3 step 1). OpenTelemetry's HTTP instrumentation leaves bodies out, and Ancha rebuilds the world your
+// agent saw from them. Each call to a tool Ancha replicates becomes a client span on your own tracer, so it travels
+// through your own exporter. Headers are never recorded, so credentials never leave the process.
+//
+//   node --import @ancha-labs/record your-agent.js     (after your OpenTelemetry SDK starts)
+//   import '@ancha-labs/record';                        (the same, from code)
+import { createRequire, syncBuiltinESMExports } from 'node:module';
+import { SpanKind, SpanStatusCode, context, trace } from '@opentelemetry/api';
+
+/** Vendor API bases Ancha reads (cloud/rebuild/ir.mjs keeps the same table; a test holds them equal). */
+export const VENDOR_API_BASES = Object.freeze({
+  slack: 'https://slack.com', github: 'https://api.github.com', datadog: 'https://api.datadoghq.com', pagerduty: 'https://api.pagerduty.com',
+  stripe: 'https://api.stripe.com', linear: 'https://api.linear.app', notion: 'https://api.notion.com', intercom: 'https://api.intercom.io',
+  sentry: 'https://sentry.io', twilio: 'https://api.twilio.com', resend: 'https://api.resend.com', airtable: 'https://api.airtable.com',
+  attio: 'https://api.attio.com', hubspot: 'https://api.hubapi.com', gmail: 'https://gmail.googleapis.com',
+});
+const MAX_BODY = 64 * 1024;
+const tracer = trace.getTracer('@ancha-labs/record', '0.0.0');
+const require = createRequire(import.meta.url);
+let hosts = new Map(), installed = false;
+
+/** host → tool. `ANCHA_RECORD_HOSTS=api.internal.example=stripe,…` adds hosts, e.g. a proxy in front of a vendor. */
+function hostTable(extra = process.env.ANCHA_RECORD_HOSTS ?? '') {
+  const table = new Map(Object.entries(VENDOR_API_BASES).map(([service, base]) => [new URL(base).host, service]));
+  for (const pair of extra.split(',').map(s => s.trim()).filter(Boolean)) { const [host, service] = pair.split('='); if (host && service) table.set(host, service); }
+  return table;
+}
+const serviceOf = (url) => { try { return hosts.get(new URL(url).host); } catch { return undefined; } };
+const clip = (text) => (text.length > MAX_BODY ? `${text.slice(0, MAX_BODY)}[truncated]` : text);
+const textOf = (body) => (typeof body === 'string' ? body : body instanceof URLSearchParams ? body.toString() : body instanceof Uint8Array ? Buffer.from(body).toString('utf8') : '');
+
+/** One client span for a finished call. */
+function record({ service, method, url, request, status, response, start }) {
+  const span = tracer.startSpan(`${method} ${service}`, { kind: SpanKind.CLIENT, startTime: start, attributes: {
+    'http.request.method': method, 'url.full': url, 'server.address': new URL(url).host, 'ancha.service': service,
+    ...(status !== undefined && { 'http.response.status_code': status }),
+    ...(request && { 'ancha.http.request.body': clip(request) }), ...(response && { 'ancha.http.response.body': clip(response) }),
+  } }, context.active());
+  if (status === undefined || status >= 400) span.setStatus({ code: SpanStatusCode.ERROR });
+  span.end();
+}
+
+/**
+ * Marks the webhook your handler is serving: call it with the tool and the raw body, inside the request's span (OpenTelemetry's
+ * HTTP server instrumentation makes it the active one). `recordInbound('slack', rawBody)`.
+ */
+export function recordInbound(service, body) {
+  const span = trace.getActiveSpan(); if (!span) return;
+  span.setAttribute('ancha.inbound.service', service);
+  span.setAttribute('ancha.http.request.body', clip(textOf(body)));
+}
+
+/** Patches fetch and node:http(s) once. Importing this module calls it; call it again to change the hosts. */
+export function install({ extraHosts } = {}) {
+  hosts = hostTable(extraHosts);
+  if (installed) return;
+  installed = true;
+  const originalFetch = globalThis.fetch;
+  if (originalFetch) globalThis.fetch = async function (input, init) {
+    const url = input instanceof Request ? input.url : String(input), service = serviceOf(url);
+    if (!service) return originalFetch(input, init);
+    const start = new Date(), method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    const request = init?.body !== undefined ? textOf(init.body) : input instanceof Request && method !== 'GET' ? await input.clone().text().catch(() => '') : '';
+    let response;
+    try { response = await originalFetch(input, init); }
+    catch (error) { record({ service, method, url, request, start }); throw error; }
+    // Server-sent streams are not buffered; everything else is read from a clone, after the caller has its response.
+    const streaming = (response.headers.get('content-type') ?? '').includes('text/event-stream');
+    const done = streaming ? Promise.resolve('') : response.clone().text().catch(() => '');
+    done.then(text => record({ service, method, url, request, status: response.status, response: text, start }));
+    return response;
+  };
+  for (const name of ['http', 'https']) {
+    const mod = require(`node:${name}`), originalRequest = mod.request;
+    mod.request = function (...args) {
+      const req = originalRequest.apply(this, args), [target] = args;
+      const url = typeof target === 'string' || target instanceof URL ? String(target)
+        : `${target.protocol ?? `${name}:`}//${target.hostname ?? target.host}${target.port ? `:${target.port}` : ''}${target.path ?? '/'}`;
+      const service = serviceOf(url); if (!service) return req;
+      const start = new Date(), sent = [], write = req.write, end = req.end;
+      req.write = function (chunk, ...rest) { if (chunk && typeof chunk !== 'function') sent.push(Buffer.from(chunk)); return write.call(this, chunk, ...rest); };
+      req.end = function (chunk, ...rest) { if (chunk && typeof chunk !== 'function') sent.push(Buffer.from(chunk)); return end.call(this, chunk, ...rest); };
+      req.on('response', res => {
+        const received = [];
+        res.on('data', c => received.push(Buffer.from(c)));
+        res.on('end', () => record({ service, method: req.method, url, request: Buffer.concat(sent).toString('utf8'), status: res.statusCode, response: Buffer.concat(received).toString('utf8'), start }));
+      });
+      req.on('error', () => record({ service, method: req.method, url, request: Buffer.concat(sent).toString('utf8'), start }));
+      return req;
+    };
+  }
+  syncBuiltinESMExports();
+}
+
+install();