@cuylabs/agent-a365-tooling 3.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# @cuylabs/agent-a365-tooling
+
+Microsoft Agent 365 tooling adapter for `@cuylabs/agent-core`.
+
+This package exposes one turn-scoped tool provider factory. On each chat turn,
+it uses Microsoft's Agent 365 tooling SDK to discover MCP servers for the active
+Microsoft 365 turn, connects those servers through agent-core's MCP manager,
+and returns MCP tools for that turn only.
+
+Use this when your agent is hosted behind Microsoft 365 / Agent 365 and should
+use the MCP tool servers configured for the current tenant, user, and agent
+identity. Do not use it for static MCP servers known at startup; use
+`agent-core` MCP config for those.
+
+## What It Gives You
+
+- Agent 365 MCP server discovery per Microsoft 365 turn.
+- Microsoft SDK token exchange and per-server bearer headers.
+- Agent 365 platform headers for real Microsoft-hosted MCP servers.
+- Turn-scoped MCP tools that are cleaned up after the turn.
+- A Microsoft-specific adapter without importing Microsoft SDK types into
+  `agent-core`.
+
+## Install
+
+```bash
+pnpm add @cuylabs/agent-a365-tooling @microsoft/agents-a365-tooling
+```
+
+If you use the default ambient TurnContext lookup, also use
+`@cuylabs/agent-channel-m365` and configure `@microsoft/agents-hosting` in the
+host app.
+
+## Usage
+
+```ts
+import { createAgent } from "@cuylabs/agent-core";
+import { createA365ToolingTurnToolProvider } from "@cuylabs/agent-a365-tooling";
+
+const agent = createAgent({
+  model,
+  turnToolProviders: [
+    createA365ToolingTurnToolProvider({
+      authorization,
+      authHandlerName: "agentic",
+      toolOptions: {
+        orchestratorName: "dory",
+      },
+    }),
+  ],
+});
+```
+
+By default the provider reads the active `TurnContext` from
+`currentM365TurnContext()` in `@cuylabs/agent-channel-m365`. For tests or custom
+hosts, pass `getTurnContext`.
+
+```ts
+createA365ToolingTurnToolProvider({
+  authorization,
+  authHandlerName: "agentic",
+  getTurnContext: () => myTurnContext,
+});
+```
+
+## Concept Docs
+
+The package docs are split by concern:
+
+| Doc | What it explains |
+| --- | --- |
+| [docs/architecture.md](./docs/architecture.md) | The four-layer split between agent-core, M365 channel ingress, Microsoft's A365 tooling SDK, and this adapter. |
+| [docs/agent-core-mcp.md](./docs/agent-core-mcp.md) | How this package uses agent-core `turnToolProviders` and how that differs from static agent-core MCP config. |
+| [docs/microsoft-a365-tooling.md](./docs/microsoft-a365-tooling.md) | What Microsoft's Agent 365 tooling SDK owns: discovery, dev manifest mode, gateway calls, and auth headers. |
+| [docs/lifecycle-and-limits.md](./docs/lifecycle-and-limits.md) | Per-turn lifecycle, cleanup, latency, filtering, connector replacement, and v0 limits. |
+
+Start with [docs/README.md](./docs/README.md) if you want the reading order.
+
+## Required Host Inputs
+
+| Option | Meaning | Typical source |
+| --- | --- | --- |
+| `authorization` | Microsoft Agents SDK `Authorization` object used for token exchange | Your M365 host application / `@microsoft/agents-hosting` setup |
+| `authHandlerName` | Name of the auth handler configured for Agent 365 token exchange | Your Microsoft Agents SDK app configuration |
+| `getTurnContext` | Optional resolver for the active Microsoft `TurnContext` | Defaults to `@cuylabs/agent-channel-m365` ambient context |
+| `authToken` | Optional pre-resolved gateway token | Local development or specialized hosts; normally omitted in production |
+| `toolOptions` | Optional metadata such as `orchestratorName` | Host/application configuration |
+
+In production, prefer omitting `authToken` so Microsoft's SDK performs token
+exchange for the active turn. In local dev-manifest mode, examples can pass a
+fake decoded token because the SDK reads `ToolingManifest.json` instead of
+calling the cloud gateway.
+
+## What This Does Not Do
+
+This package is not a channel, not an LLM provider, and not a replacement for
+agent-core's MCP engine. It does not implement cross-turn MCP pooling,
+mid-turn token refresh, or Agent 365 real-time threat protection chat-history
+submission in v0.
+
+## Examples
+
+Runnable examples live in the repository under
+[`packages/agent-a365-tooling/examples`](https://github.com/cuylabs-ai/agents-ts/tree/main/packages/agent-a365-tooling/examples).
+They are intentionally not included in the npm tarball because the example
+`tsconfig.json` and `ToolingManifest.json` are monorepo-local development
+harness files.
+
+Start with `examples/01-dev-manifest.ts`; it uses Microsoft's local
+`ToolingManifest.json` path and an in-process MCP fixture, so it verifies the
+provider without Azure.

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import { AgentTurnToolContext, Logger, AgentTurnToolProviderResult, MCPServerStatus, AgentTurnToolProvider, MCPConfig } from '@cuylabs/agent-core';
+
+type MaybePromise<T> = T | Promise<T>;
+type TurnMcpTools = NonNullable<AgentTurnToolProviderResult["mcpTools"]>;
+type A365ToolingUtility = {
+    GetToolRequestHeaders?: (authToken?: string, turnContext?: A365TurnContextLike, options?: A365ToolingToolOptions) => Record<string, string>;
+};
+type A365TurnContextLike = {
+    activity?: unknown;
+    [key: string]: unknown;
+};
+type A365AuthorizationLike = object;
+interface A365McpServerConfig {
+    mcpServerName: string;
+    url: string;
+    headers?: Record<string, string>;
+    audience?: string;
+    scope?: string;
+    publisher?: string;
+}
+interface A365ToolingToolOptions {
+    orchestratorName?: string;
+    [key: string]: unknown;
+}
+interface A365ToolingProviderContext {
+    agentContext: AgentTurnToolContext;
+    turnContext: A365TurnContextLike;
+}
+interface A365ToolingConnectorContext extends A365ToolingProviderContext {
+    providerName: string;
+    serverTimeoutMs: number;
+    logger?: Logger;
+}
+interface A365ToolingMcpConnection {
+    mcpTools: TurnMcpTools;
+    cleanup?: () => void | Promise<void>;
+    statuses?: Map<string, MCPServerStatus>;
+}
+type A365ToolingMcpConnector = (servers: A365McpServerConfig[], context: A365ToolingConnectorContext) => Promise<A365ToolingMcpConnection>;
+type A365ToolingServerFilter = (servers: A365McpServerConfig[], context: A365ToolingProviderContext) => MaybePromise<A365McpServerConfig[]>;
+type A365ToolingValueResolver<T> = (context: A365ToolingProviderContext) => MaybePromise<T>;
+interface A365ToolingModule {
+    Utility?: A365ToolingUtility;
+    McpToolServerConfigurationService: new (configurationProvider?: unknown) => {
+        listToolServers(turnContext: A365TurnContextLike, authorization: A365AuthorizationLike, authHandlerName: string, authToken?: string, options?: A365ToolingToolOptions): Promise<A365McpServerConfig[]>;
+    };
+}
+interface CreateA365ToolingTurnToolProviderOptions {
+    /**
+     * Provider name used in duplicate-tool errors and logs.
+     *
+     * @default "a365-tooling"
+     */
+    name?: string;
+    /**
+     * Microsoft Agent 365 Authorization object, or a resolver for request-scoped
+     * Authorization. The concrete object comes from `@microsoft/agents-hosting`.
+     */
+    authorization: A365AuthorizationLike | A365ToolingValueResolver<A365AuthorizationLike>;
+    /**
+     * Auth handler name configured in the Microsoft Agents SDK application.
+     */
+    authHandlerName: string;
+    /**
+     * Optional bearer token for the A365 tooling gateway. Omit this in normal
+     * production use so Microsoft's SDK performs token exchange from the
+     * Authorization object and active TurnContext.
+     */
+    authToken?: string | A365ToolingValueResolver<string | undefined>;
+    /**
+     * Optional A365 tooling request options, such as `orchestratorName`.
+     */
+    toolOptions?: A365ToolingToolOptions | A365ToolingValueResolver<A365ToolingToolOptions | undefined>;
+    /**
+     * Gets the active Microsoft TurnContext.
+     *
+     * Defaults to reading `currentM365TurnContext()?.turnContext` from
+     * `@cuylabs/agent-channel-m365`. Pass this in tests or in hosts that bind
+     * TurnContext differently. Custom hosts should return a real Microsoft
+     * TurnContext or a compatible object with the activity fields required by
+     * Microsoft's A365 tooling SDK, including conversation and agent identity
+     * metadata.
+     */
+    getTurnContext?: () => MaybePromise<A365TurnContextLike | undefined>;
+    /**
+     * Optional Microsoft A365 tooling configuration provider.
+     */
+    configurationProvider?: unknown;
+    /**
+     * Optional server filter/gate before MCP connection.
+     *
+     * The input array is freshly resolved for the active turn. Returning a new
+     * array is recommended when filtering or reordering.
+     */
+    filterServers?: A365ToolingServerFilter;
+    /**
+     * Advanced connector override. The default connector creates one
+     * agent-core MCPManager per turn and closes it during turn cleanup.
+     */
+    connectMcpServers?: A365ToolingMcpConnector;
+    /**
+     * Test seam for loading `@microsoft/agents-a365-tooling`.
+     */
+    getToolingModule?: () => Promise<A365ToolingModule>;
+    /**
+     * Per-server MCP connect/list timeout.
+     *
+     * @default 5000
+     */
+    serverTimeoutMs?: number;
+    /**
+     * Reserved for future pooling modes. v0 supports per-turn connections only.
+     *
+     * @default "per-turn"
+     */
+    mode?: "per-turn";
+    logger?: Logger;
+}
+interface ToAgentCoreMcpConfigOptions {
+    timeoutMs?: number;
+}
+declare class A365ToolingTurnContextError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class A365ToolingModuleLoadError extends Error {
+    constructor(packageName: string, cause: unknown);
+}
+declare function createA365ToolingTurnToolProvider(options: CreateA365ToolingTurnToolProviderOptions): AgentTurnToolProvider;
+declare function connectA365McpServers(servers: A365McpServerConfig[], context: A365ToolingConnectorContext): Promise<A365ToolingMcpConnection>;
+declare function toAgentCoreMcpConfig(servers: A365McpServerConfig[], options?: ToAgentCoreMcpConfigOptions): MCPConfig;
+
+export { type A365AuthorizationLike, type A365McpServerConfig, type A365ToolingConnectorContext, type A365ToolingMcpConnection, type A365ToolingMcpConnector, type A365ToolingModule, A365ToolingModuleLoadError, type A365ToolingProviderContext, type A365ToolingServerFilter, type A365ToolingToolOptions, A365ToolingTurnContextError, type A365ToolingValueResolver, type A365TurnContextLike, type CreateA365ToolingTurnToolProviderOptions, type ToAgentCoreMcpConfigOptions, connectA365McpServers, createA365ToolingTurnToolProvider, toAgentCoreMcpConfig };

package/dist/index.js

@@ -0,0 +1,266 @@
+// src/index.ts
+import {
+  createMCPManager
+} from "@cuylabs/agent-core";
+var A365_TOOLING_PACKAGE = "@microsoft/agents-a365-tooling";
+var M365_CHANNEL_PACKAGE = "@cuylabs/agent-channel-m365";
+var DEFAULT_PROVIDER_NAME = "a365-tooling";
+var DEFAULT_SERVER_TIMEOUT_MS = 5e3;
+var A365ToolingTurnContextError = class extends Error {
+  constructor(message = defaultMissingTurnContextMessage(), options) {
+    super(message, options);
+    this.name = "A365ToolingTurnContextError";
+  }
+};
+var A365ToolingModuleLoadError = class extends Error {
+  constructor(packageName, cause) {
+    super(
+      `Unable to load ${packageName}. Install it in the host application before using @cuylabs/agent-a365-tooling.`,
+      { cause }
+    );
+    this.name = "A365ToolingModuleLoadError";
+  }
+};
+function createA365ToolingTurnToolProvider(options) {
+  const providerName = normalizeProviderName(options.name);
+  const authHandlerName = normalizeRequiredString(
+    options.authHandlerName,
+    "authHandlerName"
+  );
+  const serverTimeoutMs = normalizeTimeout(options.serverTimeoutMs);
+  return {
+    name: providerName,
+    async resolveTools(agentContext) {
+      const turnContext = await resolveTurnContext(options.getTurnContext);
+      const providerContext = {
+        agentContext,
+        turnContext
+      };
+      const module = await loadToolingModule(options.getToolingModule);
+      const authorization = await resolveValue(
+        options.authorization,
+        providerContext
+      );
+      const authToken = await resolveOptionalValue(
+        options.authToken,
+        providerContext
+      );
+      const toolOptions = await resolveOptionalValue(
+        options.toolOptions,
+        providerContext
+      );
+      const service = new module.McpToolServerConfigurationService(
+        options.configurationProvider
+      );
+      let servers = await service.listToolServers(
+        turnContext,
+        authorization,
+        authHandlerName,
+        authToken,
+        toolOptions
+      );
+      if (options.filterServers) {
+        servers = await options.filterServers(servers, providerContext);
+      }
+      servers = attachBaseMcpHeaders(
+        servers,
+        module,
+        turnContext,
+        authToken,
+        toolOptions
+      );
+      if (servers.length === 0) {
+        options.logger?.info("A365 tooling resolved no MCP servers", {
+          provider: providerName,
+          sessionId: agentContext.sessionId,
+          turnId: agentContext.turnId
+        });
+        return { mcpTools: {} };
+      }
+      const connector = options.connectMcpServers ?? connectA365McpServers;
+      const connection = await connector(servers, {
+        ...providerContext,
+        providerName,
+        serverTimeoutMs,
+        ...options.logger ? { logger: options.logger } : {}
+      });
+      logConnectionStatuses(options.logger, providerName, connection.statuses);
+      return {
+        mcpTools: connection.mcpTools,
+        ...connection.cleanup ? { cleanup: connection.cleanup } : {}
+      };
+    }
+  };
+}
+async function connectA365McpServers(servers, context) {
+  const manager = createMCPManager(
+    toAgentCoreMcpConfig(servers, { timeoutMs: context.serverTimeoutMs })
+  );
+  try {
+    const statuses = await manager.connect();
+    const mcpTools = await manager.getTools();
+    return {
+      mcpTools,
+      statuses,
+      cleanup: () => manager.close()
+    };
+  } catch (error) {
+    try {
+      await manager.close();
+    } catch (closeError) {
+      context.logger?.warn(
+        "A365 tooling MCP cleanup after connect failure failed",
+        {
+          provider: context.providerName,
+          error: closeError instanceof Error ? closeError : new Error(String(closeError))
+        }
+      );
+    }
+    throw error;
+  }
+}
+function toAgentCoreMcpConfig(servers, options = {}) {
+  const timeout = normalizeTimeout(options.timeoutMs);
+  const config = {};
+  for (const server of servers) {
+    const name = normalizeRequiredString(server.mcpServerName, "mcpServerName");
+    const url = normalizeRequiredString(server.url, `url for ${name}`);
+    if (config[name]) {
+      throw new Error(`Duplicate A365 MCP server name "${name}"`);
+    }
+    config[name] = {
+      transport: "http",
+      name,
+      url,
+      timeout,
+      ...server.headers ? { headers: { ...server.headers } } : {}
+    };
+  }
+  return config;
+}
+function attachBaseMcpHeaders(servers, module, turnContext, authToken, toolOptions) {
+  const getToolRequestHeaders = module.Utility?.GetToolRequestHeaders;
+  if (!getToolRequestHeaders) {
+    return servers;
+  }
+  return servers.map((server) => {
+    const baseHeaders = getToolRequestHeaders(
+      // listToolServers already attaches per-server bearer tokens. Reuse one
+      // for header derivation when the host did not provide a gateway token.
+      authToken ?? extractBearerToken(server.headers),
+      turnContext,
+      toolOptions
+    );
+    if (Object.keys(baseHeaders).length === 0) {
+      return server;
+    }
+    return {
+      ...server,
+      // Match Microsoft's framework extensions: base platform headers first,
+      // then server-specific headers so per-server Authorization wins.
+      headers: { ...baseHeaders, ...server.headers }
+    };
+  });
+}
+function extractBearerToken(headers) {
+  if (!headers) {
+    return void 0;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== "authorization") {
+      continue;
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return match?.[1];
+  }
+  return void 0;
+}
+async function resolveTurnContext(getTurnContext) {
+  const turnContext = getTurnContext ? await getTurnContext() : await getDefaultM365TurnContext();
+  if (!turnContext) {
+    throw new A365ToolingTurnContextError();
+  }
+  return turnContext;
+}
+async function getDefaultM365TurnContext() {
+  let module;
+  try {
+    module = await import(M365_CHANNEL_PACKAGE);
+  } catch (error) {
+    if (isMissingModuleError(error, M365_CHANNEL_PACKAGE)) {
+      throw new A365ToolingTurnContextError(
+        defaultMissingChannelPackageMessage(),
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+  return module.currentM365TurnContext?.()?.turnContext;
+}
+async function loadToolingModule(getToolingModule) {
+  try {
+    return getToolingModule ? await getToolingModule() : await import(A365_TOOLING_PACKAGE);
+  } catch (error) {
+    throw new A365ToolingModuleLoadError(A365_TOOLING_PACKAGE, error);
+  }
+}
+async function resolveValue(value, context) {
+  return typeof value === "function" ? value(context) : value;
+}
+async function resolveOptionalValue(value, context) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return typeof value === "function" ? value(context) : value;
+}
+function normalizeProviderName(name) {
+  return normalizeRequiredString(name ?? DEFAULT_PROVIDER_NAME, "name");
+}
+function normalizeTimeout(timeoutMs) {
+  const timeout = timeoutMs ?? DEFAULT_SERVER_TIMEOUT_MS;
+  if (!Number.isFinite(timeout) || timeout <= 0) {
+    throw new Error("serverTimeoutMs must be a positive finite number");
+  }
+  return timeout;
+}
+function normalizeRequiredString(value, name) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return trimmed;
+}
+function logConnectionStatuses(logger, providerName, statuses) {
+  if (!logger || !statuses) {
+    return;
+  }
+  for (const [serverName, status] of statuses) {
+    if (status.status === "error") {
+      logger.warn("A365 tooling MCP server failed to connect", {
+        provider: providerName,
+        serverName,
+        error: status.error
+      });
+    }
+  }
+}
+function defaultMissingTurnContextMessage() {
+  return "createA365ToolingTurnToolProvider: no ambient TurnContext. This provider must run inside an @cuylabs/agent-channel-m365 turn. For tests or custom hosts, pass options.getTurnContext.";
+}
+function defaultMissingChannelPackageMessage() {
+  return "createA365ToolingTurnToolProvider: @cuylabs/agent-channel-m365 is not installed. Install @cuylabs/agent-channel-m365 or pass options.getTurnContext.";
+}
+function isMissingModuleError(error, packageName) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const code = error.code;
+  return code === "ERR_MODULE_NOT_FOUND" && error.message.includes(packageName);
+}
+export {
+  A365ToolingModuleLoadError,
+  A365ToolingTurnContextError,
+  connectA365McpServers,
+  createA365ToolingTurnToolProvider,
+  toAgentCoreMcpConfig
+};

package/docs/README.md

@@ -0,0 +1,28 @@
+# Agent 365 Tooling Docs
+
+`@cuylabs/agent-a365-tooling` connects Microsoft Agent 365 tooling discovery to
+agent-core's turn-scoped tool system.
+
+Read these files in this order:
+
+1. [architecture.md](./architecture.md)
+   Explains the four-layer design and where this package fits.
+2. [agent-core-mcp.md](./agent-core-mcp.md)
+   Explains what agent-core exposes, what this package uses, and how this
+   differs from normal static MCP configuration.
+3. [microsoft-a365-tooling.md](./microsoft-a365-tooling.md)
+   Explains what Microsoft's Agent 365 tooling SDK does and which host inputs
+   it needs.
+4. [lifecycle-and-limits.md](./lifecycle-and-limits.md)
+   Explains per-turn lifecycle, cleanup, latency, filtering, and v0 limits.
+
+The short version:
+
+- agent-core owns the platform-neutral runtime, model loop, tool execution, and
+  MCP client manager.
+- `agent-channel-m365` owns M365 Activity ingress and ambient `TurnContext`
+  binding.
+- Microsoft's Agent 365 tooling SDK owns A365 MCP server discovery and token
+  attachment.
+- this package turns those discovered A365 MCP servers into agent-core
+  turn-scoped MCP tools.

package/docs/agent-core-mcp.md

@@ -0,0 +1,117 @@
+# Agent-Core MCP Integration
+
+This package builds on two agent-core concepts:
+
+- `turnToolProviders`
+- `createMCPManager()`
+
+It does not replace agent-core MCP. It uses agent-core MCP at turn time.
+
+## Turn Tool Providers
+
+agent-core exposes `turnToolProviders` on `createAgent()`:
+
+```ts
+const agent = createAgent({
+  model,
+  turnToolProviders: [provider],
+});
+```
+
+A provider is called at the start of each user turn with an
+`AgentTurnToolContext`:
+
+```ts
+{
+  sessionId,
+  turnId,
+  message,
+  cwd,
+  abort,
+}
+```
+
+The provider can return:
+
+- `tools`: AI SDK-compatible tools for the current turn.
+- `mcpTools`: MCP-backed AI SDK tools for the current turn.
+- `cleanup`: a callback agent-core runs after the turn completes or fails.
+
+Those tools are merged into the model loop for only the active turn. They are
+not persisted on the agent and are not visible to other sessions or future
+turns.
+
+## How This Package Uses Turn Tools
+
+`createA365ToolingTurnToolProvider()` returns an agent-core
+`AgentTurnToolProvider`.
+
+On each turn it:
+
+1. reads the active M365 `TurnContext`;
+2. asks Microsoft's Agent 365 tooling SDK for MCP server configs;
+3. merges Microsoft base platform headers with each returned server's headers;
+4. maps those configs into agent-core MCP config;
+5. calls `createMCPManager()`;
+6. returns the MCP tools from `manager.getTools()`;
+7. returns `cleanup: () => manager.close()`.
+
+## Static MCP Config vs A365 Turn Tools
+
+agent-core already supports static MCP configuration. Use static MCP when the
+server list is known when the agent is created:
+
+```ts
+const manager = createMCPManager({
+  search: {
+    transport: "http",
+    url: "https://example.com/mcp",
+  },
+});
+```
+
+Agent 365 tooling is different. The server list is resolved from the current
+Microsoft turn and may depend on:
+
+- tenant;
+- user;
+- agent identity;
+- A365 gateway configuration;
+- auth handler and token exchange state.
+
+That makes it turn-scoped, not static.
+
+Put another way: `agent-core/mcp` is the engine that connects and executes MCP
+tools. It does not discover Agent 365 servers or perform Microsoft token
+exchange. Microsoft's `@microsoft/agents-a365-tooling` package does that
+platform-specific discovery/auth work, and this package adapts its output into
+agent-core's MCP engine.
+
+## Tool Names
+
+agent-core namespaces MCP tools by server name:
+
+```txt
+<serverName>__<toolName>
+```
+
+For example:
+
+```txt
+mail__search_messages
+calendar__create_event
+```
+
+The server name comes from Microsoft's `mcpServerName` field.
+The prefixing happens inside agent-core's MCP manager. This package only passes
+the Microsoft server name through as the MCP server `name`.
+
+## Cleanup Semantics
+
+agent-core runs turn-tool cleanup after `onChatEnd` middleware.
+
+For the default connector, cleanup closes the per-turn MCP manager. That closes
+the MCP clients opened for this turn.
+
+Cleanup is best-effort across providers. agent-core attempts all cleanup
+callbacks and logs cleanup errors instead of hiding the original turn result.

package/docs/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+This package exists to keep agent-core platform-neutral while still allowing an
+M365-hosted agent to receive Microsoft Agent 365 tools for the current turn.
+
+## Layer Split
+
+| Layer | Owns | Does not own |
+| --- | --- | --- |
+| `@cuylabs/agent-core` | Agent runtime, model loop, tool execution, MCP client lifecycle, `turnToolProviders` | Microsoft channel objects, Azure auth, Agent 365 discovery |
+| `@cuylabs/agent-channel-m365` | M365 Activity/CloudAdapter ingress and ambient `TurnContext` binding | Agent 365 MCP discovery or MCP client connection |
+| `@microsoft/agents-a365-tooling` | Agent 365 tooling discovery, `ToolingManifest.json` dev mode, gateway calls, token exchange, per-server auth headers | agent-core tool registration or model-loop lifecycle |
+| `@cuylabs/agent-a365-tooling` | Glue that resolves Agent 365 MCP servers for the current turn and exposes them as agent-core turn-scoped MCP tools | Chat transport, model provider, long-lived pooling, token refresh |
+
+The important boundary is that agent-core never imports Microsoft hosting
+types. Microsoft-specific request state stays in the channel and adapter
+packages.
+
+## Turn Flow
+
+At runtime, one user message flows like this:
+
+1. M365 channel receives an Activity.
+2. `@cuylabs/agent-channel-m365` binds the active Microsoft `TurnContext` in
+   AsyncLocalStorage.
+3. The host calls `agent.chat()` through the M365 adapter.
+4. agent-core starts the chat turn.
+5. agent-core calls this package's `AgentTurnToolProvider`.
+6. This package reads the active `TurnContext`.
+7. This package calls Microsoft's `McpToolServerConfigurationService`.
+8. Microsoft's SDK resolves Agent 365 MCP server configs from either:
+   `ToolingManifest.json` in development, or the Agent 365 tooling gateway in
+   production.
+9. This package optionally applies `filterServers`.
+10. This package connects the MCP servers through agent-core's MCP manager.
+11. agent-core exposes the resulting MCP tools to the model for this turn.
+12. After the turn, agent-core runs cleanup and closes the per-turn MCP
+    manager.
+
+## Why Not Put This In Agent-Core?
+
+Agent 365 tooling has Microsoft-specific inputs:
+
+- Microsoft `TurnContext`
+- Microsoft Agents SDK `Authorization`
+- `authHandlerName`
+- OBO token exchange behavior
+- Agent 365 MCP server metadata
+
+Putting those concepts in agent-core would make core platform-specific. The
+adapter package keeps that boundary clean.
+
+## Why Not Create A Generic Tooling Discovery Package?
+
+This package intentionally does not extract a generic discovery abstraction
+yet. The A365 path is specific to Microsoft turn state and token exchange. A
+future Salesforce, Slack, or internal platform discovery adapter may need a
+different shape.
+
+The rule for now is simple: wait for a second real adapter before extracting a
+shared abstraction.

package/docs/lifecycle-and-limits.md

@@ -0,0 +1,112 @@
+# Lifecycle And Limits
+
+This package is intentionally small for v0. It resolves Agent 365 MCP tools once
+per turn and cleans them up when the turn ends.
+
+## Per-Turn Lifecycle
+
+For each user message:
+
+1. agent-core starts a turn.
+2. this provider resolves the active M365 `TurnContext`.
+3. Microsoft's SDK resolves MCP server configs.
+4. this provider optionally filters those server configs.
+5. the default connector creates an agent-core MCP manager.
+6. the MCP manager connects the servers and lists tools.
+7. those tools are exposed to the model for the current turn.
+8. cleanup closes the MCP manager after the turn.
+
+## Filtering
+
+Use `filterServers` to gate or subset discovered MCP servers before connection:
+
+```ts
+createA365ToolingTurnToolProvider({
+  authorization,
+  authHandlerName: "agentic",
+  filterServers: (servers) =>
+    servers.filter((server) => server.mcpServerName.startsWith("soc_")),
+});
+```
+
+The input array is newly resolved for the active turn. Returning a new array is
+recommended when filtering or reordering.
+
+## Connector Replacement
+
+Use `connectMcpServers` to replace the default per-turn MCP connector.
+
+That is the extension point for:
+
+- connection pooling;
+- custom token refresh;
+- custom logging;
+- custom partial-failure policy;
+- per-tenant or per-user MCP client reuse.
+
+The default connector does this:
+
+```txt
+A365 server configs -> agent-core MCP config -> createMCPManager() -> getTools()
+```
+
+and returns cleanup that closes the manager.
+
+## Latency
+
+One turn performs one A365 tooling discovery round and one MCP connect round.
+Expect overhead from:
+
+- gateway token exchange;
+- tooling gateway discovery;
+- per-audience token exchange;
+- MCP initialize/list handshakes.
+
+For several MCP servers this can be noticeable. v0 does not pool clients.
+
+## Token TTL
+
+Microsoft's SDK attaches bearer tokens to returned MCP server headers. The
+default connector snapshots those headers into MCP clients at connect time.
+
+Long-running turns may outlive bearer token TTL. v0 does not refresh MCP
+Authorization headers mid-turn.
+
+Future token refresh should live behind `connectMcpServers`, not in agent-core.
+
+## Cleanup
+
+The default cleanup calls `manager.close()`.
+
+There is no package-level close timeout in v0. If production deployments show
+tail-latency spikes during turn cleanup, add a future `closeTimeoutMs` option to
+the connector path.
+
+## Abort
+
+`AgentTurnToolContext.abort` is passed to providers, but agent-core's MCP
+manager does not currently accept an abort signal for connection setup.
+
+If a user aborts while MCP servers are connecting, v0 waits for the active MCP
+connect/list operation to finish or hit `serverTimeoutMs`.
+
+## Partial Failures
+
+agent-core's MCP manager tolerates partial server failures. If one server fails
+to connect, healthy servers can still provide tools.
+
+The default per-server timeout is 5000 ms so one flaky server does not add the
+default 30 second MCP timeout to every turn.
+
+## Not In V0
+
+v0 does not include:
+
+- cross-turn MCP client pooling;
+- mid-turn token refresh;
+- real-time threat protection chat-history submission;
+- generic platform-neutral MCP discovery abstraction;
+- dedicated cleanup timeout;
+- custom telemetry events for per-server partial failure.
+
+Those can be added later without changing agent-core's turn-tool contract.

package/docs/microsoft-a365-tooling.md

@@ -0,0 +1,180 @@
+# Microsoft Agent 365 Tooling SDK
+
+This package delegates Agent 365 discovery and token work to Microsoft's
+`@microsoft/agents-a365-tooling` SDK.
+
+## Why Microsoft Created It
+
+Microsoft's package is part of the Agent 365 SDK surface for agents that run in
+the Microsoft 365 / Agent 365 ecosystem.
+
+It exists because Agent 365 tooling is not just "connect to this MCP URL." It
+is a platform problem:
+
+- discover which MCP tool servers are configured for a specific Agent 365
+  agent identity;
+- support local development through `ToolingManifest.json`;
+- query the Agent 365 tooling gateway in production;
+- resolve the active agent identity from `TurnContext` and/or auth token
+  claims;
+- perform token exchange through the Microsoft Agents SDK `Authorization`
+  object and `authHandlerName`;
+- attach the correct per-server bearer token headers, including per-audience
+  tokens for newer server shapes;
+- add platform headers such as channel ID, subchannel ID, user agent, and
+  agent ID;
+- optionally send chat history to the MCP platform for real-time threat
+  protection.
+
+That is why Microsoft named the package "tooling" rather than "mcp-client".
+The MCP protocol client is only one piece. The package's main job is to bridge
+Agent 365 platform state to MCP server configuration.
+
+## What The Microsoft SDK Answers
+
+The SDK answers this question:
+
+> For this Microsoft 365 agent turn, which Agent 365 MCP servers should this
+> agent be able to use, and what headers are needed to call them?
+
+The output shape this adapter needs is:
+
+```ts
+{
+  mcpServerName: "mail",
+  url: "https://...",
+  headers: {
+    Authorization: "Bearer ..."
+  }
+}
+```
+
+That maps directly to agent-core's remote HTTP MCP config.
+
+## Production Mode
+
+In production, Microsoft's SDK can:
+
+- inspect the active `TurnContext`;
+- resolve the agent identity;
+- use the host `Authorization` object;
+- use the configured `authHandlerName`;
+- acquire tokens for Agent 365 tooling gateway calls;
+- query the Agent 365 tooling gateway;
+- attach per-audience bearer tokens to returned MCP server configs.
+
+The normal production path should omit `authToken`:
+
+```ts
+createA365ToolingTurnToolProvider({
+  authorization,
+  authHandlerName: "agentic",
+});
+```
+
+When `authToken` is omitted, Microsoft's SDK performs token exchange from the
+active turn and host authorization setup.
+
+The production discovery endpoint is shaped around the Agent 365 platform:
+
+```txt
+GET https://agent365.svc.cloud.microsoft/agents/v2/{agenticAppId}/mcpServers
+```
+
+The SDK also knows how to build direct MCP server URLs under the platform base
+URL when a manifest entry does not provide a custom `url`.
+
+When framework-specific Microsoft extensions connect MCP servers, they merge
+base platform headers from `Utility.GetToolRequestHeaders()` with each returned
+server's headers. This adapter follows the same shape before handing configs to
+agent-core MCP:
+
+```txt
+base platform headers -> server-specific headers
+```
+
+That order matters because per-server `Authorization` headers returned by the
+SDK should override any shared gateway token header.
+
+## Development Manifest Mode
+
+When `NODE_ENV=development`, Microsoft's SDK reads `ToolingManifest.json`
+instead of calling the cloud gateway.
+
+That is useful for local examples and tests because it exercises the same
+adapter path without requiring:
+
+- Azure deployment;
+- a live Agent 365 tenant;
+- real OBO token exchange;
+- a real Agent 365 gateway response.
+
+The local example uses a minimal decoded token because the SDK still decodes an
+agent identity, but it does not call the cloud gateway while using the manifest
+path.
+
+The manifest mode is the reason the examples can validate this adapter without
+Azure: Microsoft's SDK still returns the same `MCPServerConfig[]` shape, and
+this package still maps those configs into agent-core MCP.
+
+## Host Inputs
+
+| Option | Meaning | Typical source |
+| --- | --- | --- |
+| `authorization` | Microsoft Agents SDK `Authorization` object used for token exchange | M365 host application / `@microsoft/agents-hosting` setup |
+| `authHandlerName` | Name of the auth handler configured for Agent 365 token exchange | Microsoft Agents SDK app configuration |
+| `getTurnContext` | Optional resolver for the active Microsoft `TurnContext` | Defaults to `@cuylabs/agent-channel-m365` ambient context |
+| `authToken` | Optional pre-resolved gateway token | Local development or specialized hosts |
+| `toolOptions` | Optional metadata such as `orchestratorName` | Host/application configuration |
+
+## Ambient TurnContext
+
+By default, this package reads:
+
+```ts
+currentM365TurnContext()?.turnContext
+```
+
+from `@cuylabs/agent-channel-m365`.
+
+That means the provider must run inside an M365 channel turn unless the host
+passes `getTurnContext`.
+
+For tests or non-standard hosts:
+
+```ts
+createA365ToolingTurnToolProvider({
+  authorization,
+  authHandlerName: "agentic",
+  getTurnContext: () => myTurnContext,
+});
+```
+
+Custom hosts should return a real Microsoft `TurnContext` or a compatible
+object with the activity fields Microsoft's SDK needs, including conversation
+and agent identity metadata.
+
+## How This Differs From Agent-Core MCP
+
+agent-core MCP starts after a server config is already known:
+
+```ts
+{
+  transport: "http",
+  url: "https://...",
+  headers: { Authorization: "Bearer ..." },
+}
+```
+
+Microsoft's Agent 365 tooling SDK is what obtains that config for an Agent 365
+turn. It determines the `url`, `mcpServerName`, and `headers` from Microsoft
+platform state.
+
+So the layering is:
+
+```txt
+Microsoft Agent 365 platform
+  -> @microsoft/agents-a365-tooling discovers authorized MCP server configs
+  -> @cuylabs/agent-a365-tooling maps those configs to agent-core turn tools
+  -> agent-core/mcp connects and executes tools
+```

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@cuylabs/agent-a365-tooling",
+  "version": "3.0.0",
+  "description": "Microsoft Agent 365 tooling adapter for @cuylabs/agent-core turn-scoped MCP tools",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cuylabs/agent-core": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@microsoft/agents-a365-tooling": ">=0.2.0-preview.5 <1.0.0",
+    "@microsoft/agents-hosting": ">=1.4.0",
+    "@cuylabs/agent-channel-m365": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cuylabs/agent-channel-m365": {
+      "optional": true
+    },
+    "@microsoft/agents-hosting": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "4.0.0-beta.38",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/node": "^22.0.0",
+    "dotenv": "^17.2.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18",
+    "zod": "^3.25.76 || ^4.1.8",
+    "@cuylabs/agent-channel-m365": "^3.0.0"
+  },
+  "keywords": [
+    "agent",
+    "microsoft",
+    "agent365",
+    "a365",
+    "mcp",
+    "tooling"
+  ],
+  "author": "cuylabs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuylabs-ai/agents-ts.git",
+    "directory": "packages/agent-a365-tooling"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}