Use Agent365ExporterOptions for exporter and create AgenticTokenCache…

packages/agents-a365-observability-tokencache/README.md

@@ -0,0 +1,100 @@
+# @microsoft/agents-a365-observability-tokencache
+
+Observability token cache utilities for the Agent365 SDK. This package provides:
+
+- In‑memory storage for observability (telemetry/export) bearer tokens
+- Early refresh using an expiration skew (default 60s before real expiry)
+- Automatic fallback TTL if the token lacks an `exp` claim
+- Linear retry on transient failures (timeouts, 5xx, 408, 429) during token exchange
+- Per key (agent + tenant) serialization to avoid thundering herds
+
+## Installation
+
+```bash
+pnpm add @microsoft/agents-a365-observability-tokencache
+```
+
+## Core API
+
+```ts
+import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-tokencache';
+```
+
+## Using With Observability Builder (Telemetry Exporter)
+
+When configuring the observability manager, supply a token resolver. Do **not** pass the method reference directly (it would lose `this`); wrap it to preserve context or use `bind`:
+
+```ts
+import { Builder, ObservabilityManager, Agent365ExporterOptions } from '@microsoft/agents-a365-observability';
+import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-tokencache';
+
+export const a365Observability = ObservabilityManager.configure((builder: Builder) => {
+	const exporterOptions = new Agent365ExporterOptions();
+	exporterOptions.maxQueueSize = 10;
+
+	builder
+		.withService('TypeScript Sample Agent', '1.0.0')
+		.withClusterCategory('prod')
+		.withExporterOptions(exporterOptions)
+		// Wrap to ensure `this` binding (so internal map & methods work).
+		.withTokenResolver((agentId, tenantId) => AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId));
+});
+```
+
+Alternatively:
+
+```ts
+builder.withTokenResolver(AgenticTokenCacheInstance.getObservabilityToken.bind(AgenticTokenCacheInstance));
+```
+
+## Example: Preloading in an Agent Turn
+
+```ts
+import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-tokencache';
+import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';
+
+// Inside activity handler:
+await AgenticTokenCacheInstance.RefreshObservabilityToken(
+	agentInfo.agentId,
+	tenantInfo.tenantId,
+	context,
+	agentApplication.authorization,
+	getObservabilityAuthenticationScope()
+);
+// Token is now cached (non-blocking if acquisition fails; subsequent resolver will return null until success).
+```
+
+## Custom Token Resolver Example (Using Application-Level Cache)
+
+If you prefer to manage the token yourself and only use this cache for retrieval:
+
+```ts
+const tokenResolver = (agentId: string, tenantId: string): string | null => {
+	const t = AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId);
+	return t ?? null;
+};
+
+builder.withTokenResolver(tokenResolver);
+```
+
+## When to Refresh vs. When to Read
+
+- Use `RefreshObservabilityToken` when you have access to `TurnContext` and `Authorization` and want to ensure a fresh token is available.
+- Use `getObservabilityToken` inside exporters / resolvers where only agent & tenant IDs are available, and you can tolerate `null` (meaning skip authenticated export or wait until later).
+
+## Handling Expiration
+
+The cache considers a token expired if:
+1. It has an `exp` and current time >= `exp * 1000 - skewMs` (default skew 60s)
+2. Or it has no `exp` and current time >= `acquiredOn + maxTokenAgeMs` (default 1h)
+
+Expired tokens are not returned; they force a refresh on next `RefreshObservabilityToken` call.
+
+## Error & Retry Behavior
+
+- Transient errors (timeouts, network issues, 408, 429, 5xx) trigger up to 2 linear backoff retries (200ms, then 400ms).
+- Non-retriable errors clear the entry’s token & expiry; subsequent reads return `null` until a successful refresh.
+- All events are logged via lightweight console wrappers (info/warn/error).
+
+## License
+MIT

packages/agents-a365-observability-tokencache/jest.config.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testPathIgnorePatterns: ['/integration/'],
+  clearMocks: true,
+};

packages/agents-a365-observability-tokencache/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@microsoft/agents-a365-observability-tokencache",
+  "version": "0.0.0-placeholder",
+  "description": "Microsoft Agent 365 SDK observability token cache utilities",
+  "keywords": [
+    "agent365",
+    "observability",
+    "telemetry",
+    "token",
+    "cache"
+  ],
+  "homepage": "https://github.com/microsoft/Agent365-nodejs",
+  "bugs": {
+    "url": "https://github.com/microsoft/Agent365-nodejs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/Agent365-nodejs.git",
+    "directory": "packages/agents-a365-observability-tokencache"
+  },
+  "license": "MIT",
+  "author": "Microsoft",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "npx tsc --project tsconfig.cjs.json",
+    "build:esm": "npx tsc --project tsconfig.esm.json",
+    "build:watch": "npx tsc --watch",
+    "clean": "npx rimraf dist",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "test": "jest --config ./jest.config.cjs --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "pack": "npm pack --pack-destination=../"
+  },
+  "dependencies": {
+    "@microsoft/agents-hosting": "^1.1.0-alpha.85",
+    "@microsoft/agents-a365-runtime": "workspace:*",
+    "@microsoft/agents-a365-observability": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.7.0",
+    "rimraf": "^6.0.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

packages/agents-a365-observability-tokencache/src/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": ["eslint:recommended"],
+  "rules": {
+    "no-unused-vars": "off",
+    "@typescript-eslint/no-unused-vars": ["error", {
+      "argsIgnorePattern": "^_",
+      "varsIgnorePattern": "^_",
+      "caughtErrorsIgnorePattern": "^_"
+    }],
+    "@typescript-eslint/no-explicit-any": "error",
+    "prefer-const": "error",
+    "no-var": "error",
+    "no-console": "error",
+    "semi": ["error", "always"],
+    "quotes": ["error", "single"],
+    "indent": ["error", 4],
+    "no-trailing-spaces": "error"
+  },
+  "env": {
+    "node": true,
+    "es6": true,
+    "jest": true
+  },
+  "ignorePatterns": ["dist/**/*", "node_modules/**/*", "*.js"]
+}