@agentdid/langchain 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# @agent-did/langchain
+
+Integracion funcional de Agent-DID para LangChain JS 1.x.
+
+Esta variante es la referencia original en JavaScript/TypeScript y ahora mantiene parity operativa con la integracion Python en superficies clave: middleware/contexto, tools opt-in, seguridad por defecto, observabilidad callback/logger/LangSmith y ejemplos de operacion.
+
+La matriz de parity entre ambas integraciones vive en `../../docs/F1-03-LangChain-TS-Python-Integration-Parity-Matrix.md`.
+
+## Compatibilidad objetivo
+
+- `langchain` `^1.2.35`
+- `@langchain/core` `^1.1.34`
+- `@agent-did/sdk` `^0.1.0`
+- Node.js 20+
+
+## Estado
+
+- Estado actual: `functional-mvp`
+- Lenguaje objetivo: TypeScript / JavaScript
+- Rol actual: referencia JS de la integracion LangChain de Agent-DID
+- Parity objetivo: alineada con Python en README, ejemplos y observabilidad base
+
+## Instalacion
+
+```bash
+npm install @agent-did/sdk langchain @langchain/core zod
+```
+
+Para habilitar el adaptador opcional de LangSmith:
+
+```bash
+npm install langsmith
+```
+
+Si publicas este paquete por separado:
+
+```bash
+npm install @agent-did/langchain
+```
+
+## Uso rapido
+
+```ts
+import { ethers } from "ethers";
+import { createAgent } from "langchain";
+import { AgentIdentity } from "@agent-did/sdk";
+import { createAgentDidIntegration } from "@agent-did/langchain";
+
+const signer = new ethers.Wallet(process.env.CREATOR_PRIVATE_KEY!);
+const identity = new AgentIdentity({ signer, network: "polygon" });
+
+const runtimeIdentity = await identity.create({
+  name: "research_assistant",
+  description: "Agente de investigacion con identidad verificable",
+  coreModel: "gpt-4.1-mini",
+  systemPrompt: "Eres un agente de investigacion preciso y trazable.",
+  capabilities: ["research:web", "report:write"]
+});
+
+const integration = createAgentDidIntegration({
+  agentIdentity: identity,
+  runtimeIdentity,
+  expose: {
+    signHttp: true,
+    verifySignatures: true,
+    signPayload: false,
+    rotateKeys: false,
+    documentHistory: true
+  }
+});
+
+const agent = createAgent({
+  name: "research_assistant",
+  model: "openai:gpt-4.1-mini",
+  systemPrompt: "Responde con precision y usa herramientas cuando haga falta.",
+  tools: integration.tools,
+  middleware: [integration.middleware]
+});
+
+const result = await agent.invoke({
+  messages: [
+    {
+      role: "user",
+      content: "Muestrame tu DID actual y firma una solicitud POST a https://api.example.com/tasks"
+    }
+  ]
+});
+
+console.log(result.messages.at(-1)?.content);
+```
+
+## Que agrega la integracion
+
+- Middleware que inyecta en el sistema el DID actual, controlador, capacidades y metodo de autenticacion activo.
+- Herramientas de consulta para identidad actual, resolucion DID y verificacion de firmas.
+- Herramientas opcionales para firma de payloads, firma HTTP, historial documental y rotacion de clave.
+- Observabilidad vendor-neutral via callback, logger estructurado y adaptador opcional de LangSmith con redaccion por defecto.
+
+## Compatibilidad de API
+
+- `createAgentDidIntegration(...)`: nombre recomendado.
+- `createAgentDidPlugin(...)`: alias mantenido por compatibilidad retroactiva.
+
+## Seguridad por defecto
+
+- `signPayload` y `rotateKeys` vienen deshabilitados por defecto.
+- `signHttp` tambien es opt-in y puede habilitarse para que el agente firme solicitudes salientes sin exponer la clave privada al modelo.
+- Los destinos HTTP privados, loopback o con credenciales embebidas se rechazan por defecto.
+- La clave privada nunca se inserta en mensajes, contexto ni estado del agente.
+
+## Observabilidad
+
+La factory publica acepta instrumentacion opcional sin acoplar el paquete a un backend especifico:
+
+```js
+const {
+  composeEventHandlers,
+  createAgentDidIntegration,
+  createJsonLoggerEventHandler,
+} = require("@agent-did/langchain");
+
+const events = [];
+
+const integration = createAgentDidIntegration({
+  agentIdentity: identity,
+  runtimeIdentity,
+  expose: {
+    signHttp: true,
+    signPayload: true,
+  },
+  observabilityHandler: composeEventHandlers(
+    (event) => events.push(event),
+    createJsonLoggerEventHandler(console, {
+      extraFields: { service: "agent-gateway" },
+    })
+  ),
+});
+```
+
+Eventos emitidos:
+
+- `agent_did.identity_snapshot.refreshed`
+- `agent_did.tool.started`
+- `agent_did.tool.succeeded`
+- `agent_did.tool.failed`
+
+Redaccion por defecto:
+
+- `payload`, `body`, `signature` y `agent_private_key` se reemplazan por metadatos de longitud.
+- `Authorization`, `Signature`, `Signature-Input`, `Cookie`, `Set-Cookie` y `X-API-Key` se redactan en headers.
+- Las URLs se serializan sin query string, fragmento ni credenciales embebidas.
+
+Helpers publicos disponibles:
+
+- `composeEventHandlers(...)`
+- `createJsonLoggerEventHandler(...)`
+- `createLangSmithRunTree(...)`
+- `createLangSmithEventHandler(...)`
+- `serializeObservabilityEvent(...)`
+- `sanitizeObservabilityAttributes(...)`
+
+Ejemplo de LangSmith local sin cambiar la factory principal:
+
+```js
+const {
+  createAgentDidIntegration,
+  createLangSmithEventHandler,
+  createLangSmithRunTree,
+} = require("@agent-did/langchain");
+
+const rootRun = createLangSmithRunTree({
+  name: "agent_did_demo",
+  inputs: { scenario: "local" },
+  tags: ["agent-did", "demo"],
+});
+
+const integration = createAgentDidIntegration({
+  agentIdentity: identity,
+  runtimeIdentity,
+  expose: { signHttp: true, signPayload: true },
+  observabilityHandler: createLangSmithEventHandler(rootRun, {
+    extraFields: { sink: "langsmith" },
+    tags: ["local-demo"],
+  }),
+});
+```
+
+## Archivos relevantes
+
+- `src/agentDidLangChain.js`: middleware, herramientas y helpers principales.
+- `src/observability.js`: callbacks, logging JSON y saneamiento de eventos.
+- `examples/agentDidLangChain.example.js`: ejemplo con `createAgent()` de LangChain 1.x.
+- `examples/agentDidLangChain.observability.example.js`: ejemplo de callback + JSON logging saneado.
+- `examples/agentDidLangChain.langsmith.example.js`: tracing local con `RunTree` de LangSmith y child runs saneados.
+- `examples/agentDidLangChain.productionRecipe.example.js`: receta con guardas de entorno para un flujo mas cercano a produccion.
+- `tests/agentDidLangChain.test.js`: pruebas de la integracion.
+- `tests/agentDidLangChain.observability.test.js`: pruebas de observabilidad saneada.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@agentdid/langchain",
+  "version": "0.1.0",
+  "description": "LangChain integration for Agent-DID identities with middleware and tools for LangChain JS 1.x agents.",
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"console.log('No build step required for source-first package')\"",
+    "test": "jest --runInBand",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "agent-did",
+    "langchain",
+    "langchainjs",
+    "ai-agent",
+    "did",
+    "identity",
+    "middleware",
+    "tool-calling"
+  ],
+  "author": "Edison Munoz <edison.munoz@agent-did.org>",
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@agentdid/sdk": "^0.1.0",
+    "@langchain/core": "^1.1.34",
+    "langchain": "^1.2.35",
+    "langsmith": "^0.5.10"
+  },
+  "peerDependenciesMeta": {
+    "langsmith": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@agentdid/sdk": "file:../../sdk",
+    "@langchain/core": "^1.1.34",
+    "@types/jest": "^29.5.14",
+    "ethers": "^6.11.1",
+    "jest": "^29.7.0",
+    "langchain": "^1.2.35",
+    "langsmith": "^0.5.10",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.4.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/agentDidLangChain.js

@@ -0,0 +1,518 @@
+const { AgentIdentity } = require("@agentdid/sdk");
+const net = require("node:net");
+const { SystemMessage } = require("@langchain/core/messages");
+const { tool } = require("@langchain/core/tools");
+const { z } = require("zod");
+const { createAgentDidObserver } = require("./observability");
+
+const MIDDLEWARE_BRAND = Symbol.for("AgentMiddleware");
+const MAX_PAYLOAD_BYTES = 1048576; // 1 MB
+
+const DEFAULT_EXPOSURE = {
+  currentIdentity: true,
+  resolveDid: true,
+  verifySignatures: true,
+  signPayload: false,
+  signHttp: false,
+  documentHistory: false,
+  rotateKeys: false,
+};
+
+function withPrefix(prefix, name) {
+  return `${prefix}_${name}`;
+}
+
+function getActiveVerificationMethodId(runtimeIdentity) {
+  return runtimeIdentity.verificationMethodId ?? runtimeIdentity.document.authentication[0];
+}
+
+function createBrandedMiddleware(config) {
+  return {
+    [MIDDLEWARE_BRAND]: true,
+    name: config.name,
+    wrapModelCall: config.wrapModelCall,
+  };
+}
+
+function buildAgentDidIdentitySnapshot(runtimeIdentity) {
+  const { document } = runtimeIdentity;
+
+  return {
+    did: document.id,
+    controller: document.controller,
+    name: document.agentMetadata.name,
+    description: document.agentMetadata.description,
+    version: document.agentMetadata.version,
+    capabilities: document.agentMetadata.capabilities ?? [],
+    memberOf: document.agentMetadata.memberOf,
+    authenticationKeyId: getActiveVerificationMethodId(runtimeIdentity),
+    created: document.created,
+    updated: document.updated,
+  };
+}
+
+function buildAgentDidSystemPrompt(snapshot, additionalSystemContext) {
+  const capabilities = snapshot.capabilities.length > 0 ? snapshot.capabilities.join(", ") : "none";
+  const lines = [
+    "Agent-DID identity context:",
+    `- did: ${snapshot.did}`,
+    `- controller: ${snapshot.controller}`,
+    `- name: ${snapshot.name}`,
+    `- version: ${snapshot.version}`,
+    `- capabilities: ${capabilities}`,
+    `- member_of: ${snapshot.memberOf ?? "none"}`,
+    `- authentication_key_id: ${snapshot.authenticationKeyId ?? "unknown"}`,
+    "Rules:",
+    "- Treat this DID as the authoritative identity of this agent.",
+    "- Never invent or substitute another DID for this agent.",
+    "- If an outbound HTTP request must be authenticated with Agent-DID, use the dedicated signing tool instead of fabricating headers.",
+  ];
+
+  if (additionalSystemContext && additionalSystemContext.trim()) {
+    lines.push(`Additional identity policy: ${additionalSystemContext.trim()}`);
+  }
+
+  return lines.join("\n");
+}
+
+function validateHttpTarget(url, allowPrivateNetworkTargets) {
+  const parsedUrl = new URL(url);
+  if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+    throw new Error("Only http and https URLs are allowed");
+  }
+
+  if (parsedUrl.username || parsedUrl.password) {
+    throw new Error("URLs with embedded credentials are not allowed");
+  }
+
+  const hostname = parsedUrl.hostname;
+  if (!hostname) {
+    throw new Error("An absolute URL with hostname is required");
+  }
+
+  const normalizedHostname = hostname.toLowerCase();
+  if (allowPrivateNetworkTargets) {
+    return;
+  }
+
+  if (normalizedHostname === "localhost" || normalizedHostname.endsWith(".localhost")) {
+    throw new Error("Private or loopback HTTP targets are not allowed by default");
+  }
+
+  const ipVersion = net.isIP(normalizedHostname);
+  if (ipVersion === 4 && isRestrictedIpv4(normalizedHostname)) {
+    throw new Error("Private or loopback HTTP targets are not allowed by default");
+  }
+
+  if (ipVersion === 6 && isRestrictedIpv6(normalizedHostname)) {
+    throw new Error("Private or loopback HTTP targets are not allowed by default");
+  }
+}
+
+function isRestrictedIpv4(hostname) {
+  const octets = hostname.split(".").map((segment) => Number.parseInt(segment, 10));
+  if (octets.length !== 4 || octets.some((segment) => Number.isNaN(segment))) {
+    return false;
+  }
+
+  const [first, second] = octets;
+  if (first === 10 || first === 127 || first === 0) {
+    return true;
+  }
+  if (first === 169 && second === 254) {
+    return true;
+  }
+  if (first === 172 && second >= 16 && second <= 31) {
+    return true;
+  }
+  if (first === 192 && second === 168) {
+    return true;
+  }
+  if (first >= 224) {
+    return true;
+  }
+
+  return false;
+}
+
+function isRestrictedIpv6(hostname) {
+  const normalizedHostname = hostname.toLowerCase();
+  return (
+    normalizedHostname === "::1"
+    || normalizedHostname === "::"
+    || normalizedHostname.startsWith("fc")
+    || normalizedHostname.startsWith("fd")
+    || normalizedHostname.startsWith("fe8")
+    || normalizedHostname.startsWith("fe9")
+    || normalizedHostname.startsWith("fea")
+    || normalizedHostname.startsWith("feb")
+    || normalizedHostname.startsWith("ff")
+  );
+}
+
+function emitToolStarted(observer, { toolName, did, inputs = {} }) {
+  observer.emit("agent_did.tool.started", {
+    attributes: {
+      tool_name: toolName,
+      did,
+      inputs,
+    },
+  });
+}
+
+function emitToolSucceeded(observer, { toolName, did, outputs = {} }) {
+  observer.emit("agent_did.tool.succeeded", {
+    attributes: {
+      tool_name: toolName,
+      did,
+      outputs,
+    },
+  });
+}
+
+function emitToolFailed(observer, { toolName, did, error, inputs = {} }) {
+  observer.emit("agent_did.tool.failed", {
+    level: "error",
+    attributes: {
+      tool_name: toolName,
+      did,
+      inputs,
+      error: error instanceof Error ? error.message : String(error),
+    },
+  });
+}
+
+function captureIdentitySnapshot(runtimeIdentity, observer, reason) {
+  const snapshot = buildAgentDidIdentitySnapshot(runtimeIdentity);
+  observer.emit("agent_did.identity_snapshot.refreshed", {
+    attributes: {
+      did: snapshot.did,
+      authentication_key_id: snapshot.authenticationKeyId,
+      reason,
+    },
+  });
+  return snapshot;
+}
+
+function createAgentDidMiddleware(options) {
+  const middlewareName = options.middlewareName ?? "AgentDidIdentityMiddleware";
+  const observer = options.observer ?? createAgentDidObserver();
+
+  return createBrandedMiddleware({
+    name: middlewareName,
+    wrapModelCall: async (request, handler) => {
+      const snapshot = captureIdentitySnapshot(options.runtimeIdentity, observer, "middleware");
+      const identitySection = buildAgentDidSystemPrompt(snapshot, options.additionalSystemContext);
+
+      return handler({
+        ...request,
+        systemMessage: request.systemMessage.concat(
+          new SystemMessage({
+            content: identitySection,
+          })
+        ),
+      });
+    },
+  });
+}
+
+function createAgentDidTools(options) {
+  const exposure = { ...DEFAULT_EXPOSURE, ...options.expose };
+  const toolPrefix = options.toolPrefix ?? "agent_did";
+  const observer = options.observer ?? createAgentDidObserver();
+  const tools = [];
+
+  if (exposure.currentIdentity) {
+    tools.push(
+      tool(async () => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "get_current_identity");
+        emitToolStarted(observer, { toolName, did: currentDid });
+        try {
+          const snapshot = captureIdentitySnapshot(options.runtimeIdentity, observer, "tool:get_current_identity");
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: {
+              authentication_key_id: snapshot.authenticationKeyId,
+            },
+          });
+          return snapshot;
+        } catch (err) {
+          emitToolFailed(observer, { toolName, did: currentDid, error: err });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "get_current_identity"),
+        description: "Return the current Agent-DID identity attached to this LangChain agent.",
+        schema: z.object({}),
+      })
+    );
+  }
+
+  if (exposure.resolveDid) {
+    tools.push(
+      tool(async ({ did }) => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "resolve_did");
+        emitToolStarted(observer, { toolName, did: currentDid, inputs: { did } });
+        try {
+          const targetDid = did && did.trim() ? did.trim() : options.runtimeIdentity.document.id;
+          const resolved = await AgentIdentity.resolve(targetDid);
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: { resolved_did: resolved.id },
+          });
+          return resolved;
+        } catch (err) {
+          emitToolFailed(observer, { toolName, did: currentDid, error: err, inputs: { did } });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "resolve_did"),
+        description: "Resolve an Agent-DID document. If no DID is provided, resolves the current agent DID.",
+        schema: z.object({
+          did: z.string().max(512).optional().describe("Optional DID to resolve"),
+        }),
+      })
+    );
+  }
+
+  if (exposure.verifySignatures) {
+    tools.push(
+      tool(async ({ did, payload, signature, keyId }) => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "verify_signature");
+        emitToolStarted(observer, {
+          toolName,
+          did: currentDid,
+          inputs: { did, key_id: keyId, payload, signature },
+        });
+        try {
+          const targetDid = did && did.trim() ? did.trim() : options.runtimeIdentity.document.id;
+          const isValid = await AgentIdentity.verifySignature(targetDid, payload, signature, keyId);
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: { target_did: targetDid, is_valid: isValid, key_id: keyId },
+          });
+          return { did: targetDid, keyId, isValid };
+        } catch (err) {
+          emitToolFailed(observer, {
+            toolName,
+            did: currentDid,
+            error: err,
+            inputs: { did, key_id: keyId, payload, signature },
+          });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "verify_signature"),
+        description: "Verify an Agent-DID signature against a DID document and active verification methods.",
+        schema: z.object({
+          did: z.string().max(512).optional().describe("Optional DID. Defaults to the current agent DID."),
+          payload: z.string().max(MAX_PAYLOAD_BYTES).describe("The exact payload that was signed."),
+          signature: z.string().max(256).describe("Hex-encoded Ed25519 signature."),
+          keyId: z.string().max(512).optional().describe("Optional verification method id to pin verification."),
+        }),
+      })
+    );
+  }
+
+  if (exposure.signPayload) {
+    tools.push(
+      tool(async ({ payload }) => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "sign_payload");
+        emitToolStarted(observer, { toolName, did: currentDid, inputs: { payload } });
+        try {
+          const signature = await options.agentIdentity.signMessage(payload, options.runtimeIdentity.agentPrivateKey);
+          const keyId = getActiveVerificationMethodId(options.runtimeIdentity);
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: { key_id: keyId, signature_generated: true },
+          });
+          return {
+            did: currentDid,
+            keyId,
+            payload,
+            signature,
+          };
+        } catch (err) {
+          emitToolFailed(observer, { toolName, did: currentDid, error: err, inputs: { payload } });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "sign_payload"),
+        description: "Sign a payload with the current agent verification key without exposing the private key.",
+        schema: z.object({
+          payload: z.string().max(MAX_PAYLOAD_BYTES).describe("Payload to sign exactly as-is."),
+        }),
+      })
+    );
+  }
+
+  if (exposure.signHttp) {
+    tools.push(
+      tool(async ({ method, url, body }) => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "sign_http_request");
+        emitToolStarted(observer, {
+          toolName,
+          did: currentDid,
+          inputs: { method, url, body },
+        });
+        try {
+          validateHttpTarget(url, options.allowPrivateNetworkTargets === true);
+          const keyId = getActiveVerificationMethodId(options.runtimeIdentity);
+          const headers = await options.agentIdentity.signHttpRequest({
+            method,
+            url,
+            body,
+            agentPrivateKey: options.runtimeIdentity.agentPrivateKey,
+            agentDid: options.runtimeIdentity.document.id,
+            verificationMethodId: keyId,
+          });
+
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: {
+              key_id: keyId,
+              method,
+              url,
+              header_names: Object.keys(headers).sort(),
+            },
+          });
+
+          return {
+            did: currentDid,
+            keyId,
+            method,
+            url,
+            headers,
+          };
+        } catch (err) {
+          emitToolFailed(observer, { toolName, did: currentDid, error: err, inputs: { method, url, body } });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "sign_http_request"),
+        description: "Create Agent-DID HTTP signature headers for an outbound request.",
+        schema: z.object({
+          method: z.string().max(16).describe("HTTP method, for example GET or POST."),
+          url: z.string().url().max(2048).describe("Target absolute URL."),
+          body: z.string().max(MAX_PAYLOAD_BYTES).optional().describe("Optional raw request body."),
+        }),
+      })
+    );
+  }
+
+  if (exposure.documentHistory) {
+    tools.push(
+      tool(async ({ did }) => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "get_document_history");
+        emitToolStarted(observer, { toolName, did: currentDid, inputs: { did } });
+        try {
+          const targetDid = did && did.trim() ? did.trim() : options.runtimeIdentity.document.id;
+          const history = await AgentIdentity.getDocumentHistory(targetDid);
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: { target_did: targetDid, entry_count: history.length },
+          });
+          return history;
+        } catch (err) {
+          emitToolFailed(observer, { toolName, did: currentDid, error: err, inputs: { did } });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "get_document_history"),
+        description: "Return the revision history registered for an Agent-DID document.",
+        schema: z.object({
+          did: z.string().max(512).optional().describe("Optional DID. Defaults to the current agent DID."),
+        }),
+      })
+    );
+  }
+
+  if (exposure.rotateKeys) {
+    tools.push(
+      tool(async () => {
+        const currentDid = options.runtimeIdentity.document.id;
+        const toolName = withPrefix(toolPrefix, "rotate_key");
+        emitToolStarted(observer, { toolName, did: currentDid });
+        try {
+          const rotated = await AgentIdentity.rotateVerificationMethod(options.runtimeIdentity.document.id);
+          const updatedIdentity = {
+            ...options.runtimeIdentity,
+            document: rotated.document,
+            agentPrivateKey: rotated.agentPrivateKey,
+            verificationMethodId: rotated.verificationMethodId,
+          };
+          Object.assign(options.runtimeIdentity, updatedIdentity);
+          const snapshot = captureIdentitySnapshot(options.runtimeIdentity, observer, "tool:rotate_key");
+          emitToolSucceeded(observer, {
+            toolName,
+            did: currentDid,
+            outputs: {
+              verification_method_id: rotated.verificationMethodId,
+            },
+          });
+
+          return {
+            did: rotated.document.id,
+            verificationMethodId: rotated.verificationMethodId,
+            snapshot,
+          };
+        } catch (err) {
+          emitToolFailed(observer, { toolName, did: currentDid, error: err });
+          return { error: err instanceof Error ? err.message : String(err) };
+        }
+      }, {
+        name: withPrefix(toolPrefix, "rotate_key"),
+        description: "Rotate the active Agent-DID verification method and update the attached runtime identity.",
+        schema: z.object({}),
+      })
+    );
+  }
+
+  return tools;
+}
+
+function createAgentDidIntegration(options) {
+  const observer = options.observer ?? createAgentDidObserver({
+    eventHandler: options.observabilityHandler,
+    logger: options.logger,
+  });
+  const integrationOptions = {
+    ...options,
+    observer,
+  };
+  const middleware = createAgentDidMiddleware(integrationOptions);
+  const tools = createAgentDidTools(integrationOptions);
+
+  return {
+    middleware,
+    observer,
+    tools,
+    getCurrentIdentity: () => captureIdentitySnapshot(options.runtimeIdentity, observer, "get_current_identity"),
+    getCurrentDocument: () => options.runtimeIdentity.document,
+  };
+}
+
+function createAgentDidPlugin(options) {
+  return createAgentDidIntegration(options);
+}
+
+module.exports = {
+  buildAgentDidIdentitySnapshot,
+  buildAgentDidSystemPrompt,
+  createAgentDidIntegration,
+  createAgentDidMiddleware,
+  createAgentDidPlugin,
+  createAgentDidTools,
+};

package/src/index.js

@@ -0,0 +1,35 @@
+const {
+  buildAgentDidIdentitySnapshot,
+  buildAgentDidSystemPrompt,
+  createAgentDidIntegration,
+  createAgentDidMiddleware,
+  createAgentDidPlugin,
+  createAgentDidTools,
+} = require("./agentDidLangChain");
+const {
+  REDACTED_VALUE,
+  composeEventHandlers,
+  createAgentDidObserver,
+  createJsonLoggerEventHandler,
+  createLangSmithEventHandler,
+  createLangSmithRunTree,
+  sanitizeObservabilityAttributes,
+  serializeObservabilityEvent,
+} = require("./observability");
+
+module.exports = {
+  REDACTED_VALUE,
+  buildAgentDidIdentitySnapshot,
+  buildAgentDidSystemPrompt,
+  composeEventHandlers,
+  createAgentDidObserver,
+  createAgentDidIntegration,
+  createAgentDidMiddleware,
+  createAgentDidPlugin,
+  createAgentDidTools,
+  createJsonLoggerEventHandler,
+  createLangSmithEventHandler,
+  createLangSmithRunTree,
+  sanitizeObservabilityAttributes,
+  serializeObservabilityEvent,
+};

package/src/observability.js

@@ -0,0 +1,415 @@
+const REDACTED_VALUE = "<redacted>";
+const SENSITIVE_FIELD_NAMES = new Set([
+  "agent_private_key",
+  "body",
+  "payload",
+  "signature",
+]);
+const SENSITIVE_HEADER_NAMES = new Set([
+  "authorization",
+  "cookie",
+  "proxy-authorization",
+  "set-cookie",
+  "signature",
+  "signature-input",
+  "x-api-key",
+]);
+
+function composeEventHandlers(...handlers) {
+  const activeHandlers = handlers.filter(Boolean);
+
+  return (event) => {
+    for (const handler of activeHandlers) {
+      try {
+        handler(event);
+      } catch {
+        continue;
+      }
+    }
+  };
+}
+
+function serializeObservabilityEvent(
+  event,
+  {
+    source = "agent_did_langchain",
+    includeTimestamp = true,
+    extraFields,
+  } = {}
+) {
+  const record = {
+    source,
+    eventType: event.eventType,
+    level: event.level,
+    attributes: sanitizeObservabilityAttributes(event.attributes ?? {}),
+  };
+
+  if (includeTimestamp) {
+    record.timestamp = new Date().toISOString();
+  }
+
+  if (extraFields) {
+    Object.assign(record, sanitizeObservabilityAttributes(extraFields));
+  }
+
+  return record;
+}
+
+function createJsonLoggerEventHandler(
+  logger,
+  {
+    source = "agent_did_langchain",
+    includeTimestamp = true,
+    extraFields,
+  } = {}
+) {
+  return (event) => {
+    const record = serializeObservabilityEvent(event, {
+      source,
+      includeTimestamp,
+      extraFields,
+    });
+    logWithLogger(logger, event.level, JSON.stringify(record));
+  };
+}
+
+function createLangSmithRunTree(
+  {
+    name,
+    projectName = "agent-did-langchain",
+    runType = "chain",
+    inputs,
+    tags,
+    extra,
+    client,
+  } = {}
+) {
+  const RunTree = loadLangSmithRunTree();
+
+  return new RunTree({
+    name,
+    run_type: runType,
+    project_name: projectName,
+    inputs: sanitizeObservabilityAttributes(inputs ?? {}),
+    tags: [...(tags ?? [])],
+    extra: sanitizeObservabilityAttributes(extra ?? {}),
+    client,
+    serialized: {},
+  });
+}
+
+function createLangSmithEventHandler(
+  runTree,
+  {
+    source = "agent_did_langchain",
+    includeTimestamp = true,
+    extraFields,
+    tags,
+    postImmediately = false,
+  } = {}
+) {
+  const activeToolRuns = new Map();
+  const normalizedTags = [...(tags ?? [])];
+
+  return (event) => {
+    const record = serializeObservabilityEvent(event, {
+      source,
+      includeTimestamp,
+      extraFields,
+    });
+    const attributes = record.attributes ?? {};
+    const toolName = attributes.tool_name;
+    const did = attributes.did;
+    const eventType = event.eventType;
+
+    try {
+      runTree.addEvent(toLangSmithEvent(record));
+    } catch {
+      // no-op defensive boundary
+    }
+
+    if (isLangSmithToolEvent(toolName, did, eventType)) {
+      handleLangSmithToolEvent({
+        runTree,
+        activeToolRuns,
+        normalizedTags,
+        source,
+        postImmediately,
+        toolName,
+        did,
+        eventType,
+        attributes,
+        record,
+      });
+      return;
+    }
+
+    handleLangSmithGenericEvent({
+      runTree,
+      normalizedTags,
+      source,
+      postImmediately,
+      eventType,
+      attributes,
+      record,
+    });
+  };
+}
+
+function createAgentDidObserver({ eventHandler, logger } = {}) {
+  return {
+    emit(eventType, { attributes = {}, level = "info" } = {}) {
+      const event = {
+        eventType,
+        level,
+        attributes: sanitizeObservabilityAttributes(attributes),
+      };
+
+      if (eventHandler) {
+        try {
+          eventHandler(event);
+        } catch {
+          // no-op defensive boundary
+        }
+      }
+
+      if (logger) {
+        try {
+          logWithLogger(
+            logger,
+            level,
+            `agent_did_langchain event=${event.eventType} attributes=${JSON.stringify(event.attributes)}`
+          );
+        } catch {
+          // no-op defensive boundary
+        }
+      }
+    },
+  };
+}
+
+function sanitizeObservabilityAttributes(attributes) {
+  return Object.fromEntries(
+    Object.entries(attributes).map(([key, value]) => [String(key), sanitizeValue(String(key), value)])
+  );
+}
+
+function sanitizeValue(fieldName, value) {
+  const normalizedFieldName = fieldName.toLowerCase();
+
+  if (SENSITIVE_FIELD_NAMES.has(normalizedFieldName) && typeof value === "string") {
+    return { redacted: true, length: value.length };
+  }
+
+  if (normalizedFieldName === "url" && typeof value === "string") {
+    return sanitizeUrl(value);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeValue(fieldName, entry));
+  }
+
+  if (value && typeof value === "object") {
+    if (normalizedFieldName === "headers") {
+      return sanitizeHeaders(value);
+    }
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nestedValue]) => [String(key), sanitizeValue(String(key), nestedValue)])
+    );
+  }
+
+  return value;
+}
+
+function sanitizeHeaders(headers) {
+  return Object.fromEntries(
+    Object.entries(headers).map(([headerName, headerValue]) => {
+      if (SENSITIVE_HEADER_NAMES.has(String(headerName).toLowerCase())) {
+        return [String(headerName), REDACTED_VALUE];
+      }
+
+      return [String(headerName), sanitizeValue(String(headerName), headerValue)];
+    })
+  );
+}
+
+function sanitizeUrl(url) {
+  const parsedUrl = new URL(url);
+  parsedUrl.username = "";
+  parsedUrl.password = "";
+  parsedUrl.search = "";
+  parsedUrl.hash = "";
+  return parsedUrl.toString();
+}
+
+function logWithLogger(logger, level, message) {
+  const normalizedLevel = normalizeLevel(level);
+  if (typeof logger[normalizedLevel] === "function") {
+    logger[normalizedLevel](message);
+    return;
+  }
+
+  if (typeof logger.log === "function") {
+    logger.log(normalizedLevel, message);
+  }
+}
+
+function normalizeLevel(level) {
+  if (level === "debug" || level === "warning" || level === "error") {
+    return level === "warning" ? "warn" : level;
+  }
+
+  return "info";
+}
+
+function loadLangSmithRunTree() {
+  try {
+    const { RunTree } = require("langsmith");
+    if (typeof RunTree !== "function") {
+      throw new Error("RunTree export not found");
+    }
+    return RunTree;
+  } catch (error) {
+    const wrappedError = new Error(
+      "LangSmith is required for the LangSmith observability adapter. Install the optional 'langsmith' package to enable it."
+    );
+    wrappedError.cause = error;
+    throw wrappedError;
+  }
+}
+
+function toLangSmithEvent(record) {
+  return {
+    name: record.eventType ?? "event",
+    kwargs: record,
+  };
+}
+
+function isLangSmithToolEvent(toolName, did, eventType) {
+  return typeof toolName === "string" && typeof did === "string" && eventType.startsWith("agent_did.tool.");
+}
+
+function createLangSmithChildRun(runTree, { name, runType, inputs, tags, source, eventType }) {
+  return runTree.createChild({
+    name,
+    run_type: runType,
+    inputs,
+    tags,
+    extra: { source, agent_did_event_type: eventType },
+    serialized: {},
+  });
+}
+
+function handleLangSmithToolEvent({
+  runTree,
+  activeToolRuns,
+  normalizedTags,
+  source,
+  postImmediately,
+  toolName,
+  did,
+  eventType,
+  attributes,
+  record,
+}) {
+  const runKey = `${toolName}:${did}`;
+  let childRun = activeToolRuns.get(runKey);
+
+  if (eventType.endsWith(".started")) {
+    childRun = createLangSmithChildRun(runTree, {
+      name: toolName,
+      runType: "tool",
+      inputs: { did, inputs: attributes.inputs ?? {}, event_type: eventType },
+      tags: [...normalizedTags, "agent-did", "tool"],
+      source,
+      eventType,
+    });
+    childRun.addEvent(toLangSmithEvent(record));
+    activeToolRuns.set(runKey, childRun);
+    maybePostLangSmithRun(childRun, { postImmediately, finalized: false });
+    return;
+  }
+
+  if (!childRun) {
+    childRun = createLangSmithChildRun(runTree, {
+      name: toolName,
+      runType: "tool",
+      inputs: { did, event_type: eventType },
+      tags: [...normalizedTags, "agent-did", "tool"],
+      source,
+      eventType,
+    });
+  }
+
+  childRun.addEvent(toLangSmithEvent(record));
+
+  if (eventType.endsWith(".failed")) {
+    void childRun.end(
+      { did, event_type: eventType, attributes },
+      String(attributes.error ?? "unknown error")
+    );
+  } else {
+    void childRun.end({ did, event_type: eventType, attributes });
+  }
+
+  activeToolRuns.delete(runKey);
+  maybePostLangSmithRun(childRun, { postImmediately, finalized: true });
+}
+
+function handleLangSmithGenericEvent({
+  runTree,
+  normalizedTags,
+  source,
+  postImmediately,
+  eventType,
+  attributes,
+  record,
+}) {
+  const childRun = createLangSmithChildRun(runTree, {
+    name: eventType,
+    runType: "chain",
+    inputs: { event_type: eventType, attributes },
+    tags: [...normalizedTags, "agent-did", "event"],
+    source,
+    eventType,
+  });
+
+  childRun.addEvent(toLangSmithEvent(record));
+  void childRun.end({ event_type: eventType, attributes });
+  maybePostLangSmithRun(childRun, { postImmediately, finalized: true });
+}
+
+const postedRuns = new WeakSet();
+
+function maybePostLangSmithRun(runTree, { postImmediately, finalized }) {
+  if (!postImmediately) {
+    return;
+  }
+
+  void Promise.resolve().then(async () => {
+    try {
+      if (!postedRuns.has(runTree) && typeof runTree.postRun === "function") {
+        postedRuns.add(runTree);
+        await runTree.postRun();
+      }
+
+      if (finalized && typeof runTree.patchRun === "function") {
+        await runTree.patchRun();
+      }
+    } catch {
+      // no-op defensive boundary
+    }
+  });
+}
+
+module.exports = {
+  REDACTED_VALUE,
+  composeEventHandlers,
+  createAgentDidObserver,
+  createJsonLoggerEventHandler,
+  createLangSmithEventHandler,
+  createLangSmithRunTree,
+  sanitizeObservabilityAttributes,
+  serializeObservabilityEvent,
+};